Frames: Extended Sockets (0x40-0x4F and 0xC0-0xCF)

Files
file	socket.h
	Because this framework dispatches received frames to frame handlers, this API layer for sockets makes use of callbacks to pass received data back to the calling code.
file	socket_frames.h
	Frame definitions and support functions for Extended Socket frames (0x40-0x4F and 0xC0-0xCF).
file	xbee_socket.c
	See xbee/socket.h for summary of API.
file	xbee_socket_frames.c
	Support functions for Extended Socket frames (0x40-0x4F and 0xC0-0xCF).

Data Structures
struct	xbee_frame_sock_create_t
	Format of XBee API frame type 0x40 (XBEE_FRAME_SOCK_CREATE). More...
struct	xbee_header_sock_option_req_t
	Header of XBee API frame type 0x41 (XBEE_FRAME_SOCK_OPTION_REQ); sent from host to XBee. More...
struct	xbee_frame_sock_option_resp_t
	Format of XBee API frame type 0xC1 (XBEE_FRAME_SOCK_OPTION_RESP); sent from XBee to host. More...
struct	xbee_header_sock_connect_t
	Header of XBee API frame type 0x42 (XBEE_FRAME_SOCK_CONNECT); sent from host to XBee. More...
struct	xbee_frame_sock_close_t
	Format of XBee API frame type 0x43 (XBEE_FRAME_SOCK_CLOSE). More...
struct	xbee_header_sock_send_t
	Header of XBee API frame type 0x44 (XBEE_FRAME_SOCK_SEND); sent from host to XBee. More...
struct	xbee_header_sock_sendto_t
	Header of XBee API frame type 0x45 (XBEE_FRAME_SOCK_SENDTO); sent from host to XBee. More...
struct	xbee_frame_sock_bind_listen_t
	Format of XBee API frame type 0x46 (XBEE_FRAME_SOCK_BIND_LISTEN). More...
struct	xbee_frame_sock_shared_resp_t
	Format of multiple XBee API frame types sent from XBee to host: 0xC0 (XBEE_FRAME_SOCK_CREATE_RESP) 0xC2 (XBEE_FRAME_SOCK_CONNECT_RESP) 0xC3 (XBEE_FRAME_SOCK_CLOSE_RESP) 0xC6 (XBEE_FRAME_SOCK_LISTEN_RESP) More...
struct	xbee_frame_sock_ipv4_client_t
	Format of XBee API frame type 0xCC (XBEE_FRAME_SOCK_IPV4_CLIENT); sent from XBee to host for new connections on a listening socket. More...
struct	xbee_frame_sock_receive_t
	Format of XBee API frame type 0xCD (XBEE_FRAME_SOCK_RECEIVE); sent from XBee to host when data arrives on a connected socket. More...
struct	xbee_frame_sock_receive_from_t
	Format of XBee API frame type 0xCE (XBEE_FRAME_SOCK_RECEIVE_FROM); sent from XBee to host when a datagram arrives on a bound UDP socket. More...
struct	xbee_frame_sock_state_t
	Format of XBee API frame type 0xCF (XBEE_FRAME_SOCK_STATE); sent from XBee to host when a socket's state changes. More...
struct	socket_t

Macros
#define	XBEE_SOCK_SOCKET_COUNT   10
	Number of sockets to track on the host. More...
#define	XBEE_SOCK_FRAME_HANDLERS   { 0, 0, xbee_sock_frame_handler, NULL }
	Macro for xbee_frame_handlers table of xbee_dispatch_table_entry_t structs.
#define	XBEE_SOCK_STATUS_SUCCESS   0x00
	Status codes used by multiple socket response frame types. More...
#define	XBEE_SOCK_STATUS_INVALID_PARAM   0x01
	invalid parameters
#define	XBEE_SOCK_STATUS_FAILED_TO_READ   0x02
	failed to retrieve option
#define	XBEE_SOCK_STATUS_IN_PROGRESS   0x03
	connect already in progress
#define	XBEE_SOCK_STATUS_CONNECTED   0x04
	connected/bound/listening
#define	XBEE_SOCK_STATUS_UNKNOWN   0x05
	unknown error
#define	XBEE_SOCK_STATUS_BAD_SOCKET   0x20
	invalid socket ID
