#include <anjay/anjay_config.h>
#include <anjay/dm.h>

Data Structures
struct	anjay_sw_mgmt_instance_initializer_t

struct	anjay_sw_mgmt_handlers_t

struct	anjay_sw_mgmt_settings_t

Macros
Software update result codes
The following result codes may be returned from anjay_sw_mgmt_stream_write_t or anjay_sw_mgmt_stream_finish_t to control the value of Update Result resource in case of an error. Their values correspond to negated numeric values of that resource. However, attempting to use other negated value will be checked and cause a fall-back to a value default for a given handler.
#define	ANJAY_SW_MGMT_ERR_NOT_ENOUGH_SPACE (-(int) ANJAY_SW_MGMT_UPDATE_RESULT_NOT_ENOUGH_SPACE)

#define	ANJAY_SW_MGMT_ERR_OUT_OF_MEMORY (-(int) ANJAY_SW_MGMT_UPDATE_RESULT_OUT_OF_MEMORY)

#define	ANJAY_SW_MGMT_ERR_INTEGRITY_FAILURE (-(int) ANJAY_SW_MGMT_UPDATE_RESULT_INTEGRITY_FAILURE)

#define	ANJAY_SW_MGMT_ERR_UNSUPPORTED_PACKAGE_TYPE (-(int) ANJAY_SW_MGMT_UPDATE_RESULT_UNSUPPORTED_PACKAGE_TYPE)

Typedefs
typedef int	anjay_sw_mgmt_stream_open_t(void obj_ctx, anjay_iid_t iid, void inst_ctx)

typedef int	anjay_sw_mgmt_stream_write_t(void obj_ctx, anjay_iid_t iid, void inst_ctx, const void *data, size_t length)

typedef int	anjay_sw_mgmt_stream_finish_t(void obj_ctx, anjay_iid_t iid, void inst_ctx)

typedef int	anjay_sw_mgmt_check_integrity_t(void obj_ctx, anjay_iid_t iid, void inst_ctx)

typedef void	anjay_sw_mgmt_reset_t(void obj_ctx, anjay_iid_t iid, void inst_ctx)

typedef const char *	anjay_sw_mgmt_get_name_t(void obj_ctx, anjay_iid_t iid, void inst_ctx)

typedef const char *	anjay_sw_mgmt_get_version_t(void obj_ctx, anjay_iid_t iid, void inst_ctx)

typedef int	anjay_sw_mgmt_pkg_install_t(void obj_ctx, anjay_iid_t iid, void inst_ctx)

typedef int	anjay_sw_mgmt_pkg_uninstall_t(void obj_ctx, anjay_iid_t iid, void inst_ctx)

typedef int	anjay_sw_mgmt_prepare_for_update_t(void obj_ctx, anjay_iid_t iid, void inst_ctx)

typedef int	anjay_sw_mgmt_activate_t(void obj_ctx, anjay_iid_t iid, void inst_ctx)

typedef int	anjay_sw_mgmt_deactivate_t(void obj_ctx, anjay_iid_t iid, void inst_ctx)

typedef int	anjay_sw_mgmt_get_security_config_t(void obj_ctx, anjay_iid_t iid, void inst_ctx, const char download_uri, anjay_security_config_t out_security_info)

typedef avs_coap_udp_tx_params_t	anjay_sw_mgmt_get_coap_tx_params_t(void obj_ctx, anjay_iid_t iid, void inst_ctx, const char *download_uri)

typedef avs_time_duration_t	anjay_sw_mgmt_get_tcp_request_timeout_t(void obj_ctx, anjay_iid_t iid, void inst_ctx, const char *download_uri)

typedef int	anjay_sw_mgmt_add_handler_t(void obj_ctx, anjay_iid_t iid, void *out_inst_ctx)

typedef int	anjay_sw_mgmt_remove_handler_t(void obj_ctx, anjay_iid_t iid, void inst_ctx)

Enumerations
enum	anjay_sw_mgmt_update_result_t { ANJAY_SW_MGMT_UPDATE_RESULT_INITIAL = 0 , ANJAY_SW_MGMT_UPDATE_RESULT_DOWNLOADING = 1 , ANJAY_SW_MGMT_UPDATE_RESULT_INSTALLED = 2 , ANJAY_SW_MGMT_UPDATE_RESULT_DOWNLOADED_VERIFIED = 3 , ANJAY_SW_MGMT_UPDATE_RESULT_NOT_ENOUGH_SPACE = 50 , ANJAY_SW_MGMT_UPDATE_RESULT_OUT_OF_MEMORY = 51 , ANJAY_SW_MGMT_UPDATE_RESULT_CONNECTION_LOST = 52 , ANJAY_SW_MGMT_UPDATE_RESULT_INTEGRITY_FAILURE = 53 , ANJAY_SW_MGMT_UPDATE_RESULT_UNSUPPORTED_PACKAGE_TYPE = 54 , ANJAY_SW_MGMT_UPDATE_RESULT_INVALID_URI = 56 , ANJAY_SW_MGMT_UPDATE_RESULT_UPDATE_ERROR = 57 , ANJAY_SW_MGMT_UPDATE_RESULT_INSTALLATION_FAILURE = 58 , ANJAY_SW_MGMT_UPDATE_RESULT_UNINSTALLATION_FAILURE = 59 }

