Blackberry RIM 950 User Manual
Developer’s Guide
RIM 950 Wireless Handheld™
Version 1.7
SDK User’s Guide
RIM 950 Wireless Handheld — SDK User's Guide, Version 1.7
Last revised 9/18/00
Part Number: PD F-03037-001
© 1997-2000, RESEARCH IN MOTION LIMITED
RIM, Research In Motion, the RIM logo, RIM 950 Wireless Handheld, RIM 957
Wireless Handheld, RIM 950, RIM 957 and RIM Wireless Handheld are trademarks
of Research In Motion Limited. Research In Motion and RIM are registered, U.S.
Patent and Trademark Office.
Complies wit h software O/S version 2.0 and applications version 1.7.
Visual C++ and Windows are trademarks of Microsoft Corporation. Intel is a
registered trademark of Intel Corporat thoion. Mobitex is a registered trademark of
Telia AB. DataTAC is a registered trademark of Motorola. All other brands, product
names, company names, trademarks, and service marks mentioned herein are
registered trademarks or trademarks of their respective holders.
Warning: This document is for the use of licensed users only. Any unauthorized
copying, distribution or disclosure of information is a violation of copyright laws.
While every effort has been made to ensure technical accuracy, information in this
document is subject to change without notice and does not represent a commitment
on the part of Research In Motion Limited.
Research In Motion Li mited
295 Phillip Street
Waterloo, Ontario
Canada N2L 3W8
Tel. (519) 888-7465
Fax (519) 888-6906
Web site: www.rim.net
Email: info@rim.net
Printed In Canada
JHM0700/sdk_uguide.doc
Contents
1. Introduction............................................................................................5
About the SDK......................................................................................5
About the network ...............................................................................6
About Research In Motion..................................................................6
About this guide...................................................................................6
2. Installing the SDK................................................................................9
To install the SDK.................................................................................9
To configure Microsoft Developer Studio.......................................11
3. Release notes........................................................................................15
Recompiling your applications.........................................................15
Message................................................................................................15
OS..........................................................................................................16
New simulator....................................................................................16
Ribbon changes...................................................................................16
Address Book changes.......................................................................17
4. Tools guide...........................................................................................19
RIM 950 Wireless Handheld simulator ...........................................19
Program loader...................................................................................37
DLLUtil................................................................................................47
Conversion utilities............................................................................47
5. An overview of the system................................................................49
RIM co-operative scheduler..............................................................50
Tasks and threads...............................................................................50
Task yielding.......................................................................................50
MESSAGE concept.............................................................................51
Memory use.........................................................................................51
User interface......................................................................................52
API overview ......................................................................................52
6. Building applications.........................................................................55
Coding an application........................................................................55
Compiling RIM Wireless Handheld applications..........................63
Installing the application...................................................................64
Appendix ..................................................................................................69
C library compatibility for RIM Wireless Ha ndheld applications69
Index..........................................................................................................75
1.Introduction
The RIM 950 Wireless Handheld Software Developer’s Kit (SDK)
includes all the tools needed to begi n application development quickly.
The SDK provides an extremely powerful development environment
that utilizes Microsoft Developer Studio 5.0 or later (Visual C++ 5.0 or
later), supporting Windows 95 and Windows NT.
The RIM Wireless Handheld™ features a 32-bit Intel386™ processor
which executes the same instruction set as a Windows 95 computer. The
operating system provided with the wireless handhel d is a multitasking
operating system with built-in messaging. You can write new
components for the wirele ss handheld wi thout needing to rewr ite entire
applications.
About the SDK
The SDK package includes:
• software
• application utilities
• PC-based simulator (herein referred to as the “RIM Wireless
Handheld simulator”)
If you have used a previous version of this SDK, you should read the
release notes section of this document (see page 15). The release notes
section describes changes required to make old applications run under
this version of the software. For example, it describes the new versioning
scheme and outlines compatibility requirements in new releases.
6 Introduction — About the network
About the network
The RIM Wireless Handheld operates over the BellSouth Intelligent
Wireless Network
wireless data network in Canada. Both networks offer broad coverage,
nationwide roaming, fast messaging, a nd reliable delivery. Even if your
RIM Wireless Handheld is turned off or temporarily out of coverage,
your messages will be stored and forwarded automatically when you
return to coverage.
SM
in the United States and the Rogers™ AT&T®
About Research In Motion
Research In Motion (RIM) manufactures high performance radio
modems for use with the Mobitex network. These modems and other
Mobitex products manufactured by RIM are used on Mobitex networks
around the world.
RIM has an internatio nal r eputa tion f or de velop in g hig h per for mance RF
technology in the narrowband PCS data communications industry.
RIM’s wireless technology has set new standards for battery life,
transceiver performance, physical size, ease-of-use, and price.
By helping companies design a broad range of wireless data products,
RIM has a detailed understanding of what end users and equipment
manufacturers need to use the Mobitex network effectively and
affordably.
The result of this close co- o per ation is a fa mily of ad vanc ed wir eles s da ta
products that are easy to use and integra te quickly, including the RIM
902M™ OEM radio modem and the RIM 950 Wireless Handheld.
About this guide
These Developer’s Guides are meant to assist you in creating your
applications. This guide includes general information on the SDK itself.
Throughout this guide, the simulator will be referred to as the ‘RIM
Wireless Handheld simulator.’
Developer’s Guide – RIM 950 Wireless Handheld™
Introduction — About this guide 7
Some information is set apart typographically in the following ways:
Note
Notes provide additional information to help complete a task.
Tips offer an alternative method of performing an action
Tip
WARNING
Warnings follow any procedure or paragraph containing
instructions that, if followed improperly, could result in
damaging the RIM Wireless Handheld or software.
The names of program groups, icons, folders, wi ndows, etc. will appear
in bold text. An example would be the Research In Motion program
group.
References to buttons have the hot key underlined where applicable. An
example would be the N
ext> button.
All programming elements such as returns, events, constants, structures,
parameters, etc. will appear in
the
COMM_RX_ERROR error code.
Courier New font. An example would be
Developer’s Guide – RIM 950 Wireless Handheld™
2. Installing the SDK
In order to run the RIM 950 Wireless Handheld Software Developer’s
Kit, you need a PC capable of running Microsof t De veloper Studio 5.0 (or
later). This chapter describes the process of installing the RIM 950
Wireless Handheld SDK an d config uring Microsof t De veloper Studi o 5.0
(or later) to work with the SDK.
You can install and run the RIM 950 Wireless Handheld SDK in both
Windows 95 and Windows NT.
To install the SDK
1. Double-click on the installer icon.
2. The RIM Wireless Handheld simulator setup desktop will appear.
Follow the instructions on your screen throughout the setup process.
Software License Agreement window
10 Installing the SDK — To install the SDK
Note
Please read the license agreement carefully. Proceeding with the
installation indicates that you agree with the conditions in the license
agreement.
3. When the Choose Destination Location window opens, a default
directory will be displayed. To change this directory, click the
Br
owse button, and the Choose Directory window will open. Select
the path, drive, and directory that you would like for your
destination. Click OK to return to the Ch oose Destination Location
window.
Choose Destination Location window
4. Once you have selected the destination directory, click N
continue. The Select Program Folder window opens.
Select Program Folder window
Developer’s Guide – RIM 950 Wireless Handheld™
ext> to
Installing the SDK — To configure Microsoft Developer Studio 11
5. Type in a folder name in which the setup items will be stored. The
default folder name is Research In Motion. Alternatively, you may
select a folder from the Existing Folders section.
6. At the end of the installation, an Installation Query window will
open to ask if you would like to view the README file.
7. A new window will open to display the Research In Motion
program group.
The RIM 950 Wireless Handheld SDK contains all of the tools and
information needed to build an application.
See page 55 for information on the process of building an applica tion for
the RIM Wireless Handheld and the structure of an application. See
Chapter 3 – Tools Guide on page 19 for information on the tools use d to
create a wireless handheld application and for a description of their
function and usage.
To configure Microsoft Developer Studio
The RIM 950 Wireless Handheld SDK is designed to make use of the
libraries and features in Microsoft Developer Studio 5.0 (or later).
Handheld applications are built as a Windows DLL target, but they are
not used as Windows applications. The final DLL is stripped of
extraneous information and then ported into the RIM Wireless Handheld
operating system.
Because Windows sees the RIM Wireless Handheld applications as
DLLs, Developer Studio allows you to use nearly all development
facilities available for Windows, including using the Integrated
Development Environment, source level debugging, and breakpoints.
However, DLLs must not make calls to the Windows API, even when
running under Wind ows.
You must be familiar with Microsoft Developer Studio to develop
applications. You must purchase and become familiar with this
application separately from the RIM 950 Wireless Handheld Software
Developer’s Kit.
Developer’s Guide – RIM 950 Wireless Handheld™
12 Installing the SDK — To configure Microsoft Developer Studio
Follow these steps to configure the Microsoft Visual C++ 5.0 (or later)
environment for building RIM 950 Wireless Handheld applications.
1. Start the Microsoft Developer Studio and select File > New > Project
to create a new project.
• Give the project a name.
• Define the project type as WIN32.DLL.
Although the target is a Windows DLL, the RIM Wireless
Handheld application is not compatible with the Windows
operating system.
2. Select Project > Settings to set up the project parameters.
• Go to the Settings For: tab.
• Select All Configurations.
3. Go to the Debug tab.
• Set the executable for the Debug Session as OSLOADER.EXE.
• In the Program arguments field put a line in the form:
OS DLL] [OS parameters] [application DLLs]
[
[
OS DLL] should be OSPGRMB.DLL if you are simulating a
RIM 950 and OSHHMB.DLL if you are simulating a RIM
957™. (If you’re using OSLOADER.EXE, you don’t need to
specify a complete path because the program looks first in its
current directory.) [
switches you need to pass to the simulator.
• Fina lly, list all of the applic ation DLLs at the end of the line,
making sure your application is the last one listed.
In order for the OSLOADER.EXE to find the DLLS, you must
either place the DLLs in your
directory and use that directory as your working directory.
4. Go to the C/C++ tab.
• Set the Category to Preprocessor.
• Enter the paths for the SDK include files in the Additional
Include Directories field. These paths are to the
OS parameters] are any command line
PATH or place them in the same
Developer’s Guide – RIM 950 Wireless Handheld™
Installing the SDK — To configure Microsoft Developer Studio 13
subdirectories \include and \include\internal of the RIM 950
Wireless Handheld SDK installation directory.
5. Change the Category to Code Generation.
• Set the Struct Member Alignment to 2 bytes. This will
minimize memory usage.
• Set the Processor to 80386.
6. Change the Category to C/C++ Language.
• Make sure that all check boxes are unchecked.
• The Enable Exception Handling checkbox should always be
unchecked.
7. Switch to the Link tab.
• Set the Category to General.
• At the end of the Object/Library Modules field, include the
files RIMOS.LIB, OSENTRY.OBJ, at the beginnin g, followed
by any .LIB files that are required (e.g. UI32.LIB,
ADDRESS.LIB, etc.). Place LIBC.LIB at the end.
• Check the checkbox Ignore all default libraries. Set the
Category to Input.
• Place the path to the subdirectory
\lib of the RIM 950
Wireless Handheld SDK installation directory in the
Additional librar y path.
8. Save these settings.
9. Your setup is complete. Now you are ready to create your
application.
Developer’s Guide – RIM 950 Wireless Handheld™
3.Release notes
This section describes some of the cha nges between versions 1.6 and 1.7
of the RIM 950 Wireless Handheld SDK. It describes changes you must
make to your existing code base before attempti ng to build applications
for RIM 950 Wireless Handheld 1.7.
WARNING
RIM 950 Wireless Handheld 1.7 comes with a new operating system, a
new simulation environme nt and some new methods and classes. This
section lists the methods and functions that have changed for 1.7 . You
should pay close attention to this list and modify your cod e if you used
the old forms.
The 1.7 environment is not binary compatible with 1.6. You
must recompile your code before running it on a 1.7 system.
Recompiling your applications
There is a new OS library, named RIMOS.LIB. Change the linker
settings for your development environment and replace the old OS
library (PAGER950.LIB) with RIMOS.LIB.
There are also a number of new methods and classes for 1.7. Check the
sections below for any code changes you might require. Be sure to
modify your code appr opriately to match the ne w method signatures.
Message
The create_message() call has been modified. It was:
bool create_message (NetworkMessage * message = NULL)
It is now:
bool create_message ( void )
16 Release notes — OS
See the Message API Developer’s Guide for more information.
OS
Version 2.0 of the OS removes certain constants. The constants
LCD_WIDTH, LCD_HEIGHT, LCD_HEIGHT_BYTE, LCD_DISPLAY_SIZE, and
LCD_DISPLAY_SIZE_BYTE that were available but deprecated in
previous releases of the SDK are no longer available. The information
they provided should be obtained using the
<LCD_API.H>). For quick recompiling, the header PRE20.H can be
included, which defines those values as function calls. This solution
should be avoided, ho wever, since the overhead of the functions makes
the use of the values very inefficient.
New simulator
For RIM 950 Wireless Handheld 1.7, a new simulator replaces the
existing PAGER950 executable. To debug applications using the new
simulator, replace PAGER950.EXE in the
field of the
OS DLL (for example, OSPGRMB.DLL) to the
the first argument. For more information on how to use the new
simulator, see the section titled “Device Simulator” in this guide.
Debug tab in the project settings with OSLOADER.EXE. Use an
LcdGetConfig call (from
Executable for debug session
Program arguments field as
Ribbon changes
The call RibbonSetApplicationString() now has an extra
parameter. If your application calls this function, you will get a lin k error
and will need to make a small code change.
The previous version of the call in the 1.5 S DK was d efined in RIBBON.H
as:
void RibbonSetApplicationString(
const char * const appName,
const char * const string,
int priority );
Developer’s Guide – RIM 950 Wireless Handheld™
Release notes — Address Book changes 17
The new version of the call is defined as:
void RibbonSetApplicationString(
const char * const appName,
const char * const string,
int priority,
const BitMap * const bitMapPtr );
The
bitMapPtr parameter is new, and refers to an optional image that
can be displayed instea d of one of the c harac ters of
has a normal maximum of five characters; if
the maximum is four characters, because one character position is used
by the bitmap.
string. The string
bitMapPtr is not NULL,
Address Book changes
Two functions have been added to notify the application of changes t o
the Address Book’s data:
an application, and
number of changes since the last reset.
register_address_book_update() registers
get_address_book_change_count() returns the
The Address Boo k API n o w has a set of f unct io ns f or de aling wit h group
addresses. A group address is an add ress name that represents a list of
other addresses. The new group addressing functions provide the
following features for dealing with group addresses:
• Determine if an address is a group address
• Get number of members
• Get information about members
• Get UIN from address handle
Developer’s Guide – RIM 950 Wireless Handheld™
4.Tools guide
This section provides information on how to make use of the tools
provided in the SDK. These tools are provided:
• RIM Wireless Handheld simulator program
(SIMULATOR.EXE/OSLOADER.EXE), used to test programs on a
PC without loading them onto a wireless handheld
• Program Loader program (PROGRAMMER.EXE), used to load
programs onto the RIM Wireless Handheld
• Conversion utilities for creating fonts and bitmaps
(BMP2DEF.EXE, BITMAP.EXE, and LCDFONT.EXE)
• A utility (DLLUTIL.EXE) to display information about a RIM
Wireless Handheld application
This chapter describes configuration and use for each of these tools. We
assume you have a basic familiarity with Microsoft Developer Studio.
RIM 950 Wireless Handheld simulator
The simulator allows you to test applications on the RIM Wireless
Handheld operating system without having to download the DLLs to the
wireless handheld itself. T he simulator supports t he full functionality of
the RIM Wireless Handheld itself, and can even be connected to a RAP
modem via the PC’s serial port, allowing the radio API to communicate
with the live Mobitex network.
Note
There are some differences between the RIM Wireless Handheld
device and the simulator. The simulator responds to certain
debugging calls, sending the output to the Visual Studio output pane;
those calls have no effect on the RIM Wireless Handheld.
20 Tools guide — RIM 950 Wireless Handheld simulator
Running the simulator
There are two RIM Wireless Handheld simulator programs:
SIMULATOR.EXE AND OSLOADER.EXE.
They are launched in different ways
SIMULATOR.EXE provides a Windows interface to the
•
OSLOADER.EXE program and is normally launched using
shortcuts.
OSLOADER.EXE provides a command-line interface and is
•
normally launched using the command line.
For both simulators, you must load applications. Each DLL loa ded into
the simulator environment is a separate application; which DLLs you
load depends upon which RIM 950 Wireless Handheld application you
want to simulate.
Run the simulator using shortcuts
The install process creates two icons in the RIM 950 Wireless Handheld
1.7 SDK program group – an SDK readme.txt icon and a Simulator icon.
Double-click the Simulator icon to start the simulator. The Simulator
window appears:
The Simulator Window
Developer’s Guide – RIM 950 Wireless Handheld™
Tools guide — RIM 950 Wireless Handheld simulator 21
1. First, select a simulation platform from the Options menu. The
Configure… item in the Options menu allows you to add new
simulation platforms or ve rsions if you have them available a s RIM
OS DLLs. The Configure… item also allows you to specify the path to
OSLOADER.EXE. Other than selecting a simulation platform, the
defaults should be appropriate.
2. When you are ready to start the simu lation, choose Start Simulation
from the Control menu. You will be prompted for command line
switches for the OSLOADER.EXE program; see below for descriptions
of the possible switches.
3. After specifying the switch es (if any), you will be prompted to load
Application DLLs via a file selector w indow. You can load more tha n
one file at a time by clicking Open after each file or by selecting more
than one file in the window and clicking Open.
4. Once all files have been loaded, click Cancel in this window; the
RIM Wireless Handheld simula tor will start.
Running the simulator from the command line
You can also start the RIM Wire less Handheld simula tor by running the
executable OSLOADER.EXE. (This executable is located in the SD K install
directory that you selected during the setup process.) The first parameter
to OSLOADER.EXE must be an
OS DLL, such as OSPGRMB.DLL.
You can optionally load applications automatically by naming them after
the OS DLL on the command line, if the directory (or directories)
containing the DLLs is specified in the Windows
PATH. For example:
OSLOADER.EXE [Switches] OsPgrMb.dll [applications]
If you don’t specify applications, you will be prompted with a file
selector window. You can load more than one file a t a time by clicking
Open after each file or by selecting more than one file in the wind ow a nd
clicking Open.
Once all files are loaded, click Cancel in thi s window; the simulator will
start.
Place the DLLs in your
PATH or place them in the same directory and use
that directory as the current directory when you execute the command.
Developer’s Guide – RIM 950 Wireless Handheld™
22 Tools guide — RIM 950 Wireless Handheld simulator
The following table summarizes the command line switches and
arguments, in alphabetical order; these are explained in greater detail
later in this section.
Switches Description
/An
Use
n sectors of flash me mory for OS and
application storage.
/Dn
Use
n sectors of flash memory for file
system data storage.
/E
/Fn
/Pf
/Ps
Erase flash allocation log.
Simulate
n kilobytes of flash memory.
Force prompt for more applications.
Always suppress prompt for more
applications.
/Rn
/RDIR=directory
/RSIM=addr
/Sn
Use serial port
Store messages in
Use
addr as the simulator's address.
n for RAP modem.
directory.
Use Windows serial port n in place of the
wireless handheld's physic al serial port.
/T[flags]
Set or suppress traps
Any argument that does not begin with / is taken as a file name, the
name of an application to be loaded.
Loading applications
Each DLL is a different application. The DLLs you load depend on which
RIM Wireless Handheld applications you want to simulate.
For example, a simple application t hat uses only the functiona lity of the
base API functions wi ll not de pend on other DLLs a nd can be l oaded by
itself. However, applications built with the User Inter face Engine require
loading the UI32.DLL file along with the UI-enabled applic ation.
There is a restriction: Each DLL loaded in a group mu st require only the
DLLs selected before or listed in the current set. Therefore, the
application with the most dependencies should be added last. This
Developer’s Guide – RIM 950 Wireless Handheld™
Tools guide — RIM 950 Wireless Handheld simulator 23
restriction does not hold if the required DLLs are in your PATH or the
working directory that was used to star t the simulator.
To simulate an application running wit h the fu ll R IM Wireless Hand held
messaging application, load a ll of the DLLs in the directory. This should
be the following DLLs:
• ADDRESS.DLL
• AUTOTEXT.DLL
• COREAPI.DLL
• CRYPTOBLOCK.DLL
• DATABASE.DLL
• MESSAGE.DLL
• RIBBON.DLL
• TRANSPORT_MDP.DLL
• UI32.DLL
Please refer to the specific API documentation for each of these DLLs for
more information.
Note
Note that SDKRADIO.DLL is not a standard application DLL for the
simulator; it is used when you want to use your RIM Wireless
Handheld as a modem (see Using the RIM Wireless Handheld as the
modem on page 30). Normally you will not load SDKRADIO.DLL into
the simulator.
Using the simulator
When you run the simulator, a window featuring a picture of the
wireless handheld appe ars on your screen. This main windo w contains
pictures of a keypad, a trackwheel, and a LCD. You can operate the
keypad and trackwheel from Windows, and the LCD will show you
what would be displayed on the actual wireless handheld.
Developer’s Guide – RIM 950 Wireless Handheld™
24 Tools guide — RIM 950 Wireless Handheld simulator
LCD Trackwheel
Keypad
The RIM Wireless Handheld simulator
Keypad
You can operate all keys on the simulator window’s keypad by clicking
them with the mouse. In addition, you can operate the keys on the RIM
Wireless Handheld keypad by using the corre sponding keys on the PC
keyboard.
ALT key
TheRIM Wireless Handheld simulator
ALT key
Alternate symbols for the keys (in red) can be accessed using the
However, due to the special function assigned to the
Developer’s Guide – RIM 950 Wireless Handheld™
BACKSPACE
key
SHIFT key
ALT key.
ALT key by
Loading...