net.rim.device.api.servicebook
Class ServiceBook

java.lang.Object
  net.rim.device.api.servicebook.ServiceBook

All Implemented Interfaces:

ITPolicyChangedListener, ITPolicyListener, MultiServicePlatformListener, Persistable

public final class ServiceBook
extends Object
implements Persistable, ITPolicyChangedListener, MultiServicePlatformListener

Contains all ServiceRecords currently defined.

Use this class to maintain a collection of information about particular aspects of the BlackBerry Wireless Handheld such as connection information. In particular, the service book is used to manage HTTP (MDS) connections and mail (CMIME) information such as account and email hierarchy information.

It is possible to listen for service book events through the globalEventListener interface (refer to the GUID_* events).

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.0.0

Nested Class Summary
	static class	ServiceBook.DuplicateSecureServiceException Exception for signalling duplicate secure service.
	static class	ServiceBook.SecurityViolationException
	static class	ServiceBook.ServiceStatus Service Statuses This class will hold various service status information Currently only the last pin status is implemented.

Field Summary
	static int	ACK_FAILURE
	static int	ACK_SUCCESSFUL
	static int	COMMAND_DELETE_SERVICE
	static int	COMMAND_INJECT_SERVICE
	static int	COMMAND_SERVICE_STATUS
	static int	COMMAND_SWITCH_SERVICE
	static int	DUP_NONE Represents a code indicating that there were no duplicate records.
	static int	DUP_REMOVED Represents a code indicating that there were duplicate records removed, but nothing was replaced.
	static int	DUP_REPLACED Represents a code indicating that there were duplicate records removed.
	static long	GUID_SB_ADDED The GUID for the global event sent when a service book is added.
	static long	GUID_SB_BR_END The GUID for the global event sent when service book backup-restore ends.
	static long	GUID_SB_BR_START The GUID for the global event sent when service book backup-restore starts.
	static long	GUID_SB_CHANGED The GUID for the global event sent when a service book is changed.
	static long	GUID_SB_OTA_SWITCH The GUID for the global event sent when all service records are inserted due to a move BES command OTA.
	static long	GUID_SB_OTA_UPDATE The GUID for the global event sent when all service records are updated for a UID OTA.
	static long	GUID_SB_PIN_CHANGE The GUID for the global event sent when a service replaces an old service and the server is reporting that the PIN last activated on that service has changed.
	static long	GUID_SB_POLICY_CHANGED The GUID for the global event sent when the service book responds to an IT Policy changed event.
	static long	GUID_SB_REMOVED The GUID for the global event sent when a service book is removed.
	static int	NEW_SERVER_UID
	static int	RESULT_CUSTOM_ERROR
	static int	RESULT_DUPLICATE_SERVICE_ERROR
	static int	RESULT_GENERAL_ERROR
	static int	RESULT_KEY_ERROR
	static int	RESULT_KEY_MISMATCH
	static int	RESULT_PACKET_PARSE_ERROR
	static int	RESULT_SECURITY_VIOLATION_ERROR
	static int	RESULT_SUCCESS
	static int	RESULT_SWITCH_PENDING_ERROR
	static int	RESULT_UNKNOWN_COMMAND
	static int	RESULT_UNSUPPORTED_CMD_VERSION
	static long	SB_GUID The GUID of the service book.
	static int	SEND_ACK_FLAG
	static int	SERVICEBOOK_PAYLOAD_VERSION_3
	static byte	SERVICE_RECORD_SUMMARY_RECORD
	static int	SERVICE_STATUS_FIELD
	static int	SOURCE_SERVER_UID
	static int	STATUS_LAST_PIN
	static int	TO_BE_DELETED_SERVER_UID
	static int	VIEW_MODE_R Indicates that the service book has read view mode access.
	static int	VIEW_MODE_RO Indicates that the service book has read-only view mode access.
	static int	VIEW_MODE_RW Indicates that the service book has read-write view mode access.
	static int	VIEW_MODE_UNKNOWN Indicates that the service book has an unknown view mode.

