Developer’s Guide RIM 950 Wireless Handheld™ Version 1.
RIM 950 Wireless Handheld — SDK User's Guide, Version 1.7 Last revised 9/18/00 Part Number: PDF-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 with software O/S version 2.0 and applications version 1.7.
Contents 1. Introduction............................................................................................ 5 About the SDK ...................................................................................... 5 About the network ............................................................................... 6 About Research In Motion .................................................................. 6 About this guide ...............................................................................
1. Introduction The RIM 950 Wireless Handheld Software Developer’s Kit (SDK) includes all the tools needed to begin 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.
Introduction — About the network About the network The RIM Wireless Handheld operates over the BellSouth Intelligent Wireless NetworkSM in the United States and the Rogers™ AT&T® wireless data network in Canada. Both networks offer broad coverage, nationwide roaming, fast messaging, and 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.
Introduction — About this guide 7 Some information is set apart typographically in the following ways: Note Tip Notes provide additional information to help complete a task. Tips offer an alternative method of performing an action 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, windows, etc. will appear in bold text.
2. Installing the SDK In order to run the RIM 950 Wireless Handheld Software Developer’s Kit, you need a PC capable of running Microsoft Developer Studio 5.0 (or later). This chapter describes the process of installing the RIM 950 Wireless Handheld SDK and configuring Microsoft Developer Studio 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.
Installing the SDK — To install the SDK Note 3. Please read the license agreement carefully. Proceeding with the installation indicates that you agree with the conditions in the license agreement. When the Choose Destination Location window opens, a default directory will be displayed. To change this directory, click the Browse button, and the Choose Directory window will open. Select the path, drive, and directory that you would like for your destination.
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.
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.
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.
3. Release notes This section describes some of the changes 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 attempting to build applications for RIM 950 Wireless Handheld 1.7. WARNING The 1.7 environment is not binary compatible with 1.6. You must recompile your code before running it on a 1.7 system. RIM 950 Wireless Handheld 1.
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 LcdGetConfig call (from ). For quick recompiling, the header PRE20.
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 instead of one of the characters of string.
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 (BMP2DEF.EXE, BITMAP.EXE, and LCDFONT.EXE) bitmaps • A utility (DLLUTIL.
Tools guide — RIM 950 Wireless Handheld simulator Running the simulator There are two RIM Wireless Handheld SIMULATOR.EXE AND OSLOADER.EXE. simulator programs: 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.
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 versions if you have them available as 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 simulation, choose Start Simulation from the Control menu.
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 memory for OS and application storage. /Dn Use n sectors of flash memory for file system data storage. /E Erase flash allocation log. /Fn Simulate n kilobytes of flash memory. /Pf Force prompt for more applications.
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 start the simulator. To simulate an application running with the full RIM Wireless Handheld messaging application, load all 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.
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 corresponding keys on the PC keyboard. BACKSPACE key ALT key SHIFT key TheRIM Wireless Handheld simulator ALT key Alternate symbols for the keys (in red) can be accessed using the ALT key.
Tools guide — RIM 950 Wireless Handheld simulator 25 Windows, activate the wireless handheld's ALT key by pushing the CTRL key on your PC. The current state of the Alt key is displayed on the upper right corner of the simulator. A reverse-video ‘A’ will be displayed when the ALT key is in effect. SHIFT key Press and release the CAP or SHIFT key to capitalize the next key you press. When this key is pressed, an up arrow will appear on the top right corner of the screen.
Tools guide — RIM 950 Wireless Handheld simulator Using the keyboard The left and right arrow buttons on the PC keyboard simulate the clicking of the trackwheel while the up and down arrow buttons simulate the rolling. Using the mouse To perform the roller action using the mouse, click the trackwheel with the left mouse button and drag vertically. To click the trackwheel, depress the right mouse button. This action allows the trackwheel to be rolled and clicked independently.
Tools guide — RIM 950 Wireless Handheld simulator 27 The Simulation menu In the Radio Simulator Control panel dialog box, you can simulate various coverage conditions. Simulating serial I/O The simulator has the ability to use one of the PC’s serial ports as the RIM Wireless Handheld’s serial port. This option must be enabled via the /S command line option when you start the simulator.
Tools guide — RIM 950 Wireless Handheld simulator When the RIM Wireless Handheld simulator starts, it determines the simulated flash size. The size can be specified using the /F command line option and the default size is 2048 KB. The simulator now checks to see if there is a file named OSXXXYY.DMP (where XXXYY corresponds to the current simulation platform) in the working directory.
Tools guide — RIM 950 Wireless Handheld simulator 29 Flash allocation The available flash memory (either simulated or real) is divided into four areas: • File system data area • Unused area • OS and application code area • Fixed use area Areas are allocated by writing an entry to a Flash allocation log, which is a special data structure stored within the fixed use area. The log may be completely erased using the /E command line option.
Tools guide — RIM 950 Wireless Handheld simulator When using a physical modem with the simulator, you cannot simulate different coverage situations in software; you are limited by what the modem is actually experiencing. To simulate different coverage situations, change the position of the antenna or obstruct the antenna's coverage.
Tools guide — RIM 950 Wireless Handheld simulator 31 Battery capacity, as well as other factors cause the rate of packet delivery to be cut back after sending large amounts of data. In addition, when sending large amounts of traffic with the RIM Wireless Handheld, its battery life may be considerably shortened. During transmission of data packets, for example, the RIM Wireless Handheld requires three times more power than normal average power consumption.
Tools guide — RIM 950 Wireless Handheld simulator /RSIM=
This option sets the address to simulate. /RDIR= This option sets the directory to use for the simulation. The default directory is the current directory. Radio simulators must point at the same directory in order to be able to communicate with each other. Simulating email Sending and receiving email through the MESSAGE.Tools guide — RIM 950 Wireless Handheld simulator 33 • Guidelines for writing a host-side application to simulate the network This section describes the network simulation in general terms. The control panel consists of two parts: reception and transmission. The Reception section of the dialog box allows you to set whether or not the modem is in coverage. The Transmission section allows you to set the success rate for packet transmission.
Tools guide — RIM 950 Wireless Handheld simulator State Description Checking... The radio is checking for data on a 10 second interval, or the Check now button was pressed. Checking for 10 sec. The radio is checking continuously because of a recent data packet sent or received. Out of coverage The modem is out of coverage. Transmission section In the Transmission section, you may choose how frequently data packets are transmitted successfully.
Tools guide — RIM 950 Wireless Handheld simulator 35 /Rn Tell the RIM Wireless Handheld simulator to use serial port n for a RAP modem. The RAP modem is used in place of the physical RF hardware in the simulation environment. If this argument is omitted, no serial port is used, and simulated radio communications will not be possible.
Tools guide — RIM 950 Wireless Handheld simulator /D15 /An Simulate n sectors simulated flash memory (in 64 KB sectors) to be used for OS and application code storage. If this option is omitted, the previous amount is preserved, unless /E is simultaneously specified. If /E is specified, a default amount is used. This can simulate the result of a PROGRAMMER ALLOC command. Example: /A16 /T[flags] Modify the stale pointer trapping behaviour of the RIM Wireless Handheld simulator.
Tools guide — Program loader 37 In this example, APP2.DLL is assumed to reside in the working directory C:\dev\app1.dll app2.dll. Debugging hints Some tips for debugging applications using the simulator (and the RIM Wireless Handheld itself). • When the machine fails and requests a reset, you can often get additional information by typing dbug. This displays the contents of different registers. • You may be able to get additional information on a reset request by typing info.
Tools guide — Program loader Program loader command line options The PROGRAMMER.EXE utility requires a set of command line options to denote serial port configuration, the action required, and what files are to be manipulated. The command line template is: PROGRAMMER [[-Pport] [-Sspeed] [-Wpassword] [command] If no command action is given, PROGRAMMER.EXE displays help information. Universal command line options The -P, -S and –W options may be given with any action. -Pn Use serial port n.
Tools guide — Program loader 39 Command Description BATCH filename Run PROGRAMMER.EXE stored in a file VER List applications currently on the Wireless Handheld, including version information MAP [-F] [-R] Display detailed flash and RAM maps LOADFS Load file system data from a .DMP file onto RIM Wireless Handheld SAVEFS Save file system data from RIM Wireless Handheld into a .
Tools guide — Program loader API, RimCatastrophicAPIFailure(). In all cases, other unresolved links fail; only unresolved OS calls can be mapped. -D specifies that unresolved OS calls should not be mapped to RimCatastrophicAPIFailure(). are one or more files or groups of files to be loaded onto the RIM Wireless Handheld. Individual files are specified alone. Groups of files are enclosed in parentheses, brackets, or braces.
Tools guide — Program loader 41 PROGRAMMER LOAD PAGER950.BIN UI32.dll ( Address.dll AutoText.dll Message.dll Options.dll Transport_RTP.dll ) The following command will load a new calculator application, grouping it with the other applications: PROGRAMMER LOAD -G Calculator.dll ERASE command ERASE –A ERASE Where -A specifies that all applications and the application environment are to be deleted. are the names of specific applications to be deleted.
Tools guide — Program loader Where -S specifies a short listing of only the application names. Description The DIR command generates a listing of the applications currently loaded on a RIM Wireless Handheld. Unless the -S option is specified, this listing includes the names of the applications and the amount of flash and RAM occupied by the applications. The applications are grouped as they are grouped on the RIM Wireless Handheld.
Tools guide — Program loader 43 Description The BATCH command allows multiple commands to be placed in a file and executed with a single, short command. This command is useful when repeatedly performing the same load process, and for overcoming the fixed limit imposed on command lines. The batch file may contain one or more of the LOAD, ERASE, DIR, or BATCH commands. The results are committed to the RIM Wireless Handheld only if all commands are successfully completed.
Tools guide — Program loader Example To get help on the LOAD command, type: PROGRAMMER HELP LOAD To get help on errors, type: PROGRAMMER HELP ERRORS To get a main help page, type: PROGRAMMER HELP HELP ALLOC command ALLOC [-E] [-D ] [-A ] Where -E specifies the File Allocation Sector to be erased before writing an entry. -D specifies the new size of the file (or data) area in flash sectors; the minimum size is 1.
Tools guide — Program loader 45 When the File Area size is decreased, at least one blank sector must remain within the area. Back up and pack your data before issuing the ALLOC command. Troubleshooting Most error messages are self-explanatory. The following errors deserve more discussion. Error: Unable to connect to device An error occurred trying to initiate communications with the RIM Wireless Handheld. Make sure that it is connected to the computer properly.
Tools guide — Program loader Error: Not all imports resolved An application is requesting imports from another application that cannot be exported by the other application. Ensure that you are loading all applications that provide the exports that you need.
Tools guide — DLLUtil 47 DLLUtil The DLLUTIL.EXE utility provides information about DLLs as they will be when loaded onto the RIM Wireless Handheld, similar to the output of PROGRAMMER DIR and PROGRAMMER VER. There are two forms of the command: DLLUTIL SIZE [-R] files DLLUTIL VER files The files argument is a list of DLLs and/or OS files, and can contain wildcards (* and ?). In the first form (SIZE), the utility displays a dump of flash memory, RAM, and thunk resources.
Tools guide — Conversion utilities The syntax is: BITMAP definition header The definition file format is described in the OS API Developer’s Guide, under “Creating bitmaps.” BMP2DEF The BMP2DEF.EXE executable creates a definition file from an existing bitmap (.BMP). The definition file can be turned into a RIM Wireless Handheld bitmap header file using BITMAP.EXE. The syntax is: BMP2DEF bitmap definition LCDFONTS The LCDFONTS.EXE executable creates a font header file from a definition file.
An overview of the system — Conversion utilities 49 5. An overview of the system This section describes parts of the RIM Wireless Handheld’s system for developers, concentrating on the operating system. When developing for the RIM Wireless Handheld, it’s important to realize that the RIM Wireless Handheld has its own operating system.
An overview of the system — RIM co-operative scheduler RIM co-operative scheduler The RIM Wireless Handheld’s operating system (OS) is designed using a co-operative multitasking model. For more information on the operating system and the OS functional specifications, see the RIM 950 Wireless Handheld Operating System API Developer’s Guide. Tasks and threads A normal application is developed as a task or thread.
An overview of the system — MESSAGE concept 51 For more information on the MESSAGE posting process, see “MESSAGE concept” below as well as the RIM 950 Wireless Handheld Operating System API Developer’s Guide. MESSAGE concept The Operating System allows for inter-task communication through posting and receiving MESSAGES.
An overview of the system — User interface User interface The user can acquire data from the application through the RIM Wireless Handheld’s LCD. In order to use the LCD, the application must make a request to become the foreground task. For more information on making an application a foreground task, see the RIM 950 Wireless Handheld OS API Developer’s Guide.
An overview of the system — API overview 53 The following APIs are provided. All but the most trivial applications will need to make use of the APIs described in the OS API Developer’s guide and the User Interface Developer’s Guide.
An overview of the system — API overview API Description Serial communications API access and configure serial port on the RIM Wireless Handheld OS API System services API Access to thread handling, messaging, and task switching, memory allocation, timers, and the system clock OS API User Interface API Calls for high-level display of information and handling input, such as creating screens, menus, and dialogs User Interface API Developer’s Guide – RIM 950 Wireless Handheld™ Documented in
6. Building applications This chapter describes the basics of writing an application for the RIM Wireless Handheld. Coding an application This section briefly outlines the required components of an application on the wireless handheld. The basic program structure essentially consists of an infinite loop that receives messages from the OS, and code to process those messages.
Building applications — Coding an application • Begin the PagerMain() function with the construction of any permanent objects required by the application. You should avoid accessing objects in other DLLs because until the PagerMain() functions in these DLLs have had a chance to run, the construction of these objects may not have occurred. • After this local initialization phase, call RimTaskYield() to allow the PagerMain() functions of other tasks to run.
Building applications — Coding an application 57 Here is some example PagerMain() code for an application that makes use of the database: #include #include //Definition of bitmap registered with ribbon #include
Building applications — Coding an application #include "Pager.h" void PagerMain( void ) { // initialization as in previous section . . . // Message loop MESSAGE msg; // perform initialization for (;;) { RimGetMessage( &msg ); // respond to events switch( msg.Device ) { case DEVICE_SYSTEM: // handle SYSTEM messages break; case DEVICE_TIMER: // handle TIMER messages break; case DEVICE_KEYPAD: // handle KEYPAD messages break; } } } Note Applications are not required to be strict state machines.
Building applications — Coding an application 59 application from the RIBBON device, with the event set to RIBBON_GRAB_FOREGROUND. If we get a RIBBON message, we call RimGetCurrentTaskID()for the current task handle. We bring the application to the foreground using RimRequestForeground(). if( msg.Device == DEVICE_RIBBON ) { if( msg.
Building applications — Coding an application If the user presses a key, the OS sends a MESSAGE to the application from the KEYPAD device. If we get a KEYPAD message, we pass the MESSAGE to the UI Engine, which returns a result code: if( msg.Device == DEVICE_KEYPAD ) { // Let the UI process the message result = m_ui_engine.HandleInput( message ); //Process UI Engine result } MESSAGEs resulting from a key being pressed on the keyboard are sent only to the foreground task.
Building applications — Coding an application 61 static void set_task_pid( void ) { PID pid; pid.Name = "Example Application"; pid.EnableForeground = true; pid.
Building applications — Coding an application To set up a basic program structure 1. Implement a message loop: Any application running on the device will need to handle messages from the OS that will notify the application of key presses, radio events, etc. The most efficient process is to do this is to use a message loop. The basic structure of the message loop is: for ( ; ; ) { // waits until a message is given // to the application by the OS RimGetMessage (&message); // processes message } 2.
Building applications — Compiling RIM Wireless Handheld applications 63 MESSAGEs resulting from a key being pressed on the keyboard are sent only to the foreground task. 4. If the UI Engine returns CLICKED, the application should display a menu. If the UI Engine returns UNHANDLED, the user may have pressed the BACKSPACE key, in which case we want to return to the main screen (RIBBON).
Building applications — Installing the application You should now be able to compile and debug your application using the RIM 950 Wireless Handheld SDK. Installing the application There are two utilities available to install the application on a RIM Wireless Handheld, the PROGRAMMER.EXE utility and the Desktop Manager software shipped with every RIM Wireless Handheld. Installing the application with PROGRAMMER.EXE has been covered (see page 39 for a description of the LOAD command action).
Building applications — Installing the application 65 Value Name Value Type Meaning Corresponds to the tag of the ALI file. Flags REG_DWORD See below. Generally 0x04 is the best value. Inferred from the optional tag of the ALI files. Path REG_SZ Fully qualified path to the actual app DLL. In ALI files, it is inferred from the pathname to the ALI file by the Application Loader. REG_DWORD Indicates version information associated with the app DLL.
Building applications — Installing the application ALI file format The ALI file is read by the Application Loader, which then sets appropriate registry keys. From that point on, your application is known to the loader. The ALI file is a text file that contains three lines.
Building applications — Installing the application 67 Application loader notes You should be aware of the following when packaging applications for the Application Loader for the RIM Wireless Handheld. Each application requires an ALI file or registry settings The ALI file contains information used by the loader to add an application to its list of available applications. The ALI file must have the same basename as the DLL it describes and it must be in the same directory as the DLL it describes.
Appendix C library compatibility for RIM Wireless Handheld applications Only some functions within the compiler C library are safe to call from the RIM Wireless Handheld environment. The following table summarizes the information. There are equivalent functions for the groups marked “No”—see the list afterwards.
Appendix — C library compatibility for RIM Wireless Handheld applications Functions that are compatible Argument access macros This set of functions is compatible with the RIM Wireless Handheld environment. This includes the macros va_arg, va_start, and va_end. Buffer manipulation functions This set of functions is compatible with the RIM Wireless Handheld environment. This includes memccpy, memchr, memcmp, memcpy, _memicmp, memmove, memset, and _swap.
Appendix — C library compatibility for RIM Wireless Handheld applications 71 debugging messages can be output to the debug output window when running MS Developer Studio by calling RimDebugPrintf. Directory control functions The RIM Wireless Handheld file system is different from those used on desktop systems. As a result, the directory control functions are not supported by the RIM Wireless Handheld.
Appendix — C library compatibility for RIM Wireless Handheld applications Handheld applications run in a protected environment, calling these functions will cause a protection fault at run time. Locale dependent functions The RIM Wireless Handheld environment does not support locales, multibyte characters, or wide characters. However, it is useful to have many of the locale dependent functions compatible. These functions were in the C library before the setlocale function.
Appendix — C library compatibility for RIM Wireless Handheld applications 73 operating system allocates application stacks, Windows functions are not safe to call even when running on the simulator. Time functions The RIM Wireless Handheld operating system represents time differently from desktop systems. As a result, time functions are not compatible with the RIM Wireless Handheld environment.
Index about this guide, 6–7 ALI file, 64 alt key, simulating, 24–25 API generic application, See generic application overview, 52–54 application loader, 64 registry keys, 64 applications compiling RIM Wireless Handheld, 63–67 restarting, 50 backlighting, 25 BITMAP.EXE utility, 47 BMP2DEF.
Index use, 51 message loops and ribbon, 59 definition, 62 entering the message loop, 57–58 MESSAGEs concept, 51 mode pager, 25 pc, 25 modem, 35 radio simulation control panel dialog box, 32 simulating using a physical modem, 29 simulating using the file system, 31 simulation with RAP modem, 30 using file system command line options, 31 packet transmission, 33, 34 radio simulation control panel dialog box, 32 using the pager as a modem, 30 MS Developer Studio configuring, 12–13 description, 11 MS Intell
Index 77 RIM Wireless Handheld simulator, See simulator running the simulator, 19–20 SDK components, 6–7 description, 5 installing, 9–13 multitasking, 5 processor, 5 serial input/output, 27 serial port, 34 shift key simulator, 25 shortcuts for starting the simulator, 20–23 simulating battery environment, 26–27 holster environment, 26–27 serial input/output, 27 simulation menu battery, 26–27 holster, 26–27 simulator, 16, 19–37 alt key, 24–25 backlighting, 25 command line options, 27–37 command line options
