The Update Control API provides functions which implement update operations This section provides more information about the Update Control API.

Required Header

#include <update_control.h>

Overview

The Update Control API provides functions which implement update operations such as connect to update server, request update information, and set update configurations. It enables the application to get the update information and control the platform version of the device. Therefore this API should be used by authorized developer like platform provider only. Because the update server may have various protocols, the implementation of APIs is able to be substituted by custom functions which connect to the server serviced by each service provider. As a default implementation, the agent for STDM (SmartThings Device Manager) is offered.

Related Features

This API is related with the following features:

http://tizen.org/feature/device_update

It is recommended to design applications with regard to features, for reliability.

You can check if a device supports the related features for this API by using System Information, and control your application's actions accordingly.

To ensure your application is only running on the device with specific features, please define the features in your manifest file using the manifest editor in the SDK.

More details on using features in your application can be found in the feature element description.

Functions
int	update_control_initialize (void)
	Initializes the update controller.
int	update_control_deinitialize (void)
	Deinitializes the update controller.
int	update_control_check_new_version (void)
	Requests checking new version of firmware.
int	update_control_download_package (void)
	Requests downloading new version of firmware.
int	update_control_do_update (void)
	Triggers upgrade script and tells it to perform RO update and finish update operations (full upgrade process).
int	update_control_set_ro_update_cb (update_control_cb user_cb, const void *user_data)
	Sets a callback to trigger once RO update has completed.
int	update_control_unset_ro_update_cb (void)
	Unsets the callback set by update_control_set_ro_update_cb().
int	update_control_do_ro_update_async (void)
	Triggers upgrade script and tells it to perform ONLY RO update asynchronously.
int	update_control_set_finish_update_cb (update_control_cb user_cb, const void *user_data)
	Sets a callback to trigger once finish update operation has completed.
int	update_control_unset_finish_update_cb (void)
	Unsets the callback set by update_control_set_finish_update_cb().
int	update_control_do_finish_update_async (void)
	Triggers upgrade script and tells it to perform ONLY the finish update process asynchronously.
int	update_control_make_reservation (struct tm *reservation_time)
	Makes reservation for update.
int	update_control_cancel_reservation (void)
	Cancels the update reservation.
int	update_control_get_property (update_control_property_e property, void **value)
	Gets the update property of the given key.
Typedefs
typedef void(*	update_control_cb )(const update_control_error_e result, const void *user_data)
	Callback type to be invoked after the RO update or the finish update process finishes.

Typedef Documentation

typedef void(* update_control_cb)(const update_control_error_e result, const void *user_data)

Callback type to be invoked after the RO update or the finish update process finishes.

The callback will be triggered when the operation triggered by update_control_do_ro_update_async()
or update_control_do_finish_update_async() finishes (does not have to be successful). Examine the result parameter
to get the result of the operation. Both RO update and finish update operations can have following results:

UPDATE_CONTROL_ERROR_NONE Successful
UPDATE_CONTROL_ERROR_SYSTEM_ERROR System error
UPDATE_CONTROL_ERROR_INVALID_OPERATION Upgrade script returned an error
UPDATE_CONTROL_ERROR_NOT_SUPPORTED Not supported Finish update operation can additionally result in following:
UPDATE_CONTROL_ERROR_RO_UPDATE_IN_PROGRESS - RO update is still in progress
UPDATE_CONTROL_ERROR_RO_UPDATE_NOT_COMPLETED - RO update has not finished (and is not currently in progress),
most likely meaning the RO update has not been triggered yet

Since :: 9.0

Remarks:: This callback will be invoked in the main event loop of the client.

Parameters:

[in]	result	Result of the operation that triggered the callback
[in]	user_data	User data given when setting the callback

Precondition:: Register the callback using update_control_set_ro_update_cb() or update_control_set_finish_update_cb().
The callback will be invoked only when the operation associated with the registering function finishes.

See also:: update_control_set_ro_update_cb(); update_control_set_finish_update_cb(); update_control_unset_ro_update_cb(); update_control_unset_finish_update_cb(); update_control_do_ro_update_async(); update_control_do_finish_update_async()

