6LoWPAN Library Socket API More...

Data Structures
struct	socket_callback_t
	ICMP socket instruction. More...
Functions
int8_t	socket_open (uint8_t protocol, uint16_t identifier, void(passed_fptr)(void ))
	Create and initialize a socket for communication.
int8_t	socket_free (int8_t socket)
	A function to free a socket.
int8_t	socket_listen (int8_t socket)
	A function to set the socket to listening mode.
int8_t	socket_connect (int8_t socket, ns_address_t *address, uint8_t randomly_take_src_number)
	A function to connect to remote peer (TCP).
int8_t	socket_bind (int8_t socket, const ns_address_t *address)
	Bind socket to address.
int8_t	socket_bind2addrsel (int8_t socket, const ns_address_t *dst_address)
	Bind a local address to a socket based on the destination address and the address selection preferences.
int8_t	socket_close (int8_t socket, ns_address_t *address)
	A function to close a connection.
int8_t	socket_send (int8_t socket, uint8_t *buffer, uint16_t length)
	Send data via a connected TCP socket by client.
int16_t	socket_read (int8_t socket, ns_address_t src_addr, uint8_t buffer, uint16_t length)
	A function to read received data buffer from a socket.
int8_t	socket_sendto (int8_t socket, ns_address_t address, uint8_t buffer, uint16_t length)
	A function to send UDP, TCP or raw ICMP data via the socket.
int8_t	socket_read_session_address (int8_t socket, ns_address_t *address)
	A function to read session info for TCP event.
int8_t	socket_setsockopt (int8_t socket, uint8_t level, uint8_t opt_name, const void *opt_value, uint16_t opt_len)
	Set an option for a socket.
int8_t	socket_getsockopt (int8_t socket, uint8_t level, uint8_t opt_name, void opt_value, uint16_t opt_len)
	Get an option for a socket.
Variables
const uint8_t	ns_in6addr_any [16]
	IPv6 wildcard address IN_ANY.

Detailed Description

6LoWPAN Library Socket API

Common socket API

socket_open(), A function to open a socket.
socket_free(), A function to free a socket.

Socket read API at callback

socket_read(), A function to read received data buffer from a socket.
socket_read_session_address(), A function to read session info for a TCP event.

Socket TX API

socket_send(), A function to write data buffer to a socket.
socket_sendto(), A function to write data to a specific destination in the socket.

TCP socket connection handle

socket_listen(), A function to set the socket to listening mode.
socket_connect(), A function to connect to a remote peer.
socket_close(), A function to close a connection.

Sockets are a common abstraction model for network communication and are used in most operating systems. 6LoWPAN Library API follows BSD socket API conventions closely with some extensions necessitated by the event-based scheduling model.

ICMP RAW socket instruction

An ICMP raw socket can be created with the function socket_open() and the identifier 0xffff. When using ICMP sockets, the minimum packet length is 4 bytes which is the 4 bytes of ICMP header. The first byte is for type, second for code and last two are for the checksum that must always be set to zero. The stack will calculate the checksum automatically before transmitting the packet. THe header is followed by the payload if there is any. NOTE: While it is perfectly legal to send an ICMP packet without payload, some packet sniffing softwares might regard such packets as malformed. In such a case, a dummy payload can be attached by providing a socket_sendto() function with a pointer to your desired data buffer. Moreover, the current implementation of the stack allows only certain ICMP types, for example ICMP echo, reply, destination unreachable, router advertisement, router solicitation. It will drop any other unimplemented types. For example, Private experimentation type (200) will be dropped by default.

| ICMP Type | ICMP Code | Checksum | Payload | Notes | | :-------: | :----------: | :-------: | :--------: | :--------------:| | 1 | 1 | 2 | n bytes | Length in bytes | | 0xXX | 0xXX | 0x00 0x00 | n bytes | Transmit | | 0xXX | 0xXX | 0xXX 0xXX | n bytes | Receive |

ICMP echo request with 4 bytes of payload (ping6).

| ICMP Type | ICMP Code | Checksum | Payload | | :-------: | :----------: | :-------: | :-----------------: | | 0x80 | 0x00 | 0x00 0x00 | 0x00 0x01 0x02 0x03 |

ICMP echo response for the message above.

| ICMP Type | ICMP Code | Checksum | Payload | | :-------: | :----------: | :-------: | :-----------------: | | 0x81 | 0x00 | 0xXX 0xXX | 0x00 0x01 0x02 0x03 |

Socket receiving

When there is data to read from the socket, a receive callback function is called with the event type parameter set to SOCKET_DATA. The application must read the received data with socket_read() during the callback because the stack will release the data when returning from the receive callback.

Socket event has event_type and socket_id fields. The receive callback function must be defined when socket is opened using socket_open() API.