#define	XBEE_SOCK_STATUS_OFFLINE   0x22
	not registered to network
#define	XBEE_SOCK_STATUS_INTERNAL_ERR   0x31
	internal error
#define	XBEE_SOCK_STATUS_RESOURCE_ERR   0x32
	resource error, try later
#define	XBEE_SOCK_STATUS_BAD_PROTOCOL   0x7B
	invalid protocol
#define	XBEE_SOCK_SOCKET_ID_INVALID   0xFF
	The 8-bit Socket ID is never 0xFF, except in Socket Create Response when socket creation wasn't successful. More...
#define	XBEE_FRAME_SOCK_CREATE   0x40
	Frame Type: Extended Socket Create.
#define	XBEE_FRAME_SOCK_OPTION_REQ   0x41
	Frame Type: Extended Socket Option Request.
#define	XBEE_FRAME_SOCK_OPTION_RESP   0xC1
	Frame Type: Extended Socket Option Response.
#define	XBEE_FRAME_SOCK_CONNECT   0x42
	Frame Type: Extended Socket Connect.
#define	XBEE_FRAME_SOCK_CLOSE   0x43
	Frame Type: Extended Socket Close.
#define	XBEE_FRAME_SOCK_SEND   0x44
	Frame Type: Extended Socket Send.
#define	XBEE_FRAME_SOCK_SENDTO   0x45
	Frame Type: Extended Socket Sendto.
#define	XBEE_FRAME_SOCK_BIND_LISTEN   0x46
	Frame Type: Extended Socket Bind/Listen.
#define	XBEE_FRAME_SOCK_CREATE_RESP   0xC0
	Frame Type: Extended Socket Create Response.
#define	XBEE_FRAME_SOCK_CONNECT_RESP   0xC2
	Frame Type: Extended Socket Connect Response.
#define	XBEE_FRAME_SOCK_CLOSE_RESP   0xC3
	Frame Type: Extended Socket Close Response.
#define	XBEE_FRAME_SOCK_LISTEN_RESP   0xC6
	Frame Type: Extended Socket Bind/Listen Response.
#define	XBEE_FRAME_SOCK_IPV4_CLIENT   0xCC
	Frame Type: Extended Socket IPv4 Client.
#define	XBEE_FRAME_SOCK_RECEIVE   0xCD
	Frame Type: Extended Socket Receive.
#define	XBEE_FRAME_SOCK_RECEIVE_FROM   0xCE
	Frame Type: Extended Socket Receive From.
#define	XBEE_FRAME_SOCK_STATE   0xCF
	Frame Type: Extended Socket State.
#define	XBEE_SOCK_STR_BUF_SIZE   40
	Buffer size used for xbee_sock_status_str() and xbee_sock_state_str().
#define	debug_printf(...)

Typedefs
typedef int	xbee_sock_t
	Unique identifier for sockets created in this API layer. More...
typedef void(*	xbee_sock_notify_fn) (xbee_sock_t socket, uint8_t frame_type, uint8_t message)
	Callback handler for notification of various socket events. More...
typedef void(*	xbee_sock_receive_fn) (xbee_sock_t socket, uint8_t status, const void *payload, size_t payload_len)
	Callback for data received on sockets created with xbee_sock_connect(). More...
typedef void(*	xbee_sock_receive_from_fn) (xbee_sock_t socket, uint8_t status, uint32_t remote_addr, uint16_t remote_port, const void *datagram, size_t datagram_len)
	Callback for datagrams received on UDP sockets created with xbee_sock_bind(). More...
typedef xbee_sock_receive_fn(*	xbee_sock_ipv4_client_fn) (xbee_sock_t listening_socket, xbee_sock_t client_socket, uint32_t remote_addr, uint16_t remote_port)
	Callback for TCP/SSL sockets created with xbee_sock_listen(). More...
typedef void(*	xbee_sock_option_resp_fn) (xbee_sock_t socket, uint8_t option_id, uint8_t status, const void *data, size_t data_len)
	Callback for responses to Get/Set Option requests sent with xbee_sock_option(). More...

Functions
xbee_sock_t	xbee_sock_create (xbee_dev_t *xbee, uint8_t protocol, xbee_sock_notify_fn notify_handler)
	Allocate a socket from the local socket table, and send a Socket Create frame to the XBee module to allocate space in its socket table. More...