Enumeration Type Documentation

enum update_control_error_e

Enumeration for the update control error.

Since :: 5.0

Enumerator:

UPDATE_CONTROL_ERROR_NONE	Successful
UPDATE_CONTROL_ERROR_INVALID_PARAMETER	Invalid parameter
UPDATE_CONTROL_ERROR_OUT_OF_MEMORY	Out of memory
UPDATE_CONTROL_ERROR_FILE_NO_SPACE_ON_DEVICE	No space left on device
UPDATE_CONTROL_ERROR_KEY_NOT_FOUND	Specified key is not available
UPDATE_CONTROL_ERROR_KEY_REJECTED	Key is not available
UPDATE_CONTROL_ERROR_NOT_SUPPORTED	Not supported
UPDATE_CONTROL_ERROR_PERMISSION_DENIED	Permission denied
UPDATE_CONTROL_ERROR_CONNECTION_ABORTED	Software caused connection abort
UPDATE_CONTROL_ERROR_CONNECTION_REFUSED	Connection refused
UPDATE_CONTROL_ERROR_PROTOCOL_NOT_SUPPORTED	Protocol not supported
UPDATE_CONTROL_ERROR_TIMED_OUT	Time out
UPDATE_CONTROL_ERROR_RESOURCE_BUSY	Device or resource busy
UPDATE_CONTROL_ERROR_INVALID_OPERATION	Function not implemented
UPDATE_CONTROL_ERROR_INVALID_PACKAGE	Invalid package
UPDATE_CONTROL_ERROR_INVALID_URI	Invalid URI
UPDATE_CONTROL_ERROR_PACKAGE_NOT_SUPPORTED	Package type not supported
UPDATE_CONTROL_ERROR_SYSTEM_ERROR	System error
UPDATE_CONTROL_ERROR_RO_UPDATE_IN_PROGRESS	RO update is in progress
UPDATE_CONTROL_ERROR_RO_UPDATE_NOT_COMPLETED	RO update has not completed

enum update_control_property_e

Enumeration for the update control properties.

Since :: 5.0

Enumerator:

UPDATE_CONTROL_PROPERTY_NEW_VERSION	New version
UPDATE_CONTROL_PROPERTY_PACKAGE_URI	URI for update package
UPDATE_CONTROL_PROPERTY_RESULT	Update result
UPDATE_CONTROL_PROPERTY_PACKAGE_SIZE	Size of update package
UPDATE_CONTROL_PROPERTY_DESCRIPTION	Update description
UPDATE_CONTROL_PROPERTY_UPDATE_AVAILABLE	Updatability flag

Function Documentation

int update_control_cancel_reservation ( void )

Cancels the update reservation.

Warning:: This is not for use by third-party applications.

Since :: 5.0

Privilege Level:: platform

Privilege:: http://tizen.org/privilege/updatecontrol.admin

Returns:: 0 on success, otherwise a negative error value

Return values:

UPDATE_CONTROL_ERROR_NONE	Successful
UPDATE_CONTROL_ERROR_NOT_SUPPORTED	Not supported
UPDATE_CONTROL_ERROR_PERMISSION_DENIED	Permission denied
UPDATE_CONTROL_ERROR_SYSTEM_ERROR	System error
UPDATE_CONTROL_ERROR_INVALID_OPERATION	Function not implemented

int update_control_check_new_version ( void )

Requests checking new version of firmware.

Since :: 5.0

Returns:: 0 on success, otherwise a negative error value

Return values:

UPDATE_CONTROL_ERROR_NONE	Successful
UPDATE_CONTROL_ERROR_NOT_SUPPORTED	Not supported
UPDATE_CONTROL_ERROR_CONNECTION_REFUSED	Connection refused
UPDATE_CONTROL_ERROR_SYSTEM_ERROR	System error
UPDATE_CONTROL_ERROR_INVALID_OPERATION	Function not implemented

int update_control_deinitialize ( void )

Deinitializes the update controller.

Since :: 5.0

Returns:: 0 on success, otherwise a negative error value

