anj_net_api.h File Reference

Platform hooks for network transport integration. More...

#include <anj/init.h>
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include <anj/compat/rng.h>
#include <anj/crypto.h>

Go to the source code of this file.

Data Structures
struct	anj_net_socket_configuration_t
struct	anj_net_psk_info_t
struct	anj_net_certificate_info_t
struct	anj_net_security_info_t
struct	anj_net_ssl_configuration_t
struct	anj_net_config_t

Macros
Network API error codes
Specific error codes recognized by Anjay. Any other generic error must be indicated by a negative value.
#define	ANJ_NET_OK   (0)
#define	ANJ_NET_EAGAIN   (1)
#define	ANJ_NET_EMSGSIZE   (2)
#define	ANJ_NET_ENOTSUP   (3)
#define	ANJ_NET_EINPROGRESS   (4)

Typedefs
typedef struct anj_net_ctx_struct	anj_net_ctx_t
	Opaque network context handle.
typedef int	anj_net_create_ctx_t(anj_net_ctx_t **ctx, const anj_net_config_t *config)
typedef int	anj_net_cleanup_ctx_t(anj_net_ctx_t **ctx)
typedef int	anj_net_connect_t(anj_net_ctx_t *ctx, const char *hostname, const char *port)
typedef int	anj_net_send_t(anj_net_ctx_t *ctx, size_t *bytes_sent, const uint8_t *buf, size_t length)
typedef int	anj_net_recv_t(anj_net_ctx_t *ctx, size_t *bytes_received, uint8_t *buf, size_t length)
typedef int	anj_net_shutdown_t(anj_net_ctx_t *ctx)
typedef int	anj_net_close_t(anj_net_ctx_t *ctx)
typedef int	anj_net_get_state_t(anj_net_ctx_t *ctx, anj_net_socket_state_t *out_value)
typedef int	anj_net_get_inner_mtu_t(anj_net_ctx_t *ctx, int32_t *out_value)
typedef int	anj_net_queue_mode_rx_off_t(anj_net_ctx_t *ctx)

Enumerations
enum	anj_net_binding_type_t {   ANJ_NET_BINDING_UDP = 0 , ANJ_NET_BINDING_TCP , ANJ_NET_BINDING_DTLS , ANJ_NET_BINDING_TLS ,   ANJ_NET_BINDING_NON_IP }
enum	anj_net_socket_state_t { ANJ_NET_SOCKET_STATE_CLOSED , ANJ_NET_SOCKET_STATE_SHUTDOWN , ANJ_NET_SOCKET_STATE_CONNECTED }
enum	anj_net_address_family_setting_t {   ANJ_NET_AF_SETTING_UNSPEC , ANJ_NET_AF_SETTING_FORCE_INET4 , ANJ_NET_AF_SETTING_FORCE_INET6 , ANJ_NET_AF_SETTING_PREFERRED_INET4 ,   ANJ_NET_AF_SETTING_PREFERRED_INET6 }
enum	anj_net_security_mode_t { ANJ_NET_SECURITY_PSK , ANJ_NET_SECURITY_CERTIFICATE }

Functions
static bool	anj_net_is_ok (int res)
	Check if a network operation succeeded.
static bool	anj_net_is_again (int res)
	Check if data was received.
static bool	anj_net_is_inprogress (int res)
	Check if a network operation is in progress.

Detailed Description

Platform hooks for network transport integration.

This header declares the minimal socket-like API that platform integrators must implement to let Anjay Lite communicate over UDP, TCP, DTLS, TLS or some Non-IP transport.

The API covers:

• creating/cleaning up opaque connection contexts
• connecting, sending, receiving, shutting down and closing
• querying state and MTU
• handling Queue Mode RX hints

Security (PSK / certificates) is supported if ANJ_WITH_SECURITY is enabled. The functions are designed to be non-blocking, with retry signaled by returning ANJ_NET_EINPROGRESS.

Implementations typically wrap system sockets, modem AT command layers, or RTOS/BSP networking stacks.

Macro Definition Documentation

ANJ_NET_EAGAIN

#define ANJ_NET_EAGAIN   (1)

A code indicating that no data is currently available to be received. The caller should retry the function with the same parameters. This does not need to occur immediately, other operations might be executed first.

ANJ_NET_EINPROGRESS

#define ANJ_NET_EINPROGRESS   (4)

A code indicating that the operation cannot be performed immediately. This may occur when the underlying operation is still in progress (e.g., ongoing communication with a cellular modem). To properly complete the operation, the caller must retry the function with the same parameters.

ANJ_NET_EMSGSIZE

#define ANJ_NET_EMSGSIZE   (2)

Message too long.

ANJ_NET_ENOTSUP

#define ANJ_NET_ENOTSUP   (3)

Operation not supported. This indicates that the function is either not implemented or that the provided arguments are not supported.

ANJ_NET_OK

#define ANJ_NET_OK   (0)

