BlackBerry Messenger SDK

Version: 1.0
Getting Started Guide

Published: 2011-08-08
SWD-1391821-0807032923-001

Contents
1 System requirements........................................................................................................................................

2 The BlackBerry Messenger pre-production environment................................................................................

3 Installing and configuring your simulators to support the BlackBerry Messenger SDK....................................
Install and run the BlackBerry MDS Simulator..................................................................................................
Configure the BlackBerry MDS Simulator to use unlimited strength encryption.............................................
Install the BlackBerry Smartphone Simulator package.....................................................................................
Configuring the BlackBerry Smartphone Simulator...................................................................................

4
4
4
4
5

4 Setting up your development environment.....................................................................................................

Create and set up a workspace for your BlackBerry Messenger platform connected application using the
BlackBerry JDE..................................................................................................................................................
Create and setup a project for your BlackBerry Messenger platform connected application using the
BlackBerry Java Plug-in for Eclipse....................................................................................................................

5 Running your application using the simulators................................................................................................

Run your BlackBerry Messenger platform application.....................................................................................

9
9

6 Provide feedback..............................................................................................................................................

10

7 Legal notice.......................................................................................................................................................

11

7
7

Getting Started Guide

System requirements

System requirements

To create BlackBerry Messenger platform connected applications, you must have one of the following development
environments:

BlackBerry Java Plug-in for Eclipse (na.blackberry.com/developers/javaappdev/javaplugin.jsp) that includes

the BlackBerry Java SDK 6.0.
BlackBerry Java Development Environment 6.0 (na.blackberry.com/eng/developers/javaappdev/
javadevenv.jsp).

Getting Started Guide

The BlackBerry Messenger pre-production environment

The BlackBerry Messenger pre-production

environment

The BBM pre-production environment is a development environment that you can use to build and test your BBM
connected app with a small beta community before you release it through the BlackBerry App World storefront. If
your app does not already exist in BlackBerry App World, it is automatically placed in the pre-production environment.
The pre-production environment provides all the functionality of the production environment, with the following
limitations:

Test licenses are limited to 1,000 per app

Apps expire after 180 days
An app in pre-production cannot communicate with the same app that is registered with BlackBerry App World

Getting Started Guide

Installing and configuring your simulators to support the BlackBerry Messenger SDK

Installing and configuring your simulators to

support the BlackBerry Messenger SDK

To test an application that uses the BlackBerry Messenger SDK on a BlackBerry Smartphone Simulator, you must
install and configure the BlackBerry MDS Simulator and BlackBerry Smartphone Simulator with settings that enable
communication between the BlackBerry MDS Simulator and two instances of the BlackBerry Smartphone Simulator.

Install and run the BlackBerry MDS Simulator

Before you begin: Complete the task, Configure the BlackBerry MDS Simulator to use unlimited strength
encryption. If you are running the BlackBerry MDS Simulator on a different computer than the BlackBerry
Smartphone Simulator, in the rimpublic.property file (by default, located in C:\Program Files\Research In Motion
\BlackBerry JDE 6.0.0\MDS\config), change the UDP.send.host value to the IP address of the computer running
the BlackBerry MDS Simulator.
1.
2.
3.
4.
5.

In the folder where you extracted the .zip file containing the BlackBerry Messenger SDK, open the MDS
simulator folder.
Extract the contents of the MDSv3.5.3.zip file.
Open the sdk folder.
Open the mds folder.
Double-click run.bat to launch the BlackBerry MDS Simulator.

Configure the BlackBerry MDS Simulator to use unlimited

strength encryption
The BlackBerry MDS Simulator requires JRE 1.6.0_20 or later with unlimited strength encryption enabled.
Note: You must live in an eligible country to enable this functionality.
1.
2.
3.
4.

Download the jce_policy-6.zip file from the Oracle website at http://www.oracle.com/technetwork/java/

javase/downloads/jce-6-download-429243.html.
Extract the contents of the jce_policy-6.zip file to your computer.
From your system's PATH environment variable, determine the location of your system JRE.
In the JRE security folder of your system JRE (by default, this folder is located at C:\Program Files\Java
\jre1.6.0_20\lib\security), replace the files, local_policy.jar and US_export_policy.jar, with the versions
provided in the .zip file you downloaded.

Install the BlackBerry Smartphone Simulator package

1.
2.
4

In the folder where you extracted the BBM SDK Beta 4_03_10_2011.zip file, open the BlackBerry smartphone
simulator folder.
Double-click the BlackBerry_Simulators_6.0.0.313_9800.exe file.

