Blackberry RIM 950 manual

Developer’s Guide RIM 950 Wireless Handheld™ Version 1.7 SDK User’s Guide[...]

RIM 950 W ireless Handheld — SDK User's G uide, Vers ion 1.7 Last revised 9/18/00 Par t N umber: PDF-03 037 -001 © 1997-2 000, RESEARCH I N MOTI O N LIMITED RIM, Resea rch In Motion, the RIM logo, RI M 950 Wireless Handhel d, RIM 957 Wireles s Hand held, RI M 950, R IM 957 and RIM Wire less Han dhe ld are trad emark s of Rese arch In M otio[...]

Contents 1. Introduction............................................................................................ 5 About the SDK ...................................................................................... 5 About the network ............................................................................... 6 About Research In Mo tion ..[...]

[...]

1. Introduction The RIM 950 Wi reless Handh eld Software Develo per’s Kit (SDK) includes all the t ools need ed to begin applicati on de velopment quic kly. The SDK provides an extremely powerful development en viro nment that u tilizes Micros oft Developer Studio 5.0 or later (Vi sual C++ 5.0 or later), supporting Wi ndows 9 5 and Window s NT. T[...]

6 Introduction — A bout the netw ork Developer ’s Guid e – RI M 950 W ireless Handheld™ About the network The RIM Wireless Handheld operates over the BellSouth Intelligent Wireless Network SM in t he United States and the R ogers™ AT&T® wireless data net work in Ca nada. B oth netw orks off er broa d covera ge, nationwide roa ming, f[...]

Introduction — A bout this g uide 7 Developer’ s Guide – RIM 950 Wireless Handheld ™ Some informati on is set apa rt typograp hica lly in the fol lowing wa ys: Note Notes prov ide additional informati on to help com plete a tas k. Tip Tips offer an alternative method of p erforming an action WARNING Warnings fo llow any proce dure or paragr[...]

[...]

2. Installing the SDK In order to run t he RIM 950 Wireless Handh eld Software Developer’s Kit, you need a PC capa ble of r unn ing Micr osoft Deve l oper Stud io 5 .0 (or later). This cha pter descri bes the proce ss of insta lling the RIM 950 Wireless Handheld SDK a nd conf iguring M icrosoft Developer Stud io 5.0 (or later) to work with the SD[...]

10 Installing t he SDK — To insta ll the SDK Developer ’s Guid e – RI M 950 W ireless Handheld™ Note Please read t he licen se agreement carefully. Pr oceeding with the install ation indicate s that you agree w ith the condit ions in the lic ense agreement. 3. When the Choose Destination Location window opens, a de fault directory will be d[...]

Installing t he SDK — To confi gure Microsof t Developer Stu dio 11 Developer’ s Guide – RIM 950 Wireless Handheld ™ 5. Type in a folder name in whic h the setup items wi ll be stored. The default folder n ame is Research In Motion . Alternatively, you may select a folder from the Existing Folders section. 6. At the end o f the installat io[...]

12 Installing t he SDK — To confi gure Microsof t Developer Studi o Developer ’s Guid e – RI M 950 W ireless Handheld™ Follow these step s to configure the Micro soft Visual C++ 5.0 (or later) environm ent for building RIM 950 Wireless Handheld applicat ions. 1. Start the Mi crosoft Developer Studio and select File > N ew > Proj ect t[...]

Installing t he SDK — To confi gure Microsof t Developer Stu dio 13 Developer’ s Guide – RIM 950 Wireless Handheld ™ subdirectories include an d inc lude in ter nal of the RIM 950 Wireless Handheld S DK insta lla tion directory. 5. Ch ange the Category to Code Generation . • Set the Struct M em ber Alignm ent to 2 bytes. T his wil l m[...]

[...]

3. Release notes This section describe s some of the changes between ve rsions 1.6 a nd 1.7 of the RIM 950 W ireless Handheld SDK. I t describes changes y ou mus t make to your existi ng code base bef ore attempting to build applications for RIM 950 W ireless Han d held 1.7. WARNING T he 1.7 environ ment is not binary compati ble with 1.6. You must[...]

