Download client

The download client library can be used to download files from an HTTP or a CoAP server. The download is carried out in a separate thread, and the application receives events such as DOWNLOAD_CLIENT_EVT_FRAGMENT that contain the data fragments as the download progresses. The fragment size can be configured independently for HTTP and CoAP (block-wise transfer) using the CONFIG_DOWNLOAD_CLIENT_HTTP_FRAG_SIZE and the CONFIG_DOWNLOAD_CLIENT_COAP_BLOCK_SIZE options, respectively. When the download completes, the library sends the DOWNLOAD_CLIENT_EVT_DONE event to the application.

Protocols

The library supports HTTP, HTTPS (TLS 1.2), CoAP, and CoAPS (DTLS 1.2) over IPv4 and IPv6.

HTTP and HTTPS (TLS 1.2)

In the case of download via HTTP, the library sends only one HTTP request to the server and receives only one HTTP response.

In the case of download via HTTPS, it is carried out through Content-Range requests (IETF RFC 7233) due to memory constraints that limit the maximum HTTPS message size to 2 kilobytes. The library thus sends and receives as many requests and responses as the number of fragments that constitutes the download. For example, to download a file of size 47 kilobytes file with a fragment size of 2 kilobytes, a total of 24 HTTP GET requests are sent. It is therefore recommended to use the largest fragment size to minimize the network usage. Make sure to configure the CONFIG_DOWNLOAD_CLIENT_BUF_SIZE and the CONFIG_DOWNLOAD_CLIENT_HTTP_FRAG_SIZE options so that the buffer is large enough to accommodate the entire HTTP header of the request and the response.

The application must provision the TLS credentials and pass the security tag to the library when using HTTPS and calling the download_client_connect() function. To provision a TLS certificate to the modem, use modem_key_mgmt_write() and other Modem key management APIs.

CoAP and CoAPS (DTLS 1.2)

When downloading from a CoAP server, the library uses the CoAP block-wise transfer. Make sure to configure the CONFIG_DOWNLOAD_CLIENT_BUF_SIZE option and the CONFIG_DOWNLOAD_CLIENT_COAP_BLOCK_SIZE option so that the buffer is large enough to accommodate the entire CoAP header and the CoAP block.

The application must provision the TLS credentials and pass the security tag to the library when using CoAPS and calling download_client_connect().

Limitations

The library requires the host server to provide a Content-Range field in the HTTP GET header when using HTTPS. If this header field is missing, the library logs the following error:

<err> download_client: Server did not send "Content-Range" in response

It is not possible to use a CoAP block size of 1024 bytes, due to internal limitations.

API documentation

Header file: include/download_client.h
Source files: subsys/net/lib/download_client/src/
group dl_client

Client for downloading an object.

The download client provides APIs for:

  • connecting to a remote server,

  • downloading an object from the server,

  • disconnecting from the server,

  • receiving asynchronous event notifications on the download status.

Typedefs

typedef int (*download_client_callback_t)(const struct download_client_evt *event)

Download client asynchronous event handler.

Through this callback, the application receives events, such as download of a fragment, download completion, or errors.

If the callback returns a non-zero value, the download stops. To resume the download, use download_client_start().

Return

Zero to continue the download, non-zero otherwise.

Parameters

  • [in] event: The event.

Enums

enum download_client_evt_id

Download client event IDs.

Values:

enumerator DOWNLOAD_CLIENT_EVT_FRAGMENT

Event contains a fragment. The application may return any non-zero value to stop the download.

enumerator DOWNLOAD_CLIENT_EVT_ERROR

An error has occurred during download and the connection to the server has been lost.

Error reason may be one of the following:

  • ECONNRESET: socket error, peer closed connection

  • ETIMEDOUT: socket error, connection timed out

  • EHOSTDOWN: host went down during download

  • EBADMSG: HTTP response header not as expected

  • E2BIG: HTTP response header could not fit in buffer