All supported socket event types are listed here:

How to use TCP sockets:

When the TCP socket is opened it is in closed state. It must be set either to listen or to connect state before it can be used to receive or transmit data.

A socket can be set to listen mode with the socket_listen() function. After the call, the socket can accept an incoming connection from a remote host. The listen mode closes the connection automatically after server timeout or when the client or application closes the connection manually by socket_close() function.

A TCP socket can be connected to a remote host with socket_connect() with correct arguments. After the function call, a (non-blocking) application must wait for the socket event to confirm the successful state change of the socket. After the successful state change, data can be sent using socket_send() by client and socket_send() by server. The connection can be closed with socket_close() function or by server timeout.

How to use UDP and RAW socket:

A UDP socket is ready to receive and send data immediately after a successful call of socket_open() and a NET_READY event is received. Data can be transmitted with the socket_sendto() function. An ICMP socket works with same function call.

Definition in file socket_api.h.

Function Documentation

int8_t socket_bind	(	int8_t	socket,
		const ns_address_t *	address
	)

Bind socket to address.

Used by the application to bind a socket to a port and/or an address. Binding can be done only once. The port or address cannot be changed after binding.

Parameters:

socket	Socket ID of the socket to bind.
address	Address structure containing the port and address to bind.

Returns:: 0 on success.; -1 if the given address is NULL.; -2 if the port is already bound to another socket.; -4 if the socket is already bound.; -5 bind is not supported on this type of socket

Definition at line 51 of file socket_api_stub.c.

int8_t socket_bind2addrsel	(	int8_t	socket,
		const ns_address_t *	dst_address
	)

Bind a local address to a socket based on the destination address and the address selection preferences.

Binding happens to the same address that socket_connect() would bind to. Reference: RFC5014 IPv6 Socket API for Source Address Selection.

Parameters:

socket	The socket ID.
dst_address	The destination address to which the socket wants to communicate.

Returns:: 0 on success.; -1 if the given address is NULL or socket ID is invalid.; -2 if the memory allocation failed.; -3 if the socket is already bound to address.; -4 if the interface cannot be found.; -5 if the source address selection fails.; -6 bind2addrsel is not supported on this type of socket.

int8_t socket_close	(	int8_t	socket,
		ns_address_t *	address
	)

A function to close a connection.

Parameters:

socket	The ID of the socket to be closed.
address	The address of the destination client. When using as a client, a null pointer shall be passed.

Returns:: 0 on success.; -1 if the given socket ID is not found, if the socket type is wrong or tcp_close() returns a failure.; -2 if no active TCP session was found.; -3 if the referred socket ID port is declared as a zero.

Note: It is highly recommended to always use randomly_take_src_number. The stack generates a new source port between 49152-65534.

Definition at line 59 of file socket_api_stub.c.

int8_t socket_connect	(	int8_t	socket,
		ns_address_t *	address,
		uint8_t	randomly_take_src_number
	)

A function to connect to remote peer (TCP).

Parameters:

socket	The socket ID.
address	The address of a remote peer.
randomly_take_src_number	1 enables find next free random port number for the current one.

Returns:: 0 on success.; -1 in case of an invalid socket ID or parameter.; -2 if memory allocation fails.; -3 if the socket is in listening state.; -4 if the socket is already connected.; -5 connect is not supported on this type of socket.; -6 if the TCP session state is wrong.; -7 if the source address selection fails.

Definition at line 43 of file socket_api_stub.c.

int8_t socket_free ( int8_t socket )

A function to free a socket.

Parameters:

socket ID of the socket to be released.

Returns:: 0 socket released.; -1 socket not released.

Definition at line 27 of file socket_api_stub.c.

int8_t socket_getsockopt	(	int8_t	socket,
		uint8_t	level,
		uint8_t	opt_name,
		void *	opt_value,
		uint16_t *	opt_len
	)

Get an option for a socket.

Used to read miscellaneous options for a socket. Supported levels and names defined above. If the buffer is smaller than the option, the output is silently truncated; otherwise opt_len is modified to indicate the actual length.

Parameters:

socket	The socket ID.
level	The protocol level.
opt_name	The option name (interpretation depends on level). See OPTNAMES_IPV6.
opt_value	A pointer to output buffer.
opt_len	A pointer to length of output buffer; updated on exit.

Returns:: 0 on success.; -1 invalid socket ID.; -2 invalid/unsupported option.

Definition at line 111 of file socket_api_stub.c.

int8_t socket_listen ( int8_t socket )

A function to set the socket to listening mode.

Parameters:

socket Socket ID to bind.

Returns:: 0 on success.; -1 on failure.

Definition at line 35 of file socket_api_stub.c.

int8_t socket_open	(	uint8_t	protocol,
		uint16_t	identifier,
		void()(void )	passed_fptr
	)