16 Release notes — OS Developer ’s Guid e – RI M 950 W ireless Handheld™ See the Message API Devel oper’s Guide for more informatio n. OS Version 2 .0 of the OS removes cer tain con stants. The consta nts LCD_WI DTH , LCD_HE IGHT , LCD_ HEIGHT _BYT E , LCD_DISP LAY_SI ZE , and LCD_DI SPLA Y_SIZE _BYT E that were available but deprecat ed [...]

Release notes — Address Bo ok changes 17 Developer’ s Guide – RIM 950 Wireless Handheld ™ The new vers ion of the call is d efined a s: void RibbonSetApplicationString( const char * const appName, const char * const string, int priority, const BitMap * const bitMapPtr ); The bitM apPt r parameter i s new, and refers to an o ptional im age t[...]

[...]

4. Tools guide This sect ion provide s infor mation o n how to ma ke use of the t ools provided in the SDK. These tools are provided: • RIM Wireless Ha ndheld simulator program ( SIMULATOR.EXE / OSLOADER.EXE ), used to tes t progr ams on a PC withou t loadi ng them onto a wirele ss hand he ld • Program Loa der progra m ( PROGRAMMER.EXE ) , u s [...]

20 Tools guide — RIM 950 Wireless Ha ndheld simula tor Developer ’s Guid e – RI M 950 W ireless Handheld™ Running t he simulator There are two RIM Wireless Handheld si mulator programs: SIMULATOR.EXE AND OSLOADER.EXE . They are launched in different w ays • SIMULA TOR. EXE provide s a Window s interfa ce to the OSLOADER.EXE program and is[...]

Tools guide — RIM 950 Wireless Ha ndheld simula tor 21 Developer’ s Guide – RIM 950 Wireless Handheld ™ 1. First, select a simulati on platform fr om the Options menu. The Configure … item in the Opti ons m e n u a l l o w s y o u t o a d d n e w simulatio n platforms or ve rsions if yo u have them a vaila ble as RIM OS DLLs. The Configur[...]

22 Tools guide — RIM 950 Wireless Ha ndheld simula tor Developer ’s Guid e – RI M 950 W ireless Handheld™ The following table summarizes the com mand line switches and arguments, in a lphabetical order; these are explained in greater d etail later in this section. Switches Description /A n Use n sect ors of flash me mory for OS and applicat[...]

Tools guide — RIM 950 Wireless Ha ndheld simula tor 23 Developer’ s Guide – RIM 950 Wireless Handheld ™ restriction does n ot hold if the req uired DLLs are in your PA TH or the working directory t hat was used to sta rt the simula tor. To simulate a n appl icatio n runni ng wit h the fu ll RIM Wireless Hand held messaging applica tion, loa[...]

24 Tools guide — RIM 950 Wireless Ha ndheld simula tor Developer ’s Guid e – RI M 950 W ireless Handheld™ The RIM Wireless Han dheld simulat or Keypad You can o perate all keys o n the si mulator wind ow’s keypad by clicki ng them with the mouse. In addition, you can operate the keys on the RIM Wireless Handheld keypad by usin g the corre[...]

Tools guide — RIM 950 Wireless Ha ndheld simula tor 25 Developer’ s Guide – RIM 950 Wireless Handheld ™ Windows, a ctiva te the wir eless handheld 's ALT key by pushi ng the CTRL key on your PC . The current state of t he Alt key is displayed on the up per right corner of the simulat o r. A reverse-vi deo ‘A’ will be displayed when[...]

26 Tools guide — RIM 950 Wireless Ha ndheld simula tor Developer ’s Guid e – RI M 950 W ireless Handheld™ Using the keyboard The left and right arro w buttons on the PC keyb oard simula te the clicking of the trac kwheel while the up and d own arrow buttons simulate the rol ling. Using the mouse To perform the roller action using the mouse,[...]

Tools guide — RIM 950 Wireless Ha ndheld simula tor 27 Developer’ s Guide – RIM 950 Wireless Handheld ™ The Simulation men u In the Rad io Sim ulator Contr ol panel dialog b ox, you can sim ulate various covera ge condit ions. Simulating seri al I/O The simulator has the ability to use one of the PC’s serial ports as the RIM Wirele ss Ha [...]

