Page 3 - Contents
Contents 1. Introduction............................................................................................ 5 About the SDK ...................................................................................... 5 About the network ...............................................................
Page 5 - Introduction; About the SDK
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), support...
Page 6 - About the network; About Research In Motion
6 Introduction — About the network Developer’s Guide – RIM 950 Wireless Handheld™ About the network The RIM Wireless Handheld operates over the BellSouth Intelligent Wireless Network SM in the United States and the Rogers™ AT&T® wireless data network in Canada. Both networks offer broad coverage...
Page 9 - Installing the SDK; To install the SDK
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 ...
Page 15 - Release notes; Recompiling your applications; Message
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 b...
Page 16 - OS; New simulator; Ribbon changes
16 Release notes — OS Developer’s Guide – RIM 950 Wireless Handheld™ 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 availab...
Page 17 - Address Book changes
Release notes — Address Book changes 17 Developer’s Guide – RIM 950 Wireless Handheld™ 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 r...
Page 19 - Tools guide
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 pro...
Page 20 - Running the simulator
20 Tools guide — RIM 950 Wireless Handheld simulator Developer’s Guide – RIM 950 Wireless Handheld™ 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 O...
Page 23 - Using the simulator
Tools guide — RIM 950 Wireless Handheld simulator 23 Developer’s Guide – RIM 950 Wireless Handheld™ 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 me...
Page 27 - Simulating serial I/O
Tools guide — RIM 950 Wireless Handheld simulator 27 Developer’s Guide – RIM 950 Wireless Handheld™ 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 por...
Page 29 - Flash allocation
Tools guide — RIM 950 Wireless Handheld simulator 29 Developer’s Guide – RIM 950 Wireless Handheld™ 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 alloc...
Page 31 - Modem simulation using the file system
Tools guide — RIM 950 Wireless Handheld simulator 31 Developer’s Guide – RIM 950 Wireless Handheld™ 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 Wireles...
Page 34 - Simulator command line options
34 Tools guide — RIM 950 Wireless Handheld simulator Developer’s Guide – RIM 950 Wireless Handheld™ 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 d...
Page 37 - Debugging hints; Program loader
Tools guide — Program loader 37 Developer’s Guide – RIM 950 Wireless Handheld™ 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...
Page 38 - Program loader command line options
38 Tools guide — Program loader Developer’s Guide – RIM 950 Wireless Handheld™ 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 templa...
Page 45 - Troubleshooting
Tools guide — Program loader 45 Developer’s Guide – RIM 950 Wireless Handheld™ 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 follo...
Page 47 - DLLUtil; Conversion utilities; BITMAP
Tools guide — DLLUtil 47 Developer’s Guide – RIM 950 Wireless Handheld™ 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...
Page 48 - BMP2DEF; LCDFONTS
48 Tools guide — Conversion utilities Developer’s Guide – RIM 950 Wireless Handheld™ 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 existin...
Page 49 - An overview of the
An overview of the system — Conversion utilities 49 Developer’s Guide – RIM 950 Wireless Handheld™ 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’...
Page 50 - RIM co-operative scheduler
50 An overview of the system — RIM co-operative scheduler Developer’s Guide – RIM 950 Wireless Handheld™ 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 functiona...
Page 51 - MESSAGE concept; Memory use
An overview of the system — MESSAGE concept 51 Developer’s Guide – RIM 950 Wireless Handheld™ 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...
Page 52 - User interface; API overview
52 An overview of the system — User interface Developer’s Guide – RIM 950 Wireless Handheld™ 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 inf...
Page 55 - Building applications; Coding an application; The PagerMain entry-point function
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 ...
Page 56 - Registering the application
56 Building applications — Coding an application Developer’s Guide – RIM 950 Wireless Handheld™ • 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 the...
Page 57 - Entering the message loop
Building applications — Coding an application 57 Developer’s Guide – RIM 950 Wireless Handheld™ Here is some example PagerMain() code for an application that makes use of the database: #include <Pager.h>#include <Ribbon.h> //Definition of bitmap registered with ribbon#include <bitSamp...
Page 58 - Becoming the foreground task
58 Building applications — Coding an application Developer’s Guide – RIM 950 Wireless Handheld™ #include "Pager.h" void PagerMain( void ){ // initialization as in previous section...// Message loopMESSAGE msg; // perform initialization for (;;) { RimGetMessage( &msg );// respond to event...
Page 59 - Using the Ribbon API; Handling user input
Building applications — Coding an application 59 Developer’s Guide – RIM 950 Wireless Handheld™ 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 fo...
Page 60 - PagerMain function example
60 Building applications — Coding an application Developer’s Guide – RIM 950 Wireless Handheld™ 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 =...
Page 62 - To set up a basic program structure
62 Building applications — Coding an application Developer’s Guide – RIM 950 Wireless Handheld™ 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 event...
Page 63 - Example programs
Building applications — Compiling RIM Wireless Handheld applications 63 Developer’s Guide – RIM 950 Wireless Handheld™ MESSAGE s 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 th...
Page 64 - Installing the application; Registry keys for installation
64 Building applications — Installing the application Developer’s Guide – RIM 950 Wireless Handheld™ 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 ...
Page 66 - ALI file format
66 Building applications — Installing the application Developer’s Guide – RIM 950 Wireless Handheld™ 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 tha...
Page 67 - Application loader notes
Building applications — Installing the application 67 Developer’s Guide – RIM 950 Wireless Handheld™ 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 s...
Page 69 - Appendix
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 lis...
Page 70 - Functions that are compatible; Functions that are not compatible
70 Appendix — C library compatibility for RIM Wireless Handheld applications Developer’s Guide – RIM 950 Wireless Handheld™ 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 ...
Page 75 - Index
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.EXE utility...
