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 Framework

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

Adding the Library to your BlackBerry Project

  1. Right-Click the project that will use the Bing BlackBerry SDK and select Properties.
  2. Choose the Java Build Path item.
  3. Select the Projects tab.
  4. Choose Add and then check off the bbing project.
  5. 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.

  1. Open bbing's application descriptor (BlackBerry_App_Descriptor.xml).
  2. Choose the Build tab on the bottom of the screen.
  3. Click the Add button under the "Preprocessor Directives" section.
  4. 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:

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.url).

Happy Bing-ing!