- Generated on Fri Feb 16 2024 11:36:38 for anjay by
1.9.1
|
anjay
|
#include <stdint.h>#include <avsystem/coap/udp.h>#include <avsystem/commons/avs_list.h>#include <avsystem/commons/avs_net.h>#include <avsystem/commons/avs_prng.h>#include <avsystem/commons/avs_sched.h>#include <avsystem/commons/avs_stream.h>#include <avsystem/commons/avs_time.h>#include <anjay/anjay_config.h>Go to the source code of this file.
Data Structures | |
| struct | anjay_lwm2m_version_config_t |
| struct | anjay_est_reenroll_config_t |
| struct | anjay_configuration |
| struct | anjay_socket_entry_t |
| struct | anjay_transport_set_t |
| struct | anjay_security_config_t |
Typedefs | |
| typedef uint16_t | anjay_ssid_t |
| typedef struct anjay_struct | anjay_t |
| typedef struct anjay_smsdrv_struct | anjay_smsdrv_t |
| typedef struct anjay_nidd_driver_struct | anjay_nidd_driver_t |
| typedef const char * | anjay_est_engine_cacert_address_gen_t(void *arg, const void *x509_der_data, size_t x509_der_data_size) |
| typedef struct anjay_configuration | anjay_configuration_t |
| typedef uint16_t | anjay_oid_t |
| typedef uint16_t | anjay_iid_t |
| typedef uint16_t | anjay_rid_t |
| typedef uint16_t | anjay_riid_t |
| #define ANJAY_COAP_DEFAULT_NIDD_TX_PARAMS |
Default transmission params for NIDD connections.
This set of parameters ensures MAX_TRANSMIT_WAIT is equal to the default (i.e. CoAP specified) MAX_TRANSMIT_WAIT, while disabling retransmissions.
NOTE: The default timeout value is something halfway the AT+QCFGEXT="nipd" may return on some NIDD modems.
| #define ANJAY_COAP_DEFAULT_SMS_TX_PARAMS |
Default transmission params for SMS connections.
This set of parameters ensures MAX_TRANSMIT_WAIT is equal to the default (i.e. CoAP specified) MAX_TRANSMIT_WAIT, while disabling retransmissions.
| #define ANJAY_COAP_DEFAULT_UDP_TX_PARAMS |
Default transmission params recommended by the CoAP specification (RFC 7252).
| #define ANJAY_COAP_STATUS | ( | Maj, | |
| Min | |||
| ) | ((uint8_t) ((Maj << 5) | (Min & 0x1F))) |
Helper macro used to define ANJAY_ERR_ constants. Generated values are valid CoAP Status Codes encoded as a single byte.
| #define ANJAY_DTLS_DEFAULT_UDP_HS_TX_PARAMS |
Default handshake retransmission params recommended by the DTLS specification (RFC 6347), i.e: 1s for the initial response, growing exponentially (with each retransmission) up to maximum of 60s.
| #define ANJAY_ERR_BAD_OPTION (-(int) ANJAY_COAP_STATUS(4, 2)) |
Low-level CoAP error code; used internally by Anjay when CoAP option values were invalid.
| #define ANJAY_ERR_BAD_REQUEST (-(int) ANJAY_COAP_STATUS(4, 0)) |
Error values that may be returned from data model handlers. Request sent by the LwM2M Server was malformed or contained an invalid value.
| #define ANJAY_ERR_FORBIDDEN (-(int) ANJAY_COAP_STATUS(4, 3)) |
| #define ANJAY_ERR_INTERNAL (-(int) ANJAY_COAP_STATUS(5, 0)) |
Unspecified error, no other error code was suitable.
| #define ANJAY_ERR_METHOD_NOT_ALLOWED (-(int) ANJAY_COAP_STATUS(4, 5)) |
Operation is not allowed in current device state or the attempted operation is invalid for this target (Object/Instance/Resource)
| #define ANJAY_ERR_NOT_ACCEPTABLE (-(int) ANJAY_COAP_STATUS(4, 6)) |
Low-level CoAP error code; used internally by Anjay when the client is unable to encode response in requested content format.
| #define ANJAY_ERR_NOT_FOUND (-(int) ANJAY_COAP_STATUS(4, 4)) |
Target of the operation (Object/Instance/Resource) does not exist.
| #define ANJAY_ERR_NOT_IMPLEMENTED (-(int) ANJAY_COAP_STATUS(5, 1)) |
Operation is not implemented by the LwM2M Client.
| #define ANJAY_ERR_REQUEST_ENTITY_INCOMPLETE (-(int) ANJAY_COAP_STATUS(4, 8)) |
Low-level CoAP error code; used internally by Anjay in case of unrecoverable problems during block-wise transfer.
| #define ANJAY_ERR_SERVICE_UNAVAILABLE (-(int) ANJAY_COAP_STATUS(5, 3)) |
LwM2M Client is busy processing some other request; LwM2M Server may retry sending the same request after some delay.
| #define ANJAY_ERR_UNAUTHORIZED (-(int) ANJAY_COAP_STATUS(4, 1)) |
LwM2M Server is not allowed to perform the operation due to lack of necessary access rights.
| #define ANJAY_ERR_UNSUPPORTED_CONTENT_FORMAT (-(int) ANJAY_COAP_STATUS(4, 15)) |
The server requested operation has a Content Format option that is unsupported by Anjay.
| #define ANJAY_ID_INVALID UINT16_MAX |
Value reserved by the LwM2M spec for all kinds of IDs (Object IDs, Object Instance IDs, Resource IDs, Resource Instance IDs, Short Server IDs).
| #define ANJAY_SSID_ANY 0 |
A constant that may be used in anjay_schedule_registration_update call instead of Short Server ID to send Update messages to all connected servers.
| #define ANJAY_SSID_BOOTSTRAP UINT16_MAX |
An SSID value reserved by LwM2M to refer to the Bootstrap Server. NOTE: The value of a "Short Server ID" Resource in the Security Object Instance referring to the Bootstrap Server is irrelevant and cannot be used to identify the Bootstrap Server.
| typedef struct anjay_configuration anjay_configuration_t |
| typedef const char* anjay_est_engine_cacert_address_gen_t(void *arg, const void *x509_der_data, size_t x509_der_data_size) |
Type for a callback function that will be called by Anjay whenever an address for storing a new trusted CA certificate provisioned over EST in external security engine is necessary. See also the est_engine_cacerts_address_gen_cb field of anjay_configuration_t.
| arg | Opaque argument configured through the est_engine_cacerts_address_gen_cb_arg field of anjay_configuration_t. |
| x509_der_data | Pointer to a buffer containing DER-formatted data of the X.509 certificate to be stored. |
| x509_der_data_size | Size in bytes of the certificate data located at x509_der_data. |
x509_der_data and x509_der_data_size are provided only as a hint for users who want the certificate addresses to depend on their contents in any way. This callback shall not attempt to store the certificate itself. This will be performed by Anjay afterwards. | typedef uint16_t anjay_iid_t |
Object Instance ID
| typedef struct anjay_nidd_driver_struct anjay_nidd_driver_t |
Driver for communication over the NIDD transport.
| typedef uint16_t anjay_oid_t |
Object ID
| typedef uint16_t anjay_rid_t |
Resource ID
| typedef uint16_t anjay_riid_t |
Resource Instance ID
| typedef struct anjay_smsdrv_struct anjay_smsdrv_t |
Driver for communication over the SMS transport.
| typedef uint16_t anjay_ssid_t |
Short Server ID type.
| typedef struct anjay_struct anjay_t |
Anjay object containing all information required for LwM2M communication.
| Enumerator | |
|---|---|
| ANJAY_REGISTRATION_EXPIRATION_STATUS_VALID | Anjay registration is valid, expiration time got from anjay_registration_expiration_time_with_status informs when the registration expires. |
| ANJAY_REGISTRATION_EXPIRATION_STATUS_EXPIRED | Anjay registration expired, expiration time is set to |
| ANJAY_REGISTRATION_EXPIRATION_STATUS_INFINITE_LIFETIME | Anjay lifetime is set to infinity and expiration time is set to |
| bool anjay_all_connections_failed | ( | anjay_t * | anjay | ) |
Tests if Anjay gave up on any further server connection attempts. It will happen if none of the configured servers could be reached.
If this function returns true, it means that Anjay is in an essentially non-operational state. anjay_schedule_reconnect may be called to reset the failure state and retry connecting to all configured servers. anjay_transport_schedule_reconnect will do the same, but only for the specified transports. Alternatively, anjay_enable_server may be used to retry connection only to a specific server.
| anjay | Anjay object to operate on. |
| void anjay_delete | ( | anjay_t * | anjay | ) |
Cleans up all resources and releases the Anjay object.
NOTE: It shall be called before freeing LwM2M Objects registered within the anjay object.
NOTE: The anjay pointer is invalidated during the call to this function. If Anjay is compiled with thread safety enabled, all the intermediary cleanup code is properly synchronized, but you should still make sure that no other thread is able to access the anjay object before calling this function, to avoid its usage after free.
| anjay | Anjay object to delete. MUST NOT be NULL . |
| int anjay_delete_with_core_persistence | ( | anjay_t * | anjay, |
| avs_stream_t * | out_stream | ||
| ) |
Persists the core library state into the out_stream and then deletes the Anjay instance but does NOT deregister from any LwM2M Servers.
NOTE: Anjay is deleted from memory even if the persistence operation fails (in which case any persisted data shall be considered invalid). It should generally not be a problem though, because in the worst case scenario the client will later need to perform full re-register and reconnection (at DTLS layer as well, if secure connection is used).
NOTE: It shall be called before freeing LwM2M Objects registered within the anjay object.
NOTE: The anjay pointer is invalidated during the call to this function. If Anjay is compiled with thread safety enabled, all the intermediary cleanup code is properly synchronized, but you should still make sure that no other thread is able to access the anjay object before calling this function, to avoid its usage after free.
| anjay | Anjay object to persist and then delete from memory. |
| out_stream | Stream where persisted data shall be stored. |
out_stream contents are undefined, and some data may have been written to the backend storage. The partially-filled persistence data should not be used with anjay_new_from_core_persistence. | int anjay_disable_server | ( | anjay_t * | anjay, |
| anjay_ssid_t | ssid | ||
| ) |
This function shall be called when an LwM2M Server Object shall be disabled. The standard case for this is when Execute is performed on the Disable resource (/1/x/4).
The server will be disabled for the period of time determined by the value of the Disable Timeout resource (/1/x/5). The resource is read soon after the invocation of this function (during next anjay_sched_run) and is not updated upon any subsequent Writes to that resource.
If the server is already disabled, its re-enable action will be re-scheduled according to the value of the Disable Timeout resource added to current time.
NOTE: Disabled servers and the time at which those servers will be reenabled is persisted and restored by anjay_new_from_core_persistence and anjay_delete_with_core_persistence .
| anjay | Anjay object to operate on. |
| ssid | Short Server ID of the server to put in a disabled state. NOTE: disabling a server requires a Server Object Instance to be present for given ssid . Because the Bootstrap Server does not have one, this function does nothing when called with ANJAY_SSID_BOOTSTRAP . |
| int anjay_disable_server_with_timeout | ( | anjay_t * | anjay, |
| anjay_ssid_t | ssid, | ||
| avs_time_duration_t | timeout | ||
| ) |
This function shall be called when an LwM2M Server Object shall be disabled. The standard case for this is when Execute is performed on the Disable resource (/1/x/4). It may also be used to prevent reconnections if the server becomes unreachable.
The server will become disabled during next anjay_sched_run call.
If the server is already disabled, its re-enable action will be re-scheduled or cancelled, according to the timeout argument.
NOTE: disabling a server with dual binding (e.g. UDP+SMS trigger) closes both communication channels. Shutting down only one of them requires changing the Binding Resource in Server object.
NOTE: Disabled servers and the time at which those servers will be reenabled is persisted and restored by anjay_new_from_core_persistence and anjay_delete_with_core_persistence .
| anjay | Anjay object to operate on. |
| ssid | Short Server ID of the server to put in a disabled state. |
| timeout | Disable timeout. If set to AVS_TIME_DURATION_INVALID, the server will remain disabled until explicit call to anjay_enable_server . Otherwise, the server will get enabled automatically after timeout . |
| int anjay_enable_server | ( | anjay_t * | anjay, |
| anjay_ssid_t | ssid | ||
| ) |
Schedules a job for re-enabling a previously disabled (with a call to anjay_disable_server_with_timeout ) server. The server will be enabled during next anjay_sched_run call.
| anjay | Anjay object to operate on. |
| ssid | Short Server ID of the server to enable. |
| bool anjay_est_state_is_ready_for_persistence | ( | anjay_t * | anjay | ) |
Checks whether the EST state is appropriate for persisting it.
Returns true if, and only if, an EST operation is not currently in progress and the state has been modified since last successful call to anjay_est_state_persist or anjay_est_state_restore .
| avs_error_t anjay_est_state_persist | ( | anjay_t * | anjay, |
| avs_stream_t * | out_stream | ||
| ) |
Dumps EST state (updated trust store, generated secret key and provisioned client certificate) to the out_stream .
| anjay | Anjay instance. |
| out_stream | Stream to write to. |
avs_errno(AVS_EAGAIN) will be returned in such case. | avs_error_t anjay_est_state_restore | ( | anjay_t * | anjay, |
| avs_stream_t * | out_stream | ||
| ) |
Attempts to restore EST state from specified in_stream . If restore fails, then the state will be left untouched.
NOTE: This function is intended to be called during client initializaiton, before entering the main event loop. If EST state is restored while server connections are already active, the new credentials will not be applied until a full reconnect with a given server, which requires either anjay_disable_server to be called, or a connection error to occur.
| anjay | Anjay instance. |
| out_stream | Stream to write to. |
avs_errno(AVS_EAGAIN) will be returned in such case. | int anjay_event_loop_interrupt | ( | anjay_t * | anjay | ) |
Interrupts an ongoing execution of anjay_event_loop_run.
This function may be called from another thread, or from a callback running within the event loop itself.
After the call to this function, the event loop will finish as soon as possible while gracefully executing any outstanding tasks.
Please note that the event loop may not be interrupted immediately and instead wait until either of the following:
poll or select() operation finishes (see the max_wait_time argument to anjay_event_loop_run)Interrupting the two latter cases may be possible by performing a system-specific call that would interrupt ongoing socket operations (e.g. raising a signal with an appropriately crafted signal handler on Unix-like systems) immediately after having called anjay_event_loop_interrupt().
| anjay | Anjay object to operate on. |
Please note that this function always returns immediately, without waiting for the event loop to actually finish. Please use an appropriate system API (e.g. pthread_join() on Unix-like systems) if you need to ensure that the event loop has finished.
| int anjay_event_loop_run | ( | anjay_t * | anjay, |
| avs_time_duration_t | max_wait_time | ||
| ) |
Runs Anjay's main event loop that executes anjay_serve and anjay_sched_run as appropriate.
This function will only return after either:
IMPORTANT: The preimplemented event loop is primarily intended to be run in a dedicated thread, while other threads may handle tasks not related to LwM2M. It is safe to control the same instance of Anjay concurrently from a different thread only if the thread safety features have been enabled at Anjay's compile time:
AVS_COMMONS_SCHED_THREAD_SAFE (WITH_SCHEDULER_THREAD_SAFE in CMake) is required to safely use Anjay's internal scheduler (see anjay_get_scheduler)avs_sched_run(anjay_get_scheduler(anjay)) while the event loop is running may lead to undefined behavior in the loopANJAY_WITH_THREAD_SAFETY (WITH_THREAD_SAFETY in CMake) is required to call any other functions, aside from the cleanup functions (which are only safe to call after the event loop has finished) and anjay_event_loop_interrupt (which is always safe to call)CAUTION: The preimplemented event loop will only work if all the sockets that may be created by Anjay will return file descriptors compatible with poll() or select() through avs_net_socket_get_system().
In particular, please be cautious when using SMS or NIDD transports (in versions of Anjay that include the relevant commercial features) - your anjay_smsdrv_system_socket_t and anjay_nidd_driver_system_descriptor_t functions need to populate the output argument with a valid file descriptor (e.g. int fd = ...; *out = ), and that file descriptor must be valid to use with the poll() or select() functions (which may not true if the socket API is separate from other IO APIs, as is the case e.g. on Windows). Otherwise attempting to use this event loop implementation will not handle NIDD and SMS transports properly, and may even lead to undefined behavior.
| anjay | Anjay object to operate on. |
| max_wait_time | Maximum time to spend in each single call to poll() or select(). Larger times will prevent the event loop thread from waking up too frequently. However, during this wait time, the call to anjay_event_loop_interrupt may not be handled immediately, and scheduler jobs requested from other threads (see anjay_get_scheduler) will not be executed, so shortening this time will make the scheduler more responsive. |
| int anjay_event_loop_run_with_error_handling | ( | anjay_t * | anjay_locked, |
| avs_time_duration_t | max_wait_time | ||
| ) |
Act same as anjay_event_loop_run, but when none of the configured servers could be reached, try to reconnect using function anjay_transport_schedule_reconnect.
| anjay | Anjay object to operate on. |
| max_wait_time | Maximum time to spend in each single call to poll() or select(). Larger times will prevent the event loop thread from waking up too frequently. However, during this wait time, the call to anjay_event_loop_interrupt may not be handled immediately, and scheduler jobs requested from other threads (see anjay_get_scheduler) will not be executed, so shortening this time will make the scheduler more responsive. |
| avs_sched_t* anjay_get_scheduler | ( | anjay_t * | anjay | ) |
Extracts the scheduler used by Anjay allowing the user to schedule his own tasks.
See docs of avs_commons library for API of avs_sched_t object.
Must not use avs_sched_cleanup on the returned scheduler. Anjay will cleanup it itself.
| anjay | Anjay object to operate on. |
| avs_error_t anjay_get_server_last_communication_time | ( | anjay_t * | anjay, |
| anjay_ssid_t | ssid, | ||
| avs_time_real_t * | out_time | ||
| ) |
Gets the time at which the client has communicated with a given LwM2M Server for the last time.
| anjay | Anjay object to operate on. | |
| ssid | A Short Server ID of a single regular LwM2M Server for which to get the information, or ANJAY_SSID_ANY to get the time of last communication attempt to any known server. | |
| [out] | out_time | Non-NULL pointer to an avs_time_real_t structure. The structure will be filled with information about a point in time according to the real-time clock at which the last communication happened, or AVS_TIME_REAL_INVALID if there was no communication attempt with a given server. |
| avs_error_t anjay_get_server_last_registration_time | ( | anjay_t * | anjay, |
| anjay_ssid_t | ssid, | ||
| avs_time_real_t * | out_time | ||
| ) |
Gets the time at which the client has registered successfully to a given LwM2M server for the last time.
| anjay | Anjay object to operate on. | |
| ssid | A Short Server ID of a single regular LwM2M Server for which to get the information, or ANJAY_SSID_ANY to get the time of the last successful registration to any known server. | |
| [out] | out_time | Non-NULL pointer to an avs_time_real_t structure. The structure will be filled with information about a point in time according to the real-time clock at which the last registration happened, or AVS_TIME_REAL_INVALID if there was no successful registration to a given server. |
| avs_error_t anjay_get_server_next_update_time | ( | anjay_t * | anjay, |
| anjay_ssid_t | ssid, | ||
| avs_time_real_t * | out_time | ||
| ) |
Gets the time at which next registration update operation with a given LwM2M Server is scheduled.
NOTE: This function may internally perform conversion between time values attached to different clocks (real-time clock vs. monotonic clock), which depends on immediate readings of those clocks. For this reason, the calculated value may slightly change from call to call, even if no action was performed in between. This accuracy depends on the accuracy of the underlying clocks as well as CPU performance. It is generally expected to be accurate within single-digit milliseconds, but it is recommended to avoid code that would perform direct comparisons on those values.
| anjay | Anjay object to operate on. | |
| ssid | A Short Server ID of a single regular LwM2M Server for which to get the information, or ANJAY_SSID_ANY to get the time of the closes registration update operation to any known server. | |
| [out] | out_time | Non-NULL pointer to an avs_time_real_t structure. The structure will be filled with information about a point in time according to the real-time clock at which next registration update operation is scheduled, or AVS_TIME_REAL_INVALID if a registration update operation isn't scheduled for a given SSID. |
| int anjay_get_server_ssid_by_msisdn | ( | anjay_t * | anjay, |
| const char * | server_msisdn, | ||
| anjay_ssid_t * | out_ssid | ||
| ) |
Gets the Server SSID of Server Object associated with given MSISDN.
| anjay | Anjay object whose data model shall be queried |
| server_msisdn | Server MSISDN |
| out_ssid | SSID of Server with the given MSISN set |
| int anjay_get_sms_trigger | ( | anjay_t * | anjay, |
| anjay_ssid_t | ssid, | ||
| bool * | out_sms_trigger | ||
| ) |
Gets the SMS Trigger resource value from Server Object associated with given SSID.
| anjay | Anjay object whose data model shall be queried |
| ssid | Server SSID |
| out_sms_trigger | SMS Trigger resource value read from Data Model |
| AVS_LIST [ const anjay_socket_entry_t ] anjay_get_socket_entries | ( | anjay_t * | anjay | ) |
Retrieves a list of structures that describe sockets used for communication with LwM2M servers. Returned list must not be freed nor modified.
The returned data is equivalent to the one that can be retrieved using anjay_get_sockets - but includes additional data that describes the socket in addition to the socket itself. See anjay_socket_entry_t for details.
NOTE: The returned list will be invalidated by any subsequent call to anjay_get_sockets or anjay_get_socket_entries. If you need to call these functions from multiple threads, you need to implement additional synchronization to achieve thread safety.
The socket object pointers themselves may additionally be invalidated by a call to anjay_sched_run, anjay_serve, anjay_serve_any or during the execution of anjay_event_loop_run or anjay_event_loop_run_with_error_handling . For this reason, it is recommended to only call this function from callback functions called from within Anjay, in scheduler jobs, or as part of a custom event loop.
| anjay | Anjay object to operate on. |
| AVS_LIST [ avs_net_socket_t *const ] anjay_get_sockets | ( | anjay_t * | anjay | ) |
Retrieves a list of sockets used for communication with LwM2M servers. Returned list must not be freed nor modified.
Example usage: poll()-based application loop
NOTE: The returned list will be invalidated by any subsequent call to anjay_get_sockets() or anjay_get_socket_entries . If you need to call these functions from multiple threads, you need to implement additional synchronization to achieve thread safety.
The socket object pointers themselves may additionally be invalidated by a call to anjay_sched_run, anjay_serve, anjay_serve_any or during the execution of anjay_event_loop_run or anjay_event_loop_run_with_error_handling . For this reason, it is recommended to only call this function from callback functions called from within Anjay, in scheduler jobs, or as part of a custom event loop.
| anjay | Anjay object to operate on. |
| const char* anjay_get_version | ( | void | ) |
| bool anjay_has_unsent_notifications | ( | anjay_t * | anjay, |
| anjay_ssid_t | ssid | ||
| ) |
Returns whether there are some notifications which have been postponed to be sent later, either due to the connection being offline or a previous failure to send some notification.
The check is performed for one specific server, or for all known servers at once. In versions that do not include the SMS commercial feature, only the primary connections are included (including the case where SMS transport is the only one in use for a given Server Account), secondary SMS Trigger connections are not.
| anjay | Anjay object to operate on. |
| ssid | A Short Server ID of a single regular LwM2M Server for which to get the information, or ANJAY_SSID_ANY to check whether unsent notifications exist for any known server connection. |
| anjay_t* anjay_new | ( | const anjay_configuration_t * | config | ) |
Creates a new Anjay object.
| config | Initial configuration. For details, see anjay_configuration_t . |
| anjay_t* anjay_new_from_core_persistence | ( | const anjay_configuration_t * | config, |
| avs_stream_t * | in_stream | ||
| ) |
Creates a new Anjay object restoring core library state from the specified stream. If the stream is empty the function will fail and return NULL.
The "core library state" includes information that is necessary to resume previously existing registrations with LwM2M Servers without sending the Register message again. This also includes the Observe information.
USE CASE: This method (along with anjay_delete_with_core_persistence()) could be used on devices which have aggressive power saving modes and even disable the main memory chip.
The restored Registration state will be used (if possible) to potentially resume the DTLS session, avoiding costly re-registrations. Of course, if the Lifetime of the Server account expires, then the client will re-register. WARNING: It is necessary to have realtime clock working properly at this stage.
The restored Observation state will be used (if possible) to maintain previous Observation requests all LwM2M Servers started.
CAUTION: After successful restore from the stream, the user SHOULD clear the persistence data source. It is not strictly necessary, but highly RECOMMENDED. The idea behind doing that is to avoid a situation where the Server is confused, because at some point in time the Client happened to spuriously restore its previous (stale state) potentially causing its behavior to be different than the Server would normally expect from a conformant LwM2M Client.
NOTE: The registration and observation state persistence make sense only if you restore the actual data model state (including registered Objects and data contained within them; this especially includes the LwM2M Server and Security objects) before entering the main loop. Otherwise the registration states are going to be cleaned up (and forgotten), as they would have no correlation with the server accounts; the observe states are also going to be cleaned up, as they have no correlation with the data model.
| config | Initial configuration. For details, see anjay_configuration_t . |
| in_stream | Readable stream from which restoring shall be performed. |
| avs_time_real_t anjay_next_planned_lifecycle_operation | ( | anjay_t * | anjay, |
| anjay_ssid_t | ssid | ||
| ) |
Returns the time at which next outgoing lifecycle message is planned to be sent if no outside intervention that might reschedule it (e.g. change of Lifetime - either by user code or from a server) happens until that time.
Lifecycle operations may include:
NOTE: This function may internally perform conversion between time values attached to different clocks (real-time clock vs. monotonic clock), which depends on immediate readings of those clocks. For this reason, the calculated value may slightly change from call to call, even if no action was performed in between. This accuracy depends on the accuracy of the underlying clocks as well as CPU performance. It is generally expected to be accurate within single-digit milliseconds, but it is recommended to avoid code that would perform direct comparisons on those values.
| anjay | Anjay object to operate on. |
| ssid | Either one of:
|
AVS_TIME_REAL_INVALID if there are none. | avs_time_real_t anjay_next_planned_notify_trigger | ( | anjay_t * | anjay, |
| anjay_ssid_t | ssid | ||
| ) |
Returns the time at which the earliest notification trigger is scheduled if no outside intervention that might reschedule it (e.g. anjay_notify_changed or a Write Attributes request from a server) happens until that time.
Notification trigger checks value of one or more resources and might send a notification (if the resource value actually changed and other criteria specified by the <NOTIFICATION> Class attributes are met), but it might also not cause any action. In this sense, the time point returned by this function is the earliest point in time at which a notification MAY be generated, i.e. the lower bound estimate for time of the nearest notification.
Notification triggers may be scheduled:
The point in time is calculated for one specific server, or for all known servers at once. In versions that include the SMS commercial feature, only the primary connections are included (including the case where SMS transport is the only one in use for a given Server Account), secondary SMS Trigger connections are not.
| anjay | Anjay object to operate on. |
| ssid | A Short Server ID of a single regular LwM2M Server for which to get the information, or ANJAY_SSID_ANY to get time of the nearest notification trigger scheduled for any known server connection. |
AVS_TIME_REAL_INVALID if there are none. | avs_time_real_t anjay_next_planned_pmax_notify_trigger | ( | anjay_t * | anjay, |
| anjay_ssid_t | ssid | ||
| ) |
Returns the time at which the earliest notification trigger based on the Maximum Period attribute is scheduled if no outside intervention that might reschedule it (e.g. anjay_notify_changed or a Write Attributes request from a server) happens until that time.
This type of notification triggers are scheduled after sending each notification, for after a period of time specified by the Maximum Period attribute. In this sense, the time point returned by this function is the earliest point in time at which a notification is REQUIRED to be generated, i.e. the upper bound estimate for time of a the nearest notification.
The point in time is calculated for one specific server, or for all known servers at once. In versions that include the SMS commercial feature, only the primary connections are included (including the case where SMS transport is the only one in use for a given Server Account), secondary SMS Trigger connections are not.
| anjay | Anjay object to operate on. |
| ssid | A Short Server ID of a single regular LwM2M Server for which to get the information, or ANJAY_SSID_ANY to get time of the nearest notification trigger based on the Maximum Period attribute scheduled for any known server connection. |
AVS_TIME_REAL_INVALID if there are none. | bool anjay_ongoing_registration_exists | ( | anjay_t * | anjay | ) |
Returns false if registration to all LwM2M Servers either succeeded or failed with no more retries pending and true if a registration or bootstrap is in progress.
|
inlinestatic |
Function replaced with anjay_registration_expiration_time_with_status(), which support LwM2M 1.2.
Returns the time at which the lifetime of a registration to a given LwM2M Server expires.
Note that this is not the time at which the Update message will be sent. Update messages are planned for MAX_TRANSMIT_WAIT before the expiration time (or at halfway between last registration update and the expiration time if that is less than MAX_TRANSMIT_WAIT) to allow some leeway to make sure that the registration is renewed strictly before it expires.
If you want to retrieve the information about the next scheduled Update operation, please use anjay_next_planned_lifecycle_operation.
| anjay | Anjay object to operate on. |
| ssid | Short Server ID of a non-bootstrap LwM2M Server for which to get the information. |
AVS_TIME_REAL_INVALID if there is no active registration for a given server or no such server connection exists. | avs_time_real_t anjay_registration_expiration_time_with_status | ( | anjay_t * | anjay, |
| anjay_ssid_t | ssid, | ||
| anjay_registration_expiration_status_t * | out_status | ||
| ) |
Returns the time at which the lifetime of a registration to a given LwM2M Server expires. Returns the registration status through an inout parameter out_status.
Note that this is not the time at which the Update message will be sent. Update messages are planned for MAX_TRANSMIT_WAIT before the expiration time (or at halfway between last registration update and the expiration time if that is less than MAX_TRANSMIT_WAIT) to allow some leeway to make sure that the registration is renewed strictly before it expires.
If you want to retrieve the information about the next scheduled Update operation, please use anjay_next_planned_lifecycle_operation.
| anjay | Anjay object to operate on. |
| ssid | Short Server ID of a non-bootstrap LwM2M Server for which to get the information. |
| out_status | Status of expiration. |
AVS_TIME_REAL_INVALID if there is no active registration for a given server or no such server connection exists. AVS_TIME_REAL_INVALID is returned also in case of inifinite lifetime | int anjay_sched_calculate_wait_time_ms | ( | anjay_t * | anjay, |
| int | limit_ms | ||
| ) |
Calculates time in milliseconds the client code may wait for incoming events before the need to call anjay_sched_run .
This function combines anjay_sched_time_to_next_ms with a user-provided limit, so that a conclusive value will always be returned. It is provided as a convenience for users of system calls such as poll().
| anjay | Anjay object to operate on. |
| limit_ms | The longest amount of time the function shall return. |
limit_ms seconds from now, or limit_ms otherwise. | void anjay_sched_run | ( | anjay_t * | anjay | ) |
Runs all scheduled events which need to be invoked at or before the time of this function invocation.
| anjay | Anjay object to operate on. |
| int anjay_sched_time_to_next | ( | anjay_t * | anjay, |
| avs_time_duration_t * | out_delay | ||
| ) |
Determines time of next scheduled task.
May be used to determine how long the device may wait before calling anjay_sched_run .
| anjay | Anjay object to operate on. | |
| [out] | out_delay | Relative time from now of next scheduled task. |
| int anjay_sched_time_to_next_ms | ( | anjay_t * | anjay, |
| int * | out_delay_ms | ||
| ) |
Determines time of next scheduled task in milliseconds.
This function is equivalent to anjay_sched_time_to_next but, as a convenience for users of system calls such as poll(), the result is returned as a single integer number of milliseconds.
| anjay | Anjay object to operate on. | |
| [out] | out_delay_ms | Relative time from now of next scheduled task, in milliseconds. |
| int anjay_schedule_bootstrap_request | ( | anjay_t * | anjay | ) |
Schedules sending a Bootstrap-Request message to the LwM2M Bootstrap Server.
The Bootstrap-Request will be sent during one of subsequent anjay_sched_run calls.
| anjay | Anjay object to operate on. |
| int anjay_schedule_register | ( | anjay_t * | anjay, |
| anjay_ssid_t | ssid | ||
| ) |
Schedules sending a Register message to the server identified by given Short Server ID.
For currently connected servers, the Register message will be sent during the next anjay_sched_run call, without reconnecting (and thus without a new DTLS handshake, if applicable). Please additionally call anjay_server_schedule_reconnect before or after this function (without running anjay_sched_run in between - so in multi-threaded applications you may need to do that from within an intermediary scheduler job) if you want to force a reconnect.
For servers that are disabled or in a failure state, this function will invalidate the registration state, so that a new Register message will definitely be sent once the server is re-enabled (even if the DTLS session is successfully resumed), but will not re-enable it itself. Please additionally call anjay_enable_server before or after this funciton if you want the server reactivated immediately.
Note: This function will not change the offline state of the server's transport.
| anjay | Anjay object to operate on. |
| ssid | Short Server ID of the server to send Register to or ANJAY_SSID_ANY to send Register to all known servers. NOTE: Since Register is not useful for the Bootstrap Server, this function does not send one for ANJAY_SSID_BOOTSTRAP ssid . |
| int anjay_schedule_registration_update | ( | anjay_t * | anjay, |
| anjay_ssid_t | ssid | ||
| ) |
Schedules sending an Update message to the server identified by given Short Server ID.
The Update will be sent during the next anjay_sched_run call.
Note: This function will not schedule registration update if Anjay is in offline mode.
| anjay | Anjay object to operate on. |
| ssid | Short Server ID of the server to send Update to or ANJAY_SSID_ANY to send Updates to all connected servers. NOTE: Since Updates are not useful for the Bootstrap Server, this function does not send one for ANJAY_SSID_BOOTSTRAP ssid . |
| int anjay_security_config_from_dm | ( | anjay_t * | anjay, |
| anjay_security_config_t * | out_config, | ||
| const char * | uri | ||
| ) |
Queries security configuration appropriate for a specified URI.
Given a URI, the Security object is scanned for instances with Server URI resource matching it in the following way:
The returned security information is exactly the same configuration that is used for LwM2M connection with the server chosen with the rules described above.
| anjay | Anjay object whose data model shall be queried. |
| out_config | Pointer to an anjay_security_config_t structure that will be filled with the appropriate information, if found. |
| uri | URI for which to find security configuration. |
NOTE: The returned structure will contain pointers to buffers allocated within the anjay object. They will only be valid until next call to anjay_security_config_from_dm() or anjay_serve. Note that this is enough for direct use in anjay_fw_update_get_security_config_t implementations. If you need this information for a longer period, you will need to manually create a deep copy.
In particular, you may need to implement additional synchronization to achieve thread safety if calling this function from multiple threads. Instead, it is recommended to only call it from callback functions called from within Anjay, or in scheduler jobs.
| anjay_security_config_t anjay_security_config_pkix | ( | anjay_t * | anjay | ) |
Returns the security configuration that Anjay is configured to use for X.509 certificate-based security, if no server-specific certificate is known, but PKIX certificate validation is requested.
The returned security information is determined by the default_tls_ciphersuites, use_system_trust_store, trust_store_certs and trust_store_crls fields of anjay_configuration_t, which may be overridden by an /est/crts request if est_cacerts_policy is set to ANJAY_EST_CACERTS_IF_EST_CONFIGURED or ANJAY_EST_CACERTS_ALWAYS.
NOTE: Pointers in the returned structure will point to internal Anjay structures. Attempting to modify or deallocate them will result in undefined behavior.
NOTE: If no valid trust store is available, an unsafe "trust everything" configuration is returned (security_info.data.cert.server_cert_validation is set to false).
| int anjay_serve | ( | anjay_t * | anjay, |
| avs_net_socket_t * | ready_socket | ||
| ) |
Reads a message from given ready_socket and handles it appropriately.
Initially, the receive method on the underlying socket is called with receive timeout set to zero. Subsequent receive requests may block with non-zero timeout values when e.g. waiting for retransmissions or subsequent BLOCK chunks - this is necessary to hide this complexity from the user callbacks in streaming mode.
This function may handle more than one request at once. Upon successful return, it is guaranteed that there is no more data to be received on the socket at the moment.
| anjay | Anjay object to operate on. |
| ready_socket | A socket to read the message from. |
| int anjay_serve_any | ( | anjay_t * | anjay, |
| avs_time_duration_t | max_wait_time | ||
| ) |
Executes select() or poll() on all sockets currently in use and calls anjay_serve if appropriate.
This is intended as a building block for custom event loops. In particular, this code:
while (true) { anjay_serve_any(anjay, max_wait_time); anjay_sched_run(anjay); }
is equivalent to anjay_event_loop_run(anjay, max_wait_time), as long as anjay_event_loop_interrupt is never called.
CAUTION: Most of the caveats described in the documentation for anjay_event_loop_run also apply to this function. Please refer there for more information.
| anjay | Anjay object to operate on. |
| max_wait_time | Maximum time to spend in poll() or select(). |
| int anjay_server_schedule_reconnect | ( | anjay_t * | anjay, |
| anjay_ssid_t | ssid | ||
| ) |
Reconnects sockets associated with a specific LwM2M Server.
The reconnection will be performed during the next anjay_sched_run call and will trigger sending any messages necessary to maintain valid registration (DTLS session resumption and/or Register or Update operations).
If the server connection is disconnected due to queue mode, and there are no outstanding messages (Register, Update, Notify or Send), the socket will not be reconnected.
If the server is in a disabled state, an error will be returned. Use anjay_enable_server if you want to re-enable such a server.
| anjay | Anjay object to operate on. |
| ssid | Short Server ID of the server to reconnect. |
| int anjay_set_queue_mode_preference | ( | anjay_t * | anjay, |
| anjay_queue_mode_preference_t | preference | ||
| ) |
Configures the client's usage of the LwM2M Queue Mode.
Please see the documentation of anjay_queue_mode_preference_t for the description of available configurations. The default value is ANJAY_PREFER_ONLINE_MODE.
NOTE: Changing the Queue Mode status of an existing registration is not possible without sending the Register (for LwM2M 1.1) or Update (for LwM2M 1.0) message again. For this reason, this call does NOT immediately take effect for connections that already have active registrations at the time of a call to this function. The changes will be applied at the time when next Register or Update message is scheduled to be sent. If you wish to apply the queue mode state change immediately, you can call either of anjay_schedule_registration_update, anjay_schedule_reconnect, anjay_transport_schedule_reconnect, anjay_exit_offline, anjay_transport_exit_offline or anjay_transport_set_online .
NOTE: The queue mode preference is persisted and restored by anjay_new_from_core_persistence and anjay_delete_with_core_persistence .
| anjay | Anjay object to operate on. |
| preference | Queue Mode preference to use. |
preference is not any of the supported values. | int anjay_transport_enter_offline | ( | anjay_t * | anjay, |
| anjay_transport_set_t | transport_set | ||
| ) |
Puts all the transports specified by transport_set into offline mode. This should be done when the connectivity for these transports is deemed unavailable or lost.
During subsequent calls to anjay_sched_run, Anjay will close all of the sockets corresponding to the specified transport and stop attempting to make any contact with remote hosts over it, until a call to anjay_transport_exit_offline for any of the corresponding transports.
Note that offline mode also affects downloads. E.g., putting the TCP transport into offline mode will pause all ongoing downloads over TCP and prevent new such download requests from being performed.
User code shall still interface normally with the library, even if all the transports are in the offline state. This include regular calls to anjay_sched_run. Notifications (as reported using anjay_notify_changed and anjay_notify_instances_changed) continue to be tracked, and may be sent after reconnecting, depending on values of the "Notification Storing When Disabled or Offline" resource.
| anjay | Anjay object to operate on. |
| transport_set | Set of transports to put into offline mode. |
| int anjay_transport_exit_offline | ( | anjay_t * | anjay, |
| anjay_transport_set_t | transport_set | ||
| ) |
Puts all the transports specified by transport_set back into online mode, if any of them were previously put into offline mode using anjay_transport_enter_offline.
Transports that are unavailable due to compile-time or runtime configuration are ignored.
During subsequent calls to anjay_sched_run, new connections to all LwM2M servers disconnected due to offline mode will be attempted, and Register or Registration Update messages will be sent as appropriate. Downloads paused due to offline mode will be resumed as well.
| anjay | Anjay object to operate on. |
| transport_set | Set of transports to put into online mode. |
| bool anjay_transport_has_unsent_notifications | ( | anjay_t * | anjay, |
| anjay_transport_set_t | transport_set | ||
| ) |
Returns whether there are some notifications which have been postponed to be sent later on any of the given transports, either due to the connection being offline or a previous failure to send some notification.
In versions that do not include the SMS commercial feature, or if no SMS trigger connections exist, anjay_transport_has_unsent_notifications(anjay, ANJAY_TRANSPORT_SET_ALL) is equivalent to anjay_has_unsent_notifications(anjay, ANJAY_SSID_ANY). In contrast to that function, both primary and secondary (SMS trigger) connections are queried, if present. Different transport sets may be used to filter the set of server connections queried to only those for which the connection transport matches the provided set.
| anjay | Anjay object to operate on. |
| transport_set | Set of transports to include in the check. |
| bool anjay_transport_is_offline | ( | anjay_t * | anjay, |
| anjay_transport_set_t | transport_set | ||
| ) |
Checks whether all the specified transports are in offline mode.
| anjay | Anjay object to operate on. |
| transport_set | Set of transports to check. |
transport_set are in offline mode, false otherwise | avs_time_real_t anjay_transport_next_planned_lifecycle_operation | ( | anjay_t * | anjay, |
| anjay_transport_set_t | transport_set | ||
| ) |
Returns the time at which next outgoing lifecycle message is planned to be sent via any of the given transports if no outside intervention that might reschedule it (e.g. change of Lifetime - either by user code or from a server) happens until that time.
anjay_transport_next_planned_lifecycle_operation(anjay, ANJAY_TRANSPORT_SET_ALL) is mostly equivalent to anjay_next_planned_lifecycle_operation(anjay, ANJAY_SSID_ANY) (see below for more details). Different transport sets may be used to filter the set of server connections queried to only those for which the last known transport matches the provided set.
Server connection entries which have not yet been matched to any transport are ignored. Such entries may exist for a short time between refreshing the list of known servers (triggered e.g. by adding a new instance to the Security or Server object) and the actual attempt to connect to that server, as those two actions are performed in separate runs of anjay_sched_run. During that brief period when such entries exist, anjay_next_planned_lifecycle_operation(anjay, ANJAY_SSID_ANY) will return the current time, while anjay_transport_next_planned_lifecycle_operation(anjay, ANJAY_TRANSPORT_SET_ALL) may return time of some later planned operation or AVS_TIME_REAL_INVALID.
| anjay | Anjay object to operate on. |
| transport_set | Set of transports to include in calculation. |
AVS_TIME_REAL_INVALID if there are none. | avs_time_real_t anjay_transport_next_planned_notify_trigger | ( | anjay_t * | anjay, |
| anjay_transport_set_t | transport_set | ||
| ) |
Returns the time at which the earliest notification trigger is scheduled for any of the given transports if no outside intervention that might reschedule it (e.g. anjay_notify_changed or a Write Attributes request from a server) happens until that time.
In versions that do not include the SMS commercial feature, or if no SMS trigger connections exist, anjay_transport_next_planned_notify_trigger(anjay, ANJAY_TRANSPORT_SET_ALL) is equivalent to anjay_next_planned_notify_trigger(anjay, ANJAY_SSID_ANY). In contrast to that function, both primary and secondary (SMS trigger) connections are queried, if present. Different transport sets may be used to filter the set of server connections queried to only those for which the connection transport matches the provided set.
| anjay | Anjay object to operate on. |
| transport_set | Set of transports to include in calculation. |
AVS_TIME_REAL_INVALID if there are none. | avs_time_real_t anjay_transport_next_planned_pmax_notify_trigger | ( | anjay_t * | anjay, |
| anjay_transport_set_t | transport_set | ||
| ) |
Returns the time at which the earliest notification trigger based on the Maximum Period attribute is scheduled for any given transports if no outside intervention that might reschedule it (e.g. anjay_notify_changed or a Write Attributes request from a server) happens until that time.
In versions that do not include the SMS commercial feature, or if no SMS trigger connections exist, anjay_transport_next_planned_pmax_notify_trigger(anjay, ANJAY_TRANSPORT_SET_ALL) is equivalent to anjay_next_planned_pmax_notify_trigger(anjay, ANJAY_SSID_ANY). In contrast to that function, both primary and secondary (SMS trigger) connections are queried, if present. Different transport sets may be used to filter the set of server connections queried to only those for which the connection transport matches the provided set.
| anjay | Anjay object to operate on. |
| transport_set | Set of transports to include in calculation. |
AVS_TIME_REAL_INVALID if there are none. | int anjay_transport_schedule_reconnect | ( | anjay_t * | anjay, |
| anjay_transport_set_t | transport_set | ||
| ) |
Reconnects sockets associated with all servers and ongoing downloads over the specified transports. Should be called if something related to the connectivity over those transports changes.
The reconnection will be performed during the next anjay_sched_run call and will trigger sending any messages necessary to maintain valid registration (DTLS session resumption and/or Register or Update operations).
In case of ongoing downloads (started via anjay_download or the fw_update module), if the reconnection fails, the download will be aborted with an error.
Note: This function puts all the transports in transport_set into online mode.
| anjay | Anjay object to operate on. |
| transport_set | Set of transports whose sockets shall be reconnected. |
| int anjay_transport_set_online | ( | anjay_t * | anjay, |
| anjay_transport_set_t | transport_set | ||
| ) |
Puts all the transports that are enabled through the compile-time and runtime configuration, and specified in transport_set, into online mode. At the same time, puts all the other transports into offline mode.
This function combines the functionality of anjay_transport_enter_offline and anjay_transport_exit_offline into a single function. See their documentation for details about the semantics of online and offline modes.
| anjay | Anjay object to operate on. |
| transport_set | Set of transports to put into online mode. |
| avs_error_t anjay_update_coap_exchange_timeout | ( | anjay_t * | anjay, |
| anjay_transport_set_t | transport_set, | ||
| avs_time_duration_t | exchange_timeout | ||
| ) |
Changes the CoAP exchange update timeout for given transports.
| anjay | Anjay object to operate on. |
| transport_set | Set of transport for which the exchange update timeout should be changed. |
| exchange_update_timeout | New exchange update timeout. |
| avs_error_t anjay_update_dtls_handshake_timeouts | ( | anjay_t * | anjay, |
| avs_net_dtls_handshake_timeouts_t | dtls_handshake_timeouts | ||
| ) |
Changes handshake timeouts for sockets that communicate using DTLS over UDP.
| anjay | Anjay object to operate on. |
| dtls_handshake_timeouts | New DTLS handshake timeouts. |
| avs_error_t anjay_update_transport_tx_params | ( | anjay_t * | anjay, |
| anjay_transport_set_t | transport_set, | ||
| const avs_coap_udp_tx_params_t * | tx_params | ||
| ) |
Changes transmission parameters for given transports.
| anjay | Anjay object to operate on. |
| transport_set | Set of transports for which parameters should be changed. |
| tx_params | New transmission parameters. |
|
extern |
anjay_transport_set_t constant with all fields set to true.
|
extern |
anjay_transport_set_t constant with udp and tcp fields set to true.
NOTE: In the open-source version, ANJAY_TRANSPORT_SET_ALL and ANJAY_TRANSPORT_SET_IP are equivalent.
|
extern |
anjay_transport_set_t constant with just the nidd field set to true.
|
extern |
anjay_transport_set_t constant with just the sms field set to true.
|
extern |
anjay_transport_set_t constant with just the tcp field set to true.
|
extern |
anjay_transport_set_t constant with just the udp field set to true.
1.9.1