XDK API  3.6.0
Documentation
Macros | Enumerations | Functions
Serval_Tcp.h File Reference

An interface to the platform TCP (Transport Layer) More...

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

Macros

#define TCP_ACCEPT   Tcp_accept
 
#define TCP_CLOSE   Tcp_close
 
#define TCP_DELETE   Tcp_delete
 
#define TCP_GET_SOCKET_STATUS   Tcp_getSocketStatus
 
#define TCP_PREPARE_FOR_SENDING   Tcp_prepareForSending
 
#define TCP_RECEIVE   Tcp_receive
 
#define TCP_RETRY_SENDING_LATER   Tcp_retrySendingLater
 
#define TCP_SEND   Tcp_send
 
#define TCP_UNLISTEN   Tcp_unlisten
 

Enumerations

enum  Tcp_SocketStatus_T
 

Functions

retcode_t Tcp_accept (Tcp_Listener_T listener, Callable_T *callback_ptr, Tcp_Socket_T *socket_ptr)
 
retcode_t Tcp_close (Tcp_Socket_T socket)
 
retcode_t Tcp_connect (Ip_Address_T *ipAddr_ptr, Ip_Port_T port, Callable_T *callback_ptr, Tcp_Socket_T *socket_ptr)
 
retcode_t Tcp_delete (Tcp_Socket_T socket)
 
Tcp_Listener_T Tcp_getInvalidListener (void)
 
Tcp_Socket_T Tcp_getInvalidSocket (void)
 
retcode_t Tcp_getPeerName (Tcp_Socket_T socket, Ip_Address_T *ipAddr_ptr, Ip_Port_T *port_ptr)
 
retcode_t Tcp_getSocketError (Tcp_Socket_T const socket, int *error_ptr)
 
retcode_t Tcp_getSocketStatus (Tcp_Socket_T socket, Tcp_SocketStatus_T *status_ptr)
 
bool Tcp_isConnected (Tcp_Socket_T const socket)
 
bool Tcp_isValidListener (Tcp_Listener_T const listener)
 
bool Tcp_isValidSocket (Tcp_Socket_T const socket)
 
retcode_t Tcp_listen (Ip_Port_T port, Callable_T *callback, Tcp_Listener_T *listener_ptr)
 
retcode_t Tcp_prepareForSending (Tcp_Socket_T const socket, MsgSendingCtx_T *sendingCtx_ptr)
 
retcode_t Tcp_receive (Tcp_Socket_T socket, CommBuff_T *packet_ptr)
 
retcode_t Tcp_retrySendingLater (Tcp_Socket_T const socket, MsgSendingCtx_T *sendingCtx_ptr)
 
retcode_t Tcp_send (Tcp_Socket_T socket, CommBuff_T packet, Callable_T *callback_ptr)
 
retcode_t Tcp_unlisten (Tcp_Listener_T listener)
 

Detailed Description

This interface provides functions to handle TCP communication.

Macro Definition Documentation

#define TCP_ACCEPT   Tcp_accept
#define TCP_CLOSE   Tcp_close
#define TCP_DELETE   Tcp_delete
#define TCP_GET_SOCKET_STATUS   Tcp_getSocketStatus
#define TCP_PREPARE_FOR_SENDING   Tcp_prepareForSending
#define TCP_RECEIVE   Tcp_receive
#define TCP_RETRY_SENDING_LATER   Tcp_retrySendingLater
#define TCP_SEND   Tcp_send
#define TCP_UNLISTEN   Tcp_unlisten

Enumeration Type Documentation

This enum is used to represent connection state of a TCP socket.

Enumerator
TCP_SOCKET_STATUS_CLOSED 

The socket is closed and should be deleted.

TCP_SOCKET_STATUS_CONNECTING 

If we initiate connection to a remote party, then the socket is connecting until the connection has been established (SYN received from the remote party).

TCP_SOCKET_STATUS_OPEN 

If we accept the connection of the other party or the other party has accepted our connection request, then the socket is open (may be used for data communication).

TCP_SOCKET_STATUS_HALF_CLOSED 

If we have initiated the closing of the connection, then the socket is half-closed until the other party closes the connection at its end (FIN received from the other party).

TCP_SOCKET_STATUS_HALF_OPEN 

If the remote party has initiated the closing of the connection (FIN received), then the socket is half-open until we close the connection at our end (by sending a FIN to the other party).

TCP_SOCKET_STATUS_CLOSING 

If the remote party has initiated the closing of the connection, i.e., the socket is half-open, and we close the connection, then the socket is closing.

Function Documentation

retcode_t Tcp_accept ( Tcp_Listener_T  listener,
Callable_T callback_ptr,
Tcp_Socket_T socket_ptr 
)

