XDK API  3.6.0
Documentation
Macros | Typedefs | Functions
Serval_XTcp.h File Reference

The interface description of a proprietary TCP based application protocol both for client and server. More...

#include <Serval_Defines.h>
#include <Serval_Msg.h>
+ Include dependency graph for Serval_XTcp.h:
+ This graph shows which files directly or indirectly include this file:

Macros

#define SERVAL_XTCP_MAX_LEN_APP_PAYLOAD   256
 
#define SERVAL_XTCP_MAX_NUM_CLIENT_INSTANCE   3
 
#define SERVAL_XTCP_MAX_NUM_CONNECTIONS   10
 
#define SERVAL_XTCP_MAX_NUM_SERVER_INSTANCE   3
 
#define SERVAL_XTCP_RESERVED_CONNECTIONS_FOR_CLIENT   3
 
#define SERVAL_XTCP_SERVER_CONNECTION_IDLE_TIMEOUT   60000
 

Typedefs

typedef void(* AppXTcpCallback_T )(uint8_t sessionId, Msg_T *msg_ptr, retcode_t status)
 
typedef struct XTcpMsg_S XTcpMsg_T
 

Functions

XTcpMsg_TMsg_getXTcpMsg (Msg_T *msg_ptr)
 
retcode_t XTcp_close (uint8_t sessionId)
 This function closes an active session. Can be called by either a TCP Client or Server. More...
 
void XTcp_getPayload (Msg_T *msg_ptr, uint8_t **payload_pptr, unsigned int *payloadLen_ptr)
 This function is called to get the payload of the received message. It provides the reference to the payload and its length as output parameters. More...
 
void XTcp_getPeer (Msg_T *msg_ptr, Ip_Address_T *ipAddress_ptr, uint16_t *port_ptr)
 This function identifies the connection partner (IP address, port) for a given socket handle. More...
 
retcode_t XTcp_isSecured (uint8_t sessionId, bool *isSecured)
 This function verifies if a session is secured or not. More...
 
retcode_t XTcp_push (uint8_t sessionId, uint8_t const *payload_ptr, unsigned int payloadLen)
 Pushes the application data over an open TCP connection. More...
 

Detailed Description

Since
1.4

Macro Definition Documentation

#define SERVAL_XTCP_MAX_LEN_APP_PAYLOAD   256

This is the length of the payload buffer of a XTCP message.

#define SERVAL_XTCP_MAX_NUM_CLIENT_INSTANCE   3

This is the maximal number of parallel XTCP client instance initiated by the application.

Note: This summed with SERVAL_XTCP_MAX_NUM_SERVER_INSTANCE should not be set greater than the SERVAL_XTCP_MAX_NUM_CONNECTIONS.

#define SERVAL_XTCP_MAX_NUM_CONNECTIONS   10

This is the maximal number of parallel XTCP connections either initiated by the application or opened by the server. This should be set to the maximum number of communication peers that are expected by the application.

Note: This should not exceed the number of TCP sockets provided by the platform

#define SERVAL_XTCP_MAX_NUM_SERVER_INSTANCE   3

This is the maximal number of parallel XTCP server instance initiated by the application.

Note: This summed with SERVAL_XTCP_MAX_NUM_CLIENT_INSTANCE should not be set greater than the SERVAL_XTCP_MAX_NUM_CONNECTIONS.

#define SERVAL_XTCP_RESERVED_CONNECTIONS_FOR_CLIENT   3

Number of connections reserved to be used as client connections. Obviously, this must be smaller than SERVAL_XTCP_MAX_NUM_CONNECTIONS

#define SERVAL_XTCP_SERVER_CONNECTION_IDLE_TIMEOUT   60000

Define the timeout in ms after which the XTCP server will close an idle connection. It should be a multiple of SERVAL_RESOURCE_MONITOR_PERIODE. Suggested is a value 2-5 times as large as SERVAL_RESOURCE_MONITOR_PERIODE.

Typedef Documentation

typedef void(* AppXTcpCallback_T)(uint8_t sessionId, Msg_T *msg_ptr, retcode_t status)

A data type representing a callback function pointer for application. The application uses such callback functions in order to be notified about the sending and receiving result of outgoing/incoming messages.

typedef struct XTcpMsg_S XTcpMsg_T

The data structure for messages of the generic proprietary TCP based application protocol XTCP.

Since
1.4
See also
struct XTcpMsg_S

Function Documentation

XTcpMsg_T* Msg_getXTcpMsg ( Msg_T msg_ptr)

This function provides a pointer to the structure holding XTCP message in the given Msg_T object.

