#include <anjay/core.h>

Data Structures
struct	anjay_advanced_fw_update_global_config_t

struct	anjay_advanced_fw_update_initial_state_t

struct	anjay_advanced_fw_update_handlers_t

Macros
#define	ANJAY_ADVANCED_FW_UPDATE_OID 33629

Advanced Firmware Update result codes
The following result codes may be returned from anjay_advanced_fw_update_stream_write_t, anjay_advanced_fw_update_stream_finish_t or anjay_advanced_fw_update_perform_upgrade_t to control the value of the Update Result Resource after the failure. 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_ADVANCED_FW_UPDATE_ERR_NOT_ENOUGH_SPACE (-(int) ANJAY_ADVANCED_FW_UPDATE_RESULT_NOT_ENOUGH_SPACE)

#define	ANJAY_ADVANCED_FW_UPDATE_ERR_OUT_OF_MEMORY (-(int) ANJAY_ADVANCED_FW_UPDATE_RESULT_OUT_OF_MEMORY)

#define	ANJAY_ADVANCED_FW_UPDATE_ERR_INTEGRITY_FAILURE (-(int) ANJAY_ADVANCED_FW_UPDATE_RESULT_INTEGRITY_FAILURE)

#define	ANJAY_ADVANCED_FW_UPDATE_ERR_UNSUPPORTED_PACKAGE_TYPE (-(int) ANJAY_ADVANCED_FW_UPDATE_RESULT_UNSUPPORTED_PACKAGE_TYPE)

#define	ANJAY_ADVANCED_FW_UPDATE_ERR_DEFERRED (-(int) ANJAY_ADVANCED_FW_UPDATE_RESULT_DEFERRED)

#define	ANJAY_ADVANCED_FW_UPDATE_ERR_CONFLICTING_STATE (-(int) ANJAY_ADVANCED_FW_UPDATE_RESULT_CONFLICTING_STATE)

#define	ANJAY_ADVANCED_FW_UPDATE_ERR_DEPENDENCY_ERROR (-(int) ANJAY_ADVANCED_FW_UPDATE_RESULT_DEPENDENCY_ERROR)

Typedefs
typedef int	anjay_advanced_fw_update_stream_open_t(anjay_iid_t iid, void *user_ptr)

typedef int	anjay_advanced_fw_update_stream_write_t(anjay_iid_t iid, void user_ptr, const void data, size_t length)

typedef int	anjay_advanced_fw_update_stream_finish_t(anjay_iid_t iid, void *user_ptr)

typedef void	anjay_advanced_fw_update_reset_t(anjay_iid_t iid, void *user_ptr)

typedef const char *	anjay_advanced_fw_update_get_pkg_name_t(anjay_iid_t iid, void *user_ptr)

typedef const char *	anjay_advanced_fw_update_get_pkg_version_t(anjay_iid_t iid, void *user_ptr)

typedef const char *	anjay_advanced_fw_update_get_current_version_t(anjay_iid_t iid, void *user_ptr)

typedef int	anjay_advanced_fw_update_perform_upgrade_t(anjay_iid_t iid, void user_ptr, const anjay_iid_t requested_supplemental_iids, size_t requested_supplemental_iids_count)

typedef int	anjay_advanced_fw_update_get_security_config_t(anjay_iid_t iid, void user_ptr, anjay_security_config_t out_security_info, const char *download_uri)

typedef avs_coap_udp_tx_params_t	anjay_advanced_fw_update_get_coap_tx_params_t(anjay_iid_t iid, void user_ptr, const char download_uri)

typedef avs_time_duration_t	anjay_advanced_fw_update_get_tcp_request_timeout_t(anjay_iid_t iid, void user_ptr, const char download_uri)

Enumerations
enum	anjay_advanced_fw_update_state_t { ANJAY_ADVANCED_FW_UPDATE_STATE_IDLE = 0 , ANJAY_ADVANCED_FW_UPDATE_STATE_DOWNLOADING , ANJAY_ADVANCED_FW_UPDATE_STATE_DOWNLOADED , ANJAY_ADVANCED_FW_UPDATE_STATE_UPDATING }