This function accepts a received incoming attempt to create a new TCP connection from a remote client. After calling this function data can be sent and received over the returned TCP socket.

When some data is received, the registered callback is invoked. Before the return of the callback, Tcp_receive() must be received in order to receive the incoming packet. The received CommBuff_T element is not guaranteed to stay available after the return of the callback. If the received packet is needed for further processing after the return of the callback, then the function CommBuff_realloc() should be used in order to allocate a buffer which is kept until it is explicitly freed using the function CommBuff_free().

The callback is also invoked to signalize errors or other issues at the socket. In this case, the callback is invoked with a TCP or an IP retcode.

Note: This function is only used by a TCP server.

Parameters
[in]listenerHandle to a TCP server socket
[in]callback_ptrPointer to callback function which is invoked if data is received on given socket. If it is a NULL pointer, then the upper-layer is not interested to be notified about socket activities such as incoming packets or socket errors.
[out]socket_ptrOn success, a TCP socket handle is returned. On failure, an invalid socket handle is returned.
Returns
RC_OK on success, or a TCP or an IP error otherwise.
See also
Tcp_listen()
retcode_t Tcp_close ( Tcp_Socket_T  socket)

This function terminates the given TCP connection. Thus calling this function causes TCP to send out a FIN message to the connected partner. After invoking this function the socket may be half-open. This means we cannot send any data to the other side, but we can receive messages from the other side. If the other side also terminates the connection by sending a FIN message, the connection is completely terminated. An incoming FIN message is indicated by an invalid buffer in Tcp_receive(). Note: Some platform may implicitly reply with FIN_ACK for a incoming FIN without waiting for confirmation from application. Thus on such platform we never have a half open connection. However application is still expected to call this function.

If the socket callback is null, then PAL needs to delete the socket implicitly after the close is done.

Parameters
[in]socketHandle to the TCP socket to be terminated.
Returns
RC_OK on success, or a TCP or an IP error otherwise.
See also
Tcp_receive()
retcode_t Tcp_connect ( Ip_Address_T ipAddr_ptr,
Ip_Port_T  port,
Callable_T callback_ptr,
Tcp_Socket_T socket_ptr 
)

This function causes to open a TCP connection to the given host (IP address, port). It creates a new TCP socket and causes an attempt to establish a new TCP connection (handshake) to the given IP address and port. After finishing the connection establishment, data can be send and received via the returned TCP socket.

After this function returns the connection has not necessarily been entirely established. The function Tcp_prepareForSending() will return RC_TCP_SOCKET_BUSY as long as the connection has not been established.

When some data is received, the registered callback is invoked. Before the return of the callback, Tcp_receive() must be received in order to receive the incoming packet. The received CommBuff_T element is not guaranteed to stay available after the return of the callback. If the received packet is needed for further processing after the return of the callback, then the function CommBuff_realloc() should be used in order to allocate a buffer which is kept until it is explicitly freed using the function CommBuff_free().

The callback is also invoked to signalize errors or other issues at the socket. In this case, the callback is invoked with a TCP or an IP retcode.

Note: This function is only used by a TCP client.

Note: This function encompasses following Berkeley socket API calls: socket(), connect()

Parameters
[in]ipAddr_ptrPointer to IP address of the remote host (server) to connect to
[in]portTCP port on remote host to connect to (server port), in network byte order.
[in]callback_ptrPointer to callback function which is invoked if data is received on given socket.

The callback function should lead to calling Tcp_receive() in order to read the incoming data. It has to be a valid pointer.

Parameters
[out]socket_ptrOn success, a TCP socket handle is returned. On failure, an invalid socket handle is returned.
Returns
RC_OK on success, or a TCP or an IP error otherwise.
See also
Tcp_isValidSocket(), Tcp_send(), Tcp_receive()
retcode_t Tcp_delete ( Tcp_Socket_T  socket)

This function causes the system to release resources allocated to the given socket. After invoking this function the given TCP socket handle is invalid. This function should be invoked after Tcp_close() had been closed and the socket callback has been invoked with an invalid buffer, which indicates that the connection has been completely closed.

Parameters
[in]socketHandle to the TCP socket to be destroyed.
Returns
RC_OK on success
RC_TCP_INVALID_SOCKET
RC_TCP_CONNECTED
See also
Tcp_close()
Tcp_Listener_T Tcp_getInvalidListener ( void  )

This function should be used to un-initialize a listener socket handle. It returns the handle of an invalid listener socket. The call Tcp_isValidListener(Tcp_getInvalidListener()) results in FALSE.

Returns
A handle of an invalid listener socket. Accessing this socket for reading or writing as well as for communication would fail.
See also
Tcp_isValidListener()
Tcp_Socket_T Tcp_getInvalidSocket ( void  )