Return values:

UPDATE_CONTROL_ERROR_NONE	Successful
UPDATE_CONTROL_ERROR_NOT_SUPPORTED	Not supported
UPDATE_CONTROL_ERROR_OUT_OF_MEMORY	Out of memory
UPDATE_CONTROL_ERROR_SYSTEM_ERROR	System error
UPDATE_CONTROL_ERROR_INVALID_OPERATION	Function not implemented

See also:: update_control_initialize()

int update_control_do_finish_update_async ( void )

Triggers upgrade script and tells it to perform ONLY the finish update process asynchronously.

Warning:: This is not for use by third-party applications.

This function does not perform the RO update process.
To trigger RO use update_control_do_ro_update_async(). If you wish to trigger both operations synchronously,
use update_control_do_update().

Since :: 9.0

Privilege Level:: platform

Privilege:: http://tizen.org/privilege/updatecontrol.admin

Remarks:: This function can be used to check whether the RO update process is still in progress.

Returns:: 0 if basic checks succeeded (does not guarantee the operation triggered finished successfully),
otherwise a negative error value

Return values:

UPDATE_CONTROL_ERROR_NONE	Successful
UPDATE_CONTROL_ERROR_NOT_SUPPORTED	Not supported
UPDATE_CONTROL_ERROR_PERMISSION_DENIED	Permission denied
UPDATE_CONTROL_ERROR_SYSTEM_ERROR	System error
UPDATE_CONTROL_ERROR_INVALID_OPERATION	Callback was not set

Precondition:: update_control_initialize() has to be called before calling this function.; A callback has to be set using update_control_set_finish_update_cb() before calling
this function.; In order for the finish update process to complete successfully, this function has
to be called after the RO update process launched by update_control_do_ro_update_async()
completes SUCCESSFULLY. Calling this function before that will not return an error.

Postcondition:: A callback set by update_control_set_finish_update_cb() will be invoked
after the finish update process finishes. To check the result of the operation, examine
the result code passed to the callback. If the process was successful, the callback
will not be invoked, because the system will be rebooting.

See also:: update_control_initialize(); update_control_set_finish_update_cb(); update_control_do_ro_update_async()

int update_control_do_ro_update_async ( void )

Triggers upgrade script and tells it to perform ONLY RO update asynchronously.

Warning:: This is not for use by third-party applications.

This function does not perform the finishing of update process (among others rebooting).
To finish the update use update_control_do_finish_update_async(). If you wish to trigger both operations synchronously,
use update_control_do_update().

Since :: 9.0

Privilege Level:: platform

Privilege:: http://tizen.org/privilege/updatecontrol.admin

Returns:: 0 if basic checks succeeded (does not guarantee the operation triggered completed successfully),
otherwise a negative error value

Return values:

UPDATE_CONTROL_ERROR_NONE	Successful
UPDATE_CONTROL_ERROR_NOT_SUPPORTED	Not supported
UPDATE_CONTROL_ERROR_PERMISSION_DENIED	Permission denied
UPDATE_CONTROL_ERROR_SYSTEM_ERROR	System error
UPDATE_CONTROL_ERROR_INVALID_OPERATION	Callback was not set

Precondition:: update_control_initialize() has to be called before calling this function.; A callback has to be set using update_control_set_ro_update_cb() before calling
this function.

Postcondition:: A callback set by update_control_set_ro_update_cb() will be invoked
after RO update finishes (does not guarantee the process was successful).
To check the result of the operation, examine the result code passed to the callback.

See also:: update_control_initialize(); update_control_set_ro_update_cb()

int update_control_do_update ( void )

Triggers upgrade script and tells it to perform RO update and finish update operations (full upgrade process).

Warning:: This is not for use by third-party applications.

This starts the script in the background and quickly returns. It doesn't check the return value of the script.

Since :: 5.0

Privilege Level:: platform

Privilege:: http://tizen.org/privilege/updatecontrol.admin