enum	anjay_advanced_fw_update_result_t { ANJAY_ADVANCED_FW_UPDATE_RESULT_INITIAL = 0 , ANJAY_ADVANCED_FW_UPDATE_RESULT_SUCCESS = 1 , ANJAY_ADVANCED_FW_UPDATE_RESULT_NOT_ENOUGH_SPACE = 2 , ANJAY_ADVANCED_FW_UPDATE_RESULT_OUT_OF_MEMORY = 3 , ANJAY_ADVANCED_FW_UPDATE_RESULT_CONNECTION_LOST = 4 , ANJAY_ADVANCED_FW_UPDATE_RESULT_INTEGRITY_FAILURE = 5 , ANJAY_ADVANCED_FW_UPDATE_RESULT_UNSUPPORTED_PACKAGE_TYPE = 6 , ANJAY_ADVANCED_FW_UPDATE_RESULT_INVALID_URI = 7 , ANJAY_ADVANCED_FW_UPDATE_RESULT_FAILED = 8 , ANJAY_ADVANCED_FW_UPDATE_RESULT_UNSUPPORTED_PROTOCOL = 9 , ANJAY_ADVANCED_FW_UPDATE_RESULT_UPDATE_CANCELLED = 10 , ANJAY_ADVANCED_FW_UPDATE_RESULT_DEFERRED = 11 , ANJAY_ADVANCED_FW_UPDATE_RESULT_CONFLICTING_STATE = 12 , ANJAY_ADVANCED_FW_UPDATE_RESULT_DEPENDENCY_ERROR = 13 }

enum	anjay_advanced_fw_update_severity_t { ANJAY_ADVANCED_FW_UPDATE_SEVERITY_CRITICAL = 0 , ANJAY_ADVANCED_FW_UPDATE_SEVERITY_MANDATORY , ANJAY_ADVANCED_FW_UPDATE_SEVERITY_OPTIONAL }

Functions
int	anjay_advanced_fw_update_install (anjay_t anjay, const anjay_advanced_fw_update_global_config_t config)

int	anjay_advanced_fw_update_instance_add (anjay_t anjay, anjay_iid_t iid, const char component_name, const anjay_advanced_fw_update_handlers_t handlers, void user_arg, const anjay_advanced_fw_update_initial_state_t *initial_state)

int	anjay_advanced_fw_update_set_state_and_result (anjay_t *anjay, anjay_iid_t iid, anjay_advanced_fw_update_state_t state, anjay_advanced_fw_update_result_t result)

int	anjay_advanced_fw_update_get_state (anjay_t anjay, anjay_iid_t iid, anjay_advanced_fw_update_state_t out_state)

int	anjay_advanced_fw_update_get_result (anjay_t anjay_locked, anjay_iid_t iid, anjay_advanced_fw_update_result_t out_result)

int	anjay_advanced_fw_update_set_linked_instances (anjay_t anjay, anjay_iid_t iid, const anjay_iid_t target_iids, size_t target_iids_count)

int	anjay_advanced_fw_update_get_linked_instances (anjay_t anjay, anjay_iid_t iid, const anjay_iid_t out_target_iids, size_t out_target_iids_count)

int	anjay_advanced_fw_update_set_conflicting_instances (anjay_t anjay, anjay_iid_t iid, const anjay_iid_t target_iids, size_t target_iids_count)

int	anjay_advanced_fw_update_get_conflicting_instances (anjay_t anjay, anjay_iid_t iid, const anjay_iid_t out_target_iids, size_t out_target_iids_count)

avs_time_real_t	anjay_advanced_fw_update_get_deadline (anjay_t *anjay, anjay_iid_t iid)

anjay_advanced_fw_update_severity_t	anjay_advanced_fw_update_get_severity (anjay_t *anjay, anjay_iid_t iid)

avs_time_real_t	anjay_advanced_fw_update_get_last_state_change_time (anjay_t *anjay, anjay_iid_t iid)

void	anjay_advanced_fw_update_pull_suspend (anjay_t *anjay)

int	anjay_advanced_fw_update_pull_reconnect (anjay_t *anjay)

Macro Definition Documentation

◆ ANJAY_ADVANCED_FW_UPDATE_ERR_CONFLICTING_STATE

#define ANJAY_ADVANCED_FW_UPDATE_ERR_CONFLICTING_STATE (-(int) ANJAY_ADVANCED_FW_UPDATE_RESULT_CONFLICTING_STATE)

◆ ANJAY_ADVANCED_FW_UPDATE_ERR_DEFERRED

#define ANJAY_ADVANCED_FW_UPDATE_ERR_DEFERRED (-(int) ANJAY_ADVANCED_FW_UPDATE_RESULT_DEFERRED)

◆ ANJAY_ADVANCED_FW_UPDATE_ERR_DEPENDENCY_ERROR

