API Guide Home (Online version only) |

# LocsLib.h

Go to the documentation of this file.

    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