7. RAS-Server for EC-Lyser and EC-Engineer

7.1. Integration Requirements

To use the diagnosis tool EC-Lyser with a customer application, some modifications have to be done during integration of the EC-Master. The task is to integrate and start the Remote API Server system within the custom application, which provides a socket based uplink, which later on is connected by the EC-Lyser.

skinparam monochrome true
skinparam SequenceMessageAlign direction

node "EC-Lyser" {
[RAS-Client]
}
node "EC-Master application" {
[RAS-Server]
[EC-Master core]
}

[RAS-Client] - [RAS-Server]
[RAS-Server] - [EC-Master core]

An example on how to integrate the Remote API Server within the application is given with the example application EcMasterDemo, which in case is pre-configured to listen for EC-Lyser on TCP Port 6000 when command line parameter EcMasterDemo -sp is given.

To clarify the steps, which are needed within a custom application, a developer may use the following pseudo-code segment as a point of start. The Remote API Server library AtemRasSrv.lib (or respectively AtemRasSrv.a) must be linked.

7.2. Pseudo Code

#include "AtEmRasSrv.h"

/* custom Remote API Notification handler, example in EcMasterDemo (EcNotification.cpp) */
EC_T_DWORD RasNotifyCallback(
    EC_T_DWORD          dwCode,     /**< [in]   Notification code identifier */
    EC_T_NOTIFYPARMS*   pParms      /**< [in]   Notification data portion */
                    )
{
    /* custom notification handler */
}

     /* initialization  */
     ATEMRAS_T_SRVPARMS  oRemoteApiConfig = {0};
     EC_T_VOID           hRemApiHandle;
     oRemoteApiConfig.dwSignature          = ATEMRASSRV_SIGNATURE;
     oRemoteApiConfig.dwSize               = sizeof(ATEMRAS_T_SRVPARMS);
 /* INADDR_ANY */
     oRemoteApiConfig.oAddr.dwAddr         = 0;
 /*< default is port 6000 > */
     oRemoteApiConfig.wPort                = wServerPort;
 /*< default is 2 msec */
     oRemoteApiConfig.dwCycleTime          = ATEMRAS_CYCLE_TIME;
     oRemoteApiConfig.dwCommunicationTimeout = ATEMRAS_MAX_WATCHDOG_TIMEOUT;
     EC_CPUSET_ZERO(oRemoteApiConfig.oAcceptorThreadCpuAffinityMask);
     oRemoteApiConfig.dwAcceptorThreadPrio           = MAIN_THREAD_PRIO;
     oRemoteApiConfig.dwAcceptorThreadStackSize      = JOBS_THREAD_STACKSIZE;
     EC_CPUSET_ZERO(oRemoteApiConfig.oClientWorkerThreadCpuAffinityMask);
     oRemoteApiConfig.dwClientWorkerThreadPrio       = MAIN_THREAD_PRIO;
     oRemoteApiConfig.dwClientWorkerThreadStackSize  = JOBS_THREAD_STACKSIZE;
 /* RAS notification callback function */
     oRemoteApiConfig.pfnRasNotify     = RasNotifyCallback;
 /* RAS notification callback function context */
     oRemoteApiConfig.pvRasNotifyCtxt = pAppContext->pNotificationHandler;
 /* pre-allocation */
     oRemoteApiConfig.dwMaxQueuedNotificationCnt = 100;
 /* pre-allocation */
     oRemoteApiConfig.dwMaxParallelMbxTferCnt       = 50;
 /* span between to consecutive cyclic notifications of same type */
     oRemoteApiConfig.dwCycErrInterval              = 500;
 /* start remote API server */
     emRasSrvStart(&oRemoteApiConfig, &hRemApiHandle);

/* init master, configure master, setup application */
     emInitMaster(...);

7.3. Required API Calls

7.3.1. emRasSrvStart

EC_T_DWORD EC_NAMESPACE::emRasSrvStart(ATEMRAS_T_SRVPARMS *pParms, EC_T_PVOID *ppHandle)

Initializes and start remote API Server Instance.

Parameters

pParms – [in] Server start-up parameters
ppHandle – [out] Handle to opened instance, used for ctrl access

Returns

EC_E_NOERROR or error code

struct ATEMRAS_T_SRVPARMS

Public Members

