11. RAS-Server for EC-Inspector and EC-Engineer

11.1. Integration Requirements

To use the diagnosis tool EC-Inspector with a customer application, some modifications have to be made 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.

skinparam monochrome true skinparam SequenceMessageAlign direction node "EC-Inspector" { [RAS-Client] } node "EC-Monitor application" { [RAS-Server] [EC-Monitor core] } [RAS-Client] - [RAS-Server] [RAS-Server] - [EC-Monitor core]

An example on how to integrate the Remote API Server within the application is given with the example application, which in this 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, the following pseudo-code segment may be used as a point of start. The Remote API Server library “EcMonitorRasServer.lib” (or respectively “EcMonitorRasServer.a”) must be linked.

11.2. Application programming interface

11.2.1. emonRasSrvStart

EC_T_DWORD EC_NAMESPACE::emonRasSrvStart(EC_T_RAS_SERVER_PARMS *pParms, EC_T_PVOID *ppHandle)

Initializes and starts a 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 EC_T_RAS_SERVER_PARMS

Public Members

EC_T_DWORD dwSignature

[in] Set to EC_RAS_SERVER_SIGNATURE

EC_T_DWORD dwSize

[in] Set to sizeof(EC_T_RAS_SERVER_PARMS)

EC_T_LOG_PARMS LogParms

[in] Logging parameters

EC_T_IPADDR oAddr

[in] Remote Access Server (RAS) listen IP address

EC_T_WORD wPort

[in] Remote Access Server (RAS) listen 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 [ms] 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

EC_T_DWORD dwMaxQueuedNotificationSize

[in] Size of concurrent active mailbox transfers

EC_PF_CHECK_TOKEN pfCheckToken

[in] Function pointer called to check token

EC_T_VOID *pvCheckTokenContext

[in] Check token context

EC_T_BYTE *pbyTlsCert

[in] TLS certificate filename string

EC_T_DWORD dwTlsCertSize

[in] Size of TLS certeficate

EC_T_TLS_CERT_TYPE eTlsCertType

[in] TLS certeficate type

EC_T_BYTE *pbyTlsPrivKey

[in] TLS private key filename string

EC_T_DWORD dwTlsPrivKeySize

[in] Size of TLS private key

EC_T_TLS_PRIVKEY_TYPE eTlsPrivKeyType

[in] TLS certeficate type

union EC_T_IPADDR
#include <EthernetServices.h>

Public Members

EC_T_INNER_IPADDR sAddr

IPv4 address (endianness independent)

EC_T_DWORD dwAddr

Reserved, use EC_T_IPADDR::sAddr.by instead. OS-Layer socket API calls (SOCKADDR_IN::sin_addr).

struct EC_T_INNER_IPADDR

Public Members

EC_T_BYTE by[4]

IPv4 address (endianness independent)

11.2.2. emonRasSrvStop

EC_T_DWORD EC_NAMESPACE::emonRasSrvStop(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

11.2.3. emonRasNotify

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)

11.2.4. emonRasNotify - EC_RAS_NOTIFY_CONNECTION

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

emonRasNotify - EC_T_RAS_CONNOTIFYDESC
Parameter

  • pbyInBuf: [in] Pointer to data of type EC_T_RAS_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 EC_T_RAS_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

11.2.5. emonRasNotify - EC_RAS_NOTIFY_REGISTER

Notification that a connected application registered a client to the EC-Monitor.

emonRasNotify - EC_RAS_NOTIFY_REGISTER
Parameter

  • pbyInBuf: [in] Pointer to data of type EC_T_RAS_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 EC_T_RAS_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

11.2.6. emonRasNotify - EC_RAS_NOTIFY_UNREGISTER

Notification that a connected application un-registered a client from the EC-Monitor.

emonRasNotify - EC_RAS_NOTIFY_UNREGISTER
Parameter

  • pbyInBuf: [in] Pointer to data of type EC_T_RAS_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

See also

EC_T_RAS_REGNOTIFYDESC

11.2.7. emonRasNotify - EC_RAS_NOTIFY_MARSHALERROR

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

emonRasNotify - EC_RAS_NOTIFY_MARSHALERRORDESC
Parameter

  • pbyInBuf: [in] Pointer to data of type EC_T_RAS_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 EC_T_RAS_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 of the faulty command

EC_T_DWORD dwCommandCode

[in] Command code of the faulty command

11.2.8. emonRasNotify - EC_RAS_NOTIFY_ACKERROR

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

emonRasNotify - EC_RAS_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

11.2.9. emonRasNotify - EC_RAS_NOTIFY_NONOTIFYMEMORY

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

emonRasNotify - EC_RAS_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

11.2.10. emonRasNotify - EC_RAS_NOTIFY_STDNOTIFYMEMORYSMALL

Notification given when the buffer size for standard notifications available in pre-allocated notification store is too small to carry a specific notification. This points to a configuration error.

emonRasNotify - EC_RAS_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

11.2.11. emonRasNotify - EC_RAS_NOTIFY_MBXNOTIFYMEMORYSMALL

Notification given when the buffer size for Mailbox notifications available in pre-allocated notification store is 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 become out of sync and therefore no longer valid. Mailbox notifications should be dimensioned correctly, see emonRasSrvStart()

emonRasNotify - EC_RAS_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