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

Go to the source code of this file.

Data Structures

struct  anjay_etag
struct  anjay_download_status_t
struct  anjay_download_config


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


enum  anjay_download_result {


anjay_etag_tanjay_etag_new (uint8_t etag_size)
anjay_etag_tanjay_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)

Typedef Documentation

◆ 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.

anjayAnjay object managing the download process.
statusStatus of the download, with additional error information if applicable.
user_dataValue 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.

anjayAnjay object managing the download process.
dataReceived data.
data_sizeNumber of bytes available in data .
etagETag option sent by the server. Should be saved if the client may need to resume the transfer after it gets interrupted.
user_dataValue of anjay_download_config_t::user_data passed to anjay_download .
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

◆ anjay_etag_t

typedef struct anjay_etag anjay_etag_t

CoAP Entity Tag.

Enumeration Type Documentation

◆ anjay_download_result


Download finished successfully.


Download failed due to a local failure or a network error.


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).


Downloaded resource changed while transfer was in progress.


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.

anjayAnjay object that will manage the download process.
configDownload configuration.
out_handlePointer to a variable that will be set to a download handle, that may be used for aborting the download. MUST NOT be NULL.
  • 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.

anjayAnjay object managing the download process.
dl_handleDownload handle previously returned by anjay_download.

◆ 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.

anjayAnjay object managing the download process.
dl_handleDownload handle previously returned by anjay_download.
next_block_offsetBlock offset to set.
  • 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_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.

old_etagPointer to old ETag copy
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.

etag_sizeThe number of bytes to be available in the returned anjay_etag_t::value array.
Pointer to created ETag, NULL on failure