Method Summary
	void	commit() Commits changes to the persistent store.
	void	deRegisterCIDAsSingleton(String CID) Allows an application to revoke the singleton restriction.
	void	deRegisterCIDAsSingleton(String CID, boolean secureServices, boolean insecureServices) Allows an application to revoke the singleton restriction.
	ServiceRecord[]	findDuplicateRecords(ServiceRecord rec, int newType, String newName, String newUid, String newCid, String dataSourceId, int userId) Retrieves any and all duplicates of the specified record.
	ServiceRecord[]	findDuplicateRecords(ServiceRecord rec, int newType, String newName, String newUid, String newCid, String dataSourceId, int userId, String newUserIdentity, String newSourceIdentity) Retrieves any and all duplicates of the specified record.
	ServiceRecord[]	findRecordsByCid(String cid) Retrieves all service records with specified content ID.
	ServiceRecord[]	findRecordsByName(String name) Retrieves all service records with specified name.
	ServiceRecord[]	findRecordsByType(int type) Retrieves all service records of specified type.
	ServiceRecord[]	findRecordsByUid(String uid) Retrieves all service records with specified UID.
	ServiceRecord	getCIDAssociatedWithService(String targetCID, int userID, String dsID, String uid) Retrieve a service record that matches your provided parameters.
	ServiceRecord	getCIDAssociatedWithService(String targetCID, ServiceRecord sr) Retrieve a specific service record with a target CID that is associated with a provided service record.
	int	getNumRecords(int type) Retrieves the number of records with the specified type in the service book.
	ServiceRecord	getRecordByCidAndDataSourceId(String cid, String aDataSourceId) Retrieves service record by CID and data source ID.
	ServiceRecord	getRecordByCidAndHash(String cid, int nameHash, int uidHash) Retrieves service record by CID and either name hash or UID hash.
	ServiceRecord	getRecordByCidAndSid(String cid, long sid) Retrieves service record by service identifier (sid)
	ServiceRecord	getRecordByCidAndSid(String cid, long sid, boolean useServiceEquivalency) Retrieves service record by service identifier (sid)
	ServiceRecord	getRecordByCidAndSid(String cid, long sid, boolean useServiceEquivalency, boolean onlyActiveRecord) Retrieves service record by service identifier (sid)
	ServiceRecord	getRecordByCidAndUserId(String cid, int userId) Retrieves service record user ID
	ServiceRecord	getRecordByCidAndUserId(String cid, int userId, int nameHash, int uidHash) Retrieves service record with a specified CID by user ID, if not found by user ID it is the service record with the CID, name hash and UID hash is returned.
	ServiceRecord	getRecordById(int id) Retrieves a service record by ID.
	ServiceRecord	getRecordByUidAndCid(String uid, String cid) Retrieves service record by UID and CID.
	ServiceRecord[]	getRecords() Retrieves all records.
	static ServiceBook	getSB() Retrieves the service book from the Factory.
	boolean	getSerialInjectionInProgress() Gets the current state of serial service record injection
	byte[]	getServiceList() Get the Service Record list summary encoding (used by the Device Agent Database.)
	ServiceBook.ServiceStatus	getStatusForUid(String uid) Get the status for a Server (UID)
	boolean	isAllowedRecord(ServiceRecord sr, int newType, String newName, String newUid, String newCid) Verifies that a record is allowed in the current book, according to IT policy settings.
	void	registerCIDAsSingleton(String CID) Allows an application to indicate that only one CID is supported.
	void	registerCIDAsSingleton(String CID, boolean secureServices, boolean insecureServices) Allows an application to indicate that only one CID is supported.
	void	setSerialInjectionInProgress(boolean flag) Sets current state of serial service record injection

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface net.rim.device.api.itpolicy.ITPolicyChangedListener

policyChanged

Methods inherited from interface net.rim.device.api.system.MultiServicePlatformListener

wipe

Field Detail

SB_GUID

public static final long SB_GUID

The GUID of the service book.

See Also:

Constant Field Values

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.0.0

DUP_NONE

public static final int DUP_NONE

Represents a code indicating that there were no duplicate records.

See Also:

Constant Field Values

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.0.0

DUP_REMOVED

public static final int DUP_REMOVED

Represents a code indicating that there were duplicate records removed, but nothing was replaced.

See Also:

Constant Field Values

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.0.0

DUP_REPLACED

public static final int DUP_REPLACED

Represents a code indicating that there were duplicate records removed.

In addtion, one record's internals were replaced by the master's. The master record has now been removed.

See Also:

Constant Field Values

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.0.0

GUID_SB_ADDED

public static final long GUID_SB_ADDED

The GUID for the global event sent when a service book is added.

See Also:

Constant Field Values

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.0.0

GUID_SB_REMOVED

public static final long GUID_SB_REMOVED

The GUID for the global event sent when a service book is removed.

See Also:

Constant Field Values

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.0.0

GUID_SB_CHANGED

public static final long GUID_SB_CHANGED