Error code indicating success.

Typedef Documentation

anj_net_cleanup_ctx_t

typedef int anj_net_cleanup_ctx_t(anj_net_ctx_t **ctx)

Calls shutdown on the connection associated with ctx, cleans up the ctx context, and sets it to NULL.

Note

This function does not block.

Parameters

[in,out]

ctx

Connection context to clean up.

Returns

ANJ_NET_OK on success. ANJ_NET_EINPROGRESS Other non-zero value in case of other errors.

anj_net_close_t

typedef int anj_net_close_t(anj_net_ctx_t *ctx)

Shuts down the connection associated with ctx. No further communication is allowed using this context. Discards any buffered but not yet processed data.

ctx may later be reused by calling anj_net_connect again.

Note

This function does not block.

Parameters

ctx	Communication context to close.

Returns

ANJ_NET_OK on success. ANJ_NET_EINPROGRESS Other non-zero value in case of other errors.

anj_net_connect_t

typedef int anj_net_connect_t(anj_net_ctx_t *ctx, const char *hostname, const char *port)

This function connects to a server specified by the hostname and port parameters. If the specific binding being used does not require these parameters, the user should pass NULL instead.

Warning

The function is allowed to block during the connection attempt or return immediately with ANJ_NET_EINPROGRESS. The behavior of the function in blocking or non-blocking mode will not be enforced, allowing flexibility in implementation.

Parameters

ctx	Pointer to a socket context.
hostname	Target host name to connect to.
port	Target port of the server.

Returns

ANJ_NET_OK on success. ANJ_NET_EINPROGRESS Other non-zero value in case of an error.

anj_net_create_ctx_t

typedef int anj_net_create_ctx_t(anj_net_ctx_t **ctx, const anj_net_config_t *config)

Initializes a communication context for a connection.

If a valid config pointer is supplied, it is used to configure the context; otherwise, a NULL pointer is acceptable.

Note

This function does not block.

Parameters

[out]	ctx	Created socket context.
	config	Optional configuration for initializing the socket context.

Returns

ANJ_NET_OK on success. Other non-zero value in case of other errors.

anj_net_ctx_t

typedef struct anj_net_ctx_struct anj_net_ctx_t

Opaque network context handle.

This type represents a network context object used internally by the networking layer. Its definition is intentionally hidden and implementation- specific. Applications should only work with pointers to anj_net_ctx_t obtained from API functions such as anj_net_create_ctx, and never attempt to access or modify its contents directly.

On the implementation side, anj_net_ctx_t is cast to a backend-specific structure.

anj_net_get_inner_mtu_t

typedef int anj_net_get_inner_mtu_t(anj_net_ctx_t *ctx, int32_t *out_value)

Returns the maximum size of a buffer that can be passed to anj_net_send and transmitted as a single packet.

Note

This function does not block.

Parameters

	ctx	Pointer to a socket context.
[out]	out_value	Retrieved option value.

Returns

ANJ_NET_OK on success. Other non-zero value in case of other errors.

anj_net_get_state_t

typedef int anj_net_get_state_t(anj_net_ctx_t *ctx, anj_net_socket_state_t *out_value)

Returns the current state of the socket context.

Note

This function does not block.

Parameters

	ctx	Pointer to a socket context.
[out]	out_value	Retrieved option value.

Returns

ANJ_NET_OK on success. Other non-zero value in case of other errors.

anj_net_queue_mode_rx_off_t

typedef int anj_net_queue_mode_rx_off_t(anj_net_ctx_t *ctx)

Hints the transport that the client is entering LwM2M Queue Mode and will not need to receive application data until it initiates the next outgoing exchange. Implementations may use this to reduce power consumption (e.g., disable RX path / radio) while keeping the connection context valid.

Note

This function does not block.

Requirements:

• Must not invalidate ctx. Subsequent calls to anj_net_send / anj_net_recv and others must still be possible.
• Should be idempotent: calling it multiple times is allowed.
• Net compat implementation must implicitly re-enable RX whenever a subsequent net API call may require inbound traffic (e.g., anj_net_connect, anj_net_send, anj_net_recv, and anj_net_close / anj_net_shutdown for TCP/TLS).
• Once RX is re-enabled, it remains enabled for the connection until anj_net_queue_mode_rx_off_t is called again.

Non-blocking semantics:

• If disabling RX requires asynchronous work (e.g., modem operations), return ANJ_NET_EINPROGRESS and complete the operation on subsequent calls.

Parameters

ctx	Pointer to a transport context.

Returns

ANJ_NET_OK if RX successfully disabled, or not applicable (no-op). ANJ_NET_EINPROGRESS Other non-zero value in case of other errors.

anj_net_recv_t

typedef int anj_net_recv_t(anj_net_ctx_t *ctx, size_t *bytes_received, uint8_t *buf, size_t length)