#define ANJAY_ADVANCED_FW_UPDATE_ERR_DEPENDENCY_ERROR (-(int) ANJAY_ADVANCED_FW_UPDATE_RESULT_DEPENDENCY_ERROR)

◆ ANJAY_ADVANCED_FW_UPDATE_ERR_INTEGRITY_FAILURE

#define ANJAY_ADVANCED_FW_UPDATE_ERR_INTEGRITY_FAILURE (-(int) ANJAY_ADVANCED_FW_UPDATE_RESULT_INTEGRITY_FAILURE)

◆ ANJAY_ADVANCED_FW_UPDATE_ERR_NOT_ENOUGH_SPACE

#define ANJAY_ADVANCED_FW_UPDATE_ERR_NOT_ENOUGH_SPACE (-(int) ANJAY_ADVANCED_FW_UPDATE_RESULT_NOT_ENOUGH_SPACE)

◆ ANJAY_ADVANCED_FW_UPDATE_ERR_OUT_OF_MEMORY

#define ANJAY_ADVANCED_FW_UPDATE_ERR_OUT_OF_MEMORY (-(int) ANJAY_ADVANCED_FW_UPDATE_RESULT_OUT_OF_MEMORY)

◆ ANJAY_ADVANCED_FW_UPDATE_ERR_UNSUPPORTED_PACKAGE_TYPE

#define ANJAY_ADVANCED_FW_UPDATE_ERR_UNSUPPORTED_PACKAGE_TYPE (-(int) ANJAY_ADVANCED_FW_UPDATE_RESULT_UNSUPPORTED_PACKAGE_TYPE)

◆ ANJAY_ADVANCED_FW_UPDATE_OID

#define ANJAY_ADVANCED_FW_UPDATE_OID 33629

Typedef Documentation

◆ anjay_advanced_fw_update_get_coap_tx_params_t

typedef avs_coap_udp_tx_params_t anjay_advanced_fw_update_get_coap_tx_params_t(anjay_iid_t iid, void *user_ptr, const char *download_uri)

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.

NOTE: This callback is called even for non-CoAP downloads, but the returned transmission parameters are ignored in that case.

Parameters

iid	Instance ID of an Advanced Firmware Object which query tx_params.
user_ptr	Opaque pointer to user data, as passed to anjay_advanced_fw_update_instance_add .
download_uri	Target firmware URI.

Returns: Object with CoAP transmission parameters.

◆ anjay_advanced_fw_update_get_current_version_t

typedef const char * anjay_advanced_fw_update_get_current_version_t(anjay_iid_t iid, void *user_ptr)

Returns the current version of firmware represented by Advanced Firmware Update object instance.

The version will be exposed in the data model as the Current Version Resource. If this callback returns NULL or is not implemented at all (with the corresponding field set to NULL), that Resource will not be present in the data model.

Parameters

iid	Instance ID of an Advanced Firmware Object which tries to get related current version.
user_ptr	Opaque pointer to user data, as passed to anjay_advanced_fw_update_instance_add

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

◆ anjay_advanced_fw_update_get_pkg_name_t

typedef const char * anjay_advanced_fw_update_get_pkg_name_t(anjay_iid_t iid, void *user_ptr)

Returns the name of downloaded firmware 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 not be present in the data model.

It only makes sense for this handler to return non-NULL values if there is a valid package already downloaded. The library will not call this handler in any state other than Downloaded.

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

iid	Instance ID of an Advanced Firmware Object which tries to get related package name.
user_ptr	Opaque pointer to user data, as passed to anjay_advanced_fw_update_instance_add

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_advanced_fw_update_get_pkg_version_t

typedef const char * anjay_advanced_fw_update_get_pkg_version_t(anjay_iid_t iid, void *user_ptr)

Returns the version of downloaded firmware 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 not be present in the data model.

It only makes sense for this handler to return non-NULL values if there is a valid package already downloaded. The library will not call this handler in any state other than Downloaded.

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

iid	Instance ID of an Advanced Firmware Object which tries to get related package version.
user_ptr	Opaque pointer to user data, as passed to anjay_advanced_fw_update_instance_add

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

◆ anjay_advanced_fw_update_get_security_config_t

typedef int anjay_advanced_fw_update_get_security_config_t(anjay_iid_t iid, void *user_ptr, anjay_security_config_t *out_security_info, const char *download_uri)

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