The GUID for the global event sent when a service book is changed.

See Also:

Constant Field Values

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.0.0

GUID_SB_BR_START

public static final long GUID_SB_BR_START

The GUID for the global event sent when service book backup-restore starts.

See Also:

Constant Field Values

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.0.0

GUID_SB_BR_END

public static final long GUID_SB_BR_END

The GUID for the global event sent when service book backup-restore ends.

See Also:

Constant Field Values

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.0.0

GUID_SB_OTA_UPDATE

public static final long GUID_SB_OTA_UPDATE

The GUID for the global event sent when all service records are updated for a UID OTA.

See Also:

Constant Field Values

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.0.0

GUID_SB_OTA_SWITCH

public static final long GUID_SB_OTA_SWITCH

The GUID for the global event sent when all service records are inserted due to a move BES command OTA.

See Also:

Constant Field Values

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.0.0

GUID_SB_PIN_CHANGE

public static final long GUID_SB_PIN_CHANGE

The GUID for the global event sent when a service replaces an old service and the server is reporting that the PIN last activated on that service has changed. (ie user switched devices)

See Also:

Constant Field Values

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.2.0

GUID_SB_POLICY_CHANGED

public static final long GUID_SB_POLICY_CHANGED

The GUID for the global event sent when the service book responds to an IT Policy changed event.

See Also:

Constant Field Values

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.1.0

SERVICEBOOK_PAYLOAD_VERSION_3

public static final int SERVICEBOOK_PAYLOAD_VERSION_3

See Also:

Constant Field Values

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.0.0

SEND_ACK_FLAG

public static final int SEND_ACK_FLAG

See Also:

Constant Field Values

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.0.0

ACK_SUCCESSFUL

public static final int ACK_SUCCESSFUL

See Also:

Constant Field Values

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.0.0

ACK_FAILURE

public static final int ACK_FAILURE

See Also:

Constant Field Values

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.0.0

SOURCE_SERVER_UID

public static final int SOURCE_SERVER_UID

See Also:

Constant Field Values

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.0.0

NEW_SERVER_UID

public static final int NEW_SERVER_UID

See Also:

Constant Field Values

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.0.0

TO_BE_DELETED_SERVER_UID

public static final int TO_BE_DELETED_SERVER_UID

See Also:

Constant Field Values

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.0.0

SERVICE_STATUS_FIELD

public static final int SERVICE_STATUS_FIELD

See Also:

Constant Field Values

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.0.0

STATUS_LAST_PIN

public static final int STATUS_LAST_PIN

See Also:

Constant Field Values

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.0.0

COMMAND_INJECT_SERVICE

public static final int COMMAND_INJECT_SERVICE

See Also:

Constant Field Values

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.0.0

COMMAND_SWITCH_SERVICE

public static final int COMMAND_SWITCH_SERVICE

See Also:

Constant Field Values

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.0.0

COMMAND_DELETE_SERVICE

public static final int COMMAND_DELETE_SERVICE

See Also:

Constant Field Values

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.0.0

COMMAND_SERVICE_STATUS

public static final int COMMAND_SERVICE_STATUS

See Also:

Constant Field Values

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.0.0

RESULT_SUCCESS

public static final int RESULT_SUCCESS

See Also:

Constant Field Values

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.0.0

RESULT_GENERAL_ERROR

public static final int RESULT_GENERAL_ERROR

See Also:

Constant Field Values

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.0.0

RESULT_UNKNOWN_COMMAND

public static final int RESULT_UNKNOWN_COMMAND

See Also:

Constant Field Values

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.0.0

RESULT_SECURITY_VIOLATION_ERROR

public static final int RESULT_SECURITY_VIOLATION_ERROR

See Also:

Constant Field Values

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.0.0

RESULT_KEY_ERROR

public static final int RESULT_KEY_ERROR

See Also:

Constant Field Values

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.0.0

RESULT_KEY_MISMATCH

public static final int RESULT_KEY_MISMATCH

See Also:

Constant Field Values

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.0.0

RESULT_UNSUPPORTED_CMD_VERSION

public static final int RESULT_UNSUPPORTED_CMD_VERSION

See Also:

Constant Field Values

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.0.0

RESULT_SWITCH_PENDING_ERROR

public static final int RESULT_SWITCH_PENDING_ERROR

See Also:

Constant Field Values

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.0.0

RESULT_DUPLICATE_SERVICE_ERROR

public static final int RESULT_DUPLICATE_SERVICE_ERROR

See Also:

Constant Field Values

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.0.0