Getting Started Guide

3.

Install the BlackBerry Smartphone Simulator package

Complete the instructions on the screen.

After you finish installing the BlackBerry Smartphone Simulator package, two .bat files, sim1.bat and sim2.bat,
are available in the folder in which you installed the BlackBerry Smartphone Simulator package. These .bat files
launch two instances of the BlackBerry Smartphone Simulator. These instances communicate with each other
over the BlackBerry Messenger platform using the BlackBerry MDS Simulator running on the same computer.
If you want to run the BlackBerry Smartphone Simulator instances and the BlackBerry MDS Simulator on different
computers, see the Running the BlackBerry Smartphone Simulator topic.

Configuring the BlackBerry Smartphone Simulator

If you want to run the BlackBerry Smartphone Simulator without launching the two .bat files in the BlackBerry
Messenger SDK .zip file, you can create your own .bat files that specifies the following parameters to support the
BlackBerry Messenger SDK.
Parameter
app-param=regDestIP

app-param=regDestPort

appparam=DisableSyncServiceRecord

session
app-param=regSrcPort
pin

Description
This parameter specifies the IP address of the computer running the
BlackBerry MDS Simulator. If the BlackBerry MDS Simulator is running
on the same computer as the BlackBerry Smartphone Simulator,
specify 127.0.0.1.
This parameter should specify the default port, 19781. If you use a
different value, make sure it is the same for every instance of the
BlackBerry Smartphone Simulator.
This parameter must be specified to make PIN-to-PIN communication
between devices possible. If you have run the BlackBerry Smartphone
Simulator without specifying this parameter in the past, in the
BlackBerry JDE click File > Erase Simulator File > Erase Filesystem to
delete the file system anerd remove the SYNC service record from the
previous instance.
The session number must be unique for each instance of the simulator.
The port number must be unique for each instance of the simulator.
This parameter must be 0x2100000 or greater and unique for each
instance of the simulator.

Example
The following example demonstrates how to run two instances of the BlackBerry Smartphone Simulator using the
same BlackBerry MDS Simulator instance. Create a .bat file to launch each custom BlackBerry Smartphone Simulator
instance with the following contents:
Simulator 1 .bat file contents example:

Getting Started Guide

Install the BlackBerry Smartphone Simulator package

@echo off
fledge.exe /app=Jvm.dll /handheld=9800 /session=Sim1 /app-param=JvmAlxConfigFile:
9800.xml /data-port=0x4d44 /data-port=0x4d4e /pin=0x2100000A /app-param=regVersion=3 /
app-param=regDestIP=127.0.0.1 /app-param=regDestPort=19781 /appparam=regSrcPort=19780 /app-param=DisableSyncServiceRecord

Simulator 2 .bat file contents example:

@echo off
fledge.exe /app=Jvm.dll /handheld=9800 /session=Sim2 /app-param=JvmAlxConfigFile:
9800.xml /data-port=0x4d44 /data-port=0x4d4e /pin=0x2100000B /app-param=regVersion=3 /
app-param=regDestIP=127.0.0.1 /app-param=regDestPort=19781 /appparam=regSrcPort=19782 /app-param=DisableSyncServiceRecord

Getting Started Guide

Setting up your development environment

Setting up your development environment

Both the BlackBerry Java Development Environment and the BlackBerry Java Plug-in for Eclipse support
development of BlackBerry Messenger platform enabled applications.

Create and set up a workspace for your BlackBerry

Messenger platform connected application using the
BlackBerry JDE
Before you begin: In the folder where you extracted the BBM SDK Beta 4_03_10_2011.zip file, copy the
net_rim_bb_qm_platform.jar file from the BBM SDK folder to the lib folder of the BlackBerry Java Development
Environment (the default location of the lib folder is C:\Program Files\Research In Motion\BlackBerry JDE 6.0.0\lib).
1.
2.
3.
4.
5.

6.

7.
8.
9.

In the BlackBerry JDE, click File > New Workspace.

