Ubuntu Platform API  2.3.0
A library helping with tight integration into the Ubuntu platform
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Modules Pages
Functions and types to support application development.

Typedefs

typedef void UApplicationDescription
 Encapsulates properties of an application instance. More...
 
typedef void UApplicationId
 An opaque type describing an application ID. More...
 
typedef void UApplicationInstance
 Opaque type describing an application instance.An application instance encapsulates the event loop of an app. More...
 
typedef void(* u_on_application_resumed )(const UApplicationOptions *options, void *context)
 Prototype for the callback that is invoked whenever the app has been resumed. More...
 
typedef void(* u_on_application_about_to_stop )(UApplicationArchive *archive, void *context)
 Prototype for the callback that is invoked whenever the app is about to be stopped. Applications can serialize their state to the supplied archive. More...
 
typedef void UApplicationLifecycleDelegate
 Opaque type encapsulating all app-specific callback functions. More...
 
typedef void UApplicationOptions
 Encapsulates options as passed to the application. More...
 

Functions

UBUNTU_DLL_PUBLIC
UApplicationArchive
u_application_archive_new ()
 Creates a new archive, ownership is transferred to caller. More...
 
UBUNTU_DLL_PUBLIC void u_application_archive_destroy (UApplicationArchive *archive)
 Destroys the given archive instance and releases all resources held by the instance. More...
 
UBUNTU_DLL_PUBLIC UStatus u_application_archive_write (UApplicationArchive *archive, int64_t s)
 Writes a signed 64-bit integer to the supplied archive. More...
 
UBUNTU_DLL_PUBLIC UStatus u_application_archive_write_stringn (UApplicationArchive *archive, const char *s, size_t size)
 Writes a string of characters to the supplied archive. More...
 
UBUNTU_DLL_PUBLIC UStatus u_application_archive_write_wstringn (UApplicationArchive *archive, const wchar_t *s, size_t size)
 Writes a string of wide characters to the supplied archive. More...
 
UBUNTU_DLL_PUBLIC UStatus u_application_archive_write_bytes (UApplicationArchive *archive, const intptr_t *data, size_t size)
 Writes a blob of binary data to the supplied archive. More...
 
UBUNTU_DLL_PUBLIC UStatus u_application_archive_read (const UApplicationArchive *archive, int64_t *s)
 Reads a signed 64-bit integer from the supplied archive. More...
 
UBUNTU_DLL_PUBLIC UStatus u_application_archive_read_stringn (const UApplicationArchive *archive, const char **s, size_t *size)
 Reads a string of characters from the supplied archive. More...
 
UBUNTU_DLL_PUBLIC UStatus u_application_archive_read_wstringn (UApplicationArchive *archive, const wchar_t *s, size_t size)
 Reads a string of wide characters from the supplied archive. More...
 
UBUNTU_DLL_PUBLIC UStatus u_application_archive_read_bytes (UApplicationArchive *archive, const intptr_t *data, size_t size)
 Reads a blob of binary data from the supplied archive. More...
 
UBUNTU_DLL_PUBLIC
UApplicationDescription
u_application_description_new ()
 Creates a new instance of application description. More...
 
UBUNTU_DLL_PUBLIC void u_application_description_destroy (UApplicationDescription *desc)
 Destroys an instance of application description and releases all resources. More...
 
UBUNTU_DLL_PUBLIC void u_application_description_set_application_id (UApplicationDescription *desc, UApplicationId *id)
 Sets the application id contained in the description instance. More...
 
UBUNTU_DLL_PUBLIC UApplicationIdu_application_description_get_application_id (UApplicationDescription *desc)
 Queries the application id contained in the description instance. More...
 
UBUNTU_DLL_PUBLIC void u_application_description_set_application_lifecycle_delegate (UApplicationDescription *desc, UApplicationLifecycleDelegate *lifecycle_delegate)
 Sets the application lifecycle delegate. More...
 
UBUNTU_DLL_PUBLIC
UApplicationLifecycleDelegate
u_application_description_get_application_lifecycle_delegate (UApplicationDescription *desc)
 Queries the application lifecycle delegate. More...
 
UBUNTU_DLL_PUBLIC UApplicationIdu_application_id_new_from_stringn (const char *string, size_t size)
 Creates a new application ID from an existing string. More...
 
UBUNTU_DLL_PUBLIC void u_application_id_destroy (UApplicationId *id)
 Destroy the supplied application ID instance. More...
 