RESULT_PACKET_PARSE_ERROR

public static final int RESULT_PACKET_PARSE_ERROR

See Also:

Constant Field Values

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.0.0

RESULT_CUSTOM_ERROR

public static final int RESULT_CUSTOM_ERROR

See Also:

Constant Field Values

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.0.0

SERVICE_RECORD_SUMMARY_RECORD

public static final byte SERVICE_RECORD_SUMMARY_RECORD

See Also:

Constant Field Values

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.1.0

VIEW_MODE_UNKNOWN

public static final int VIEW_MODE_UNKNOWN

Indicates that the service book has an unknown view mode.

See Also:

Constant Field Values

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.0.0

VIEW_MODE_RW

public static final int VIEW_MODE_RW

Indicates that the service book has read-write view mode access.

See Also:

Constant Field Values

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.0.0

VIEW_MODE_R

public static final int VIEW_MODE_R

Indicates that the service book has read view mode access.

See Also:

Constant Field Values

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.0.0

VIEW_MODE_RO

public static final int VIEW_MODE_RO

Indicates that the service book has read-only view mode access.

See Also:

Constant Field Values

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.0.0

Method Detail

getSB

public static ServiceBook getSB()

Retrieves the service book from the Factory.

Returns:

Reference to the service book.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.0.0

getStatusForUid

public ServiceBook.ServiceStatus getStatusForUid(String uid)

Get the status for a Server (UID)

Parameters:

uid - - UID for the server to get the status for.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.0.0

getNumRecords

public int getNumRecords(int type)

Retrieves the number of records with the specified type in the service book.

Parameters:

type - Type of records to count.

Returns:

Number of records with the specified type.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.0.0

getRecordById

public ServiceRecord getRecordById(int id)

Retrieves a service record by ID.

Parameters:

id - ID of the desired record.

Returns:

Service record associated with the ID, or null if no matching record found.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.0.0

getRecordByUidAndCid

public ServiceRecord getRecordByUidAndCid(String uid,
                                          String cid)

Retrieves service record by UID and CID.

Note that the content ID and user ID comparisons are case insensitive.

Parameters:

uid - User ID to match.

cid - Content ID to match.

Returns:

Service record associated with the UID and CID, or null if no matching record found.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.0.0

getRecordByCidAndHash

public ServiceRecord getRecordByCidAndHash(String cid,
                                           int nameHash,
                                           int uidHash)

Retrieves service record by CID and either name hash or UID hash.

Both name and UID are SHA-1 hashes (you can use ServiceRecord.getNameHash() and ServiceRecord.getUidHash() to retrieve these values). Note that the CID comparison is case insensitive.

Parameters:

cid - Content ID to match.

nameHash - SHA hash for the name to match.

uidHash - SHA hash for the UID to match.

Returns:

Service record that matched, or null if no matching record found.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.0.0

getRecordByCidAndDataSourceId

public ServiceRecord getRecordByCidAndDataSourceId(String cid,
                                                   String aDataSourceId)

Retrieves service record by CID and data source ID.

Note that the CID comparison is case insensitive, while the data source ID comparison is case sensitive.

Parameters:

cid - Content ID to match.

aDataSourceId - Data source ID to match.

Returns:

Service record that matched, or null if no matching record found.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.0.0

getRecordByCidAndUserId

public ServiceRecord getRecordByCidAndUserId(String cid,
                                             int userId,
                                             int nameHash,
                                             int uidHash)

Retrieves service record with a specified CID by user ID, if not found by user ID it is the service record with the CID, name hash and UID hash is returned.

Both name and UID are SHA-1 hashes (you can use ServiceRecord.getNameHash() and ServiceRecord.getUidHash() to retrieve these values). Note that the CID comparison is case insensitive.

Parameters:

cid - Content ID to match.

userId - user ID to match.

nameHash - SHA hash for the name to match.

uidHash - SHA hash for the UID to match.

Returns:

Service records that matched, or null if no matching records are found.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.1.0

getRecordByCidAndUserId

public ServiceRecord getRecordByCidAndUserId(String cid,
                                             int userId)

Retrieves service record user ID

Parameters:

cid - Content ID to match.

userId - user ID to match.

Returns:

Service records that matched, or null if no matching records are found.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.0.0

getRecordByCidAndSid

public ServiceRecord getRecordByCidAndSid(String cid,
                                          long sid,
                                          boolean useServiceEquivalency,
                                          boolean onlyActiveRecord)

Retrieves service record by service identifier (sid)

Parameters:

cid - Content ID to match.

sid - the service identifier to match.

useServiceEquivalency - true to use service equivalency, false to explicitly check the long value.

onlyActiveRecord - true returns the first matching service record that is active, false returns the first matching service record.

Returns:

The service record that matches, or null if no matching record is found.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.6.0

getRecordByCidAndSid

public ServiceRecord getRecordByCidAndSid(String cid,
                                          long sid)

Retrieves service record by service identifier (sid)

Parameters:

cid - Content ID to match.

sid - the service identifier to match.

Returns:

The service record that matches, or null if no matching record is found.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.3.0

getRecordByCidAndSid

public ServiceRecord getRecordByCidAndSid(String cid,
                                          long sid,
                                          boolean useServiceEquivalency)

Retrieves service record by service identifier (sid)

Parameters:

cid - Content ID to match.

sid - the service identifier to match.

useServiceEquivalency - true to use service equivalency for the check, false not to

Returns:

The service record that matches, or null if no matching record is found.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.5.0

getCIDAssociatedWithService

public ServiceRecord getCIDAssociatedWithService(String targetCID,
                                                 ServiceRecord sr)

Retrieve a specific service record with a target CID that is associated with a provided service record.

Use this method if you must find an "associated" service on the same server as a given service (for example, the calendar often needs to use message services, so you need to find the CMIME service record associated with a particular CICAL service record).

This is a convenience method that invokes ServiceBook.getCIDAssociatedWithService(String, int, String, String) providing targetCID, and the user ID, data source ID, and service UID retrieved from your provided sr.

Parameters:

targetCID - Content ID for the associated service you want.

sr - The service record for the service you have. The user ID (if present), data source ID (if present), and service UID from this record are used to match.

Returns:

The associated service record, or null, if no associated service record can be found.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.2.0

getCIDAssociatedWithService

public ServiceRecord getCIDAssociatedWithService(String targetCID,
                                                 int userID,
                                                 String dsID,
                                                 String uid)

Retrieve a service record that matches your provided parameters.

Service records have at least a content ID (CID), service UID (UID), and service name. They may also contain a data source ID or user ID.

Parameters:

targetCID - Content ID for the service you want, or null, if you don't want to match against a content ID.

userId - User ID for the service you want, or null, if you don't want to match against a user ID.

dsID - Datasource ID for the service you want, or null, if you don't want to match against a datasource ID.

uid - Service UID for the service you want, or null, if you don't want to match against a service UID.

Returns:

Service record matching your provided parameters, or null if no service record can be found.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.2.0

findRecordsByType

public ServiceRecord[] findRecordsByType(int type)

Retrieves all service records of specified type.

Parameters:

type - Specified type of the records.

Returns:

Array of all service records with the specified type.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.0.0

findRecordsByUid

public ServiceRecord[] findRecordsByUid(String uid)

Retrieves all service records with specified UID.

Note that the UID comparison is case insensitive.

Parameters:

uid - UID to match.

Returns:

Array of all service records with the specified UID.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.0.0

findRecordsByCid

public ServiceRecord[] findRecordsByCid(String cid)

Retrieves all service records with specified content ID.

Note that the CID comparison is case insensitive.

Parameters:

cid - Content ID to match.

Returns:

Array of all service records with the specified CID.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.2.0

findRecordsByName

public ServiceRecord[] findRecordsByName(String name)

Retrieves all service records with specified name.

Parameters:

name - Name to match.

Returns:

Array of all service records with the specified name.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.0.0

findDuplicateRecords

public ServiceRecord[] findDuplicateRecords(ServiceRecord rec,
                                            int newType,
                                            String newName,
                                            String newUid,
                                            String newCid,
                                            String dataSourceId,
                                            int userId)

Retrieves any and all duplicates of the specified record.

It is possible to perform the search using different values for the record's type, name, CID and UID. This way you can verify the changes before they are actually committed. Any record which has the same UID and CID or the same name and CID of the specified record will be returned.

This routine will consider records depending on the type of the argument record. If the argument record has type ServiceRecord.SRT_ACTIVE, then records with the types ServiceRecord.SRT_ACTIVE or ServiceRecord.SRT_OBSOLETE are considered. Otherwise any considered records will have the same type as the argument record.

Note: UIDs and CIDs are case-insensitive.

Parameters:

rec - Record to match against.

newType - Record's new type or ServiceRecord.SRT_NO_CHANGE if the type will not be changed.

newName - Record's new name or null if the name will not be changed.

newUid - Record's new UID or null if the UID will not be changed.

newCid - Record's new CID or null if the CID will not be changed.

dataSourceId - Record's new data-source ID or null if the data-source ID will not be changed.

Returns:

Array of all matching duplicate service records.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.0.0

findDuplicateRecords

public ServiceRecord[] findDuplicateRecords(ServiceRecord rec,
                                            int newType,
                                            String newName,
                                            String newUid,
                                            String newCid,
                                            String dataSourceId,
                                            int userId,
                                            String newUserIdentity,
                                            String newSourceIdentity)

Retrieves any and all duplicates of the specified record.

It is possible to perform the search using different values for the record's type, name, CID and UID. This way you can verify the changes before they are actually committed. Any record which has the same UID and CID or the same name and CID of the specified record will be returned.

This routine will consider records depending on the type of the argument record. If the argument record has type ServiceRecord.SRT_ACTIVE, then records with the types ServiceRecord.SRT_ACTIVE or ServiceRecord.SRT_OBSOLETE are considered. Otherwise any considered records will have the same type as the argument record.

Note: UIDs and CIDs are case-insensitive.

Parameters:

rec - Record to match against.

newType - Record's new type or ServiceRecord.SRT_NO_CHANGE if the type will not be changed.

newName - Record's new name or null if the name will not be changed.

newUid - Record's new UID or null if the UID will not be changed.

newCid - Record's new CID or null if the CID will not be changed.

dataSourceId - Record's new data-source ID or null if the data-source ID will not be changed.

newUserIdentity - Globally unique and immutable identity that defines the user within a particular service.

newSourceIdentity - Globally unique and immutable identity that defines the account within a service.

Returns:

Array of all matching duplicate service records.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 7.1.0

getRecords

public ServiceRecord[] getRecords()

Retrieves all records.

Returns:

Array of all registered service records.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.0.0

isAllowedRecord

public boolean isAllowedRecord(ServiceRecord sr,
                               int newType,
                               String newName,
                               String newUid,
                               String newCid)

Verifies that a record is allowed in the current book, according to IT policy settings.

Checks the record against the current IT policy. It is possible to do the search with different values for the record's type, name, CID and UID. This way it is possible to verify changes before they are actually commited to the service book.

Parameters:

sr - Record to check.

newType - Record's new type or SRT_NO_CHANGE if the type will not be changed.

newName - Record's new name or null if the name will not be changed.

newUid - Record's new UID or null if the uid will not be changed.

newCid - Record's new CID or null if the cid will not be changed.

Returns:

True if the record is allowed (passes the IT policy check); otherwise, false.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.0.0

commit

public void commit()

Commits changes to the persistent store.

This causes events to be transmitted to all listeners for any changed, new or removed records.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.0.0

setSerialInjectionInProgress

public void setSerialInjectionInProgress(boolean flag)

Sets current state of serial service record injection

Parameters:

flag - True if serial injection is occuring; false otherwise

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.0.0

getSerialInjectionInProgress

public boolean getSerialInjectionInProgress()

Gets the current state of serial service record injection

Returns:

flag True if serial injection is occuring; false otherwise

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.0.0

deRegisterCIDAsSingleton

public void deRegisterCIDAsSingleton(String CID)

Allows an application to revoke the singleton restriction.

Parameters:

CID - The CID to register as a singleton.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.2.0

registerCIDAsSingleton

public void registerCIDAsSingleton(String CID)

Allows an application to indicate that only one CID is supported. Duplicate service records of this CID are not allowed. The last in service record will overwrite the previous record.

Parameters:

CID - The CID to register as a singleton.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.0.0

registerCIDAsSingleton

public void registerCIDAsSingleton(String CID,
                                   boolean secureServices,
                                   boolean insecureServices)

Allows an application to indicate that only one CID is supported. Duplicate service records of this CID are not allowed. The last in service record will overwrite the previous record.

Parameters:

CID - The CID to register as a singleton.

secureServices - restricts secure services

insecureServices - restricts insecure services

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.2.0

deRegisterCIDAsSingleton

public void deRegisterCIDAsSingleton(String CID,
                                     boolean secureServices,
                                     boolean insecureServices)

Allows an application to revoke the singleton restriction.

Parameters:

CID - The CID to register as a singleton.

secureServices - restricts secure services

insecureServices - restricts insecure services

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.2.0

getServiceList

public byte[] getServiceList()

Get the Service Record list summary encoding (used by the Device Agent Database.)

Returns:

TLE encoded list of service records and their key values.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.1.0