nRF5 IoT SDK  v0.9.0
 All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
UDP Application Interface for Nordic's IPv6 stack

Nordic User Datagram Protocol Application Interface for Nordic's IPv6 stack. More...

Data Structures

struct  udp6_socket_t
 UDP socket reference. More...
 

Typedefs

typedef uint32_t(* udp6_handler_t )(const udp6_socket_t *p_socket, const ipv6_header_t *p_ip_header, const udp6_header_t *p_udp_header, uint32_t process_result, iot_pbuffer_t *p_rx_packet)
 UDP data receive callback. More...
 

Functions

uint32_t udp6_socket_allocate (udp6_socket_t *p_socket)
 Allocates a UDP socket. More...
 
uint32_t udp6_socket_free (const udp6_socket_t *p_socket)
 Frees an allocated UDP socket. More...
 
uint32_t udp6_socket_recv (const udp6_socket_t *p_socket, const udp6_handler_t callback)
 Registers callback to be notified of data received on a socket. More...
 
uint32_t udp6_socket_bind (const udp6_socket_t *p_socket, const ipv6_addr_t *p_src_addr, uint16_t src_port)
 Binds a UDP socket to a specific port and address. More...
 
uint32_t udp6_socket_connect (const udp6_socket_t *p_socket, const ipv6_addr_t *p_dest_addr, uint16_t dest_port)
 Connects a UDP socket to aspecific port and address. More...
 
uint32_t udp6_socket_send (const udp6_socket_t *p_socket, iot_pbuffer_t *p_packet)
 Sends a UDP packet on a specific socket. More...
 
uint32_t udp6_socket_sendto (const udp6_socket_t *p_socket, const ipv6_addr_t *p_dest_addr, uint16_t dest_port, iot_pbuffer_t *p_packet)
 Sends a UDP packet on a specific socket to a remote address and port. More...
 
uint32_t udp6_socket_app_data_set (const udp6_socket_t *p_socket)
 Sets application data for a socket. More...
 

Detailed Description

Nordic User Datagram Protocol Application Interface for Nordic's IPv6 stack.

This module provides basic features related to User Datagram Protocol (UDP) support.

Typedef Documentation

typedef uint32_t(* udp6_handler_t)(const udp6_socket_t *p_socket, const ipv6_header_t *p_ip_header, const udp6_header_t *p_udp_header, uint32_t process_result, iot_pbuffer_t *p_rx_packet)

UDP data receive callback.

API used to notify the application of UDP packets received. If the received data is malformed (for example, a checksum error), the packet is still notified to the application. The process_result parameter indicates whether the packet was successfully processed by UDP. The application should check process_result before consuming the packet.

Parameters
[in]p_socketReference to the socket on which the data is received.
[in]p_ip6_headerPointer to the IP header of the received ICMP packet.
[in]p_udp_headerPointer to the UDP header of the received packet.
[in]process_resultNotifies the application if the UDP packet was processed successfully success or if an error occurred, for example, the packet was malformed.
[in]p_rx_packetPacket buffer containing the received packed. p_rx_packet->p_payload contains the UDP payload.
Returns
A provision for the application to notify the module of whether the received packet was processed successfully by application. The application may take ownership of the received packet by returning IOT_IPV6_ERR_PENDING, in which case the application must take care to free it using iot_pbuffer_free.

Function Documentation

uint32_t udp6_socket_allocate ( udp6_socket_t p_socket)

Allocates a UDP socket.

This API should be called to be assigned a UDP socket. The maximum number of sockets that can be allocated using the API is determined by the define UDP6_MAX_SOCKET_COUNT.

Parameters
[out]p_socketReference to the allocated socket is provided in the pointer if the procedure was successful. Should not be NULL.
Return values
NRF_SUCCESSIf the socket was allocated successfully. Otherwise, an error code that indicates the reason for the failure is returned.
uint32_t udp6_socket_app_data_set ( const udp6_socket_t p_socket)

Sets application data for a socket.

A utility API that allows the application to set any application specific mapping with the UDP Socket. The UDP module remembers the pointer provided by the application as long as the socket is not freed and if receive data callback is called each time as part of udp_socket_t.