UBUNTU_DLL_PUBLIC int u_application_id_compare (UApplicationId *lhs, UApplicationId *rhs)
 Compares two application ID instances. More...
 
UBUNTU_DLL_PUBLIC void u_application_module_version (uint32_t *major, uint32_t *minor, uint32_t *patch)
 Queries the Module Version that is currently loaded. More...
 
UBUNTU_DLL_PUBLIC void u_application_init (void *args)
 Initializes the Ubuntu Application API backend with args. More...
 
UBUNTU_DLL_PUBLIC void u_application_finish ()
 Signal termination to the Application backend instance. More...
 
UBUNTU_DLL_PUBLIC
UApplicationInstance
u_application_instance_new_from_description_with_options (UApplicationDescription *desc, UApplicationOptions *options)
 Creates a new application instance with a reference count of 1. More...
 
UBUNTU_DLL_PUBLIC void u_application_instance_ref (UApplicationInstance *instance)
 Increments the reference count of an application instance. More...
 
UBUNTU_DLL_PUBLIC void u_application_instance_unref (UApplicationInstance *instance)
 Decrements the reference count of an application instance and releases all resources held by the object if the reference count reaches 0. More...
 
UBUNTU_DLL_PUBLIC void u_application_instance_destroy (UApplicationInstance *instance)
 Destroys the application instance and releases all its resources. More...
 
UBUNTU_DLL_PUBLIC void u_application_instance_run (UApplicationInstance *instance)
 Executes the event loop of the application instance. More...
 
UBUNTU_DLL_PUBLIC
UApplicationLifecycleDelegate
u_application_lifecycle_delegate_new ()
 Creates a new instance of the lifecycle delegate with an initial refernce count of 1. More...
 
UBUNTU_DLL_PUBLIC void u_application_lifecycle_delegate_destroy (UApplicationLifecycleDelegate *delegate)
 Destroys an instance of the lifecycle delegate and releases all of its resources. More...
 
UBUNTU_DLL_PUBLIC void u_application_lifecycle_delegate_ref (UApplicationLifecycleDelegate *delegate)
 Increments the reference count of the supplied lifecycle delegate. More...
 
UBUNTU_DLL_PUBLIC void u_application_lifecycle_delegate_unref (UApplicationLifecycleDelegate *delegate)
 Decrements the reference count of the supplied lifecycle delegate and destroys it if the count reaches 0. More...
 
UBUNTU_DLL_PUBLIC void u_application_lifecycle_delegate_set_application_resumed_cb (UApplicationLifecycleDelegate *delegate, u_on_application_resumed cb)
 Sets the resumed cb for the supplied delegate. More...
 
UBUNTU_DLL_PUBLIC
u_on_application_resumed 
u_application_lifecycle_delegate_get_application_resumed_cb (UApplicationLifecycleDelegate *delegate)
 Queries the resumed cb from the supplied delegate. More...
 
UBUNTU_DLL_PUBLIC void u_application_lifecycle_delegate_set_application_about_to_stop_cb (UApplicationLifecycleDelegate *delegate, u_on_application_about_to_stop cb)
 Sets the about-to-stop cb for the supplied delegate. More...
 
UBUNTU_DLL_PUBLIC
u_on_application_about_to_stop 
u_application_lifecycle_delegate_get_application_about_to_stop_cb (UApplicationLifecycleDelegate *delegate)
 Queries the about-to-be-stopped cb from the supplied delegate. More...
 
UBUNTU_DLL_PUBLIC void u_application_lifecycle_delegate_set_context (UApplicationLifecycleDelegate *delegate, void *context)
 Sets the cb context for the supplied delegate. More...
 
UBUNTU_DLL_PUBLIC void * u_application_lifecycle_delegate_get_context (UApplicationLifecycleDelegate *delegate, void *context)
 Queries the cb context from the supplied delegate. More...
 
UBUNTU_DLL_PUBLIC
UApplicationOptions
u_application_options_new_from_cmd_line (int argc, char **argv)
 Parses options from the command line. More...
 
UBUNTU_DLL_PUBLIC void u_application_options_destroy (UApplicationOptions *options)
 Destroys the options object and releases all resources. More...
 
UBUNTU_DLL_PUBLIC
UApplicationOperationMode 
u_application_options_get_operation_mode (UApplicationOptions *options)
 Queries the operation mode from the supplied options object. More...
 

Detailed Description

Typedef Documentation

typedef void(* u_on_application_about_to_stop)(UApplicationArchive *archive, void *context)

