Overview  Package   Class  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES
SUMMARY:  INNER | FIELD | CONSTR | METHOD DETAIL:  FIELD | CONSTR | METHOD
 

net.rim.blackberry.api.bbm.platform
Interface BBMPlatformContext

public interface BBMPlatformContext

In order to access the BBM platform, an application should register with the BBMPlatformManager by calling its registration method, which returns a BBMPlatformContext object. BBMPlatformContext contains information about the application registration and platform access status. To receive a notification of any status changes, the application must attach a BBMPlatformContextListener to the BBMPlatformContext object.

Since:
BBM SDK 1.0

Field Summary
static int ACCESS_ALLOWED
          Access permission status that indicates that the application has full access to BBM Social SDK.
static int ACCESS_BLOCKED_BY_IT_POLICY
          Access permission status that indicates that the application has been blocked by IT policy.
static int ACCESS_BLOCKED_BY_RIM
          Access permission status that indicates that the application has been blocked by RIM (the application has most likely violated the terms of use).
static int ACCESS_BLOCKED_BY_USER
          Access permission status that indicates that the application has been blocked by the user.
static int ACCESS_BLOCKED_RESET_REQUIRED
          Access permission status that indicates the user needs to reset their device in order for this application to continue the registration process.
static int ACCESS_NO_DATA_COVERAGE
          Access permission status that indicates that the application is pending registration because device is out of data coverage.
static int ACCESS_REGISTER_WITH_UI_APPLICATION
          Access permission status that indicates that the application needs to register using a UiApplication because user interaction is required.
static int ACCESS_REREGISTRATION_REQUIRED
          Access permission status that indicates the application needs to re-register with BBM Social SDK by calling BBMPlatformManager.register(BBMPlatformApplication).
static int ACCESS_TEMPORARY_ERROR
          Access permission status that indicates that the application is pending registration because of a temporary error.
static int APP_ENVIRONMENT_APPWORLD
          This constant indicates the application exists in AppWorld.
static int APP_ENVIRONMENT_TEST
          This constant indicates the application doesn't exist in App World.
static int BBM_SDK_VER_1_0
          Constant representing BBM SDK version 1.0
static int BBM_SDK_VER_1_2
          Constant representing BBM SDK version 1.2
static int BBM_SDK_VER_1_3
          Constant representing BBM SDK version 1.3
static int INVOKE_CHAT_MESSAGE
          Invocation code indicating that the application was invoked by clicking a chat message TPA link in a BBM chat.
static int INVOKE_PERSONAL_MESSAGE
          Invocation code indicating that the application was invoked by clicking a personal message TPA link in a user's BBM profile.
static int INVOKE_PROFILE_BOX
          Invocation code indicating that the application was invoked by clicking a profile box header in a user's BBM profile.
static int INVOKE_PROFILE_BOX_ITEM
          Invocation code indicating that the application was invoked by clicking a profile box item in a user's BBM profile.
static int SETTING_SHARECONTENT_SPLAT
          This constant enables the BBM Platform to splat the application's home screen icon when MessagingService#shareContent(String, BBMPlatformData) request is received while application is not running This constant can be set by overriding BBMPlatformApplication.getDefaultSettings()
 
Method Summary
 int getAccessErrorCode()
          Returns the access status code that indicates the current access status to the BBM Social SDK,
 int getAppEnvironment()
          Tells if the application exists in AppWorld.
 ContactListService getContactListService()
          Retrieves ContactListService registered with the BBM platform.
 MessagingService getMessagingService()
          Retrieves MessagingService registered with BBM platform.
 SettingsManager getSettingsManager()
          Retrieves SettingsManager registered with the BBM platform.
 UIService getUIService()
          Retrieves UIService registered with BBM platform.
 UserProfile getUserProfile()
          Retrieves this device user's profile.
 boolean isAccessAllowed()
          Checks if the application is authorized to access BBM.
 void removeListener()
          Removes a BBMPlatformContextListener from BBMPlatformContext.
 void requestAppSettings()
          Brings the BBM settings screen for this application to the foreground.
 void requestBBMToForeground()
          Requests to have the BBM application brought to the foreground.
 boolean requestUserPermission()
          Deprecated. Use requestAppSettings().
 void setListener(BBMPlatformContextListener listener)
          Sets a BBMPlatformContextListener for the BBMPlatformContext.
 

Field Detail

ACCESS_ALLOWED

public static final int ACCESS_ALLOWED
Access permission status that indicates that the application has full access to BBM Social SDK.
Since:
BBM SDK 1.0

ACCESS_BLOCKED_BY_IT_POLICY

public static final int ACCESS_BLOCKED_BY_IT_POLICY
Access permission status that indicates that the application has been blocked by IT policy.
Since:
BBM SDK 1.2

ACCESS_BLOCKED_BY_RIM

public static final int ACCESS_BLOCKED_BY_RIM
Access permission status that indicates that the application has been blocked by RIM (the application has most likely violated the terms of use).
Since:
BBM SDK 1.0

ACCESS_BLOCKED_BY_USER

