# RAS-Server for EC-Lyser and EC-Engineer

## Integration Requirements

To use the diagnosis tool EC-Lyser with a customer application, some modifications have to be done during integration of the EC-Simulator. 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.

![Diagram showing RAS-Server integration requirements with EC-Lyser or EC-Engineer connecting via a socket-based uplink to the Remote API (RAS) Server opened by the customer application for EC-Simulator diagnosis](../Media/integration-requirements.png)

An example on how to integrate the Remote API Server within the application is given with the example application EcSimulatorHilDemo, which is preconfigured to listen for EC-Lyser on TCP Port 6000 when command line parameter “-sp” is given.

To demonstrate the steps needed within a custom application, a developer may use the following pseudo-code segment as a point of start. The Remote API Server library “EcSimulatorRasServer” must be linked.

## Pseudo Code

```cpp
#include "EcSimulatorRasServer.h"

/* custom Remote API Notification handler, example in EcSimulatorHilDemo (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 */
}
```

```cpp
    /* initialization  */
    EC_T_RAS_SERVER_PARMS  oRemoteApiConfig;
    OsMemset(&oRemoteApiConfig, 0, sizeof(EC_T_RAS_SERVER_PARMS));
    EC_T_PVOID          pvRemApiHandle;
    oRemoteApiConfig.dwSignature            = EC_RAS_SERVER_SIGNATURE;
    oRemoteApiConfig.dwSize                 = sizeof(EC_T_RAS_SERVER_PARMS);
    /* INADDR_ANY */
    oRemoteApiConfig.oAddr.dwAddr           = 0;
    /*< default is port 6000 > */
    oRemoteApiConfig.wPort                  = wServerPort;
    /*< default is 2 ms */
    oRemoteApiConfig.dwCycleTime            = EC_RAS_CYCLE_TIME;
    oRemoteApiConfig.dwCommunicationTimeout = EC_RAS_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;

    /* init simulator */
    esInitSimulator(...);

    /* start remote API server */
    esRasSrvStart(dwSimulatorInstanceId, &oRemoteApiConfig, &pvRemApiHandle);

    /* stop remote API server */
    esRasSrvStop(dwSimulatorInstanceId, pvRemApiHandle, 2000)

    esDeinitSimulator(...);
}
```

## Required API Calls