int	xbee_sock_connect (xbee_sock_t socket, uint16_t remote_port, uint32_t remote_addr, const char *remote_host, xbee_sock_receive_fn receive_handler)
	Connect a socket created with xbee_sock_create() to a remote host. More...
int	xbee_sock_bind (xbee_sock_t socket, uint16_t local_port, xbee_sock_receive_from_fn receive_from_handler)
	Bind a UDP socket to a local port to accept datagrams from multiple hosts. More...
int	xbee_sock_listen (xbee_sock_t socket, uint16_t local_port, xbee_sock_ipv4_client_fn ipv4_client_handler)
	Listen on a local port for inbound TCP/SSL connections from multiple hosts. More...
int	xbee_sock_send (xbee_sock_t socket, uint8_t tx_options, const void *payload, size_t payload_len)
	Send data on a Connected socket, or an IPv4 Client socket spawned from a Listening socket. More...
int	xbee_sock_sendto (xbee_sock_t socket, uint8_t tx_options, uint32_t remote_addr, uint16_t remote_port, const void *payload, size_t payload_len)
	Send a datagram on a Bound UDP socket. More...
int	xbee_sock_option (xbee_sock_t socket, uint8_t option_id, const void *data, size_t data_len, xbee_sock_option_resp_fn callback)
	Get or set a socket option. More...
int	xbee_sock_reset (xbee_dev_t *xbee)
	Send command to close all open sockets on device xbee, even if they aren't tracked in the local sockets table. More...
int	xbee_sock_close (xbee_sock_t socket)
	Close and release a socket. More...
int	xbee_sock_close_all (xbee_dev_t *xbee)
	Close all created sockets for a given XBee device. More...
int	xbee_sock_frame_handler (xbee_dev_t *xbee, const void FAR *rawframe, uint16_t length, void FAR *context)
	Frame handler for all response frames. More...
const char *	xbee_sock_status_str (uint8_t status, char buffer[XBEE_SOCK_STR_BUF_SIZE])
	Get a description of an XBEE_SOCK_STATUS_xxx value (returned in multiple socket response frame types) for error messages. More...
const char *	xbee_sock_state_str (uint8_t state, char buffer[XBEE_SOCK_STR_BUF_SIZE])
	Get a description of an XBEE_SOCK_STATE_xxx value (returned in an XBEE_FRAME_SOCK_STATE) for error messages. More...

Detailed Description

Macro Definition Documentation

#define XBEE_SOCK_SOCKET_COUNT   10

Number of sockets to track on the host.

Base on number of simultaneous sockets while considering XBee Cellular device's limits.

Referenced by xbee_sock_close_all(), and xbee_sock_reset().

#define XBEE_SOCK_SOCKET_ID_INVALID   0xFF

The 8-bit Socket ID is never 0xFF, except in Socket Create Response when socket creation wasn't successful.

#define XBEE_SOCK_STATUS_SUCCESS   0x00

Status codes used by multiple socket response frame types.

operation successful

Referenced by xbee_sock_close_all(), and xbee_sock_status_str().

Typedef Documentation

typedef xbee_sock_receive_fn(* xbee_sock_ipv4_client_fn) (xbee_sock_t listening_socket, xbee_sock_t client_socket, uint32_t remote_addr, uint16_t remote_port)

Callback for TCP/SSL sockets created with xbee_sock_listen().

Parameters

[in]	listening_socket	Socket that received the connection.
[in]	client_socket	New socket created for the client connection (acts like an xbee_socket_connect() socket).
[in]	remote_addr	Client's IPv4 address.
[in]	remote_port	Client's TCP/SSL port.

Returns

Handler to use for data received on the new client socket, or NULL to reject the connection and close the socket.

See also

xbee_sock_listen, xbee_sock_receive_fn

typedef void(* xbee_sock_notify_fn) (xbee_sock_t socket, uint8_t frame_type, uint8_t message)

Callback handler for notification of various socket events.

message contains an XBEE_SOCK_STATUS_xxx value for frame_type values:

• XBEE_FRAME_SOCK_CREATE_RESP
• XBEE_FRAME_SOCK_CONNECT_RESP
• XBEE_FRAME_SOCK_CLOSE_RESP
• XBEE_FRAME_SOCK_LISTEN_RESP

