API Guide Home
(Online version only)

Header Files » Incs » 68k » libraries » locs

LocsLib.h File Reference

Detailed Description

Public 68K include file for location/timezone/DST support on Palm devices.

Definition in file LocsLib.h.

Include dependency graph for LocsLib.h:

Go to the source code of this file.

Functions

Function Documentation

void LocationCopy ( UInt16  iLibRefNum,
LocationType *  thisP,
const LocationType *  iLocToCopyP 
)

Copy from one location data into another

Parameters:
iLibRefNum,: IN: Library reference number
thisP,: IN: Pointer to the location object to copy to
iLocToCopyP IN: Pointer to the location to be copied

void LocationCopyV20 ( UInt16  iLibRefNum,
LocationType *  thisP,
const LocationType *  iLocToCopyP 
)

Copy from one location data into another

Parameters:
iLibRefNum,: IN: Library reference number
thisP,: IN: Pointer to the location object to copy to
iLocToCopyP IN: Pointer to the location to be copied

void LocationFinal ( UInt16  iLibRefNum,
LocationType *  thisP 
)

Destructor for location objects

Parameters:
iLibRefNum,: IN: Library reference number
thisP,: IN: Pointer to the location object to destroy

void LocationFinalV20 ( UInt16  iLibRefNum,
LocationType *  thisP 
)

Destructor for location objects v 2.0 (support for note)

Parameters:
iLibRefNum,: IN: Library reference number
thisP,: IN: Pointer to the location object to destroy

UInt16 LocationGetSize ( UInt16  iLibRefNum,
const LocationType *  thisP 
)

Calculate the size in bytes of the location object with the name field size included, but without the size of the pointer to the name field.

Parameters:
iLibRefNum,: IN: Library reference number
thisP,: IN: Pointer to the location object to size
Returns:
Size in bytes

UInt16 LocationGetSizeV20 ( UInt16  iLibRefNum,
LocationType *  locationP 
)

Calculate the size in bytes of the location object with the name and note field size included, but without the size of the pointer to the name and note field.

Parameters:
iLibRefNum,: IN: Library reference number
locationP,: IN: Pointer to the location object to size
Returns:
Size in bytes

void LocationInit ( UInt16  iLibRefNum,
LocationType *  thisP 
)

Constructor for location objects; initialize the given location data structure.

Parameters:
iLibRefNum,: IN: Library reference number
thisP,: IN: Pointer to the location object to initialize

void LocationInitV20 ( UInt16  iLibRefNum,
LocationType *  thisP 
)

Constructor for location objects v 2.0 (support for note); initialize the given location data structure.

Parameters:
iLibRefNum,: IN: Library reference number
thisP,: IN: Pointer to the location object to initialize

Boolean LocationIsDSTPast ( UInt16  iLibRefNum,
DSTType *  iDstDateP 
)

Determine if a given DST date is in the past relative to the current time

Parameters:
iLibRefNum,: IN: Library reference number
iDstDateP,: IN: Pointer to a DST date to use for determining if that date is in the past relative to the current time.
Returns:
True if given DST date is in the past.

Err LocationMakeGeneric ( UInt16  iLibRefNum,
LocationType *  thisP,
CountryType  iCountryCode,
Int16  iUTC 
)

Create a generic location using the given country and UTC values.

Parameters:
iLibRefNum,: IN: Library reference number
thisP,: IN: Pointer to the location object to initialize with generic location data
iCountryCode,: IN: Country code for generic location
iUTC,: IN: UTC (timezone is minutes east west of prime meridian) for generic location; also used to create the location name.
Returns:
errNone if success.

void LocationSetName ( UInt16  iLibRefNum,
LocationType *  thisP,
const Char *  iNameP 
)

Mutator for changing location name value

Parameters:
iLibRefNum,: IN: Library reference number
thisP,: IN: Pointer to the location object to change
iNameP,: IN: Pointer to the new name

void LocationSetNote ( UInt16  iLibRefNum,
LocationType *  thisP,
const Char *  iNameP 
)

Copy note to location note field

Parameters:
iLibRefNum,: IN: Library reference number
thisP,: IN: Pointer to the location object to change.
iNoteP,: IN: Pointer to the new note.

