Struct anjay_configuration

Defined in File core.h

Struct Documentation

struct anjay_configuration

Public Members

const char *endpoint_name

Endpoint name as presented to the LwM2M server. Must be non-NULL, or otherwise anjay_new() will fail.

NOTE: Endpoint name is copied during anjay_new() and cannot be modified later on.

uint16_t udp_listen_port: UDP port number that all listening sockets will be bound to. It may be left at 0 - in that case, connection with each server will use a freshly generated ephemeral port number.

avs_net_ssl_version_t dtls_version: DTLS version to use for communication.

size_t in_buffer_size: Maximum size of a single incoming CoAP message. Decreasing this value reduces memory usage, but packets bigger than this value will be dropped.

size_t out_buffer_size: Maximum size of a single outgoing CoAP message. If the message exceeds this size, the library performs the block-wise CoAP transfer ( https://tools.ietf.org/html/rfc7959 ). NOTE: in case of block-wise transfers, this value limits the payload size for a single block, not the size of a whole packet.

size_t msg_cache_size

Number of bytes reserved for caching CoAP responses. If not 0, the library looks up recently generated responses and reuses them to handle retransmitted packets (ones with identical CoAP message ID).

NOTE: while a single cache is used for all LwM2M servers, cached responses are tied to a particular server and not reused for other ones.

avs_net_socket_configuration_t socket_config

Socket configuration to use when creating TCP/UDP sockets.

Note that:

reuse_addr will be forced to true.
Value pointed to by the preferred_endpoint will be ignored.

const avs_coap_udp_tx_params_t *udp_tx_params

Configuration of the CoAP transmission params for UDP connection, as per RFC 7252.

If NULL, the default configuration ANJAY_COAP_DEFAULT_UDP_TX_PARAMS will be selected.

NOTE: Parameters are copied during anjay_new() and cannot be modified later on.

const avs_net_dtls_handshake_timeouts_t *udp_dtls_hs_tx_params

Configuration of the DTLS handshake retransmission timeouts for UDP connection.

If NULL, the default configuration ANJAY_DTLS_DEFAULT_UDP_HS_TX_PARAMS will be selected.

NOTE: Parameters are copied during anjay_new() and cannot be modified later on.

IMPORTANT: In case of a need to adjust DTLS retransmission params to match the CoAP retransmission params, the udp_dtls_hs_tx_params shall be initialized as dtls_hs_params is in the following code snippet:

const avs_coap_udp_tx_params_t coap_tx_params = {
    // ... some initialization
};

// Without ACK_RANDOM_FACTOR = 1.0, it is impossible to create a DTLS HS
// configuration that matches CoAP retransmission configuration
// perfectly.
assert(coap_tx_params.ack_random_factor == 1.0);

const avs_net_dtls_handshake_timeouts_t dtls_hs_tx_params = {
    .min = avs_time_duration_fmul(coap_tx_params.ack_timeout,
                                  coap_tx_params.ack_random_factor),
    .max = avs_time_duration_fmul(
            coap_tx_params.ack_timeout,
            (1 << coap_tx_params.max_retransmit)
                * coap_tx_params.ack_random_factor)
};

bool confirmable_notifications: Controls whether Notify operations are conveyed using Confirmable CoAP messages by default.

bool disable_legacy_server_initiated_bootstrap

If set to true, connection to the Bootstrap Server will be closed immediately after making a successful connection to any regular LwM2M Server and only opened again if (re)connection to a regular server is rejected.

If set to false, legacy Server-Initiated Bootstrap is possible, i.e. the Bootstrap Server can reach the client at any time to re-initiate the bootstrap sequence.

NOTE: This parameter controls a legacy Server-Initiated Bootstrap mechanism based on an interpretation of LwM2M 1.0 TS that is not universally accepted. Server-Initiated Bootstrap as specified in LwM2M 1.1 TS is always supported, regardless of this setting.

size_t stored_notification_limit

If “Notification Storing When Disabled or Offline” resource is set to true and either the client is in offline mode, or uses Queue Mode, Notify messages are enqueued and sent whenever the client is online again. This value allows one to limit the size of said notification queue. The limit applies to notifications queued for all servers.

If set to 0, size of the stored notification queue is only limited by the amount of available RAM.

If set to a positive value, that much most recent notifications are stored. Attempting to add a notification to the queue while it is already full drops the oldest one to make room for new one.

bool prefer_hierarchical_formats

Sets the preference of the library for Content-Format used when responding to a request without Accept option.

If set to true, the formats used would be:

for LwM2M 1.0: TLV,
for LwM2M 1.1: SenML CBOR, or if not compiled in, SenML JSON, or if not compiled in TLV.

bool use_connection_id: Enables support for DTLS connection_id extension for all DTLS connections.

bool update_immediately_on_dm_change

Send the Update message immediately when Object Instances are created or deleted.

NOTE: In case of Create and Delete operations, the Update message will be immediately sent to all the servers, including the one that initiated the operation.

By default, such data model changes are reported in the next scheduled update message (or the message can be requested using anjay_schedule_registration_update), but the Update is not triggered automatically.

bool enable_self_notify

Send the Notify messages as a result of a server action (e.g. Write) even to the initiating server.

By default, notifications resulting from server actions are only sent to the servers other than the one which initiated the action.

bool connection_error_is_registration_failure

Treat failures of the “connect” socket operation (e.g. (D)TLS handshake failures) as a failed LwM2M Register operation. This enables automatic retrying of them as described in the “Bootstrap and LwM2M Server

Registration Mechanisms” of LwM2M Core TS 1.1.

When disabled, such failures are treated as fatal errors and cause the entire registration sequence for that server to be aborted (which will trigger a fallback to Bootstrap if applicable).

avs_net_socket_tls_ciphersuites_t default_tls_ciphersuites

(D)TLS ciphersuites to use if the “DTLS/TLS Ciphersuite” Resource (/0/x/16) is not available or empty.

Passing a value with num_ids == 0 (default) will cause defaults of the TLS backend library to be used.

Contents of the ids array are copied, so it is safe to free the passed array after the call to anjay_new.

avs_crypto_prng_ctx_t *prng_ctx

Custom PRNG context to use. If NULL , a default one is used, with entropy source specific to selected cryptograpic backend. If default entropy source isn’t available, creation of Anjay object will fail.

Used for establishing TLS and DTLS connections, generation of tokens and by OSCORE module, if it’s available.

If not NULL , then MUST outlive created Anjay object.

avs_ssl_additional_configuration_clb_t *additional_tls_config_clb: Callback that will be executed when initializing TLS and DTLS connections, that can be used for additional configuration of the TLS backend.

size_t coap_tcp_max_options_size

Maximum expected TCP options size. CoAP messages with options longer than this value will be rejected.

If set to 0, a hard-coded default value (128) will be used.

avs_time_duration_t coap_tcp_request_timeout

Time to wait for incoming response after sending a request. After this time request is considered unsuccessful.

If zero-initialized or set to AVS_TIME_DURATION_ZERO, a default value of 30s is used.

const avs_coap_udp_tx_params_t *sms_tx_params

Configuration of the CoAP transmission params for SMS connection, as per RFC 7252.

If NULL, the default configuration ANJAY_COAP_DEFAULT_SMS_TX_PARAMS will be selected.

NOTE: Parameters are copied during anjay_new() and cannot be modified later on.

const avs_coap_udp_tx_params_t *nidd_tx_params

Configuration of the CoAP transmission params for NIDD connection, as per RFC 7252.

If NULL, the default configuration ANJAY_COAP_DEFAULT_NIDD_TX_PARAMS will be selected.

NOTE: Parameters are copied during anjay_new() and cannot be modified later on.

anjay_smsdrv_t *sms_driver: Specifies the cellular modem driver to use, enabling the SMS transport if not NULL.

anjay_nidd_driver_t *nidd_driver: Specifies the NIDD driver to use, enabling the NIDD transport if not NULL.

const char *local_msisdn

Phone number at which the local device is reachable, formatted as an MSISDN (international number without neither the international dialing prefix nor the “+” sign).

Notes:

Local MSISDN is copied during anjay_new() and cannot be modified later on.
Either both sms_driver and local_msisdn have to be NULL, or both have to be non-NULL.
Phone number must be limited to 15 digits, otherwise anjay_new() will fail.

bool prefer_multipart_sms

If set to true, Anjay will prefer using Concatenated SMS messages when seding large chunks of data over the SMS transport.

NOTE: This is only a preference; even if set to true, Concatenated SMS may not be used e.g. when the SMS driver does not support it; even if set to false, Concatenated SMS may be used in cases when it is impossible to split the message in another way, e.g. during DTLS handshake.

const anjay_lwm2m_version_config_t *lwm2m_version_config

Configuration of LwM2M protocol versions to use when attempting to register to LwM2M servers.

If NULL, the default configuration, that allows all supported versions to be used, will be selected.

Notes:

Configuration is copied during anjay_new() and cannot be modified later on.
Restricting the set of supported versions may speed up the Register operation, as less versions will be attempted for registration.
If minimum_version is set to a higher value than maximum_version, anjay_new will fail.
If minimum_version is set to a version higher than LwM2M 1.0, disable_legacy_server_initiated_bootstrap will be effectively implied even if that field is set to false.

bool use_system_trust_store

Enable usage of system-wide trust store (e.g. /etc/ssl/certs on most Unix-like systems) for PKIX certificate verification in addition to those specified via trust_store_certs and trust_store_crls.

NOTE: System-wide trust store is currently supported only by the OpenSSL backend. This field will not have the intended effect with the Mbed TLS backend.

NOTE: PKIX certificate verification is only used in certain “Certificate

Usage” modes configured in the Security object of the data model. It is also not automatically propagated to downloads, although is passed through by

anjay_security_config_from_dm.

NOTE: System-wide trust store will be disabled for connections using the trust store updated through the /est/crts request, regardless of the value of this flag.

avs_crypto_certificate_chain_info_t trust_store_certs

Store of trust anchor certificates to use for PKIX certificate verification. This field is optional and can be left zero-initialized. If used, it shall be initialized using one of the avs_crypto_trusted_cert_info_from_* helper functions.

Any data passed is copied immediately, so it is safe to free any associated buffers after calling anjay_new.

NOTE: PKIX certificate verification is only used in certain “Certificate

Usage” modes configured in the Security object of the data model. It is also not automatically propagated to downloads, although is passed through by

anjay_security_config_from_dm.

avs_crypto_cert_revocation_list_info_t trust_store_crls

Store of certificate revocation lists to use for PKIX certificate verification. This field is optional and can be left zero-initialized. If used, it shall be initialized using one of the avs_crypto_cert_revocation_list_info_from_* helper functions.

Any data passed is copied immediately, so it is safe to free any associated buffers after calling anjay_new.

NOTE: PKIX certificate verification is only used in certain “Certificate

Usage” modes configured in the Security object of the data model. It is also not automatically propagated to downloads, although is passed through by

anjay_security_config_from_dm.

bool rebuild_client_cert_chain

Enable rebuilding of client certificate chain based on certificates in the trust store.

If this field is set to true, when performing a (D)TLS handshake, if the client certificate configured in the data model (or the last certificate in a chain) is not self-signed, Anjay will attempt to find its ancestors in the appropriate trust store (which may be trust_store_certs or the one provisioned by /est/crts operation) and append them to the chain presented during handshake.

const anjay_est_reenroll_config_t *est_reenroll_config

Configuration of re-enrollment mechanism for EST certificate mode.

If NULL, the following settings are used:

.enable = true, .nominal_usage = 0.9, .max_margin = avs_time_duration_from_scalar(30, AVS_TIME_DAY)

anjay_est_cacerts_policy_t est_cacerts_policy: Policy of when to perform the /est/crts request and which servers will use the trust store updated through it.

const char *est_engine_key_address

Address to use for storing the EST private key in external security engine.

If NULL, software-based security will be used.

const char *est_engine_cert_address

Address to use for storing the client certificate provisioned through EST in external security engine.

If NULL, software-based security will be used.

anjay_est_engine_cacert_address_gen_t *est_engine_cacerts_address_gen_cb

Callback function that will be called whenever Anjay needs an address for storing a new CA certificate provisioned over EST in external security engine.

If NULL, software-based security will be used.

void *est_engine_cacerts_address_gen_cb_arg

Opaque argument that will be passed to the function configured in the est_engine_cacerts_address_gen_cb field.

If est_engine_cacerts_address_gen_cb is NULL, this field is ignored.

anjay_confirmable_notification_status_cb_t *confirmable_notification_status_cb: A handler called if acknowledgement for confirmable notification is received from the Server or some error has occurred.

anjay_server_connection_status_cb_t *server_connection_status_cb: Function called each time there is a transition of a server connection status (as listed in anjay_server_conn_status_t ).

void *server_connection_status_cb_arg

Opaque argument that will be passed to the function configured in the server_connection_status_cb field.

If server_connection_status_cb is NULL, this field is ignored.

anjay_ssl_error_cb_t *ssl_error_cb

Experimental:: This is experimental SSL error callback API. This API can change in future versions without any notice.

Function called each time a (D)TLS error is reported.

void *ssl_error_cb_arg

Experimental:: This is experimental SSL error callback API. This API can change in future versions without any notice.

Opaque argument that will be passed to the function configured in the ssl_error_cb field.

If ssl_error_cb is NULL, this field is ignored.

size_t coap_downloader_retry_count

If set, defines the number of additional CoAP download attempts that will be made in case of failure. Can be useful for large files (Firmware Update) and poor network quality. If the resumption of the transfer was successful then the retry counter is reset.

Retries are performed only in case of network problems - AVS_ERRNO_CATEGORY or exchange timeout, in case of internal problems or error server responses the download is stopped.

Each try will establish new connections and start a new exchange but preserve the download status. This logic does not comply with CoAP, but it can prevent multiple downloads of the same file.

NOTE: Keep in mind that the behavior of this feature changes when the same socket is used for both file downloads and other CoAP operations (which may happen if the anjay_download_config_t::prefer_same_socket_downloads flag is set). A specific difference is how network errors (e.g., ICMP) are handled: if a separate socket is used for downloads, Anjay will retry downloading; however, if the same socket is used for other CoAP operations, Anjay will abort the download. In the event of a timeout, Anjay will retry downloading in both cases.

avs_time_duration_t coap_downloader_retry_delay: If set, defines the delay between CoAP download attempts in case of failure. If not set, next attempt will be made immediately. Related to coap_downloader_retry_count.