In the Workspace Name field, type a name for the workspace and click OK.
Right-click the workspace and click Properties.
In the Workspace Properties dialog box, in the General tab, beside the Imported Jar Files list, click Add.
In the Add file dialog box, navigate to C:\Program Files\Research In Motion\BlackBerry JDE 6.0.0\lib and double
click the net_rim_bb_qm_platform.jar file.
The file appears in the Imported Jar Files list in your workspace properties. You can now import the BlackBerry
Messenger classes and compile your application.
Right-click the workspace and perform one of the following actions:
To import an existing project, click Add Project to <workspace name>.
To create a new project, click Create new Project in <workspace name>.
When you are ready to build your project, click the BlackBerry Smartphone Simulator profile drop-down list
located in the top-right corner of the BlackBerry JDE. By default, the selected profile is Default Simulator.
In the drop-down list, click 9800-6.0.0.313.
On the Build menu, click Build.
The .cod files for your application are created and placed in the simulators directory of the BlackBerry JDE.

After you finish:

To test your application, see Running your application using the simulators.

Create and setup a project for your BlackBerry Messenger

platform connected application using the BlackBerry Java
Plug-in for Eclipse
1.
2.

In Eclipse, open the BlackBerry Application Development perspective.

Click File > New > BlackBerry Project.
7

Getting Started Guide

Create and setup a project for your BlackBerry Messenger platform connected application using the
BlackBerry Java Plug-in for Eclipse

3.
4.
5.
6.
7.
8.
9.

In the New BlackBerry Project dialog box, in the Project Name field, type a name for your project.
In the JRE section, make sure you select a BlackBerry JRE that is version 6.0 or later, and click Finish.
In the Package Explorer view, right-click the project and click Properties.
In the Properties dialog box, in the left pane, click Java Build Path.
Click the Libraries tab.
Click the Add External JARs button.
Navigate to the folder where you extracted the BBM SDK Beta 4_03_10_2011.zip file. In the BBM SDK folder,
double-click net_rim_bb_qm_platform.jar.
10. Click Next.
11. In the properties window, click OK.
12. When you are ready to build your project, on the Project menu, click BlackBerry > Package All.
After you finish:
To test your application see Running your application using the simulators.

Getting Started Guide

Running your application using the simulators

Running your application using the simulators

Run your BlackBerry Messenger platform application

1.
2.
3.

4.
5.

6.
7.
8.
9.
10.
11.
12.
13.

In the folder where you extracted the .zip file containing the BlackBerry Messenger SDK, open the MDS
Simulator -> sdk -> mds folder.
Double-click run.bat to launch the BlackBerry MDS Simulator.
In Windows Explorer, navigate to the folder where you installed the BlackBerry Smartphone Simulator. By
default, the location of this folder is C:\Program Files\Research In Motion\BlackBerry Smartphone Simulators
6.0\6.0.0.313 (9800).
Double-click the sim1.bat file (or your custom .bat file) to launch a BlackBerry Smartphone Simulator with
appropriate settings to run your application and communicate with the BlackBerry MDS Simulator.
In Windows Explorer, in the BlackBerry Smartphone Simulator folder, double-click the sim2.bat file (or your
second custom .bat file) to launch a second instance of the BlackBerry Smartphone Simulator with the
appropriate settings to communicate with the first BlackBerry Smartphone Simulator.
To have each instance of BlackBerry Messenger have each other as contacts, in the first BlackBerry Smartphone
Simulator instance, open BlackBerry Messenger.
Click the Menu key and click the Invite Contact menu item.
Click Invite by sending a PIN or email message.
In the To field, type 2100000B. This is the default PIN of the second BlackBerry Smartphone Simulator instance.
In the second BlackBerry Smartphone Simulator instance, open BlackBerry Messenger and accept the invitation.
Click the Send key.
In the first BlackBerry Smartphone Simulator instance, close BlackBerry Messenger.
On the Home screen, click the icon for your BlackBerry Messenger platform application.

You can now communicate between the two BlackBerry Smartphone Simulator instances.

Getting Started Guide

Provide feedback
To provide feedback on this deliverable, visit www.blackberry.com/docsfeedback.

10

Provide feedback

Getting Started Guide

Legal notice

Legal notice