May be called before anjay_advanced_fw_update_stream_open_t 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_advanced_fw_update_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 firmware 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 those aforementioned functions (anjay_security_config_from_dm, anjay_security_config_pkix) in your callback, for example as a fallback mechanism.

Parameters

iid	Instance ID of an Advanced Firmware Object which tries to get security config.
user_ptr	Opaque pointer to user data, as passed to anjay_advanced_fw_update_instance_add
out_security_config	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_advanced_fw_update_reset_t, or exit to the event loop (from either anjay_serve, anjay_sched_run or anjay_advanced_fw_update_instance_add), whichever happens first. Anjay will not attempt to deallocate anything automatically.
download_uri	Target firmware URI.

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

◆ anjay_advanced_fw_update_get_tcp_request_timeout_t

typedef avs_time_duration_t anjay_advanced_fw_update_get_tcp_request_timeout_t(anjay_iid_t iid, void *user_ptr, const char *download_uri)

Returns request timeout to be used during firmware update 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.

NOTE: This callback is called even for non-TCP downloads, but the returned transmission parameters are ignored in that case.

Parameters

iid	Instance ID of an Advanced Firmware Object which query tx_params.
user_ptr	Opaque pointer to user data, as passed to anjay_advanced_fw_update_instance_add .
download_uri	Target firmware URI.

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

◆ anjay_advanced_fw_update_perform_upgrade_t

typedef int anjay_advanced_fw_update_perform_upgrade_t(anjay_iid_t iid, void *user_ptr, const anjay_iid_t *requested_supplemental_iids, size_t requested_supplemental_iids_count)

Performs the actual upgrade with previously downloaded package.

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

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

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

After rebooting, the result of the upgrade process may be passed to the library during initialization via the initial_result argument to anjay_advanced_fw_update_instance_add .

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

Parameters

iid	Instance ID of an Advanced Firmware Object which tries to perform upgrade.
user_ptr	Opaque pointer to user data, as passed to anjay_advanced_fw_update_instance_add
requested_supplemental_iids	Pointer to list of Advanced Firmware Object instances that server request to upgrade along with instance that this callback belongs to.
requested_supplemental_iids_count	Count of requested supplemental iids

Returns: The callback shall return a negative value if it can be determined without a reboot, that the firmware upgrade cannot be successfully performed.

If one of the ANJAY_ADVANCED_FW_UPDATE_ERR_* values is returned, an equivalent value will be set in the Update Result Resource. Otherwise, if a non-zero value is returned, the Update Result Resource is set to generic "Firmware update failed" code.

◆ anjay_advanced_fw_update_reset_t

typedef void anjay_advanced_fw_update_reset_t(anjay_iid_t iid, void *user_ptr)

Resets the firmware update state and performs any applicable cleanup of temporary storage if necessary.

Will be called at request of the server, or after a failed download. Note that it may be called without previously calling anjay_advanced_fw_update_stream_finish_t, so it shall also close the currently open download stream, if any.

Note: If reset of particular instance is done while it is in ANJAY_ADVANCED_FW_UPDATE_STATE_DOWNLOADED state, it is likely possible that it is listed as linked instance of another instance. If that is the case, it should be marked as Conflicting instance in every instance that it is linked with.

Parameters

iid	Instance ID of an Advanced Firmware Object which performs reset.
user_ptr	Opaque pointer to user data, as passed to anjay_advanced_fw_update_instance_add

◆ anjay_advanced_fw_update_stream_finish_t

typedef int anjay_advanced_fw_update_stream_finish_t(anjay_iid_t iid, void *user_ptr)

Closes the download stream and prepares the firmware package to be flashed.

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

The intended way of implementing this handler is to e.g. call fclose() and perform integrity check on the downloaded file. It might also be uncompressed or decrypted as necessary, so that it is ready to be flashed. The exact split of responsibility between anjay_advanced_fw_update_stream_finish_t and anjay_advanced_fw_update_perform_upgrade_t is not clearly defined and up to the implementor.

Note that regardless of the return value, the stream is considered to be closed. That is, upon successful return, the Advanced Firmware Update object is considered to be in the Downloaded state, and upon returning an error - in the Idle state.

Parameters

iid	Instance ID of an Advanced Firmware Object which tries to finish a stream.
user_ptr	Opaque pointer to user data, as passed to anjay_advanced_fw_update_instance_add

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

◆ anjay_advanced_fw_update_stream_open_t

