Invoke (navigator_invoke.h)

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:

Creating, customizing, and sending a handler invocation using the action and the type, and passing necessary data directly to the handler: 

   // 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);

Decoding an invocation request from a BPS event on the target handler's side: 

   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;
   }

Decoding the invocation target response's ID and the error from a BPS event: 

   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;
   }

Creating, customizing, and sending a handler invocation using the action and the type, and passing the URI location of the data to be passed to the handler: 

   // 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 the 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);

Decoding the URI path to the invocation data from a BPS event on the target handler's side: 

   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;
   }

Invoking a handler with a known target ID: 

   // 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);

Sending a query for a find a specific action and type: 

   // 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);

Handling a query response: 

   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);
         }
       }
     }
   }

Since:
BlackBerry 10.0.0

Related links