#include <stddef.h>
#include <stdint.h>
#include <avsystem/commons/avs_net.h>
#include <anjay/anjay_config.h>
#include <anjay/core.h>

Data Structures
struct	anjay_etag

struct	anjay_download_status_t

struct	anjay_download_config

Typedefs
typedef struct anjay_etag	anjay_etag_t

typedef avs_error_t	anjay_download_next_block_handler_t(anjay_t anjay, const uint8_t data, size_t data_size, const anjay_etag_t etag, void user_data)

typedef enum anjay_download_result	anjay_download_result_t

typedef void	anjay_download_finished_handler_t(anjay_t anjay, anjay_download_status_t status, void user_data)

typedef struct anjay_download_config	anjay_download_config_t

typedef void *	anjay_download_handle_t

Enumerations
enum	anjay_download_result { ANJAY_DOWNLOAD_FINISHED , ANJAY_DOWNLOAD_ERR_FAILED , ANJAY_DOWNLOAD_ERR_INVALID_RESPONSE , ANJAY_DOWNLOAD_ERR_EXPIRED , ANJAY_DOWNLOAD_ERR_ABORTED }

Functions
anjay_etag_t *	anjay_etag_new (uint8_t etag_size)

anjay_etag_t *	anjay_etag_clone (const anjay_etag_t *old_etag)

avs_error_t	anjay_download (anjay_t anjay, const anjay_download_config_t config, anjay_download_handle_t *out_handle)

avs_error_t	anjay_download_set_next_block_offset (anjay_t *anjay, anjay_download_handle_t dl_handle, size_t next_block_offset)

void	anjay_download_abort (anjay_t *anjay, anjay_download_handle_t dl_handle)

void	anjay_download_suspend (anjay_t *anjay, anjay_download_handle_t dl_handle)

int	anjay_download_reconnect (anjay_t *anjay, anjay_download_handle_t dl_handle)

Typedef Documentation

◆ anjay_download_config_t

typedef struct anjay_download_config anjay_download_config_t

◆ anjay_download_finished_handler_t

typedef void anjay_download_finished_handler_t(anjay_t *anjay, anjay_download_status_t status, void *user_data)

Called whenever the download finishes, successfully or not.

Parameters

anjay	Anjay object managing the download process.
status	Status of the download, with additional error information if applicable.
user_data	Value of anjay_download_config_t::user_data passed to anjay_download .

◆ anjay_download_handle_t

typedef void* anjay_download_handle_t

◆ anjay_download_next_block_handler_t

typedef avs_error_t anjay_download_next_block_handler_t(anjay_t *anjay, const uint8_t *data, size_t data_size, const anjay_etag_t *etag, void *user_data)

Called each time a chunk of data is received from remote host. It is guaranteed to be called with consecutive chunks of data, starting from anjay_download_config_t::start_offset.

Parameters

anjay	Anjay object managing the download process.
data	Received data.
data_size	Number of bytes available in `data` .
etag	ETag option sent by the server. Should be saved if the client may need to resume the transfer after it gets interrupted.
user_data	Value of anjay_download_config_t::user_data passed to anjay_download .

Returns

Should return:

AVS_OK on success,
an error value if an error occurred, in which case the download will be terminated with ANJAY_DOWNLOAD_ERR_FAILED result.

◆ anjay_download_result_t

typedef enum anjay_download_result anjay_download_result_t

◆ anjay_etag_t

typedef struct anjay_etag anjay_etag_t

CoAP Entity Tag.

Enumeration Type Documentation

◆ anjay_download_result

enum anjay_download_result

Enumerator
ANJAY_DOWNLOAD_FINISHED	Download finished successfully.
ANJAY_DOWNLOAD_ERR_FAILED	Download failed due to a local failure or a network error.
ANJAY_DOWNLOAD_ERR_INVALID_RESPONSE	The remote server responded in a way that is permitted by the protocol, but does not indicate a success (e.g. a 4xx or 5xx HTTP status).
ANJAY_DOWNLOAD_ERR_EXPIRED	Downloaded resource changed while transfer was in progress.
ANJAY_DOWNLOAD_ERR_ABORTED	Download was aborted by calling anjay_download_abort .

Function Documentation

◆ anjay_download()

avs_error_t anjay_download	(	anjay_t *	anjay,
		const anjay_download_config_t *	config,
		anjay_download_handle_t *	out_handle
	)

Requests asynchronous download of an external resource.

Download will create a new socket that will be later included in the list returned by anjay_get_sockets . Calling anjay_serve on such socket may cause calling anjay_download_config_t::on_next_block if received packet is the next expected chunk of downloaded data and anjay_download_finished_handler_t if the transfer completes or fails. Request packet retransmissions are managed by Anjay scheduler, and sent by anjay_sched_run whenever required.

No network activity is performed immediately during the call to anjay_download(). Instead, the TCP and/or (D)TLS handshakes and the first request packet, will be sent during subsequent calls to anjay_sched_run. This also means that you can create a postponed download by calling anjay_download_suspend immediately afterwards.

Parameters