Create and initialize a socket for communication.

Parameters:

protocol	Defines the protocol to use.
identifier	The socket port. 0 indicates that port is not specified and it will be selected automatically when using the socket.
passed_fptr	A function pointer to a function that is called whenever a data frame is received to this socket.

Returns:: 0 or greater on success; Return value is the socket ID.; -1 on failure.; -2 on port reserved.

Definition at line 17 of file socket_api_stub.c.

int16_t socket_read	(	int8_t	socket,
		ns_address_t *	src_addr,
		uint8_t *	buffer,
		uint16_t	length
	)

A function to read received data buffer from a socket.

Used by the application to get data from a socket. This method must be called once from a socket callback when handling event SOCKET_DATA. If the received data does not fit in the buffer provided the excess data bytes are discarded.

Parameters:

socket	The socket ID.
src_addr	A pointer to a structure where the sender's address is stored.
buffer	A pointer to an array where the read data is written to.
length	The maximum length of the allocated buffer.

Returns:: greater than 0 indicates the length of the data copied to buffer.; 0 if no data is available to read.; -1 invalid input parameters.

Definition at line 75 of file socket_api_stub.c.

int8_t socket_read_session_address	(	int8_t	socket,
		ns_address_t *	address
	)

A function to read session info for TCP event.

Parameters:

socket	The socket ID.
address	A pointer to the address structure where the session address information is read to.

Returns:: 0 on success.; -1 if no socket is found or TCP is not compiled into this project.; -2 if no session information is found.

Note: This function should be called only at socket callback when the socket event is SOCKET_BIND_DONE or SOCKET_TX_DONE. The following sections introduce those functions.

Definition at line 95 of file socket_api_stub.c.

int8_t socket_send	(	int8_t	socket,
		uint8_t *	buffer,
		uint16_t	length
	)

Send data via a connected TCP socket by client.

Note: The socket connection must be ready before using this function. The stack uses automatically the address of the remote connected host as the destination address for the packet.

Parameters:

socket	The socket ID.
buffer	A pointer to data.
length	Data length.

Returns:: 0 done; -1 Invalid socket ID.; -2 Socket memory allocation fail.; -3 TCP state not established.; -4 Socket TX process busy.; -5 Socket is not connected.; -6 Packet too short.

Definition at line 67 of file socket_api_stub.c.

int8_t socket_sendto	(	int8_t	socket,
		ns_address_t *	address,
		uint8_t *	buffer,
		uint16_t	length
	)

A function to send UDP, TCP or raw ICMP data via the socket.

Used by the application to send data.

Parameters:

socket	The socket ID.
address	A pointer to the destination address information.
buffer	A pointer to data to be sent.
length	Length of the data to be sent.

Returns:: 0 on success.; -1 Invalid socket ID.; -2 Socket memory allocation fail.; -3 TCP state not established.; -4 Socket TX process busy.; -6 Packet too short.

Definition at line 87 of file socket_api_stub.c.

int8_t socket_setsockopt	(	int8_t	socket,
		uint8_t	level,
		uint8_t	opt_name,
		const void *	opt_value,
		uint16_t	opt_len
	)

Set an option for a socket.

Used to specify miscellaneous options for a socket. Supported levels and names defined above.

Parameters:

socket	The socket ID.
level	The protocol level.
opt_name	The option name (interpretation depends on level). See OPTNAMES_IPV6.
opt_value	A pointer to value for the specified option.
opt_len	Size of the data pointed to by the value.

Returns:: 0 on success.; -1 invalid socket ID.; -2 invalid/unsupported option.; -3 invalid option value.

Definition at line 103 of file socket_api_stub.c.

Variable Documentation

const uint8_t ns_in6addr_any[16]

IPv6 wildcard address IN_ANY.

Type:	Library
Created:	20 Jul 2017
Imports:	0
Forks:	0
Commits:	2
Dependents:	0
Dependencies:	0
Followers:	1

Important changes to repositories hosted on mbed.com

socket_api.h File Reference

Data Structures

Functions

Variables

Detailed Description

Common socket API

Socket read API at callback

Socket TX API

TCP socket connection handle

ICMP RAW socket instruction

Socket receiving

How to use TCP sockets:

How to use UDP and RAW socket:

Function Documentation

Variable Documentation

Repository toolbox

Repository details

Important Information for this Arm website

Important changes to repositories hosted on mbed.com

socket_api.h File Reference

Data Structures

Functions

Variables

Detailed Description

Common socket API

Socket read API at callback

Socket TX API

TCP socket connection handle

ICMP RAW socket instruction

Socket receiving

How to use TCP sockets:

How to use UDP and RAW socket:

Function Documentation

Variable Documentation

Repository toolbox

Repository details

Important Information for this Arm website

Access Warning