typedef int anjay_advanced_fw_update_stream_open_t(anjay_iid_t iid, void *user_ptr)

Opens the stream that will be used to write the firmware 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_advanced_fw_update_stream_write_t without having previously called anjay_advanced_fw_update_stream_open_t . Please see anjay_advanced_fw_update_handlers_t for more information about state transitions.

Note that this handler will NOT be called after initializing the object with the ANJAY_ADVANCED_FW_UPDATE_STATE_DOWNLOADING option, so any necessary resources shall be already open before calling anjay_advanced_fw_update_instance_add .

Parameters

iid	Instance ID of an Advanced Firmware Object which tries to open a stream.
user_ptr	Opaque pointer to user data, as passed to anjay_advanced_fw_update_instance_add

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_ADVANCED_FW_UPDATE_ERR_* values will NOT cause any effect different than any other negative value.

◆ anjay_advanced_fw_update_stream_write_t

typedef int anjay_advanced_fw_update_stream_write_t(anjay_iid_t iid, void *user_ptr, const void *data, size_t length)

Writes data to the download stream.

May be called multipled times after anjay_advanced_fw_update_stream_open_t, once for each consecutive chunk of downloaded data.

Parameters

iid	Instance ID of an Advanced Firmware Object which tries to write to a stream.
user_ptr	Opaque pointer to user data, as passed to anjay_advanced_fw_update_instance_add
data	Pointer to a chunk of the firmware 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_ADVANCED_FW_UPDATE_ERR_* value is returned, an equivalent value will be set in the Update Result Resource.

Enumeration Type Documentation

◆ anjay_advanced_fw_update_result_t

enum anjay_advanced_fw_update_result_t

Numeric values of the Advanced Firmware Update Result resource. See AVSystem specification of Advanced Firmware Update for details.

Note: they SHOULD only be used with anjay_advanced_fw_update_set_state_and_result .

Enumerator
ANJAY_ADVANCED_FW_UPDATE_RESULT_INITIAL
ANJAY_ADVANCED_FW_UPDATE_RESULT_SUCCESS
ANJAY_ADVANCED_FW_UPDATE_RESULT_NOT_ENOUGH_SPACE
ANJAY_ADVANCED_FW_UPDATE_RESULT_OUT_OF_MEMORY
ANJAY_ADVANCED_FW_UPDATE_RESULT_CONNECTION_LOST
ANJAY_ADVANCED_FW_UPDATE_RESULT_INTEGRITY_FAILURE
ANJAY_ADVANCED_FW_UPDATE_RESULT_UNSUPPORTED_PACKAGE_TYPE
ANJAY_ADVANCED_FW_UPDATE_RESULT_INVALID_URI
ANJAY_ADVANCED_FW_UPDATE_RESULT_FAILED
ANJAY_ADVANCED_FW_UPDATE_RESULT_UNSUPPORTED_PROTOCOL
ANJAY_ADVANCED_FW_UPDATE_RESULT_UPDATE_CANCELLED
ANJAY_ADVANCED_FW_UPDATE_RESULT_DEFERRED
ANJAY_ADVANCED_FW_UPDATE_RESULT_CONFLICTING_STATE
ANJAY_ADVANCED_FW_UPDATE_RESULT_DEPENDENCY_ERROR

◆ anjay_advanced_fw_update_severity_t

enum anjay_advanced_fw_update_severity_t

Numeric values of the Advanced Firmware Update Severity resource. See AVSystem specification of Advanced Firmware Update for details.

Enumerator
ANJAY_ADVANCED_FW_UPDATE_SEVERITY_CRITICAL
ANJAY_ADVANCED_FW_UPDATE_SEVERITY_MANDATORY
ANJAY_ADVANCED_FW_UPDATE_SEVERITY_OPTIONAL

◆ anjay_advanced_fw_update_state_t

enum anjay_advanced_fw_update_state_t

Numeric values of the Advanced Firmware Update State resource. See AVSystem specification of Advanced Firmware Update for details.

Note: they SHOULD only be used with anjay_advanced_fw_update_set_state_and_result .

Enumerator
ANJAY_ADVANCED_FW_UPDATE_STATE_IDLE
ANJAY_ADVANCED_FW_UPDATE_STATE_DOWNLOADING
ANJAY_ADVANCED_FW_UPDATE_STATE_DOWNLOADED
ANJAY_ADVANCED_FW_UPDATE_STATE_UPDATING

Function Documentation

◆ anjay_advanced_fw_update_get_conflicting_instances()

