coap_downloader.h File Reference

API for downloading resources over CoAP/CoAPs. More...

#include <anj/init.h>
#include <anj/compat/net/anj_net_api.h>
#include <anj/defs.h>

Go to the source code of this file.

Data Structures
struct	anj_coap_downloader_configuration_struct

Macros
#define	ANJ_COAP_DOWNLOADER_H
#define	ANJ_COAP_DOWNLOADER_ERR_INVALID_URI   -1
#define	ANJ_COAP_DOWNLOADER_ERR_IN_PROGRESS   -2
#define	ANJ_COAP_DOWNLOADER_ERR_INVALID_CONFIGURATION   -3
#define	ANJ_COAP_DOWNLOADER_ERR_TERMINATED   -4
#define	ANJ_COAP_DOWNLOADER_ERR_NETWORK   -5
#define	ANJ_COAP_DOWNLOADER_ERR_INVALID_RESPONSE   -6
#define	ANJ_COAP_DOWNLOADER_ERR_TIMEOUT   -7
#define	ANJ_COAP_DOWNLOADER_ERR_INTERNAL   -8
#define	ANJ_COAP_DOWNLOADER_ERR_ETAG_MISMATCH   -9

Typedefs
typedef void	anj_coap_downloader_event_callback_t(void *arg, anj_coap_downloader_t *coap_downloader, anj_coap_downloader_status_t conn_status, const uint8_t *data, size_t data_len)
typedef struct anj_coap_downloader_configuration_struct	anj_coap_downloader_configuration_t

Enumerations
enum	anj_coap_downloader_status_t {   ANJ_COAP_DOWNLOADER_STATUS_INITIAL , ANJ_COAP_DOWNLOADER_STATUS_STARTING , ANJ_COAP_DOWNLOADER_STATUS_DOWNLOADING , ANJ_COAP_DOWNLOADER_STATUS_FINISHING ,   ANJ_COAP_DOWNLOADER_STATUS_FINISHED , ANJ_COAP_DOWNLOADER_STATUS_FAILED }

Functions
int	anj_coap_downloader_init (anj_coap_downloader_t *coap_downloader, const anj_coap_downloader_configuration_t *config)
void	anj_coap_downloader_step (anj_coap_downloader_t *coap_downloader)
int	anj_coap_downloader_start (anj_coap_downloader_t *coap_downloader, const char *uri, const anj_net_config_t *net_config)
void	anj_coap_downloader_terminate (anj_coap_downloader_t *coap_downloader)
int	anj_coap_downloader_get_error (anj_coap_downloader_t *coap_downloader)

Detailed Description

API for downloading resources over CoAP/CoAPs.

Provides a state machine—driven downloader that fetches resources via CoAP. Applications configure it with callbacks, start a download from a URI, and step it regularly in the main loop. Supports error reporting, termination, and secure transport when enabled.

Macro Definition Documentation

ANJ_COAP_DOWNLOADER_H

#define ANJ_COAP_DOWNLOADER_H

Typedef Documentation

anj_coap_downloader_configuration_t

typedef struct anj_coap_downloader_configuration_struct anj_coap_downloader_configuration_t

CoAP downloader configuration structure. Should be filled before passing to anj_coap_downloader_init.

anj_coap_downloader_event_callback_t

typedef void anj_coap_downloader_event_callback_t(void *arg, anj_coap_downloader_t *coap_downloader, anj_coap_downloader_status_t conn_status, const uint8_t *data, size_t data_len)

Callback type for CoAP downloader events.

This callback is invoked whenever the CoAP downloader reports a new event, such as a status change or the reception of a data packet.

When the status is ANJ_COAP_DOWNLOADER_STATUS_DOWNLOADING, the callback will also provide the received data chunk. For all other statuses, data will be NULL and data_len will be 0.

Parameters

arg	Opaque user argument passed to the callback.
coap_downloader	CoAP downloader object reporting the status change.
conn_status	Current connection status value; see anj_coap_downloader_status_t.
data	Pointer to the received data, if applicable.
data_len	Length of the received data, if applicable.

Enumeration Type Documentation

anj_coap_downloader_status_t

enum anj_coap_downloader_status_t

This enum represents the possible states of a CoAP Downloader module.

