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 UApplicationId * | u_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 UApplicationId * | u_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 MirConnection * | u_application_instance_get_mir_connection (UApplicationInstance *instance)
| Return the MirConnection associated with an application instance. Use of MirConnection with the mir client API is now the preferred way to create and use application surfaces. The ua_ui_ namespace is now deprecated. 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] | options | Application instance options
  [in] | context | The callback context as specified by the application

Definition at line 38 of file lifecycle_delegate.h.

typedef void UApplicationDescription

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 41 of file instance.h.

typedef void UApplicationLifecycleDelegate

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] | archive | The 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] | archive | The archive to read from.
  [out] | s | Pointer 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] | archive | The archive to read from.
  [out] | data | Pointer to memory that receives the binary data.
  [out] | size | Pointer 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] | archive | The archive to read from.
  [out] | s | Pointer to memory that receives the string.
  [out] | size | Pointer 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] | archive | The archive to read from.
  [out] | s | Pointer to memory that receives the wide string.
  [out] | size | Pointer 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] | archive | The archive to write to.
  [in] | s | The 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] | archive | The archive to write to.
  [in] | data | The binary blob to write.
  [in] | size | The 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] | archive | The archive to write to.
  [in] | s | The string to write.
  [in] | size | The 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] | archive | The archive to write to.
  [in] | s | The string to write.
  [in] | size | The 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] | desc | The 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] | desc | The 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] | desc | The 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] | desc | The application description instance, must not be NULL.
  [in] | id | The 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] | desc | The application description instance, must not be NULL.
  [in] | lifecycle_delegate | The 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] | lhs | The left-hand-side id to be compared.
  [in] | rhs | The 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] | id | The 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] | string | The string containing the application ID.
  [in] | size | The size of the string.

UBUNTU_DLL_PUBLIC void u_application_init | ( | void * | args | ) |

Initializes the Ubuntu Application API backend with args.

Parameters

  [in] | args | Opaque initialization arguments.

UBUNTU_DLL_PUBLIC void u_application_instance_destroy | ( | UApplicationInstance * | instance | ) |

Destroys the application instance and releases all its resources.

Parameters

  [in] | instance | The instance to be destroyed.

UBUNTU_DLL_PUBLIC MirConnection* u_application_instance_get_mir_connection | ( | UApplicationInstance * | instance | ) |

Return the MirConnection associated with an application instance. Use of MirConnection with the mir client API is now the preferred way to create and use application surfaces. The ua_ui_ namespace is now deprecated.

Parameters

  [in] | instance | The instance from which to retreive the MirConnection

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] | desc | A description object, must not be NULL.
  [in] | options | An 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] | instance | The 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] | instance | The 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] | instance | The 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] | delegate | The 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] | delegate | The 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] | delegate | The 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] | delegate | The lifecycle delegate to query the context from.
  [in] | context | Unused.

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] | delegate | The 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] | delegate | The lifecycle delegate to adjust the cb for.
  [in] | cb | The 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] | delegate | The lifecycle delegate to adjust the cb for.
  [in] | cb | The 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] | delegate | The lifecycle delegate to adjust the context for.
  [in] | context | The 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] | delegate | The 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] | major | Major version.
  [out] | minor | Minor version.
  [out] | patch | Patch version.

UBUNTU_DLL_PUBLIC void u_application_options_destroy | ( | UApplicationOptions * | options | ) |

Destroys the options object and releases all resources.

Parameters

  [in] | options | The 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] | options | The 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] | argc | Number of arguments.
  [in] | argv | Arguments.