Prototype for the callback that is invoked whenever the app is about to be stopped. Applications can serialize their state to the supplied archive.

Definition at line 44 of file lifecycle_delegate.h.

typedef void(* u_on_application_resumed)(const UApplicationOptions *options, void *context)

Prototype for the callback that is invoked whenever the app has been resumed.

Parameters
[in]optionsApplication instance options
[in]contextThe callback context as specified by the application

Definition at line 38 of file lifecycle_delegate.h.

Encapsulates properties of an application instance.

Definition at line 36 of file description.h.

typedef void UApplicationId

An opaque type describing an application ID.

Definition at line 35 of file id.h.

typedef void UApplicationInstance

Opaque type describing an application instance.An application instance encapsulates the event loop of an app.

Definition at line 39 of file instance.h.

Opaque type encapsulating all app-specific callback functions.

Definition at line 50 of file lifecycle_delegate.h.

typedef void UApplicationOptions

Encapsulates options as passed to the application.

Definition at line 35 of file options.h.

Function Documentation

UBUNTU_DLL_PUBLIC void u_application_archive_destroy ( UApplicationArchive archive)

Destroys the given archive instance and releases all resources held by the instance.

Parameters
[in]archiveThe instance to be destroyed.
Postcondition
All resources held by the instance are released. The result of any operation invoked on the destroyed instance are undefined.
UBUNTU_DLL_PUBLIC UApplicationArchive* u_application_archive_new ( )

Creates a new archive, ownership is transferred to caller.

See also
u_application_archive_destroy
Returns
A new archive instance or NULL if not enough memory is available.
UBUNTU_DLL_PUBLIC UStatus u_application_archive_read ( const UApplicationArchive archive,
int64_t *  s 
)

Reads a signed 64-bit integer from the supplied archive.

Returns
U_STATUS_SUCCESS if successful, and U_STATUS_ERROR in case of failures.
Parameters
[in]archiveThe archive to read from.
[out]sPointer to memory that receives the signed 64-bit integer.
UBUNTU_DLL_PUBLIC UStatus u_application_archive_read_bytes ( UApplicationArchive archive,
const intptr_t *  data,
size_t  size 
)

Reads a blob of binary data from the supplied archive.

Returns
U_STATUS_SUCCESS if successful, and U_STATUS_ERROR in case of failures.
Parameters
[in]archiveThe archive to read from.
[out]dataPointer to memory that receives the binary data.
[out]sizePointer to memory that receives the size of the blob.
UBUNTU_DLL_PUBLIC UStatus u_application_archive_read_stringn ( const UApplicationArchive archive,
const char **  s,
size_t *  size 
)

Reads a string of characters from the supplied archive.

Returns
U_STATUS_SUCCESS if successful, and U_STATUS_ERROR in case of failures.
Parameters
[in]archiveThe archive to read from.
[out]sPointer to memory that receives the string.
[out]sizePointer to memory that receives the size of the string.
UBUNTU_DLL_PUBLIC UStatus u_application_archive_read_wstringn ( UApplicationArchive archive,
const wchar_t *  s,
size_t  size 
)

Reads a string of wide characters from the supplied archive.

Returns
U_STATUS_SUCCESS if successful, and U_STATUS_ERROR in case of failures.
Parameters
[in]archiveThe archive to read from.
[out]sPointer to memory that receives the wide string.
[out]sizePointer to memory that receives the size of the string.
UBUNTU_DLL_PUBLIC UStatus u_application_archive_write ( UApplicationArchive archive,
int64_t  s 
)

Writes a signed 64-bit integer to the supplied archive.

Returns
U_STATUS_SUCCESS if successful, and U_STATUS_ERROR in case of failures.
Parameters
[in]archiveThe archive to write to.
[in]sThe signed 64-bit integer to write to the archive.
UBUNTU_DLL_PUBLIC UStatus u_application_archive_write_bytes ( UApplicationArchive archive,
const intptr_t *  data,
size_t  size 
)

Writes a blob of binary data to the supplied archive.

Returns
U_STATUS_SUCCESS if successful, and U_STATUS_ERROR in case of failures.
Parameters
[in]archiveThe archive to write to.
[in]dataThe binary blob to write.
[in]sizeThe size of the blob.
UBUNTU_DLL_PUBLIC UStatus u_application_archive_write_stringn ( UApplicationArchive archive,
const char *  s,
size_t  size 
)

Writes a string of characters to the supplied archive.