int anjay_advanced_fw_update_get_conflicting_instances	(	anjay_t *	anjay,
		anjay_iid_t	iid,
		const anjay_iid_t **	out_target_iids,
		size_t *	out_target_iids_count
	)

Gets conflicting instances resource of Advance Firmware Update object instance.

When the download or update fails and the Update Result resource is set to ANJAY_ADVANCED_FW_UPDATE_RESULT_CONFLICTING_STATE or ANJAY_ADVANCED_FW_UPDATE_RESULT_DEPENDENCY_ERROR this resource MUST be present and contain references to the Advanced Firmware Update object instances that caused the conflict. See LwM2M specification for details.

NOTE: The returned array points directly into the internal structures of Anjay; however, it may only be modified by a call to anjay_advanced_fw_update_set_conflicting_instances . Nevertheless, if your code calls the "get" and "set" functions from different threads, the calls need to be additionally synchronized to achieve thread safety.

Parameters

anjay	Anjay object to operate on.
iid	Instance ID of an Advanced Firmware Object.
out_target_iids	Points to memory where to write array of iids of conflicting instances.
out_target_iids_count	Point to memory where to write count of target iids in an array.

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

◆ anjay_advanced_fw_update_get_deadline()

avs_time_real_t anjay_advanced_fw_update_get_deadline	(	anjay_t *	anjay,
		anjay_iid_t	iid
	)

Gets the update deadline based on Maximum Defer Period resource value and time of downloading full firmware.

Parameters

anjay	Anjay object to operate on.
iid	Instance ID of an Advanced Firmware Object.

Returns: Real time of the update deadline. In case of not deferring update returns AVS_TIME_REAL_INVALID.

◆ anjay_advanced_fw_update_get_last_state_change_time()

avs_time_real_t anjay_advanced_fw_update_get_last_state_change_time	(	anjay_t *	anjay,
		anjay_iid_t	iid
	)

Gets the value of Last State Change Time resource.

Parameters

anjay	Anjay object to operate on.
iid	Instance ID of an Advanced Firmware Object.

Returns: Real time of last State resource change, or AVS_TIME_REAL_INVALID on error.

◆ anjay_advanced_fw_update_get_linked_instances()

int anjay_advanced_fw_update_get_linked_instances	(	anjay_t *	anjay,
		anjay_iid_t	iid,
		const anjay_iid_t **	out_target_iids,
		size_t *	out_target_iids_count
	)

Gets linked instances resource of Advance Firmware Update object instance.

Linked instances mark instances that will be updated in a batch together when performing upgrade of a iid instance. See AVSystem specification of Advanced Firmware Update for details.

NOTE: The returned array points directly into the internal structures of Anjay; however, it may only be modified by a call to anjay_advanced_fw_update_set_linked_instances . Nevertheless, if your code calls the "get" and "set" functions from different threads, the calls need to be additionally synchronized to achieve thread safety.

Parameters

anjay	Anjay object to operate on.
iid	Instance ID of an Advanced Firmware Object.
out_target_iids	Points to memory where to write array of iids of linked instances.
out_target_iids_count	Point to memory where to write count of target iids in an array.

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

◆ anjay_advanced_fw_update_get_result()

int anjay_advanced_fw_update_get_result	(	anjay_t *	anjay_locked,
		anjay_iid_t	iid,
		anjay_advanced_fw_update_result_t *	out_result
	)

Gets the Advanced Firmware Update object instance Result.

Parameters

anjay	Anjay object to operate on.
iid	Instance ID of an Advanced Firmware Object.
out_result	Pointer to where write output result.

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

◆ anjay_advanced_fw_update_get_severity()

anjay_advanced_fw_update_severity_t anjay_advanced_fw_update_get_severity	(	anjay_t *	anjay,
		anjay_iid_t	iid
	)

Gets the update severity.

Parameters

anjay	Anjay object to operate on.
iid	Instance ID of an Advanced Firmware Object.

Returns: Severity resource value present in Firmware Update object on success, or ANJAY_ADVANCED_FW_UPDATE_SEVERITY_MANDATORY on error.

◆ anjay_advanced_fw_update_get_state()

int anjay_advanced_fw_update_get_state	(	anjay_t *	anjay,
		anjay_iid_t	iid,
		anjay_advanced_fw_update_state_t *	out_state
	)

Gets the Advanced Firmware Update object instance State.

Parameters

