/*************************************************************************\
* Copyright (c) 2002 The University of Chicago, as Operator of Argonne
*     National Laboratory.
* Copyright (c) 2002 The Regents of the University of California, as
*     Operator of Los Alamos National Laboratory.
* SPDX-License-Identifier: EPICS
* EPICS BASE is distributed subject to a Software License Agreement found
* in file LICENSE that is included with this distribution.
\*************************************************************************/
/* dbNotify.h   */

#ifndef INCdbNotifyh
#define INCdbNotifyh

#include "dbCoreAPI.h"
#include "ellLib.h"

#ifdef __cplusplus
    extern "C" {
#endif

struct dbCommon;
struct processNotify;

typedef struct ellCheckNode{
    ELLNODE node;
    int     isOnList;
} ellCheckNode;

typedef enum {
    processRequest,
    putProcessRequest,
    processGetRequest,
    putProcessGetRequest
} notifyRequestType;

typedef enum {
    putDisabledType,
    putFieldType,
    putType
} notifyPutType;

typedef enum {
    getFieldType,
    getType     /* FIXME: Never used? */
} notifyGetType;

typedef enum {
    notifyOK,
    notifyCanceled,
    notifyError,
    notifyPutDisabled
} notifyStatus;

typedef struct processNotify {
    /* following fields are for private use by dbNotify implementation */
    ellCheckNode    restartNode;
    void            *pnotifyPvt;
    /* The following fields are set by dbNotify. */
    notifyStatus status;
    int              wasProcessed; /* (0,1) => (no,yes) */
    /*The following members are set by user*/
    notifyRequestType requestType;
    struct dbChannel *chan;         /*dbChannel*/
    int              (*putCallback)(struct processNotify *,notifyPutType type);
    void             (*getCallback)(struct processNotify *,notifyGetType type);
    void             (*doneCallback)(struct processNotify *);
    void             *usrPvt;        /*for private use of user*/
} processNotify;


/* dbProcessNotify and dbNotifyCancel are called by user*/
DBCORE_API void dbProcessNotify(processNotify *pprocessNotify);
DBCORE_API void dbNotifyCancel(processNotify *pprocessNotify);

/* dbProcessNotifyInit called by iocInit */
DBCORE_API void dbProcessNotifyInit(void);
DBCORE_API void dbProcessNotifyExit(void);

/*dbNotifyAdd called by dbScanPassive and dbScanLink*/
DBCORE_API void dbNotifyAdd(
    struct dbCommon *pfrom,struct dbCommon *pto);
/*dbNotifyCompletion called by recGblFwdLink  or dbAccess*/
DBCORE_API void dbNotifyCompletion(struct dbCommon *precord);

/* db_put_process defined here since it requires dbNotify.
 * src_type is the old DBR type
 * This is called by a dbNotify putCallback that uses oldDbr types
 */
DBCORE_API int db_put_process(
    processNotify *processNotify,notifyPutType type,
    int src_type,const void *psrc, int no_elements);

/* dbtpn is test routine for dbNotify putProcessRequest */
DBCORE_API long dbtpn(char *recordname,char *value);

/* dbNotifyDump is an INVASIVE debug utility. Don't use this needlessly*/
DBCORE_API int dbNotifyDump(void);

/* This module provides code to handle process notify.
 * client code semantics are:
 * 1) The client code allocates storage for a processNotify structure.
 *    This structure can be used for multiple calls to dbProcessNotify.
 *    The client is responsible for setting the following fields :
 *    requestType - The type of request.
 *    chan - This is typically set via a call to dbChannelCreate.
 *    putCallback - If requestType is putProcessRequest or putProcessGetRequest
 *    getCallback - If request is processGetRequest or putProcessGetRequest
 *    doneCallback - Must be set
 *    usrPvt - For exclusive use of client. dbNotify does not access this field
 * 2) The client calls dbProcessNotify.
 * 3) putCallback is called after dbNotify has claimed the record instance
 *    but before a potential process is requested.
 *    The putCallback MUST issue the correct put request
 *    specified by notifyPutType
 * 4) getCallback is called after a possible process is complete
 *    (including asynchronous completion) but before dbNotify has
 *    released the record.
 *    The getCallback MUST issue the correct get request
 *    specified by notifyGetType
 * 5) doneCallback is called when dbNotify has released the record.
 *    The client can issue a new dbProcessNotify request from
 *    doneCallback or anytime after doneCallback returns.
 * 6) The client can call dbNotifyCancel at any time.
 *    If a dbProcessNotify is active, dbNotifyCancel will not return until
 *    the dbNotifyRequest is actually canceled. The client must be prepared
 *    for a callback to be called while dbNotifyCancel is active.
 *
 * dbProcessNotify handles the semantics of record locking and deciding
 * if a process request is issued and also calls the client callbacks.
 *
 * A process request is issued if any of the following is true.
 * 1) The requester has issued a process request and record is passive.
 * 2) The requester is doing a put, the record is passive, and either
 *     a) The field description is process passive.
 *     b) The field is PROC.
 * 3) The requester has requested processGet and the record is passive.
 *
 * iocInit calls processNotifyInit.
 *
 * The other global routines (dbNotifyAdd and dbNotifyCompletion) are called by:
 *
 *  dbAccess.c
 *      dbScanPassive and dbScanLink
 *              call dbNotifyAdd just before calling dbProcess
 *      dbProcess
 *              Calls dbNotifyCompletion if dbProcess does not call process
 *              Unless pact is already true.
 *      recGbl
 *              recGblFwdLink calls dbNotifyCompletion
 *
 * Two fields in dbCommon are used for put notify.
 *      ppn     pointer to processNotify
 *              If a record is part of a put notify group,
 *              This field is the address of the associated processNotify.
 *              As soon as a record completes processing the field is set NULL
 *      ppnr    pointer to processNotifyRecord, which is a private structure
 *              owned by dbNotify.
 *              dbNotify is responsible for this structure.
 *
 */
#ifdef __cplusplus
}
#endif

#endif /*INCdbNotifyh*/