providing search functionality by using the Unified Search API

You can leverage the search functionality that is available on the BlackBerry device by using the Unified Search API. The search functionality that is provided in BlackBerry Device Software 6.0 provides users with a simplified search application that is available from the Home screen. Users can search for content on their device, content that is available off of the device or on the Internet, and search for content available from third-party applications. As users type search criteria, search results are displayed along with an associated application icon. You can include your application in search results and also invoke searches from your application so that your users can easily perform searches.

You can invoke the search functionality by performing the following actions:

• You can conduct a search on all searchable data sources and fields by submitting keywords to the UnifiedSearchServices.search() method.
• Optionally, you can restrict the search to specific searchable data sources and fields within those sources by submitting them to the search() method. To retrieve a list of searchable data sources, invoke the UnifiedSearchServices.getDeviceSearchables() method. To retrieve a list of searchable fields, invoke the defineSupportedSearchFields() on each searchable object.
• The search() method returns a SearchResponse object. You can find your search results in a Hashtable that arranges SearchableEntity objects as values and the Searchable and the SearchField objects that generated the match as values.

You can provide users an option to run their query on your network server (behind the corporate firewall, or public web service) by performing the following actions:

• Create an application that extends the ExternalSearchProvider interface.
• Implement the ExternalSearchProvider.search() method to invoke several actions in you application, such as:
  • make a network connection
  • submit the user's query to your search engine
  • retrieve and display the results
• Register your application using the SearchRegistry class

Users of the Universal search application will see all registered external search providers in their search. When they click on one, Universal search invokes the provider's search() method.

enhancement to retrieving the default GPS mode

You can use the GPSInfo.getDefaultGPSMode() method that is provided in the net.rim.device.api.gps package to retrieve the default GPS mode. By default, the getDefaultGPSMode() method now returns the modes in the following order: assisted, autonomous, and cellsite. The assisted mode is selected as the default when assisted GPS can be provided to the application without requiring additional credentials from the application.

If you do not specify a GPS mode when requesting a location update, the default mode is determined using the GPS capability supported by the wireless network.

new geolocation modes

You can use the following modes that are provided in the new net.rim.device.api.gps.LocationInfo class to retrieve location information from the geolocation service:

You can use the LocationInfo.isModeAvailable() method that is provided in the net.rim.device.api.gps.LocationInfo package to query if a specific mode is available. You can specify a geolocation mode from the LocationInfo class, or a mode from the GPSInfo class as a parameter for the LocationInfo.isModeAvailable() method.

You can use the geolocation modes in the BlackBerryCriteria class to request a location provider for geolocation from the BlackBerryLocationProvider class.

If you specify the GPSInfo.GPS_MODE_CELLSITE mode, the location is retrieved from cell site towers. If this mode is not supported or available by the wireless service provider, the location is retrieved using GEOLOCATION_MODE.

For more information about the geolocation modes, visit www.blackberry.com/go/devguides to read the BlackBerry Java Application Location-Based Services Development Guide.

perform reverse geocoding requests at the postal code or zip code level

You can use the Locator.POSTAL_ZIP_CODE constant as a parameter to perform a reverse geocoding request at the postal code or zip code level. This constant returns the postal/zip code, province/state and country.

querying location sources

You can use the following methods in the LocationInfo class to determine which location sources (internal GPS receiver, external GPS receiver, or geolocation) are supported or available on the device.

requesting both GPS and geolocation updates in parallel

You can now specify parallel requests for GPS and geolocation updates. For example, you can provide the user with a quick approximate location before a GPS fix is available. To request both GPS and geolocation updates in parallel, create two separate threads to request separate instances of the BlackBerryLocationProvider class. One thread specifies a GPS mode, and the other thread specifies a geolocation mode.

requesting both GPS and geolocation updates with new methods

You can use one of the following new methods in the BlackBerryCriteria to request geolocation fixes whenever GPS fixes are unavailable. The geolocation fix that is returned is the optimal geolocation fix that is available.

setting a default content handler

You can register your application as the default handler for a content type by using the DefaultContentHandlerRegistry class provided in the net.rim.device.api.content package. If multiple content handlers are registered for a content type, BlackBerry device users have the ability to choose the content handler they want to use and to set the default content handler.

turning on and querying Location Services on the device

You can use the LocationInfo.isLocationOn() method to determine if the Location Services option on the device is turned on. If Location Services is turned on but the user turns off the geolocation feature in the Location Data option, geolocation services are unavailable.

You can use the LocationInfo.setLocationOn() method to turn on the Location Services option on the BlackBerry device. If the Location Services option is turned on, your application can retrieve location information using the available location sources (for example, GPS and geolocation). You should prompt the user before turning on the Location Services option.