anjay	Anjay object to operate on.
iid	Instance ID of an Advanced Firmware Object.
out_state	Pointer to where write output state.

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

◆ anjay_advanced_fw_update_install()

int anjay_advanced_fw_update_install	(	anjay_t *	anjay,
		const anjay_advanced_fw_update_global_config_t *	config
	)

Installs the Advanced Firmware Update object in an Anjay object.

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

Parameters

anjay	Anjay object for which the Advanced Firmware Update Object is installed.
config	Provides configuration of preferred socked downloads and lwm2m send usage; anjay_advanced_fw_update_global_config_t

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

◆ anjay_advanced_fw_update_instance_add()

int anjay_advanced_fw_update_instance_add	(	anjay_t *	anjay,
		anjay_iid_t	iid,
		const char *	component_name,
		const anjay_advanced_fw_update_handlers_t *	handlers,
		void *	user_arg,
		const anjay_advanced_fw_update_initial_state_t *	initial_state
	)

Adds the Advanced Firmware Update object instance in an Advanced Firmware Update object.

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

Parameters

anjay	Anjay object for which the Advanced Firmware Update Object is installed.
iid	Instance ID of an Advanced Firmware Object.
component_name	Pointer to null-terminated component name string. Note: String is NOT copied, so it needs to remain valid for the lifetime of the object instance.
handlers	Pointer to a set of handler functions that handle the platform-specific part of firmware update process. Note: Contents of the structure are NOT copied, so it needs to remain valid for the lifetime of the object instance.
user_arg	Opaque user pointer that will be passed as the first argument to handler functions.
initial_state	Information about the state to initialize the Advanced Firmware Update object instance in. It is intended to be used after either an orderly reboot caused by a firmware update attempt to report the update result, or by an unexpected reboot in the middle of the download process. If the object shall be initialized in a neutral initial state, `NULL` might be passed.

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

◆ anjay_advanced_fw_update_pull_reconnect()

int anjay_advanced_fw_update_pull_reconnect ( anjay_t * anjay )

