Using the Unified Data Source APIs

This section provides code examples that demonstrate how to use some of the functions and features of the UDS library. The examples demonstrate how to use the UDS library in synchronous mode.

To use the examples, you need to include the following header file and classes. For more information about using the Accounts class, see Account.

#include <bb/pim/unified/unified_data_source.h>
#include <QDir>
#include <QThread>
#include <bb/pim/account/account.hpp>
#include <bb/pim/account/AccountService>
#include <bb/pim/account/Provider>
#include <bb/pim/account/Result>

Open a connection to the BlackBerry Hub

You can use uds_init() to initialize the UDS library and open a connection to the BlackBerry Hub so that your app can start adding and manipulating data. This function must be the first UDS function that your app calls.

To use synchronous mode, your app calls this function with the async parameter set to false. To use asynchronous mode, your app calls this function with the async parameter set to true. Check the return value to verify the success of the initialization call.

The primary handle that's used to communicate with the BlackBerry Hub is uds_context_t. You need to pass this handle to many functions that interact with the BlackBerry Hub. If you see a UDS_ERROR_TIMEOUT status, you need to reinitialize by calling uds_init() again.

Not applicable

Not applicable

uds_context_t udsHandle;
int retVal = -1;
bool _async = false;

retVal = uds_init(&_udsHandle, _async);
if (retVal == UDS_SUCCESS) 
{
    printf("uds_init call succeeded \n");
}

/* After the initialization has succeeded,
   you can register your app */

Register your app with the BlackBerry Hub

You can use uds_register_client() to register your app with the BlackBerry Hub. When your app registers using this function, you need to provide a service URL to identify your app, a library path that specifies any modules that must be loaded by the BlackBerry Hub, and a relative path to any assets that your data uses, such as images or icons. This function returns a unique service ID to identify your app, as well as the status of the registration.

The service URL is unique to your app. If the service URL that you use is the same as another one that is already registered, you will get errors. You can't use the service URL that is in the sample code.

You need to determine the perimeter type and then determine the absolute path to the BlackBerry Hub assets. The path to your app's assets is dependent on which perimeter is being used and you need to provide different assets for each perimeter.

If your app hasn't registered with the BlackBerry Hub before or the BlackBerry Hub has been cleared because the device was restarted after an update, the status that's 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 that's 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 of the information. If you see a UDS_ERROR_TIMEOUT status, you need to reinitialize by calling uds_register_client() again.

Not applicable

Not applicable

uds_context_t _udsHandle;
uds_perimeter_type_t _itemPerimeterType;
char _serviceURL[256];
const char* libPath = "";
char _assetPath[256];
int retVal = -1;
int status = 0;

/* Determine the perimeter type */
char *perimeter = getenv("PERIMETER");

if (!strcmp(perimeter, "personal")) 
{
    _itemPerimeterType = UDS_PERIMETER_PERSONAL;
}
else if (!strcmp(perimeter, "enterprise")) 
{
    _itemPerimeterType = UDS_PERIMETER_ENTERPRISE;
}

memset(_serviceURL, 0, 256);
strncpy(_serviceURL, serviceURL.toUtf8().data(), 255);

/* Determine the absolute path for BlackBerry Hub assets */

QString tmpPath = QDir::current().absoluteFilePath("data");
tmpPath = tmpPath.replace("/data", "/public/");
tmpPath = tmpPath.append(hubAssetsFolderName);
tmpPath = tmpPath.append("/");

if (!strcmp(perimeter, "personal")) 
{
    tmpPath = tmpPath.replace("/accounts/1000/appdata", "/apps");
}
else if (!strcmp(perimeter, "enterprise")) 
{
    tmpPath = tmpPath.replace("/accounts/1000-enterprise/appdata", "/apps-enterprise");
}

memset(_assetPath, 0, 256);
strcpy(_assetPath, tmpPath.toUtf8().data());

retVal = uds_register_client(_udsHandle, _serviceURL, libPath, _assetPath);
if (retVal != UDS_SUCCESS) 
{
    /* Something went wrong during the registration process */
    printf("uds_register_client call failed with error %d\n", retVal);
}

