API Guide Home (Online version only) |

# 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

- Err LocsLibOpen (UInt16 iLibRefNum)
- Err LocsLibClose (UInt16 iLibRefNum)
- Err LocsLibSleep (UInt16 iLibRefNum)
- Err LocsLibWake (UInt16 iLibRefNum)
- Err LocsLibGetVersion (UInt16 iLibRefNum, UInt32 iSDKVersion, UInt32 *oVersionP)
- Boolean LocsLibLaunchEditListDialogue (UInt16 iLibRefNum, LocsLibSelLocsType *ioSelLocsP)
- Boolean LocsLibLaunchSelDialogue (UInt16 iLibRefNum, LocsLibSelLocsType *ioSelLocsP)
- void LocationCopy (UInt16 iLibRefNum, LocationType *thisP, const LocationType *iLocToCopyP)
- void LocationFinal (UInt16 iLibRefNum, LocationType *thisP)
- UInt16 LocationGetSize (UInt16 iLibRefNum, const LocationType *thisP)
- void LocationInit (UInt16 iLibRefNum, LocationType *thisP)
- Boolean LocationIsDSTPast (UInt16 iLibRefNum, DSTType *iDstDateP)
- Err LocationMakeGeneric (UInt16 iLibRefNum, LocationType *thisP, CountryType iCountryCode, Int16 iUTC)
- void LocationSetName (UInt16 iLibRefNum, LocationType *thisP, const Char *iNameP)
- Err LocDBChangeRecord (UInt16 iLibRefNum, DmOpenRef dbP, UInt16 *ioRecordIndexP, const LocationType *iLocationP)
- Int16 LocDBCompareRecordsSimple (UInt16 iLibRefNum, LocDBRecordType **iRecord01P, LocDBRecordType **iRecord02P, Int32 iFlags)
- void LocDBConvertRecord (UInt16 iLibRefNum, LocationType *ioLocationP, const LocDBRecordType *iRecordP)
- void LocDBCopyLocation (UInt16 iLibRefNum, LocDBRecordType *ioRecordP, const LocationType *iLocationP)
- Err LocDBDeleteRecord (UInt16 iLibRefNum, DmOpenRef dbP, UInt16 iRecordIndex)
- LocDBRecordType * LocDBFindCustomRecord (UInt16 iLibRefNum, DmOpenRef iDbP, UInt16 *ioRecordIndex, MemHandle *oRecordH)
- Err LocDBFindFirst (UInt16 iLibRefNum, DmOpenRef dbP, UInt16 *oRecordIndexP, LocDBRecordType *iMatchValueP)
- Err LocDBFindFirstByName (UInt16 iLibRefNum, DmOpenRef dbP, UInt16 *oRecordIndexP, const Char *iNameP)
- Err LocDBFindFirstByUTCCountry (UInt16 iLibRefNum, DmOpenRef dbP, UInt16 *oRecordIndexP, CountryType iCountry, Int16 iUTC)
- UInt16 LocDBFindFirstInList (UInt16 iLibRefNum, UInt16 iLocsListItemsCount, LocDBRecordType **iLocsListP, const LocationType *iMatchLocationP)
- MemHandle LocDBGetCustomList (UInt16 iLibRefNum, DmOpenRef iDbP, UInt16 *oListCount)
- LocDBRecordType ** LocDBGetRecordList (UInt16 iLibRefNum, DmOpenRef iDbP, UInt16 *oListCount, CmpFuncPtr iCompareF, Int32 iCompareFlags)
- LocDBRecordType * LocDBGetRecord (UInt16 iLibRefNum, DmOpenRef dbP, UInt16 iRecordIndex, MemHandle *oRecordHP)
- Err LocDBInitDBs (UInt16 iLibRefNum, DmOpenRef *oDefDbPP, DmOpenRef *oCusDbPP)
- Err LocDBNewRecord (UInt16 iLibRefNum, DmOpenRef dbP, UInt16 *oRecordIndexP, const LocationType *iLocationP)
- LocalID LocDBOpenCustom (UInt16 iLibRefNum, const LocDBInfoType *iDbInfoP, UInt16 iOpenMode, DmOpenRef *oDbPP, const DmOpenRef iDefDbP)
- LocalID LocDBOpenDefault (UInt16 iLibRefNum, DmOpenRef *oDbPP)
- UInt16 LocDBRecordSize (UInt16 iLibRefNum, const LocDBRecordType *iLocRecordP)
- Err LocDBSetRecordCustom (UInt16 iLibRefNum, LocDBRecordType *ioLocRecordP, UInt8 iValue)
- Err LocDBSort (UInt16 iLibRefNum, DmOpenRef iDbP, LocDBSortOrderType iSortOrder)
- void LocsLibDSTAlarmClear (UInt16 iLibRefNum)
- Boolean LocsLibDSTAlarmIsDST (UInt16 iLibRefNum, const DSTType *iDSTStartP, const DSTType *iDSTEndP, UInt32 iTimeInSecs)
- UInt32 LocsLibDSTAlarmSet (UInt16 iLibRefNum, const DSTType *iDstStartP, const DSTType *iDstEndP)
- Err LocDBNewRecordV20 (UInt16 iLibRefNum, DmOpenRef dbP, UInt16 *oRecordIndexP, LocationType *iLocationP)
- LocationType * LocDBGetRecordV20 (UInt16 iLibRefNum, DmOpenRef dbP, UInt16 iRecordIndex, MemHandle *oRecordHP)
- void LocDBConvertRecordV20 (UInt16 iLibRefNum, LocationType *destRecordP, const LocationType *srcRecordP)
- Err LocDBChangeRecordV20 (UInt16 iLibRefNum, DmOpenRef dbP, UInt16 *ioRecordIndexP, LocationType *iLocationP)
- LocationType ** LocDBGetRecordListV20 (UInt16 iLibRefNum, DmOpenRef iDbP, UInt16 *oListCount, CmpFuncPtr iCompareF, Int32 iCompareFlags)
- Err LocDBGetNearestLocation (UInt16 iLibRefNum, DmOpenRef iDb1P, DmOpenRef iDb2P, PosType *iPosP, LocationType *oLocP)
- void LocationInitV20 (UInt16 iLibRefNum, LocationType *thisP)
- void LocationFinalV20 (UInt16 iLibRefNum, LocationType *thisP)
- Err LocDBGetVersion (UInt16 iLibRefNum, UInt16 cardNo, const Char *dbNameP, UInt16 *version)
- void LocationSetNote (UInt16 iLibRefNum, LocationType *thisP, const Char *iNameP)
- void LocationSetPosition (UInt16 iLibRefNum, LocationType *thisP, const PosType *iPosP)
- Boolean LocsLibLocationNote (UInt16 iLibRefNum, const Char *iNameP, Boolean noteStatus)
- UInt16 LocationGetSizeV20 (UInt16 iLibRefNum, LocationType *locationP)
- void LocationCopyV20 (UInt16 iLibRefNum, LocationType *thisP, const LocationType *iLocToCopyP)
- LocationType * LocDBFindCustomRecordV20 (UInt16 iLibRefNum, DmOpenRef iDbP, UInt16 *ioRecordIndex, MemHandle *oRecordH)

## 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