Callback Types

Callback function pointer types of the OTA library. More...

Typedefs
typedef void(*	OtaAppCallback_t) (OtaJobEvent_t eEvent, void *pData)
	OTA update complete callback function typedef. More...

Detailed Description

Callback function pointer types of the OTA library.

Typedef Documentation

OtaAppCallback_t

typedef void(* OtaAppCallback_t) (OtaJobEvent_t eEvent, void *pData)

OTA update complete callback function typedef.

The user must register a callback function when initializing the OTA Agent. This callback is used to notify the main application when the OTA update job is complete. Typically, it is used to reset the device after a successful update by calling OTA_ActivateNewImage and may also be used to kick off user specified self tests during the Self Test phase.

The callback function is called with one of the following arguments:

 OtaJobEventActivate           OTA update is authenticated and ready to activate.
 OtaJobEventFail               OTA update failed. Unable to use this update.
 OtaJobEventStartTest          OTA job is now ready for optional user self tests.
 OtaJobEventProcessed          Event OTA got from user has been handled.
 OtaJobEventSelfTestFailed     OTA update failed in self-test.
 OtaJobEventParseCustomJob     OTA got an unknown job from cloud, need user to check
                               if it's a custom job.
 OtaJobEventReceivedJob        OTA event when a new valid job is received.
 OtaJobEventUpdateComplete     OTA event when the update is completed.
 OtaJobEventNoActiveJob        OTA event when no active job is pending.

When OtaJobEventActivate is received, the job status details have been updated with the state as ready for Self Test. After reboot, the new firmware will (normally) be notified that it is in the Self Test phase via the callback and the application may then optionally run its own tests before committing the new image.

If the callback function is called with a result of OtaJobEventFail, the OTA update job has failed in some way and should be rejected.

When OtaJobEventStartTest is received, the load is first boot after OTA. Users can set the image state to OtaImageStateAccepted if the load is verified.

When OtaJobEventProcessed is received, the event (OtaAgentEventReceivedJobDocument) sent from user has been handled. User can free the buffer when receiving this callback.

When OtaJobEventSelfTestFailed is received, that means the load is failed on verification. And the device is going to reboot after this callback.

When OtaJobEventParseCustomJob is received, that means OTA received an unknown job from cloud. User can parse the job by casting pData to OtaJobDocument_t, then check the pJobDocJson and pJobId in the document. User should set the result to parseErr if it's a custom job.

When OtaJobEventReceivedJob is received, that means OTA has addressed the json file provided by user successfully. Let user know to handler the buffer.

When OtaJobEventUpdateComplete is received, that means OTA has downloaded a full image for the file type which is different from configOTA_FIRMWARE_UPDATE_FILE_TYPE_ID.

When OtaJobEventNoActiveJob is received, that means OTA has received a job document without valid job ID and job document key.

Parameters

[in]	eEvent	An OTA update event from the OtaJobEvent_t enum.
[in]	pData	Optional data related to the event.

eEvent	Structure of pData	Variable in pData
OtaJobEventActivate	OtaJobDocument_t	status and reason
OtaJobEventFail	OtaJobDocument_t	status, reason and subReason
OtaJobEventStartTest	NULL	nothing
OtaJobEventProcessed	OtaEventData_t	data buffer inputed from user by OTA_SignalEvent
OtaJobEventSelfTestFailed	NULL	nothing
OtaJobEventParseCustomJob	OtaJobDocument_t	pJobId, jobIdLength, pJobDocJson, and jobDocLength
OtaJobEventReceivedJob	OtaJobDocument_t	pJobId, jobIdLength, pJobDocJson, jobDocLength, and fileTypeId
OtaJobEventUpdateComplete	OtaJobDocument_t	status, reason and subReason
OtaJobEventNoActiveJob	NULL	nothing