10. RAS-Server for EC-Inspector and EC-Engineer
10.1. Integration Requirements
To use the diagnosis tool EC-Inspector with a customer application, some modifications have to be done during integration of the EC-Monitor. 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-Inspector.
An example on how to integrate the Remote API Server within the application is given with the example application, which in case is pre-configured to listen for EC-Inspector on TCP Port 6000 when command line parameter “-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 “EcMonitorRasSrv.lib” (or respectively “EcMonitorRasSrv.a”) must be linked.
10.2. Application programming interface
10.2.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
-
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_DWORD dwAcceptorThreadPrio
[in] Acceptor Thread Priority
-
EC_T_DWORD dwAcceptorThreadStackSize
[in] Acceptor Thread Stack Size
-
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_DWORD dwCycErrInterval
[in] Interval which allows cyclic Notifications
-
EC_T_DWORD dwSignature
10.2.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
10.2.3. emRasNotify
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)
10.2.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_CONNOTIFYDESCdwInBufSize
: [in] Size of the input buffer in bytespbyOutBuf
: [out] Should be set to EC_NULLdwOutBufSize
: [in] Should be set to 0pdwNumOutData
: [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.
-
EC_T_DWORD dwCause
10.2.5. emRasNotify - ATEMRAS_NOTIFY_REGISTER
Notification about a connected application registered a client to the EC-Monitor.
- emRasNotify - ATEMRAS_NOTIFY_REGISTER
- Parameter
pbyInBuf
: [in] Pointer to data of type ATEMRAS_T_REGNOTIFYDESCdwInBufSize
: [in] Size of the input buffer in bytespbyOutBuf
: [out] Should be set to EC_NULLdwOutBufSize
: [in] Should be set to 0pdwNumOutData
: [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
-
EC_T_DWORD dwCookie
10.2.6. emRasNotify - ATEMRAS_NOTIFY_UNREGISTER
Notification about a connected application un-registered a client from the EC-Monitor.
- emRasNotify - ATEMRAS_NOTIFY_UNREGISTER
- Parameter
pbyInBuf
: [in] Pointer to data of type ATEMRAS_T_REGNOTIFYDESCdwInBufSize
: [in] Size of the input buffer in bytespbyOutBuf
: [out] Should be set to EC_NULLdwOutBufSize
: [in] Should be set to 0pdwNumOutData
: [out] Should be set to EC_NULL
See also
10.2.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_MARSHALERRORDESCdwInBufSize
: [in] Size of the input buffer in bytespbyOutBuf
: [out] Should be set to EC_NULLdwOutBufSize
: [in] Should be set to 0pdwNumOutData
: [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
-
EC_T_DWORD dwCookie
10.2.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 codedwInBufSize
: [in] Size of the input buffer in bytespbyOutBuf
: [out] Should be set to EC_NULLdwOutBufSize
: [in] Should be set to 0pdwNumOutData
: [out] Should be set to EC_NULL
10.2.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 instancedwInBufSize
: [in] Size of the input buffer in bytespbyOutBuf
: [out] Should be set to EC_NULLdwOutBufSize
: [in] Should be set to 0pdwNumOutData
: [out] Should be set to EC_NULL
10.2.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 instancedwInBufSize
: [in] Size of the input buffer in bytespbyOutBuf
: [out] Should be set to EC_NULLdwOutBufSize
: [in] Should be set to 0pdwNumOutData
: [out] Should be set to EC_NULL
10.2.11. emRasNotify - ATEMRAS_NOTIFY_MBXNOTIFYMEMORYSMALL
Notification given, when buffer size 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 instancedwInBufSize
: [in] Size of the input buffer in bytespbyOutBuf
: [out] Should be set to EC_NULLdwOutBufSize
: [in] Should be set to 0pdwNumOutData
: [out] Should be set to EC_NULL