This function receives data from the specified connection context. If data is available, it is stored in the provided buffer, and bytes_received indicates the number of bytes received.

Note

This function does not block.

Parameters

	ctx	Pointer to a socket context.
[out]	bytes_received	Output parameter indicating the number of bytes received.
[out]	buf	Pointer to the message buffer.
	length	Size of the provided buffer.

Returns

ANJ_NET_OK if data was received successfully. ANJ_NET_EAGAIN ANJ_NET_EMSGSIZE if the provided buffer is too small. ANJ_NET_EINPROGRESS Other non-zero value in case of other errors.

anj_net_send_t

typedef int anj_net_send_t(anj_net_ctx_t *ctx, size_t *bytes_sent, const uint8_t *buf, size_t length)

This function sends the provided data through the given connection context.

If no data has been sent, the function returns ANJ_NET_EINPROGRESS. However, if some (all) data has been successfully sent, the function returns ANJ_NET_OK, and bytes_sent will indicate the amount of data transmitted. The caller should then retry the operation with the remaining data until all bytes are sent.

Note

This function does not block.

Parameters

	ctx	Pointer to a socket context.
[out]	bytes_sent	Number of bytes sent.
	buf	Pointer to the message buffer.
	length	Length of the data in the message buffer.

Returns

ANJ_NET_OK if all data was sent or partial data was sent successfully. ANJ_NET_EINPROGRESS Other non-zero value in case of an error.

anj_net_shutdown_t

typedef int anj_net_shutdown_t(anj_net_ctx_t *ctx)

Shuts down the connection associated with ctx. No further communication is allowed using this context. Any buffered but not yet processed data should still be delivered. Performs the termination handshake if the protocol used requires one.

Data already received can still be read using anj_net_recv. However, the user must call anj_net_close before reusing the context.

Note

This function does not block.

Parameters

ctx	Communication context to shut down.

Returns

ANJ_NET_OK on success. ANJ_NET_EINPROGRESS Other non-zero value in case of an error.

Enumeration Type Documentation

anj_net_address_family_setting_t

enum anj_net_address_family_setting_t

Address family preference when creating a network socket.

Enumerator
ANJ_NET_AF_SETTING_UNSPEC	No preference specified. The actual address family is chosen by the implementation.
ANJ_NET_AF_SETTING_FORCE_INET4	Force IPv4. Only IPv4 addresses will be supported.
ANJ_NET_AF_SETTING_FORCE_INET6	Force IPv6. Only IPv6 addresses will be supported.
ANJ_NET_AF_SETTING_PREFERRED_INET4	Prefer IPv4, but allow IPv6. The final choice depends on address resolution and system behavior.
ANJ_NET_AF_SETTING_PREFERRED_INET6	Prefer IPv6, but allow IPv4. The final choice depends on address resolution and system behavior.

anj_net_binding_type_t

enum anj_net_binding_type_t

Enumerator
ANJ_NET_BINDING_UDP
ANJ_NET_BINDING_TCP
ANJ_NET_BINDING_DTLS
ANJ_NET_BINDING_TLS
ANJ_NET_BINDING_NON_IP

anj_net_security_mode_t

enum anj_net_security_mode_t

Enumerator
ANJ_NET_SECURITY_PSK
ANJ_NET_SECURITY_CERTIFICATE

anj_net_socket_state_t

enum anj_net_socket_state_t

Enumerator
ANJ_NET_SOCKET_STATE_CLOSED	Socket is either newly constructed, or it has been closed by calling anj_net_close.
ANJ_NET_SOCKET_STATE_SHUTDOWN	Socket was previously in ANJ_NET_SOCKET_STATE_CONNECTED state, and anj_net_shutdown was called.
ANJ_NET_SOCKET_STATE_CONNECTED	anj_net_connect has been called. The socket is connected to some specific server. It is ready for anj_net_send and anj_net_recv operations.

Function Documentation

anj_net_is_again()

static bool anj_net_is_again ( int  res )

inlinestatic

Check if data was received.

Convenience function that tests whether the result code of a network operation equals ANJ_NET_EAGAIN.

Parameters

res	Result code returned by a networking API call.

Returns

true if res equals ANJ_NET_EAGAIN, false otherwise.

anj_net_is_inprogress()

static bool anj_net_is_inprogress ( int  res )

inlinestatic

Check if a network operation is in progress.

Convenience function that tests whether the result code of a network operation equals ANJ_NET_EINPROGRESS.

This indicates thst the operation requires a repeated call, without any other anj_net_* calls being performed in between.

Parameters

res	Result code returned by a networking API call.

Returns

true if res indicates a retryable condition, false otherwise.

anj_net_is_ok()

static bool anj_net_is_ok ( int  res )

inlinestatic

Check if a network operation succeeded.

Convenience function that tests whether the result code of a network operation equals ANJ_NET_OK.

Parameters

res	Result code returned by a networking API call.

Returns

true if res indicates success, false otherwise.