(Online version only)
|
API Guide Home (Online version only) |
|
00001 /******************************************************************************* 00002 * Copyright (c) 2004-2005 Palm, Inc. or its subsidiaries. 00003 * All rights reserved. 00004 ******************************************************************************/ 00005 /** 00006 * @defgroup Locs Locations Library 00007 * @brief This library provides location/timezone/DST support for applications. 00008 * 00009 * Developers who want to provide location/timezone/DST or country information 00010 * to their application on Palm devices should use Locations Library API. 00011 * 00012 * @{ 00013 * @} 00014 */ 00015 /** 00016 * @ingroup Locs 00017 */ 00018 00019 /** 00020 * @file LocsLibCommon.h 00021 * @brief Public 68K common header file for locations library. 00022 * 00023 * This file contains the library constants and error codes used in the APIs. 00024 * <hr> 00025 */ 00026 00027 #ifndef LOCS_LIB_COMMON_H 00028 #define LOCS_LIB_COMMON_H 00029 00030 #include <DataMgr.h> 00031 #include <LocaleMgr.h> 00032 #include <PalmTypes.h> 00033 #include <SystemResources.h> 00034 #include <SysUtils.h> 00035 00036 00037 /****************************************************************************** 00038 * 00039 * LIBRARY VERSION 00040 * 00041 * The library version scheme follows the system versioning scheme. 00042 * See sysMakeROMVersion and friends in SystemMgr.h. 00043 * 00044 * For reference: 00045 * 00046 * 0xMMmfsbbb, where 00047 * MM is major version, 00048 * m is minor version, 00049 * f is bug fix, 00050 * s is stage: 3-release, 2-beta, 1-alpha, 0-development, 00051 * bbb is build number for non-releases. 00052 * e.g.: 00053 * V1.12b3 would be: 0x01122003 00054 * V2.00a2 would be: 0x02001002 00055 * V1.01 would be: 0x01013000 00056 * 00057 * Stages are: 00058 * sysROMStageDevelopment 00059 * sysROMStageAlpha 00060 * sysROMStageBeta 00061 * sysROMStageRelease 00062 * 00063 * Note: This scheme was taken from the SampleLib.c of the Palm OS Dev KB 00064 * download. 00065 * 00066 *****************************************************************************/ 00067 /** 00068 *@name Library Versions 00069 */ 00070 /*@{*/ 00071 #define kLocsLibVersion01 sysMakeROMVersion (1, 0, 0, sysROMStageDevelopment, 1) 00072 #define kLocsLibVersion0121 sysMakeROMVersion (1, 2, 1, sysROMStageDevelopment, 1) 00073 #define kLocsLibVersion013 sysMakeROMVersion (1, 3, 0, sysROMStageDevelopment, 1) 00074 #define kLocsLibVersionCurrent kLocsLibVersion013 00075 /*@}*/ 00076 00077 /****************************************************************************** 00078 * 00079 * LocsLib ERROR CODES 00080 * 00081 *****************************************************************************/ 00082 /** 00083 *@name Error Codes 00084 */ 00085 /*@{*/ 00086 #define locLErrorClass (appErrorClass | 0x0100) 00087 #define locLErrNone 0 00088 #define locLErrCantFindLocsDB (locLErrorClass | 1) 00089 #define locLErrBadParam (locLErrorClass | 2) 00090 #define locLErrBadRefNum (locLErrorClass | 3) 00091 #define locLErrNoGlobals (locLErrorClass | 4) 00092 #define locLErrNoMemForGlobals (locLErrorClass | 5) 00093 #define locLErrNoLibSysReference (locLErrorClass | 6) 00094 #define locLErrCantOpenLibRsc (locLErrorClass | 7) 00095 #define locLErrMemAllocFail (locLErrorClass | 8) 00096 #define locLErrBadVersion (locLErrorClass | 9) 00097 #define locLErrNotOpen (locLErrorClass | 10) 00098 #define locLErrStillOpen (locLErrorClass | 11) 00099 /*@}*/ 00100 00101 /****************************************************************************** 00102 * 00103 * LocsLib General CONSTANTS 00104 * 00105 *****************************************************************************/ 00106 00107 // Use this for SysLibFind calls: 00108 /** Library name */ 00109 #define kLocsLibName "LocsLib-locL" 00110 00111 // The locations library creator ID: 00112 // Note: this is registered with Palm, Inc. 00113 /** Library creator ID */ 00114 #define kLocsFileCLocsLib (UInt32)('locL') 00115 00116 /** The feature number used to refer to the stored library reference number */ 00117 #define kLocsLibFtrNumRefNum (UInt16)(1) 00118 00119 // The notification types for location change events: 00120 // Note: used the creator id for the base event, as this seems to be what the 00121 // other notifcation event types are based on and it seems the best way 00122 // to assure no confusion. Apps checking the types based on the first 00123 // type should also verify the broadcaster is the Locs lib. 00124 /** 00125 *@name Notifications 00126 */ 00127 /*@{*/ 00128 #define kLocsLibNotifyLocChangeEvent kLocsFileCLocsLib 00129 #define kLocsLibNotifyLocEditEvent kLocsLibNotifyLocChangeEvent + 1 00130 #define kLocsLibNotifyLocDeleteEvent kLocsLibNotifyLocChangeEvent + 2 00131 #define kLocsLibNotifyLocAddEvent kLocsLibNotifyLocChangeEvent + 3 00132 /*@}*/ 00133 00134 // Masks for determing which bits in the selection dirty bits are set: 00135 /** 00136 *@name Bit Masks 00137 */ 00138 /*@{*/ 00139 #define kLocsLibSel01 0x00000001 00140 #define kLocsLibSel02 0x00000002 00141 #define kLocsLibSel03 0x00000004 00142 #define kLocsLibSel04 0x00000008 00143 #define kLocsLibSel05 0x00000010 00144 #define kLocsLibSel06 0x00000020 00145 #define kLocsLibSel07 0x00000040 00146 #define kLocsLibSel08 0x00000080 00147 #define kLocsLibSel09 0x00000100 00148 #define kLocsLibSelMax 0x80000000 00149 /*@}*/ 00150 00151 /****************************************************************************** 00152 * 00153 * Location CONSTANTS 00154 * 00155 ***********************************************************************/ 00156 00157 // Max location name length: 00158 #define kLocNameMaxLength (UInt16)(100) 00159 00160 //Max location note length 00161 #define kLocNoteMaxLength (UInt16)(4096) 00162 00163 // Location custom member values: 00164 #define kLocNoDisplayInCustom (UInt8)(0) /**< don't display location in custom database */ 00165 #define kLocDisplayInCustom (UInt8)(1) /**< display location in custom database */ 00166 00167 //Undefined position 00168 #define kUndefinedPosition (Int16)999 /**< flag: position of location in database in undefined */ 00169 00170 00171 /****************************************************************************** 00172 * 00173 * LocsLibEditList CONSTANTS 00174 * 00175 ***********************************************************************/ 00176 #define kLocsLibListUpdateClass 0x0400 00177 #define kLocsLibListUpdate (UInt16)(kLocsLibListUpdateClass | 1) 00178 00179 00180 /****************************************************************************** 00181 * 00182 * LocationsDB CONSTANTS 00183 * 00184 ***********************************************************************/ 00185 00186 #define kLocDBVersion (UInt16)(2) /**< Current version of the location DB format */ 00187 #define kLocDBMaxLocNameLength kLocNameMaxLength /**< Max # of bytes for a location name stored. */ 00188 00189 /** 00190 *@name Database Names and Types 00191 */ 00192 /*@{*/ 00193 #define kLocFileCDatabase (UInt32)('locL') 00194 #define kLocFileTDefLocDB (UInt32)('DATA') 00195 #define kLocFileTCusLocDB (UInt32)('DATC') 00196 #define kLocFileNDefaultDB "locLDefLocationDB" 00197 #define kLocFileNCustomDB "locLCusLocationDB" 00198 /*@}*/ 00199 00200 // Location record reserve member values: 00201 #define kLocDBTypeDefault (UInt8)(0) /**< the location database is the default one */ 00202 #define kLocDBTypeCustom (UInt8)(1) /**< the location database is custom */ 00203 00204 /** Location database sort constants */ 00205 enum _LocDBSortOrderType { 00206 kSortByNameCountryTZ, 00207 kSortByCountryTZName, 00208 kSortByCountryCodeTZName 00209 }; 00210 00211 typedef UInt8 LocDBSortOrderType; 00212 00213 /****************************************************************************** 00214 * 00215 * LocsLibDSTAlarm CONSTANTS 00216 * 00217 ***********************************************************************/ 00218 /** 00219 *@name DST Alarm Constants 00220 */ 00221 /*@{*/ 00222 #define kLocsLibDSTAlert (UInt32)(1) 00223 #define kLocsLibDSTStartAlert (UInt32)(2) 00224 #define kLocsLibDSTEndAlert (UInt32)(3) 00225 /*@}*/ 00226 00227 00228 /****************************************************************************** 00229 * 00230 * Location OBJECT TYPES 00231 * Important!! Any changes made to the following location data types require 00232 * a recompile of the DDEditor and a rebuild of the default db 00233 * to match the new format. 00234 * 00235 ***********************************************************************/ 00236 00237 /**< Daylight saving time (DST) data format */ 00238 typedef struct DSTDataTag DSTType; 00239 struct DSTDataTag 00240 { 00241 UInt8 hour; /**< 1 - 24, usually 1 for 1 a.m. */ 00242 UInt8 dayOrd; /**< 0 = Sun, 1 = Mon, 2 = Tues, 3 = Weds, 4 = Thurs, 5 = Fri, 6 = Sat. */ 00243 UInt8 weekOrd; /**< 0 = 1st, 1 = 2nd, 2 = 3rd, 3 = 4th, 4 = Last */ 00244 UInt8 month; /**< 1 - 12 = Jan - Dec 00245 No year member, as the DST date should be consistent 00246 from year to year in regards to this "1st Sunday in 00247 October" format used here. DST boundary alerts are 00248 always set for the current year, or to the following 00249 year as needed. */ 00250 }; 00251 00252 // Note: It's possible that DST adjustments may change in the future, 00253 // and at that time, a UI can be provided to set the proper adjustment, 00254 // or an updated default db can be distributed and installed. 00255 00256 /** Container to store degree and minute of a coordinate */ 00257 typedef struct{ 00258 Int16 degree; 00259 Int16 minute; 00260 }Coordinate; 00261 00262 /** Container to store longitude and latitude of a specific location */ 00263 typedef struct{ 00264 Coordinate latitude; 00265 Coordinate longitude; 00266 }PosType; 00267 00268 typedef struct LocationDataTag LocationType; 00269 /** Location data format */ 00270 struct LocationDataTag 00271 { 00272 Int16 uTC; /**< timezone */ 00273 DSTType dSTStart; /**< date/time when DST begins, e.g. 31 Oct 2am */ 00274 DSTType dSTEnd; /**< date/time when DST end */ 00275 Int16 dSTAdjustmentInMinutes; /**< 0 = DST not observed, 60 = observed. */ 00276 CountryType country; /**< see Palm OS documentation for values */ 00277 UInt8 custom : 1, /**< not used */ 00278 reserved : 7; /**< not used */ 00279 Char* name; /**< for db record type use name[] */ 00280 PosType position; /**< Position (Longitude & Latitude) values */ 00281 Char* note; /**< Note for each City */ 00282 }; 00283 00284 00285 /****************************************************************************** 00286 * 00287 * LocationsDB OBJECT TYPES 00288 * 00289 ***********************************************************************/ 00290 00291 typedef struct LocDBInfoTag LocDBInfoType; 00292 /** Helpful struct for passing db info as an argument */ 00293 struct LocDBInfoTag 00294 { 00295 Char* dbName; /**< name of location database */ 00296 UInt32 dbCreatorID; /**< creator of the database */ 00297 UInt32 dbType; /**< database type */ 00298 UInt16 dbCardNum; /**< cardNo where database resides */ 00299 }; 00300 00301 00302 typedef struct LocDBRecordTag LocDBRecordType; 00303 /** Location database record format */ 00304 struct LocDBRecordTag 00305 { 00306 Int16 uTC; /**< timezone */ 00307 DSTType dSTStart; /**< time when DST begins e.g. 2am */ 00308 DSTType dSTEnd; /**< time when DST end */ 00309 Int16 dSTAdjustmentInMinutes; /**< 0 = DST not observed, 60 = observed. */ 00310 CountryType country; /**< Country. See Palm OS documentation for values */ 00311 UInt8 custom : 1, /**< not used */ 00312 reserved : 7; /**< not used */ 00313 Char name[0]; /**< LocationType uses Char* name */ 00314 }; 00315 00316 00317 /****************************************************************************** 00318 * 00319 * LocsLibUtils OBJECT TYPES 00320 * 00321 *****************************************************************************/ 00322 00323 typedef struct LocsLibNotifyLocsDataTag LocsLibNotifyLocsDataType; 00324 /** Struct used to pass notification location data to interested apps */ 00325 struct LocsLibNotifyLocsDataTag 00326 { 00327 LocationType locationDataNew; /**< new location data */ 00328 const Char* locationNameOldP; /**< name of old location */ 00329 }; 00330 00331 00332 typedef struct LocsLibNotifyDataTag LocsLibNotifyDataType; 00333 /** Helpful struct for passing notification info as an arg */ 00334 struct LocsLibNotifyDataTag 00335 { 00336 Boolean showWaitDialogue; /**< If true, a "Please Wait" dialogue will be displayed while waiting for broadcast completion */ 00337 UInt32 notifyType; /**< One of the Locs lib notification type constants. */ 00338 LocsLibNotifyLocsDataType locationData; /**< The location data to broadcast. */ 00339 }; 00340 00341 00342 /****************************************************************************** 00343 * 00344 * LocsLib OBJECT TYPES 00345 * 00346 *****************************************************************************/ 00347 00348 typedef struct LocsLibSelLocsTag LocsLibSelLocsType; 00349 /** Container for the selected location in the location database */ 00350 struct LocsLibSelLocsTag 00351 { 00352 LocationType* locationP; /**< Location data of the location selected from the Add Sel list. Caller must allocate the memory. */ 00353 UInt32 dirtySelections; /**< indicates which selections were modified 00354 e.g.: the 1st selection, element 0, would be 00355 indicated by dirtySelections & kLocsLibSel01 */ 00356 Boolean needSelLoc; /**< true if the caller wants a location name being chosen from the Add Sel list to be saved in the selLocsList. */ 00357 Boolean warnIfLocExists; /**< false if the caller doesn't want the user warned if selecting a location that already exists in the custom db. */ 00358 Boolean noEditOnSelect; /**< true if the caller wants the "Edit Location" dialogue to NOT be displayed after user selects a location; only applies to LocsLibLaunchSelDialogue(). */ 00359 Boolean preSelect; /**< true if the caller wants the current location to be preselected in the Add Sel list; only applies to ADD/SEL location dialogue (shows master default list of locations).*/ 00360 Boolean sendChangeNotify; /**< true if the caller wants the selected location data to be broadcast to all registered apps; only applies to LocsLibLaunchSelDialogue().*/ 00361 Boolean noAddToCustomDB; /**< true if the caller doesn't want the selected location to be added to the custom db.*/ 00362 UInt8 numSelLocs; /**< Number of items in the selLocsList*/ 00363 UInt8 reserved; /**< Reserved, not used */ 00364 Char** selLocsListP; /**< List of locations names that are "selected" and the caller needs to know if they are changed.*/ 00365 }; 00366 00367 00368 00369 /****************************************************************************** 00370 * 00371 * Location MACROS 00372 * 00373 ***********************************************************************/ 00374 00375 /** 00376 *@name Accessor Macros 00377 */ 00378 /*@{*/ 00379 #define LocationGetUTC(locationP) (locationP)->uTC 00380 #define LocationGetDSTStart(locationP) &((locationP)->dSTStart) 00381 #define LocationGetDSTEnd(locationP) &((locationP)->dSTEnd) 00382 #define LocationGetDSTAdj(locationP) (locationP)->dSTAdjustmentInMinutes 00383 #define LocationGetCountry(locationP) (locationP)->country 00384 #define LocationGetCustom(locationP) (locationP)->custom 00385 #define LocationGetReserved(locationP) (locationP)->reserved 00386 #define LocationGetName(locationP) (locationP)->name 00387 /*@}*/ 00388 00389 /** 00390 *@name Mutator Macros 00391 */ 00392 /*@}*/ 00393 #define LocationSetUTC(locationP, newUTC) \ 00394 ((locationP)->uTC = newUTC) 00395 #define LocationSetDSTStart(locationP, newDstStart) \ 00396 ((locationP)->dSTStart = newDstStart) 00397 #define LocationSetDSTEnd(locationP, newDstEnd) \ 00398 ((locationP)->dSTEnd = newDstEnd) 00399 #define LocationSetDSTAdj(locationP, newDstAdj) \ 00400 ((locationP)->dSTAdjustmentInMinutes = newDstAdj) 00401 #define LocationSetCountry(locationP, newCountry) \ 00402 ((locationP)->country = newCountry) 00403 #define LocationSetCustom(locationP, newCustom) \ 00404 ((locationP)->custom = newCustom) 00405 #define LocationSetReserved(locationP, newReserved) \ 00406 ((locationP)->reserved = newReserved) 00407 /*@}*/ 00408 // Note: SetName is implemented as a function. 00409 00410 // Predicate macros: 00411 #define LocationAreDSTDatesEqual(iDST01P, iDST02P) \ 00412 ( (iDST01P)->hour == (iDST02P)->hour \ 00413 && (iDST01P)->dayOrd == (iDST02P)->dayOrd \ 00414 && (iDST01P)->weekOrd == (iDST02P)->weekOrd \ 00415 && (iDST01P)->month == (iDST02P)->month) 00416 00417 /****************************************************************************** 00418 * 00419 * LocationsDB MACROS 00420 * 00421 ***********************************************************************/ 00422 /** 00423 *@name Helper Macros 00424 */ 00425 /*@{*/ 00426 #define LocDBCompareUTC(iUTC01, iUTC02) \ 00427 (iUTC01 - iUTC02) 00428 #define LocDBCompareCountries(iCountry01, iCountry02) \ 00429 (iCountry01 - iCountry02) 00430 #define LocDBCompareNames(iName01, iName02) \ 00431 (StrCompare (iName01, iName02)) 00432 00433 #define LocDBGetUTC(locRecP) (locRecP)->uTC 00434 #define LocDBGetCountry(locRecP) (locRecP)->country 00435 /*@}*/ 00436 00437 /****************************************************************************** 00438 * 00439 * LOCATIONS LIBRARY TRAP NUMBERS 00440 * 00441 *****************************************************************************/ 00442 00443 // These are LocsLib's trap identifiers: 00444 // Note: The PalmOS constant 'sysLibTrapCustom' is the first trap number 00445 // that can be used after open, close, sleep, and wake: 00446 00447 /** 00448 *@name Function Traps 00449 */ 00450 /*@{*/ 00451 #define locsLibTrapGetVersion (sysLibTrapCustom + 0) 00452 #define locsLibTrapLaunchEditListDlg (sysLibTrapCustom + 1) 00453 #define locsLibTrapLaunchSelDialogue (sysLibTrapCustom + 2) 00454 #define locsLibTrapLocCopy (sysLibTrapCustom + 3) 00455 #define locsLibTrapLocFinal (sysLibTrapCustom + 4) 00456 #define locsLibTrapLocGetSize (sysLibTrapCustom + 5) 00457 #define locsLibTrapLocInit (sysLibTrapCustom + 6) 00458 #define locsLibTrapLocIsDSTPast (sysLibTrapCustom + 7) 00459 #define locsLibTrapLocMakeGeneric (sysLibTrapCustom + 8) 00460 #define locsLibTrapLocSetName (sysLibTrapCustom + 9) 00461 #define locsLibTrapDBChangeRecord (sysLibTrapCustom + 10) 00462 #define locsLibTrapDBCmpRecordsSimple (sysLibTrapCustom + 11) 00463 #define locsLibTrapDBConvertRecord (sysLibTrapCustom + 12) 00464 #define locsLibTrapDBCopyLocation (sysLibTrapCustom + 13) 00465 #define locsLibTrapDBDeleteRecord (sysLibTrapCustom + 14) 00466 #define locsLibTrapDBFindCustomRecord (sysLibTrapCustom + 15) 00467 #define locsLibTrapDBFindFirst (sysLibTrapCustom + 16) 00468 #define locsLibTrapDBFindFirstByName (sysLibTrapCustom + 17) 00469 #define locsLibTrapDBFindFirstByUTCCtry (sysLibTrapCustom + 18) 00470 #define locsLibTrapDBFindFirstInList (sysLibTrapCustom + 19) 00471 #define locsLibTrapDBGetCustomList (sysLibTrapCustom + 20) 00472 #define locsLibTrapDBGetRecordList (sysLibTrapCustom + 21) 00473 #define locsLibTrapDBGetRecord (sysLibTrapCustom + 22) 00474 #define locsLibTrapDBInitDBs (sysLibTrapCustom + 23) 00475 #define locsLibTrapDBNewRecord (sysLibTrapCustom + 24) 00476 #define locsLibTrapDBOpenCustom (sysLibTrapCustom + 25) 00477 #define locsLibTrapDBOpenDefault (sysLibTrapCustom + 26) 00478 #define locsLibTrapDBRecordSize (sysLibTrapCustom + 27) 00479 #define locsLibTrapDBSetRecordCustom (sysLibTrapCustom + 28) 00480 #define locsLibTrapDBSort (sysLibTrapCustom + 29) 00481 #define locsLibTrapDSTAlarmClear (sysLibTrapCustom + 30) 00482 #define locsLibTrapDSTAlarmIsDST (sysLibTrapCustom + 31) 00483 #define locsLibTrapDSTAlarmSet (sysLibTrapCustom + 32) 00484 #define locsLibTrapLocDBNewRecordV20 (sysLibTrapCustom + 33) 00485 #define locsLibTrapLocDBGetRecordV20 (sysLibTrapCustom + 34) 00486 #define locsLibTrapLocDBConvertRecordV20 (sysLibTrapCustom + 35) 00487 #define locsLibTrapLocDBChangeRecordV20 (sysLibTrapCustom + 36) 00488 #define locsLibTrapLocDBGetRecordListV20 (sysLibTrapCustom + 37) 00489 #define locsLibTrapLocDBGetNearestLocation (sysLibTrapCustom + 38) 00490 #define locsLibTrapLocationInitV20 (sysLibTrapCustom + 39) 00491 #define locsLibTrapLocationFinalV20 (sysLibTrapCustom + 40) 00492 #define locsLibTrapLocDBGetVersion (sysLibTrapCustom + 41) 00493 #define locsLibTrapLocationSetNote (sysLibTrapCustom + 42) 00494 #define locsLibTrapLocationSetPosition (sysLibTrapCustom + 43) 00495 #define locsLibTrapLocsLibLocationNote (sysLibTrapCustom + 44) 00496 #define locsLibTrapLocationGetSizeV20 (sysLibTrapCustom + 45) 00497 #define locsLibTrapLocationCopyV20 (sysLibTrapCustom + 46) 00498 #define locsLibTrapLocDBFindCustomRecordV20 (sysLibTrapCustom + 47) 00499 /*@}*/ 00500 00501 #endif
| Top | Palm Developer Network © 2004-2008, Palm, Inc. All rights reserved. Generated on Fri Jun 13 10:06:54 2008 for Palm API Guide |