Application and
BlackBerry device integration

Item

Description

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 include your application in search results by
performing the following actions:

Register your
application as a searchable application: Implement the
EntityBasedSearchable interface, and
register it with the
SearchRegistry class.

Specify the data
that you want to let users search: You provide searchable data to the search
framework when requested and manually insert new content. To specify searchable
data when the framework requests it, you use
SearchableEntity objects. When the device
starts, the search framework notifies the registered applications to load their
data. The search framework indexes search data when the device is idle or when
requested by the user.

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.

For more information, refer to the classes and interfaces in
the following packages:

net.rim.device.api.unifiedsearch

net.rim.device.api.unifiedsearch.action

net.rim.device.api.unifiedsearch.content

net.rim.device.api.unifiedsearch.entity

net.rim.device.api.unifiedsearch.registry

net.rim.device.api.unifiedsearch.searchables

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:

GEOLOCATION_MODE
retrieves a location from a geolocation source. The geolocation feature
determines and obtains the best location from among the currently available
sources based on factors such as network connectivity, location accuracy and
data availability.

GEOLOCATION_MODE_CELL
retrieves a location based on cell tower positioning.

GEOLOCATION_MODE_WLAN
retrieves a location based on WLAN access point positioning.

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.

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.

getSupportedLocationSources()
determines which location sources are supported on the device

isLocationSourceSupported()
determines if a specified location source is supported on the device

getAvailableLocationSources()
determines which location sources are available on the device

isLocationSourceAvailable()
determines if a specified location source is available on the device

Note: A location source might be supported on the device but
unavailable (for example, the user turned the location source off).

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.

enableGeolocationWithGPS()
returns a GPS fix as soon as it's available or within the specified timeout
period. If the GPS fix in unavailable, a geolocation fix is returned. This
method can be used for single and multiple fix requests.

enableGeolocationWithGPS(int
mode) returns a GPS fix as soon as it's available or within the
specified timeout period. With this method, you can specify the option to
return the fastest single fix that is available. The fastest single fix might
be the first geolocation or GPS fix received.

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:

Each contact
list has a unique UID, which is the value returned by
createPIMList().

The contact
lists do not have service records and do not support wireless synchronization.

Applications can
register to listen for changes to your contact list by invoking
BlackBerryPIMList.addListener().

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:

You cannot
remove contact lists that have service records.

You cannot
remove the last remaining contact list on a device.

You cannot
remove the default contact list (which has the UID -1).

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:

ATTR_MOBILE2 -
attribute used on values in the
TEL field to indicate that the mobile
number is a secondary mobile number

ATTR_FAX2 - attribute
used on values in the
TEL field to indicate that the fax number
is a secondary fax number

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:

A new
ScreenModel class accesses phone screen
objects along with the device orientation (portrait or landscape) and the type
of phone screen (incoming or active). A
ScreenModel can return up to four phone
screen objects: incoming/landscape, incoming/portrait, active/landscape, and
active/portrait.

The
PhoneScreen.getCallerInfoFont() method
retrieves the font of the phone screen which you can use to format the content
that you add to a phone screen so that it uses the same font as the default
content.

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:

isAutoFocusLocked() which queries whether
or not autofocus is locked.

startAutoFocus() which locks the autofocus
and keeps the camera's viewfinder focused until
stopAutoFocus() is called, a picture is
taken, or the viewfinder is closed.