Skip to content

Datagram interface functions#

The header file for the Datagram interface is fullsdkdtg.h.

NOTE: Use the functions of the Management interface to configure lab.SCHC FullSDK stack before using the Datagram interface.

The datagram interface allows the application to send and receive data packets to and from a remote application.

The interface is similar to the Berkeley datagram socket interface:

  • Sending packets – If a data packet to send is larger than what Layer 2 can accept, the fragmentation mechanism is activated. This fragmentation is transparent to the remote application: it will receive the data packet all at once.
  • Receiving packets – Fragmentation can also be activated in a receive operation, if the packet sent by the remote application is larger than what Layer 2 can accept.

Initialization#

The first function that the application must call is dtg_initialize() to initialize the the datagram interface before using it.

This function must be provided with the following parameters:

  • Callbacks parameter: transmission_result will inform the application of the end of a send request (success or failure). data_received will inform the application when a data packet is received.
  • Protocol parameter: Select an IPv6 or IPv4 network layer.

Socket creation#

In order to be able to send or receive data packets, the application must now call the dtg_socket() function.

This function must be provided with the following parameters:

  • socket: The socket for which transmission result is returned.
  • p_buffer: A pointer to the buffer where the received packets will be written.
  • data_size: The length of this buffer (in bytes).
  • dtg_sockaddr: The address f the socket.
  • status: The status of the tramission. No data is raised to the user in case of error.

dtg_socket() returns a socket structure that needs to be used as parameter for the following local port binding functions.

Local port binding#

dtg_socket() returns a socket structure that can be used by dtg_bind() to bind the application to an IPv6/v4 address and a local port for data packet reception.

If the application is not supposed to receive data packets from the remote application, it does not have to call dtg_bind().

Transmission#

A send operation is requested by calling the dtg_sendto() function on the corresponding socket structure. The function immediately returns a status that informs the caller whether the request has been accepted or not.

The request can be refused, for example when there is an ongoing send operation, or when the connectivity is not available.

If the request has been accepted, the result of the send operation will be provided later, by a call to the dtg_transmission_result callback (which is provided at initialization by dtg_initialize()) with the corresponding socket as parameter.

A new request for the same socket will not be accepted as long as the dtg_transmission_result callback with the corresponding socket is called.

Reception#

When a data packet is received, the dtg_data_received callback (which is provided at initialization by dtg_initialize()) is called.

Check the header file (fullsdkdtg.h) for information about flow control for reception.

Socket closing#

When a socket is no longer used, it must be closed, by calling dtg_close(). Any ongoing fragmentation process that could exist when calling dtg_close() is then terminated.