public static final int ACCESS_BLOCKED_BY_USER
Access permission status that indicates that the application has been blocked by the user. Access to BBM Social SDK is not allowed.

The application can ask the user to change the setting, and bring him or her to the application's BBM Options screen by calling requestAppSettings().

Since:
BBM SDK 1.0

ACCESS_BLOCKED_RESET_REQUIRED

public static final int ACCESS_BLOCKED_RESET_REQUIRED
Access permission status that indicates the user needs to reset their device in order for this application to continue the registration process. The application will be blocked until the user resets the device.
Since:
BBM SDK 1.0

ACCESS_NO_DATA_COVERAGE

public static final int ACCESS_NO_DATA_COVERAGE
Access permission status that indicates that the application is pending registration because device is out of data coverage. The user needs to enable data services and have sufficient data coverage in order to register the application. The application can call BBMPlatformManager.register(BBMPlatformApplication) again if there is sufficient coverage.
Since:
BBM SDK 1.0

ACCESS_REGISTER_WITH_UI_APPLICATION

public static final int ACCESS_REGISTER_WITH_UI_APPLICATION
Access permission status that indicates that the application needs to register using a UiApplication because user interaction is required.
Since:
BBM SDK 1.0

ACCESS_REREGISTRATION_REQUIRED

public static final int ACCESS_REREGISTRATION_REQUIRED
Access permission status that indicates the application needs to re-register with BBM Social SDK by calling BBMPlatformManager.register(BBMPlatformApplication). All references obtained through the API are no longer valid and need to be re-acquired. Call BBMPlatformManager.register(BBMPlatformApplication application) to obtain a new BBMPlatformContext and subsequently new references for MessagingService, UIService, ContactListService, UserProfile, etc.
Since:
BBM SDK 1.0

ACCESS_TEMPORARY_ERROR

public static final int ACCESS_TEMPORARY_ERROR
Access permission status that indicates that the application is pending registration because of a temporary error. The application should try to call BBMPlatformManager.register(BBMPlatformApplication) in 30 minutes or the next time the application starts.
Since:
BBM SDK 1.0

APP_ENVIRONMENT_APPWORLD

public static final int APP_ENVIRONMENT_APPWORLD
This constant indicates the application exists in AppWorld.
Since:
BBM SDK 1.0

APP_ENVIRONMENT_TEST

public static final int APP_ENVIRONMENT_TEST
This constant indicates the application doesn't exist in App World.
Since:
BBM SDK 1.0

BBM_SDK_VER_1_0

public static final int BBM_SDK_VER_1_0
Constant representing BBM SDK version 1.0
See Also:
Presence.getBBMSDKVersion()
Since:
BBM SDK 1.2

BBM_SDK_VER_1_2

public static final int BBM_SDK_VER_1_2
Constant representing BBM SDK version 1.2
See Also:
Presence.getBBMSDKVersion()
Since:
BBM SDK 1.2

BBM_SDK_VER_1_3

public static final int BBM_SDK_VER_1_3
Constant representing BBM SDK version 1.3
See Also:
Presence.getBBMSDKVersion()
Since:
BBM SDK 1.3

INVOKE_CHAT_MESSAGE

public static final int INVOKE_CHAT_MESSAGE
Invocation code indicating that the application was invoked by clicking a chat message TPA link in a BBM chat.

A TPA link appears in a chat message (bubble) when the user starts a chat from the application, using UIService.startBBMChat(java.lang.String).

Used in BBMPlatformContextListener.appInvoked(int, Object, Presence), where:

  • param is null.
  • user is the user whose chat message TPA link was clicked.
See Also:
BBMPlatformContextListener.appInvoked(int, Object, Presence), UIService.startBBMChat(java.lang.String)
Since:
BBM SDK 1.3

INVOKE_PERSONAL_MESSAGE

public static final int INVOKE_PERSONAL_MESSAGE
Invocation code indicating that the application was invoked by clicking a personal message TPA link in a user's BBM profile.

A TPA link appears in a user's personal message when set by UserProfile.setPersonalMessage(java.lang.String).

Used in BBMPlatformContextListener.appInvoked(int, Object, Presence), where:

  • param is the personal message String, excluding the TPA link.
  • user is the user whose personal message TPA link was clicked.
See Also:
BBMPlatformContextListener.appInvoked(int, Object, Presence), UserProfile.setPersonalMessage(String)
Since:
BBM SDK 1.3

INVOKE_PROFILE_BOX

public static final int INVOKE_PROFILE_BOX
Invocation code indicating that the application was invoked by clicking a profile box header in a user's BBM profile.

Used in BBMPlatformContextListener.appInvoked(int, Object, Presence), where:

  • param is null.
  • user is the user whose profile box was clicked.
See Also:
BBMPlatformContextListener.appInvoked(int, Object, Presence), UserProfileBox
Since:
BBM SDK 1.3

INVOKE_PROFILE_BOX_ITEM

public static final int INVOKE_PROFILE_BOX_ITEM
Invocation code indicating that the application was invoked by clicking a profile box item in a user's BBM profile.