EC_T_DWORD dwSignature: [in] Set to ATEMRASSRV_SIGNATURE

EC_T_DWORD dwSize: [in] Set to sizeof(ATEMRAS_T_SRVPARMS)

EC_T_LOG_PARMS LogParms: [in] Logging parameters

ATEMRAS_T_IPADDR oAddr: [in] Server Bind IP Address

EC_T_WORD wPort: [in] Server Bind IP Port

EC_T_WORD wMaxClientCnt: [in] Max. clients in parallel (0: unlimited)

EC_T_DWORD dwCycleTime: [in] Cycle Time of RAS Network access (acceptor, worker)

EC_T_DWORD dwCommunicationTimeout: [in] timeout before automatically closing connection

EC_T_CPUSET oAcceptorThreadCpuAffinityMask: [in] Acceptor Thread CPU affinity mask

EC_T_DWORD dwAcceptorThreadPrio: [in] Acceptor Thread Priority

EC_T_DWORD dwAcceptorThreadStackSize: [in] Acceptor Thread Stack Size

EC_T_CPUSET oClientWorkerThreadCpuAffinityMask: [in] Client Worker Thread CPU affinity mask

EC_T_DWORD dwClientWorkerThreadPrio: [in] Client Worker Thread Priority

EC_T_DWORD dwClientWorkerThreadStackSize: [in] Client Worker Thread Stack Size

EC_T_DWORD dwMaxQueuedNotificationCnt: [in] Amount of concurrently queue able Notifications

EC_T_DWORD dwMaxParallelMbxTferCnt: [in] Amount of concurrent active mailbox transfers

EC_PF_NOTIFY pfnRasNotify: [in] Function pointer called to notify error and status information generated by Remote API Layer

EC_T_VOID *pvRasNotifyCtxt: [in] Notification context returned while calling pfNotification

EC_T_DWORD dwCycErrInterval: [in] Interval which allows cyclic Notifications

7.3.2. emRasSrvStop

EC_T_DWORD EC_NAMESPACE::emRasSrvStop(EC_T_PVOID pvHandle, EC_T_DWORD dwTimeout)

Stop and de-initialize remote API Server Instance.

Parameters

pvHandle – [in] Handle to previously started Server
dwTimeout – [in] Timeout [ms] used to shut down all spawned threads, it’s multiplied internally by the amount of threads spawned.

Returns

EC_E_NOERROR or error code

7.3.3. emRasNotify - xxx

Callback function called by Remote API Server in case of state changes or error situations.

typedef EC_T_DWORD (*EC_PF_NOTIFY)(EC_T_DWORD dwCode, EC_T_NOTIFYPARMS *pParms)

7.3.4. emRasNotify - ATEMRAS_NOTIFY_CONNECTION

Notification about a change in the Remote API’s state.

emRasNotify - ATEMRAS_T_CONNOTIFYDESC

Parameter

pbyInBuf: [in] Pointer to data of type ATEMRAS_T_CONNOTIFYDESC
dwInBufSize: [in] Size of the input buffer in bytes
pbyOutBuf: [out] Should be set to EC_NULL
dwOutBufSize: [in] Should be set to 0
pdwNumOutData: [out] Should be set to EC_NULL

struct ATEMRAS_T_CONNOTIFYDESC

Public Members

EC_T_DWORD dwCause: [in] Cause of state connection state change

EC_T_DWORD dwCookie: [in] Unique identification cookie of connection instance.

7.3.5. emRasNotify - ATEMRAS_NOTIFY_REGISTER

Notification about a connected application registered a client to the master stack.

emRasNotify - ATEMRAS_NOTIFY_REGISTER

Parameter

pbyInBuf: [in] Pointer to data of type ATEMRAS_T_REGNOTIFYDESC
dwInBufSize: [in] Size of the input buffer in bytes
pbyOutBuf: [out] Should be set to EC_NULL
dwOutBufSize: [in] Should be set to 0
pdwNumOutData: [out] Should be set to EC_NULL

struct ATEMRAS_T_REGNOTIFYDESC

Public Members

EC_T_DWORD dwCookie: [in] Unique identification cookie of connection instance

EC_T_DWORD dwResult: [in] Result of registration request

EC_T_DWORD dwInstanceId: [in] Master Instance client registered to