enum	anjay_sw_mgmt_initial_state_t { ANJAY_SW_MGMT_INITIAL_STATE_IDLE , ANJAY_SW_MGMT_INITIAL_STATE_DOWNLOADED , ANJAY_SW_MGMT_INITIAL_STATE_DELIVERED , ANJAY_SW_MGMT_INITIAL_STATE_INSTALLING , ANJAY_SW_MGMT_INITIAL_STATE_INSTALLED_DEACTIVATED , ANJAY_SW_MGMT_INITIAL_STATE_INSTALLED_ACTIVATED }

enum	anjay_sw_mgmt_finish_pkg_install_result_t { ANJAY_SW_MGMT_FINISH_PKG_INSTALL_SUCCESS_INACTIVE , ANJAY_SW_MGMT_FINISH_PKG_INSTALL_SUCCESS_ACTIVE , ANJAY_SW_MGMT_FINISH_PKG_INSTALL_FAILURE }

Functions
void	anjay_sw_mgmt_pull_suspend (anjay_t *anjay)

int	anjay_sw_mgmt_pull_reconnect (anjay_t *anjay)

int	anjay_sw_mgmt_install (anjay_t anjay, const anjay_sw_mgmt_settings_t settings)

int	anjay_sw_mgmt_get_activation_state (anjay_t anjay, anjay_iid_t iid, bool out_state)

int	anjay_sw_mgmt_finish_pkg_install (anjay_t *anjay, anjay_iid_t iid, anjay_sw_mgmt_finish_pkg_install_result_t pkg_install_result)

int	anjay_sw_mgmt_add_instance (anjay_t anjay, const anjay_sw_mgmt_instance_initializer_t instance_initializer)

int	anjay_sw_mgmt_remove_instance (anjay_t *anjay, anjay_iid_t iid)

Macro Definition Documentation

◆ ANJAY_SW_MGMT_ERR_INTEGRITY_FAILURE

#define ANJAY_SW_MGMT_ERR_INTEGRITY_FAILURE (-(int) ANJAY_SW_MGMT_UPDATE_RESULT_INTEGRITY_FAILURE)

◆ ANJAY_SW_MGMT_ERR_NOT_ENOUGH_SPACE

#define ANJAY_SW_MGMT_ERR_NOT_ENOUGH_SPACE (-(int) ANJAY_SW_MGMT_UPDATE_RESULT_NOT_ENOUGH_SPACE)

◆ ANJAY_SW_MGMT_ERR_OUT_OF_MEMORY

#define ANJAY_SW_MGMT_ERR_OUT_OF_MEMORY (-(int) ANJAY_SW_MGMT_UPDATE_RESULT_OUT_OF_MEMORY)

◆ ANJAY_SW_MGMT_ERR_UNSUPPORTED_PACKAGE_TYPE

#define ANJAY_SW_MGMT_ERR_UNSUPPORTED_PACKAGE_TYPE (-(int) ANJAY_SW_MGMT_UPDATE_RESULT_UNSUPPORTED_PACKAGE_TYPE)

Typedef Documentation

◆ anjay_sw_mgmt_activate_t

typedef int anjay_sw_mgmt_activate_t(void *obj_ctx, anjay_iid_t iid, void *inst_ctx)

Experimental:: This is experimental Software Management object API. This API can change in future versions without any notice.

Activates software package.

This callback will be called only in Installed state. The activation state does not affect the execution of this callback. If the user wants to block the execution when the package is already active, this must be done on user side. The anjay_sw_mgmt_get_activation_state function may be useful.

Some of the users will want to opt-out from ability to handle the activation state - if this callback is not implemented at all (with the corresponding field set to NULL), executing Activate resource will always succeed. If this callback is not implemented, anjay_sw_mgmt_deactivate_t MUST NOT be implemented too.

Parameters

obj_ctx	Opaque pointer to object-wide user data, as passed to anjay_sw_mgmt_settings_t .
iid	ID of Software Management object instance.
inst_ctx	Opaque pointer to instance-specific user data, as passed to anjay_sw_mgmt_instance_initializer_t or `out_inst_ctx` parameter of anjay_sw_mgmt_add_handler_t .

Returns: The callback shall return 0 if successful or a negative value in case of error or when user do not want to execute this callback. Error codes are NOT handled here, so attempting to return ANJAY_SW_MGMT_ERR_* values will NOT cause any effect different than any other negative value.

◆ anjay_sw_mgmt_add_handler_t

typedef int anjay_sw_mgmt_add_handler_t(void *obj_ctx, anjay_iid_t iid, void **out_inst_ctx)

Experimental:: This is experimental Software Management object API. This API can change in future versions without any notice.

Handles server's request to create new instance of Software Management object.

This callback allows the user to set up user-specific data or to reject server's attempt to create a new object instance.

If this handler is not implemented at all (with the corresponding field set to NULL), library won't allow creating new instances of the object.

This callback won't be called if the application adds a new instance of the object on its own.

Parameters

obj_ctx	Opaque pointer to object-wide user data, as passed to anjay_sw_mgmt_settings_t .
iid	ID of Software Management object instance.
out_inst_ctx	Pointer in which the handler shall fill in opaque pointer to instance-specific user data.

Returns: The callback shall return 0 if successful or a negative value in case of error. Error codes are NOT handled here, so attempting to return ANJAY_SW_MGMT_ERR_* values will NOT cause any effect different than any other negative value.

◆ anjay_sw_mgmt_check_integrity_t

typedef int anjay_sw_mgmt_check_integrity_t(void *obj_ctx, anjay_iid_t iid, void *inst_ctx)

Experimental:: This is experimental Software Management object API. This API can change in future versions without any notice.