void LocationSetPosition ( UInt16  iLibRefNum,
LocationType *  thisP,
const PosType *  iPosP 
)

Initialize position values of location

Parameters:
iLibRefNum,: IN: Library reference number
thisP,: IN: Pointer to the city object to initialize.
iPosP,: IN: Pointer to PosType to set values of location

Err LocDBChangeRecord ( UInt16  iLibRefNum,
DmOpenRef  dbP,
UInt16 *  ioRecordIndexP,
const LocationType *  iLocationP 
)

Modify a record and re-sort the db if needed.

Parameters:
iLibRefNum,: IN: Library reference number
dbP,: IN: Pointer to the given location database to be modified.
ioRecordIndexP,: I/O: Pointer to the record index of the location record to be modified. If the record is moved, this value is updated with the new index.
iLocationP,: IN: Pointer to the new location data that is used to update the record.
Returns:
errNone if success.

Err LocDBChangeRecordV20 ( UInt16  iLibRefNum,
DmOpenRef  dbP,
UInt16 *  ioRecordIndexP,
LocationType *  iLocationP 
)

Modify a record and re-sort the db if needed.

Parameters:
iLibRefNum,: IN: Library reference number
dbP,: IN: Pointer to the given location database to be modified.
ioRecordIndexP,: I/O: Pointer to the record index of the location record to be modified. If the record is moved, this value is updated with the new index.
iLocationP,: IN: Pointer to the new location data that is used to update the record.
Returns:
errNone if success.

Int16 LocDBCompareRecordsSimple ( UInt16  iLibRefNum,
LocDBRecordType **  iRecord01P,
LocDBRecordType **  iRecord02P,
Int32  iFlags 
)

Comparison function to be used with system sort routines.

Note: the system sort functions, like SysQSort, treat the elements of the passed list as is; i.e.: instead of passing the elements to this function, pointers to the elements are passed. Thus, it is necessary to here to use double pointers and dereferencing to to compare the actual records.

Parameters:
iLibRefNum,: IN: Library reference number
iRecord01P,: IN: Pointer to the first location record.
iRecord02P,: IN: Pointer to the second location record.
iFlags IN: Sort order.
Returns:
-n if 1st is lesser, +n if 2nd is lesser, 0 if the two are the same, except for DST data, which isn't compared.

void LocDBConvertRecord ( UInt16  iLibRefNum,
LocationType *  ioLocationP,
const LocDBRecordType *  iRecordP 
)

This function will format and copy locked record (LocationType) data into another locationType

Parameters:
iLibRefNum,: IN: library reference number
ioLocationP,: I/O: Pointer to the location object that is filled with the converted record data.
iRecordP,: IN: Pointer to the record whose data is converted to the location object format.

void LocDBConvertRecordV20 ( UInt16  iLibRefNum,
LocationType *  destRecordP,
const LocationType *  srcRecordP 
)

This function will format and copy locked record (LocationType) data into another locationType

Parameters:
iLibRefNum,: IN: library reference number
destRecordP,: IN: Pointer to the location object that is filled with the converted record data.
srcRecordP,: IN: Pointer to the record whose data is converted to the location object format.

void LocDBCopyLocation ( UInt16  iLibRefNum,
LocDBRecordType *  ioRecordP,
const LocationType *  iLocationP 
)

Copy the data in a given location object into a given location db record format. Note: the caller must allocate enough memory to the record object to hold the location data!

Parameters:
iLibRefNum,: IN: Library reference number
ioRecordP,: I/O: Pointer to a record that is filled with the location object data.
iLocationP,: IN: Pointer to the location object whose data is copied to the record.

Err LocDBDeleteRecord ( UInt16  iLibRefNum,
DmOpenRef  dbP,
UInt16  iRecordIndex 
)

Deletes a record from the cities database.

Parameters:
iLibRefNum,: IN: Library reference number
dbP,: IN: Pointer to the database containing the record to delete.
iRecordIndex,: IN: Index of the record to delete.
Returns:
errNone if success.

LocDBRecordType* LocDBFindCustomRecord ( UInt16  iLibRefNum,
DmOpenRef  iDbP,
UInt16 *  ioRecordIndex,
MemHandle *  oRecordH 
)

Finds a record having the custom bit set.

Parameters:
iLibRefNum,: IN: Library reference number
iDbP,: IN: Pointer to a locations record database.
ioRecordIndex,: I/O: Index of the record to begin searching from, and index of the found record.
oRecordH,: OUT: Pointer to the record handle; set by this function.
Returns:
Pointer to the record found or NULL. Caller is responsible for freeing record when done.

LocationType* LocDBFindCustomRecordV20 ( UInt16  iLibRefNum,
DmOpenRef  iDbP,
UInt16 *  ioRecordIndex,
MemHandle *  oRecordH 
)

Finds a record having the custom bit set.

Parameters:
iLibRefNum,: IN: Library reference number
iDbP,: IN: Pointer to a locations record database.
ioRecordIndex,: I/O: Index of the record to begin searching from, and index of the found record.
oRecordH,: OUT: Pointer to the record handle; set by this function.
Returns:
Pointer to the record found or NULL. Caller is responsible for freeing record when done.

Err LocDBFindFirst ( UInt16  iLibRefNum,
DmOpenRef  dbP,
UInt16 *  oRecordIndexP,
LocDBRecordType *  iMatchValueP 
)

Returns the record index for the first record matching the given location data.

Parameters:
iLibRefNum,: IN: Library reference number
dbP,: IN: Pointer to the given cities database to search for a match.
oRecordIndexP,: OUT: Pointer to record index var to store the record index of the matching record found in the search. Set to dmMaxRecordIndex if no match is found.
iMatchLocationP,: IN: Pointer to the location data for which to find the first matching record in the given database.
Returns:
Error code for a failure, or errNone if success. If no match is found, the index value is set to the value dmMaxRecordIndex.

Err LocDBFindFirstByName ( UInt16  iLibRefNum,
DmOpenRef  dbP,
UInt16 *  oRecordIndexP,
const Char *  iNameP 
)

Sequential search of the locations database records for a match to the given city name.

Parameters:
iLibRefNum,: IN: Library reference number
dbP,: IN: Pointer to the record db to search.
oRecordIndexP,: OUT: Pointer to an index var to set with the index of the matching record, or dmMaxRecordIndex if no match.
iNameP,: IN: Pointer to the name string for which to find a match.
Returns:
errNone if no problems. No match indicated by oRecordIndexP set to dmMaxRecordIndex.

Err LocDBFindFirstByUTCCountry ( UInt16  iLibRefNum,
DmOpenRef  dbP,
UInt16 *  oRecordIndexP,
CountryType  iCountry,
Int16  iUTC 
)

Sequential search of the locations database records for the first location matching the given country and UTC values.

Parameters:
iLibRefNum,: IN: Library reference number
dbP,: IN: Pointer to the record db to search.
oRecordIndexP,: OUT: Pointer to an index var to set with the index of the matching record, or dmMaxRecordIndex if no match.
iCountry,: IN: The country code for which to find a match.
iUTC,: IN: The UTC for which to find a match.
Returns:
errNone if no problems. No match indicated by oRecordIndexP set to dmMaxRecordIndex.

UInt16 LocDBFindFirstInList ( UInt16  iLibRefNum,
UInt16  iLocsListItemsCount,
LocDBRecordType **  iLocsListP,
const LocationType *  iMatchLocationP 
)

Returns the record index for the first record in the given list matching the given location data.

Note: This complements the get list functions, which return a list of pointers to location records in a db.

Parameters:
iLibRefNum,: IN: Library reference number
iLocsListItemsCount,: IN: Number of record items in the list.
iLocsListP,: IN: Pointer to the list of location records.
iMatchLocationP,: IN: Pointer to the location data for which to find the first matching record in the given list.
Returns:
The index of the list item matching the given location, or if no match found, then dmMaxRecordIndex.

MemHandle LocDBGetCustomList ( UInt16  iLibRefNum,
DmOpenRef  iDbP,
UInt16 *  oListCount 
)

Returns a handle to a list of pointers to location records having the custom bit set. It is the responsibility of the caller to free the memory for the returned list.

Parameters:
iLibRefNum,: IN: Library reference number
iDbP,: IN: Pointer to a locations record database.
oListCount,: OUT: Number of records found with custom bit set.
Returns:
Handle to the list of location record pointers or NULL. Note: Caller is repsonsible for freeing memory associated with the list of pointers to records.

Err LocDBGetNearestLocation ( UInt16  iLibRefNum,
DmOpenRef  iDb1P,
DmOpenRef  iDb2P,
PosType *  iPosP,
LocationType *  oLocP 
)

Get a valid location from the locations DB nearest to the location specified

Parameters:
iLibRefNum,: IN: Library reference number
iDefDb,: IN: Reference to default location database
iCustDb,: IN: Reference to custom location database
iPosP,: IN: Pointer to reference position
oLocP,: OUT: Pointer to location, nearest city will return in this pointer
Returns:
Error if database not found.

LocDBRecordType* LocDBGetRecord ( UInt16  iLibRefNum,
DmOpenRef  dbP,
UInt16  iRecordIndex,
MemHandle *  oRecordHP 
)

Returns a pointer to a locked record chunk in the given db. It is the responsibility of the caller to unlock and release the record when done using the record. It is must to call LocDBCovertRecordV20 to get formated data in another LocationType variable.

Parameters:
iLibRefNum,: IN: library reference number
dbP,: IN: Pointer to a database having the desired record.
iRecordIndex,: IN: Index of the record in the given db.
oRecordHP,: OUT: Pointer to the record handle; set by this function.
Returns:
Pointer to the locked record or NULL; if non-NULL, caller is responsible for unlocking and releasing the record.

LocDBRecordType** LocDBGetRecordList ( UInt16  iLibRefNum,
DmOpenRef  iDbP,
UInt16 *  oListCount,
CmpFuncPtr  iCompareF,
Int32  iCompareFlags 
)

Get an array of pointers to those records from the the given database.

Parameters:
iLibRefNum,: IN: Library reference number
iDbP,: IN: Pointer to an open locations database.
oListCount,: OUT: Pointer to the list count to be set with the number of items in the locations list.
iCompareF,: IN: Function pointer for the function to use when sorting the list. Pass NULL if the list should not be sorted.
iCompareFlags,: IN: Any flags for comparison/sort behavior.
Returns:
Pointer to the array of location data, or NULL. Note: Caller is responsible for freeing this memory.

LocationType** LocDBGetRecordListV20 ( UInt16  iLibRefNum,
DmOpenRef  iDbP,
UInt16 *  oListCount,
CmpFuncPtr  iCompareF,
Int32  iCompareFlags 
)

Get an array of pointers to those records from the the given database.

Parameters:
iLibRefNum,: IN: Library reference number
iDbP,: IN: Pointer to an open locations database.
oListCount,: OUT: Pointer to the list count to be set with the number of items in the locations list.
iCompareF,: IN: Function pointer for the function to use when sorting the list. Pass NULL if the list should not be sorted.
iCompareFlags,: IN: Any flags for comparison/sort behavior.
Returns:
Pointer to the array of location data, or NULL. Note: Caller is responsible for freeing this memory.

LocationType* LocDBGetRecordV20 ( UInt16  iLibRefNum,
DmOpenRef  dbP,
UInt16  iRecordIndex,
MemHandle *  oRecordHP 
)

Returns a pointer to a locked record chunk in the given db. It is the responsibility of the caller to unlock and release the record when done using the record. It is must to call LocDBCovertRecordV20 to get formated data in another LocationType variable.

Parameters:
iLibRefNum,: IN: library reference number
dbP,: IN: Pointer to a database having the desired record.
iRecordIndex,: IN: Index of the record in the given db.
oRecordHP,: OUT: Pointer to the record handle; set by this function.
Returns:
Pointer to the locked record or NULL; if non-NULL, caller is responsible for unlocking and releasing the record.

Err LocDBGetVersion ( UInt16  iLibRefNum,
UInt16  cardNo,
const Char *  dbNameP,
UInt16 *  version 
)

Get version of database

Parameters:
iLibRefNum,: IN: Library reference number
cardNo,: IN: cardNo for database
dbNameP,: IN: Pointer to database name to search
versionP,: OUT: Pointer to version, version no will return in this variable
Returns:
Error if database not found.

Err LocDBInitDBs ( UInt16  iLibRefNum,
DmOpenRef *  oDefDbPP,
DmOpenRef *  oCusDbPP 
)

Open the default db and open and initialize the custom db.

Parameters:
iLibRefNum,: IN: library reference number
oDefDbPP,: OUT: Pointer to the default db pointer to initialize.
oCusDbPP,: OUT: Pointer to the custom db pointer to initialize.
Returns:
On success the default and custom db pointers are initialized.

Err LocDBNewRecord ( UInt16  iLibRefNum,
DmOpenRef  dbP,
UInt16 *  oRecordIndexP,
const LocationType *  iLocationP 
)

Generates a new record for the given database.

Parameters:
iLibRefNum,: IN: library reference number
dbP,: IN: Pointer to the given location database into which the location data is to be inserted as a new record.
oRecordIndexP,: OUT: Pointer to the given record index value to be initialized with the new location record's index.
iLocationP,: IN: Pointer to the given location data from which to generate the new location record.
Returns:
errNone if success.

Err LocDBNewRecordV20 ( UInt16  iLibRefNum,
DmOpenRef  dbP,
UInt16 *  oRecordIndexP,
LocationType *  iLocationP 
)

Generates a new record for the given database.

Parameters:
iLibRefNum,: IN: library reference number
dbP,: IN: Pointer to the given location database into which the location data is to be inserted as a new record.
oRecordIndexP,: OUT: Pointer to the given record index value to be initialized with the new location record's index.
iLocationP,: IN: Pointer to the given location data from which to generate the new location record.
Returns:
errNone if success.

LocalID LocDBOpenCustom ( UInt16  iLibRefNum,
const LocDBInfoType *  iDbInfoP,
UInt16  iOpenMode,
DmOpenRef *  oDbPP,
const DmOpenRef  iDefDbP 
)

Open the custom db and return the dbID and an initialized db pointer.

Parameters:
iLibRefNum,: IN: library reference number
iDbInfoP,: IN: Pointer to a database info struct having db name, crid, type, and card number.
iOpenMode,: IN: Read and write mode to open the database for.
oDbPP,: OUT: Pointer to a db reference that is set by this function.
iDefDbP,: IN: Pointer to the default db from which to init the custom db if necessary. Initialization occurs if the custom db must be created, and then any records marked as custom in the given default db are copied into the custom db.
Returns:
Zero (0) on failure the dbP is set to NULL; the database ID is returned on success and the dbP is set to the address of the database.

LocalID LocDBOpenDefault ( UInt16  iLibRefNum,
DmOpenRef *  oDbPP 
)

Open the default db and return the dbID and an initialized db pointer.

Parameters:
iLibRefNum,: IN: library reference number
oDbPP,: OUT: Pointer to a db reference that is set by this function.
Returns:
Error code (errNone if successful). Zero (0) on failure and the dbP is set to NULL; occurs if the default db isn't found and the install from ROM fails. The database ID is returned on success and the dbP is set to the address of the database.

UInt16 LocDBRecordSize ( UInt16  iLibRefNum,
const LocDBRecordType *  iLocRecordP 
)

Determines the size in bytes of a record.

Parameters:
iLibRefNum,: IN: library reference number
iLocRecordP,: IN: Pointer to the record for which to determine the size.
Returns:
Size of the given record in bytes.

Err LocDBSetRecordCustom ( UInt16  iLibRefNum,
LocDBRecordType *  ioLocRecordP,
UInt8  iValue 
)

Set the custom field of the record.

Parameters:
iLibRefNum,: IN: library reference number
ioLocRecordP,: I/O: Pointer to the record for which to set the custom field.
iValue,: IN: Value to which the custom field is set.
Returns:
errNone if success.

Err LocDBSort ( UInt16  iLibRefNum,
DmOpenRef  iDbP,
LocDBSortOrderType  iSortOrder 
)

Sorts the given location data database.

Parameters:
iLibRefNum,: IN: library reference number
iDbP,: IN: Pointer to the location db to sort.
iSortOrder,: IN: Sort order desired.
Returns:
errNone if success.

Err LocsLibClose ( UInt16  iLibRefNum  ) 

Standard library close routine.

Parameters:
iLibRefNum,: IN: Library reference number.
Returns:
Error code.

void LocsLibDSTAlarmClear ( UInt16  iLibRefNum  ) 

Clear an existing DST alert alarm from the system.

Parameters:
iLibRefNum,: IN: library reference number

Boolean LocsLibDSTAlarmIsDST ( UInt16  iLibRefNum,
const DSTType *  iDSTStartP,
const DSTType *  iDSTEndP,
UInt32  iTimeInSecs 
)

Check if the current time is within a daylight saving time range.

Parameters:
iLibRefNum,: IN: library reference number
iDSTStartP,: IN: Pointer to the start DST date.
iDSTEndP,: IN: Pointer to the end DST date.
iTimeInSecs,: IN: The time in seconds against which to check the given DST date range.
Returns:
True if in the DST range.

UInt32 LocsLibDSTAlarmSet ( UInt16  iLibRefNum,
const DSTType *  iDstStartP,
const DSTType *  iDstEndP 
)

Set the DST alert alarm to the given DST date.

Parameters:
iLibRefNum,: IN: library reference number
iDstP,: IN: Pointer to the DST date data.
Returns:
Time in seconds for which the DST alert was set, or 0 if not set (e.g.: if the given DST date data indicates DST is not observed).

Err LocsLibGetVersion ( UInt16  iLibRefNum,
UInt32  iSDKVersion,
UInt32 *  oVersionP 
)

Get the version of the library on the device.

Parameters:
iLibRefNum,: IN: Library reference number.
iSDKVersion,: IN: Currently used library version in the SDK
oVersionP,: OUT: Version of the library on the device.
Returns:
Error code.

Boolean LocsLibLaunchEditListDialogue ( UInt16  iLibRefNum,
LocsLibSelLocsType *  ioSelLocsP 
)

Runs the event loop for handling the Locations dialogues. Note: the preSelect, noEditOnSelect, and sendChangeNotify values of the caller data block don't apply for this API.

Parameters:
iLibRefNum,: IN: Library reference number.
ioSelLocsP,: I/O: Pointer to a selected locations object that contains data on selected locations. e.g.: The Clock 2.0 app displays several selected locations and the associated times. If any of those locations are removed or renamed, the Clock 2.0 app needs to know so it can update the display. This object is updated if any of the selected locations are renamed or removed. Use the dirty bits to determine quickly if any data were changed and if so, which. Pass NULL to ignore.
Returns:
True if changes are made.

Boolean LocsLibLaunchSelDialogue ( UInt16  iLibRefNum,
LocsLibSelLocsType *  ioSelLocsP 
)

Run the location selection dialogue, and then the Edit Location dialogue if the user tapped [OK] in the location selection dialogue and if the caller didn't specify to skip that dialogue.

Parameters:
iLibRefNum,: IN: Library reference number.
ioSelLocsP,: I/O: Pointer to a selected locations object that contains data on selected locations. e.g.: The Clock 2.0 app displays several selected locations and the associated times. If any of those locations are removed or renamed, the Clock 2.0 app needs to know so it can update the display. This object is updated if any of the selected locations are renamed or removed. Use the dirty bits to determine quickly if any data were changed and if so, which. Must not be NULL.
Returns:
True if changes are made.

Boolean LocsLibLocationNote ( UInt16  iLibRefNum,
const Char *  iNameP,
Boolean  noteStatus 
)

Err LocsLibOpen ( UInt16  iLibRefNum  ) 

Standard library open routine.

Parameters:
iLibRefNum,: IN: Library reference number.
Returns:
Error code.

Err LocsLibSleep ( UInt16  iLibRefNum  ) 

Standard library sleep routine.

Parameters:
iLibRefNum,: IN: Library reference number.
Returns:
Error code.

Err LocsLibWake ( UInt16  iLibRefNum  ) 

Standard library wake routine.

Parameters:
iLibRefNum,: IN: Library reference number.
Returns:
Error code.

Top Palm Developer Network
© 2004-2008, Palm, Inc. All rights reserved.
Generated on Fri Jun 13 10:07:37 2008 for Palm API Guide