anjay	Anjay object that will manage the download process.
config	Download configuration.
out_handle	Pointer to a variable that will be set to a download handle, that may be used for aborting the download. MUST NOT be NULL.

Returns

AVS_OK on success, in which case *out_handle is set to a handle to the created download,
Code of the error that happened, in which case *out_handle is not modified, and anjay_download_config_t::on_download_finished handler is NOT called.

◆ anjay_download_abort()

void anjay_download_abort	(	anjay_t *	anjay,
		anjay_download_handle_t	dl_handle
	)

Aborts a download identified by dl_handle. Does nothing if dl_handle does not represent a valid download handle.

Parameters

anjay	Anjay object managing the download process.
dl_handle	Download handle previously returned by anjay_download.

◆ anjay_download_reconnect()

int anjay_download_reconnect	(	anjay_t *	anjay,
		anjay_download_handle_t	dl_handle
	)

Reconnects a download identified by dl_handle while retaining the download progress.

If the download has been previously suspended using anjay_download_suspend, it will be resumed. If the download is suspended due to the transport being offline (see anjay_transport_set_online), no immediate action is performed, but the suspended state as per anjay_download_suspend will be cleared.

This function only schedules the actual reconnect operation. The socket will be actually reconnected during subsequent calls to anjay_sched_run.

Parameters

anjay	Anjay object managing the download process.
dl_handle	Download handle previously returned by anjay_download.

Returns: 0 for success; -1 if dl_handle does not represent a valid download handle, or if the reconnect job could not be scheduled (e.g. due to an out-of-memory condition).

◆ anjay_download_set_next_block_offset()

avs_error_t anjay_download_set_next_block_offset	(	anjay_t *	anjay,
		anjay_download_handle_t	dl_handle,
		size_t	next_block_offset
	)

Changes the offset of the remote resource that the user wants to receive the next response data block from.

This function is only intended to be called from within an implementation of anjay_download_next_block_handler_t.

The offset can only be moved forward relative to the last known starting offset. Attempting to set it to an offset of byte that was already received in a previously finished call to anjay_download_next_block_handler_t, or is smaller than an offset already passed to this function, will result in an error.

When called from within anjay_download_next_block_handler_t, next_block_offset may be set to a position that lies after or within the data buffer passed to it (but further than the current offset). If a position within the buffer is passed, the block handler will be called again with a portion of the same buffer, starting at the desired offset.

If this function is never called during a call to anjay_download_next_block_handler_t, the file pointer is implicitly moved by the whole size of the buffer passed to it.

It is guaranteed that if there will be a next call to anjay_download_next_block_handler_t for the given download, it will be passed data from the specified offset.

NOTE: Actual efficient skipping of already downloaded data is currently only supported for CoAP. Using this function with HTTP downloads will only suppress passing the skipped data; full file will still be transmitted over the network.

Parameters

anjay	Anjay object managing the download process.
dl_handle	Download handle previously returned by anjay_download.
next_block_offset	Block offset to set.

Returns

AVS_OK for success
avs_errno(AVS_ENOENT) if dl_handle does not refer to an existing download process
avs_errno(AVS_EINVAL) if next_block_offset is smaller than the currently recognized value
avs_errno(AVS_ENOTSUP) if Anjay has been compiled without support for downloads

◆ anjay_download_suspend()

void anjay_download_suspend	(	anjay_t *	anjay,
		anjay_download_handle_t	dl_handle
	)

Suspends a download identified by dl_handle. Does nothing if dl_handle does not represent a valid download handle.

The suspend operation is performed immediately and synchronously. The socket is disconnected, but the rest of the download context is kept intact. The download can be resumed by calling anjay_download_reconnect.

If the download is already suspended due to the transport being offline (see anjay_transport_set_online), no immediate action is performed, but the download is marked in such a way that it will not be automatically resumed until an explicit call to anjay_download_reconnect.

Parameters

anjay	Anjay object managing the download process.
dl_handle	Download handle previously returned by anjay_download.

◆ anjay_etag_clone()

anjay_etag_t * anjay_etag_clone ( const anjay_etag_t * old_etag )

Given one ETag, creates a new one, with the same size and value. The new ETag can be freed using avs_free.

Parameters

old_etag Pointer to old ETag copy

Returns: Pointer to created ETag copy, NULL on failure

◆ anjay_etag_new()

anjay_etag_t * anjay_etag_new ( uint8_t etag_size )

Allocates ETag with a given size. The new ETag can be freed using avs_free.

Parameters

etag_size The number of bytes to be available in the returned anjay_etag_t::value array.

Returns: Pointer to created ETag, NULL on failure

Data Structures

Typedefs

Enumerations

Functions

Typedef Documentation

◆ anjay_download_config_t

◆ anjay_download_finished_handler_t

◆ anjay_download_handle_t

◆ anjay_download_next_block_handler_t

◆ anjay_download_result_t

◆ anjay_etag_t

Enumeration Type Documentation

◆ anjay_download_result

Function Documentation

◆ anjay_download()

◆ anjay_download_abort()

◆ anjay_download_reconnect()

◆ anjay_download_set_next_block_offset()

◆ anjay_download_suspend()

◆ anjay_etag_clone()

◆ anjay_etag_new()