Conducts integrity check of downloaded package.

If this handler is not implemented at all (with the corresponding field set to NULL), integrity check will be entirely skipped, and the Update State resource upon finished download will change the state directly from Download started to Delivered.

Parameters

obj_ctx	Opaque pointer to object-wide user data, as passed to anjay_sw_mgmt_settings_t .
iid	ID of Software Management object instance.
inst_ctx	Opaque pointer to instance-specific user data, as passed to anjay_sw_mgmt_instance_initializer_t or `out_inst_ctx` parameter of anjay_sw_mgmt_add_handler_t .

Returns: The callback shall return 0 if successful or a negative value in case of error. If one of the ANJAY_SW_MGMT_ERR_* value is returned, an equivalent value will be set in the Update Result Resource.

◆ anjay_sw_mgmt_deactivate_t

typedef int anjay_sw_mgmt_deactivate_t(void *obj_ctx, anjay_iid_t iid, void *inst_ctx)

Experimental:: This is experimental Software Management object API. This API can change in future versions without any notice.

Deactivates software package.

This callback will be called only in Installed state. The activation state does not affect the execution of this callback. If the user wants to block the execution when the package is already deactivate, this must be done on user side. The anjay_sw_mgmt_get_activation_state function may be useful.

Some of the users will want to opt-out from ability to handle the activation state - if this callback is not implemented at all (with the corresponding field set to NULL), executing Deactivate resource will always succeed. If this callback is not implemented, anjay_sw_mgmt_activate_t MUST NOT be implemented too.

Parameters

obj_ctx	Opaque pointer to object-wide user data, as passed to anjay_sw_mgmt_settings_t .
iid	ID of Software Management object instance.
inst_ctx	Opaque pointer to instance-specific user data, as passed to anjay_sw_mgmt_instance_initializer_t or `out_inst_ctx` parameter of anjay_sw_mgmt_add_handler_t .

Returns: The callback shall return 0 if successful or a negative value in case of error or when user do not want to execute this callback. Error codes are NOT handled here, so attempting to return ANJAY_SW_MGMT_ERR_* values will NOT cause any effect different than any other negative value.

◆ anjay_sw_mgmt_get_coap_tx_params_t

typedef avs_coap_udp_tx_params_t anjay_sw_mgmt_get_coap_tx_params_t(void *obj_ctx, anjay_iid_t iid, void *inst_ctx, const char *download_uri)

Experimental:: This is experimental Software Management object API. This API can change in future versions without any notice.

Returns tx_params used to override default ones.

If this handler is not implemented at all (with the corresponding field set to NULL), udp_tx_params from anjay_t object are used.

Parameters

obj_ctx	Opaque pointer to object-wide user data, as passed to anjay_sw_mgmt_settings_t .
iid	ID of Software Management object instance.
inst_ctx	Opaque pointer to instance-specific user data, as passed to anjay_sw_mgmt_instance_initializer_t or `out_inst_ctx` parameter of anjay_sw_mgmt_add_handler_t .
download_uri	Target software URI.

Returns: Object with CoAP transmission parameters.

◆ anjay_sw_mgmt_get_name_t

typedef const char * anjay_sw_mgmt_get_name_t(void *obj_ctx, anjay_iid_t iid, void *inst_ctx)

Experimental:: This is experimental Software Management object API. This API can change in future versions without any notice.

Returns the name of downloaded software package.

The name will be exposed in the data model as the PkgName Resource. If this callback returns NULL or is not implemented at all (with the corresponding field set to NULL), that Resource will have its value set to empty string.

It only makes sense for this handler to return non-NULL values if there is a valid package already downloaded. The library will call this handler in Delivered and Installed states.

The library will not attempt to deallocate the returned pointer. User code must assure that the pointer will remain valid at least until return from anjay_serve or anjay_sched_run .

Parameters

obj_ctx	Opaque pointer to object-wide user data, as passed to anjay_sw_mgmt_settings_t .
iid	ID of Software Management object instance.
inst_ctx	Opaque pointer to instance-specific user data, as passed to anjay_sw_mgmt_instance_initializer_t or `out_inst_ctx` parameter of anjay_sw_mgmt_add_handler_t .

Returns: The callback shall return a pointer to a null-terminated string containing the package name, or NULL if it is not currently available.

◆ anjay_sw_mgmt_get_security_config_t

typedef int anjay_sw_mgmt_get_security_config_t(void *obj_ctx, anjay_iid_t iid, void *inst_ctx, const char *download_uri, anjay_security_config_t *out_security_info)

Experimental:: This is experimental Software Management object API. This API can change in future versions without any notice.

Queries security information that shall be used for an encrypted connection with a PULL-mode download server.

May be called before anjay_sw_mgmt_stream_open if the download is to be performed in PULL mode and the connection needs to use TLS or DTLS encryption.

Note that the anjay_security_config_t contains references to file paths, binary security keys, and/or ciphersuite lists. It is the user's responsibility to appropriately allocate them and ensure proper lifetime of the returned pointers. The returned security information may only be invalidated in a call to anjay_sw_mgmt_reset_t or after a call to anjay_delete .

If this handler is not implemented at all (with the corresponding field set to NULL), anjay_security_config_from_dm will be used as a default way to get security information.

WARNING: If the aforementioned anjay_security_config_from_dm function won't find any server connection that matches the download_uri by protocol, hostname and port triple, it'll attempt to match a configuration just by the hostname. This may cause Anjay to use wrong security configuration, e.g. in case when both CoAPS LwM2M server and HTTPS software package server have the same hostname, but require different security configs.