2011 Research In Motion Limited. All rights reserved. BlackBerry, RIM, Research In Motion, and related
trademarks, names, and logos are the property of Research In Motion Limited and are registered and/or used in the
U.S. and countries around the world.
Java, JRE, and JDK are trademarks of Oracle America, Inc. Windows is a trademark of Microsoft Corporation. All other
trademarks are the property of their respective owners.
This documentation including all documentation incorporated by reference herein such as documentation provided
or made available at www.blackberry.com/go/docs is provided or made accessible "AS IS" and "AS AVAILABLE" and
without condition, endorsement, guarantee, representation, or warranty of any kind by Research In Motion Limited
and its affiliated companies ("RIM") and RIM assumes no responsibility for any typographical, technical, or other
inaccuracies, errors, or omissions in this documentation. In order to protect RIM proprietary and confidential
information and/or trade secrets, this documentation may describe some aspects of RIM technology in generalized
terms. RIM reserves the right to periodically change information that is contained in this documentation; however,
RIM makes no commitment to provide any such changes, updates, enhancements, or other additions to this
documentation to you in a timely manner or at all.
This documentation might contain references to third-party sources of information, hardware or software, products
or services including components and content such as content protected by copyright and/or third-party web sites
(collectively the "Third Party Products and Services"). RIM does not control, and is not responsible for, any Third
Party Products and Services including, without limitation the content, accuracy, copyright compliance, compatibility,
performance, trustworthiness, legality, decency, links, or any other aspect of Third Party Products and Services. The
inclusion of a reference to Third Party Products and Services in this documentation does not imply endorsement by
RIM of the Third Party Products and Services or the third party in any way.
EXCEPT TO THE EXTENT SPECIFICALLY PROHIBITED BY APPLICABLE LAW IN YOUR JURISDICTION, ALL CONDITIONS,
ENDORSEMENTS, GUARANTEES, REPRESENTATIONS, OR WARRANTIES OF ANY KIND, EXPRESS OR IMPLIED,
INCLUDING WITHOUT LIMITATION, ANY CONDITIONS, ENDORSEMENTS, GUARANTEES, REPRESENTATIONS OR
WARRANTIES OF DURABILITY, FITNESS FOR A PARTICULAR PURPOSE OR USE, MERCHANTABILITY, MERCHANTABLE
QUALITY, NON-INFRINGEMENT, SATISFACTORY QUALITY, OR TITLE, OR ARISING FROM A STATUTE OR CUSTOM OR
A COURSE OF DEALING OR USAGE OF TRADE, OR RELATED TO THE DOCUMENTATION OR ITS USE, OR PERFORMANCE
OR NON-PERFORMANCE OF ANY SOFTWARE, HARDWARE, SERVICE, OR ANY THIRD PARTY PRODUCTS AND SERVICES
REFERENCED HEREIN, ARE HEREBY EXCLUDED. YOU MAY ALSO HAVE OTHER RIGHTS THAT VARY BY STATE OR
PROVINCE. SOME JURISDICTIONS MAY NOT ALLOW THE EXCLUSION OR LIMITATION OF IMPLIED WARRANTIES AND
CONDITIONS. TO THE EXTENT PERMITTED BY LAW, ANY IMPLIED WARRANTIES OR CONDITIONS RELATING TO THE
DOCUMENTATION TO THE EXTENT THEY CANNOT BE EXCLUDED AS SET OUT ABOVE, BUT CAN BE LIMITED, ARE
HEREBY LIMITED TO NINETY (90) DAYS FROM THE DATE YOU FIRST ACQUIRED THE DOCUMENTATION OR THE ITEM
THAT IS THE SUBJECT OF THE CLAIM.
TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW IN YOUR JURISDICTION, IN NO EVENT SHALL RIM BE
LIABLE FOR ANY TYPE OF DAMAGES RELATED TO THIS DOCUMENTATION OR ITS USE, OR PERFORMANCE OR NONPERFORMANCE OF ANY SOFTWARE, HARDWARE, SERVICE, OR ANY THIRD PARTY PRODUCTS AND SERVICES
REFERENCED HEREIN INCLUDING WITHOUT LIMITATION ANY OF THE FOLLOWING DAMAGES: DIRECT,
CONSEQUENTIAL, EXEMPLARY, INCIDENTAL, INDIRECT, SPECIAL, PUNITIVE, OR AGGRAVATED DAMAGES, DAMAGES
11

Getting Started Guide

Legal notice

