(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 * @ingroup Locs 00007 */ 00008 00009 /** 00010 * 00011 * @file LocsLib.h 00012 * @brief Public 68K include file for location/timezone/DST support on Palm devices. 00013 * 00014 */ 00015 00016 00017 #ifndef _LOCSLIB_H_ 00018 #define _LOCSLIB_H_ 00019 00020 // PalmSource includes: 00021 #include <DataMgr.h> 00022 #include <LibTraps.h> 00023 #include <LocaleMgr.h> 00024 #include <PalmTypes.h> 00025 #include <SystemResources.h> 00026 #include <SysUtils.h> 00027 #include <Common/Libraries/locs/LocsLibCommon.h> 00028 00029 00030 /****************************************************************************** 00031 * 00032 * PROTOTYPES 00033 * 00034 *****************************************************************************/ 00035 #ifdef __cplusplus 00036 extern "C" { 00037 #endif 00038 00039 00040 // Required entry points: 00041 00042 /// Standard library open routine. 00043 /// 00044 /// @param iLibRefNum: IN: Library reference number. 00045 /// @return Error code. 00046 extern Err LocsLibOpen (UInt16 iLibRefNum) 00047 SYS_TRAP (sysLibTrapOpen); 00048 00049 /// Standard library close routine. 00050 /// 00051 /// @param iLibRefNum: IN: Library reference number. 00052 /// @return Error code. 00053 extern Err LocsLibClose (UInt16 iLibRefNum) 00054 SYS_TRAP (sysLibTrapClose); 00055 00056 /// Standard library sleep routine. 00057 /// 00058 /// @param iLibRefNum: IN: Library reference number. 00059 /// @return Error code. 00060 extern Err LocsLibSleep (UInt16 iLibRefNum) 00061 SYS_TRAP (sysLibTrapSleep); 00062 00063 /// Standard library wake routine. 00064 /// 00065 /// @param iLibRefNum: IN: Library reference number. 00066 /// @return Error code. 00067 extern Err LocsLibWake (UInt16 iLibRefNum) 00068 SYS_TRAP (sysLibTrapWake); 00069 00070 // LocsLib general public custom functions (library extends to callers): 00071 00072 /// Get the version of the library on the device. 00073 /// 00074 /// @param iLibRefNum: IN: Library reference number. 00075 /// @param iSDKVersion: IN: Currently used library version in the SDK 00076 /// @param oVersionP: OUT: Version of the library on the device. 00077 /// @return Error code. 00078 extern Err LocsLibGetVersion (UInt16 iLibRefNum, UInt32 iSDKVersion, UInt32* oVersionP) 00079 SYS_TRAP (locsLibTrapGetVersion); 00080 00081 /// Runs the event loop for handling the Locations dialogues. 00082 /// Note: the preSelect, noEditOnSelect, and sendChangeNotify 00083 /// values of the caller data block don't apply for this API. 00084 /// 00085 /// @param iLibRefNum: IN: Library reference number. 00086 /// @param ioSelLocsP: I/O: Pointer to a selected locations object 00087 /// that contains data on selected locations. 00088 /// e.g.: The Clock 2.0 app displays 00089 /// several selected locations and the 00090 /// associated times. If any of those 00091 /// locations are removed or renamed, the 00092 /// Clock 2.0 app needs to know so it can 00093 /// update the display. 00094 /// This object is updated if any of the 00095 /// selected locations are renamed or removed. 00096 /// Use the dirty bits to determine quickly 00097 /// if any data were changed and if so, which. 00098 /// Pass NULL to ignore. 00099 /// @return True if changes are made. 00100 extern Boolean LocsLibLaunchEditListDialogue (UInt16 iLibRefNum, LocsLibSelLocsType* ioSelLocsP) 00101 SYS_TRAP (locsLibTrapLaunchEditListDlg); 00102 00103 /// Run the location selection dialogue, and then the 00104 /// Edit Location dialogue if the user tapped [OK] in 00105 /// the location selection dialogue and if the caller 00106 /// didn't specify to skip that dialogue. 00107 /// 00108 /// @param iLibRefNum: IN: Library reference number. 00109 /// @param ioSelLocsP: I/O: Pointer to a selected locations object 00110 /// that contains data on selected locations. 00111 /// e.g.: The Clock 2.0 app displays 00112 /// several selected locations and the 00113 /// associated times. If any of those 00114 /// locations are removed or renamed, the 00115 /// Clock 2.0 app needs to know so it can 00116 /// update the display. 00117 /// This object is updated if any of the 00118 /// selected locations are renamed or removed. 00119 /// Use the dirty bits to determine quickly 00120 /// if any data were changed and if so, which. 00121 /// Must not be NULL. 00122 /// @return True if changes are made. 00123 extern Boolean LocsLibLaunchSelDialogue (UInt16 iLibRefNum, LocsLibSelLocsType* ioSelLocsP) 00124 SYS_TRAP (locsLibTrapLaunchSelDialogue); 00125 00126 // Location public custom functions: 00127 00128 /// Copy from one location data into another 00129 /// 00130 /// @param iLibRefNum: IN: Library reference number 00131 /// @param thisP: IN: Pointer to the location object to copy to 00132 /// @param iLocToCopyP IN: Pointer to the location to be copied 00133 extern void LocationCopy (UInt16 iLibRefNum, LocationType* thisP, const LocationType* iLocToCopyP) 00134 SYS_TRAP (locsLibTrapLocCopy); 00135 00136 /// Destructor for location objects 00137 /// 00138 /// @param iLibRefNum: IN: Library reference number 00139 /// @param thisP: IN: Pointer to the location object to destroy 00140 extern void LocationFinal (UInt16 iLibRefNum, LocationType* thisP) 00141 SYS_TRAP (locsLibTrapLocFinal); 00142 00143 /// Calculate the size in bytes of the location object with the name field size 00144 /// included, but without the size of the pointer to the name field. 00145 /// 00146 /// @param iLibRefNum: IN: Library reference number 00147 /// @param thisP: IN: Pointer to the location object to size 00148 /// @return Size in bytes 00149 extern UInt16 LocationGetSize (UInt16 iLibRefNum, const LocationType* thisP) 00150 SYS_TRAP (locsLibTrapLocGetSize); 00151 00152 /// Constructor for location objects; initialize the given location data 00153 /// structure. 00154 /// 00155 /// @param iLibRefNum: IN: Library reference number 00156 /// @param thisP: IN: Pointer to the location object to initialize 00157 extern void LocationInit (UInt16 iLibRefNum, LocationType* thisP) 00158 SYS_TRAP (locsLibTrapLocInit); 00159 00160 /// Determine if a given DST date is in the past relative to the current time 00161 /// 00162 /// @param iLibRefNum: IN: Library reference number 00163 /// @param iDstDateP: IN: Pointer to a DST date to use for determining if that 00164 /// date is in the past relative to the current time. 00165 /// @return True if given DST date is in the past. 00166 extern Boolean LocationIsDSTPast (UInt16 iLibRefNum, DSTType* iDstDateP) 00167 SYS_TRAP (locsLibTrapLocIsDSTPast); 00168 00169 /// Create a generic location using the given country and UTC values. 00170 /// 00171 /// @param iLibRefNum: IN: Library reference number 00172 /// @param thisP: IN: Pointer to the location object to initialize 00173 /// with generic location data 00174 /// @param iCountryCode: IN: Country code for generic location 00175 /// @param iUTC: IN: UTC (timezone is minutes east west of prime 00176 /// meridian) for generic location; also used to 00177 /// create the location name. 00178 /// @return errNone if success. 00179 extern Err LocationMakeGeneric (UInt16 iLibRefNum, LocationType* thisP, CountryType iCountryCode, Int16 iUTC) 00180 SYS_TRAP (locsLibTrapLocMakeGeneric); 00181 00182 /// Mutator for changing location name value 00183 /// 00184 /// @param iLibRefNum: IN: Library reference number 00185 /// @param thisP: IN: Pointer to the location object to change 00186 /// @param iNameP: IN: Pointer to the new name 00187 extern void LocationSetName (UInt16 iLibRefNum, LocationType* thisP, const Char* iNameP) 00188 SYS_TRAP (locsLibTrapLocSetName); 00189 00190 // LocationsDB public custom functions: 00191 00192 /// Modify a record and re-sort the db if needed. 00193 /// 00194 /// @param iLibRefNum: IN: Library reference number 00195 /// @param dbP: IN: Pointer to the given location database 00196 /// to be modified. 00197 /// @param ioRecordIndexP: I/O: Pointer to the record index of the location 00198 /// record to be modified. If the record is 00199 /// moved, this value is updated with the 00200 /// new index. 00201 /// @param iLocationP: IN: Pointer to the new location data that is 00202 /// used to update the record. 00203 /// 00204 /// @return errNone if success. 00205 extern Err LocDBChangeRecord (UInt16 iLibRefNum, DmOpenRef dbP, UInt16* ioRecordIndexP, const LocationType* iLocationP) 00206 SYS_TRAP (locsLibTrapDBChangeRecord); 00207 00208 /// Comparison function to be used with system sort routines. 00209 /// 00210 /// Note: the system sort functions, like SysQSort, treat the 00211 /// elements of the passed list as is; i.e.: instead of 00212 /// passing the elements to this function, pointers to 00213 /// the elements are passed. Thus, it is necessary to 00214 /// here to use double pointers and dereferencing to 00215 /// to compare the actual records. 00216 /// 00217 /// @param iLibRefNum: IN: Library reference number 00218 /// @param iRecord01P: IN: Pointer to the first location record. 00219 /// @param iRecord02P: IN: Pointer to the second location record. 00220 /// @param iFlags IN: Sort order. 00221 /// 00222 /// @return -n if 1st is lesser, +n if 2nd is lesser, 0 if the two are the same, 00223 /// except for DST data, which isn't compared. 00224 extern Int16 LocDBCompareRecordsSimple (UInt16 iLibRefNum, LocDBRecordType** iRecord01P, LocDBRecordType** iRecord02P, Int32 iFlags) 00225 SYS_TRAP (locsLibTrapDBCmpRecordsSimple); 00226 00227 /// This function will format and copy locked record (LocationType) data into another 00228 /// locationType 00229 /// 00230 /// @param iLibRefNum: IN: library reference number 00231 /// @param ioLocationP: I/O: Pointer to the location object that is 00232 /// filled with the converted record data. 00233 /// @param iRecordP: IN: Pointer to the record whose data is 00234 /// converted to the location object format. 00235 extern void LocDBConvertRecord (UInt16 iLibRefNum, LocationType* ioLocationP, const LocDBRecordType* iRecordP) 00236 SYS_TRAP (locsLibTrapDBConvertRecord); 00237 00238 /// Copy the data in a given location object into a given 00239 /// location db record format. Note: the caller must allocate enough memory to the 00240 /// record object to hold the location data! 00241 /// 00242 /// @param iLibRefNum: IN: Library reference number 00243 /// @param ioRecordP: I/O: Pointer to a record that is filled with 00244 /// the location object data. 00245 /// @param iLocationP: IN: Pointer to the location object whose data 00246 /// is copied to the record. 00247 extern void LocDBCopyLocation (UInt16 iLibRefNum, LocDBRecordType* ioRecordP, const LocationType* iLocationP) 00248 SYS_TRAP (locsLibTrapDBCopyLocation); 00249 00250 /// Deletes a record from the cities database. 00251 /// 00252 /// @param iLibRefNum: IN: Library reference number 00253 /// @param dbP: IN: Pointer to the database containing the record to delete. 00254 /// @param iRecordIndex: IN: Index of the record to delete. 00255 /// 00256 /// @return errNone if success. 00257 extern Err LocDBDeleteRecord (UInt16 iLibRefNum, DmOpenRef dbP, UInt16 iRecordIndex) 00258 SYS_TRAP (locsLibTrapDBDeleteRecord); 00259 00260 /// Finds a record having the custom bit set. 00261 /// 00262 /// @param iLibRefNum: IN: Library reference number 00263 /// @param iDbP: IN: Pointer to a locations record database. 00264 /// @param ioRecordIndex: I/O: Index of the record to begin searching from, 00265 /// and index of the found record. 00266 /// @param oRecordH: OUT: Pointer to the record handle; set by this 00267 /// function. 00268 /// 00269 /// @return Pointer to the record found or NULL. Caller is responsible 00270 /// for freeing record when done. 00271 extern LocDBRecordType* LocDBFindCustomRecord (UInt16 iLibRefNum, DmOpenRef iDbP, UInt16* ioRecordIndex, MemHandle* oRecordH) 00272 SYS_TRAP (locsLibTrapDBFindCustomRecord); 00273 00274 /// Returns the record index for the first record matching 00275 /// the given location data. 00276 /// 00277 /// @param iLibRefNum: IN: Library reference number 00278 /// @param dbP: IN: Pointer to the given cities database 00279 /// to search for a match. 00280 /// @param oRecordIndexP: OUT: Pointer to record index var to store the 00281 /// record index of the matching record found 00282 /// in the search. Set to dmMaxRecordIndex if 00283 /// no match is found. 00284 /// @param iMatchLocationP: IN: Pointer to the location data for which 00285 /// to find the first matching record in 00286 /// the given database. 00287 /// 00288 /// @return Error code for a failure, or errNone if success. If no match 00289 /// is found, the index value is set to the value dmMaxRecordIndex. 00290 extern Err LocDBFindFirst (UInt16 iLibRefNum, DmOpenRef dbP, UInt16* oRecordIndexP, LocDBRecordType* iMatchValueP) 00291 SYS_TRAP (locsLibTrapDBFindFirst); 00292 00293 /// Sequential search of the locations database records for a 00294 /// match to the given city name. 00295 /// 00296 /// @param iLibRefNum: IN: Library reference number 00297 /// @param dbP: IN: Pointer to the record db to search. 00298 /// @param oRecordIndexP: OUT: Pointer to an index var to set with the 00299 /// index of the matching record, or dmMaxRecordIndex 00300 /// if no match. 00301 /// @param iNameP: IN: Pointer to the name string for which to find a match. 00302 /// 00303 /// @return errNone if no problems. No match indicated by oRecordIndexP set to dmMaxRecordIndex. 00304 extern Err LocDBFindFirstByName (UInt16 iLibRefNum, DmOpenRef dbP, UInt16* oRecordIndexP, const Char* iNameP) 00305 SYS_TRAP (locsLibTrapDBFindFirstByName); 00306 00307 /// Sequential search of the locations database records for 00308 /// the first location matching the given country and UTC values. 00309 /// 00310 /// @param iLibRefNum: IN: Library reference number 00311 /// @param dbP: IN: Pointer to the record db to search. 00312 /// @param oRecordIndexP: OUT: Pointer to an index var to set with the 00313 /// index of the matching record, or dmMaxRecordIndex 00314 /// if no match. 00315 /// @param iCountry: IN: The country code for which to find a match. 00316 /// @param iUTC: IN: The UTC for which to find a match. 00317 /// 00318 /// @return errNone if no problems. No match indicated by oRecordIndexP set to dmMaxRecordIndex. 00319 extern Err LocDBFindFirstByUTCCountry (UInt16 iLibRefNum, DmOpenRef dbP, UInt16* oRecordIndexP, CountryType iCountry, Int16 iUTC) 00320 SYS_TRAP (locsLibTrapDBFindFirstByUTCCtry); 00321 00322 /// Returns the record index for the first record in the given 00323 /// list matching the given location data. 00324 /// 00325 /// Note: This complements the get list functions, which return 00326 /// a list of pointers to location records in a db. 00327 /// 00328 /// @param iLibRefNum: IN: Library reference number 00329 /// @param iLocsListItemsCount: IN: Number of record items in the list. 00330 /// @param iLocsListP: IN: Pointer to the list of location records. 00331 /// @param iMatchLocationP: IN: Pointer to the location data for which 00332 /// to find the first matching record in 00333 /// the given list. 00334 /// 00335 /// @return The index of the list item matching the given location, or 00336 /// if no match found, then dmMaxRecordIndex. 00337 extern UInt16 LocDBFindFirstInList (UInt16 iLibRefNum, UInt16 iLocsListItemsCount, LocDBRecordType** iLocsListP, const LocationType* iMatchLocationP) 00338 SYS_TRAP (locsLibTrapDBFindFirstInList); 00339 00340 /// Returns a handle to a list of pointers to location records 00341 /// having the custom bit set. It is the responsibility of the caller to free the 00342 /// memory for the returned list. 00343 /// 00344 /// @param iLibRefNum: IN: Library reference number 00345 /// @param iDbP: IN: Pointer to a locations record database. 00346 /// @param oListCount: OUT: Number of records found with custom bit set. 00347 /// 00348 /// @return Handle to the list of location record pointers or NULL. 00349 /// Note: Caller is repsonsible for freeing memory associated 00350 /// with the list of pointers to records. 00351 extern MemHandle LocDBGetCustomList (UInt16 iLibRefNum, DmOpenRef iDbP, UInt16* oListCount) 00352 SYS_TRAP (locsLibTrapDBGetCustomList); 00353 00354 /// Get an array of pointers to those records from the the given database. 00355 /// 00356 /// @param iLibRefNum: IN: Library reference number 00357 /// @param iDbP: IN: Pointer to an open locations database. 00358 /// @param oListCount: OUT: Pointer to the list count to be set with 00359 /// the number of items in the locations list. 00360 /// @param iCompareF: IN: Function pointer for the function to use 00361 /// when sorting the list. Pass NULL if the 00362 /// list should not be sorted. 00363 /// @param iCompareFlags: IN: Any flags for comparison/sort behavior. 00364 /// 00365 /// @return Pointer to the array of location data, or NULL. 00366 /// Note: Caller is responsible for freeing this memory. 00367 extern LocDBRecordType** LocDBGetRecordList (UInt16 iLibRefNum, DmOpenRef iDbP, UInt16* oListCount, CmpFuncPtr iCompareF, Int32 iCompareFlags) 00368 SYS_TRAP (locsLibTrapDBGetRecordList); 00369 00370 /// Returns a pointer to a locked record chunk in the given db. 00371 /// It is the responsibility of the caller to unlock and release the record 00372 /// when done using the record. It is must to call LocDBCovertRecordV20 to get 00373 /// formated data in another LocationType variable. 00374 /// 00375 /// @param iLibRefNum: IN: library reference number 00376 /// @param dbP: IN: Pointer to a database having the desired record. 00377 /// @param iRecordIndex: IN: Index of the record in the given db. 00378 /// @param oRecordHP: OUT: Pointer to the record handle; set by this function. 00379 /// 00380 /// @return Pointer to the locked record or NULL; if non-NULL, caller 00381 /// is responsible for unlocking and releasing the record. 00382 extern LocDBRecordType* LocDBGetRecord (UInt16 iLibRefNum, DmOpenRef dbP, UInt16 iRecordIndex, MemHandle* oRecordHP) 00383 SYS_TRAP (locsLibTrapDBGetRecord); 00384 00385 /// Open the default db and open and initialize the custom db. 00386 /// 00387 /// @param iLibRefNum: IN: library reference number 00388 /// @param oDefDbPP: OUT: Pointer to the default db pointer to initialize. 00389 /// @param oCusDbPP: OUT: Pointer to the custom db pointer to initialize. 00390 /// 00391 /// @return On success the default and custom db pointers are initialized. 00392 extern Err LocDBInitDBs (UInt16 iLibRefNum, DmOpenRef* oDefDbPP, DmOpenRef* oCusDbPP) 00393 SYS_TRAP (locsLibTrapDBInitDBs); 00394 00395 /// Generates a new record for the given database. 00396 /// 00397 /// @param iLibRefNum: IN: library reference number 00398 /// @param dbP: IN: Pointer to the given location database 00399 /// into which the location data is to be 00400 /// inserted as a new record. 00401 /// @param oRecordIndexP: OUT: Pointer to the given record index value 00402 /// to be initialized with the new location 00403 /// record's index. 00404 /// @param iLocationP: IN: Pointer to the given location data from 00405 /// which to generate the new location record. 00406 /// 00407 /// @return errNone if success. 00408 extern Err LocDBNewRecord (UInt16 iLibRefNum, DmOpenRef dbP, UInt16* oRecordIndexP, const LocationType* iLocationP) 00409 SYS_TRAP (locsLibTrapDBNewRecord); 00410 00411 /// Open the custom db and return the dbID and an initialized db pointer. 00412 /// 00413 /// @param iLibRefNum: IN: library reference number 00414 /// @param iDbInfoP: IN: Pointer to a database info struct having db 00415 /// name, crid, type, and card number. 00416 /// @param iOpenMode: IN: Read and write mode to open the database for. 00417 /// @param oDbPP: OUT: Pointer to a db reference that is set by this 00418 /// function. 00419 /// @param iDefDbP: IN: Pointer to the default db from which to init 00420 /// the custom db if necessary. Initialization 00421 /// occurs if the custom db must be created, and 00422 /// then any records marked as custom in the given 00423 /// default db are copied into the custom db. 00424 /// 00425 /// @return Zero (0) on failure the dbP is set to NULL; the database ID 00426 /// is returned on success and the dbP is set to the address 00427 /// of the database. 00428 extern LocalID LocDBOpenCustom (UInt16 iLibRefNum, const LocDBInfoType* iDbInfoP, UInt16 iOpenMode, DmOpenRef* oDbPP, const DmOpenRef iDefDbP) 00429 SYS_TRAP (locsLibTrapDBOpenCustom); 00430 00431 /// Open the default db and return the dbID and an initialized db pointer. 00432 /// 00433 /// @param iLibRefNum: IN: library reference number 00434 /// @param oDbPP: OUT: Pointer to a db reference that is set by this 00435 /// function. 00436 /// 00437 /// @return Error code (errNone if successful). Zero (0) on failure 00438 /// and the dbP is set to NULL; occurs if the default db isn't 00439 /// found and the install from ROM fails. The database ID is 00440 /// returned on success and the dbP is set to the address 00441 /// of the database. 00442 extern LocalID LocDBOpenDefault (UInt16 iLibRefNum, DmOpenRef* oDbPP) 00443 SYS_TRAP (locsLibTrapDBOpenDefault); 00444 00445 /// Determines the size in bytes of a record. 00446 /// 00447 /// @param iLibRefNum: IN: library reference number 00448 /// @param iLocRecordP: IN: Pointer to the record for which to 00449 /// determine the size. 00450 /// 00451 /// @return Size of the given record in bytes. 00452 extern UInt16 LocDBRecordSize (UInt16 iLibRefNum, const LocDBRecordType* iLocRecordP) 00453 SYS_TRAP (locsLibTrapDBRecordSize); 00454 00455 /// Set the custom field of the record. 00456 /// 00457 /// @param iLibRefNum: IN: library reference number 00458 /// @param ioLocRecordP: I/O: Pointer to the record for which to set the 00459 /// custom field. 00460 /// @param iValue: IN: Value to which the custom field is set. 00461 /// 00462 /// @return errNone if success. 00463 extern Err LocDBSetRecordCustom (UInt16 iLibRefNum, LocDBRecordType* ioLocRecordP, UInt8 iValue) 00464 SYS_TRAP (locsLibTrapDBSetRecordCustom); 00465 00466 /// Sorts the given location data database. 00467 /// 00468 /// @param iLibRefNum: IN: library reference number 00469 /// @param iDbP: IN: Pointer to the location db to sort. 00470 /// @param iSortOrder: IN: Sort order desired. 00471 /// 00472 /// @return errNone if success. 00473 extern Err LocDBSort (UInt16 iLibRefNum, DmOpenRef iDbP, LocDBSortOrderType iSortOrder) 00474 SYS_TRAP (locsLibTrapDBSort); 00475 00476 // LocsLibDSTAlarm public functions: 00477 00478 /// Clear an existing DST alert alarm from the system. 00479 /// 00480 /// @param iLibRefNum: IN: library reference number 00481 extern void LocsLibDSTAlarmClear (UInt16 iLibRefNum) 00482 SYS_TRAP (locsLibTrapDSTAlarmClear); 00483 00484 /// Check if the current time is within a daylight saving time range. 00485 /// 00486 /// @param iLibRefNum: IN: library reference number 00487 /// @param iDSTStartP: IN: Pointer to the start DST date. 00488 /// @param iDSTEndP: IN: Pointer to the end DST date. 00489 /// @param iTimeInSecs: IN: The time in seconds against which to check 00490 /// the given DST date range. 00491 /// 00492 /// @return True if in the DST range. 00493 extern Boolean LocsLibDSTAlarmIsDST (UInt16 iLibRefNum, const DSTType* iDSTStartP, const DSTType* iDSTEndP, UInt32 iTimeInSecs) 00494 SYS_TRAP (locsLibTrapDSTAlarmIsDST); 00495 00496 /// Set the DST alert alarm to the given DST date. 00497 /// 00498 /// @param iLibRefNum: IN: library reference number 00499 /// @param iDstP: IN: Pointer to the DST date data. 00500 /// 00501 /// @return Time in seconds for which the DST alert was set, or 00502 /// 0 if not set (e.g.: if the given DST date data indicates DST is not observed). 00503 extern UInt32 LocsLibDSTAlarmSet (UInt16 iLibRefNum, const DSTType* iDstStartP, const DSTType* iDstEndP) 00504 SYS_TRAP (locsLibTrapDSTAlarmSet); 00505 00506 /// Generates a new record for the given database. 00507 /// 00508 /// @param iLibRefNum: IN: library reference number 00509 /// @param dbP: IN: Pointer to the given location database 00510 /// into which the location data is to be 00511 /// inserted as a new record. 00512 /// @param oRecordIndexP: OUT: Pointer to the given record index value 00513 /// to be initialized with the new location 00514 /// record's index. 00515 /// @param iLocationP: IN: Pointer to the given location data from 00516 /// which to generate the new location record. 00517 /// 00518 /// @return errNone if success. 00519 extern Err LocDBNewRecordV20 (UInt16 iLibRefNum, DmOpenRef dbP, UInt16* oRecordIndexP, LocationType* iLocationP) 00520 SYS_TRAP (locsLibTrapLocDBNewRecordV20); 00521 00522 /// Returns a pointer to a locked record chunk in the given db. 00523 /// It is the responsibility of the caller to unlock and release the record 00524 /// when done using the record. It is must to call LocDBCovertRecordV20 to get 00525 /// formated data in another LocationType variable. 00526 /// 00527 /// @param iLibRefNum: IN: library reference number 00528 /// @param dbP: IN: Pointer to a database having the desired record. 00529 /// @param iRecordIndex: IN: Index of the record in the given db. 00530 /// @param oRecordHP: OUT: Pointer to the record handle; set by this function. 00531 /// 00532 /// @return Pointer to the locked record or NULL; if non-NULL, caller 00533 /// is responsible for unlocking and releasing the record. 00534 extern LocationType* LocDBGetRecordV20 (UInt16 iLibRefNum, DmOpenRef dbP, UInt16 iRecordIndex, MemHandle* oRecordHP) 00535 SYS_TRAP (locsLibTrapLocDBGetRecordV20); 00536 00537 /// This function will format and copy locked record (LocationType) data into another 00538 /// locationType 00539 /// 00540 /// @param iLibRefNum: IN: library reference number 00541 /// @param destRecordP: IN: Pointer to the location object that is 00542 /// filled with the converted record data. 00543 /// @param srcRecordP: IN: Pointer to the record whose data is 00544 /// converted to the location object format. 00545 extern void LocDBConvertRecordV20 (UInt16 iLibRefNum, LocationType* destRecordP, const LocationType* srcRecordP) 00546 SYS_TRAP (locsLibTrapLocDBConvertRecordV20); 00547 00548 /// Modify a record and re-sort the db if needed. 00549 /// 00550 /// @param iLibRefNum: IN: Library reference number 00551 /// @param dbP: IN: Pointer to the given location database 00552 /// to be modified. 00553 /// @param ioRecordIndexP: I/O: Pointer to the record index of the location 00554 /// record to be modified. If the record is 00555 /// moved, this value is updated with the 00556 /// new index. 00557 /// @param iLocationP: IN: Pointer to the new location data that is 00558 /// used to update the record. 00559 /// 00560 /// @return errNone if success. 00561 extern Err LocDBChangeRecordV20 (UInt16 iLibRefNum, DmOpenRef dbP, UInt16* ioRecordIndexP, LocationType* iLocationP) 00562 SYS_TRAP (locsLibTrapLocDBChangeRecordV20); 00563 00564 /// Get an array of pointers to those records from the the given database. 00565 /// 00566 /// @param iLibRefNum: IN: Library reference number 00567 /// @param iDbP: IN: Pointer to an open locations database. 00568 /// @param oListCount: OUT: Pointer to the list count to be set with 00569 /// the number of items in the locations list. 00570 /// @param iCompareF: IN: Function pointer for the function to use 00571 /// when sorting the list. Pass NULL if the 00572 /// list should not be sorted. 00573 /// @param iCompareFlags: IN: Any flags for comparison/sort behavior. 00574 /// 00575 /// @return Pointer to the array of location data, or NULL. 00576 /// Note: Caller is responsible for freeing this memory. 00577 extern LocationType** LocDBGetRecordListV20 (UInt16 iLibRefNum, DmOpenRef iDbP, UInt16* oListCount, CmpFuncPtr iCompareF, Int32 iCompareFlags) 00578 SYS_TRAP (locsLibTrapLocDBGetRecordListV20); 00579 00580 /// Get a valid location from the locations DB nearest to the 00581 /// location specified 00582 /// 00583 /// @param iLibRefNum: IN: Library reference number 00584 /// @param iDefDb: IN: Reference to default location database 00585 /// @param iCustDb: IN: Reference to custom location database 00586 /// @param iPosP: IN: Pointer to reference position 00587 /// @param oLocP: OUT: Pointer to location, nearest city will 00588 /// return in this pointer 00589 /// @return Error if database not found. 00590 extern Err LocDBGetNearestLocation (UInt16 iLibRefNum,DmOpenRef iDb1P,DmOpenRef iDb2P,PosType* iPosP,LocationType* oLocP) 00591 SYS_TRAP (locsLibTrapLocDBGetNearestLocation); 00592 00593 /// Constructor for location objects v 2.0 (support for note); initialize the 00594 /// given location data structure. 00595 /// 00596 /// @param iLibRefNum: IN: Library reference number 00597 /// @param thisP: IN: Pointer to the location object to initialize 00598 extern void LocationInitV20 (UInt16 iLibRefNum, LocationType* thisP) 00599 SYS_TRAP (locsLibTrapLocationInitV20); 00600 00601 /// Destructor for location objects v 2.0 (support for note) 00602 /// 00603 /// @param iLibRefNum: IN: Library reference number 00604 /// @param thisP: IN: Pointer to the location object to destroy 00605 extern void LocationFinalV20 (UInt16 iLibRefNum, LocationType* thisP) 00606 SYS_TRAP (locsLibTrapLocationFinalV20); 00607 00608 /// Get version of database 00609 /// 00610 /// @param iLibRefNum: IN: Library reference number 00611 /// @param cardNo: IN: cardNo for database 00612 /// @param dbNameP: IN: Pointer to database name to search 00613 /// @param versionP: OUT: Pointer to version, version no will return 00614 /// in this variable 00615 /// 00616 /// @return Error if database not found. 00617 extern Err LocDBGetVersion (UInt16 iLibRefNum, UInt16 cardNo, const Char *dbNameP, UInt16 *version) 00618 SYS_TRAP (locsLibTrapLocDBGetVersion); 00619 00620 /// Copy note to location note field 00621 /// 00622 /// @param iLibRefNum: IN: Library reference number 00623 /// @param thisP: IN: Pointer to the location object to change. 00624 /// @param iNoteP: IN: Pointer to the new note. 00625 extern void LocationSetNote (UInt16 iLibRefNum, LocationType* thisP, const Char* iNameP) 00626 SYS_TRAP (locsLibTrapLocationSetNote); 00627 00628 /// Initialize position values of location 00629 /// 00630 /// @param iLibRefNum: IN: Library reference number 00631 /// @param thisP: IN: Pointer to the city object to initialize. 00632 /// @param iPosP: IN: Pointer to PosType to set values of location 00633 extern void LocationSetPosition (UInt16 iLibRefNum, LocationType* thisP, const PosType* iPosP) 00634 SYS_TRAP (locsLibTrapLocationSetPosition); 00635 00636 00637 extern Boolean LocsLibLocationNote (UInt16 iLibRefNum, const Char* iNameP, Boolean noteStatus) 00638 SYS_TRAP (locsLibTrapLocsLibLocationNote); 00639 00640 /// Calculate the size in bytes of the location object with the name and note field size 00641 /// included, but without the size of the pointer to the name and note field. 00642 /// 00643 /// @param iLibRefNum: IN: Library reference number 00644 /// @param locationP: IN: Pointer to the location object to size 00645 /// @return Size in bytes 00646 extern UInt16 LocationGetSizeV20 (UInt16 iLibRefNum, LocationType* locationP) 00647 SYS_TRAP (locsLibTrapLocationGetSizeV20); 00648 00649 // Location public custom functions: 00650 00651 /// Copy from one location data into another 00652 /// 00653 /// @param iLibRefNum: IN: Library reference number 00654 /// @param thisP: IN: Pointer to the location object to copy to 00655 /// @param iLocToCopyP IN: Pointer to the location to be copied 00656 extern void LocationCopyV20 (UInt16 iLibRefNum, LocationType* thisP, const LocationType* iLocToCopyP) 00657 SYS_TRAP (locsLibTrapLocationCopyV20); 00658 00659 /// Finds a record having the custom bit set. 00660 /// 00661 /// @param iLibRefNum: IN: Library reference number 00662 /// @param iDbP: IN: Pointer to a locations record database. 00663 /// @param ioRecordIndex: I/O: Index of the record to begin searching from, 00664 /// and index of the found record. 00665 /// @param oRecordH: OUT: Pointer to the record handle; set by this 00666 /// function. 00667 /// 00668 /// @return Pointer to the record found or NULL. Caller is responsible 00669 /// for freeing record when done. 00670 extern LocationType* LocDBFindCustomRecordV20 (UInt16 iLibRefNum, DmOpenRef iDbP, UInt16* ioRecordIndex, MemHandle* oRecordH) 00671 SYS_TRAP (locsLibTrapLocDBFindCustomRecordV20); 00672 00673 00674 #ifdef __cplusplus 00675 } 00676 #endif 00677 00678 00679 00680 #endif 00681 00682 00683 /****************************************************************************** 00684 * 00685 * END LocsLib.h 00686 * 00687 *****************************************************************************/
| Top | Palm Developer Network © 2004-2008, Palm, Inc. All rights reserved. Generated on Fri Jun 13 10:06:54 2008 for Palm API Guide |