message contains an XBEE_TX_DELIVERY_xxx value for frame_type XBEE_FRAME_TX_STATUS

message contains an XBEE_SOCK_STATE_xxx value for frame_type XBEE_FRAME_SOCK_STATE

Parameters

[in]	socket	Socket receiving notification.
[in]	frame_type	XBee frame responsible for the notification.
[in]	message	Status/state delivered. 0x00 always indicates success; meaning of non-zero values varies by value of frame_type.

See also

xbee_sock_create

typedef void(* xbee_sock_option_resp_fn) (xbee_sock_t socket, uint8_t option_id, uint8_t status, const void *data, size_t data_len)

Callback for responses to Get/Set Option requests sent with xbee_sock_option().

Parameters

[in]	socket	Socket of original request.
[in]	option_id	Option ID of original request.
[in]	status	Status of the request. 0x00 indicates SUCCESS, see XBEE_SOCK_STATUS_xxx for other values.
[in]	data	Value of Option ID (for GET) or NULL (for SET).
[in]	data_len	Data length (for GET) or 0 (for SET).

See also

xbee_sock_option

typedef void(* xbee_sock_receive_fn) (xbee_sock_t socket, uint8_t status, const void *payload, size_t payload_len)

Callback for data received on sockets created with xbee_sock_connect().

For UDP sockets, this is a single datagram. For TCP/SSL sockets this is data from the stream. Note that the status bitfield is currently unused.

Parameters

[in]	socket	Socket that received the data.
[in]	status	Status bitfield from Socket Receive frame.
[in]	payload	Received data.
[in]	payload_len	Length of received data, up to 1500 bytes.

See also

xbee_sock_connect, xbee_sock_send, xbee_sock_receive_from_fn

typedef void(* xbee_sock_receive_from_fn) (xbee_sock_t socket, uint8_t status, uint32_t remote_addr, uint16_t remote_port, const void *datagram, size_t datagram_len)

Callback for datagrams received on UDP sockets created with xbee_sock_bind().

Note that the status bitfield is currently unused.

Parameters

[in]	socket	Socket that received the data.
[in]	status	Status bitfield from Socket Receive From frame.
[in]	remote_addr	Remote device's IPv4 address.
[in]	remote_port	Remote device's UDP port.
[in]	datagram	Datagram payload.
[in]	datagram_len	Length of datagram, up to 1500 bytes.

See also

xbee_sock_bind, xbee_sock_sendto, xbee_sock_receive_fn

typedef int xbee_sock_t

Unique identifier for sockets created in this API layer.

Valid IDs are greater than 0, and APIs returning an xbee_sock_t use -Exxx macros to signal errors.

Function Documentation

int xbee_sock_bind	(	xbee_sock_t	socket,
		uint16_t	local_port,
		xbee_sock_receive_from_fn	receive_from_handler
	)

Bind a UDP socket to a local port to accept datagrams from multiple hosts.

Caller must wait for xbee_sock_notify_fn callback with a frame_type of XBEE_FRAME_SOCK_LISTEN_RESP and message of 0 before sending.

Parameters

[in]	socket	Socket ID returned from xbee_sock_create().
[in]	local_port	Port to bind to.
[in]	receive_from_handler	Callback for data received on socket once established. Must be non-NULL.

Return values

0	Sent Socket Bind/Listen frame to XBee module.
-EINVAL	Invalid parameter passed to function.
-ENOENT	Invalid socket ID passed to function.
-EPERM	Socket already connected/bound/listening, or not a UDP socket.
-EBUSY	Transmit serial buffer is full, or XBee is not accepting serial data (deasserting /CTS signal).

See also

xbee_sock_create, xbee_sock_sendto, xbee_sock_receive_from_fn

References EINVAL, socket_t::handler, and socket_t::receive_from.

int xbee_sock_close

(

xbee_sock_t

socket

)

Close and release a socket.

Parameters

[in]

socket

Socket to close.

Return values

0	Sent request to close the socket. socket is no longer valid.
-ENOENT	socket isn't a valid ID
-EBUSY	Transmit serial buffer is full, or XBee is not accepting serial data (deasserting /CTS signal).

See also

xbee_sock_reset, xbee_sock_close_all

int xbee_sock_close_all

(

xbee_dev_t *

xbee

)

