Manuel d'utilisation / d'entretien du produit RIM 950 du fabricant Blackberry
Aller à la page of 77
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 l.
Contents 1. Introduction............................................................................................ 5 About the SDK ...................................................................................... 5 About the network ...........
.
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.
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.
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.
.
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.
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.
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.
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.
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 .
.
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.
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 .
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 appN.
.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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 in.
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.
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.
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.
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.
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.
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.
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.
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).
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.
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 current.
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 () .
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.
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.
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.
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 : PROGRAM.
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.
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 .
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.
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.
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.
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.
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.
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.
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 t.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
.
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.
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.
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 .
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.
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.
.
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.
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, 2.
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–.
Un point important après l'achat de l'appareil (ou même avant l'achat) est de lire le manuel d'utilisation. Nous devons le faire pour quelques raisons simples:
Si vous n'avez pas encore acheté Blackberry RIM 950 c'est un bon moment pour vous familiariser avec les données de base sur le produit. Consulter d'abord les pages initiales du manuel d'utilisation, que vous trouverez ci-dessus. Vous devriez y trouver les données techniques les plus importants du Blackberry RIM 950 - de cette manière, vous pouvez vérifier si l'équipement répond à vos besoins. Explorant les pages suivantes du manuel d'utilisation Blackberry RIM 950, vous apprendrez toutes les caractéristiques du produit et des informations sur son fonctionnement. Les informations sur le Blackberry RIM 950 va certainement vous aider à prendre une décision concernant l'achat.
Dans une situation où vous avez déjà le Blackberry RIM 950, mais vous avez pas encore lu le manuel d'utilisation, vous devez le faire pour les raisons décrites ci-dessus,. Vous saurez alors si vous avez correctement utilisé les fonctions disponibles, et si vous avez commis des erreurs qui peuvent réduire la durée de vie du Blackberry RIM 950.
Cependant, l'un des rôles les plus importants pour l'utilisateur joués par les manuels d'utilisateur est d'aider à résoudre les problèmes concernant le Blackberry RIM 950. Presque toujours, vous y trouverez Troubleshooting, soit les pannes et les défaillances les plus fréquentes de l'apparei Blackberry RIM 950 ainsi que les instructions sur la façon de les résoudre. Même si vous ne parvenez pas à résoudre le problème, le manuel d‘utilisation va vous montrer le chemin d'une nouvelle procédure – le contact avec le centre de service à la clientèle ou le service le plus proche.