FOR LOSS OF PROFITS OR REVENUES, FAILURE TO REALIZE ANY EXPECTED SAVINGS, BUSINESS INTERRUPTION, LOSS
OF BUSINESS INFORMATION, LOSS OF BUSINESS OPPORTUNITY, OR CORRUPTION OR LOSS OF DATA, FAILURES TO
TRANSMIT OR RECEIVE ANY DATA, PROBLEMS ASSOCIATED WITH ANY APPLICATIONS USED IN CONJUNCTION WITH
RIM PRODUCTS OR SERVICES, DOWNTIME COSTS, LOSS OF THE USE OF RIM PRODUCTS OR SERVICES OR ANY PORTION
THEREOF OR OF ANY AIRTIME SERVICES, COST OF SUBSTITUTE GOODS, COSTS OF COVER, FACILITIES OR SERVICES,
COST OF CAPITAL, OR OTHER SIMILAR PECUNIARY LOSSES, WHETHER OR NOT SUCH DAMAGES WERE FORESEEN OR
UNFORESEEN, AND EVEN IF RIM HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW IN YOUR JURISDICTION, RIM SHALL HAVE NO OTHER
OBLIGATION, DUTY, OR LIABILITY WHATSOEVER IN CONTRACT, TORT, OR OTHERWISE TO YOU INCLUDING ANY
LIABILITY FOR NEGLIGENCE OR STRICT LIABILITY.
THE LIMITATIONS, EXCLUSIONS, AND DISCLAIMERS HEREIN SHALL APPLY: (A) IRRESPECTIVE OF THE NATURE OF THE
CAUSE OF ACTION, DEMAND, OR ACTION BY YOU INCLUDING BUT NOT LIMITED TO BREACH OF CONTRACT,
NEGLIGENCE, TORT, STRICT LIABILITY OR ANY OTHER LEGAL THEORY AND SHALL SURVIVE A FUNDAMENTAL BREACH
OR BREACHES OR THE FAILURE OF THE ESSENTIAL PURPOSE OF THIS AGREEMENT OR OF ANY REMEDY CONTAINED
HEREIN; AND (B) TO RIM AND ITS AFFILIATED COMPANIES, THEIR SUCCESSORS, ASSIGNS, AGENTS, SUPPLIERS
(INCLUDING AIRTIME SERVICE PROVIDERS), AUTHORIZED RIM DISTRIBUTORS (ALSO INCLUDING AIRTIME SERVICE
PROVIDERS) AND THEIR RESPECTIVE DIRECTORS, EMPLOYEES, AND INDEPENDENT CONTRACTORS.
IN ADDITION TO THE LIMITATIONS AND EXCLUSIONS SET OUT ABOVE, IN NO EVENT SHALL ANY DIRECTOR, EMPLOYEE,
AGENT, DISTRIBUTOR, SUPPLIER, INDEPENDENT CONTRACTOR OF RIM OR ANY AFFILIATES OF RIM HAVE ANY
LIABILITY ARISING FROM OR RELATED TO THE DOCUMENTATION.
Prior to subscribing for, installing, or using any Third Party Products and Services, it is your responsibility to ensure
that your airtime service provider has agreed to support all of their features. Some airtime service providers might
not offer Internet browsing functionality with a subscription to the BlackBerry Internet Service. Check with your
service provider for availability, roaming arrangements, service plans and features. Installation or use of Third Party
Products and Services with RIM's products and services may require one or more patent, trademark, copyright, or
other licenses in order to avoid infringement or violation of third party rights. You are solely responsible for
determining whether to use Third Party Products and Services and if any third party licenses are required to do so.
If required you are responsible for acquiring them. You should not install or use Third Party Products and Services
until all necessary licenses have been acquired. Any Third Party Products and Services that are provided with RIM's
products and services are provided as a convenience to you and are provided "AS IS" with no express or implied
conditions, endorsements, guarantees, representations, or warranties of any kind by RIM and RIM assumes no liability
whatsoever, in relation thereto. Your use of Third Party Products and Services shall be governed by and subject to
you agreeing to the terms of separate licenses and other agreements applicable thereto with third parties, except
to the extent expressly covered by a license or other agreement with RIM.
Certain features outlined in this documentation require a minimum version of BlackBerry Enterprise Server,
BlackBerry Desktop Software, and/or BlackBerry Device Software.

12

Getting Started Guide

Legal notice

The terms of use of any RIM product or service are set out in a separate license or other agreement with RIM applicable
thereto. NOTHING IN THIS DOCUMENTATION IS INTENDED TO SUPERSEDE ANY EXPRESS WRITTEN AGREEMENTS OR
WARRANTIES PROVIDED BY RIM FOR PORTIONS OF ANY RIM PRODUCT OR SERVICE OTHER THAN THIS
DOCUMENTATION.

Research In Motion Limited

295 Phillip Street
Waterloo, ON N2L 3W8
Canada
Research In Motion UK Limited
Centrum House
36 Station Road
Egham, Surrey TW20 9LF
United Kingdom
Published in Canada

13