In case of errors on the socket during send() or recv() (ECONNRESET), returning zero from the callback will let the library attempt to reconnect to the server and download the last fragment again. Otherwise, the application may return any non-zero value to stop the download.

In case the download is stopped, the application should manually disconnect (download_client_disconnect) to clean up the network socket as necessary before re-attempting the download.

enumerator DOWNLOAD_CLIENT_EVT_DONE

Download complete.

Functions

int download_client_init(struct download_client *client, download_client_callback_t callback)

Initialize the download client.

Parameters

  • [in] client: Client instance.

  • [in] callback: Callback function.

Return Value

  • int: Zero on success, otherwise a negative error code.

int download_client_connect(struct download_client *client, const char *host, const struct download_client_cfg *config)

Establish a connection to the server.

Parameters

  • [in] client: Client instance.

  • [in] host: Name of the host to connect to, null-terminated. Can include scheme and port number, defaults to HTTP or HTTPS if no scheme is provided.

  • [in] config: Configuration options.

Return Value

  • int: Zero on success, a negative error code otherwise.

int download_client_start(struct download_client *client, const char *file, size_t from)

Download a file.

The download is carried out in fragments of up to CONFIG_DOWNLOAD_CLIENT_HTTP_FRAG_SIZE bytes for HTTP, or CONFIG_DOWNLOAD_CLIENT_COAP_BLOCK_SIZE bytes for CoAP, which are delivered to the application via DOWNLOAD_CLIENT_EVT_FRAGMENT events.

Parameters

  • [in] client: Client instance.

  • [in] file: File to download, null-terminated.

  • [in] from: Offset from where to resume the download, or zero to download from the beginning.

Return Value

  • int: Zero on success, a negative error code otherwise.

void download_client_pause(struct download_client *client)

Pause the download.

Parameters

  • [in] client: Client instance.

void download_client_resume(struct download_client *client)

Resume the download.

Parameters

  • [in] client: Client instance.

int download_client_file_size_get(struct download_client *client, size_t *size)

Retrieve the size of the file being downloaded, in bytes.

The file size is only available after the download has begun.

Parameters

  • [in] client: Client instance.

  • [out] size: File size.

Return Value

  • int: Zero on success, a negative error code otherwise.

int download_client_disconnect(struct download_client *client)

Disconnect from the server.

Return

Zero on success, a negative error code otherwise.

Parameters

  • [in] client: Client instance.

struct download_fragment
#include <download_client.h>
struct download_client_evt
#include <download_client.h>

Download client event.

Public Members

enum download_client_evt_id id

Event ID.

int error

Error cause.

struct download_fragment fragment

Fragment data.

struct download_client_cfg
#include <download_client.h>

Download client configuration options.

Public Members

int sec_tag

TLS security tag. Pass -1 to disable TLS.

const char *apn

Access point name identifying a packet data network. Pass a null-terminated string with the APN or NULL to use the default APN.

size_t frag_size_override

Maximum fragment size to download. 0 indicates that Kconfigured values shall be used.

bool set_tls_hostname

Set hostname for TLS Server Name Indication extension

struct download_client
#include <download_client.h>

Download client instance.

Public Members

int fd

Socket descriptor.

char buf[CONFIG_DOWNLOAD_CLIENT_BUF_SIZE]

Response buffer.

size_t offset

Buffer offset.

size_t file_size

Size of the file being downloaded, in bytes.

size_t progress

Download progress, number of bytes downloaded.

const char *host

Server hosting the file, null-terminated.

const char *file

File name, null-terminated.

struct download_client_cfg config

Configuration options.

int proto

Protocol for current download.

bool has_header

Whether the HTTP header for the current fragment has been processed.

bool connection_close

The server has closed the connection.

struct coap_block_context block_ctx

CoAP block context.

k_tid_t tid

Internal thread ID.

struct k_thread thread

Internal download thread.

download_client_callback_t callback

Event handler.