Close all created sockets for a given XBee device.

Parameters

[in]

xbee

XBee device for socket closures, or NULL for all sockets.

Return values

0	Socket Close sent for all allocated sockets.
-EBUSY	Transmit serial buffer is full, or XBee is not accepting serial data (deasserting /CTS signal).

See also

xbee_sock_reset, xbee_sock_close

References be16toh, be32toh, socket_t::create_frame_id, EINVAL, ENOENT, EPERM, FAR, socket_t::handler, socket_t::ipv4_client, socket_t::notify_handler, socket_t::option_handler, socket_t::receive, socket_t::receive_from, socket_t::tx_frame_id, socket_t::xbee, XBEE_FRAME_SOCK_CONNECT_RESP, XBEE_FRAME_SOCK_CREATE_RESP, XBEE_FRAME_SOCK_STATE, XBEE_FRAME_TX_STATUS, XBEE_SOCK_SOCKET_COUNT, XBEE_SOCK_SOCKET_TYPE_ATTACH, XBEE_SOCK_SOCKET_TYPE_BIND, XBEE_SOCK_SOCKET_TYPE_CONNECT, XBEE_SOCK_SOCKET_TYPE_CREATED, XBEE_SOCK_SOCKET_TYPE_LISTEN, XBEE_SOCK_SOCKET_TYPE_PENDING, and XBEE_SOCK_STATUS_SUCCESS.

int xbee_sock_connect	(	xbee_sock_t	socket,
		uint16_t	remote_port,
		uint32_t	remote_addr,
		const char *	remote_host,
		xbee_sock_receive_fn	receive_handler
	)

Connect a socket created with xbee_sock_create() to a remote host.

Caller must wait for xbee_sock_notify_fn callback with a frame_type of XBEE_FRAME_SOCK_CONNECT_RESP and message of 0 before sending.

Parameters

[in]	socket	Socket ID returned from xbee_sock_create().
[in]	remote_port	Remote device's port.
[in]	remote_addr	Remote device's address as a 32-bit value (0x01020304 = 1.2.3.4) or zero to make use of /a remote_host.
[in]	remote_host	Remote hostname or a "dotted quad" IPv4 address as a null-terminated string.
[in]	receive_handler	Callback for data received on socket once established. Must be non-NULL.

Return values

0	Sent Socket Connect frame to XBee module.
-EINVAL	Invalid parameter passed to function.
-ENOENT	Invalid socket ID passed to function.
-EPERM	Socket already connected/bound/listening.
-EBUSY	Transmit serial buffer is full, or XBee is not accepting serial data (deasserting /CTS signal).

See also

xbee_sock_create, xbee_sock_send, xbee_sock_receive_fn

References EINVAL, ENOENT, EPERM, socket_t::handler, htobe16, htobe32, socket_t::receive, socket_t::xbee, XBEE_FRAME_SOCK_BIND_LISTEN, XBEE_FRAME_SOCK_CONNECT, xbee_frame_write(), xbee_next_frame_id(), XBEE_SOCK_SOCKET_TYPE_ATTACH, and XBEE_SOCK_SOCKET_TYPE_CREATED.

xbee_sock_t xbee_sock_create	(	xbee_dev_t *	xbee,
		uint8_t	protocol,
		xbee_sock_notify_fn	notify_handler
	)

Allocate a socket from the local socket table, and send a Socket Create frame to the XBee module to allocate space in its socket table.

Socket is PENDING until XBee returns a Socket Create Response.

Parameters

[in]	xbee	XBee device to create socket on
[in]	protocol	one of XBEE_SOCK_PROTOCOL_UDP, _TCP or _SSL
[in]	notify_handler	Callback to receive socket notifications from multiple frame types. Must be non-NULL.

Return values

>0	Socket identifier of newly allocated socket.
-EINVAL	Invalid protocol or NULL notify_handler.
-ENOSPC	Active socket table is full.
-EBUSY	Transmit serial buffer is full, or XBee is not accepting serial data (deasserting /CTS signal).

See also

xbee_sock_notify_fn

References socket_t::create_frame_id, EINVAL, ENOSPC, socket_t::notify_handler, XBEE_FRAME_SOCK_CREATE, xbee_frame_write(), and xbee_next_frame_id().

