Unified Data Source Library

You can use the Unified Data Source (UDS) library to add data from your app directly to the BlackBerry Hub. By integrating your data with the BlackBerry Hub, you can make it easier for users to interact with your app to view updates, create new content, and more.

For example, if your app provides regular notifications of certain events (say, updates to content that your app provides, or reminders to renew subscriptions to your app's content), you can register with the BlackBerry Hub to include these notifications in a dedicated account view for your app data. Or, if your app lets users send messages or start conversations with other users, you can integrate your chat and conversation interface with the BlackBerry Hub and let users view and create messages there, instead of needing to open your app explicitly.

When your app adds data to the BlackBerry Hub, this data is available to users even when your app isn't running. The only exception is if the schema of the BlackBerry Hub changes (for example, after an upgrade of the OS on the device), in which case you might need to add your data to the BlackBerry Hub again to make it available to users.

Required permissions

To use the UDS library in your app, you need to include the following two permissions in the bar-descriptor.xml file of your project:

<permission system="true">_sys_manage_pimdomain_external_accounts
    </permission>
<permission>_sys_access_pim_unified</permission>

To learn more about permissions, see App permissions.

These UDS library permissions also require you to apply for them before you can use them in your app. Please email hubdevsupport@blackberry.com with your detailed use cases.

Elements of the UDS library

The UDS library consists of several elements that you can interact with and use to organize your data in the BlackBerry Hub.

Accounts

An account represents a grouping of related items that can be displayed together in the BlackBerry Hub. If you open the BlackBerry Hub on a device, you'll notice that there are already some accounts that are predefined, such as "Notifications", "BBM", and "Text Messages". These accounts appear as tabs in the BlackBerry Hub, and you can add your own accounts to this list. When you add an account, it also appears in the Hub Management settings screen (which allows users to choose to show or hide items in specific accounts).

Account-related data is represented by the uds_account_data_t structure. This structure includes all of the information that's required to register and display an account in the BlackBerry Hub, such as name, description, icon, and so on.

Inbox list items

An inbox list item is an individual item that appears in an account in the BlackBerry Hub. For example, if you're viewing an account that's associated with an email account, each message that appears in that view is an inbox list item. You can add data from your app as inbox list items, and you can associate these items with accounts in the BlackBerry Hub so that they're displayed on that account's tab.

Data that's related to inbox list items is represented by the uds_inbox_item_data_t structure. This structure includes all of the information that's required to add and display an inbox list item in the BlackBerry Hub, such as source ID, category ID, name, and so on.

Categories

A category is a grouping of items within an account. You can use categories to sort and filter inbox list items in the account. For example, a messaging account might contain folders for different types of messages, and each folder is considered a category.

Category-related data is represented by the uds_category_data_t structure. This structure includes all of the information that's required to correctly place a category in a particular account, such as account ID, parent ID, type, and so on.

Account actions

An account action is an option that users can select when they view a particular account in the BlackBerry Hub. Account actions can appear in the action bar at the bottom of the screen, in the overflow menu, or in both locations.

You can associate an account action with one of the invocation actions that are available as part of the invocation framework. When a user selects the account action in the BlackBerry Hub, the appropriate target application is invoked to perform the action. For example, you might specify the "bb.action.CREATE" invocation action for an account action. To learn more about actions, targets, and other invocation framework principles, see App integration.

Data that's related to account actions is represented by the uds_account_action_data_t structure. This structure includes all of the information that's required for an account action, such as the target, type, MIME type, and so on.

Inbox item actions

An inbox item action is similar to an account action, but applies to the inbox list items that appear within an account in the BlackBerry Hub. Inbox item actions appear in the context menu when a user presses and holds an inbox list item.

Again, similar to account actions, you can associate an inbox item action with one of the invocation actions that are available as part of the invocation framework. To learn more about invocation framework principles, see App integration.

Inbox item actions typically appear in the context menu for all inbox list items in a particular account. Additionally, you can specify context-sensitive inbox actions, which appear only for certain inbox list items, depending on the state of the item.

Data that's related to inbox item actions is represented by the uds_item_action_data_t structure. This structure includes all of the information that's required for an inbox item action, such as the target, type, MIME type, and so on.

Modes for the UDS library

You can choose to use the UDS library in one of two modes: synchronous or asynchronous. This section describes how both of these modes work and introduces you to some common functions in the UDS library. For a full code sample that illustrates how to use library functions, see the "Using the Unified Data Source APIs" section below.

Synchronous mode

In this mode, all calls to UDS library functions (such as uds_account_added(), uds_item_updated(), and so on) block until a response is received from the BlackBerry Hub server, or until an error occurs.

To show how this mode works, consider the following sequence of function calls. This sequence illustrates how you might choose to use some common functions in the UDS library.

1. uds_init() - Opens a connection to the BlackBerry Hub using the UDS library. To use synchronous mode, you call this function with the async parameter set to false.

2. uds_register_client() - Registers your app with the BlackBerry Hub. This function provides a unique service ID to identify your app, as well as the status of the registration.

If your app hasn't registered with the BlackBerry Hub before, the status received is UDS_REGISTRATION_NEW. In this case, your app must send all of its information (such as account information, inbox list item information, and so on) to the BlackBerry Hub for population.

If your app has previously registered with the BlackBerry Hub, the status received is UDS_REGISTRATION_EXISTS. In this case, you can choose to send only the information that is new since your app last synchronized with the BlackBerry Hub, instead of sending all information.

3. uds_get_service_id() - Retrieves the service ID that's assigned to identify your app to the BlackBerry Hub. In synchronous mode, you should call this function only after you call uds_register_client() and receive UDS_SUCCESS from that function. This function call is optional.

4. uds_get_service_status() - Retrieves the service status after you register your app with the BlackBerry Hub. In synchronous mode, you should call this function only after you call uds_register_client() and receive UDS_SUCCESS from that function. This function call is optional.

5. uds_account_added() - Adds an account to the BlackBerry Hub. Typically, your app creates one account to represent its data in the BlackBerry Hub. Each account is represented by a unique tab and icon (which you set using uds_account_data_set_icon()).

6. uds_category_added() - Adds a category (such as a folder) for inbox list items within an account.

7. uds_item_added() - Adds an inbox list item to a specific account in the BlackBerry Hub.

8. uds_item_updated() - Updates an inbox list item if its state changes (for example, if the icon changes, if the number of unread messages changes, and so on).

9. uds_item_removed() - Removes an inbox list item from the BlackBerry Hub.

Asynchronous mode

In this mode, all calls to UDS library functions will return immediately after sending the associated command to the BlackBerry Hub server. You call uds_wait_for_response() on a separate thread to block until you receive a response. Then, when a response is available, you can call uds_get_response() to retrieve and parse the response. You might choose to use asynchronous mode instead of synchronous mode if you want your app to be able to continue doing its own operations (such as processing information while it's waiting for responses from the BlackBerry Hub server.

To show how this mode works and how it's different than synchronous mode, consider the following sequence of function calls. This sequence performs the same operations as the sequence presented in the "Synchronous mode" section above, but because asynchronous mode is used, a few extra function calls to wait for and retrieve responses are required. Note that some of the descriptions of functions have been abbreviated, so check the descriptions in the "Synchronous mode" section for full details.

1. uds_init() - Opens a connection to the BlackBerry Hub using the UDS library. To use asynchronous mode, you call this function with the async parameter set to true.

2. uds_register_client() - Registers your app with the BlackBerry Hub.

3. uds_wait_for_response() - Blocks (possibly on a separate thread) and waits for a response from the BlackBerry Hub server. Here, this function waits for a response regarding the uds_register_client() command that was sent in step 2 above.

4. uds_get_response() - Retrieves and parses the response. Here, we're retrieving the response from the uds_register_client() command that was sent in step 2 above.

5. uds_get_service_id() - Retrieves the service ID that's assigned to identify your app to the BlackBerry Hub. In asynchronous mode, you should call this function only after you call uds_register_client() and receive and parse the response using uds_get_response(). This function call is optional.

6. uds_get_service_status() - Retrieves the service status after you register your app with the BlackBerry Hub. In asynchronous mode, you should call this function only after you call uds_register_client() and receive and parse the response using uds_get_response(). This function call is optional.

7. uds_account_added() - Adds an account to the BlackBerry Hub.

8. uds_wait_for_response() and uds_get_response() - Blocks and waits for a response regarding the uds_account_added() command that was sent in step 7 above. Then, retrieves and parses the response.

9. uds_category_added() - Adds a category (such as a folder) for inbox list items within an account.

10. uds_wait_for_response() and uds_get_response() - Blocks and waits for a response regarding the uds_category_added() command that was sent in step 9 above. Then, retrieves and parses the response.

11. uds_item_added() - Adds an inbox list item to a specific account in the BlackBerry Hub.

12. uds_wait_for_response() and uds_get_response() - Blocks and waits for a response regarding the uds_item_added() command that was sent in step 11 above. Then, retrieves and parses the response.

13. uds_item_updated() - Updates an inbox list item if its state changes (for example, if the icon changes, if the number of unread messages changes, and so on).

14. uds_wait_for_response() and uds_get_response() - Blocks and waits for a response regarding the uds_item_updated() command that was sent in step 13 above. Then, retrieves and parses the response.

15. uds_item_removed() - Removes an inbox list item from the BlackBerry Hub.

16. uds_wait_for_response() and uds_get_response() - Blocks and waits for a response regarding the uds_item_removed() command that was sent in step 15 above. Then, retrieves and parses the response.

Using the Unified Data Source APIs

This section provides some sample code that demonstrates how to use the functions and features of the UDS library. Note that this sample demonstrates how to use the UDS library in synchronous mode.

First, your app must register with the BlackBerry Hub and include some required data in the registration request, such as name, asset path, and so on.

uds_context_t udsHandle;
int retVal = -1;
int serviceId = 0;
int status = 0;
bool async = false;

if ((retVal = uds_init(&udsHandle, async)) == UDS_SUCCESS)
{
    char* serviceURL = "c_lib_service";
    char* libPath = "";
    char* assetPath = "/apps/com.example.UDSTestApp.testDev__UDSTestApp9ded287c/app/public/assets/images";
    if( (retVal = uds_register_client(udsHandle, serviceURL,
                                      libPath, assetPath))
                                      != UDS_SUCCESS)
    {
        printf("uds_register_client call failed with error %d\n",
               retVal);
    }
    if (retVal == UDS_SUCCESS)
    {
        serviceId = uds_get_service_id(udsHandle);
        status = uds_get_service_status(udsHandle);
    }
}
printf("uds_register_client call successful with %d as serviceId
        and %d as status\n", serviceId, status);

Next, your app can add unique accounts that are associated with its features or services. When you add an account, it appears as a tab in the main view of the BlackBerry Hub. Users can select the tab to view your data.

uds_account_data_t paccount_data = uds_account_data_create();
uds_account_data_set_id(account_data,1000);
uds_account_data_set_name(account_data,"My C Account");
uds_account_data_set_icon(account_data,"ic_account.png");
uds_account_data_set_target_name(account_data,"com.example.service");
  
if (0 != (retVal = uds_account_added(udsHandle, account_data)))
{
    printf("uds_account_added failed with error %d \n", retVal);
}

Now, your app can register account actions and inbox item actions. Account actions apply to the account as a whole, and they appear on the action bar (or in the overflow menu) when users view the tab for your account. Inbox item actions appear in the context menu when users press and hold an inbox list item in your account.

// Client service supported and defined actions on list items
typedef enum{
    Read = 0x01<<0,
    Unread = 0x01<<1,
    FriendRequest = 0x01<<2
} ActionState;

uds_account_action_data_t account_action = uds_account_action_data_create();
AccountActionData aItem;
uds_account_action_data_set_action(account_action,"bb.action.SHARE");
uds_account_action_data_set_target(account_action,"UDSTestApp");
uds_account_action_data_set_type(account_action,"text/plain");
uds_account_action_data_set_title(account_action,"Status");
uds_account_action_data_set_image_source(account_action,
                                         "ic_status.png");
uds_account_action_data_set_placement(account_action,
    uds_placement_type_t::UDS_PLACEMENT_BAR);
    
if (UDS_SUCCESS!= (retVal = uds_register_account_action(udsHandle,
                                1000, account_action)))
{
    printf("uds_register_account_action failed with error %d\n",
           retVal);
}
uds_account_action_destroy(action_data);

uds_item_action_data_t item_action = uds_item_action_data_create();
uds_item_action_data_set_action(item_action,"bb.action.MARKREAD");
uds_item_action_data_set_target(item_action,"text/plain");
uds_item_action_data_set_title(item_action,"Mark Read");
uds_item_action_data_set_image_source(item_action,"ca_uds_read.png");
uds_item_action_data_set_mime_type(item_action,"plain/message");
uds_item_action_data_set_context_mask(item_action,Read);
    
if (UDS_SUCCESS!= (retVal = uds_register_item_context_action(udsHandle,
                                1000, item_action)))
{
    printf("uds_register_item_context_action failed with error %d\n",
           retVal);
}
uds_item_action_destroy(item_action);

Finally, your app can add inbox list items that represent your data, as well as categories if you want to sort the items within an account.

uds_inbox_item_data_t pInboxItem = uds_inbox_item_data_create();
uds_inbox_item_data_set_account_id(pInboxItem,1000);
uds_inbox_item_data_set_source_id(pInboxItem,"1");
uds_inbox_item_data_set_name(pInboxItem,"C Inbox Item Unread");
uds_inbox_item_data_set_description(pInboxItem,"C Subject Unread");
uds_inbox_item_data_set_icon(pInboxItem,"ca_uds_unread.png");
uds_inbox_item_data_set_mime_type(pInboxItem,"plain/message");
uds_inbox_item_data_set_unread_count(pInboxItem,1);
uds_inbox_item_data_set_total_count(pInboxItem,1);
uds_inbox_item_data_set_category_id(pInboxItem,1);
uds_inbox_item_data_set_timestamp(pInboxItem,1373405489000);
uds_inbox_item_data_set_context_state(pInboxItem,Read);
   
if (UDS_SUCCESS!= (retVal = uds_item_added(udsHandle, pInboxItem)))
{
    printf("uds_item_added failed with error %d\n", retVal);
}
uds_inbox_item_data_destroy(pInboxItem);

Last modified: 2014-06-26



Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus