Utilities
[API's]

Functions

alp_status_t alp_contacts_dml_begin_modify_batch (AlpDmlH dmlH)

Wrapper for alp_hscm_begin_modify_batch.

alp_status_t alp_contacts_dml_cid_lookup (AlpDmlH dmlH, const char *lookupString, AlpLuid *personLuid, AlpLuid *contactLuid)

Given a lookup string as input, this routine searches all contact records in the data model for a matching Value field.

alp_status_t alp_contacts_dml_duplicate (AlpDmlH dmlH, AlpLuid srcContact, AlpLuid *dupedContact)

Duplicates the given contact returning, if successful, the new contact LUID.

alp_status_t alp_contacts_dml_end_modify_batch (AlpDmlH dmlH, bool batchSucceeded)

Wrapper for alp_hscm_begin_modify_batch.

alp_status_t alp_contacts_dml_event_statement_begin (AlpDmlH dmlH, uint32_t startDay, uint32_t startMonth, uint32_t endDay, uint32_t endMonth, uint32_t year, AlpDmlStatementH *personStmtH, int32_t *numResults)

alp_status_t alp_contacts_dml_event_statement_begin_with_columns (AlpDmlH dmlH, uint32_t startDay, uint32_t startMonth, uint32_t endDay, uint32_t endMonth, uint32_t year, const AlpContactsDmlColumnType *columnTypes, int16_t numColumnTypes, AlpDmlStatementH *personStmtH, int32_t *numResults)

alp_status_t alp_contacts_dml_get_category_ringtone (AlpDmlH dmlH, AlpLuid categoryLuid, AlpContactsDmlRingtoneType ringtoneType, char **ringtoneMFURL)

Retrieves any ringtone associated with the given category.

AlpDmlH alp_contacts_dml_get_catmgr_handle (AlpDmlH dmlH)

Returns an AlpDmlH that can be passed to Category Manager functions.

alp_status_t alp_contacts_dml_get_person_ringtone (AlpDmlH dmlH, AlpLuid personLuid, AlpContactsDmlRingtoneType ringtoneType, char **ringtoneFilePath)

Retrieves any ringtone associated with the given person. It will automatically search the person, its category, and finally default preferences for the appropriate ringtone.

alp_status_t alp_contacts_dml_get_thumbnail_sizes (uint32_t *largeWidth, uint32_t *largeHeight, uint32_t *smallWidth, uint32_t *smallHeight)

Returns the sizes used for thumbnail data.

alp_status_t alp_contacts_dml_get_version (AlpDmlH dmlH, int32_t *version)

alp_status_t alp_contacts_dml_listview_person_index (AlpDmlH dmlH, AlpLuid personLuid, AlpLuid categoryLuid, bool unfiled, AlpContactsDmlOrderByType orderBy, const char *filterBy, int32_t *index)

Given a set of list view creation criteria and a person luid calculate the index of the person in the list.

alp_status_t alp_contacts_dml_monitor_object (AlpDmlH dmlH, AlpLuid personLuid, AlpLuid *conflictLuid, AlpHsMonitorPtr *ppMonitor)

Creates an internal change manager object monitor for the given luid. The policy will be to create conflicts. If alp_contacts_dml_update returns ALP_STATUS_CONTACT_DML_CHANGEMGR_CONFLICT the conflictLuid pointer will be set.

alp_status_t alp_contacts_dml_person_get_name (AlpDmlStatementH personStmtH, AlpContactsDmlFormatNameType formatType, char **name)

Builds a Display Name.

alp_status_t alp_contacts_dml_persons_from_vCard_buffer (AlpDmlH dmlH, const uint8_t *dataBuf, int32_t dataBufSize, bool fromExgMgr, bool forModify, GList **personIDs) __attribute((deprecated))

Deprecated. Use alp_contacts_dml_read_from_vCard_buffer instead.

alp_status_t alp_contacts_dml_persons_from_vCard_file (AlpDmlH dmlH, int theDataFd, bool fromExgMgr, bool forModify, GList **personIDs) __attribute((deprecated))

Deprecated. Use alp_contacts_dml_read_from_vCard_file.

alp_status_t alp_contacts_dml_persons_to_vCard_buffer (AlpDmlH dmlH, uint8_t **dataBuf, int32_t *dataBufSize, bool toExgMgr, GList *personLuids) __attribute((deprecated))

Deprecated. Use alp_contacts_dml_write_to_vCard_buffer instead.

alp_status_t alp_contacts_dml_persons_to_vCard_file (AlpDmlH dmlH, int theDataFd, bool toExgMgr, GList *personLuids) __attribute((deprecated))

Deprecated. Use alp_contacts_dml_write_to_vCard_file instead.

alp_status_t alp_contacts_dml_read_from_vCard_buffer (AlpDmlH dmlH, const uint8_t *dataBuf, int32_t dataBufSize, bool fromExgMgr, bool forModify, GList **personLuids)

Creates/Modifies one or more contacts from the contents of a buffer containing vCards.

alp_status_t alp_contacts_dml_read_from_vCard_file (AlpDmlH dmlH, int theDataFd, bool fromExgMgr, bool forModify, GList **personLuids)

Creates/Modifies one or more contacts from the contents of a file containing vCards.

alp_status_t alp_contacts_dml_register_alarm_ui_handler (AlpDmlH dmlH, char *appName)

alp_status_t alp_contacts_dml_release_monitor (AlpDmlH dmlH, AlpHsMonitorPtr pMonitor)

Releases any monitor set from alp_contacts_dml_monitor_object.

alp_status_t alp_contacts_dml_search_begin (AlpDmlH dmlH, AlpDmlStatementH *personStmtH, char *string, int32_t *numResults)

alp_status_t alp_contacts_dml_search_statement_begin (AlpDmlH dmlH, char *string, AlpDmlStatementH *personStmtH, int32_t *numResults) __attribute((deprecated))

Deprecated. Use alp_contacts_dml_search_begin instead.

alp_status_t alp_contacts_dml_set_category_ringtone (AlpDmlH dmlH, AlpLuid categoryLuid, AlpContactsDmlRingtoneType ringtoneType, const char *ringtoneFilePath)

Sets any ringtone associated with the given category.

alp_status_t alp_contacts_dml_set_next_alarm (AlpDmlH dmlH, AlpLuid personLuid)

alp_status_t alp_contacts_dml_write_to_vCard_buffer (AlpDmlH dmlH, uint8_t **dataBuf, int32_t *dataBufSize, bool toExgMgr, const GList *personLuids)

Writes one or more contact vCards to an allocated buffer.

alp_status_t alp_contacts_dml_write_to_vCard_file (AlpDmlH dmlH, int theDataFd, bool toExgMgr, const GList *personLuids)

Writes one or more contact vCards to the given file.

Function Documentation

alp_status_t alp_contacts_dml_begin_modify_batch ( AlpDmlH dmlH )

Wrapper for alp_hscm_begin_modify_batch.

Parameters:

[in] dmlH Handle to the Contacts data model.

Returns:
ALP_STATUS_CONTACTS_DML_* error

alp_status_t alp_contacts_dml_cid_lookup ( AlpDmlH dmlH,

const char * lookupString,

AlpLuid * personLuid,

AlpLuid * contactLuid

)

Given a lookup string as input, this routine searches all contact records in the data model for a matching Value field.
If a match is found, the corresponding contactLuid and personLUID is returned. If no match is found, those parameters are set to 0.
This routine can be used to search for any kind of contact record (instant message ID, email address, phone number, ...), by exact string match, but it also does some special things to accomodate searching for phone numbers, since phone numbers may have embedded non-numeric characters that should be ignored.
The search will return the first "strongly matching" record it finds, if it finds one. Otherwise it will return the best "weakly matching" record it finds, if it finds any.
"Strongly matching" means that either (1) the original lookup and Value strings match exactly, or (2) after discarding all non-numeric characters, the two strings match exactly and are at least 4 digits long.
"Weakly matching" means that after discarding all non-numeric characters, the rightmost N >= 6 digits of the two strings match, but there are unmatched digits to the left in one or both of the strings. Among all weakly matching records, the "best" is the first with the biggest N.
Example: assume the following contact records:

"06.99.99.45.67"
"Main number: 1-800-123-4567"
"45.67"

The lookup string "4567" will match "45.67". The lookup string "34567" will not match anything. The lookup string "234567" will match "Main number: 1-800-123-4567". The lookup string "+33699994567" will match "06.99.99.45.67".

Parameters:

[in] dmlH Handle to the Contacts Datamodel

[in] lookupString Any contact information such as a phone number, FAX number, Mobile number, email address, URL, etc.

[out] personLuid If a match is found, the personLuid will contain the local unique ID for that record's PersonItem. The personLuid can be used to find out any information about the record.

[out] contactLuid If a match is found, the contactLuid will contain the id of the ContactItem that was matched.

Returns:
ALP_STATUS_CONTACTS_DML_* error

alp_status_t alp_contacts_dml_duplicate ( AlpDmlH dmlH,

AlpLuid srcContact,

AlpLuid * dupedContact

)

Duplicates the given contact returning, if successful, the new contact LUID.

Parameters:

[in] dmlH Handle to the contacts data model handle.

[out] srcContact AlpLuid of the source person.

[out] dupedContact AlpLuid of the duplicated person.

Returns:
ALP_STATUS_CONTACTS_DML_* error

alp_status_t alp_contacts_dml_end_modify_batch ( AlpDmlH dmlH,

bool batchSucceeded

)

Wrapper for alp_hscm_begin_modify_batch.

Parameters:

[in] dmlH Handle to the Contacts data model.

[in] batchSucceeded Indicates whether the batch succeeded.

Returns:
ALP_STATUS_CONTACTS_DML_* error

alp_status_t alp_contacts_dml_event_statement_begin ( AlpDmlH dmlH,

uint32_t startDay,

uint32_t startMonth,

uint32_t endDay,

uint32_t endMonth,

uint32_t year,

AlpDmlStatementH * personStmtH,

int32_t * numResults

)

Fetch a list of PersonItems for people that have had a birthday and/or anniversary between the given start day and month and end day and month, on the given year.
After calling this routine, you must call alp_contacts_dml_statement_next() to advance the statement to the first object in the result set before you can call any of the alp_contacts_dml_statement_get_* API to retrieve information from an object.
It is important to keep track of which alp_contact_dml_*_statement_init function you use to initialize which AlpDmlStatementH, because that will dictate which objects are included in the statement's result set, and what AlpContactsDmlColumnType's you can use to fetch properties from items in the statement.
If there are no records found that match the search critereon, numResults, if it was supplied will be set to 0, ALP_STATUS_CONTACTS_DML_NO_RECORDS will be returned, and the personStmtH parameter will not be initialized (so the caller should not call alp_contacts_dml_statement_next (or end) on it.

Parameters:

[in] dmlH Handle to the contacts data model

[in] startDay beginning day of month containing a birthday/anniversary [1..31]

[in] startMonth beginning month containing a birthday/anniversary [0..11]

[in] endDay end day of month containing a birthday/anniversary [1..31]

[in] endMonth end month containing a birthday/anniversary [0..11]

[in] year containing a birthday/anniversary. If the person's date of birth and anniversary are after the day, month, and year given, it won't be matched, however if the person had a bday or anniversary event between the two dates of the same given year, it will match.

[out] personStmtH The address of a statement handle that is to be allocated and initialized by this routine.

[out] numResults Pointer to an integer that will be used to store the number of PersonItems found matching the filter parameters supplied. This parameter is optional, and if NULL, this value won't be computed or set.

Returns:
ALP_STATUS_CONTACTS_DML_* error

alp_status_t alp_contacts_dml_event_statement_begin_with_columns ( AlpDmlH dmlH,

uint32_t startDay,

uint32_t startMonth,

uint32_t endDay,

uint32_t endMonth,

uint32_t year,

const AlpContactsDmlColumnType * columnTypes,

int16_t numColumnTypes,

AlpDmlStatementH * personStmtH,

int32_t * numResults

)

Fetch a list of PersonItems for people that have had a birthday and/or anniversary between the given start day and month and end day and month, on the given year fetching only data in the list of column types.
After calling this routine, you must call alp_contacts_dml_statement_next() to advance the statement to the first object in the result set before you can call any of the alp_contacts_dml_statement_get_* API to retrieve information from an object.
It is important to keep track of which alp_contact_dml_*_statement_init function you use to initialize which AlpDmlStatementH, because that will dictate which objects are included in the statement's result set, and what AlpContactsDmlColumnType's you can use to fetch properties from items in the statement.
If there are no records found that match the search critereon, numResults, if it was supplied will be set to 0, ALP_STATUS_CONTACTS_DML_NO_RECORDS will be returned, and the personStmtH parameter will not be initialized (so the caller should not call alp_contacts_dml_statement_next (or end) on it.

Parameters:

[in] dmlH Handle to the contacts data model

[in] startDay beginning day of month containing a birthday/anniversary [1..31]

[in] startMonth beginning month containing a birthday/anniversary [0..11]

[in] endDay end day of month containing a birthday/anniversary [1..31]

[in] endMonth end month containing a birthday/anniversary [0..11]

[in] year containing a birthday/anniversary. If the person's date of birth and anniversary are after the day, month, and year given, it won't be matched, however if the person had a bday or anniversary event between the two dates of the same given year, it will match.

[in] columnTypes An array of AlpContactsDmlColumnType ids to specify which columns data should be fetched for. Requesting data from an unfetched column will result in an error.

[in] numColumnTypes The number of items in columnTypes array.

[out] personStmtH The address of a statement handle that is to be allocated and initialized by this routine.

[out] numResults Pointer to an integer that will be used to store the number of PersonItems found matching the filter parameters supplied. This parameter is optional, and if NULL, this value won't be computed or set.

Returns:
ALP_STATUS_CONTACTS_DML_* error

alp_status_t alp_contacts_dml_get_category_ringtone ( AlpDmlH dmlH,

AlpLuid categoryLuid,

AlpContactsDmlRingtoneType ringtoneType,

char ** ringtoneMFURL

)

Retrieves any ringtone associated with the given category.

Parameters:

[in] dmlH Handle to the contacts data model handle.

[in] categoryLuid AlpLuid of the category.

[in] ringtoneType Type of ringtone.

[out] ringtoneMFURL Allocated ringtone media file URL. Use alp_mf_get_url_path to convert to full path. Must be free'd by caller.

Returns:
ALP_STATUS_CONTACTS_DML_* error

AlpDmlH alp_contacts_dml_get_catmgr_handle ( AlpDmlH dmlH )

Returns an AlpDmlH that can be passed to Category Manager functions.

Parameters:

[in] dmlH Handle to the contacts data model handle.

Returns:
dmlH to be used to pass to catmgr functions. NULL on errors.

alp_status_t alp_contacts_dml_get_person_ringtone ( AlpDmlH dmlH,

AlpLuid personLuid,

AlpContactsDmlRingtoneType ringtoneType,

char ** ringtoneFilePath

)

Retrieves any ringtone associated with the given person. It will automatically search the person, its category, and finally default preferences for the appropriate ringtone.

Parameters:

[in] dmlH Handle to the contacts data model handle.

[in] personLuid AlpLuid of the person.

[in] ringtoneType Type of ringtone.

[out] ringtoneFilePath Allocated ringtone full path. Must be free'd by caller.

Returns:
ALP_STATUS_CONTACTS_DML_* error

alp_status_t alp_contacts_dml_get_thumbnail_sizes ( uint32_t * largeWidth,

uint32_t * largeHeight,

uint32_t * smallWidth,

uint32_t * smallHeight

)

Returns the sizes used for thumbnail data.

Parameters:

[out] largeWidth If not NULL then width of large thumbnail

[out] largeHeight If not NULL then height of large thumbnail

[out] smallWidth If not NULL then width of small thumbnail

[out] smallHeight If not NULL then height of small thumbnail

Returns:
ALP_STATUS_CONTACTS_DML_* error

alp_status_t alp_contacts_dml_get_version ( AlpDmlH dmlH,

int32_t * version

)

Fetch schema version number

Parameters:

[in] dmlH Handle to the contacts data model to close.

[out] version version number of contacts data model

See also:
alp_contacts_dml_open

Returns:
ALP_STATUS_CONTACTS_DML_* error

alp_status_t alp_contacts_dml_listview_person_index ( AlpDmlH dmlH,

AlpLuid personLuid,

AlpLuid categoryLuid,

bool unfiled,

AlpContactsDmlOrderByType orderBy,

const char * filterBy,

int32_t * index

)

Given a set of list view creation criteria and a person luid calculate the index of the person in the list.
If there are no records found that match the search critereon ALP_STATUS_CONTACTS_DML_NO_RECORDS will be returned.

Parameters:

[in] dmlH Handle to the Contacts data model.

[in] personLuid The person we are looking for.

[in] categoryLuid This optional parameter specifies a categoryLuid filter to use. If 0, then then look in "All" PersonItems. Otherwise it will only look in items that are a member of the given category.

[in] unfiled If true, then categoryLuid is ignored and only records that have no category memberships are searched.

[in] orderBy An enum specifying how the PersonItems are to be sorted

[in] filterBy If non-NULL then data is filtered by this prefix on firstname, lastname, company and englishname.

[out] index The index of the personLuid in the list.

Returns:
ALP_STATUS_CONTACTS_DML_* error

alp_status_t alp_contacts_dml_monitor_object ( AlpDmlH dmlH,

AlpLuid personLuid,

AlpLuid * conflictLuid,

AlpHsMonitorPtr * ppMonitor

)

Creates an internal change manager object monitor for the given luid. The policy will be to create conflicts. If alp_contacts_dml_update returns ALP_STATUS_CONTACT_DML_CHANGEMGR_CONFLICT the conflictLuid pointer will be set.

Parameters:

[in] dmlH Handle to the contacts data model handle.

[in] personLuid AlpLuid of the person.

[in] conflictLuid Pointer to where any new luid created due to a conflict will be stored. May be NULL.

[in,out] ppMonitor The change monitor either newly created (if param points to NULL) or the change monitor to use for subsequent updates.

Returns:
ALP_STATUS_CONTACTS_DML_* error
ALP_STATUS_HOTSYNC_* error

alp_status_t alp_contacts_dml_person_get_name ( AlpDmlStatementH personStmtH,

AlpContactsDmlFormatNameType formatType,

char ** name

)

Builds a Display Name.
The string is malloced here and must be freed by the caller.
The Name formatting depends on localization rules
If the person pointed to by the statement has no name fragments that can be used to construct a name under the current localization rules, the string, kUnnamedPerson is allocated and returned through the name parameter.

Parameters:

[in] personStmtH Statement handle that has been initialized using any alp_contacts_dml_person_statement_begin() API and stepped using alp_contacts_dml_statement_next()

[in] formatType Indicates one of AlpContactsDmlFormatNameType name formats. Each format will obey a set of format rules for the device's current locale.

[out] name Address of a string who's memory will be allocated by this routine and freed by the caller

Returns:
alp_status_t

alp_status_t alp_contacts_dml_persons_from_vCard_buffer ( AlpDmlH dmlH,

const uint8_t * dataBuf,

int32_t dataBufSize,

bool fromExgMgr,

bool forModify,

GList ** personIDs

)

Deprecated. Use alp_contacts_dml_read_from_vCard_buffer instead.

alp_status_t alp_contacts_dml_persons_from_vCard_file ( AlpDmlH dmlH,

int theDataFd,

bool fromExgMgr,

bool forModify,

GList ** personIDs

)

Deprecated. Use alp_contacts_dml_read_from_vCard_file.

alp_status_t alp_contacts_dml_persons_to_vCard_buffer ( AlpDmlH dmlH,

uint8_t ** dataBuf,

int32_t * dataBufSize,

bool toExgMgr,

GList * personLuids

)

Deprecated. Use alp_contacts_dml_write_to_vCard_buffer instead.

alp_status_t alp_contacts_dml_persons_to_vCard_file ( AlpDmlH dmlH,

int theDataFd,

bool toExgMgr,

GList * personLuids

)

Deprecated. Use alp_contacts_dml_write_to_vCard_file instead.

alp_status_t alp_contacts_dml_read_from_vCard_buffer ( AlpDmlH dmlH,

const uint8_t * dataBuf,

int32_t dataBufSize,

bool fromExgMgr,

bool forModify,

GList ** personLuids

)

Creates/Modifies one or more contacts from the contents of a buffer containing vCards.
If a given vCard contains the GUID of an existing person, and we are called to handle an exchange manager request, than that data will replace what is already in the database. Otherwise this function creates new persons for each vCard (or modifies existing persons, see parameters.)

Parameters:

[in] dmlH Handle to the contacts data model handle.

[in] dataBuf buffer of vCard(s).

[in] dataBufSize Number of bytes in dataBuf, -1 if NULL terminated.

[in] fromExgMgr true iff we are called to handle an exchange manager request

[in] forModify true iff we are called to modify existing contacts. *personLuids must contain the luids that will map one-for-one vCards to existing contacts.

[in/out] personLuids If *personLuids is NULL, and forModify is false, then new persons will be created for each vCard and this will contain the list of luids of created persons. The caller must dispose of the list in this case.

If *personLuids is non-NULL, and forModify is false, then new persons will be created for each vCard with one-to-one mapping of the luids in this list.
If *personLuids is non-NULL, and forModify is true, then existing persons will be modified for each vCard with one-to-one mapping of the luids in this list.

Returns:
ALP_STATUS_CONTACTS_DML_* error

alp_status_t alp_contacts_dml_read_from_vCard_file ( AlpDmlH dmlH,

int theDataFd,

bool fromExgMgr,

bool forModify,

GList ** personLuids

)

Creates/Modifies one or more contacts from the contents of a file containing vCards.
If a given vCard contains the GUID of an existing person, and we are called to handle an exchange manager request, than that data will replace what is already in the database. Otherwise this function creates new persons for each vCard (or modifies existing persons, see parameters.)

Parameters:

[in] dmlH Handle to the contacts data model handle.

[in] theDataFd The opened files descriptor of the file containing the vCard(s). Must be opened and closed by the caller.

[in] fromExgMgr true iff we are called to handle an exchange manager request

[in] forModify true iff we are called to modify existing contacts. *personLuids must contain the luids that will map one-for-one vCards to existing contacts.

[in/out] personLuids If *personLuids is NULL, and forModify is false, then new persons will be created for each vCard and this will contain the list of luids of created persons. The caller must dispose of the list in this case.

If *personLuids is non-NULL, and forModify is false, then new persons will be created for each vCard with one-to-one mapping of the luids in this list.
If *personLuids is non-NULL, and forModify is true, then existing persons will be modified for each vCard with one-to-one mapping of the luids in this list.

Returns:
ALP_STATUS_CONTACTS_DML_* error

alp_status_t alp_contacts_dml_register_alarm_ui_handler ( AlpDmlH dmlH,

char * appName

)

Allows an application to register with the Contacts DML to provide the user interface for displaying birthday and anniversary alarm messages. Only one application may register at a time. The last application to register is the one that will be called. When calling this function, all future alarms will point to the new UI, and all existing birthday and anniversary alarms will be updated to point to the new UI handler.
Applications should re-register at installation and reset time.
Applications that register to handle the user interface for birthday and anniversary events will receive an ALP_EVENT_DISPLAY notification, at which point it should view the record given by the PersonItem Luid in argv[1] and call alp_contacts_dml_set_next_alarm() with that Luid.

Parameters:

[in] dmlH Handle to the contacts data model

[in] appName The application ID string used to identify the registered application with the bundle manager (ie "bar:com.access.apps.contacts")

Returns:
ALP_STATUS_CONTACTS_DML_* error

alp_status_t alp_contacts_dml_release_monitor ( AlpDmlH dmlH,

AlpHsMonitorPtr pMonitor

)

Releases any monitor set from alp_contacts_dml_monitor_object.

Parameters:

[in] dmlH Handle to the contacts data model handle.

[in] pMonitor Monitor to release.

Returns:
ALP_STATUS_CONTACTS_DML_* error
ALP_STATUS_HOTSYNC_* error

alp_status_t alp_contacts_dml_search_begin ( AlpDmlH dmlH,

AlpDmlStatementH * personStmtH,

char * string,

int32_t * numResults

)

Fetch a list of PersonItems for people that have any associated data or Items that contain a string that matches the input. The comparison used is a case-insensitive substring match.
For example, if the input is "Jone", it will match PersonItems with * First Name = "Jones" * Note = "Meet Jones at the store" * A person with an address "123 Jones Street"
After calling this routine, you must call alp_contacts_dml_statement_next() to advance the statement to the first object in the result set before you can call any of the alp_contacts_dml_statement_get_* API to retrieve information from an object.
It is important to keep track of which alp_contact_dml_*_statement_init function you use to initialize which AlpDmlStatementH, because that will dictate which objects are included in the statement's result set, and what AlpContactsDmlColumnType's you can use to fetch properties from items in the statement.
If there are no records found that match the search critereon, numResults, if it was supplied will be set to 0, ALP_STATUS_CONTACTS_DML_NO_RECORDS will be returned, and the personStmtH parameter will not be initialized (so the caller should not call alp_contacts_dml_statement_next (or end) on it.

Parameters:

[in] dmlH Handle to the contacts data model

[in] string Input string to match against.

[out] personStmtH The address of a statement handle that is to be allocated and initialized by this routine.

[out] numResults Pointer to an integer that will be used to store the number of PersonItems found matching the filter parameters supplied. This parameter is optional, and if NULL, this value won't be computed or set.

Returns:
ALP_STATUS_CONTACTS_DML_* error

alp_status_t alp_contacts_dml_search_statement_begin ( AlpDmlH dmlH,

char * string,

AlpDmlStatementH * personStmtH,

int32_t * numResults

)

Deprecated. Use alp_contacts_dml_search_begin instead.

alp_status_t alp_contacts_dml_set_category_ringtone ( AlpDmlH dmlH,

AlpLuid categoryLuid,

AlpContactsDmlRingtoneType ringtoneType,

const char * ringtoneFilePath

)

Sets any ringtone associated with the given category.

Parameters:

[in] dmlH Handle to the contacts data model handle.

[in] categoryLuid AlpLuid of the category.

[in] ringtoneType Type of ringtone.

[in] ringtoneFilePath Full path to valid media file. Pass NULL to clear any current ringtone.

Returns:
ALP_STATUS_CONTACTS_DML_* error

alp_status_t alp_contacts_dml_set_next_alarm ( AlpDmlH dmlH,

AlpLuid personLuid

)

Called by an application that has registered with the Contacts data model to handle alarms using alp_contacts_dml_register_alarm_ui_handler(). After a birthday or anniversary alarm goes off, the AlarmMgr launches the application registered to handle alarm UI with an ALP_APP_NOTIFY launch command. That application must parse out the PersonItem Luid for the alarm it received from the command line, and then perform two tasks: (a) Create an attention manager item to notify the user that a birthday or anniversary alarm has gone off (b) Call this function, alp_contacts_dml_set_next_alarm() on the given Person Luid to schedule the next birthday/anniversary alarm

Parameters:

[in] dmlH Handle to the contacts data model

[in] personLuid The Luid for the PersonItem who's next birthday or anniversary alarm needs to be set

Returns:
ALP_STATUS_CONTACTS_DML_* error

alp_status_t alp_contacts_dml_write_to_vCard_buffer ( AlpDmlH dmlH,

uint8_t ** dataBuf,

int32_t * dataBufSize,

bool toExgMgr,

const GList * personLuids

)

Writes one or more contact vCards to an allocated buffer.
If called to handle an exchange manager request we'll add the GUID to the vCard.

Parameters:

[in] dmlH Handle to the contacts data model handle.

[out] dataBuf Allocated buffer of vCard's. NULL terminated. Must be free'd by the caller.

[out] dataBufSize (optional) Size of dataBuf, not including NULL terminator.

[in] toExgMgr true iff we are called to handle an exchange manager request

[in] personLuids List of AlpLuid's of all the contacts to write.

Returns:
ALP_STATUS_CONTACTS_DML_* error

alp_status_t alp_contacts_dml_write_to_vCard_file ( AlpDmlH dmlH,

int theDataFd,

bool toExgMgr,

const GList * personLuids

)

Writes one or more contact vCards to the given file.
If called to handle an exchange manager request we'll add the GUID to the vCard.

Parameters:

[in] dmlH Handle to the contacts data model handle.

[in] theDataFd The opened files descriptor of the file containing the vCard(s). Must be opened and closed by the caller.

[in] toExgMgr true iff we are called to handle an exchange manager request

[in] personLuids List of AlpLuid's of all the contacts to write.

Returns:
ALP_STATUS_CONTACTS_DML_* error

Generated on Wed Jul 30 07:06:42 2008 by Doxygen 1.4.6 for ALP SDK + Hiker Documentation


Functions
alp_status_t	alp_contacts_dml_begin_modify_batch (AlpDmlH dmlH)
	Wrapper for alp_hscm_begin_modify_batch.
alp_status_t	alp_contacts_dml_cid_lookup (AlpDmlH dmlH, const char lookupString, AlpLuid personLuid, AlpLuid *contactLuid)
	Given a lookup string as input, this routine searches all contact records in the data model for a matching Value field.
alp_status_t	alp_contacts_dml_duplicate (AlpDmlH dmlH, AlpLuid srcContact, AlpLuid *dupedContact)
	Duplicates the given contact returning, if successful, the new contact LUID.
alp_status_t	alp_contacts_dml_end_modify_batch (AlpDmlH dmlH, bool batchSucceeded)
	Wrapper for alp_hscm_begin_modify_batch.
alp_status_t	alp_contacts_dml_event_statement_begin (AlpDmlH dmlH, uint32_t startDay, uint32_t startMonth, uint32_t endDay, uint32_t endMonth, uint32_t year, AlpDmlStatementH personStmtH, int32_t numResults)
alp_status_t	alp_contacts_dml_event_statement_begin_with_columns (AlpDmlH dmlH, uint32_t startDay, uint32_t startMonth, uint32_t endDay, uint32_t endMonth, uint32_t year, const AlpContactsDmlColumnType columnTypes, int16_t numColumnTypes, AlpDmlStatementH personStmtH, int32_t *numResults)
alp_status_t	alp_contacts_dml_get_category_ringtone (AlpDmlH dmlH, AlpLuid categoryLuid, AlpContactsDmlRingtoneType ringtoneType, char **ringtoneMFURL)
	Retrieves any ringtone associated with the given category.
AlpDmlH	alp_contacts_dml_get_catmgr_handle (AlpDmlH dmlH)
	Returns an AlpDmlH that can be passed to Category Manager functions.
alp_status_t	alp_contacts_dml_get_person_ringtone (AlpDmlH dmlH, AlpLuid personLuid, AlpContactsDmlRingtoneType ringtoneType, char **ringtoneFilePath)
	Retrieves any ringtone associated with the given person. It will automatically search the person, its category, and finally default preferences for the appropriate ringtone.
alp_status_t	alp_contacts_dml_get_thumbnail_sizes (uint32_t largeWidth, uint32_t largeHeight, uint32_t smallWidth, uint32_t smallHeight)
	Returns the sizes used for thumbnail data.
alp_status_t	alp_contacts_dml_get_version (AlpDmlH dmlH, int32_t *version)
alp_status_t	alp_contacts_dml_listview_person_index (AlpDmlH dmlH, AlpLuid personLuid, AlpLuid categoryLuid, bool unfiled, AlpContactsDmlOrderByType orderBy, const char filterBy, int32_t index)
	Given a set of list view creation criteria and a person luid calculate the index of the person in the list.
alp_status_t	alp_contacts_dml_monitor_object (AlpDmlH dmlH, AlpLuid personLuid, AlpLuid conflictLuid, AlpHsMonitorPtr ppMonitor)
	Creates an internal change manager object monitor for the given luid. The policy will be to create conflicts. If alp_contacts_dml_update returns ALP_STATUS_CONTACT_DML_CHANGEMGR_CONFLICT the conflictLuid pointer will be set.
alp_status_t	alp_contacts_dml_person_get_name (AlpDmlStatementH personStmtH, AlpContactsDmlFormatNameType formatType, char **name)
	Builds a Display Name.
alp_status_t	alp_contacts_dml_persons_from_vCard_buffer (AlpDmlH dmlH, const uint8_t dataBuf, int32_t dataBufSize, bool fromExgMgr, bool forModify, GList *personIDs) __attribute((deprecated))
	Deprecated. Use alp_contacts_dml_read_from_vCard_buffer instead.
alp_status_t	alp_contacts_dml_persons_from_vCard_file (AlpDmlH dmlH, int theDataFd, bool fromExgMgr, bool forModify, GList **personIDs) __attribute((deprecated))
	Deprecated. Use alp_contacts_dml_read_from_vCard_file.
alp_status_t	alp_contacts_dml_persons_to_vCard_buffer (AlpDmlH dmlH, uint8_t *dataBuf, int32_t dataBufSize, bool toExgMgr, GList *personLuids) __attribute((deprecated))
	Deprecated. Use alp_contacts_dml_write_to_vCard_buffer instead.
alp_status_t	alp_contacts_dml_persons_to_vCard_file (AlpDmlH dmlH, int theDataFd, bool toExgMgr, GList *personLuids) __attribute((deprecated))
	Deprecated. Use alp_contacts_dml_write_to_vCard_file instead.
alp_status_t	alp_contacts_dml_read_from_vCard_buffer (AlpDmlH dmlH, const uint8_t dataBuf, int32_t dataBufSize, bool fromExgMgr, bool forModify, GList *personLuids)
	Creates/Modifies one or more contacts from the contents of a buffer containing vCards.
alp_status_t	alp_contacts_dml_read_from_vCard_file (AlpDmlH dmlH, int theDataFd, bool fromExgMgr, bool forModify, GList **personLuids)
	Creates/Modifies one or more contacts from the contents of a file containing vCards.
alp_status_t	alp_contacts_dml_register_alarm_ui_handler (AlpDmlH dmlH, char *appName)
alp_status_t	alp_contacts_dml_release_monitor (AlpDmlH dmlH, AlpHsMonitorPtr pMonitor)
	Releases any monitor set from alp_contacts_dml_monitor_object.
alp_status_t	alp_contacts_dml_search_begin (AlpDmlH dmlH, AlpDmlStatementH personStmtH, char string, int32_t *numResults)
alp_status_t	alp_contacts_dml_search_statement_begin (AlpDmlH dmlH, char string, AlpDmlStatementH personStmtH, int32_t *numResults) __attribute((deprecated))
	Deprecated. Use alp_contacts_dml_search_begin instead.
alp_status_t	alp_contacts_dml_set_category_ringtone (AlpDmlH dmlH, AlpLuid categoryLuid, AlpContactsDmlRingtoneType ringtoneType, const char *ringtoneFilePath)
	Sets any ringtone associated with the given category.
alp_status_t	alp_contacts_dml_set_next_alarm (AlpDmlH dmlH, AlpLuid personLuid)
alp_status_t	alp_contacts_dml_write_to_vCard_buffer (AlpDmlH dmlH, uint8_t *dataBuf, int32_t dataBufSize, bool toExgMgr, const GList *personLuids)
	Writes one or more contact vCards to an allocated buffer.
alp_status_t	alp_contacts_dml_write_to_vCard_file (AlpDmlH dmlH, int theDataFd, bool toExgMgr, const GList *personLuids)
	Writes one or more contact vCards to the given file.

Utilities [API's]

Functions

Function Documentation

Utilities
[API's]