Main Page | Modules | Namespace List | Class Hierarchy | Data Structures | Directories | File List | Namespace Members | Data Fields | Globals

Attention Manager


Modules

 Private

Typedefs

typedef void(* AlpAttnAlertCB )(const char *sourceAppId, const char *alertTypeName, const char *handle, int argc, char *argv[], void *user_data)
 Prototype for the Attention Manager callback function.
typedef AlpLuid AlpAttnId
 type of an attn alert ID
typedef void * AlpAttnAlertH
 opaque type holding an alert object
typedef void * AlpAttnPropertyH
 opaque type holding a property object

Functions

alp_status_t alp_attn_alert_post (const char *sourceAppId, const char *alertTypeName, const char *handle, const char *interface, int32_t priority, int32_t duration, uint32_t nprops, AlpAttnProp *properties[])
 Post an attention alert.
alp_status_t alp_attn_alert_post_with_callback (const char *sourceAppId, const char *alertTypeName, const char *handle, const char *interface, int32_t priority, int32_t duration, uint32_t nprops, AlpAttnProp *properties[], AlpAttnAlertCB callback, void *user_data)
 Post an attention alert with a callback.
alp_status_t alp_attn_alert_update (const char *sourceAppId, const char *alertTypeName, const char *handle, uint32_t nprops, AlpAttnProp *properties[])
 Update the properties of a previously posted alert specified by the alert identifier.
alp_status_t alp_attn_alert_delete (const char *sourceAppId, const char *alertTypeName, const char *handle)
 Delete a posted attention alert using the alert identifier.


Typedef Documentation

typedef void(* AlpAttnAlertCB)(const char *sourceAppId, const char *alertTypeName, const char *handle, int argc, char *argv[], void *user_data)
 

Prototype for the Attention Manager callback function.

Parameters:
[in] sourceAppId the source id that was supplied in the alert post call (ex. bar:com.access.apps.calendar)
[in] alertTypeName the name of the alert type that was associated examples would be "/alp/mobile/incoming-call", "/alp/mobile/missed-call", "/alp/calendar/alarm", "/alp/email/new-messages", etc.
[in] handle the string handle that was assocated with the alert in the alert post call (i.e. the handle parameter).
[in] argc the number of additional arguments passed back.
[in] argv the additional arguments passed back in as an array of strings.
[in] user_data the pointer to user data that was passed in the alp_attn_alert_post_with_callback() call.

typedef void* AlpAttnAlertH
 

opaque type holding an alert object

typedef AlpLuid AlpAttnId
 

type of an attn alert ID

typedef void* AlpAttnPropertyH
 

opaque type holding a property object


Function Documentation

alp_status_t alp_attn_alert_delete const char *  sourceAppId,
const char *  alertTypeName,
const char *  handle
 

Delete a posted attention alert using the alert identifier.

Parameters:
[in] sourceAppId the source app ID/URL of the bundle posting the alert (i.e. bar:com.access.apps.calendar)
[in] alertTypeName the name of the application alert type examples would be "/alp/mobile/incoming-call", "/alp/mobile/missed-call", "/alp/calendar/alarm", "/alp/email/new-messages", etc.
[in] handle a string handle to used by the application in conjunction with the other parts of the tuple (the source app id and the alert type name) to uniquely reference the particular alert. This tuple of the sourceAppId, alertTypeName and handle must be unique.
Returns:
ALP_STATUS_OK if no error

ALP_STATUS_ATTN_BAD_PARAM for any invalid arguments passed in

ALP_STATUS_ATTN_NOT_FOUND if alert matching tuple is not found

alp_status_t alp_attn_alert_post const char *  sourceAppId,
const char *  alertTypeName,
const char *  handle,
const char *  interface,
int32_t  priority,
int32_t  duration,
uint32_t  nprops,
AlpAttnProp properties[]
 

Post an attention alert.

Post an alert to the attention manager. This version is primarily meant to be used by applications. Applications received notification of a user action taken by being launched (or relaunched) via the application manager with the arguments specified for that particular user action. This is done because there is no guarantee that the desired application will be running when the alert dialog or the alert list is displayed and the user selects an action for the alert.

The properties provided in the post and update calls control how and what is displayed in the alert dialog and the alert list. They also specify the actions to be associated with the buttons present in the user interface.