EC_T_DWORD dwClientId: [in] Client ID of registered client

7.3.6. emRasNotify - ATEMRAS_NOTIFY_UNREGISTER

Notification about a connected application un-registered a client from the master stack.

emRasNotify - ATEMRAS_NOTIFY_UNREGISTER

Parameter

pbyInBuf: [in] Pointer to data of type ATEMRAS_T_REGNOTIFYDESC
dwInBufSize: [in] Size of the input buffer in bytes
pbyOutBuf: [out] Should be set to EC_NULL
dwOutBufSize: [in] Should be set to 0
pdwNumOutData: [out] Should be set to EC_NULL

7.3.7. emRasNotify - ATEMRAS_NOTIFY_MARSHALERROR

Notification about an error during marshalling in Remote API Server connection layer.

emRasNotify - ATEMRAS_NOTIFY_MARSHALERRORDESC

Parameter

pbyInBuf: [in] Pointer to data of type ATEMRAS_T_MARSHALERRORDESC
dwInBufSize: [in] Size of the input buffer in bytes
pbyOutBuf: [out] Should be set to EC_NULL
dwOutBufSize: [in] Should be set to 0
pdwNumOutData: [out] Should be set to EC_NULL

struct ATEMRAS_T_MARSHALERRORDESC

Public Members

EC_T_DWORD dwCookie: [in] Unique identification cookie of connection instance

EC_T_DWORD dwCause: [in] Cause of the command marshalling error

EC_T_DWORD dwLenStatCmd: [in] Length faulty command

EC_T_DWORD dwCommandCode: [in] Command code of faulty command

7.3.8. emRasNotify - ATEMRAS_NOTIFY_ACKERROR

Notification about an error during creation of ack / nack packet.

emRasNotify - ATEMRAS_NOTIFY_ACKERROR

Parameter

pbyInBuf: [in] Pointer to EC_T_DWORD containing error code
dwInBufSize: [in] Size of the input buffer in bytes
pbyOutBuf: [out] Should be set to EC_NULL
dwOutBufSize: [in] Should be set to 0
pdwNumOutData: [out] Should be set to EC_NULL

7.3.9. emRasNotify - ATEMRAS_NOTIFY_NONOTIFYMEMORY

Notification given, when no empty buffers for notifications are available in pre-allocated notification store. This points to a configuration error.

emRasNotify - ATEMRAS_NOTIFY_NONOTIFYMEMORY

Parameter

pbyInBuf: [in] Pointer to EC_T_DWORD containing unique identification cookie of connection instance
dwInBufSize: [in] Size of the input buffer in bytes
pbyOutBuf: [out] Should be set to EC_NULL
dwOutBufSize: [in] Should be set to 0
pdwNumOutData: [out] Should be set to EC_NULL

7.3.10. emRasNotify - ATEMRAS_NOTIFY_STDNOTIFYMEMORYSMALL

Notification given, when buffersize for standard notifications available in pre-allocated notification store are too small to carry a specific notification. This points to a configuration error.

emRasNotify - ATEMRAS_NOTIFY_STDNOTIFYMEMORYSMALL

Parameter

pbyInBuf: [in] Pointer to EC_T_DWORD containing unique identification cookie of connection instance
dwInBufSize: [in] Size of the input buffer in bytes
pbyOutBuf: [out] Should be set to EC_NULL
dwOutBufSize: [in] Should be set to 0
pdwNumOutData: [out] Should be set to EC_NULL

7.3.11. emRasNotify - ATEMRAS_NOTIFY_MBXNOTIFYMEMORYSMALL

Notification given, when buffersize for Mailbox notifications available in pre-allocated notification store are too small to carry a specific notification. This points to a configuration error. This is a serious error. If this error is given, Mailbox Transfer objects may have been become out of sync and therefore no more valid usable. Mailbox notifications should be dimensioned correctly see emRasSrvStart()

emRasNotify - ATEMRAS_NOTIFY_MBXNOTIFYMEMORYSMALL

Parameter

pbyInBuf: [in] Pointer to EC_T_DWORD containing unique identification cookie of connection instance
dwInBufSize: [in] Size of the input buffer in bytes
pbyOutBuf: [out] Should be set to EC_NULL
dwOutBufSize: [in] Should be set to 0
pdwNumOutData: [out] Should be set to EC_NULL