Parameters
[in]msg_ptrReference to a Msg_T object. It has to be a valid pointer.
Returns
a pointer of type XTcpMsg_T to the required web message structure.
Since
1.4
retcode_t XTcp_close ( uint8_t  sessionId)
Parameters
[in]sessionIdIdentification number provided by the callback function
Return values
RC_OKon success
RC_XTCP_SESSION_NOT_ACTIVEwhen trying to close a session that does not exist
RC_XTCP_SOCKET_ACTIVEwhen trying to close a session that has not finished receiving/sending data
RC_XTCP_SOCKET_ERRORif the socket to be closed is invalid or close function fails
Example
Close an active session
1 uint8_t sessionId = 0;
2 
3 if (RC_OK == XTcp_close(sessionId))
4 {
5  printf("TCP Server and Client(s) stopped ...\n\r");
6 }
7 else
8 {
9  printf("TCP Server not stopped!\n\r");
10 }
Warning
The session ID must exist in order to close it.
void XTcp_getPayload ( Msg_T msg_ptr,
uint8_t **  payload_pptr,
unsigned int *  payloadLen_ptr 
)
Parameters
[in]msg_ptrReference to an object which identifies the instance of parsing context which should be used for parsing. It has to be a valid pointer.
[out]payload_pptrAn output parameter which references to the payload of the TCP message.
[out]payloadLen_ptrAn output parameter for the length of the payload of the parsed TCP message.
Return values
none.
Example
Get payload from a TCP Server or from a TCP Client. This must be used in the receive callback function.
1 // The Application Receive Callback must be set when calling
2 // function to start TCP Server or when calling function to
3 // connect a TCP Client
4 
5 void appReceiveCallback(uint8_t sessionId, Msg_T *msg_ptr, retcode_t status)
6 {
7  uint8_t *rcvPayload;
8  unsigned int rcvPayloadLen;
9 
10  XTcp_getPayload(msg_ptr, &rcvPayload, &rcvPayloadLen);
11 
12  printf("Payload (length = %d): ", rcvPayloadLen);
13 }
See also
XTcpClient_connect(), XTcpServer_listen(), XTcp_push()
void XTcp_getPeer ( Msg_T msg_ptr,
Ip_Address_T ipAddress_ptr,
uint16_t *  port_ptr 
)
Parameters
[in]msg_ptrReference to a object which identifies the instance of parsing context which should be used for parsing. It has to be a valid pointer.
[out]ipAddress_ptrIP address of the connection partner
[out]port_ptrTCP port of the connection partner
Return values
none.
Example
Get peer information. This must be used in the receive callback function.
1 void appReceiveCallback(uint8_t sessionId, Msg_T *msg_ptr, retcode_t status)
2 {
3  // Get peer information from the message pointer
4  Ip_Address_T peerIpAddress;
5  uint16_t peerPort;
6  char peerIpAddressString[15];
7 
8  XTcp_getPeer(msg_ptr, &peerIpAddress, &peerPort);
9  // Convert address to string
10  rc = Ip_convertAddrToString(&peerIpAddress, peerIpAddressString);
11 
12  if(0 > rc)
13  {
14  printf("IP conversion to string has failed!\r\n");
15  }
16 
17  printf("[TCE] : Peer IP is : %s:%d\r\n", peerIpAddressString, peerPort);
18 }
retcode_t XTcp_isSecured ( uint8_t  sessionId,
bool *  isSecured 
)
Parameters
[in]sessionIdIdentification number provided by the callback function
[in]isSecuredPointer to secured/non-secured variable passed by the application
Return values
RC_OKwhen success
RC_XTCP_SESSION_NOT_ACTIVEwhen no session was found
Example
Check whether a connection is secured or not inside a callback function
1 void appReceiveCallback(uint8_t sessionId, Msg_T *msg_ptr, retcode_t status)
2 {
3  retcode_t rc;
4 
5  rc = XTcp_isSecured(sessionId, &isSecure);
6 }
retcode_t XTcp_push ( uint8_t  sessionId,
uint8_t const *  payload_ptr,
unsigned int  payloadLen 
)
Parameters
[in]sessionIdIdentification number provided by the callback function
[in]payload_ptrA pointer to the buffer which contains the payload of a XTCP message.
[in]payloadLenThe length of the payload. The payload must not be longer than SERVAL_XTCP_MAX_LEN_APP_PAYLOAD.
Return values
RC_OKon success
RC_XTCP_PAYLOAD_TOO_LARGEif the length of the payload is larger than SERVAL_XTCP_MAX_LEN_APP_PAYLOAD
RC_XTCP_SESSION_NOT_ACTIVEwhen trying to push data to a session that does not exist
RC_XTCP_OVERLOADEDif no free message struct is available to accept the new sending job
RC_XTCP_MSG_FACTORY_OVERFLOWif there is a problem to construct the message payload to be sent
RC_XTCP_SENDING_ERRORif an error occurs while trying to send the message
Example
Push data from a TCP Server to a TCP Client or from TCP Client to a TCP Server.
1 retcode_t rc = RC_OK;
2 uint8_t * sendPayload = (uint8_t *)"Message";
3 unsigned int sendPayloadLen = strlen((char *)sendPayload);
4 uint8_t sessionId = 1;
5 
6 // Push payload
7 rc = XTcp_push(sessionId, sendPayload, sendPayloadLen);
Warning
The session ID must exist in order to push data to a client or a server.
See also
XTcpClient_connect(), XTcpServer_listen(), XTcp_getPayload()

All rights reserved. The use is subject to the XDK SDK EULA by Bosch Connected Devices and Solutions GmbH.
This documentation file has been automatically generated on Thu Mar 14 2019 19:12:46 by doxygen 1.8.8