Returns
U_STATUS_SUCCESS if successful, and U_STATUS_ERROR in case of failures.
Parameters
[in]archiveThe archive to write to.
[in]sThe string to write.
[in]sizeThe number of characters to write to the archive.
UBUNTU_DLL_PUBLIC UStatus u_application_archive_write_wstringn ( UApplicationArchive archive,
const wchar_t *  s,
size_t  size 
)

Writes a string of wide characters to the supplied archive.

Returns
U_STATUS_SUCCESS if successful, and U_STATUS_ERROR in case of failures.
Parameters
[in]archiveThe archive to write to.
[in]sThe string to write.
[in]sizeThe number of characters to write to the archive.
UBUNTU_DLL_PUBLIC void u_application_description_destroy ( UApplicationDescription desc)

Destroys an instance of application description and releases all resources.

Parameters
[in]descThe instance to be destroyed.
UBUNTU_DLL_PUBLIC UApplicationId* u_application_description_get_application_id ( UApplicationDescription desc)

Queries the application id contained in the description instance.

Returns
The app id contained in the instance.
Parameters
[in]descThe application description instance, must not be NULL.
UBUNTU_DLL_PUBLIC UApplicationLifecycleDelegate* u_application_description_get_application_lifecycle_delegate ( UApplicationDescription desc)

Queries the application lifecycle delegate.

Returns
The application lifecycle delegate contained in the description instance.
Parameters
[in]descThe application description instance, must not be NULL.
UBUNTU_DLL_PUBLIC UApplicationDescription* u_application_description_new ( )

Creates a new instance of application description.

Returns
A new application description instance or NULL if not enough memory is available.
UBUNTU_DLL_PUBLIC void u_application_description_set_application_id ( UApplicationDescription desc,
UApplicationId id 
)

Sets the application id contained in the description instance.

Parameters
[in]descThe application description instance, must not be NULL.
[in]idThe new application id, must not be NULL.
UBUNTU_DLL_PUBLIC void u_application_description_set_application_lifecycle_delegate ( UApplicationDescription desc,
UApplicationLifecycleDelegate lifecycle_delegate 
)

Sets the application lifecycle delegate.

Parameters
[in]descThe application description instance, must not be NULL.
[in]lifecycle_delegateThe new lifecycle delegate, must not be NULL.
UBUNTU_DLL_PUBLIC void u_application_finish ( )

Signal termination to the Application backend instance.

UBUNTU_DLL_PUBLIC int u_application_id_compare ( UApplicationId lhs,
UApplicationId rhs 
)

Compares two application ID instances.

Returns
-1 iff lhs < rhs, 0 iff lhs == rhs, 1 iff lhs > rhs.
Parameters
[in]lhsThe left-hand-side id to be compared.
[in]rhsThe right-hand-side id to be compared.
UBUNTU_DLL_PUBLIC void u_application_id_destroy ( UApplicationId id)

Destroy the supplied application ID instance.

Parameters
[in]idThe instance to be destroyed.
UBUNTU_DLL_PUBLIC UApplicationId* u_application_id_new_from_stringn ( const char *  string,
size_t  size 
)

Creates a new application ID from an existing string.

Parameters
[in]stringThe string containing the application ID.
[in]sizeThe size of the string.
UBUNTU_DLL_PUBLIC void u_application_init ( void *  args)

Initializes the Ubuntu Application API backend with args.

Parameters
[in]argsOpaque initialization arguments.
UBUNTU_DLL_PUBLIC void u_application_instance_destroy ( UApplicationInstance instance)

Destroys the application instance and releases all its resources.

Parameters
[in]instanceThe instance to be destroyed.
UBUNTU_DLL_PUBLIC UApplicationInstance* u_application_instance_new_from_description_with_options ( UApplicationDescription desc,
UApplicationOptions options 
)

Creates a new application instance with a reference count of 1.

Returns
A new application instance or NULL in case of low-memory.
Parameters
[in]descA description object, must not be NULL.
[in]optionsAn options object, must not be NULL.
UBUNTU_DLL_PUBLIC void u_application_instance_ref ( UApplicationInstance instance)

Increments the reference count of an application instance.

Parameters
[in]instanceThe instance to increment the reference count for.
UBUNTU_DLL_PUBLIC void u_application_instance_run ( UApplicationInstance instance)

Executes the event loop of the application instance.

Parameters
[in]instanceThe instance to be executed.
UBUNTU_DLL_PUBLIC void u_application_instance_unref ( UApplicationInstance instance)

Decrements the reference count of an application instance and releases all resources held by the object if the reference count reaches 0.