int xbee_sock_frame_handler	(	xbee_dev_t *	xbee,
		const void FAR *	rawframe,
		uint16_t	length,
		void FAR *	context
	)

Frame handler for all response frames.

View the documentation of xbee_frame_handler_fn() for this function's parameters and return value.

See also

xbee_frame_handler_fn

References XBEE_FRAME_SOCK_CONNECT_RESP, XBEE_FRAME_SOCK_CREATE_RESP, XBEE_FRAME_SOCK_IPV4_CLIENT, XBEE_FRAME_SOCK_LISTEN_RESP, XBEE_FRAME_SOCK_OPTION_RESP, XBEE_FRAME_SOCK_RECEIVE, XBEE_FRAME_SOCK_RECEIVE_FROM, XBEE_FRAME_SOCK_STATE, and XBEE_FRAME_TX_STATUS.

int xbee_sock_listen	(	xbee_sock_t	socket,
		uint16_t	local_port,
		xbee_sock_ipv4_client_fn	ipv4_client_handler
	)

Listen on a local port for inbound TCP/SSL connections from multiple hosts.

Parameters

[in]	socket	Socket ID returned from xbee_sock_create().
[in]	local_port	Port to listen on.
[in]	ipv4_client_handler	Callback for client notifications from listening socket. Must be non-NULL.

Return values

0	Sent Socket Bind/Listen frame to XBee module.
-EINVAL	Invalid parameter passed to function.
-ENOENT	Invalid socket ID passed to function.
-EPERM	Socket already connected/bound/listening, or not a UDP socket.
-EBUSY	Transmit serial buffer is full, or XBee is not accepting serial data (deasserting /CTS signal).

See also

xbee_sock_create, xbee_sock_ipv4_client_fn

References EINVAL, socket_t::handler, and socket_t::ipv4_client.

int xbee_sock_option	(	xbee_sock_t	socket,
		uint8_t	option_id,
		const void *	data,
		size_t	data_len,
		xbee_sock_option_resp_fn	callback
	)

Get or set a socket option.

See XBEE_SOCK_OPT_ID_xxx macros for values of option_id.

Parameters

[in]	socket	Socket to get or set the option on.
[in]	option_id	Option to get or set.
[in]	data	Value to set or NULL to get the current value.
[in]	data_len	Length of data, or 0 if data is NULL.
[in]	callback	Function called with data in Option Response. Only used if retval is 0. Can be NULL to ignore the response.

Return values

0	Sent request to get/set the socket option.
-ENOENT	socket isn't a valid ID
-EPERM	Waiting for Create Response from XBee module.
-EBUSY	Transmit serial buffer is full, or XBee is not accepting serial data (deasserting /CTS signal).

See also

xbee_sock_option_resp_fn

References ENOENT, EPERM, socket_t::notify_handler, socket_t::option_handler, socket_t::xbee, XBEE_FRAME_SOCK_CLOSE, XBEE_FRAME_SOCK_OPTION_REQ, XBEE_FRAME_SOCK_STATE, xbee_frame_write(), xbee_next_frame_id(), and XBEE_SOCK_SOCKET_TYPE_CREATED.

int xbee_sock_reset

(

xbee_dev_t *

xbee

)

Send command to close all open sockets on device xbee, even if they aren't tracked in the local sockets table.

Useful if a previous program left sockets open on the device.

Parameters

[in]

xbee

XBee device for socket closures.

Return values

0	Sent request to close all sockets.
-EBUSY	Transmit serial buffer is full, or XBee is not accepting serial data (deasserting /CTS signal).

See also

xbee_sock_close, xbee_sock_close_all

References socket_t::xbee, and XBEE_SOCK_SOCKET_COUNT.

int xbee_sock_send	(	xbee_sock_t	socket,
		uint8_t	tx_options,
		const void *	payload,
		size_t	payload_len
	)

Send data on a Connected socket, or an IPv4 Client socket spawned from a Listening socket.

