net.rim.blackberry.api.bbm.platform.io
Interface BBMPlatformConnection

All Known Subinterfaces:

BBMPlatformChannel, BBMPlatformSession

public interface BBMPlatformConnection

This interface is a base interface of BBMPlatformChannel and BBMPlatformSession providing basic functionality of sending invitations, messages and maintaining a contact list in a connection.

Method Summary

void	add(BBMPlatformContact contact, String cookie) This API allows the user to add a contact, who has joined an existing connection, to another connection within the same application.
BBMPlatformContactList	getContactList() Each connection, which can be a BBMPlatformChannel or a BBMPlatformSession, has its own contact list which consists of all participants that have joined the connection.
int	getId() Each connection is assigned a unique Id when the connection gets created.
Enumeration	getIncomingJoinRequests() This API is used to get all pending join requests the user has received when he or she is hosting a public connection, so the user can choose which request he or she wants to accept via BBMPlatformIncomingJoinRequest.accept(String cookie) or to decline via BBMPlatformIncomingJoinRequest.decline().
BBMPlatformConnectionListener	getListener() Returns the listener that is supposed to be associated with the connection.
int	getMaxContacts() This API tells the maximum number of contacts that a BBMPlatformChannel or BBMPlatformSession can have.
int	getMaxCookieLength() This API tells the length limit of the cookie parameter that can be sent via sendInvitation(String inviteMessage, String cookie, long expiryTime).
int	getMaxDataSize() This API tells the size limit of the data that can be sent via sendData(BBMPlatformData data, BBMPlatformContactList contactList) or sendData(BBMPlatformData data, BBMPlatformContact contact) or BBMPlatformSession.broadcastData(BBMPlatformData data).
int	getMaxInvitationMessageLength() This API tells the length limit of the invitation message that can be sent via sendInvitation(String inviteMessage, String cookie, long expiryTime).
int	getPendingContactsCount() This API is used to get the number of pending contacts who were invited by the user to join a connection but have not yet accepted or declined the invitation.
boolean	isPublic() This API tells if a connection is public.
void	remove(BBMPlatformContact contact) This API behaves differently depending on if it is called from a BBMPlatformChannel or a BBMPlatformSession.
void	remove(BBMPlatformContactList contactList) This API is similar to {link BBMPlatformConnection#remove(BBMPlatformContact contact)} except here the application can remove multiple contacts.
void	removeAllContacts() This API is similar to {link BBMPlatformConnection#remove(BBMPlatformContact contact)} except here the application is removing all contacts that are in the connection from the user's view.
void	sendData(BBMPlatformData data, BBMPlatformContact contact) This API is used to let the application send data to an individual contact who has joined this connection.
void	sendData(BBMPlatformData data, BBMPlatformContactList contactList) This API is used to let the application send data to any subset of contacts who have joined the connection.
void	sendInvitation(String inviteMessage, String cookie, long expiryTime) This API allows the user to invite his or her BBM contacts to join his or her connection.
void	sendInvitation(String inviteMessage, String cookie, long expiryTime, ContactListProvider clProvider) This API allows the user to invite his or her BBM contacts to join his or her connection.
boolean	setPrivate() Sets a connection to private.
boolean	setPublic() A connection is private by default.

Method Detail

add

public void add(BBMPlatformContact contact,
                String cookie)

This API allows the user to add a contact, who has joined an existing connection, to another connection within the same application.

Data can only be shared among the people who have joined the same BBMPlatformChannel or BBMPlatformSession.

The Contact Picker will not pop up in this API call, so the application needs to specify which contact is going to be added. The contact to be added has to be chosen from those who have connected with the user in other connections within the same application.

When this API gets called, the Platform will behave the same as sending a join invitation to the contact. However, since the contact has connected with the sender in an existing connection, which implies they have agreed to be connected to each other before, so a subsequent invitation will not be visible to the contact and thus the contact has no need to handle the invitation again manually. The Platform will automatically accept the subsequent invitations on behalf of the contact as long as the sender and the contact haven been connected in any existing BBMPlatformChannel or BBMPlatformSession.

For example, if user_A and user_B are connected in Connection_1, which can be a BBMPlatformChannel or BBMPlatformSession, now user_A creates a new Connection_2 and wants to add user_B to this new connection, then on user_A's side, the application can call Connection_2.add(user_B, cookie, expiryTime). In this case, user_B will not see the invitation in the BBM chat but will be automatically added to Connection_2.

Parameters:

contact - The contact that the user is trying to add to another connection.

cookie - A custom parameter provided by the application. It can be null but cannot be longer than 128 characters.

Throws:

NullPointerException - if contact is null.

IllegalArgumentException - if contact is not connected with the user in any existing connections they have in the application.

PersistentContentException - when Content Protection is enabled and device is locked.

Since:

BBM SDK 1.0

See Also:

sendInvitation(String inviteMessage, String cookie, long expiryTime)

getContactList

public BBMPlatformContactList getContactList()

Each connection, which can be a BBMPlatformChannel or a BBMPlatformSession, has its own contact list which consists of all participants that have joined the connection.

Note that in a BBMPlatformChannel, only the inviter and the invitee who accepted the invitation will have each other in their channel contact list.
For example, if user_A invited user_B to Channel_1, B accepted to join; and user_B further invited user_C to Channel_1, and C accepted to join, then user_B will have both A and C in his or her Channel_1 contact list. However, user_A and user_C has user_B only in their Channel_1's contact lists. I.e., A is not in C's Channel_1 contact list, and C is not in A's Channel_1 contact list either.

However, in a BBMPlatformSession, everyone who joined a session will have all other people who joined the same session in his or her session contact list. In short, every participant in a session is visible and available to all other people in the same session to share data. Therefore, in the example above, if user_A, B and C are in a session instead of a channel, user_A will have B and C in the session contact list; user_B will have A and C in the session contact list; and user_C will have A and B.

Returns:

The contact list that consists of all other participants in the connection except the current user. It does not include any pending contacts either.

Since:

BBM SDK 1.0

getId

public int getId()

Each connection is assigned a unique Id when the connection gets created.

Returns:

The unique ID of a connection.

Since:

BBM SDK 1.0

getIncomingJoinRequests

public Enumeration getIncomingJoinRequests()

This API is used to get all pending join requests the user has received when he or she is hosting a public connection, so the user can choose which request he or she wants to accept via BBMPlatformIncomingJoinRequest.accept(String cookie) or to decline via BBMPlatformIncomingJoinRequest.decline().

Returns:

Returns the enumeration of all pending join requests the user has received, which can be null.
The type of each object that the Enumeration contains is BBMPlatformIncomingJoinRequest

Since:

BBM SDK 1.0

getListener

public BBMPlatformConnectionListener getListener()

Returns the listener that is supposed to be associated with the connection. A BBMPlatformChannelListener is required when a BBMPlatformChannel is created. A BBMPlatformSessionListener is required when a BBMPlatformSession is created.

Returns:

The listener associated with the connection.

Since:

BBM SDK 1.0

See Also:

MessagingService.createChannel(BBMPlatformChannelListener channelListener), MessagingService.createSession(BBMPlatformSessionListener sessionListener)

getMaxContacts

public int getMaxContacts()

This API tells the maximum number of contacts that a BBMPlatformChannel or BBMPlatformSession can have.

Returns:

The maximum number of contacts a channel or session can have. The Platform allows up to 24 contacts in a channel or session. Once the limit is reached, the Platform will not allow the user to send more join invitations and will not allow more people to join either.

Since:

BBM SDK 1.0

getMaxCookieLength

public int getMaxCookieLength()

This API tells the length limit of the cookie parameter that can be sent via sendInvitation(String inviteMessage, String cookie, long expiryTime).

Returns:

The maximum length of the cookie parameter the Platform allows, which is 128 characters.

Since:

BBM SDK 1.0

getMaxDataSize

public int getMaxDataSize()

This API tells the size limit of the data that can be sent via sendData(BBMPlatformData data, BBMPlatformContactList contactList) or sendData(BBMPlatformData data, BBMPlatformContact contact) or BBMPlatformSession.broadcastData(BBMPlatformData data).

Returns:

The maximum size of the data that can be sent in a BBMPlatformChannel or BBMPlatformSession, which is 60K bytes.

Since:

BBM SDK 1.0

getMaxInvitationMessageLength

public int getMaxInvitationMessageLength()

This API tells the length limit of the invitation message that can be sent via sendInvitation(String inviteMessage, String cookie, long expiryTime).

Returns:

the maximum length of the invitation message the Platform allows, which is 128 characters.

Since:

BBM SDK 1.0

getPendingContactsCount

public int getPendingContactsCount()

This API is used to get the number of pending contacts who were invited by the user to join a connection but have not yet accepted or declined the invitation.

Returns:

Total number of pending contacts invited who have not yet accepted or declined the invitation.

Since:

BBM SDK 1.0

isPublic

public boolean isPublic()

This API tells if a connection is public.
A user can set the connection to public via setPublic() or set it to private via setPrivate()
A user can host at most one public connection at a time within an application.

Returns:

true if the connection is public to join; false otherwise.

Since:

BBM SDK 1.0

remove

public void remove(BBMPlatformContact contact)

This API behaves differently depending on if it is called from a BBMPlatformChannel or a BBMPlatformSession.

If this API is called from a BBMPlatformChannel, it means only the user, who initiated the removal, wants to disconnect with the contact. Therefore, the contact is no longer in the user's connection contact list, and vice versa.

Note that the contact to be removed can still be alive in the connection on his or her side, i.e, he or she can still send data to or receive data from other people that are in the same connection. That is, BBMPlatformChannel uses this API to break the connection between the user and this contact only.
For example, if user_A, B, and C all have joined Channel_1, if the application calls Channel_1.remove(user_B) on user_A's side, from then on, user_A and B cannot communicate to each other within Channel_1 unless they re-invite each other in the future. However, they both can still communicate with user_C in Channel_1. On user_B's side, it appears that the user_A has left the Channel_1, and vice versa.

If this API is called from a BBMPlatformSession, the contact will be globally removed from the session. I.e., all people in the same session will become disconnected with the contact.

For example, if user_A, B, and C all have joined Session_1, if the application calls Session_1.remove(user_B) on user_A's side, from then on, user_B will not be able to access Session_1 for sending or receiving invitations or data. Also, both user_A and user_C will not see user_B in this session anymore and thus will not be able to send data to user_B from within Session_1.

Parameters:

contact - the BBMPlatformContact to be removed.

Throws:

NullPointerException - if contact is null.

IllegalArgumentException - if contact doesn't belong to this connection.

PersistentContentException - when Content Protection is enabled and device is locked.

Since:

BBM SDK 1.0

remove

public void remove(BBMPlatformContactList contactList)

This API is similar to {link BBMPlatformConnection#remove(BBMPlatformContact contact)} except here the application can remove multiple contacts.

Parameters:

contactList - the BBMPlatformContactList which consists of the contacts to be removed.

Throws:

IllegalArgumentException - if any contact in the contactList doesn't belong to this connection.

PersistentContentException - when Content Protection is enabled and device is locked. If the contactList is null, the Platform does nothing.

Since:

BBM SDK 1.0

See Also:

remove(BBMPlatformContact contact).

removeAllContacts

public void removeAllContacts()

This API is similar to {link BBMPlatformConnection#remove(BBMPlatformContact contact)} except here the application is removing all contacts that are in the connection from the user's view. If a BBMPlatformChannel is destroyed, all contacts in this channel will be removed. If a BBMPlatformSession is ended, all contacts in this session will be removed.

Throws:

PersistentContentException - when Content Protection is enabled and device is locked.

Since:

BBM SDK 1.0

sendData

public void sendData(BBMPlatformData data,
                     BBMPlatformContact contact)
              throws DataOverflowException,
                     ContactUnreachableException

This API is used to let the application send data to an individual contact who has joined this connection.

Note that the Platform cannot guarantee all the packets will come in order, so applications will have to make sure the sequence of events if needed.

Data sent via this API is always private. That is, the receiver's reply is supposed to be sent to the data sender only. The receiver will receive the data via BBMPlatformConnectionListener.dataReceived(BBMPlatformConnection connection, BBMPlatformContact sender, BBMPlatformData data), or BBMPlatformConnectionListener.dataReceived(BBMPlatformConnection connection, BBMPlatformContact sender, BBMPlatformData data), depending on if the data is sent from a BBMPlatformChannel or a BBMPlatformSession.

Parameters:

data - The data that's sent to the contact.

contact - The person who is supposed to receive the data.

Throws:

DataOverflowException - if the rate of data sent by the application exceeds that which the BBM Platform allows.

ContactUnreachableException - if pending data for the unreachable contact has exceeded the buffer limit set by the BBM Platform.

NullPointerException - if data is null or empty.

IllegalArgumentException - if data is larger than 60KB.

NullPointerException - if contact is null.

IllegalArgumentException - if contact doesn't belong to this connection.

PersistentContentException - when Content Protection is enabled and device is locked.

Since:

BBM SDK 1.0

sendData

public void sendData(BBMPlatformData data,
                     BBMPlatformContactList contactList)
              throws DataOverflowException,
                     ContactUnreachableException

This API is used to let the application send data to any subset of contacts who have joined the connection.

Note that the Platform cannot guarantee all the packets will come in order, so applications will have to make sure the sequence of events if needed.

Data sent via this API is always private. That is, the receiver never knows who else receives the data, which implies a reply is supposed to be sent to the data sender only. The receiver will receive the data via BBMPlatformConnectionListener.dataReceived(BBMPlatformConnection connection, BBMPlatformContact sender, BBMPlatformData data), or BBMPlatformConnectionListener.dataReceived(BBMPlatformConnection connection, BBMPlatformContact sender, BBMPlatformData data), depending on if the data is sent from a BBMPlatformChannel or a BBMPlatformSession.

Parameters:

data - The data that's sent to the contactList.

contactList - It consists of only the people who are supposed to receive the data and is a subset of the connection's contact list.

Throws:

DataOverflowException - if the rate of data sent by the application exceeds that which the BBM Platform allows.

ContactUnreachableException - if pending data for an unreachable contact in the destination has exceeded the buffer limit set by the BBM Platform.

NullPointerException - if data is null or empty.

IllegalArgumentException - if data is larger than 60KB.

NullPointerException - if contactList is null.

IllegalArgumentException - if contactList has more than 24 data recipients.

IllegalArgumentException - if contactList has any contact that doesn't belong to this connection.

PersistentContentException - when Content Protection is enabled and device is locked.

Since:

BBM SDK 1.0

sendInvitation

public void sendInvitation(String inviteMessage,
                           String cookie,
                           long expiryTime)

This API allows the user to invite his or her BBM contacts to join his or her connection.

Data can only be shared among the people who have joined the same BBMPlatformChannel or BBMPlatformSession.

A Contact Picker will always pop up for the user to select contacts to be invited. Also, an invitation dialog will pop up for the user to type an invitation message.

On the receiver side, if the receiver and the sender have not been connected in any of the connections they have in the same application, the receiver will see the invitation from within the BBM chat and will need choose to accept or decline the invitation manually. However, if the receiver has connected with the sender in any of the connections that they have, which implies they have agreed to be connected to each other before, so this subsequent invitation will not be visible to the receiver and thus the receiver has no need to handle the invitation again manually. The Platform will automatically accept the subsequent invitations on behalf of the receiver as long as the sender and the receiver haven been connected in any existing BBMPlatformChannel or BBMPlatformSession.

For example, if user_A and user_B are connected in Connection_1, which can be a BBMPlatformChannel or BBMPlatformSession, now user_A creates a new Connection_2 and wants to invite user_B to this new connection, then on user_A's side, the application can call Connection_2.sendInvitation(inviteMessage, cookie, expiryTime) which pops up the Contact Picker where user_A can select user_B to send the invitation. In this case, user_B will not see the invitation in the BBM chat but will be automatically added to Connection_2.

Invitation cookies

A custom cookie parameter can be sent with invitations. Cookies are not displayed to the user but can be used as initialization data for when a user accepts an invitation.

If a user accepts the invitation, the cookie will be passed both to the inviter and the invitee in BBMPlatformConnectionListener#onContactsJoined:

• On the inviter's side, type == BBMPlatformConnectionListener.CONTACT_INVITED_BY_ME, contactList contains the joining invitees, and cookie sent with the invitation.
• On the invitee's side, type == BBMPlatformConnectionListener.CONTACT_INVITING_ME, contactList contains the inviter, and the cookie sent with the invitation.

Parameters:

inviteMessage - A custom invitation message that the user provides. This message cannot be null and cannot be longer than 128 characters.

cookie - A custom parameter provided by the application. It can be null but cannot be longer than 128 characters.

expiryTime - It is an invitation expiry time in milliseconds, which is a delta value and set by the inviter's side.
If the expiryTime is zero or a negative value, the invitation will never expire.
If the sender wants the invitation to expire in 5 minutes, then the expiryTime should be set to 5*60*1000L.

Throws:

IllegalStateException - if the connection has been full and the user still tries to invite more people. The Platform allows up to 24 contacts in one BBMPlatformChannel or BBMPlatformSession.

IllegalStateException - if the connection that the user is sending invitation from is inactive, which can happen if BBMPlatformChannel.destroy(), or BBMPlatformSession.leave(), or BBMPlatformSession.end() has been called() previously.

Since:

BBM SDK 1.0

See Also:

sendInvitation(String inviteMessage, String cookie, long expiryTime, ContactListProvider clProvider), add(BBMPlatformContact contact, String cookie)

sendInvitation

public void sendInvitation(String inviteMessage,
                           String cookie,
                           long expiryTime,
                           ContactListProvider clProvider)

This API allows the user to invite his or her BBM contacts to join his or her connection.

A Contact Picker will always pop up for the user to select contacts to be invited. This API allows an application to define the type of contact list that needs to be shown in the Contact Picker. Also, an invitation dialog will pop up for the user to type an invitation message.

Parameters:

inviteMessage - A custom invitation message that the user provides. This message cannot be null and cannot be longer than 128 characters.

cookie - A custom parameter provided by the application. It can be null but cannot be longer than 128 characters.

expiryTime - It is an invitation expiry time in milliseconds, which is a delta value and set by the inviter's side.

clProvider - It allows an application to define the type of contact list that needs to be shown in the Contact Picker. If clProvider is null, the Platform will pop up the Contact Picker with the default setting.
If the expiryTime is zero or a negative value, the invitation will never expire.
If the sender wants the invitation to expire in 5 minutes, then the expiryTime should be set to 5*60*1000L.

Throws:

IllegalStateException - if the connection has been full and the user still tries to invite more people. The Platform allows up to 24 contacts in one BBMPlatformChannel or BBMPlatformSession.

IllegalStateException - if the connection that the user is sending invitation from is inactive, which can happen if BBMPlatformChannel.destroy(), or BBMPlatformSession.leave(), or BBMPlatformSession.end() has been called() previously.

Since:

BBM SDK 1.0

See Also:

sendInvitation(String inviteMessage, String cookie, long expiryTime), add(BBMPlatformContact contact, String cookie)

setPrivate

public boolean setPrivate()

Sets a connection to private. When a new connection (channel or session) is created, the connection is private by default.
If a connection is public and has pending incoming requests that haven't been accepted or declined yet, calling this API will remove all pending join requests that the user has received as a host of the public connection.
Also, the requests senders will be declined to join automatically when this API gets called, but ongoing activities will not be affected. For example, if a player has joined a public game earlier, when this game is set to private, the player will not be kicked out.

Returns:

true if the connection is private, false if the connection is public

Throws:

PersistentContentException - when Content Protection is enabled and device is locked.

Since:

BBM SDK 1.0

See Also:

setPublic()

setPublic

public boolean setPublic()

A connection is private by default. This API allows the user to set a connection to public within an application so that other people who are running the same application can join. The user who initiates this call is the host of the connection. The host can accept or decline a BBMPlatformIncomingJoinRequest.

The BBM Platform allows all application users, who are not necessary in the host's BBM contact list, to send join requests to the host as long as they have the same application installed.

If a request sender successfully joined a public connection, the connection created on this request sender's side will still be private by default unless it is explicitly set to public by the request sender after he or she joins. Once it becomes public on the request sender's side, the request sender can receive join requests from other users too. I.e., a request sender can become a host too if desired, which is completely independent to the original host.

There will be a confirmation dialog when this method gets called, so the method blocks until the dialog is dismissed by the user.

Returns:

true if the connection is public, false if the connection is private

Throws:

IllegalStateException - if the user has hosted a public connection in the same application.

Since:

BBM SDK 1.0

See Also:

setPrivate()