endeBoth.h

/*
 * Licensed Materials - Property of HCL and/or IBM
 * Copyright HCL Technologies Ltd. 2016, 2023. All Rights Reserved.
 * Copyright IBM Corporation 1999, 2016. All Rights Reserved.
 *
 * U.S. Government Users Restricted Rights -  Use, duplication or 
 * disclosure restricted by GSA ADP Schedule.
 */
 
#ifndef __endeBoth_h__
#define __endeBoth_h__ included
 
#ifndef __RTConfig_h__
#include <RTConfig.h>
#endif
 
#ifdef __cplusplus
extern "C"
{
#endif
 
/*||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
||
||  Public:
||
+|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||*/
 
enum encodingResult          /* when encoding a message to send       */
{
    ENC_SUCCESS,             /* encoding OK                           */
    ENC_BAD_PARM,            /* bad parameter was detected            */
    ENC_BAD_FUNC_TYPE,       /* func value unknown                    */
    ENC_OVERFLOW,            /* buf was too small                     */
 
    ENC_LAST                 /* last-in-list flag, no real meaning    */
};
 
enum decodingResult          /* when decoding a received message      */
{
    DEC_SUCCESS,             /* decoding OK                           */
    DEC_BAD_PARM,            /* bad parameter was detected            */
    DEC_UNDERRUN,            /* buf contains incomplete message       */
    DEC_NO_FUNC_ID,          /* FUNC_ identifier not found            */
    DEC_NO_FUNC_VAL,         /* FUNC_ value could not be found        */
    DEC_BAD_FUNC_TYPE,       /* FUNC_ value found but unknown         */
    DEC_NO_METHOD,           /* No decoding method for this func found*/
    DEC_NO_INT_ID,           /* INT identifier not found              */
    DEC_NO_INT_VAL,          /* INT value could not be read           */
    DEC_NO_STR_ID,           /* STR identifier not found              */
    DEC_NO_STR_LEN,          /* STR length field not found            */
    DEC_NO_STR_SPC,          /* STR no space between length and value */
 
    DEC_LAST                 /* last-in-list flag, no real meaning    */
};
 
enum resultCode              /* result of a target operation          */
{
    RES_OK,                  /* Alles ist Gut!                        */
    RES_BAD_FUNC,            /* The func was not recognized           */
    RES_BAD_MESSAGE,         /* The message could not be encoded      */
    RES_BAD_DAEMON,          /* The daemon given could not be found   */
    RES_BAD_ACTOR,           /* The actor given could not be found    */
    RES_BAD_PORT,            /* The port given could not be found     */
    RES_BAD_STATE,           /* The state given could not be found    */
    RES_BAD_CHAIN,           /* The chain given could not be found    */
    RES_BAD_VAR,             /* The variable given could not be found */
 
    RES_OTHER_ERROR,         /* An unspecified error occurred         */
 
    RES_LAST                 /* last-in-list flag, no real meaning    */
};
 
enum rtsStatusCode
{
    RTS_STATUS_INITIAL,      /* Initially, before started first time  */
    RTS_STATUS_RUNNING,      /* Target started by someone             */
    RTS_STATUS_STOPPED,      /* Target stopped manually by an observer*/
    RTS_STATUS_HALTED,       /* Target halted by a daemon with halt   */
 
    RTS_STATUS_LAST          /* last-in-list flag, no real meaning    */
};
 
enum funcType                /* Direction: Toolset <-> Application    */
{
    FUNC_NONE,               /* last-in-list flag, no real meaning    */
 
    RES_CODE,                /* <-- Result of the target operation    */
 
    EVT_TARGINFO,            /* <-- Target Information                */
    EVT_PRESENCE,            /* <-- Presence Event or Info            */
    EVT_REFERENCE,           /* <-- Reference Event or Info           */
    EVT_CHAIN,               /* <-- Chain Event or Info               */
    EVT_STATE,               /* <-- State Event or Info               */
    EVT_VARIABLE,            /* <-- Variable Event or Info            */
    EVT_MSG_OUT,             /* <-- Message Out Event or Info         */
    EVT_MSG_IN,              /* <-- Message In Event or Info          */
    EVT_MSG_OUTIN,           /* <-- Message Between Event or Info     */
    EVT_RTS_STATUS,          /* <-- RTS Status (Reset/Running/Stopped)*/
    EVT_HISTORY,             /* <-- State History Info                */
    EVT_MSG_QUEUE,           /* <-- Message from Event Queue          */
    EVT_CHILDREN,           /* <-- Actor parts and ports info         */
    
    CMD_REQ_INFO,            /* --> Request Target Information        */
    CMD_CLOSE_SESSION,       /* --> Close T.O. session                */
    CMD_CREATE_DAEMON,       /* --> Create a daemon                   */
    CMD_UPDATE_DAEMON,       /* --> Send new settings to a daemon     */
    CMD_COMMAND_DAEMON,      /* --> Send command to a daemon          */
    CMD_REFRESH_DAEMON,      /* --> Ask daemon to refresh             */
    CMD_DESTROY_DAEMON,      /* --> Destroy the daemon and all inside */
 
    CMD_ADD_ACTOR,           /* --> Add an actor to a daemon          */
    CMD_DEL_ACTOR,           /* --> Del an actor from a daemon        */
    CMD_ADD_PORT,            /* --> Add a port to a daemon            */
    CMD_DEL_PORT,            /* --> Del a port from a daemon          */
    CMD_ADD_STATE,           /* --> Add a state to a daemon           */
    CMD_DEL_STATE,           /* --> Del a state from a daemon         */
    CMD_ADD_CHAIN,           /* --> Add a chain to a daemon           */
    CMD_DEL_CHAIN,           /* --> Del a chain from a daemon         */
    CMD_ADD_VAR,             /* --> Add a variable to a daemon        */
    CMD_DEL_VAR,             /* --> Del a variable from a daemon      */
    CMD_START_VAR_MON,       /* --> Add a variable monitor            */
    CMD_STOP_VAR_MON,        /* --> Del a variable monitor            */
    CMD_SET_VAR,             /* --> Set a variable to a new value     */
    CMD_GET_VAR,             /* --> Get a variable's value            */
 
    CMD_INJECT_MSG,          /* --> Inject a message into all ports   */
 
    CMD_GET_MESSAGES,        /* --> Get message queue                 */
 
    CMD_SEND_TO_APP,         /* Handle command send from UI to TargetRTS */
 
    CMD_GET_CHILDREN,        /* Get Children of Capsule  */
 
    FUNC_LAST                /* last-in-list flag, no real meaning    */
};
 
typedef struct
{
    long sec;                /* seconds */
    long nsec;               /* nano-seconds */
} TO_timeStamp;
 
typedef struct
{
    int    number;
    char * invokeID;
} TO_daemonInfo;
 
/*||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
||
||  Daemon Set-up and maintenance ( TOOLSET -> TARGET ):
||
+|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||*/
 
typedef struct
{
    const char   * signal;   /* the signal                            */
    int            prio;     /* the priority                          */
    char         * data;     /* the data                              */
} TO_message;
 
typedef struct
{
    char         * settings; /* settings, like "type=FSM" or command  */
} TO_daemonSett;
 
typedef struct
{
    char         * actor;    /* actor "/A1:1/A2:0" or ref "/A1:1/A2"  */
    int            allRecurs; /* addActor ref: send presence setting  */
                 /* delActor: delete recursive setting    */
} TO_actorInfo;
 
typedef struct
{
    char         * actor;    /* actor, like "/sender:1/buf:0"         */
    char         * port;     /* port, like "commandPort:0"            */
} TO_portInfo;
 
typedef struct
{
    char         * actor;    /* actor, like "/sender:1/buf:0"         */
    char         * state;    /* state, like "running/wait4ack"        */
} TO_stateInfo;
 
typedef struct
{
    char         * actor;    /* actor, like "/sender:1/buf:0"         */
    char         * state;    /* path to the LEAVING state             */
    char         * chain;    /* the chain (transition name)           */
    int            position; /* pos withing chain: 1, 2, 3, or 0      */
} TO_chainInfo;
 
typedef struct
{
    char         * actor;    /* actor, like "/sender:1/buf:0"         */
    char         * variable; /* the variable name                     */
} TO_variableInfo;
 
typedef struct
{
    char         * variable; /* the variable name                     */
    char         * value;    /* the variable data                     */
} TO_variableData;
 
typedef struct
{
    char         * signal;   /* the signal                            */
    char         * data;     /* the data to inject                    */
    int            inwards;  /* 1 if inwards, 0 if outwards           */
    int            prio;     /* the priority                          */
} TO_injectMsg;
 
typedef struct
{
    char         * path;     /* actor path, or null for all actors    */
} TO_getMessages;
 
typedef struct
{
    char         * msgSendToApp;     /* e.g. rtLogAll and rtDelAll data    */
} TO_sendToAppInfo;
 
typedef struct
{
    char         * actor;    /* path to actor                         */
    char         * actorID;  /* actor's unique string                 */
    char         * classID;  /* actor's class name, or "" of nonexist */
} TO_getChildrenInfo;
 
/*||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
||
||  Daemon Events ( TOOLSET <- TARGET ):
||
+|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||*/
 
typedef struct
{
    int            code;     /* result code, see resultCode enum      */
} TO_resultCode;
 
typedef struct
{
    const char   * info;     /* target info, like "libset=sparc-gnu-2.8.1" */
} TO_evtTargetInfo;
 
typedef struct
{
    TO_timeStamp   time;     /* timestamp (0,0) if response           */
    char         * actor;    /* path to actor                         */
    char         * actorID;  /* actor's unique string                 */
    const char   * classID;  /* actor's class name, or "" of nonexist */
} TO_evtPresence;
 
typedef struct
{
    TO_timeStamp   time;     /* timestamp (0,0) if response           */
    char         * actorRef; /* path to actor reference               */
    int            incarns;  /* number of incarnations present        */
} TO_evtReference;
 
typedef struct
{
    TO_timeStamp   time;     /* timestamp (0,0) if response           */
    char         * actor;    /* path to actor                         */
    char         * state;    /* path to the LEAVING state             */
    char         * chain;    /* the chain (transition name)           */
} TO_evtChain;
 
typedef struct
{
    TO_timeStamp   time;     /* timestamp (0,0) if response           */
    char         * actor;    /* path to actor                         */
    char         * state;    /* path to the CURRENT state             */
} TO_evtState;
 
typedef struct
{
    TO_timeStamp   time;     /* timestamp (0,0) if response           */
    char         * actor;    /* path to actor                         */
    char         * variable;
    char         * value;
} TO_evtVariable;
 
 
typedef struct
{
    TO_timeStamp   time;     /* timestamp (0,0) if response           */
    char         * actor;    /* path to actor                         */
    char         * actorID;  /* actor's unique string                 */
    const char   * classID;  /* actor's class name, or "" of nonexist */
    char         * data;     /* the actor data  in json string        */
} TO_evtChildren;
 
typedef struct
{
    TO_timeStamp   sendTime;    /* timestamp sent                     */
    char         * sendActor;   /* sending actor path                 */
    char         * sendPort;    /* sending port                       */
    int            sendMethod;  /* 0:send; 1:invoke; 2:reply to invoke */
 
    TO_message     message;
} TO_evtMsgOut;
 
typedef struct
{
    TO_timeStamp   recTime;    /* timestamp received                  */
    char         * recActor;   /* receiving actor path                */
    char         * recPort;    /* receiving port                      */
 
    TO_message     message;
} TO_evtMsgIn;
 
typedef struct
{
    TO_timeStamp   sendTime;    /* timestamp sent                     */
    char         * sendActor;   /* sending actor path                 */
    char         * sendPort;    /* sending port                       */
    int            sendMethod;  /* 0:send; 1:invoke; 2:reply to invoke */
 
    TO_timeStamp   recTime;     /* timestamp received                 */
    char         * recActor;    /* receiving actor path               */
    char         * recPort;     /* receiving port                     */
 
    TO_message     message;
} TO_evtMsgOutIn;
 
typedef struct
{
    TO_timeStamp   time;     /* timestamp (0,0) if response           */
    int            status;   /* status code, see rtsStatusCode enum   */
    int            byYou;    /* 1 if event was caused by this observer */
} TO_evtRtsStatus;
 
typedef struct
{
    char         * actor;       /* path to actor                      */
    char         * state;       /* the requested state                */
    char         * history;     /* history of the requested state     */
    char         * current;     /* the current state                  */
} TO_evtHistory;
 
typedef struct
{
    char         * actor;
    char         * port;
    TO_message     message;
} TO_evtMsgQueue;
 
typedef struct
{
    int    size;       /* size of data[] in bytes                        */
    int    used;       /* encoded: how much used, decoded: where error   */
    int    status;     /* the encoding/decoding status code              */
    char * start;      /* beginning of the buffer; length is stored here */
    char * data;       /* the data buffer                                */
} TO_bufferInfo;
 
typedef struct
{
    int             func;   /* enum describing what struct             */
    void          * ptr;    /* pointer to the structure                */
    TO_daemonInfo   daemon; /* daemon information                      */
} TO_structInfo;
 
/*||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
||
||  Shared functions:
||
+|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||*/
 
/*----------------------------------------------------------------------------
|  Decode the buffer back to a decent structure.
+-----------------------------------------------------------------------------
|  If decoding was successful:
|    returns DEC_SUCCESS and sets buf->status to same as return value
|    sets buf->used to number of bytes decoded
|    sets info->func to the enum code describing *ptr
|    sets info->ptr to point to a suitable struct. This struct is malloc'ed
|        by TO_decodeBuffer. YOU are responsible for freeing it, and a good
|        help is to use TO_freeStructInfo().
|
|  If decoding was unsuccessful:
|    returns != DEC_SUCCESS (see enum decodingResult above for details),
|        and sets buf->status to same as return value
|    sets buf->used to _roughly_ where in buf->data something went wrong
|    sets info->func to FUNC_NONE
|    sets info->ptr to nullptr
|  No dynamic structures are allocated in this case.
+-----------------------------------------------------------------------------
|  Example:
|
|  TO_bufferInfo  buf;
|  TO_structInfo  info;
|
|  TO_evtPresence myPresence;
|
|  // YOU put decodeable data into buf.data and buf.size
|  // You don't need to set buf.used, buf.status or any info.* fields
|
|  TO_decodeBuffer( &buf, &info );
|  switch( buf.status )
|  {
|    case DEC_SUCCESS:
|      switch( info.func )
|      {
|        case EVT_PRESENCE: myPresence = *(TO_evtPresence *)info.ptr;
|          // Use the presence information in some way...
|          break;
|        case ...
|        default: // I can't handle this kind of function.
|      }
|      TO_freeStructInfo( &info );
|      break;
|    case DEC_BAD_PARM:
|      // One or both parameters to TO_decodeBuffer were null pointers.
|      break;
|    case DEC_NO_STR_LEN:
|      // No string length field at or around buf.data[ buf.used ].
|      break;
|    case ... // Other error codes here.
|  }
+---------------------------------------------------------------------------*/
int TO_decodeBuffer( TO_bufferInfo * buf, TO_structInfo * info );
 
/*----------------------------------------------------------------------------
|  Free whatever is in the info structure.
+-----------------------------------------------------------------------------
|  This routine assumes that the field info->func actually matches the
|  data type info->ptr points to. Manual fiddling here can be disastrous.
+---------------------------------------------------------------------------*/
void TO_freeStructInfo( TO_structInfo * info );
 
#ifdef __cplusplus
}
#endif
 
#endif // __endeBoth_h__