The Bing BlackBerry SDK can be built as an embedded Library that can be added to any BlackBerry application.
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.
All searches must be invoked using the search method on a 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");
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...
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.
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);
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.
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.
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).