What determines whether a posted alert will cause an alert dialog to be displayed or simply have the alert show up on the alert list depends on the supplied priority and a predefined ruleset which specifies how alerts are to be handled. The default handling of priority 1 and 2 is to present a system dialog on the screen which will require user response. Priority 3 will accept the posted alert for display in the alert list and play an attention alert sound (or vibrate depending on the quite mode). Priority 4 will only play the sound.

Parameters:
[in] sourceAppId the source app ID/URL of the bundle posting the alert (i.e. bar:com.access.apps.calendar)
[in] alertTypeName the name of the application alert type examples would be "/alp/mobile/incoming-call", "/alp/mobile/missed-call", "/alp/calendar/alarm", "/alp/email/new-messages", etc.
[in] handle a string handle to used by the application in conjunction with the other parts of the tuple (the source app id and the alert type name) to uniquely reference the particular alert. The tuple of the sourceAppId, alertTypeName and appHandle must be unique.
[in] interface an URL of the alert interface specification to use for this alert. If no interface, pass NULL.
[in] priority an integer from 1 to 5 specifying the priority of the alert with 1 being highest and 5 lowest.
[in] duration an integer representing the number of seconds after being posted before being automatically cleared. A user or application may dismiss an alert sooner. A value of zero (0) means that the alert will remain until dismissed by the user or application.
[in] nprops the count of properties in the properties argument.
[in] properties an array of pointers to items of type AlpAttnProp.
Returns:
ALP_STATUS_OK if no error

ALP_STATUS_ATTN_BAD_PARAM for any invalid arguments passed in

Example
An example of posting a possible calendar alarm attention.
 #include <hiker/types.h>
 #include <hiker/bundlemgr.h>
 #include <hiker/attnmgr.h>

 void
 sent_alert (const char *handle, char *sDate, char *sTime, char *sSubject) {
     alp_status_t err;
     AlpAttnId    id;
     AlpBundle    my_bundle;
     char        *my_app_id;
     AlpAttnProp  prop0 = { "title", "Alarm" };
     AlpAttnProp  prop1 = { "text-1", sDate };
     AlpAttnProp  prop2 = { "text-2", sTime };
     AlpAttnProp  prop3 = { "smarttext-3", sSubject };
     AlpAttnProp  prop4 = { "image", "calendar_icon.jpg" };
     AlpAttnProp *properties[] = {
         &prop0,
         &prop1,
         &prop2,
         &prop3,
         &prop4
     };
     uint32_t nprops = sizeof(properties) / sizeof(properties[0]);

     my_bundle = alp_bundle_me();
     my_app_id = alp_bundle_metadata_value (my_bundle, "name");
     err = alp_attn_alert_post (my_app_id, "/foo/example/alarm", handle,
                                NULL,         // interface file URL
                                2,            // priority 2
                                0,            // no duration
                                nprops,       // number of properties
                                properties);  // array of properties
 }
Since:
ALP iSDK 1.0

alp_status_t alp_attn_alert_post_with_callback const char *  sourceAppId,
const char *  alertTypeName,
const char *  handle,
const char *  interface,
int32_t  priority,
int32_t  duration,
uint32_t  nprops,
AlpAttnProp properties[],
AlpAttnAlertCB  callback,
void *  user_data
 

Post an attention alert with a callback.

Post an alert to the attention manager. This version is primarily meant to be used by a service daemon that can't be launched like an application and must rely on a callback to receive notification of a user action taken during the display of the alert by the attention alert user interface. Depending on the configuration of the actions given for this alert (either through explicit properties or specified in the alert interface specification), one or more of the user actions may result in the callback being called with the supplied user_data and list of arguments configured for the given action taken.

The properties provided in the post and update calls control how and what is displayed in the alert dialog and the alert list. They also specify the actions to be associated with the buttons present in the user interface.

What determines whether a posted alert will cause an alert dialog to be displayed or simply have the alert show up on the alert list depends on the supplied priority and a predefined ruleset which specifies how alerts are to be handled. The default handling of priority 1 and 2 is to present a system dialog on the screen which will require user response. Priority 3 will accept the posted alert for display in the alert list and play an attention alert sound (or vibrate depending on the quite mode). Priority 4 will only play the sound.