if (status == UDS_REGISTRATION_NEW) 
{
    /* If this is a new registration, your app should add all of its 
       data to the BlackBerry Hub */
    printf("uds_register_client call indicates that your app must send
            all of its data to the BlackBerry Hub. \n");
} 
else if (status == UDS_REGISTRATION_EXISTS)
{
    /* If this is an existing registration, your app doesn't
       need to add all of its data again */
    printf("uds_register_client call indicates that your
            app is already registered. \n");   
}

/* After registering your app, you can get the service ID and status */

Retrieve the service ID and service status

You can use uds_get_service_id() to retrieve 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. In asynchronous mode, you should call this function only after you call uds_register_client() and receive a return value of true from uds_get_response() . This function call is optional.

You can use uds_get_service_status() to retrieve 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. In asynchronous mode, you should call this function only after you call uds_register_client() and receive a return value of true from uds_get_response(). This function call is optional.

Not applicable

Not applicable

uds_context_t _udsHandle;
char _serviceURL[256];
const char* libPath = "";
char _assetPath[256];
int retVal = -1;

retVal = uds_register_client(_udsHandle, _serviceURL, libPath, _assetPath);
if (retVal == UDS_SUCCESS) 
{
    serviceId = uds_get_service_id(_udsHandle);
    status = uds_get_service_status(_udsHandle);
}

/* Your app can start adding unique accounts that are associated
   with its features or services */

Create the account service

Before you can add a UDS account, you need to create the corresponding AccountService account first.

Not applicable

Not applicable

Account act;
AccountService accountService;
_nextAccountId = 0;
QString s;
char *p = 0;

if (_itemPerimeterType == UDS_PERIMETER_ENTERPRISE)
{
    displayName.append("-Work");
}

/* Retrieve all of the active accounts that are currently stored on the device */
QList<Account> allAccounts;
do
{
    allAccounts = accountService.accounts();

    if (allAccounts.length() > 0)
    {
        for(int index = 0; index < allAccounts.length(); index++)
        {
            
Account account = allAccounts.at(index);

            if (_itemPerimeterType == UDS_PERIMETER_ENTERPRISE)
            {
                
account.setExternalEnterprise (Property::Enterprise);
                if (account.displayName() == displayName && account.provider().id() == "external" && account.isEnterprise() == Property::Enterprise)
                {
                    _nextAccountId = account.id();
                } else
                {
                    if (account.displayName() == displayName && account.provider().id() == "external")
                    {
                        _nextAccountId = account.id();
                    }
                }
            }
        }
    } while (allAccounts.length() == 0);

    /* Create the message service account */
	if (_nextAccountId != 0) 
    {
        cleanupAccountsExcept(_nextAccountId, displayName);
        accountService.updateAccount (act.id(), act);
	} else
    {
        // Map to the filename of the provider's json file */
        QString providerId("external");
        const Provider provider = accountService.provider(providerId);
        Account account(provider);
        account.setExternalData(true);

        if (_itemPerimeterType == UDS_PERIMETER_ENTERPRISE) 
        {
            account.setExternalEnterprise (Property::Enterprise);
        }
        
        account.setSettingsValue("server", serverName);
        account.setDisplayName(displayName);
        Result r = accountService.createAccount(provider.id(), account);
        
        if (!r.isSuccess())
        {
            s = r.message();
            p = s.toUtf8().data();
            qCritical() << "UDSUtil::addAccount: account create failed !"<<s<<p<<account.isValid();
            act = Account();
        }
		else
        {
            /* Get the account id */
            AccountKey id = account.id();
            act = account;
        }

        if( act.isValid() )
        {
            _nextAccountId = act.id();
        } else
        {
            _nextAccountId = 0;
        }
    }
}

/* You can now start adding accounts */

Add an account

Your app can add unique accounts that are associated with its features or services. You can use uds_account_added() to add an account to the BlackBerry Hub. Typically, your app creates one account to represent its data in the BlackBerry Hub. Each account is represented in the main view of the BlackBerry Hub by a unique tab and icon (which you set using uds_account_data_set_icon() ). Users can select the tab to view your data.

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.

Not applicable

Not applicable

int retVal = -1;
char accountName[256];
uds_account_key_t accountId;
uds_context_t _udsHandle;
uds_account_data_t *account_data = uds_account_data_create();
uds_account_data_set_id(account_data,_nextAccountId);
uds_account_data_set_name(account_data,accountName);
uds_account_data_set_icon(account_data,iconName);

retVal = uds_account_added(udsHandle, account_data);
if (retVal != UDS_SUCCESS)
{
    printf("uds_account_added failed with error %d for account: %s\n", retVal, accountName);
    accountId = -1;
}
else
{
    printf("uds_account_added successfully \n");
}
/* If successful, your app can register account actions and inbox item actions */

Add a category

You can use uds_category_added() to add a category (such as a folder) for inbox list items within an account.

Not applicable

Not applicable

int retVal = -1;
char categoryName[256];
uds_category_data_t *category = uds_category_data_create();
uds_category_data_set_id(category, _nextCategoryId);
uds_category_data_set_parent_id(category, parentCategoryId);
uds_category_data_set_account_id(category, accountId);
uds_category_data_set_name(category, categoryName);

retVal = uds_category_added(_udsHandle, category);
if (retVal != UDS_SUCCESS) 
{
   printf("uds_category_added failed for %s with error %d\n", categoryName, retVal);
   _nextCategoryId = -1;
} 
else 
{
    printf("Category: %s added \n", categoryName);
    _nextCategoryId++;
}
/* Your app can add inbox list items to the category */

Add an inbox list item

You can use uds_item_added() to add an inbox list item to a specific account in the BlackBerry Hub. Before adding an inbox list item, you need to determine the perimeter type.

Like the service URL, the BlackBerry Hub app item MIME types are unique. If you reuse a MIME type that is used by another app, BlackBerry Hub item invocations can stop working or invoke the wrong app or service when trying to view an item or perform a BlackBerry Hub action on an item.

Not applicable

Not applicable

int retVal = -1;
uds_inbox_item_data_t inbox_item = uds_inbox_item_data_create();
uds_inbox_item_data_set_account_id(inbox_item,accountId);
uds_inbox_item_data_set_source_id(inbox_item,sourceId);
uds_inbox_item_data_set_name(inbox_Item,itemName);
uds_inbox_item_data_set_description(inbox_item,subjectDesc);
uds_inbox_item_data_set_icon(inbox_item,iconName);
uds_inbox_item_data_set_mime_type(inbox_item,mime);
uds_inbox_item_data_set_unread_count(inbox_item, read ? 0 : 1);
uds_inbox_item_data_set_total_count(inbox_item,1);
uds_inbox_item_data_set_category_id(inbox_item, categoryId);
uds_inbox_item_data_set_timestamp(inbox_item,timestamp);
uds_inbox_item_data_set_context_state(inbox_item, contextState);

retVal = uds_item_added(_udsHandle, inbox_item);
if (retVal != UDS_SUCCESS) 
{
    printf("uds_item_added failed for %s with error %d\n", 
            itemName, retVal);
}
else
{
    printf("Inbox item: %s added \n", inbox_item);
}

Update an inbox list item

You can use uds_item_updated() to update an inbox list item if its state changes (for example, if the icon changes, if the number of unread messages changes, and so on).

Not applicable

Not applicable

int retVal = -1;

retVal = uds_item_updated(_udsHandle, inbox_item);
if (retVal != UDS_SUCCESS) 
{
    printf("uds_item_updated failed with error %d\n", retVal);
} 
else 
{
    printf("Item updated\n");
}

Remove an inbox list item

You can use uds_item_removed() to remove an inbox list item from the BlackBerry Hub.

Not applicable

Not applicable

int retVal = -1;

retVal = uds_item_removed(_udsHandle, accountId, sourceId);
if (retVal != UDS_SUCCESS) 
{
    printf("uds_item_removed failed with error %d\n", retVal);
} 
else
{
    printf("Item removed\n");
}

Close a connection to the BlackBerry Hub

You can use uds_close() to close the connection to the BlackBerry Hub and release all of the resources that are allocated. This function should be the last UDS function that your app calls.

Not applicable

Not applicable

int uds_close(uds_context_t* pHandle);

Last modified: 2015-07-24



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

comments powered by Disqus