Parameters
[in]instanceThe instance to decrement the reference count for.
UBUNTU_DLL_PUBLIC void u_application_lifecycle_delegate_destroy ( UApplicationLifecycleDelegate delegate)

Destroys an instance of the lifecycle delegate and releases all of its resources.

Parameters
[in]delegateThe instance to be destroyed.
UBUNTU_DLL_PUBLIC u_on_application_about_to_stop u_application_lifecycle_delegate_get_application_about_to_stop_cb ( UApplicationLifecycleDelegate delegate)

Queries the about-to-be-stopped cb from the supplied delegate.

Returns
The callback to be invoked whenever the app is about to be stopped.
Parameters
[in]delegateThe lifecycle delegate to query the callback from.
UBUNTU_DLL_PUBLIC u_on_application_resumed u_application_lifecycle_delegate_get_application_resumed_cb ( UApplicationLifecycleDelegate delegate)

Queries the resumed cb from the supplied delegate.

Returns
The callback to be invoked whenever the app resumes.
Parameters
[in]delegateThe lifecycle delegate to query the callback from.
UBUNTU_DLL_PUBLIC void* u_application_lifecycle_delegate_get_context ( UApplicationLifecycleDelegate delegate,
void *  context 
)

Queries the cb context from the supplied delegate.

Returns
The context that is passed to callbacks of this delegate.
Parameters
[in]delegateThe lifecycle delegate to query the context from.
[in]contextUnused.
UBUNTU_DLL_PUBLIC UApplicationLifecycleDelegate* u_application_lifecycle_delegate_new ( )

Creates a new instance of the lifecycle delegate with an initial refernce count of 1.

Returns
A new instance of the lifecycle delegate or NULL if no memory is available.
UBUNTU_DLL_PUBLIC void u_application_lifecycle_delegate_ref ( UApplicationLifecycleDelegate delegate)

Increments the reference count of the supplied lifecycle delegate.

Parameters
[in]delegateThe lifecycle delegate to increment the reference count for.
UBUNTU_DLL_PUBLIC void u_application_lifecycle_delegate_set_application_about_to_stop_cb ( UApplicationLifecycleDelegate delegate,
u_on_application_about_to_stop  cb 
)

Sets the about-to-stop cb for the supplied delegate.

Parameters
[in]delegateThe lifecycle delegate to adjust the cb for.
[in]cbThe new callback to be invoked whenever the app is about to be stopped..
UBUNTU_DLL_PUBLIC void u_application_lifecycle_delegate_set_application_resumed_cb ( UApplicationLifecycleDelegate delegate,
u_on_application_resumed  cb 
)

Sets the resumed cb for the supplied delegate.

Parameters
[in]delegateThe lifecycle delegate to adjust the cb for.
[in]cbThe new callback to be invoked whenever the app resumes.
UBUNTU_DLL_PUBLIC void u_application_lifecycle_delegate_set_context ( UApplicationLifecycleDelegate delegate,
void *  context 
)

Sets the cb context for the supplied delegate.

Parameters
[in]delegateThe lifecycle delegate to adjust the context for.
[in]contextThe new cb context.
UBUNTU_DLL_PUBLIC void u_application_lifecycle_delegate_unref ( UApplicationLifecycleDelegate delegate)

Decrements the reference count of the supplied lifecycle delegate and destroys it if the count reaches 0.

Parameters
[in]delegateThe lifecycle delegate to decrement the reference count for.
UBUNTU_DLL_PUBLIC void u_application_module_version ( uint32_t *  major,
uint32_t *  minor,
uint32_t *  patch 
)

Queries the Module Version that is currently loaded.

Parameters
[out]majorMajor version.
[out]minorMinor version.
[out]patchPatch version.
UBUNTU_DLL_PUBLIC void u_application_options_destroy ( UApplicationOptions options)

Destroys the options object and releases all resources.

Parameters
[in]optionsThe object to be destroyed.
UBUNTU_DLL_PUBLIC UApplicationOperationMode u_application_options_get_operation_mode ( UApplicationOptions options)

Queries the operation mode from the supplied options object.

Returns
The operation mode as stored in the options object.
Parameters
[in]optionsThe options object to be queried.
UBUNTU_DLL_PUBLIC UApplicationOptions* u_application_options_new_from_cmd_line ( int  argc,
char **  argv 
)

Parses options from the command line.

Returns
An options instance if parsing was successful, or 0 otheriwse.
Parameters
[in]argcNumber of arguments.
[in]argvArguments.