PIN-to-PIN Messaging

What it is

PIN-to-PIN messaging is a method of sending information from one BlackBerry device to another. It is typically very fast, and noticeably faster than push messages. PIN messages must be sent by a BlackBerry device, and received by a BlackBerry device (a server cannot send a PIN message).

Here's a visual example, excuse the French. This is a pin-to-pin message exchange between Bob and Alice. Notice the infrastructure is similar to push messaging.

How to send a PIN message

Sending a PIN message is very similar to sending any other type of message. You can specify a subject, content, recipients, etc. just like you would an email. The difference is that the recipient attribute must be a PINAddress object.

        Message msg = new Message( sentfolder );
        try {
            PINAddress to[] = { new PINAddress( pinAddress, name ) };
            msg.addRecipients( Message.RecipientType.TO, to );
            msg.setSubject( subject );
            msg.setContent( pinMessage );
            Transport.send( msg );
        }
        catch (Throwable t) {

            log.info( "Error sending PIN Message", t );
        }

A PinMessenger utility class has been added to the SDK to facilitate this.

How to receive a PIN message

PIN messages can be listened for by using a FolderListener.

Do not use Message.getMessageType() to determine whether or not the incoming message is a PIN message. This will always return Message.EMAIL_MESSAGE. RIM has confirmed this bug.

You'll need to specify your own way of identifying PIN messages sent between users of your app.

public class PinMessageListener implements FolderListener {

    private static org.slf4j.Logger log = org.slf4j.LoggerFactory.getLogger( PinMessageListener.class );

    public void messagesAdded( FolderEvent event ) {

        String subject = event.getMessage().getSubject();

        //make sure this message is intended for you, having a common subject should be sufficient
        if ( !Text.equals( subject, Settings.PIN_MESSAGE_SUBJECT ) ) {

            return;
        }

        //do whatever you want here