Enumerator
ANJ_COAP_DOWNLOADER_STATUS_INITIAL	Initial state of the module after startup. Start new download by calling anj_coap_downloader_start.
ANJ_COAP_DOWNLOADER_STATUS_STARTING	A new connection to the server is being established. The download will begin once the connection is ready.
ANJ_COAP_DOWNLOADER_STATUS_DOWNLOADING	A new chunk of data is being downloaded. This status will be reported via callback for each received packet.
ANJ_COAP_DOWNLOADER_STATUS_FINISHING	Last packet has been received or error occurred. Connection is being closed.
ANJ_COAP_DOWNLOADER_STATUS_FINISHED	The download process has finished successfully. The last packet has been received and the connection has been closed.
ANJ_COAP_DOWNLOADER_STATUS_FAILED	The download process has finished due to an error. The failure may be caused by a network issue, invalid server response, or another unexpected condition. Call anj_coap_downloader_get_error to retrieve error details.

Function Documentation

anj_coap_downloader_get_error()

int anj_coap_downloader_get_error

(

anj_coap_downloader_t *

coap_downloader

)

Retrieves the error code from the last failed download operation.

This function must be called only when the downloader's status is ANJ_COAP_DOWNLOADER_STATUS_FAILED. It returns a negative error code indicating the reason for the failure. The behavior is undefined if this function is called in any other state.

Parameters

coap_downloader

CoAP downloader state.

Returns

Error code indicating the reason for the failure. For possible return values, see CoAP downloader error codes.

anj_coap_downloader_init()

int anj_coap_downloader_init	(	anj_coap_downloader_t *	coap_downloader,
		const anj_coap_downloader_configuration_t *	config
	)

Initializes CoAP downloader internal state variable.

Parameters

coap_downloader	Pointer to a variable that will hold the state of CoAP downloader.
config	Configuration structure for the CoAP downloader. Object pointed to by this pointer can be freed after this function returns, as it is copied internally.

Returns

0 on success, a non-zero value in case of an error.

anj_coap_downloader_start()

int anj_coap_downloader_start	(	anj_coap_downloader_t *	coap_downloader,
		const char *	uri,
		const anj_net_config_t *	net_config
	)

Starts a new download operation.

Warning

The URI is not copied or stored internally by the CoAP downloader, so the pointer must remain valid throughout the entire download process.

Parameters

coap_downloader	CoAP downloader state.
uri	URI of the resource to download. The string must be null-terminated.
net_config	Optional network configuration to use for the connection. Can be NULL for non-secure CoAP. Object pointed to by this pointer can be freed after this function returns, as it is copied internally.

Returns

0 on success, ANJ_COAP_DOWNLOADER_ERR_INVALID_URI if the provided URI is invalid or unsupported. ANJ_COAP_DOWNLOADER_ERR_IN_PROGRESS if a download is already in progress. ANJ_COAP_DOWNLOADER_ERR_INVALID_CONFIGURATION if provided net_config is NULL while uri indicates secure CoAP.

anj_coap_downloader_step()

void anj_coap_downloader_step

(

anj_coap_downloader_t *

coap_downloader

)

Main step function of the Anjay Lite CoAP downloader module.

This function should be called regularly in the main application loop. It drives the internal state machine and handles all scheduled operations related to downloading data via CoAP.

This function is non-blocking, unless a custom network implementation introduces blocking behavior.

Parameters

coap_downloader

CoAP downloader state.

anj_coap_downloader_terminate()

void anj_coap_downloader_terminate

(

anj_coap_downloader_t *

coap_downloader

)

Terminates the current download operation and cleans up the CoAP downloader.

This function should be called when the download is no longer needed or when an error condition requires aborting the transfer. It has effect only when the downloader is in the ANJ_COAP_DOWNLOADER_STATUS_STARTING or ANJ_COAP_DOWNLOADER_STATUS_DOWNLOADING state. If called in any other state, the function has no effect.

After calling this function, the downloader's status will be set to ANJ_COAP_DOWNLOADER_STATUS_FINISHING, and anj_coap_downloader_get_error will return ANJ_COAP_DOWNLOADER_ERR_TERMINATED.

Subsequent calls to anj_coap_downloader_step will complete the termination sequence by closing the CoAP exchange and terminating the connection. Once finished, the final status will be ANJ_COAP_DOWNLOADER_STATUS_FAILED.

Parameters

coap_downloader

CoAP downloader state.