If no user-defined handler is provided and the call to anjay_security_config_from_dm fails (including case when no matching LwM2M Security Object instance is found, even just by the hostname), anjay_security_config_pkix will be used as an additional fallback if ANJAY_WITH_LWM2M11 is enabled and a valid trust store is available (either specified through use_system_trust_store, trust_store_certs or trust_store_crls fields in anjay_configuration_t, or obtained via /est/crts request if est_cacerts_policy is set to ANJAY_EST_CACERTS_IF_EST_CONFIGURED or ANJAY_EST_CACERTS_ALWAYS).

You may also use these functions yourself, for example as a fallback mechanism.

Parameters

obj_ctx	Opaque pointer to object-wide user data, as passed to anjay_sw_mgmt_settings_t .
iid	ID of Software Management object instance.
inst_ctx	Opaque pointer to instance-specific user data, as passed to anjay_sw_mgmt_instance_initializer_t or `out_inst_ctx` parameter of anjay_sw_mgmt_add_handler_t .
download_uri	URI of the package from which a Pull-mode download is performed.
out_security_info	Pointer in which the handler shall fill in security configuration to use for download. Note that leaving this value as empty without filling it in will result in a configuration that is valid, but very insecure: it will cause any server certificate to be accepted without validation. Any pointers used within the supplied structure shall remain valid until either a call to anjay_sw_mgmt_reset_t, or exit to the event loop (from either anjay_serve, anjay_sched_run or anjay_sw_mgmt_add_instance), whichever happens first. Anjay will not attempt to deallocate anything automatically.

Returns: The callback shall return 0 if successful or a negative value in case of error. Error codes are NOT handled here, so attempting to return ANJAY_SW_MGMT_ERR_* values will NOT cause any effect different than any other negative value.

◆ anjay_sw_mgmt_get_tcp_request_timeout_t

typedef avs_time_duration_t anjay_sw_mgmt_get_tcp_request_timeout_t(void *obj_ctx, anjay_iid_t iid, void *inst_ctx, const char *download_uri)

Experimental:: This is experimental Software Management object API. This API can change in future versions without any notice.

Returns request timeout to be used during software download over CoAP+TCP or HTTP.

If this handler is not implemented at all (with the corresponding field set to NULL), coap_tcp_request_timeout from anjay_t object will be used for CoAP+TCP, and AVS_NET_SOCKET_DEFAULT_RECV_TIMEOUT (i.e., 30 seconds) will be used for HTTP.

Parameters

obj_ctx	Opaque pointer to object-wide user data, as passed to anjay_sw_mgmt_settings_t .
iid	ID of Software Management object instance.
inst_ctx	Opaque pointer to instance-specific user data, as passed to anjay_sw_mgmt_instance_initializer_t or `out_inst_ctx` parameter of anjay_sw_mgmt_add_handler_t .
download_uri	Target software URI.

Returns: The desired request timeout. If the value returned is non-positive (including zero and invalid value), the default will be used.

◆ anjay_sw_mgmt_get_version_t

typedef const char * anjay_sw_mgmt_get_version_t(void *obj_ctx, anjay_iid_t iid, void *inst_ctx)

Experimental:: This is experimental Software Management object API. This API can change in future versions without any notice.

Returns the version of downloaded software package.

The version will be exposed in the data model as the PkgVersion Resource. If this callback returns NULL or is not implemented at all (with the corresponding field set to NULL), that Resource will have its value set to empty string.

It only makes sense for this handler to return non-NULL values if there is a valid package already downloaded. The library will call this handler in Delivered and Installed states.

The library will not attempt to deallocate the returned pointer. User code must assure that the pointer will remain valid at least until return from anjay_serve or anjay_sched_run .

Parameters

obj_ctx	Opaque pointer to object-wide user data, as passed to anjay_sw_mgmt_settings_t .
iid	ID of Software Management object instance.
inst_ctx	Opaque pointer to instance-specific user data, as passed to anjay_sw_mgmt_instance_initializer_t or `out_inst_ctx` parameter of anjay_sw_mgmt_add_handler_t .

Returns: The callback shall return a pointer to a null-terminated string containing the package name, or NULL if it is not currently available.

◆ anjay_sw_mgmt_pkg_install_t

typedef int anjay_sw_mgmt_pkg_install_t(void *obj_ctx, anjay_iid_t iid, void *inst_ctx)

Experimental:: This is experimental Software Management object API. This API can change in future versions without any notice.

Performs the actual installation of previously downloaded software package.

Will be called at the request of the server, after a package has been downloaded and its integrity has been checked.

Some users will want to implement software installation in a way that involves a reboot. In such case, it is expected that this callback will do either one of the following:

