Functions and structures to create, configure, and send application or card invocations and queries.
The Navigator Invoke API defines the invocation framework service, which allows you to send and receive application or card invocations, to send queries to the invocation framework, and to send data between a parent application and the corresponding card. For information about the invocation framework, see App Integration.
This has a number of uses, including:
// create handler invocation navigator_invoke_invocation_t *invoke = NULL; navigator_invoke_invocation_create(&invoke); // set invocation action and type navigator_invoke_invocation_set_action(invoke, "com.example.action.SET_SCREEN_COLOR"); navigator_invoke_invocation_set_type(invoke, "application/com.example.type"); // pass arbitrary data (in this example, set screen color value to yellow) int screen_color = 0xffffff00; navigator_invoke_invocation_set_data(invoke, &screen_color, sizeof(int)); // invoke the target navigator_invoke_invocation_send(invoke); // clean up resources navigator_invoke_invocation_destroy(invoke);
switch (bps_event_get_code(event)) { case NAVIGATOR_INVOKE_TARGET: { const navigator_invoke_invocation_t *invoke = navigator_invoke_event_get_invocation(event); // an invocation has been received if(invoke) { // retrieve invocation action const char *action = navigator_invoke_invocation_get_action(invoke); // if invocation includes data, retrieve data if(navigator_invoke_invocation_get_data_length(invoke) > 0) { // set color to value passed by invocation const int *p; p = navigator_invoke_invocation_get_data(invoke); change_color(*p); } } } break; }
switch (bps_event_get_code(event)) { case NAVIGATOR_INVOKE_TARGET_RESULT: { const char *id = navigator_event_get_id(event); const char *err = navigator_event_get_err(event); } break; }
// create handler invocation navigator_invoke_invocation_t *invoke = NULL; navigator_invoke_invocation_create(&invoke); // set action and type (in this example, view a jpeg image) navigator_invoke_invocation_set_action(invoke, "com.example.action.VIEW"); navigator_invoke_invocation_set_type(invoke, "image/jpeg"); // pass URI pointing to the data (in this example, the image to view) navigator_invoke_invocation_set_uri(invoke, "file:///accounts/1000/appdata/com.example.application.123456789123456789123456789/data/image%201.jpg"); // invoke the target navigator_invoke_invocation_send(invoke); // clean up resources navigator_invoke_invocation_destroy(invoke);
switch (bps_event_get_code(event)) { case NAVIGATOR_INVOKE_TARGET: { const navigator_invoke_invocation_t *invoke = navigator_invoke_event_get_invocation(event); // an invocation has been received if(invoke) { // retrieve action, MIME type, and URI of the image from the // invocation const char *action = navigator_invoke_invocation_get_action(invoke); const char *mime_type = navigator_invoke_invocation_get_type(invoke); const char *image_uri = navigator_invoke_invocation_get_uri(invoke); // view image located at the defined URI view_image(image_uri); } } break; }
// create handler invocation navigator_invoke_invocation_t *invoke = NULL; navigator_invoke_invocation_create(&invoke); // set action navigator_invoke_invocation_set_action(invoke, "com.example.action.SET_SCREEN_COLOR"); // set handler ID navigator_invoke_invocation_set_target(invoke, "com.example.DefaultHandler"); // invoke the target navigator_invoke_invocation_send(invoke); // clean up resources navigator_invoke_invocation_destroy(invoke);
// create query navigator_invoke_query_t *query = NULL; navigator_invoke_query_create(&query); // set query ID navigator_invoke_query_set_id(query, "123"); // set action and type to query for navigator_invoke_query_set_action(query, "bb.action.SHARE"); navigator_invoke_query_set_type(query, "image/png"); // send query navigator_invoke_query_send(query);
switch (bps_event_get_code(event)) { case NAVIGATOR_INVOKE_QUERY_RESULT: { const char *id = navigator_event_get_id(event); // create integer holding the number of actions returned by the query int action_count = navigator_invoke_event_get_query_result_action_count(event); int i=0; // loop listing all actions returned by the query for (; i < action_count; i++) { const navigator_invoke_query_result_action_t *action = navigator_invoke_event_get_query_result_action(event, i); // retrieve action attributes const char *name = navigator_invoke_query_result_action_get_name(action); const char *icon = navigator_invoke_query_result_action_get_icon(action); const char *label = navigator_invoke_query_result_action_get_label(action); // create integer holding the number of targets in the action int target_count = navigator_invoke_query_result_action_get_target_count(action); int j=0; // loop listing all targets in the action for (; j < target_size; j++) { const navigator_invoke_query_result_target_t *target = navigator_invoke_query_result_action_get_target(action, j); // retrieve target attributes const char *target_key = navigator_invoke_query_result_target_get_key(target); const char *target_icon = navigator_invoke_query_result_target_get_icon(target); const char *target_splash = navigator_invoke_query_result_target_get_splash(target); const char *target_label = navigator_invoke_query_result_target_get_label(target); navigator_invoke_target_type_t target_type = navigator_invoke_query_result_target_get_type(target); navigator_invoke_perimeter_type_t perimeter = navigator_invoke_query_result_target_get_perimeter(target); } } } }
Registering a recurrence rule as a timer trigger for a headless application:
A recurrence rule specifies the interval at which to trigger a headless application. The recurrence is invoked by a timer registration. A recurrence rule has one of the frequencies enumerated in navigator_invoke_recurrence_rule_frequency_t. It can have a date limit or a count limit. The date limit specifies the date at which the recurrence ends. The count limit specifies the number of times of the recurrence. The interval is a positive integer identifying the interval of repetition for the rule. The default interval is related to the interval type. For example, the default interval for a NAVIGATOR_INVOKE_RECURRENCE_RULE_FREQUENCY_HOURLY rule is every hour, and the default interval for a NAVIGATOR_INVOKE_RECURRENCE_RULE_FREQUENCY_WEEKLY rule is every week. Setting a NAVIGATOR_INVOKE_RECURRENCE_RULE_FREQUENCY_DAILY rule to an interval of 2 sets the interval to every other day. The start date specifies the date at which the recurrence starts. It defaults to the present date. Additionally, the rule can be further modified by specifying recurrences such as minutes of the hour, hours of the day, days of the week and months of the year.
The following sample code demonstrates how to register a daily recurrent timer that fires at 10AM and 5PM, beginning January 1st, 2014. The headless target is invoked on the specified time slot with the action 'bb.action.system.TIMER_FIRED'. Note that error handling is omitted for clarity.
navigator_invoke_timer_registration_t *reg = NULL; navigator_invoke_recurrence_rule_t *rule = NULL; navigator_invoke_specific_time_t *start_date = NULL; navigator_invoke_timer_registration_create(®, NAVIGATOR_INVOKE_TIMER_TRIGGER_RECURRENT); navigator_invoke_recurrence_rule_create(&rule, NAVIGATOR_INVOKE_RECURRENCE_RULE_FREQUENCY_DAILY); int hours_of_day[] = {10, 17}; // 10 and 17 correspond to 10AM and 5PM, respectively. // These are the times the timer trigger will be activated. navigator_invoke_recurrence_rule_set_hours_of_day(rule, hours_of_day, 2); // specify a start date from when the trigger should activate - mandatory // January 1st, 2014 at 00:00 (America/New_York timezone) navigator_invoke_specific_time_create(&start_date); navigator_invoke_specific_time_set_year(start_date, 2014); navigator_invoke_specific_time_set_month(start_date, 1); navigator_invoke_specific_time_set_day(start_date, 1); navigator_invoke_specific_time_set_hour(start_date, 0); navigator_invoke_specific_time_set_minute(start_date, 0); navigator_invoke_specific_time_set_time_zone(start_date, "America/New_York"); navigator_invoke_recurrence_rule_set_start_date(rule, start_date); navigator_invoke_timer_registration_set_id(reg, "123"); navigator_invoke_timer_registration_set_action(reg, NAVIGATOR_INVOKE_TIMER_ACTION_REGISTER); navigator_invoke_timer_registration_set_target(reg, "com.example.MyHeadlessTarget"); navigator_invoke_timer_registration_set_recurrence_rule(reg, rule); navigator_invoke_timer_registration_send(reg); navigator_invoke_specific_time_destroy(start_date); navigator_invoke_recurrence_rule_destroy(rule); navigator_invoke_timer_registration_destroy(reg);