Used in BBMPlatformContextListener.appInvoked(int, Object, Presence), where:

  • param is the UserProfileBoxItem that was clicked.
  • user is the user whose profile box item was clicked.
See Also:
BBMPlatformContextListener.appInvoked(int, Object, Presence), UserProfileBox
Since:
BBM SDK 1.0

SETTING_SHARECONTENT_SPLAT

public static final int SETTING_SHARECONTENT_SPLAT
This constant enables the BBM Platform to splat the application's home screen icon when MessagingService#shareContent(String, BBMPlatformData) request is received while application is not running

This constant can be set by overriding BBMPlatformApplication.getDefaultSettings()

Since:
BBM SDK 1.2
Method Detail

getAccessErrorCode

public int getAccessErrorCode()
Returns the access status code that indicates the current access status to the BBM Social SDK,
Returns:
status code that indicates the current access status to the BBM Social SDK (see ACCESS_*)
Since:
BBM SDK 1.0

getAppEnvironment

public int getAppEnvironment()
                      throws ControlledAccessException
Tells if the application exists in AppWorld.
Returns:
APP_ENVIRONMENT_TEST or APP_ENVIRONMENT_APPWORLD
Throws:
ControlledAccessException - if the caller does not have access permission to BBM platform.
Since:
BBM SDK 1.0

getContactListService

public ContactListService getContactListService()
                                         throws ControlledAccessException
Retrieves ContactListService registered with the BBM platform.
Returns:
ContactListService instance
Throws:
ControlledAccessException - if the caller does not have access permission to BBM platform.
Since:
BBM SDK 1.0

getMessagingService

public MessagingService getMessagingService()
                                     throws ControlledAccessException
Retrieves MessagingService registered with BBM platform.
Returns:
MessagingService instance
Throws:
ControlledAccessException - if the caller does not have access permission to BBM platform.
Since:
BBM SDK 1.0

getSettingsManager

public SettingsManager getSettingsManager()
                                   throws ControlledAccessException
Retrieves SettingsManager registered with the BBM platform.
Returns:
the settings manager
Throws:
ControlledAccessException - if the caller does not have access permission to BBM platform.
Since:
BBM SDK 1.2

getUIService

public UIService getUIService()
                       throws ControlledAccessException
Retrieves UIService registered with BBM platform.
Returns:
UIService instance
Throws:
ControlledAccessException - if the caller does not have access permission to BBM platform.
Since:
BBM SDK 1.0

getUserProfile

public UserProfile getUserProfile()
                           throws ControlledAccessException
Retrieves this device user's profile.
Returns:
UserProfile
Throws:
ControlledAccessException - if the caller does not have access permission to BBM platform.
PersistentContentException - when Content Protection is enabled and device is locked.
Since:
BBM SDK 1.0

isAccessAllowed

public boolean isAccessAllowed()
Checks if the application is authorized to access BBM. If access is not allowed, the error can be obtained using getAccessErrorCode().
Returns:
true if the application is authorized to access BBM, false otherwise.
Since:
BBM SDK 1.0

removeListener

public void removeListener()
Removes a BBMPlatformContextListener from BBMPlatformContext. If a listener has not been added, then this method does nothing.
Since:
BBM SDK 1.0

requestAppSettings

public void requestAppSettings()
Brings the BBM settings screen for this application to the foreground. This method may only be called if getAccessErrorCode() has a value of ACCESS_ALLOWED or ACCESS_BLOCKED_BY_USER.
Throws:
IllegalStateException - if not called from the event thread of a UiApplication
ControlledAccessException - if getAccessErrorCode() is not ACCESS_ALLOWED or ACCESS_BLOCKED_BY_USER.
Since:
BBM SDK 1.2

requestBBMToForeground

public void requestBBMToForeground()
Requests to have the BBM application brought to the foreground. When the user hasn't initialized BBM, the application may want to bring BBM to foreground to complete initialization.
Since:
BBM SDK 1.0

requestUserPermission

public boolean requestUserPermission()
Deprecated. Use requestAppSettings().

Requests the user to connect to the application. This is a blocking call and will be executed on the event thread using net.rim.device.api.system.Application#invokeAndWait(Runnable). The method has no effect unless getAccessErrorCode() has a value of ACCESS_BLOCKED_BY_USER.
Returns:
true if the user connected the application to BBM; otherwise, false. Returns false if getAccessErrorCode() is not ACCESS_BLOCKED_BY_USER.
Throws:
IllegalStateException - if not called from a UiApplication
Since:
BBM SDK 1.0

setListener

public void setListener(BBMPlatformContextListener listener)
Sets a BBMPlatformContextListener for the BBMPlatformContext. The listener will be notified of all BBMPlatformContext events.
Parameters:
listener - The listener to add to the BBMPlatformContext
Since:
BBM SDK 1.0

Overview  Package   Class  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES
SUMMARY:  INNER | FIELD | CONSTR | METHOD DETAIL:  FIELD | CONSTR | METHOD

Copyright 1999- 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.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.