### esRasSrvStart

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) EC_NAMESPACE::esRasSrvStart(const [EC_T_RAS_SERVER_PARMS](#_CPPv421EC_T_RAS_SERVER_PARMS) \*pParms, [EC_T_PVOID](api.html.md#_CPPv410EC_T_PVOID) \*ppHandle)

Starts the RAS Server. 

* **Parameters:**
  * **pParms** – [in] Server start-up parameters 
  * **ppHandle** – [out] Handle to opened instance, used for ctrl access 
* **Returns:**
  [EC_E_NOERROR](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga8c8419c32e88e73d940a4501fe427116) or error code 

### struct EC_T_RAS_SERVER_PARMS

### Public Members

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwSignature

[in] Set to EC_RAS_SERVER_SIGNATURE 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwSize

[in] Set to sizeof(EC_T_RAS_SERVER_PARMS) 

### [EC_T_LOG_PARMS](api_general.html.md#_CPPv414EC_T_LOG_PARMS) LogParms

[in] Logging parameters 

### [EC_T_IPADDR](#_CPPv411EC_T_IPADDR) oAddr

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

### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wPort

[in] Remote Access Server (RAS) listen port 

### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wMaxClientCnt

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

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwCycleTime

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

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwCommunicationTimeout

[in] Timeout [ms] before automatically closing connection 

### EC_T_CPUSET oAcceptorThreadCpuAffinityMask

[in] Acceptor Thread CPU affinity mask 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwAcceptorThreadPrio

[in] Acceptor Thread Priority 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwAcceptorThreadStackSize

[in] Acceptor Thread Stack Size 

### EC_T_CPUSET oClientWorkerThreadCpuAffinityMask

[in] Client Worker Thread CPU affinity mask 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwClientWorkerThreadPrio

[in] Client Worker Thread Priority 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwClientWorkerThreadStackSize

[in] Client Worker Thread Stack Size 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwMaxQueuedNotificationCnt

[in] Amount of concurrently queue able Notifications 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwMaxParallelMbxTferCnt

[in] Amount of concurrent active mailbox transfers 

### [EC_PF_NOTIFY](api_general.html.md#_CPPv412EC_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](api.html.md#_CPPv410EC_T_DWORD) dwCycErrInterval

[in] Interval which allows cyclic Notifications 

### [EC_T_DWORD](api.html.md#_CPPv410EC_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](api.html.md#_CPPv49EC_T_BYTE) \*pbyTlsCert

[in] TLS certificate filename string 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwTlsCertSize

[in] Size of TLS certeficate 

### EC_T_TLS_CERT_TYPE eTlsCertType

[in] TLS certeficate type 

### [EC_T_BYTE](api.html.md#_CPPv49EC_T_BYTE) \*pbyTlsPrivKey

[in] TLS private key filename string 

### [EC_T_DWORD](api.html.md#_CPPv410EC_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](#_CPPv417EC_T_INNER_IPADDR) sAddr

IPv4 address (endianness independent) 

### [EC_T_DWORD](api.html.md#_CPPv410EC_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](api.html.md#_CPPv49EC_T_BYTE) by[4]

IPv4 address (endianness independent) 

### esRasSrvStop

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) EC_NAMESPACE::esRasSrvStop([EC_T_PVOID](api.html.md#_CPPv410EC_T_PVOID) pvHandle, [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwTimeout)

Stops the RAS Server. 

* **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](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga8c8419c32e88e73d940a4501fe427116) or error code 

### RasNotifyCallback - xxx

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

Data structure filled with detailed information about the according notification.

### struct [EC_T_NOTIFYPARMS](api_notifications.html.md#_CPPv416EC_T_NOTIFYPARMS)

### EC_T_VOID \*[pCallerData](api_notifications.html.md#_CPPv4N16EC_T_NOTIFYPARMS11pCallerDataE)

### [EC_T_BYTE](api.html.md#_CPPv49EC_T_BYTE) \*[pbyInBuf](api_notifications.html.md#_CPPv4N16EC_T_NOTIFYPARMS8pbyInBufE)

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) [dwInBufSize](api_notifications.html.md#_CPPv4N16EC_T_NOTIFYPARMS11dwInBufSizeE)

### [EC_T_BYTE](api.html.md#_CPPv49EC_T_BYTE) \*[pbyOutBuf](api_notifications.html.md#_CPPv4N16EC_T_NOTIFYPARMS9pbyOutBufE)

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) [dwOutBufSize](api_notifications.html.md#_CPPv4N16EC_T_NOTIFYPARMS12dwOutBufSizeE)

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) \*[pdwNumOutData](api_notifications.html.md#_CPPv4N16EC_T_NOTIFYPARMS13pdwNumOutDataE)

### RasNotifyCallback - EC_RAS_NOTIFY_CONNECTION

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

**RasNotifyCallback - EC_RAS_NOTIFY_CONNECTION**
: **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

Data structure containing the new Remote API state and the cause of state change.

### struct EC_T_RAS_CONNOTIFYDESC

### Public Members

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwCause

[in] Cause of state connection state change 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwCookie

[in] Unique identification cookie of connection instance 

### RasNotifyCallback - EC_RAS_NOTIFY_REGISTER

Notification that a connected application registered a client to the stack.

**RasNotifyCallback - 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](api.html.md#_CPPv410EC_T_DWORD) dwCookie

[in] Unique identification cookie of connection instance 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwResult

[in] Result of registration request 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceId

[in] Master Instance client registered to 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwClientId

[in] Client ID of registered client 

### RasNotifyCallback - EC_RAS_NOTIFY_UNREGISTER

Notification that a connected application un-registered a client from the simulator stack.

**RasNotifyCallback - 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

[RasNotifyCallback - EC_RAS_NOTIFY_REGISTER](#rasnotifycallback-ec-ras-notify-register)

### RasNotifyCallback - EC_RAS_NOTIFY_MARSHALERROR

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

**RasNotifyCallback - EC_RAS_NOTIFY_MARSHALERROR**
: **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](api.html.md#_CPPv410EC_T_DWORD) dwCookie

[in] Unique identification cookie of connection instance 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwCause

[in] Cause of the command marshalling error 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwLenStatCmd

[in] Length of the faulty command 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwCommandCode

[in] Command code of the faulty command 

### RasNotifyCallback - EC_RAS_NOTIFY_ACKERROR

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

**RasNotifyCallback - 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

### RasNotifyCallback - EC_RAS_NOTIFY_NONOTIFYMEMORY

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

**RasNotifyCallback - EC_RAS_NOTIFY_NONOTIFYMEMORY**
: **Parameter**
  : * `pbyInBuf`: [in] Pointer to EC_T_DWORD containing a 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

### RasNotifyCallback - EC_RAS_NOTIFY_STDNOTIFYMEMORYSMALL

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

<!-- RasNotifyCallback: EC_RAS_NOTIFY_STDNOTIFYMEMORYSMALL
:pbyInBuf: Pointer to EC_T_DWORD containing unique identification cookie of connection instance
:dwInBufSize: Size of the input buffer in bytes -->

### RasNotifyCallback - EC_RAS_NOTIFY_MBXNOTIFYMEMORYSMALL

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

**RasNotifyCallback - 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

This is a serious error. If this error occurs, Mailbox Transfer objects may have gotten out of sync and are therefore no longer valid.

#### SEE ALSO
`esRasSrvStart()` for Mailbox notifications should be dimensioned correctly.

\\newpage