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 Deprecated. use LinkedContactUtilities.registerLinkedContactInfoProvider(LinkedContactInfoProvider, long, int)
LinkableContact Represents an object that is linkable with a contact in the contacts application.
LinkedContactCallback An interface allowing access to linked contact information to be set.
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.
LinkedContactInfoProvider A provider to supply requested linked contact information.
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 the information 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

The Contact Linking Demo sample application is included in the BlackBerry® Java® SDK. The application demonstrates how to use the Contact Linking API.

The process

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

  1. Create your linkable contacts
  2. Create a LinkedContactInfoProvider
  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 a LinkedContactInfoProvider

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

Defining the class

LinkedContactInfoProvider supplies the information about a linked contact that is displayed in the Contacts application when the user views a contact in the Contacts application. The underlying framework determines how the information is displayed in the Contacts application.

To define the information provider for your linkable contact:

  1. Create a class that extends LinkedContactInfoProvider.
  2. Implement getAppImage() and specify the icon that represents your application. The method must return an image in order for any information to be displayed for your linked contact when a user views a contact in the Contacts application.
  3. Implement getAppName() and specify the name of your application. The method must return a name in order for information about the linked contact to display when a user edits a contact in the Contacts application.
  4. Optionally, implement isSupported() to indicate which LinkedContactInfoProvider fields (user name, availability, and/or status) your application supports. By default, a field is not supported. You only need to implement isSupported() if your application supports any of the fields.
  5. Implement requestFields() to specify the information to display for the contact in the Contacts application. This method is called by the framework when it needs to display information for the linked contact in the Contacts application. Specify the contact's name, status, and current availability, depending on which fields you defined as supported in isSupported().

Here is the implementation of LinkedContactInfoProvider in the Contact Linking Demo sample application. The image and application name are set when the information provider is constructed. The information provider supports all the fields defined in LinkedContactInfoProvider.


public class SampleLinkedContactInfoProvider extends LinkedContactInfoProvider
{
    private Image _image;
    private String _appName;
        
    public SampleLinkedContactInfoProvider(Image image, String appName)    
    {        
        _image = image;
        _appName = appName;                
    }
    
    public Image getAppImage()
    {
        return _image;        
    }
    
    public String getAppName()
    {        
        return _appName;
    }  
    
    public boolean isSupported(int capability)
    {
        switch(capability)
        {
            case LinkedContactInfoProvider.STATUS:
            case LinkedContactInfoProvider.AVAILABILITY:
            case LinkedContactInfoProvider.USER_NAME:
                return true;
            default:
                return false;
        }
    }

    public void requestFields(String contactID, final LinkedContactCallback callback, int fields)
    {        
        LinkableContact contact = ContactListScreen.getUserForID(contactID);
        
        if((fields & LinkedContactInfoProvider.AVAILABILITY) != 0)
        {
            callback.setAvailability(LinkedContactInfoProvider.AVAILABILITY_ONLINE);
        }
        if((fields & LinkedContactInfoProvider.STATUS) != 0)
        {            
            callback.setStatusString("<Sample contact status>");
        }       
        if((fields & LinkedContactInfoProvider.USER_NAME) != 0)
        {
            callback.setUserName(contact.toString());
        }
    }      
}

Registering the class

After creating a LinkedContactInfoProvider, you register it with your application using registerLinkedContactInfoProvider() The method takes the information provider, the application ID, and the application group for your application, 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

The following code sample registers an application as a social networking application.

LinkedContactUtilities.registerLinkedContactInfoProvider(
    new SampleLinkedContactInfoProvider(imageBlue, "Demo App 1"), 
    APPLICATION_ID,
    LinkedContactConstants.COMPOSE_SN_MENU_GROUP);

When a user displays a contact in the Contacts application that is linked to one of your contacts, the information that you defined in your information provider displays on the contact screen. The framework determines the layout of the information. In this example, because the application was defined as a social networking application, the information displays in the Social Networks section of the contact.

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 Contacts 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.

For more information about how menu items are grouped in the Contacts application when there are multiple linked contacts, see the BlackBerry Java SDK 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.

For an example of this approach to linking a contact, see the linkContact() method in the Contact Linking Demo sample application that is included in the BlackBerry Java SDK.






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.