anj_net_api.h File Reference

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

Go to the source code of this file.

Data Structures
struct	anj_net_socket_configuration_t
struct	anj_net_config_t

Macros
#define	ANJ_NET_OK   (0)
#define	ANJ_NET_EAGAIN   (1)
#define	ANJ_NET_EMSGSIZE   (2)
#define	ANJ_NET_ENOTSUP   (3)

Typedefs
typedef struct anj_net_ctx_struct	anj_net_ctx_t
typedef const void *	anj_net_get_system_socket_t(anj_net_ctx_t *ctx)
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_reuse_last_port_t(anj_net_ctx_t *ctx)
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_get_bytes_sent_t(anj_net_ctx_t *ctx, uint64_t *out_value)
typedef int	anj_net_get_bytes_received_t(anj_net_ctx_t *ctx, uint64_t *out_value)

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_BOUND , 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 }

Functions
static bool	anj_net_is_ok (int res)
static bool	anj_net_is_again (int res)

Macro Definition Documentation

ANJ_NET_EAGAIN

#define ANJ_NET_EAGAIN   (1)

Error code indicating that the operation would block. The caller should 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)

A list of specific error codes recognized by Anjay. Any other generic error must be indicated by a negative value. 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.

If the function returns ANJ_NET_EAGAIN, a subsequent call with the same arguments resumes the operation. Note that such a call may not occur immediately, as other operations may be performed first depending on internal scheduling.

Parameters

[in,out]

ctx

Connection context to clean up.

Returns

ANJ_NET_OK on success. ANJ_NET_EAGAIN if function would block. A negative value in case of an error.

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.

If the function returns ANJ_NET_EAGAIN, a subsequent call with the same arguments resumes the operation. Note that such a call may not occur immediately, as other operations may be performed first depending on internal scheduling.

ctx may later be reused by calling anj_net_connect again.

Parameters

ctx	Communication context to close.

Returns

ANJ_NET_OK on success. ANJ_NET_EAGAIN if function would block. A negative value in case of an error.

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.

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

If the function returns ANJ_NET_EAGAIN, a subsequent call with the same arguments resumes the operation. Note that such a call may not occur immediately, as other operations may be performed first depending on internal scheduling.

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_EAGAIN if function would block. A negative 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.

This function never returns ANJ_NET_EAGAIN.

Parameters

ctx	Output parameter to store the created socket context.
config	Optional configuration for initializing the socket context.

Returns

ANJ_NET_OK on success, or a negative value in case of an error.

anj_net_ctx_t

typedef struct anj_net_ctx_struct anj_net_ctx_t

anj_net_get_bytes_received_t

typedef int anj_net_get_bytes_received_t(anj_net_ctx_t *ctx, uint64_t *out_value)

Returns the number of bytes received. Does not include protocol overhead.

Parameters

ctx	Pointer to a socket context.
out_value	Variable to store the retrieved option value.

Returns

ANJ_NET_OK on success, or a negative value in case of an error.

anj_net_get_bytes_sent_t

typedef int anj_net_get_bytes_sent_t(anj_net_ctx_t *ctx, uint64_t *out_value)

Returns the number of bytes sent. Does not include protocol overhead.

Parameters

ctx	Pointer to a socket context.
out_value	Variable to store the retrieved option value.

Returns

ANJ_NET_OK on success, or a negative value in case of an error.

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.

Parameters

ctx	Pointer to a socket context.
out_value	Variable to store retrieved option value in.

Returns

ANJ_NET_OK on success, or a negative value in case of an error.

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.

Parameters

ctx	Pointer to a socket context.
out_value	Variable to store the retrieved option value.

Returns

ANJ_NET_OK on success, or a negative value in case of an error.

anj_net_get_system_socket_t

typedef const void * anj_net_get_system_socket_t(anj_net_ctx_t *ctx)

Returns a pointer to the underlying system socket (e.g., for use with functions like select or poll).

Although Anjay does not call this function directly, it may be useful for the end user. The caller should be aware of the system socket type and cast it appropriately.

If the system socket is not yet available or is invalid, this function returns NULL.

const int *sock_fd = (const int*) anj_net_get_system_socket_t(ctx);
struct pollfd pfd;
pfd.fd = *sock_fd;
pfd.events = POLLIN;
 
int ret = poll(&pfd, 1, timeout);

Parameters

ctx	Pointer to the socket context.

Returns

A pointer to the system socket on success, or NULL in case of an error.

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.

If the operation would block and no data has been received, the function returns ANJ_NET_EAGAIN. If the provided buffer is too small to hold the full message, the function returns ANJ_NET_EMSGSIZE.

If the function returns ANJ_NET_EAGAIN, a subsequent call with the same arguments resumes the operation. Note that such a call may not occur immediately, as other operations may be performed first depending on internal scheduling.

NOTE: This function does not block.

Parameters

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

Returns

ANJ_NET_OK on success. ANJ_NET_EAGAIN if no data was received or the operation would block. ANJ_NET_EMSGSIZE if the provided buffer is too small. Negative value in case of other errors.

anj_net_reuse_last_port_t

typedef int anj_net_reuse_last_port_t(anj_net_ctx_t *ctx)

Binds a socket associated with ctx to the previous port number used by this context.

If bind operation is not supported the function returns ANJ_NET_ENOTSUP.

If the function returns ANJ_NET_EAGAIN, a subsequent call with the same arguments resumes the operation. Note that such a call may not occur immediately, as other operations may be performed first depending on internal scheduling.

Parameters

ctx	Pointer to a socket context.

Returns

ANJ_NET_OK on success. ANJ_NET_EAGAIN if function would block. A negative value in case of an error.

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 the operation would block and no data has been sent, the function returns ANJ_NET_EAGAIN. However, if all or partial 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.

If the function returns ANJ_NET_EAGAIN, a subsequent call with the same arguments resumes the operation. Note that such a call may not occur immediately, as other operations may be performed first depending on internal scheduling.

NOTE: This function does not block.

Parameters

ctx	Pointer to a socket context.
bytes_sent	Output parameter indicating the 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_EAGAIN if no data was sent and the operation would block. A negative 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.

If the function returns ANJ_NET_EAGAIN, a subsequent call with the same arguments resumes the operation. Note that such a call may not occur immediately, as other operations may be performed first depending on internal scheduling.

Parameters

ctx	Communication context to shut down.

Returns

ANJ_NET_OK on success. ANJ_NET_EAGAIN if function would block. A negative value in case of an error.

Enumeration Type Documentation

anj_net_address_family_setting_t

enum anj_net_address_family_setting_t

Enumerator
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

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_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 either BOUND or CONNECTED state, but anj_net_shutdown was called.
ANJ_NET_SOCKET_STATE_BOUND	anj_net_reuse_last_port_t has been called. The socket is associated with some port.
ANJ_NET_SOCKET_STATE_CONNECTED	anj_net_connect has been called. The socket is connected to some concrete 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

anj_net_is_ok()

static bool anj_net_is_ok ( int  res )

inlinestatic