enhancements to the Message List API

The Message List API has been enhanced to display the new message indicator for the messages application when there are application messages that have not been opened by the user. The new message indicator is the same indicator (for example, a red asterisk overlaid on the indicator icon) that is used for other standard messages, such as emails.

Two methods in the ApplicationMessageFolder class have been overloaded to indicate that the application message folder contains new messages: fireElementAdded(ApplicationMessage AppMsg, boolean newMessage) and fireReset(boolean hasNewMessages). If the boolean parameter is true, the new message indicator is displayed. The indicator is automatically cleared when the message list is opened. Note that by default application messages with the status UNREAD are treated as new. To override this behavior, specify false in the second argument to fireElementAdded().

The ApplicationMessageFolderListener contains a new constant, MESSAGE_MARKED_OLD, which is performed when the user opens the message list, telling listeners that the application messages have been partially viewed. Note that the user doesn't have to open the message itself, only that the partial information, such as contact name and subject, has been viewed.

The ApplicationIndicator class has a new method, setNotificationState(boolean isNew). If isNew is true, the indicator indicates that there are new messages that have not been opened. Your application should listen for the message list open event based on the MESSAGE_MARKED_OLD constant and clear the new indicator status by calling setNotificationState(false). Also, you can now invoke the messages application to view an application message folder by using the new MessageArguments constructor, MessageArguments(ApplicationMessageFolder folder), where folder is a registered application message folder.

creating and managing contact lists

You can now create contact lists by using theBlackBerryPIM.createPIMList(int type,String name) method in net.rim.blackberry.api.pdap.BlackBerryPIM. Currently, the type specified in createPIMList() must be PIM.CONTACT_LIST or PIMException is thrown.

Note the following about creating contact lists:

You can also remove contact lists by using one of the BlackBerryPIM.removePIMList() methods. Currently, these methods support PIM lists only of type PIM.CONTACT_LIST.

Note the following about removing contact lists:

The new exception BlackBerryPIMRemovalException is thrown if an error occurs when you try to remove a contact list.

looking up contact information associated with a telephone call

You can now look up a contact corresponding to a phone call. If the phone call is active, you can use the new PhoneCall.getContact() method in a PhoneListener.

If a phone call has been completed, you can get the contact information from the phone call log by using the new PhoneCallLogID.getContact() method.

looking up contact information associated with a telephone number

You can use the BlackBerryContactList.getContactsByPhoneNumber() method to search all contact lists for a matching phone number.

You can also search a specific contact list for contacts with a matching phone number by using one of the new BlackBerryContactList.itemsByPhoneNumber() methods.

new contact fields

The net.rim.blackberry.api.pdap.BlackBerryContact class has the following two new fields, which provide the ability for a contact to have two mobile or fax telephone numbers:

updating calendar entries without sending notification

You can now update a calendar entry on a BlackBerry device without sending a notification to the meeting's participants.

BlackBerryPIMItem is a new interface with a commit(int flags) method. Currently, the only supported flag is the new field BlackBerryEvent.DO_NOT_NOTIFY_ATTENDEES. Pass this field into the method to commit changes to a calendar entry without notifying attendees.

If you use the flag BlackBerryEvent.DO_NOT_NOTIFY_ATTENDEES when committing changes to a calendar entry, notification is not sent unless it is a new meeting or meeting attendees have been added since the last update (attendees must be notified about the meeting to acceptor decline the meeting). The commit(int flags) method returns BlackBerryEvent.MEETING_RECORD_NOT_FOUND or BlackBerryEvent.INVITEE_LIST_CHANGED if the notification was sent.

Similarly, BlackBerryEventList has a new method: removeElement(Eventelement,intflags). Currently, the only supported flag is BlackBerryEvent.DO_NOT_NOTIFY_ATTENDEES. Pass this field into the method to remove a calendar entry without notifying attendees.

enhancements to the Phone Screen API

The Phone Screen API has been enhanced with new features and features that make it easier for you to add content to a phone screen. In BlackBerry Java API 5.0, the Phone Screen API provided in the net.rim.blackberry.api.phone.phonegui package enabled you to add content to the phone screen on the BlackBerry device. The Phone Screen API has been enhanced to support the following features:

responding to convenience key events

You can now register your application with the KeyHandlerRegistry to receive convenience key events in your application. Your application can now respond to any combination of presses or holds of the convenience keys.

Your application must implement the KeyListener interface to handle these events.

enhanced focus control for the camera's autofocus

You can use the net.rim.device.api.amms.control.camera.EnhancedFocusControl interface, which extends the FocusControl class and provides the following methods, to enhance the existing camera's autofocus functionality: