net.rim.blackberry.api.pdap.contactlinking
Class LinkedContactUtilities

java.lang.Object
  net.rim.blackberry.api.pdap.contactlinking.LinkedContactUtilities

public final class LinkedContactUtilities
extends Object

Provides utility methods for manipulating the contact list from other applications.

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 5.0.0

Method Summary
	static String	getContactIdFromLinkedContact(BlackBerryContact contact, long applicationId) Returns the contact ID for the LinkableContact whose BlackBerryContact is supplied.
	static BlackBerryContact	getContactLinkCandidate(LinkableContact userData) Returns the BlackBerryContact that is the best candidate to link the supplied LinkableContact with.
	static BlackBerryContact	getLinkedContact(LinkableContact userData) Returns the BlackBerryContact that is linked with the supplied LinkableContact.
	static boolean	isContactLinked(BlackBerryContact contact, long applicationId) Checks if the supplied BlackBerryContact has a link for the supplied application.
	static BlackBerryContact	linkContact(BlackBerryContact contact, LinkableContact userData) Creates a link between a BlackBerryContact and a LinkableContact.
	static void	registerAddressBookFieldFactory(AddressBookFieldFactory factory, long applicationId) Deprecated. use LinkedContactUtilities.registerLinkedContactInfoProvider(LinkedContactInfoProvider, long, int).
	static void	registerLinkedContactInfoProvider(LinkedContactInfoProvider provider, long applicationId, int appGroupId) Registers a LinkedContactInfoProvider for providing information about a linked contact.
	static void	registerMenuItems(ApplicationMenuItem[] items, long applicationId, int appGroupId, ApplicationDescriptor app) Takes an array of menu items that you want to display in the menu when a linked contact is viewed in the Contacts application.
	static BlackBerryContact	unlinkContact(BlackBerryContact contact, long applicationId) Removes the link between the supplied BlackBerryContact and an application.

Methods inherited from class java.lang.Object

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

Method Detail

registerMenuItems

public static void registerMenuItems(ApplicationMenuItem[] items,
                                     long applicationId,
                                     int appGroupId,
                                     ApplicationDescriptor app)

Takes an array of menu items that you want to display in the menu when a linked contact is viewed in the Contacts application. Multiple calls to this method with the same application ID cause the previous array of items to be overwritten. If items is null or an empty array, the menu items for the specified application ID will be deleted.

Parameters:

items - An array of ApplicationMenuItems to display.

applicationId - Your application ID.

appGroupId - The group ID of your application. Should be one of COMPOSE_IM_MENU_GROUP, COMPOSE_SN_MENU_GROUP or COMPOSE_OTHER_MENU_GROUP.

app - An ApplicationDescriptor that describes your application.

Throws:

IllegalArgumentException - if appGroupId is not one of COMPOSE_IM_MENU_GROUP, COMPOSE_SN_MENU_GROUP or COMPOSE_OTHER_MENU_GROUP.

SecurityException - if app is not the descriptor of the application that called this method or if the calling application is not allowed to access the PIM capabilities on the device.

NullPointerException - if items is null.

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 5.0.0

registerAddressBookFieldFactory

public static void registerAddressBookFieldFactory(AddressBookFieldFactory factory,
                                                   long applicationId)

Deprecated. use LinkedContactUtilities.registerLinkedContactInfoProvider(LinkedContactInfoProvider, long, int).

Registers a factory for building the field that will display information about a linked contact. Multiple calls to this method with the same application ID cause the field to be overwritten. A factory must be registered before any contact linking can be performed.

Parameters:

factory - The factory used to create the field.

applicationId - Your application ID.

Throws:

NullPointerException - if factory is null.

SecurityException - if the calling application is not allowed to access the PIM capabilities on the device.

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 5.0.0

registerLinkedContactInfoProvider

public static void registerLinkedContactInfoProvider(LinkedContactInfoProvider provider,
                                                     long applicationId,
                                                     int appGroupId)

Registers a LinkedContactInfoProvider for providing information about a linked contact. Multiple calls to this method with the same application ID cause the field to be overwritten. A LinkedContactInfoProvider must be registered before any contact linking can be performed.

Parameters:

provider - The LinkedContactInfoProvider to provide linked contact information.

applicationId - Your application ID.

appGroupId - The group ID of your application. Should be one of COMPOSE_IM_MENU_GROUP, COMPOSE_SN_MENU_GROUP or COMPOSE_OTHER_MENU_GROUP.

Throws:

SecurityException

IllegalArgumentException - if appGroupId is not one of COMPOSE_IM_MENU_GROUP, COMPOSE_SN_MENU_GROUP or COMPOSE_OTHER_MENU_GROUP.

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 6.0.0

getContactLinkCandidate

public static BlackBerryContact getContactLinkCandidate(LinkableContact userData)

Returns the BlackBerryContact that is the best candidate to link the supplied LinkableContact with. This method first matches by the contact's email address, then by a phone number. If no match is found, this method returns null.

Parameters:

userData - The data to look for in the contact list.

Returns:

The best matched BlackBerryContact, or null if no match is found. If multiple contacts have the same email address or phone number, the link candidate may not be the one the user wants to link to. It is recommended that you confirm the candidate with the user before linking.

Throws:

IllegalStateException - if registerLinkedContactInfoProvider() has not been called before calling this method.

SecurityException - if the calling application is not allowed to access the PIM capabilities on the device.

See Also:

LinkedContactUtilities.registerLinkedContactInfoProvider(LinkedContactInfoProvider, long, int)

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 5.0.0

getLinkedContact

public static BlackBerryContact getLinkedContact(LinkableContact userData)

Returns the BlackBerryContact that is linked with the supplied LinkableContact. If the LinkableContact is not linked, this method returns null.

Parameters:

userData - The LinkableContact whose linked BlackBerryContact you want to see.

Returns:

The linked BlackBerryContact, or null if there is no link.

Throws:

SecurityException - if the calling application is not allowed to access the PIM capabilities on the device.

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 5.0.0

getContactIdFromLinkedContact

public static String getContactIdFromLinkedContact(BlackBerryContact contact,
                                                   long applicationId)

Returns the contact ID for the LinkableContact whose BlackBerryContact is supplied.

Parameters:

contact - The contact to retrieve the user ID from.

applicationId - The application to get the contact ID for.

Returns:

The contact ID.

Throws:

IllegalArgumentException - if contact is not linked.

NullPointerException - if contact is null.

SecurityException - if the calling application is not allowed to access the PIM capabilities on the device.

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 5.0.0

isContactLinked

public static boolean isContactLinked(BlackBerryContact contact,
                                      long applicationId)

Checks if the supplied BlackBerryContact has a link for the supplied application.

Parameters:

contact - The contact to check.

applicationId - The unique ID of the application.

Returns:

true if and only if there is a link for this contact.

Throws:

SecurityException - if the calling application is not allowed to access the PIM capabilities on the device.

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 5.0.0

linkContact

public static BlackBerryContact linkContact(BlackBerryContact contact,
                                            LinkableContact userData)

Creates a link between a BlackBerryContact and a LinkableContact.

Parameters:

contact - The BlackBerryContact to link with.

userData - The LinkableContact to link.

Returns:

The new BlackBerryContact, including the linked data.

Throws:

IllegalArgumentException - if contact is already linked for userData's application or if userData's contact ID is null or if userData is already linked to another BlackBerryContact.

IllegalStateException - if registerLinkedContactInfoProvider() has not been called before calling this method.

NullPointerException - if this method is invoked with null arguments.

SecurityException - if the calling application is not allowed to access the PIM capabilities on the device.

See Also:

LinkedContactUtilities.registerLinkedContactInfoProvider(LinkedContactInfoProvider, long, int)

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 5.0.0

unlinkContact

public static BlackBerryContact unlinkContact(BlackBerryContact contact,
                                              long applicationId)

Removes the link between the supplied BlackBerryContact and an application.

Parameters:

contact - The BlackBerryContact to unlink.

applicationId - The unique ID of the application to remove the link for.

Returns:

A new BlackBerryContact with the link data removed.

Throws:

IllegalArgumentException - if contact is not linked for applicationId or if contact is null.

SecurityException - if the calling application is not allowed to access the PIM capabilities on the device.

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 5.0.0