software package installation, terminate outermost event loop and return, call reboot after anjay_event_loop_run()
perform the software package installation internally and then reboot, it means that the return will never happen (although the library won't be able to send the acknowledgement of execution of Install resource)

After rebooting, the result of the installation process may be passed to the library during initialization via the initial_state field of anjay_sw_mgmt_instance_initializer_t .

Alternatively, if the installation can be performed without reinitializing Anjay, you can use anjay_sw_mgmt_finish_pkg_install (either from within the handler or some time after returning from it) to pass the installation result.

Parameters

obj_ctx	Opaque pointer to object-wide user data, as passed to anjay_sw_mgmt_settings_t .
iid	ID of Software Management object instance.
inst_ctx	Opaque pointer to instance-specific user data, as passed to anjay_sw_mgmt_instance_initializer_t or `out_inst_ctx` parameter of anjay_sw_mgmt_add_handler_t .

Returns: The callback shall return a negative value if it can be determined without a reboot that the package installation cannot be successfully performed. Error codes are NOT handled here, so attempting to return ANJAY_SW_MGMT_ERR_* values will NOT cause any effect different than any other negative value.

◆ anjay_sw_mgmt_pkg_uninstall_t

typedef int anjay_sw_mgmt_pkg_uninstall_t(void *obj_ctx, anjay_iid_t iid, void *inst_ctx)

Experimental:: This is experimental Software Management object API. This API can change in future versions without any notice.

Uninstalls software package.

This callback will be called only in Installed state, if the Uninstall resource was executed with no argument or argument "0".

If this callback is not implemented at all (with the corresponding field set to NULL), uninstalling software will not be possible.

Note: in case the server requests to remove the software package which has been delivered, but not yet installed (Delivered state), anjay_sw_mgmt_reset_t callback will be used.

Parameters

obj_ctx	Opaque pointer to object-wide user data, as passed to anjay_sw_mgmt_settings_t .
iid	ID of Software Management object instance.
inst_ctx	Opaque pointer to instance-specific user data, as passed to anjay_sw_mgmt_instance_initializer_t or `out_inst_ctx` parameter of anjay_sw_mgmt_add_handler_t .

Returns: The callback shall return 0 if successful or a negative value in case of error. Error codes are NOT handled here, so attempting to return ANJAY_SW_MGMT_ERR_* values will NOT cause any effect different than any other negative value.

◆ anjay_sw_mgmt_prepare_for_update_t

typedef int anjay_sw_mgmt_prepare_for_update_t(void *obj_ctx, anjay_iid_t iid, void *inst_ctx)

Experimental:: This is experimental Software Management object API. This API can change in future versions without any notice.

Prepares software package for update.

This callback will be called only in Installed state, if the Uninstall resource was executed with argument "1".

If this callback is not implemented at all (with the corresponding field set to NULL), updating software will not be possible.

Most users will want to implement this callback as a no-op.

Parameters

obj_ctx	Opaque pointer to object-wide user data, as passed to anjay_sw_mgmt_settings_t .
iid	ID of Software Management object instance.
inst_ctx	Opaque pointer to instance-specific user data, as passed to anjay_sw_mgmt_instance_initializer_t or `out_inst_ctx` parameter of anjay_sw_mgmt_add_handler_t .

Returns: The callback shall return 0 if successful or a negative value in case of error. Error codes are NOT handled here, so attempting to return ANJAY_SW_MGMT_ERR_* values will NOT cause any effect different than any other negative value.

◆ anjay_sw_mgmt_remove_handler_t

typedef int anjay_sw_mgmt_remove_handler_t(void *obj_ctx, anjay_iid_t iid, void *inst_ctx)

Experimental:: This is experimental Software Management object API. This API can change in future versions without any notice.

Handles server's request to remove an instance of Software Management object.

This callback allows the user to clean up user-specific data or to reject server's attempt to remove an object instance.

If this handler is not implemented at all (with the corresponding field set to NULL), library won't allow deleting instances of the object.

Parameters

obj_ctx	Opaque pointer to object-wide user data, as passed to anjay_sw_mgmt_settings_t .
iid	ID of Software Management object instance.
inst_ctx	Opaque pointer to instance-specific user data, as passed to anjay_sw_mgmt_instance_initializer_t or `out_inst_ctx` parameter of anjay_sw_mgmt_add_handler_t .

Returns: The callback shall return 0 if successful or a negative value in case of error. Error codes are NOT handled here, so attempting to return ANJAY_SW_MGMT_ERR_* values will NOT cause any effect different than any other negative value.

◆ anjay_sw_mgmt_reset_t

typedef void anjay_sw_mgmt_reset_t(void *obj_ctx, anjay_iid_t iid, void *inst_ctx)

Experimental:: This is experimental Software Management object API. This API can change in future versions without any notice.

Resets the software installation state and performs any applicable cleanup of temporary storage if necessary.

Will be called at request of the server (upon execution of Uninstall resource in Delivered state in purpose of removing downloaded, but not yet installed software package) or after a failed download. Note that it may be called without previously calling anjay_sw_mgmt_stream_finish_t, so it shall also close the currently open download stream, if any.

Parameters

obj_ctx	Opaque pointer to object-wide user data, as passed to anjay_sw_mgmt_settings_t .
iid	ID of Software Management object instance.
inst_ctx	Opaque pointer to instance-specific user data, as passed to anjay_sw_mgmt_instance_initializer_t or `out_inst_ctx` parameter of anjay_sw_mgmt_add_handler_t .

◆ anjay_sw_mgmt_stream_finish_t

typedef int anjay_sw_mgmt_stream_finish_t(void *obj_ctx, anjay_iid_t iid, void *inst_ctx)

Experimental:: This is experimental Software Management object API. This API can change in future versions without any notice.

Closes the download stream.

Will be called after a series of anjay_sw_mgmt_stream_write_t calls after the whole package is downloaded.

The intended way of implementing this handler is to e.g. call fclose() on the downloaded file. After that, package might also be uncompressed, decrypted and checked for integrity in anjay_sw_mgmt_check_integrity_t . The exact split of responsibility between these two methods is not clearly defined and up to implementor.

Note that regardless of the return value, the stream is considered to be closed. That is, upon successful return, the Update State resource is considered to be either in the Downloaded state, and upon returning an error - in the Initial state, with appropriate Update Result set.

Parameters

obj_ctx	Opaque pointer to object-wide user data, as passed to anjay_sw_mgmt_settings_t .
iid	ID of Software Management object instance.
inst_ctx	Opaque pointer to instance-specific user data, as passed to anjay_sw_mgmt_instance_initializer_t or `out_inst_ctx` parameter of anjay_sw_mgmt_add_handler_t .

Returns: The callback shall return 0 if successful or a negative value in case of error. If one of the ANJAY_SW_MGMT_ERR_* value is returned, an equivalent value will be set in the Update Result Resource.

◆ anjay_sw_mgmt_stream_open_t

typedef int anjay_sw_mgmt_stream_open_t(void *obj_ctx, anjay_iid_t iid, void *inst_ctx)

Experimental:: This is experimental Software Management object API. This API can change in future versions without any notice.

Opens the stream that will be used to write the software package to.

The intended way of implementing this handler is to open a temporary file using fopen() or allocate some memory buffer that may then be used to store the downloaded data in. The library will not attempt to call anjay_sw_mgmt_stream_write_t without having previously called anjay_sw_mgmt_stream_open_t . Please see anjay_sw_mgmt_handlers_t for more information about state transitions.

Parameters

obj_ctx	Opaque pointer to object-wide user data, as passed to anjay_sw_mgmt_settings_t .
iid	ID of Software Management object instance.
inst_ctx	Opaque pointer to instance-specific user data, as passed to anjay_sw_mgmt_instance_initializer_t or `out_inst_ctx` parameter of anjay_sw_mgmt_add_handler_t .

Returns: The callback shall return 0 if successful or a negative value in case of error. Error codes are NOT handled here, so attempting to return ANJAY_SW_MGMT_ERR_* values will NOT cause any effect different than any other negative value.

◆ anjay_sw_mgmt_stream_write_t

typedef int anjay_sw_mgmt_stream_write_t(void *obj_ctx, anjay_iid_t iid, void *inst_ctx, const void *data, size_t length)

Experimental:: This is experimental Software Management object API. This API can change in future versions without any notice.

Writes data to the download stream.

May be called multiple times after anjay_sw_mgmt_stream_open_t, once for each consecutive chunk of downloaded data.

Parameters

obj_ctx	Opaque pointer to object-wide user data, as passed to anjay_sw_mgmt_settings_t .
iid	ID of Software Management object instance.
inst_ctx	Opaque pointer to instance-specific user data, as passed to anjay_sw_mgmt_instance_initializer_t or `out_inst_ctx` parameter of anjay_sw_mgmt_add_handler_t .
data	Pointer to a chunk of the software package being downloaded. Guaranteed to be non-`NULL`.
length	Number of bytes in the chunk pointed to by `data`. Guaranteed to be greater than zero.

Returns: The callback shall return 0 if successful or a negative value in case of error. If one of the ANJAY_SW_MGMT_ERR_* value is returned, an equivalent value will be set in the Update Result Resource.

Enumeration Type Documentation

◆ anjay_sw_mgmt_finish_pkg_install_result_t

enum anjay_sw_mgmt_finish_pkg_install_result_t

Experimental:: This is experimental Software Management object API. This API can change in future versions without any notice.

Possible values that control package state after installation.

Enumerator

ANJAY_SW_MGMT_FINISH_PKG_INSTALL_SUCCESS_INACTIVE

Corresponds to the "Installed" Update State, "Installed" Update Result and Activation State set to false.

ANJAY_SW_MGMT_FINISH_PKG_INSTALL_SUCCESS_ACTIVE

Corresponds to the "Installed" Update State, "Installed" Update Result and Activation State set to true.

WARNING: Setting the Activation State to true via anjay_sw_mgmt_finish_pkg_install breaks the specifications. Activation should be done on the server side. However, there are known cases in which such behavior is required.

ANJAY_SW_MGMT_FINISH_PKG_INSTALL_FAILURE

Corresponds to the "Delivered" Update State, "Installation failure" Update Result and Activation State set to false.

◆ anjay_sw_mgmt_initial_state_t

enum anjay_sw_mgmt_initial_state_t

Experimental:: This is experimental Software Management object API. This API can change in future versions without any notice.

Possible values that control Update State, Update Result and Activation State resources at the time of initialization of the Software Management object.

Enumerator
ANJAY_SW_MGMT_INITIAL_STATE_IDLE	Corresponds to the "Initial" Update State and "Initial" Update Result. Shall be used for software instances which are not yet downloaded. Note: "Initial" Update State and "Initial" Update Result can be also caused by preparing installed software for update process (by executing Uninstall resource with "1" argument), although, in case of a reboot, it is recommended to revert back to "Installed" Update State by initializing the object instance with ANJAY_SW_MGMT_INITIAL_STATE_INSTALLED_DEACTIVATED or ANJAY_SW_MGMT_INITIAL_STATE_INSTALED_ACTIVATED . Software Management Object in its current state is not able to differentiate these two situations.
ANJAY_SW_MGMT_INITIAL_STATE_DOWNLOADED	Corresponds to the "Downloaded" Update State and "Initial" Update Result. Shall be used when the device unexpectedly rebooted when the software package has already been downloaded into some non-volatile memory and integrity check wasn't performed yet.
ANJAY_SW_MGMT_INITIAL_STATE_DELIVERED	Corresponds to the "Delivered" Update State and "Initial" Update Result. Shall be used when the device unexpectedly rebooted when the software package has already been downloaded into some non-volatile memory and integrity check was performed.
ANJAY_SW_MGMT_INITIAL_STATE_INSTALLING	Corresponds to the "Delivered" Update State and "Initial" Update Result. Shall be used when the device has rebooted as a part of installation process, which hasn't completed yet. The application should call anjay_sw_mgmt_finish_pkg_install to set the result to success or failure after the installation process is complete.
ANJAY_SW_MGMT_INITIAL_STATE_INSTALLED_DEACTIVATED	Corresponds to the "Installed" Update State, "Installed" Update Result and Activation State set to false. Shall be used when given software instance is installed, but deactivated.
ANJAY_SW_MGMT_INITIAL_STATE_INSTALLED_ACTIVATED	Corresponds to the "Installed" Update State, "Installed" Update Result and Activation State set to true. Shall be used when given software instance is installed and activated.

◆ anjay_sw_mgmt_update_result_t

enum anjay_sw_mgmt_update_result_t

Numeric values of the Update Result resource. See LwM2M specification related to object 9 for details.

Enumerator
ANJAY_SW_MGMT_UPDATE_RESULT_INITIAL
ANJAY_SW_MGMT_UPDATE_RESULT_DOWNLOADING
ANJAY_SW_MGMT_UPDATE_RESULT_INSTALLED
ANJAY_SW_MGMT_UPDATE_RESULT_DOWNLOADED_VERIFIED
ANJAY_SW_MGMT_UPDATE_RESULT_NOT_ENOUGH_SPACE
ANJAY_SW_MGMT_UPDATE_RESULT_OUT_OF_MEMORY
ANJAY_SW_MGMT_UPDATE_RESULT_CONNECTION_LOST
ANJAY_SW_MGMT_UPDATE_RESULT_INTEGRITY_FAILURE
ANJAY_SW_MGMT_UPDATE_RESULT_UNSUPPORTED_PACKAGE_TYPE
ANJAY_SW_MGMT_UPDATE_RESULT_INVALID_URI
ANJAY_SW_MGMT_UPDATE_RESULT_UPDATE_ERROR
ANJAY_SW_MGMT_UPDATE_RESULT_INSTALLATION_FAILURE
ANJAY_SW_MGMT_UPDATE_RESULT_UNINSTALLATION_FAILURE

Function Documentation

◆ anjay_sw_mgmt_add_instance()

int anjay_sw_mgmt_add_instance	(	anjay_t *	anjay,
		const anjay_sw_mgmt_instance_initializer_t *	instance_initializer
	)

Experimental:: This is experimental Software Management object API. This API can change in future versions without any notice.

Adds an instance of Software Management object.

This method will not cause anjay_sw_mgmt_add_handler_t to be called, as this method creates a new instance of the object on application's request.

Parameters

anjay	Anjay object for which the Software Management Object is installed.
instance_initializer	Information about the state to initialize the Software Management object instance in.

Returns: 0 on success, or a negative value in case of error.

◆ anjay_sw_mgmt_finish_pkg_install()

int anjay_sw_mgmt_finish_pkg_install	(	anjay_t *	anjay,
		anjay_iid_t	iid,
		anjay_sw_mgmt_finish_pkg_install_result_t	pkg_install_result
	)

Experimental:: This is experimental Software Management object API. This API can change in future versions without any notice.

Marks delivered software package as installed and optionally activated, making transition to Installed state or reports installation error.

WARNING: Calling this function is only valid in Delivered state, directly in the anjay_sw_mgmt_pkg_install_t handler, or in some later point of time, possibly after a reboot, as explained in anjay_sw_mgmt_pkg_install_t .

NOTE: Setting activation state with this function does NOT mean that activation ( anjay_sw_mgmt_activate_t ) or deactivation ( anjay_sw_mgmt_deactivate_t ) software package handler will be called. Setting activation state to true after installation breaks the specifications, but there are known cases when this behavior is required.

NOTE: If this function is called inside anjay_sw_mgmt_pkg_install_t handler with pkg_install_result set to ANJAY_SW_MGMT_FINISH_PKG_INSTALL_SUCCESS_INACTIVE or ANJAY_SW_MGMT_FINISH_PKG_INSTALL_SUCCESS_ACTIVE , the handler is expected to return 0. Otherwise, returning nonzero value will cause the result set by this function being overwritten.

Parameters

anjay	Anjay object for which the Software Management Object is installed.
iid	ID of Software Management object instance.
pkg_install_result	Result of the installation process.

Returns: 0 on success, or a negative value in case of error.

◆ anjay_sw_mgmt_get_activation_state()

int anjay_sw_mgmt_get_activation_state	(	anjay_t *	anjay,
		anjay_iid_t	iid,
		bool *	out_state
	)

Experimental:: This is experimental Software Management object API. This API can change in future versions without any notice.

Checks if the instance state is Installed and return the activation state via out_state argument. Can be used in anjay_sw_mgmt_activate_t or anjay_sw_mgmt_deactivate_t to check if we want to proceed with current activation state with the code responsible for activation/deactivation the package.

Parameters

anjay	Anjay object for which the Software Management Object is installed.
iid	ID of Software Management object instance.
out_state	Activation state of Software Management object instance.

Returns: 0 on success, -1 if there is no such instance or instance state is different than Installed

◆ anjay_sw_mgmt_install()

int anjay_sw_mgmt_install	(	anjay_t *	anjay,
		const anjay_sw_mgmt_settings_t *	settings
	)

Experimental:: This is experimental Software Management object API. This API can change in future versions without any notice.

Installs the Software Management object in an Anjay object.

The Software Management module does not require explicit cleanup; all resources will be automatically freed up during the call to anjay_delete.

Specific instances of Software Management object shall be created using anjay_sw_mgmt_add_instance . It is desirable to create all instances expected by the server before the first call to anjay_event_loop_run , anjay_serve or anjay_sched_run , to make sure that they are present from the beginning of the device registration.

Parameters

anjay	Anjay object for which the Software Management Object is installed.
settings	Configuration of Software Management module, see anjay_sw_mgmt_settings_t for details.

Returns: 0 on success, or a negative value in case of error.

◆ anjay_sw_mgmt_pull_reconnect()

int anjay_sw_mgmt_pull_reconnect ( anjay_t * anjay )

Experimental:: This is experimental Software Management object API. This API can change in future versions without any notice.

Reconnects any ongoing PULL-mode downloads in the Software Management module. Which could be disconnected due to connection loss or deliberate suspend. In the latter case, when PULL-mode downloads are suspended (see anjay_sw_mgmt_pull_suspend), resumes normal operation.

If an ongoing PULL-mode download exists, this will call anjay_download_reconnect internally, so you may want to reference the documentation of that function for details.

Parameters

anjay Anjay object to operate on.

Returns: 0 on success; -1 if anjay does not have the Software Management object installed or the latest non-zero error code returned by anjay_download_reconnect .

◆ anjay_sw_mgmt_pull_suspend()

void anjay_sw_mgmt_pull_suspend ( anjay_t * anjay )

Experimental:: This is experimental Software Management object API. This API can change in future versions without any notice.

Suspends the operation of PULL-mode downloads in the Software Management module.

This will have the effect of suspending any ongoing downloads (see anjay_download_suspend for details), as well as preventing new downloads from being started.

When PULL-mode downloads are suspended, anjay_sw_mgmt_stream_open_t will NOT be called when a download request is issued. However, anjay_sw_mgmt_get_security_config_t, anjay_sw_mgmt_get_coap_tx_params_t and anjay_sw_mgmt_get_tcp_request_timeout_t will be called. You may call anjay_sw_mgmt_pull_reconnect from one of these functions if you decide to accept the download immediately after all.

Parameters

anjay Anjay object to operate on.

◆ anjay_sw_mgmt_remove_instance()

int anjay_sw_mgmt_remove_instance	(	anjay_t *	anjay,
		anjay_iid_t	iid
	)

Experimental:: This is experimental Software Management object API. This API can change in future versions without any notice.

Remove an instance of Software Management object.

This method will not cause anjay_sw_mgmt_remove_handler_t to be called, as this method deletes a instance of the object on application's request.

CAUTION: Calling this function inside any Software Management module handler with the same iid as passed to the handler, will result in an error code with value 1. This function shouldn't be called from any module handler. In multi-threaded scenarios, it should be expected that this function can also return an error code with value 1, in case one thread calls this function when another thread is executing one of the module's handler associated with the instance with the same iid as the one passed to this function. In this case, the user should wait a while and call this function again.

Parameters

anjay	Anjay object for which the Software Management Object is installed.
iid	ID of Software Management object instance.

Returns: 0 on success; 1 if a handler associated with an instance with the same iid as the one passed to this function is currently being executed; a negative value in case of error

Data Structures

Macros

Typedefs

Enumerations

Functions

Macro Definition Documentation

◆ ANJAY_SW_MGMT_ERR_INTEGRITY_FAILURE

◆ ANJAY_SW_MGMT_ERR_NOT_ENOUGH_SPACE

◆ ANJAY_SW_MGMT_ERR_OUT_OF_MEMORY

◆ ANJAY_SW_MGMT_ERR_UNSUPPORTED_PACKAGE_TYPE

Typedef Documentation

◆ anjay_sw_mgmt_activate_t

◆ anjay_sw_mgmt_add_handler_t

◆ anjay_sw_mgmt_check_integrity_t

◆ anjay_sw_mgmt_deactivate_t

◆ anjay_sw_mgmt_get_coap_tx_params_t

◆ anjay_sw_mgmt_get_name_t

◆ anjay_sw_mgmt_get_security_config_t

◆ anjay_sw_mgmt_get_tcp_request_timeout_t

◆ anjay_sw_mgmt_get_version_t

◆ anjay_sw_mgmt_pkg_install_t

◆ anjay_sw_mgmt_pkg_uninstall_t

◆ anjay_sw_mgmt_prepare_for_update_t

◆ anjay_sw_mgmt_remove_handler_t

◆ anjay_sw_mgmt_reset_t

◆ anjay_sw_mgmt_stream_finish_t

◆ anjay_sw_mgmt_stream_open_t

◆ anjay_sw_mgmt_stream_write_t

Enumeration Type Documentation

◆ anjay_sw_mgmt_finish_pkg_install_result_t

◆ anjay_sw_mgmt_initial_state_t

◆ anjay_sw_mgmt_update_result_t

Function Documentation

◆ anjay_sw_mgmt_add_instance()

◆ anjay_sw_mgmt_finish_pkg_install()

◆ anjay_sw_mgmt_get_activation_state()

◆ anjay_sw_mgmt_install()

◆ anjay_sw_mgmt_pull_reconnect()

◆ anjay_sw_mgmt_pull_suspend()

◆ anjay_sw_mgmt_remove_instance()