This function has a hard limit of 1500 bytes for the payload, and returns -EMSGSIZE for values above 1500. An XBee Cellular module may have a lower limit in some scenarios (e.g., UDP sockets on XBee3 Cellular LTE-M/NBIoT) and will respond with an XBEE_TX_DELIVERY_PAYLOAD_TOO_BIG delivery status (passed to the socket's Notify handler.

Parameters

[in]	socket	Socket ID returned from xbee_sock_create().
[in]	tx_options	Reserved field of Socket Send frame; set to 0.
[in]	payload	Data to send.
[in]	payload_len	Length of data to send (maximum of 1500 bytes).

Return values

0	Sent Socket Send frame to XBee module.
-EINVAL	Invalid parameter passed to function.
-ENOENT	Invalid socket ID passed to function.
-EPERM	Not a Connected socket.
-EBUSY	Transmit serial buffer is full, or XBee is not accepting serial data (deasserting /CTS signal).
-EMSGSIZE	Serial buffer can't hold a frame this large, or payload_len is over 1500 bytes.

See also

xbee_sock_connect, xbee_sock_receive_fn, xbee_sock_sendto

References EMSGSIZE, ENOENT, EPERM, socket_t::tx_frame_id, socket_t::xbee, XBEE_FRAME_SOCK_SEND, xbee_frame_write(), XBEE_IPV4_MAX_PAYLOAD, xbee_next_frame_id(), and XBEE_SOCK_SOCKET_TYPE_CONNECT.

int xbee_sock_sendto	(	xbee_sock_t	socket,
		uint8_t	tx_options,
		uint32_t	remote_addr,
		uint16_t	remote_port,
		const void *	payload,
		size_t	payload_len
	)

Send a datagram on a Bound UDP socket.

This function has a hard limit of 1500 bytes for the payload, and returns -EMSGSIZE for values above 1500. An XBee Cellular module may have a lower limit in some scenarios (e.g., UDP sockets on XBee3 Cellular LTE-M/NBIoT) and will respond with an XBEE_TX_DELIVERY_PAYLOAD_TOO_BIG delivery status (passed to the socket's Notify handler).

Parameters

[in]	socket	Socket ID returned from xbee_sock_create().
[in]	tx_options	Reserved field of Socket SendTo frame; set to 0.
[in]	remote_addr	Remote device's address as a 32-bit value (0x01020304 = 1.2.3.4).
[in]	remote_port	Remote device's port.
[in]	payload	Data to send.
[in]	payload_len	Length of data to send (maximum of 1500 bytes).

Return values

0	Sent Socket Send frame to XBee module.
-EINVAL	Invalid parameter passed to function.
-ENOENT	Invalid socket ID passed to function.
-EPERM	Not a Bound socket.
-EBUSY	Transmit serial buffer is full, or XBee is not accepting serial data (deasserting /CTS signal).
-EMSGSIZE	Serial buffer can't hold a frame this large, or payload_len is over 1500 bytes.

See also

xbee_sock_bind, xbee_sock_receive_from_fn, xbee_sock_send

References EMSGSIZE, ENOENT, EPERM, htobe16, htobe32, socket_t::tx_frame_id, socket_t::xbee, XBEE_FRAME_SOCK_SENDTO, xbee_frame_write(), XBEE_IPV4_MAX_PAYLOAD, xbee_next_frame_id(), and XBEE_SOCK_SOCKET_TYPE_BIND.

const char * xbee_sock_state_str	(	uint8_t	state,
		char	buffer[XBEE_SOCK_STR_BUF_SIZE]
	)

Get a description of an XBEE_SOCK_STATE_xxx value (returned in an XBEE_FRAME_SOCK_STATE) for error messages.

const char * xbee_sock_status_str	(	uint8_t	status,
		char	buffer[XBEE_SOCK_STR_BUF_SIZE]
	)

Get a description of an XBEE_SOCK_STATUS_xxx value (returned in multiple socket response frame types) for error messages.

References XBEE_SOCK_STATUS_BAD_PROTOCOL, XBEE_SOCK_STATUS_BAD_SOCKET, XBEE_SOCK_STATUS_CONNECTED, XBEE_SOCK_STATUS_FAILED_TO_READ, XBEE_SOCK_STATUS_IN_PROGRESS, XBEE_SOCK_STATUS_INTERNAL_ERR, XBEE_SOCK_STATUS_INVALID_PARAM, XBEE_SOCK_STATUS_OFFLINE, XBEE_SOCK_STATUS_RESOURCE_ERR, XBEE_SOCK_STATUS_SUCCESS, and XBEE_SOCK_STATUS_UNKNOWN.