Parameters:
[in] sourceAppId the source app ID/URL of the bundle posting the alert (ex. bar:com.access.apps.calendar)
[in] alertTypeName the name of the application alert type examples would be "/alp/mobile/incoming-call", "/alp/mobile/missed-call", "/alp/calendar/alarm", "/alp/email/new-messages", etc.
[in] handle a string handle to used by the application in conjunction with the other parts of the tuple (the source app id and the alert type name) to uniquely reference the particular alert. The tuple of the sourceAppId, alertTypeName and appHandle must be unique.
[in] interface an URL of the alert interface specification to use for this alert. If no interface, pass NULL.
[in] priority an integer from 1 to 5 specifying the priority of the alert with 1 being highest and 5 lowest.
[in] duration an integer representing the number of seconds after being posted before being automatically cleared. A user or application may dismiss an alert sooner. A value of zero (0) means that the alert will remain until dismissed by the user or application.
[in] nprops the count of properties in the properties argument.
[in] properties an array of pointers to items of type AlpAttnProp.
[in] callback a callback function.
[in] user_data the user data to pass to the callback function.
Returns:
ALP_STATUS_OK if no error

ALP_STATUS_ATTN_BAD_PARAM for any invalid arguments passed in

Example of Usage
An example of posting an alert with a callback.
 #include <hiker/types.h>
 #include <hiker/bundlemgr.h>
 #include <hiker/attnmgr.h>

 void
 alert_cb (const char *id, const char *type, const char *handle,
           int argc, char *argv[], void *user_data)
 {
     if (argc > 1)
         gtk_label_set_text (GTK_LABEL(user_data), argv[1]);
 }

 void
 sent_alert (const char *handle,
             char *sDate, char *sTime, char *sSubject,
             GtkWidget *widget) {
     alp_status_t err;
     AlpAttnId    id;
     AlpBundle    my_bundle;
     char        *my_app_id;
     AlpAttnProp  prop0 = { "title", "Alarm" };
     AlpAttnProp  prop1 = { "text-1", sDate };
     AlpAttnProp  prop2 = { "text-2", sTime };
     AlpAttnProp  prop3 = { "smarttext-3", sSubject };
     AlpAttnProp  prop4 = { "image", "calendar_icon.jpg" };
     AlpAttnProp *properties[] = {
         &prop0,
         &prop1,
         &prop2,
         &prop3,
         &prop4
     };
     uint32_t nprops = sizeof(properties)/ sizeof(properties[0]);

     my_bundle = alp_bundle_me();
     my_app_id = alp_bundle_metadata_value (my_bundle, "name");
     err = alp_attn_alert_post (my_app_id, "/alp/example/alarm", handle,
                                NULL,         // interface file url
                                2,            // priority 2
                                0,            // no duration
                                nprops,       // number of properties
                                properties,   // array of pointers to props
                                alert_cb,     // callback function 
                                widget);      // callback user data
 }
Since:
ALP iSDK 1.2
See also:
AlpAttnAlertCB for callback prototype.

alp_status_t alp_attn_alert_update const char *  sourceAppId,
const char *  alertTypeName,
const char *  handle,
uint32_t  nprops,
AlpAttnProp properties[]
 

Update the properties of a previously posted alert specified by the alert identifier.

New properties will be added to the attention alert, existing properties will have their values replaced with the new values.

Parameters:
[in] sourceAppId the source app ID/URL of the bundle posting the alert (i.e. bar:com.access.apps.calendar)
[in] alertTypeName the name of the application alert type examples would be "/alp/mobile/incoming-call", "/alp/mobile/missed-call", "/alp/calendar/alarm", "/alp/email/new-messages", etc.
[in] handle a string handle to used by the application in conjunction with the other parts of the tuple (the source app id and the alert type name) to uniquely reference the particular alert. The tuple of the sourceAppId, alertTypeName and handle must be unique.
[in] nprops number of properties in properties array
[in] properties an array of pointers to items of type AlpAttnProp.
Returns:
ALP_STATUS_OK if no error

ALP_STATUS_ATTN_BAD_PARAM for any invalid arguments passed in

ALP_STATUS_ATTN_NOT_FOUND if alert matching tuple is not found

Since:
ALP iSDK 1.0
See also:
alp_attn_alert_post


Generated on Sat Dec 16 20:29:50 2006 for hiker-0.9 by  doxygen 1.4.4