28 Tools guide — RIM 950 Wireless Ha ndheld simula tor Developer ’s Guid e – RI M 950 W ireless Handheld™ When the RIM Wirele ss Handheld simulat or starts, it determines t he simulat ed flash size. The size can be specifi ed using the /F command line opt ion and the default size is 2048 K B. The simulator now ch ecks to see if there is a f[...]

Tools guide — RIM 950 Wireless Ha ndheld simula tor 29 Developer’ s Guide – RIM 950 Wireless Handheld ™ Flash alloca tion The available f lash memor y (either sim ulated or real) is divided into four areas: • File system data a rea • Unused area • OS and appli cation code area • Fixed use area Areas a re allocated by writing an entr[...]

30 Tools guide — RIM 950 Wireless Ha ndheld simula tor Developer ’s Guid e – RI M 950 W ireless Handheld™ When using a phys ical mo dem with t he simula tor, you ca nnot simu late different coverage situations in software; you are limited by what the modem is actually exp eriencing. To si mulate different covera ge situations, chan ge the p[...]

Tools guide — RIM 950 Wireless Ha ndheld simula tor 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 se nding large a mounts of data. In addit ion, when sending la rge a mount s of tra ffic with the RIM Wirele ss Hand held, it s battery life[...]

32 Tools guide — RIM 950 Wireless Ha ndheld simula tor Developer ’s Guid e – RI M 950 W ireless Handheld™ /RSIM= <add ress> This option set s the address to si mula te. /RDIR= <dir ectory > Thi s opti on se ts the dire ctory to use for th e simu latio n. Th e defa ult director y is the curre nt director y. Radio sim ulators m us[...]

Tools guide — RIM 950 Wireless Ha ndheld simula tor 33 Developer’ s Guide – RIM 950 Wireless Handheld ™ • Guidelines for wr iti ng a host- side applica tion to s im ula te the network This section de scribes t he network sim ulation in gener al terms. The contr ol pane l cons ists of two part s: recepti on and trans mission. T he Recepti [...]

34 Tools guide — RIM 950 Wireless Ha ndheld simula tor Developer ’s Guid e – RI M 950 W ireless Handheld™ State Description Checking... The radio is checking for data on a 10 secon d interval, or the Check now butt on was pressed. Checking for 10 sec. The radio is checking c ontinu ously because of a rec e nt data pa c ke t sent or rece ive[...]

Tools guide — RIM 950 Wireless Ha ndheld simula tor 35 Developer’ s Guide – RIM 950 Wireless Handheld ™ /R n Tell the RIM Wireless Han dheld simula tor to use serial port n for a RAP modem. The RAP modem is used in place of the physical RF hardware in the simulati on envir on ment. If this ar gu ment i s o mitted, no serial port is used, a [...]

36 Tools guide — RIM 950 Wireless Ha ndheld simula tor Developer ’s Guid e – RI M 950 W ireless Handheld™ /D15 /A n Simu late n sec tors simulat ed fla sh mem ory (in 6 4 KB se ctors) to be used for OS and applica tion code stor age. If thi s opti on is omitte d, the previous amount is preserved, unles s /E is simul taneously specified. If [...]

Tools guide — Program load er 37 Developer’ s Guide – RIM 950 Wireless Handheld ™ In this example, APP2.DLL is assumed to reside in the working directory C:devapp1.dll app2.dll. Debuggi ng hint s Some tips f or debuggin g applicatio ns usi ng the si mulator (a nd the RIM Wireless Handheld it self). • When the ma chine fails and request [...]