Parameters
[in]p_socketPointer to the socket for which the application data mapping is being set. A pointer to the application data should be provided by setting the p_socket->p_app_data field.
Return values
NRF_SUCCESSIf the procedure was executed successfully. Otherwise, an error code that indicates the reason for the failure is returned.
uint32_t udp6_socket_bind ( const udp6_socket_t p_socket,
const ipv6_addr_t p_src_addr,
uint16_t  src_port 
)

Binds a UDP socket to a specific port and address.

API used to bind a UDP socket to a local port and an address.

Parameters
[in]p_socketHandle reference to the socket. Should not be NULL.
[in]p_src_addrLocal IPv6 address to be bound on specific socket.
[in]src_portLocal UDP port to be bound on specific socket.
Return values
NRF_SUCCESSIf the procedure was executed successfully. Otherwise, an error code that indicates the reason for the failure is returned.
uint32_t udp6_socket_connect ( const udp6_socket_t p_socket,
const ipv6_addr_t p_dest_addr,
uint16_t  dest_port 
)

Connects a UDP socket to aspecific port and address.

API used to connect a UDP socket to a remote port and remote address.

Parameters
[in]p_socketHandle reference to the socket. Should not be NULL.
[in]p_dest_addrIPv6 address of the remote destination.
[in]dest_portRemote USP port to connect the socket to.
Return values
NRF_SUCCESSIf the connection was established successfully.
uint32_t udp6_socket_free ( const udp6_socket_t p_socket)

Frees an allocated UDP socket.

API used to free a socket allocated using udp6_socket_allocate.

Parameters
[in]p_socketHandle reference to the socket. Should not be NULL.
Return values
NRF_SUCCESSIf the socket was freed successfully. Otherwise, an error code that indicates the reason for the failure is returned.
uint32_t udp6_socket_recv ( const udp6_socket_t p_socket,
const udp6_handler_t  callback 
)

Registers callback to be notified of data received on a socket.

API to register a callback to be notified of data received on a socket.

Parameters
[in]p_socketHandle reference to the socket. Should not be NULL.
[in]callbackCallback being registered to receive data. Should not be NULL.
Return values
NRF_SUCCESSIf the procedure was executed successfully. Otherwise, an error code that indicates the reason for the failure is returned.
uint32_t udp6_socket_send ( const udp6_socket_t p_socket,
iot_pbuffer_t p_packet 
)

Sends a UDP packet on a specific socket.

API used to send UDP data over a UDP socket. Remote port and address must be set with udp6_socket_connect() before using this API.

Applications that call this function should allocate a packet with type UDP6_PACKET_TYPE (set in the allocation parameter) before calling the function.

The application shall not free the allocated packet buffer if the procedure was successful, to ensure that no data copies are needed when transmitting a packet.

Parameters
[in]p_socketHandle reference to the socket. Should not be NULL.
[in]p_packetData to be transmitted on the socket. The application should allocate a packet buffer with type UDP6_PACKET_TYPE using iot_pbuffer_allocate. p_packet->p_payload and p_packet->length should be appropriately populated by the application to contain the payload and length of the UDP packet, respectively.
Return values
NRF_SUCCESSIf the procedure was executed successfully. Otherwise, an error code that indicates the reason for the failure is returned.
uint32_t udp6_socket_sendto ( const udp6_socket_t p_socket,
const ipv6_addr_t p_dest_addr,
uint16_t  dest_port,
iot_pbuffer_t p_packet 
)

Sends a UDP packet on a specific socket to a remote address and port.

API used to send UDP data over a UDP socket.

Parameters
[in]p_socketHandle reference to the socket. Should not be NULL.
[in]p_dest_addrIPv6 address of the remote destination.
[in]dest_portRemote UDP port to which data transmission is requested.
[in]p_packetData to be transmitted on the socket. Application should allocate a packet buffer with type UDP6_PACKET_TYPE using iot_pbuffer_allocate. p_packet->p_payload and p_packet->length should be appropriately populated by the application to contain the payload and length of the UDP packet, respectively.
Return values
NRF_SUCCESSIf the procedure was executed successfully. Otherwise, an error code that indicates the reason for the failure is returned.