Package net.rim.blackberry.api.pdap.contactlinking

Provides classes and interfaces for linking contacts in applications with contacts in the contacts application.

See:
          Description

Interface Summary
AddressBookFieldFactory A factory for creating custom fields that display in the contacts application when the user views a linked contact.
LinkableContact Represents an object that is linkable with a contact in the contacts application.
LinkedContactConstants Constants useful for linking application contacts to contacts in the contacts application.
 

Class Summary
AbstractLinkableContact Provides default implementations for some of the methods in the LinkableContact interface.
DefaultLinkableContact A simple implementation of LinkableContact.
LinkedContactUtilities Provides utility methods for manipulating the contact list from other applications.
 

Package net.rim.blackberry.api.pdap.contactlinking Description

Provides classes and interfaces for linking contacts in applications with contacts in the contacts application.

Overview

You can link contact data in your application with contacts in the contacts application on the BlackBerry® device by using the Contact Linking API in this package. A particular contact in the contacts application can be linked with one contact in your application, though a contact in the contacts application can be linked with contacts in multiple applications.

When linking to a contact in the contacts application, you can use the Contact Linking API to perform some tasks automatically, such as searching for a matching contact in the contacts application and checking to see whether a contact in the contacts application is already linked to one of your contacts.

You can define a custom field to display in the contacts application when the user is viewing a contact that is linked to one of your contacts. You can also create menu items that display in the contacts application when a user views a linked contact.

Sample application

To download a sample application that demonstrates how to use the Contact Linking API, visit www.blackberry.com/go/contactlinkingsample.

The process

To link contacts in your application with contacts in the contacts application:

  1. Create your linkable contacts
  2. Create an AddressBookFieldFactory
  3. Optionally, create menu items associated with linked contacts
  4. Link your contacts

Creating linkable contacts

Objects in your application that you want to link to a contact in the contacts application must implement the LinkableContact interface. LinkableContact contains fields you can use to store information about your contact, such as NAME, EMAIL, and HOME_PHONE. A LinkableContact must have at least an application ID, returned from the interface's getApplicationID() method, and a contact ID, returned from getContactID().

Your contact class can directly implement LinkableContact, or it can extend one of the helper classes in the Contact Linking API, AbstractLinkableContact or DefaultLinkableContact.

Here is a LinkableContact that extends AbstractLinkableContact:

public final class SampleContact extends AbstractLinkableContact
{
    String _contactID;

    // Creates a new SampleContact object
    // contactId is the login ID for a new SampleContact
    public SampleContact(String contactId)
    {
        _contactID = contactId;
    }

    // Displays the contact's name
    public String toString()
    {
        return getString(LinkableContact.NAME);
    }

    // LinkableContact method
    public long getApplicationID()
    {
        return ContactLinkingDemo.APPLICATION_ID;
    }

    // LinkableContact method
    public String getContactID()
    {
        return _contactID;
    }
}

Creating an AddressBookFieldFactory

Before linking contacts from your application, you must define a class that implements AddressBookFieldFactory and register the class with your application.

Defining the class

AddressBookFieldFactory is an interface that defines one method: createAddressBookField(), which defines a field to add to the contacts application when a user displays a contact that is linked to a contact in your application. The method takes one argument, the contact ID (remember that linkable contacts must define an ID).

Here is an example of an implementation of AddressBookFieldFactory:

public final class SampleAddressBookFieldFactory implements AddressBookFieldFactory
{
    private String _applicationName;

    // Creates a newSampleAddressBookFieldFactory object
    // appName is the name of the application to display in the field
    public SampleAddressBookFieldFactory(String appName)
    {
        _applicationName = appName;
    }

    // Displays the name of the application and the linked contact
    // in the contacts application
    public Field createAddressBookField(final String contactID)
    {
        LinkableContact user = ContactListScreen.getUserForID(contactID);
        if(user == null)
        {
            return null;
        }
        return new BasicEditField(_applicationName + ": ",
            user.getString(LinkableContact.NAME),
            BasicEditField.DEFAULT_MAXCHARS,
            Field.USE_ALL_WIDTH | Field.READONLY);
    }
}

Registering the class

After creating an AddressBookFieldFactory, you register it with your application using registerAddressBookFieldFactory().

AddressBookFieldFactory factory = new SampleAddressBookFieldFactory("Sample App");
LinkedContactUtilities.registerAddressBookFieldFactory(factory, APPLICATION_ID);

When a user displays a contact in the contacts application that is linked to one of your contacts, the field you defined in createAddressBookField() displays on the contact screen.

Creating menu items

Though not required in contact linking, you can create menu items that are available in the contacts application when a user views a contact that is linked with a contact in your application. For example, you might want menu items that invoke your application or that allow users to add notes to the contact application about the contact in your application.

You use registerMenuItems() to register menu items with your application. When using this method, you must assign a menu item to an application group using the LinkedContactConstants interface.

Application group Description
COMPOSE_SN_MENU_GROUP Social networking applications
COMPOSE_IM_MENU_GROUP Instant messaging applications
COMPOSE_OTHER_MENU_GROUP Applications that are not social networking or instant messaging applications

For more information about how menu items are grouped in the contacts application when there are multiple linked contacts, see the BlackBerry Java Application Integration Development Guide.

To create menu items:

  1. Create a variable to store the unique ID of your application.
  2. Create an application descriptor.
  3. Create a class that extends ApplicationMenuItem.
  4. Create an array of application menu items.
  5. Register the menu items with your application.

The following code sample illustrates these steps.

public static final long APPLICATION_ID = 0x1eredfe71d34760fdL;

ApplicationDescriptor appdesc = new
    ApplicationDescriptor(ApplicationDescriptor.currentApplicationDescriptor(),
    "Linking Application", null);

public class LinkedMenuItem extends ApplicationMenuItem {...}

ApplicationMenuItem[] items = new ApplicationMenuItem[1];
items[0] = new LinkedMenuItem();

LinkedContactUtilities.registerMenuItems(items, APPLICATION_ID,
    LinkedContactConstants.COMPOSE_SN_MENU_GROUP, appdesc);

Linking your contacts

You use linkContact() to link a contact in the contacts application with a LinkableContact. You can use methods in LinkedContactUtilities to help automate the process.

It is up to you to decide how to interact with the user before linking a contact. Here is a simple approach, which involves no user interaction:

  1. Use getContactLinkCandidate() to see whether there is a contact in the contacts application with the same email address or phone number as your linkable contact.
  2. If there is a matching candidate, use isContactLinked() to see whether the matching candidate is already linked to a contact in your application.
  3. If the matching candidate is not linked to one of your contacts, use linkContact() to do the linking.
private static void simpleLink(LinkableContact linkableContact)
{
    BlackBerryContact bbContact =
        LinkedContactUtilities.getContactLinkCandidate(linkableContact);

    if(bbContact != null)
    {
        if(!LinkedContactUtilities.isContactLinked(bbContact,
            linkableContact.getApplicationID()))
        {
            bbContact =
                LinkedContactUtilities.linkContact(bbContact, linkableContact);
        {
    }
}

You can also allow the user to decide whether to link to a contact in the contacts application. For example, if you find a matching contact, you could ask the user whether the user wants to link to the matching contact. If not, you could open the contact list and allow the user to select a contact to link to.

See the linkContact() method in the sample contact linking application for an example of this approach to linking a contact. To download the sample application, visit www.blackberry.com/go/contactlinkingsample.






Copyright 1999-2010 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A. All Rights Reserved.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark of Sun Microsystems, Inc.