Bing BlackBerry SDK Documentation

Adding Bing to Your Application

Using Bing in a BlackBerry Application

The Bing BlackBerry SDK can be built as an embedded Library that can be added to any BlackBerry application.

Building the Library

Open Eclipse.
In "Project Explorer" Right-Click.
Choose Import->General->Existing Projects into Workspace.
Import the bbing.

Adding the Library to your BlackBerry Project

Right-Click the project that will use the Bing BlackBerry SDK and select Properties.
Choose the Java Build Path item.
Select the Projects tab.
Choose Add and then check off the bbing project.
Select OK.

When using the Bing BlackBerry SDK as a Library, you can import the necessary Bing objects into your application by using the Bing Library prefix:

import bing.*;

Note that you can also compile the Bing source files directly into your BlackBerry App in addition to using a compiled Library.

Querying Bing

All searches must be invoked using the search method on a Bing object.

Initializing the Bing Object

The Bing object is used to dispatch search requests to the Bing API. In order to initialize the Bing object and use the Bing API you will first need to obtain a Bing Application ID. You can easily sign up for one at the Bing Developer Center.

Bing bing = new Bing("MY_APP_ID");

Performing a Basic Single Source Type Query

To perform a basic web search, you first must instantiate a request object, set any parameters, and then perform the search using the Bing object.

BingWebRequest request = new BingWebRequest();
request.setFileType("pdf");

// Performs a synchronous request
BingWebResponse response = (BingWebResponse)bing.search("Bing API", request);
 
// Do something interesting with the results...

Querying Multiple Source Types at Once

With the Bing API, it is possible to search multiple source types using a single HTTP request. In the Bing BlackBerry SDK, this is called a BundleRequest because it bundles together other request objects. To perform a bundle request, create individual request objects and then add them to a BundleRequest object.

BingWebRequest webRequest = new BingWebRequest();
BingImageRequest imageRequest = new BingImageRequest();

imageRequest.setFilters("Size:Width:320"); // Set request specific options

BingBundleRequest bundle = new BingBundleRequest();
bundle.addRequest(webRequest);
bundle.addRequest(imageRequest);

BingBundleResponse response = (BingBundleResponse)bing.search("Bing API", bundle);

BingResponse[] responses = response.responses();
for(int i = 0; i < responses.length; i++)
{
    BingResponse singleResponse = responses[i];
    BingResult[] results = singleResponse.results();
    for(int k = 0; k < results.length; k++)
    {
        BingResult result = results[k];
        // Do something interesting with the results...
    }
}

Alternatively, you can also pass a list of several requests into the BingBundleRequest initializer. This can provide more concise code.

BingBundleRequest bundle = new BingBundleRequest(new BingRequest[]{ request1, request2, request3 });

Note that when using a bundle, only the top level request options (version, market, etc.) within the Bundle will be respected. The top level request options of all requests passed into the bundle will be removed. Because of this, it is suggested that you create new request objects for each BingBundleRequest object.

Parsing Results From a Bundle Response

For BingBundleResponse objects, the results function will return null, instead use the responses function, it will return an array of BingResponse objects each corresponding to a single source type. An example of how to access individual results from each response can be seen in the previous code example.

Performing Asynchronous Requests

In some cases it may be desirable to perform an asynchronous search. Asynchronous requests are especially useful when creating a BlackBerry application. To perform an asynchronous search, pass in a delegate object that implements the BingAsyncRequestNotification informal interface to the search(String,BingRequest,BingAsyncRequestNotification) method. Everything else is exactly the same.

public class MySampleDelegate implements BingAsyncRequestNotification
{
    public void receiveBingResponse(BingResponse response)
    {
        // Do something interesting with the results...
    }
}

...

MySampleDelegate myDelegate = new MySampleDelegate();
BingWebRequest webRequest = new BingWebRequest();

bing.search("Bing API", webRequest, myDelegate);

Handling Errors

If an error is encountered while querying the API, a null value will be returned instead of a BingResponse object. The most common cause for this is an invalid Application ID. However, an error can also be caused by setting an invalid parameter in one of the BingRequest objects.

For more detailed error messages, compile the Bing Library in with the BING_DEBUG which can be set in the Bing Library's BlackBerry_App_Descriptor.xml.

Open bbing's application descriptor (BlackBerry_App_Descriptor.xml).
Choose the Build tab on the bottom of the screen.
Click the Add button under the "Preprocessor Directives" section.
Type BING_DEBUG into the pop-up that comes up and select OK.

If Bing Library has BING_DEBUG defined then a couple extra functions appear in the Bing class. These classes are to allow the developer to handle full error messages by setting their Bing object to return a BingError if an error occurs. The BingError object will be returned in the BingResponse to developer's query.

Available SourceTypes

Currently, the Bing BlackBerry SDK supports the following Bing SourceTypes:

Ad Request
Image Request
InstantAnwser Request
MobileWeb Request
News Request
Phonebook Request
RelatedSearch Request
Spell Request
Translation Request
Video Request
Web Request

Each of the available source type result objects has its properties defined in the Bing API Documentationation

The properties of the result objects can be easily accessed using dot notation (ex: myWebResultObject.getUrl()).

Unified Search

As of BlackBerry OS 6.0, a new search API has been implemented known as Unified Search. This API allows users and developers to search the web, 3rd party apps and data, and the BlackBerry handheld itself for information.

bbing has a Unified Search implementation built in as of 2.2.1, this allows for simple setup and cleanup of what is known as an ExternalSearchProvider. This creates a single search icon that allways appears when a search is performed, when the icon is selected the "External Search Provider" performs its search and returns the results on its own UI.

Using bbing, the developer creates a SearchProviderOptions and registers it with UnifiedSearch. That's it, bbing does the rest.

Creating a SearchProviderOptions

This is very easy. SearchProviderOptions is a special wrapper around a callback called SearchCallback. Implement SearchCallback, pass it into a SearchProviderOptions and this step is done.

SearchProviderOptions options = new SearchProviderOptions(new new SearchCallback()
{
    //SearchCallback implementation
});

The options provider should be saved because it will be used to register and unregister your search system.

Registering SearchProviderOptions

This is very easy:

UnifiedSearch.registerSearchProvider(options);

That's it! Before this when you did a search nothing showed up. Now if you do a search, a icon appears that can be selected and (if a search UI has been implemented) the UI with the results is displayed

Note: One element of SearchCallback is a function called updated. This function can be used to alert registerSearchProvider that the name and/or icon of the provider has been updated. This does not automatically occur, if the name or icon get updated the devloper can call registerSearchProvider again and pass in the same SearchProviderOptions. As long as the options provider is not in use it will be updated with the new icon and name.

Also remeber to unregister your SearchProviderOptions when it is no longer needed. Failing to unregister your SearchProviderOptions can cause unpredictable operations to occur or multiple search options to appear when a search is performed.

To create a singleton search implementation, follow the following developer article "Ensure that a device runs a single instance of your application" adapting the code so that instead of the operation occuring at search time it occurs at register time.

Unregistering SearchProviderOptions

This is extremely easy again:

UnifiedSearch.unregisterSearchProvider(options);

Other Unified Search notes

A couple small requirements for using Unified Search exist:

Application signing is required. If no signing is desired then use the define NO_SIGNING. This will disable the need for application signing but will also disable Unified Search support.
Requires OS/API 6.0 or higher. This is a given, luckily Unified Search support is determined internally. It determine is Unified Search is supported at runtim call UnifiedSearch.isSupported().