Reconnects any ongoing PULL-mode downloads in the Advanced Firmware Update module. Additionally, if PULL-mode downloads are suspended (see anjay_advanced_fw_update_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 for success; -1 if anjay does not have the Firmware Update object installed or if the call to anjay_download_reconnect fails.

◆ anjay_advanced_fw_update_pull_suspend()

void anjay_advanced_fw_update_pull_suspend ( anjay_t * anjay )

Suspends the operation of PULL-mode downloads in the Advanced Firmware Update 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_advanced_fw_update_stream_open_t will NOT be called when a download request is issued. However, anjay_advanced_fw_update_get_security_config_t, anjay_advanced_fw_update_get_coap_tx_params_t and anjay_advanced_fw_update_get_tcp_request_timeout_t will be called. You may call anjay_advanced_fw_update_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_advanced_fw_update_set_conflicting_instances()

int anjay_advanced_fw_update_set_conflicting_instances	(	anjay_t *	anjay,
		anjay_iid_t	iid,
		const anjay_iid_t *	target_iids,
		size_t	target_iids_count
	)

Sets conflicting instances resource of Advance Firmware Update object instance.

When the download or update fails and the Update Result resource is set to ANJAY_ADVANCED_FW_UPDATE_RESULT_CONFLICTING_STATE or ANJAY_ADVANCED_FW_UPDATE_RESULT_DEPENDENCY_ERROR this resource MUST be present and contain references to the Advanced Firmware Update object instances that caused the conflict. See LwM2M specification for details.

Parameters

anjay	Anjay object to operate on.
iid	Instance ID of an Advanced Firmware Object.
target_iids	Points to array iids of conflicting instances in relation to Advanced Firmware Update object instance `iid`. NOTE: Only already added instances only of Advanced Firmware Update object are allowed.
target_iids_count	Count of target iids in an array.

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

◆ anjay_advanced_fw_update_set_linked_instances()

int anjay_advanced_fw_update_set_linked_instances	(	anjay_t *	anjay,
		anjay_iid_t	iid,
		const anjay_iid_t *	target_iids,
		size_t	target_iids_count
	)

Sets linked instances resource of Advance Firmware Update object instance.

Linked instances mark instances that will be updated in a batch together when performing upgrade of a iid instance. See AVSystem specification of Advanced Firmware Update for details.

Parameters

anjay	Anjay object to operate on.
iid	Instance ID of an Advanced Firmware Object.
target_iids	Points to array iids of linked instances in relation to Advanced Firmware Update object instance `iid`. NOTE: Only already added instances only of Advanced Firmware Update object are allowed.
target_iids_count	Count of target iids in an array.

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

◆ anjay_advanced_fw_update_set_state_and_result()

int anjay_advanced_fw_update_set_state_and_result	(	anjay_t *	anjay,
		anjay_iid_t	iid,
		anjay_advanced_fw_update_state_t	state,
		anjay_advanced_fw_update_result_t	result
	)

Sets the Advanced Firmware Update object instance State to state and Result to result , interrupting the update process.

If the function fails, neither Update State nor Update Result are changed.

Some state transitions are disallowed and cause this function to fail:

ANJAY_ADVANCED_FW_UPDATE_RESULT_INITIAL and ANJAY_ADVANCED_FW_UPDATE_RESULT_UPDATE_CANCELLED are never allowed and cause this function to fail.
ANJAY_ADVANCED_FW_UPDATE_RESULT_SUCCESS is only allowed if the firmware application process was started by the server (an Execute operation was already performed on the Update resource of the Firmware Update object or ANJAY_ADVANCED_FW_UPDATE_STATE_UPDATING was used in a call to anjay_advanced_fw_update_instance_add). Otherwise, the function fails.
Other values of result (various error codes) are only allowed if Advanced Firmware Update State is not Idle (0), i.e. firmware is being downloaded, was already downloaded or is being applied.

WARNING: calling this in anjay_advanced_fw_update_perform_upgrade_t handler is supported, but the result of using it from within any other of anjay_advanced_fw_update_handlers_t handlers is undefined.

Parameters

anjay	Anjay object to operate on.
iid	Instance ID of an Advanced Firmware Object.
state	Value of the State resource to set.
result	Value of the Update Result resource to set.

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

Data Structures

Macros

Typedefs

Enumerations

Functions

Macro Definition Documentation

◆ ANJAY_ADVANCED_FW_UPDATE_ERR_CONFLICTING_STATE

◆ ANJAY_ADVANCED_FW_UPDATE_ERR_DEFERRED

◆ ANJAY_ADVANCED_FW_UPDATE_ERR_DEPENDENCY_ERROR

◆ ANJAY_ADVANCED_FW_UPDATE_ERR_INTEGRITY_FAILURE

◆ ANJAY_ADVANCED_FW_UPDATE_ERR_NOT_ENOUGH_SPACE

◆ ANJAY_ADVANCED_FW_UPDATE_ERR_OUT_OF_MEMORY

◆ ANJAY_ADVANCED_FW_UPDATE_ERR_UNSUPPORTED_PACKAGE_TYPE

◆ ANJAY_ADVANCED_FW_UPDATE_OID

Typedef Documentation

◆ anjay_advanced_fw_update_get_coap_tx_params_t

◆ anjay_advanced_fw_update_get_current_version_t

◆ anjay_advanced_fw_update_get_pkg_name_t

◆ anjay_advanced_fw_update_get_pkg_version_t

◆ anjay_advanced_fw_update_get_security_config_t

◆ anjay_advanced_fw_update_get_tcp_request_timeout_t

◆ anjay_advanced_fw_update_perform_upgrade_t

◆ anjay_advanced_fw_update_reset_t

◆ anjay_advanced_fw_update_stream_finish_t

◆ anjay_advanced_fw_update_stream_open_t

◆ anjay_advanced_fw_update_stream_write_t

Enumeration Type Documentation

◆ anjay_advanced_fw_update_result_t

◆ anjay_advanced_fw_update_severity_t

◆ anjay_advanced_fw_update_state_t

Function Documentation

◆ anjay_advanced_fw_update_get_conflicting_instances()

◆ anjay_advanced_fw_update_get_deadline()

◆ anjay_advanced_fw_update_get_last_state_change_time()

◆ anjay_advanced_fw_update_get_linked_instances()

◆ anjay_advanced_fw_update_get_result()

◆ anjay_advanced_fw_update_get_severity()

◆ anjay_advanced_fw_update_get_state()

◆ anjay_advanced_fw_update_install()

◆ anjay_advanced_fw_update_instance_add()

◆ anjay_advanced_fw_update_pull_reconnect()

◆ anjay_advanced_fw_update_pull_suspend()

◆ anjay_advanced_fw_update_set_conflicting_instances()

◆ anjay_advanced_fw_update_set_linked_instances()

◆ anjay_advanced_fw_update_set_state_and_result()