38 Tools guide — Program load er Developer ’s Guid e – RI M 950 W ireless Handheld™ Program loader command lin e options The PROGRAMMER.EXE uti lity re quires a set of co mmand line opti ons to denote s erial port configu ration, the action required, and what fil es are to be manipulated. The co mmand line te mplate is: PROGRAMMER [[-P port[...]

Tools guide — Program load er 39 Developer’ s Guide – RIM 950 Wireless Handheld ™ Command Description BATCH filename Run PROGRAMMER.EXE commands stored in a file VER List applicat ions currentl y on the Wireless Handheld, includ ing version informa tion MAP [-F] [-R] Display deta iled f lash a nd RAM maps LOADFS Load file s ystem data from [...]

40 Tools guide — Program load er Developer ’s Guid e – RI M 950 W ireless Handheld™ API, RimCat astr ophic APIF ailure () . In a ll cases, ot her unresolved links fa il; only unresolved OS calls can be ma pped. -D specifies that u nresolved OS ca lls should not b e mapped to RimCat astr ophicA PIFa ilure () . <files or g roup s> are o[...]

Tools guide — Program load er 41 Developer’ s Guide – RIM 950 Wireless Handheld ™ PROGRAMMER LOAD PAGER950.BIN UI32.dll ( Address.dll AutoText.dll Message.dll Options.dll Transport_RTP.dll ) The following c ommand w i ll load a new ca lculator app lication, grou ping it with the other applica ti ons: PROGRAMMER LOAD -G Calculator.dll ER ASE[...]

42 Tools guide — Program load er Developer ’s Guid e – RI M 950 W ireless Handheld™ Where -S specifies a shor t listing of o nly the applica tio n name s. Description The DIR com mand generates a listing of the applica tions currently loaded on a RIM Wireless Ha ndheld. Unle ss the -S op tion is specified, this listing i ncludes the na mes [...]

Tools guide — Program load er 43 Developer’ s Guide – RIM 950 Wireless Handheld ™ Description The BA TCH comma nd allows mu ltiple commands to be placed in a file and executed with a single, short command. This com mand is useful when repeatedly performing the same load process, and for overcoming the fixed limit imp osed on com ma nd lines[...]

44 Tools guide — Program load er Developer ’s Guid e – RI M 950 W ireless Handheld™ Example To get help on t he LOAD command, type: PROGRAMMER HELP LOAD To get help on e r rors, type : PROGRAMMER HELP ERRORS To get a main help pa ge, type: PROGRAMMER HELP HELP A L LOC command ALLOC [-E] [-D <sectors>] [-A <sectors>] Where -E spe[...]

Tools guide — Program load er 45 Developer’ s Guide – RIM 950 Wireless Handheld ™ When the File Area siz e is decreased , at least one blank sector mu st remain within t he area. Back up and pack yo ur data before issuing t he ALLOC command. Troubleshoo ting Most error messages are self-explanatory. The following err ors deserve more discus[...]

46 Tools guide — Program load er Developer ’s Guid e – RI M 950 W ireless Handheld™ Error: No t all imp orts res olved An applica tion is r equest ing imp orts fr om anot her applicatio n that cannot be ex ported by the other applic ation. Ensure that you are loa ding all application s tha t pr ovide the exports t hat you need.[...]

Tools guide — DLLUtil 47 Developer’ s Guide – RIM 950 Wireless Handheld ™ DLLUtil The DLLUTIL.EXE u tility provides information a bout DLLs as they will be when loa ded onto t he RIM Wire less Handhe ld, si milar to the output of PROGRAMMER DIR and PROGRAMMER VER . There are two forms of the command: DLLUTIL SIZE [-R] files DLLUTIL VER file[...]

48 Tools gu ide — Convers ion utilities Developer ’s Guid e – RI M 950 W ireless Handheld™ The syntax is: BITMAP definition header The definition f ile format is d escribed in the OS API Developer’s Gu ide, under “Creatin g bitmaps.” BMP2DEF The BMP2DEF.EXE execut able c reates a definiti on fil e from an e xisti ng bitmap ( .BMP ). T[...]

An overvi ew of the sy stem — Conver sion utilit ies 49 Developer’ s Guide – RIM 950 Wireless Handheld ™ 5. An overview of the sy stem This section de scribes part s of the RIM Wireless Handheld ’s system for developers, concentrati ng on the operating syste m. When devel oping f or the RIM Wir eless Handheld, it’s imp ortant to realize[...]

50 An overvi ew of the sy stem — RIM co-operative sch eduler Developer ’s Guid e – RI M 950 W ireless Handheld™ RIM co-operative scheduler The RIM Wireless Handhel d’s operating sy stem (OS) is designed usi ng a co-operative multita sking model. For more informati on on the operating system an d the OS function al specifications , see the[...]

An overview of t he system — MESSAGE concept 51 Developer’ s Guide – RIM 950 Wireless Handheld ™ For more information on the MESSAG E posting proc ess, see “ MESS AGE concept ” below as well as the RIM 950 W ireless Han dheld Op erating System API Developer’s G uide. MESSAGE concept The Operating Sy stem allows for inter-task c ommuni[...]

52 An overvi ew of the sy stem — User interfa ce Developer ’s Guid e – RI M 950 W ireless Handheld™ User interface The user can acquire data f rom the application through the RIM Wireless Handheld’s LCD. I n order to use the LCD, the applica tion mus t make a request to become the foreground task. For more information on making an applica[...]

An overvi ew of the sy stem — API overview 53 Developer’ s Guide – RIM 950 Wireless Handheld ™ The following A PIs are pr ovided. All but the most trivial a pplications will need to make use of t he APIs described in the OS A PI Developer’s guide and the User Interface Developer’s Guide. API Descripti on Documente d in Address Boo k API[...]

54 An overvi ew of the sy stem — API overview Developer ’s Guid e – RI M 950 W ireless Handheld™ API Descripti on Documente d in Serial communications API access and configure serial port on the RIM Wire less Hand held OS API System services API Access to thread handling, messaging, a nd task sw itching, memory allocati on, timers, a nd the[...]

6. Building applications This chapter de scribes the basics of writing a n application f or the RIM Wireless Ha ndheld. Coding an application This section briefl y outlines the required components of an application on the wireless handhel d. The basic program st ructure essentiall y consists of an infinite l oop that receives messages fr om the OS,[...]

56 Building appl ications — C oding an appl ication Developer ’s Guid e – RI M 950 W ireless Handheld™ • Begin the PagerM ain() f unction w ith the c onstruc tion of a ny permanent object s required by the applica tion. You sho uld avoid accessing objects in other DLLs because until the Page rMai n() functions i n these DLLs ha ve ha d a [...]

Building appl ications — C oding an appl ication 57 Developer’ s Guide – RIM 950 Wireless Handheld ™ Here is some example PagerMai n() code fo r an application t hat makes use of the database: #include <Pager.h> #include <Ribbon.h> //Definition of bitmap registered with ribbon #include <bitSample.h> char VersionPtr[] = &qu[...]

58 Building appl ications — C oding an appl ication Developer ’s Guid e – RI M 950 W ireless Handheld™ #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 ) { c[...]

Building appl ications — C oding an appl ication 59 Developer’ s Guide – RIM 950 Wireless Handheld ™ application f rom t he RIBBON device, with the event set to RIBBON _GRA B_FORE GROU ND . If we get a RIBB ON message, we call RimGet Curr entTas kID( ) for the current ta sk han dle. We bring the application to the f oreground usi ng RimR eq[...]

60 Building appl ications — C oding an appl ication Developer ’s Guid e – RI M 950 W ireless Handheld™ If the user presses a key, the OS se nds a MESSAGE to the applica tion f r om the KEYP AD d e v i c e. I f w e ge t a KEYP AD message, we p ass the MESS AGE to the UI Engine, which retur ns a result code: if( msg.Device == DEVICE_KEYPAD ) [...]

Building appl ications — C oding an appl ication 61 Developer’ s Guide – RIM 950 Wireless Handheld ™ static void set_task_pid( void ) { PID pid; pid.Name = "Example Application"; pid.EnableForeground = true; pid.Icon = NULL; RimSetPID( &pid ); } // Function which creates the main thread void PagerMain( void ) { MESSAGE msg; se[...]

62 Building appl ications — C oding an appl ication Developer ’s Guid e – RI M 950 W ireless Handheld™ To set up a ba sic progr am struc ture 1. Implem ent a message loo p: Any applicati on running on the d evice will need to h andle messa ges from the OS tha t will n otify the applicati on of key presses, ra dio events, etc. The most effic[...]

Building appl ications — C ompiling RIM Wireless Hand held appli cations 63 Developer’ s Guide – RIM 950 Wireless Handheld ™ MESSAG E s resulting fr om a key being pressed on the keyboard are sent only t o the fore gr ou nd ta sk. 4. If th e UI Engine returns CLICKED , the applicat ion should display a menu. If the UI Engine returns UN HAND[...]

64 Building appl ications — Installing the applicati on Developer ’s Guid e – RI M 950 W ireless Handheld™ You shou ld now be able t o compile a nd debug your a pplication using the RI M 950 Wireless H andheld SDK. Installing the application There are two uti lities availa ble to install the appl ication on a RIM Wireless Hand held, the PRO[...]

Building appl ications — Installing the applicati on 65 Developer’ s Guide – RIM 950 Wireless Handheld ™ Value Name Value Type Meaning Corresponds to the <DISPL AY_N AME> tag of the ALI file. Flags RE G_ DWORD See below. Generall y 0x04 is the best value. Inferred fro m the optional <SCR EEN_SIZE > tag of the ALI files. Path REG[...]

66 Building appl ications — Installing the applicati on Developer ’s Guid e – RI M 950 W ireless Handheld™ A LI fi le fo rma t The ALI file is rea d by the Applicat ion Loader, whic h then sets appropriate registry keys. From tha t point on, y our applica tion is kn own to the loader. The ALI file is a text file tha t conta ins three lines.[...]

Building appl ications — Installing the applicati on 67 Developer’ s Guide – RIM 950 Wireless Handheld ™ Application l oader notes You should be aware of the follo wing whe n packag ing appl ications f or the Applicat i on Loade r for the RIM Wirele ss Ha ndhel d. Each application requires an ALI file or registry settings The ALI file conta[...]

[...]

Appendix C library compatibility for RIM Wireless Handheld applications Only some functi ons withi n the compiler C library ar e safe to ca ll from the RIM Wireless Ha ndheld environment. The following table summarizes the information. There are equivalent functions for the groups marked “No”—see the list afterwards. Compatible w ith RIM W ir[...]

70 Appendix — C library com patibility f or RIM Wireles s Handheld ap plication s Developer ’s Guid e – RI M 950 W ireless Handheld™ Functions t hat are com patible Argument ac cess ma cros This set of function s is compatible wit h the RIM Wireless Hand held environment. This includes the macros va_a rg , va_sta rt , and va_end . Buffer ma[...]

Appendix — C library com patibility f or RIM Wireles s Handheld ap plications 71 Developer’ s Guide – RIM 950 Wireless Handheld ™ debugging message s can b e outp ut to the debug o utput w indow when running MS Develope r S tudio by ca lling RimDeb ugPrintf . Directory control functions The RIM Wireles s Handhe ld file system is d iffere nt[...]

72 Appendix — C library com patibility f or RIM Wireles s Handheld ap plication s Developer ’s Guid e – RI M 950 W ireless Handheld™ Handheld appl ications ru n in a protected e nvironment, ca lling the se functions will ca use a protection f ault at run time. Locale dependent func tions The RIM Wireless Hand held environ ment does not supp[...]

Appendix — C library com patibility f or RIM Wireles s Handheld ap plications 73 Developer’ s Guide – RIM 950 Wireless Handheld ™ operating syste m alloca tes applica tion sta cks, Wi ndo ws funct ions a re not safe to call even when running on the simulator. Time functions The RIM Wireless Ha ndheld operating system represents time differe[...]

[...]

Index about t his guide, 6–7 ALI file, 64 alt key , simulat ing, 24–25 API generic application, See generic application overview, 52– 54 applicati on loader, 64 registry keys, 64 applications compiling RIM W ireless Handhe ld, 63–67 restartin g, 50 backlighting, 2 5 BITMAP.EXE utilit y, 47 BMP2DEF.E XE uti lity, 48 buildin g applicat ions, [...]

76 Index Developer ’s Guid e – RI M 950 W ireless Handheld™ use, 51 message loop s and ribbon , 59 definiti on, 62 entering the messa ge lo op, 57–58 MESSAGEs concept, 5 1 mode pager, 25 pc, 25 modem, 3 5 radio simu lation c o ntrol panel dial og box, 32 simulatin g using a phy sica l modem, 2 9 simulatin g using the file system, 3 1 simula[...]

Index 77 Developer’ s Guide – RIM 950 Wireless Handheld ™ RIM Wireles s Handhe ld simulator, See simulat or running the simulator, 19–20 SDK compone nts, 6–7 description, 5 ins talling, 9– 13 multitaski ng, 5 processor, 5 serial i nput/output , 27 serial po rt, 34 shift key simulato r, 25 shortcuts f or s tarting t he simulat or, 20–2[...]