Returns:: 0 if RO update and finish were triggered successfully (doesn't guarantee upgrade script COMPLETED successfully), otherwise a negative error value

Return values:

UPDATE_CONTROL_ERROR_NONE	Successful
UPDATE_CONTROL_ERROR_NOT_SUPPORTED	Not supported
UPDATE_CONTROL_ERROR_PERMISSION_DENIED	Permission denied
UPDATE_CONTROL_ERROR_TIMED_OUT	Time out
UPDATE_CONTROL_ERROR_INVALID_PACKAGE	Invalid package
UPDATE_CONTROL_ERROR_PACKAGE_NOT_SUPPORTED	Package type not supported
UPDATE_CONTROL_ERROR_SYSTEM_ERROR	System error
UPDATE_CONTROL_ERROR_INVALID_OPERATION	Function not implemented

int update_control_download_package ( void )

Requests downloading new version of firmware.

Since :: 5.0

Returns:: 0 on success, otherwise a negative error value

Return values:

UPDATE_CONTROL_ERROR_NONE	Successful
UPDATE_CONTROL_ERROR_NOT_SUPPORTED	Not supported
UPDATE_CONTROL_ERROR_FILE_NO_SPACE_ON_DEVICE	No space left on device
UPDATE_CONTROL_ERROR_OUT_OF_MEMORY	Out of memory
UPDATE_CONTROL_ERROR_CONNECTION_REFUSED	Connection refused
UPDATE_CONTROL_ERROR_CONNECTION_ABORTED	Software caused connection abort
UPDATE_CONTROL_ERROR_PROTOCOL_NOT_SUPPORTED	Protocol not supported
UPDATE_CONTROL_ERROR_INVALID_URI	Invalid URI
UPDATE_CONTROL_ERROR_SYSTEM_ERROR	System error
UPDATE_CONTROL_ERROR_INVALID_OPERATION	Function not implemented

int update_control_get_property	(	update_control_property_e	property,
		void **	value
	)

Gets the update property of the given key.

Since :: 5.0

Remarks:: The value must be released using free()

Parameters:

[in]	property	The key of property to get
[out]	value	The value of given property

Returns:: 0 on success, otherwise a negative error value

Return values:

UPDATE_CONTROL_ERROR_NONE	Successful
UPDATE_CONTROL_ERROR_NOT_SUPPORTED	Not supported
UPDATE_CONTROL_ERROR_INVALID_PARAMETER	Invalid parameter
UPDATE_CONTROL_ERROR_OUT_OF_MEMORY	Out of memory
UPDATE_CONTROL_ERROR_KEY_NOT_FOUND	Specified property not found
UPDATE_CONTROL_ERROR_KEY_REJECTED	Specified property not available
UPDATE_CONTROL_ERROR_SYSTEM_ERROR	System error
UPDATE_CONTROL_ERROR_INVALID_OPERATION	Function not implemented

int update_control_initialize ( void )

Initializes the update controller.

Since :: 5.0

Returns:: 0 on success, otherwise a negative error value

Return values:

UPDATE_CONTROL_ERROR_NONE	Successful
UPDATE_CONTROL_ERROR_NOT_SUPPORTED	Not supported
UPDATE_CONTROL_ERROR_OUT_OF_MEMORY	Out of memory
UPDATE_CONTROL_ERROR_SYSTEM_ERROR	System error
UPDATE_CONTROL_ERROR_INVALID_OPERATION	Function not implemented

See also:: update_control_deinitialize()

int update_control_make_reservation ( struct tm * reservation_time )

Makes reservation for update.

Warning:: This is not for use by third-party applications.

Makes update reservation at a specific time. At the given time, it automatically checks, downloads and updates to a new version. To cancel the reservation, call update_control_cancel_reservation().

Since :: 5.0

Privilege Level:: platform

Privilege:: http://tizen.org/privilege/updatecontrol.admin

Remarks:: Only one reservation can be used at any given time. If a new reservation is made, the previous one will be removed.

Parameters:

[in] reservation_time The time to start update

Returns:: 0 on success, otherwise a negative error value

Return values:

UPDATE_CONTROL_ERROR_NONE	Successful
UPDATE_CONTROL_ERROR_NOT_SUPPORTED	Not supported
UPDATE_CONTROL_ERROR_PERMISSION_DENIED	Permission denied
UPDATE_CONTROL_ERROR_INVALID_PARAMETER	Invalid parameter
UPDATE_CONTROL_ERROR_SYSTEM_ERROR	System error
UPDATE_CONTROL_ERROR_INVALID_OPERATION	Function not implemented

int update_control_set_finish_update_cb	(	update_control_cb	user_cb,
		const void *	user_data
	)

Sets a callback to trigger once finish update operation has completed.

Since :: 9.0

Remarks:: If there already is a callback set using this function, calling it again will overwrite it.

Parameters:

[in]	user_cb	The callback to be triggered once the operation has completed
[in]	user_data	Data to be passed to the callback

Returns:: 0 if callback was set, otherwise a negative error value

Return values:

UPDATE_CONTROL_ERROR_NONE	Successful
UPDATE_CONTROL_ERROR_NOT_SUPPORTED	Not supported
UPDATE_CONTROL_ERROR_INVALID_PARAMETER	user_cb is null
UPDATE_CONTROL_ERROR_SYSTEM_ERROR	System error

Postcondition:: user_cb will be called after an operation launched by update_control_do_finish_update_async() finishes.

See also:: update_control_unset_finish_update_cb(); update_control_do_finish_update_async()

int update_control_set_ro_update_cb	(	update_control_cb	user_cb,
		const void *	user_data
	)

Sets a callback to trigger once RO update has completed.

Since :: 9.0

Remarks:: If there already is a callback set using this function, calling it again will overwrite it.

Parameters:

[in]	user_cb	The callback to be triggered once the operation has completed
[in]	user_data	Data to be passed to the callback

Returns:: 0 if callback was set, otherwise a negative error value

Return values:

UPDATE_CONTROL_ERROR_NONE	Successful
UPDATE_CONTROL_ERROR_NOT_SUPPORTED	Not supported
UPDATE_CONTROL_ERROR_INVALID_PARAMETER	user_cb is null
UPDATE_CONTROL_ERROR_SYSTEM_ERROR	System error

Postcondition:: user_cb will be called after an operation launched by update_control_do_ro_update_async() finishes.

See also:: update_control_unset_ro_update_cb(); update_control_do_ro_update_async()

int update_control_unset_finish_update_cb ( void )

Unsets the callback set by update_control_set_finish_update_cb().

Since :: 9.0

Remarks:: Using this function after launching associated operation but before
receiving the callback will not cause any errors, but will make tracking the result of
the operation impossible.

Returns:: 0 if callback was unset, otherwise a negative error value

Return values:

UPDATE_CONTROL_ERROR_NONE	Successful
UPDATE_CONTROL_ERROR_NOT_SUPPORTED	Not supported
UPDATE_CONTROL_ERROR_SYSTEM_ERROR	System error
UPDATE_CONTROL_ERROR_INVALID_OPERATION	No callback to unset

Precondition:: A callback has to be set using update_control_set_finish_update_cb() before calling
this function.

See also:: update_control_set_finish_update_cb()

int update_control_unset_ro_update_cb ( void )

Unsets the callback set by update_control_set_ro_update_cb().

Since :: 9.0

Remarks:: Using this function after launching associated operation but before
receiving the callback will not cause any errors, but will make tracking the result of
the operation impossible.

Returns:: 0 if callback was unset, otherwise a negative error value

Return values:

UPDATE_CONTROL_ERROR_NONE	Successful
UPDATE_CONTROL_ERROR_NOT_SUPPORTED	Not supported
UPDATE_CONTROL_ERROR_SYSTEM_ERROR	System error
UPDATE_CONTROL_ERROR_INVALID_OPERATION	No callback to unset

Precondition:: A callback has to be set using update_control_set_ro_update_cb() before calling
this function.

See also:: update_control_set_ro_update_cb()

Required Header

Overview

Related Features

Functions

Typedefs

Typedef Documentation

Enumeration Type Documentation

Function Documentation