This function should be used to un-initialize a socket handle. It returns the handle of an invalid socket. The call Tcp_isValidSocket(Tcp_getInvalidSocket()) results in FALSE.

Returns
A handle of an invalid socket. Accessing this socket for reading or writing as well as for communication would fail.
See also
Tcp_isValidSocket()
retcode_t Tcp_getPeerName ( Tcp_Socket_T  socket,
Ip_Address_T ipAddr_ptr,
Ip_Port_T port_ptr 
)

This function identifies the connection partner (IP address, port) for a given socket handle.

Parameters
[in]socketHandle to the socket to get information from
[out]ipAddr_ptrIP address of the connection partner
[out]port_ptrTCP port of the connection partner, in network byte order.
Returns
RC_OK on success
RC_TCP_INVALID_SOCKET
RC_TCP_NOT_CONNECTED
RC_TCP_INVALID_PEER
retcode_t Tcp_getSocketError ( Tcp_Socket_T const  socket,
int *  error_ptr 
)

This function is used to check if there are pending errors on a given TCP socket.

Parameters
[in]socketHandle to the TCP socket to be checked
[out]error_ptrPointer to error value
Returns
RC_OK if error value is successfully stored in given error pointer
RC_TCP_INVALID_SOCKET
retcode_t Tcp_getSocketStatus ( Tcp_Socket_T  socket,
Tcp_SocketStatus_T status_ptr 
)

It returns the status of the given socket.

Parameters
[in]socketThe socket the status of which is required. It must be a valid socket.
[out]status_ptrThe status of the socket. It must be a valid pointer to save the status to.
Returns
RC_OK on success
RC_TCP_INVALID_SOCKET if the given socket is invalid.
bool Tcp_isConnected ( Tcp_Socket_T const  socket)

This function checks if the connection for a given TCP socket is established.

Parameters
[in]socketHandle to the TCP socket to be checked
Returns
TRUE if socket is connected, FALSE if socket is not connected.
Deprecated:
Use Tcp_getSocketStatus() instead!
bool Tcp_isValidListener ( Tcp_Listener_T const  listener)

This function checks if the given TCP server socket is a valid one.

Parameters
[in]listenerHandle to the TCP server socket to be checked
Returns
TRUE if server socket handle is valid, FALSE if listener handle is invalid
bool Tcp_isValidSocket ( Tcp_Socket_T const  socket)

This function checks if the given TCP socket is a valid one.

Parameters
[in]socketHandle to the TCP socket to be checked
Returns
TRUE if socket handle is valid, FALSE if socket handle is invalid
retcode_t Tcp_listen ( Ip_Port_T  port,
Callable_T callback,
Tcp_Listener_T listener_ptr 
)

This function creates a new TCP listener socket, binds it to the given port number and causes the socket to enter the listening state. After invoking this function the socket is ready to accept incoming connections.

When a connection request comes in, the given callback is invoked. Before the callback function returns, Tcp_accept() must be called in order to accept the incoming connection.

The callback function is also invoked on errors. In this case the callback is invoked with a TCP or an IP error.

Note: This function is only used by a TCP server.

Note: This function encompasses following Berkeley socket API calls: socket(), bind(), listen()

Parameters
[in]portTCP port to listen at, in network byte order.
[in]callbackCallback function which is invoked on incoming connection requests. It must be valid and assigned.
[out]listener_ptrOn success, a TCP listener handle is given back. On failure, an invalid socket handle is given back.
Returns
RC_OK on success, or a TCP or an IP error otherwise.
See also
Tcp_isValidListener(), Tcp_accept(), Callable_T, Callable_isAssigned()
retcode_t Tcp_prepareForSending ( Tcp_Socket_T const  socket,
MsgSendingCtx_T sendingCtx_ptr 
)

Prepares the socket and the sending context for sending. This function must be called before invoking Tcp_send(). It ensures that the socket is ready for sending. It also allocates a communication buffer for serializing the message packets. This means that sendingCtx_ptr->buffer must be a valid buffer.

The allocated buffer is used for serialization of the message. It needs to be valid until either a) Tcp_send has been invoked with this buffer after which the ownership of the buffer passes back to the PAL implementation, or b) CommBuff_free has been called on this buffer to indicate that sending has been aborted due to a serialization error.

Parameters
[in]socketThe socket over which the message should be sent.
[in]sendingCtx_ptrA pointer to the context structure of the sending job.
Returns
RC_OK on success. RC_TCP_OUT_OF_MEMORY or RC_TCP_SOCKET_BUSY to indicate the respective transient problems and the stack should retry sending using Tcp_retrySendingLater. Any other IP, TCP or DTLS return code indicates an error that will cause the stack to abort sending.
See also
MsgSendingCtx_T, Tcp_retrySendingLater()
retcode_t Tcp_receive ( Tcp_Socket_T  socket,
CommBuff_T packet_ptr 
)

This function fetches the received data from the given TCP socket. This function should only be called if the socket callback passed to Tcp_connect() or Tcp_accept() is invoked with the status RC_OK, which indicates incoming data.

If the received CommBuff_T element is invalid while the callback status as well as the retcode of Tcp_receive() is RC_OK, then a FIN has been received which means that the remote party has closed the connection. If such an invalid CommBuff_T is received after Tcp_close() has been invoked, then the connection is completely closed and should be deleted using the function Tcp_delete().

Parameters
[in]socketHandle to the TCP socket to get data of
[out]packet_ptrPointer to communication buffer to which received data is written. The provided CommBuff_T element should be released by the upper-layer as soon as possible. After the return of the socket callback, the buffer is not guaranteed to stay available.
Returns
RC_OK on success, or a TCP or an IP error otherwise.
See also
Tcp_accept(), Tcp_connect(), CommBuff_isValid()
retcode_t Tcp_retrySendingLater ( Tcp_Socket_T const  socket,
MsgSendingCtx_T sendingCtx_ptr 
)

This function should schedule the given sending job to be carried out later. This means that this function takes care to invoke the corresponding sending function, i.e., sendingCtx_ptr->sendingFunc, at some point later. Any other return code except RC_OK means that sending cannot be completed by by lower layer at given time and should be dropped.

It is up to the PAL implementation when to execute the function. However, the execution MUST be asynchronous, i.e. the caller of this function can remove itself from the execution stack and is not part of the execution stack when sendingCtx_ptr->sendingFunc is executed.

An implementation of this function is free to decide whether to call sendingCtx_ptr->sending function after an interval or when the socket is able to send again. In the latter case, however, calling this function on a socket that is not busy, MUST nevertheless trigger execution of sendingCtx_ptr->sendingFunc.

Finally, on multi-threaded implementations of the PAL, the execution of sendingCtx_ptr->sendingFunc is expected to happen in the same context that normal network operations take place in.

Implementation note: The interface currently does not provide a meaningful way for aborting a retry. This can occur if the message times out while waiting for transmission and is thus deleted. This in turn will result in the MsgSendingCtx_T structure to have been cleared. Thus an implementation must check the validity of the sending function in sendingCtx_ptr->sendingFunc before calling it.

Parameters
[in]socketThe socket over which the message should be sent.
[in]sendingCtx_ptrA pointer to the context structure of the sending job.
Returns
RC_OK on success, or a TCP or an IP error otherwise.
See also
MsgSendingCtx_T, Tcp_retrySendingLater()
retcode_t Tcp_send ( Tcp_Socket_T  socket,
CommBuff_T  packet,
Callable_T callback_ptr 
)

This function sends the data in the given CommBuff via the given TCP socket. Every time before invoking this function, the function Tcp_prepareForSending() must be invoked and return RC_OK. The CommBuff_T element provided by Tcp_prepareForSending() must be used here to carry the payload.

After this function returns, the packet will not necessarily have been sent. The caller will be informed about the completion of sending using the given callback function. Furthermore, successful sending does guarantee that the remote party received the packet as TCP does provide reliable communication.

The callback is also used to report errors to the callers. If an error occurred after Tcp_send has returned. In this case the callback is invoked with a TCP or an IP retcode.

Parameters
[in]socketHandle to the TCP socket to send data
[in]packetHandle to the CommBuff_T which contains the payload to be sent. This CommBuff_T must be the one which has been provided by the function Tcp_prepareForSending(). The PAL implementation must free any buffers that have been allocated. Thus, the buffer must not be used after the return of this function.
[in]callback_ptrPointer to callback function which is invoked after sending of given data is complete. The application has to wait with sending a new packet until the callback is invoked.
Returns
RC_OK on success. RC_TCP_OUT_OF_MEMORY or RC_TCP_SOCKET_BUSY to indicate the respective transient problems and the stack should retry sending using Tcp_retrySendingLater. Any other IP, TCP or DTLS return code indicates an error that will cause the stack to abort sending.
See also
Tcp_retrySendingLater()
retcode_t Tcp_unlisten ( Tcp_Listener_T  listener)

This function stops listening on given TCP listener socket. After invoking this function the given TCP listener handle is invalid. Before invoking this function Tcp_listen() has to be called.
This function is only used by a TCP server.

Parameters
[in]listenerTCP listener handle to be closed
Returns
RC_OK on success
RC_TCP_PORT_NOT_USED port not registered as listener
See also
Tcp_isValidListener(), Tcp_listen()

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:47 by doxygen 1.8.8