Read Item
[API's]


Functions

alp_status_t alp_contacts_dml_address_statement_begin (AlpDmlH dmlH, AlpLuid personLuid, AlpLuid addressLuid, AlpDmlStatementH *addressStmtH, int32_t *numResults)
 Creates and initializes a new AlpDmlStatementH that can be used to iterate over a set of AddressItem's in the Contacts data model.
alp_status_t alp_contacts_dml_address_statement_begin_with_columns (AlpDmlH dmlH, AlpLuid personLuid, AlpLuid addressLuid, const AlpContactsDmlColumnType *columnTypes, int16_t numColumnTypes, AlpDmlStatementH *addressStmtH, int32_t *numResults)
 Creates and initializes a new AlpDmlStatementH that can be used to iterate over a set of AddressItem's in the Contacts data model fetching only data in the list of column types.
alp_status_t alp_contacts_dml_contact_statement_begin (AlpDmlH dmlH, AlpLuid personLuid, AlpLuid contactLuid, const char *const *contactTypes, uint16_t numContactTypes, AlpDmlStatementH *contactsStmtH, int32_t *numResults)
 Creates and initializes a new AlpDmlStatementH that can be used to iterate over a set of ContactItem's in the Contacts data model.
alp_status_t alp_contacts_dml_contact_statement_begin_with_columns (AlpDmlH dmlH, AlpLuid personLuid, AlpLuid contactLuid, const char *const *contactTypes, uint16_t numContactTypes, const AlpContactsDmlColumnType *columnTypes, int16_t numColumnTypes, AlpDmlStatementH *contactsStmtH, int32_t *numResults)
 Creates and initializes a new AlpDmlStatementH that can be used to iterate over a set of ContactItem's in the Contacts data model fetching only data in the list of column types.
alp_status_t alp_contacts_dml_custom_label_statement_begin (AlpDmlH dmlH, AlpDmlStatementH *customLabelStmtH, int32_t *numResults)
alp_status_t alp_contacts_dml_custom_label_statement_begin_with_columns (AlpDmlH dmlH, const AlpContactsDmlColumnType *columnTypes, int16_t numColumnTypes, AlpDmlStatementH *customLabelStmtH, int32_t *numResults)
alp_status_t alp_contacts_dml_distribution_statement_begin (AlpDmlH dmlH, AlpLuid distributionLuid, const char *const *distributionTypes, uint16_t numDistributionTypes, AlpContactsDmlDistributionOrderByType orderBy, int32_t limit, int32_t offset, AlpDmlStatementH *distributionStmtH, int32_t *numResults)
 Creates and initializes a new AlpDmlStatementH that can be used to iterate over a set of DistributionItem's in the Contacts data model fetching only data in the list of column types.
alp_status_t alp_contacts_dml_extrafields_statement_begin (AlpDmlH dmlH, AlpLuid personLuid, AlpDmlStatementH *extraFieldsStmtH, int32_t *numResults)
 Creates and initializes a new AlpDmlStatementH that can be used to iterate over a set of ExtraFieldItem's in the Contacts data model.
alp_status_t alp_contacts_dml_extrafields_statement_begin_with_columns (AlpDmlH dmlH, AlpLuid personLuid, const AlpContactsDmlColumnType *columnTypes, int16_t numColumnTypes, AlpDmlStatementH *extraFieldsStmtH, int32_t *numResults)
 Creates and initializes a new AlpDmlStatementH that can be used to iterate over a set of ExtraFieldItem's in the Contacts data model fetching only data in the list of column types.
alp_status_t alp_contacts_dml_listview_statement_begin (AlpDmlH dmlH, AlpLuid categoryLuid, AlpLuid distributionLuid, bool unfiled, const char *const *contactTypes, int16_t numContactTypes, AlpContactsDmlOrderByType orderBy, int32_t limit, int32_t offset, const char *filterBy, bool filterDataOnly, AlpDmlStatementH *listViewStmtH, int32_t *totalPersons, int32_t *totalItems)
 Creates and initializes a new AlpDmlStatementH that can be used to iterate over a set of specific PersonItem and ContactItem fields needed by the Contacts list view in the Contacts data model.
alp_status_t alp_contacts_dml_listview_statement_begin2 (AlpDmlH dmlH, AlpLuid categoryLuid, AlpLuid distributionLuid, bool unfiled, const char *const *contactTypes, int16_t numContactTypes, AlpContactsDmlOrderByType orderBy, int32_t limit, int32_t offset, const char *filterBy, AlpDmlStatementH *listViewStmtH, int32_t *totalPersons)
alp_status_t alp_contacts_dml_person_statement_begin (AlpDmlH dmlH, AlpLuid personLuid, AlpLuid categoryLuid, bool unfiled, const char *const *contactTypes, int16_t numContactTypes, AlpContactsDmlOrderByType orderBy, AlpDmlStatementH *personStmtH, int32_t *numResults)
 Creates and initializes a new AlpDmlStatementH that can be used to iterate over a set of PersonItem's in the Contacts data model.
alp_status_t alp_contacts_dml_person_statement_begin_with_columns (AlpDmlH dmlH, AlpLuid personLuid, AlpLuid categoryLuid, bool unfiled, const char *const *contactTypes, int16_t numContactTypes, AlpContactsDmlOrderByType orderBy, const AlpContactsDmlColumnType *columnTypes, int16_t numColumnTypes, AlpDmlStatementH *personStmtH, int32_t *numResults)
 Creates and initializes a new AlpDmlStatementH that can be used to iterate over a set of PersonItem's in the Contacts data model fetching only data in the list of column types.
alp_status_t alp_contacts_dml_statement_end (AlpDmlStatementH stmtH)
 Disposes of the statement handle.
alp_status_t alp_contacts_dml_statement_get_blob (AlpDmlStatementH stmtH, AlpContactsDmlColumnType column, bool copy, void **value, int32_t *size)
 Retrieves a blob from a statement handle.
alp_status_t alp_contacts_dml_statement_get_int32 (AlpDmlStatementH stmtH, AlpContactsDmlColumnType column, int32_t *value)
 Retrieves an integer from a statement handle.
alp_status_t alp_contacts_dml_statement_get_luids (AlpDmlStatementH stmtH, AlpLuid *personLuid, AlpLuid *itemLuid)
 Retrieves luids from a statement handle.
alp_status_t alp_contacts_dml_statement_get_string (AlpDmlStatementH stmtH, AlpContactsDmlColumnType column, bool copy, char **value)
 Retrieves a string from a statement handle.
alp_status_t alp_contacts_dml_statement_next (AlpDmlStatementH stmtH)
 Given a statement handle initialized with an alp_contacts_dml_*_statement_init() API, this routine will step the statement forward to point to the next item in the sequence.
alp_status_t alp_contacts_dml_thumbnail_statement_begin (AlpDmlH dmlH, AlpLuid personLuid, AlpDmlStatementH *thumbnailStmtH, int32_t *numResults)
 Creates and initializes a new AlpDmlStatementH that can be used to iterate over a set of ThumbnailItem's in the Contacts data model.
alp_status_t alp_contacts_dml_thumbnail_statement_begin_with_columns (AlpDmlH dmlH, AlpLuid personLuid, const AlpContactsDmlColumnType *columnTypes, int16_t numColumnTypes, AlpDmlStatementH *thumbnailStmtH, int32_t *numResults)
 Creates and initializes a new AlpDmlStatementH that can be used to iterate over a set of ThumbnailItem's in the Contacts data model fetching only data in the list of column types.

Function Documentation

alp_status_t alp_contacts_dml_address_statement_begin (  AlpDmlH  dmlH,
AlpLuid  personLuid,
AlpLuid  addressLuid,
AlpDmlStatementH *  addressStmtH,
int32_t *  numResults
) 
 

Creates and initializes a new AlpDmlStatementH that can be used to iterate over a set of AddressItem's in the Contacts data model.

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 values 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 addressStmtH 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] personLuid This optional parameter specifies a personLuid filter to use when building the statement handle. If 0, the statement will include all addresses in the datamodel. If set to a valid personLuid, it will only retrieve addresses that have been added for that person.
[in] addressLuid This optional paramter is used when the caller knows exactly which address they want to find. When given, all other filter parameters (personLuid) are ignored.
[out] addressStmtH 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 AddressItems 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_address_statement_begin_with_columns (  AlpDmlH  dmlH,
AlpLuid  personLuid,
AlpLuid  addressLuid,
const AlpContactsDmlColumnType *  columnTypes,
int16_t  numColumnTypes,
AlpDmlStatementH *  addressStmtH,
int32_t *  numResults
) 
 

Creates and initializes a new AlpDmlStatementH that can be used to iterate over a set of AddressItem's in the Contacts data model 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 values 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 addressStmtH 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] personLuid This optional parameter specifies a personLuid filter to use when building the statement handle. If 0, the statement will include all addresses in the datamodel. If set to a valid personLuid, it will only retrieve addresses that have been added for that person.
[in] addressLuid This optional paramter is used when the caller knows exactly which address they want to find. When given, all other filter parameters (personLuid) are ignored.
[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] addressStmtH 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 AddressItems 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_contact_statement_begin (  AlpDmlH  dmlH,
AlpLuid  personLuid,
AlpLuid  contactLuid,
const char *const *  contactTypes,
uint16_t  numContactTypes,
AlpDmlStatementH *  contactsStmtH,
int32_t *  numResults
) 
 

Creates and initializes a new AlpDmlStatementH that can be used to iterate over a set of ContactItem's in the Contacts data model.

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 values 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 contactsStmtH 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] personLuid This optional parameter specifies a personLuid filter to use when building the statement handle. If 0, the statement will include all contacts in the datamodel. If set to a valid personLuid, it will only retrieve contacts that have been added for that person.
[in] contactLuid This optional paramter is used when the caller knows exactly which contact they want to find. When given, all other filter parameters (personLuid, contactTypes, numContactTypes) are ignored.
[in] contactTypes An array of ContactType strings that the PersonItem must have in order to be included in the statement. For example, if the array includes the strings "kContactsTypePhone" and "kContactsTypeURL", then the statement handle will only include PersonItems that have a ContactItem with either one of those two ContactTypes set for it. If NULL, then associated ContactItems' ContactTypes will not be used to filter the list.
[in] numContactTypes The number of strings in contactTypes array. If contactTypes is NULL, this parameter is ignored.
[out] contactsStmtH 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 ContactItems 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_contact_statement_begin_with_columns (  AlpDmlH  dmlH,
AlpLuid  personLuid,
AlpLuid  contactLuid,
const char *const *  contactTypes,
uint16_t  numContactTypes,
const AlpContactsDmlColumnType *  columnTypes,
int16_t  numColumnTypes,
AlpDmlStatementH *  contactsStmtH,
int32_t *  numResults
) 
 

Creates and initializes a new AlpDmlStatementH that can be used to iterate over a set of ContactItem's in the Contacts data model 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 values 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 contactsStmtH 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] personLuid This optional parameter specifies a personLuid filter to use when building the statement handle. If 0, the statement will include all contacts in the datamodel. If set to a valid personLuid, it will only retrieve contacts that have been added for that person.
[in] contactLuid This optional paramter is used when the caller knows exactly which contact they want to find. When given, all other filter parameters (personLuid, contactTypes, numContactTypes) are ignored.
[in] contactTypes An array of ContactType strings that the PersonItem must have in order to be included in the statement. For example, if the array includes the strings "kContactsTypePhone" and "kContactsTypeURL", then the statement handle will only include PersonItems that have a ContactItem with either one of those two ContactTypes set for it. If NULL, then associated ContactItems' ContactTypes will not be used to filter the list.
[in] numContactTypes The number of strings in contactTypes array. If contactTypes is NULL, this parameter is ignored.
[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] contactsStmtH 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 ContactItems 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_custom_label_statement_begin (  AlpDmlH  dmlH,
AlpDmlStatementH *  customLabelStmtH,
int32_t *  numResults
) 
 

Creates and initializes a new AlpDmlStatementH that can be used to iterate over a set of CustomLabelItem's in the Contacts data model.

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 values 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 customLabelStmtH 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
[out] customLabelStmtH 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 CustomLabelItems 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_custom_label_statement_begin_with_columns (  AlpDmlH  dmlH,
const AlpContactsDmlColumnType *  columnTypes,
int16_t  numColumnTypes,
AlpDmlStatementH *  customLabelStmtH,
int32_t *  numResults
) 
 

Creates and initializes a new AlpDmlStatementH that can be used to iterate over a set of CustomLabelItem's in the Contacts data model 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 values 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 customLabelStmtH 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] 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] customLabelStmtH 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 CustomLabelItems 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_distribution_statement_begin (  AlpDmlH  dmlH,
AlpLuid  distributionLuid,
const char *const *  distributionTypes,
uint16_t  numDistributionTypes,
AlpContactsDmlDistributionOrderByType  orderBy,
int32_t  limit,
int32_t  offset,
AlpDmlStatementH *  distributionStmtH,
int32_t *  numResults
) 
 

Creates and initializes a new AlpDmlStatementH that can be used to iterate over a set of DistributionItem's in the Contacts data model 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 values 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 distributionStmtH 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] distributionLuid This optional parameter specifies a distributionLuid filter to use when building the statement handle. If 0, the statement will include all distribution lists in the datamodel. If set to a valid distributionLuid, it will only retrieve that specific distribution list.
[in] distributionTypes An array of DistributionContactType strings that the DistributionItem must have in order to be included in the statement. For example, if the array includes the strings kDistributionContactTypePhone and kDistributionContactTypeURL, then the statement handle will only include DistributionItems that have a ContactItem with either one of those two ContactTypes set for it. If NULL, then associated DistributionItems' ContactTypes will not be used to filter the list.
[in] numDistributionTypes The number of strings in distributionTypes array. If distributionTypes is NULL, this parameter is ignored.
[in] orderBy An enum specifying how the DistributionItems in the statement handle are to be sorted
[in] limit Places an upper bound on the number of rows returned in the result. Zero means no limit.
[in] offset If limit is non-zero then specifies how many rows to skip at the beginning of the result set.
[out] distributionStmtH The address of a statement handle that is to be allocated and initialized by this routine. This parameter may be NULL if all you want is numResults.
[out] numResults Pointer to an integer that will be used to store the number of ContactItems 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_extrafields_statement_begin (  AlpDmlH  dmlH,
AlpLuid  personLuid,
AlpDmlStatementH *  extraFieldsStmtH,
int32_t *  numResults
) 
 

Creates and initializes a new AlpDmlStatementH that can be used to iterate over a set of ExtraFieldItem's in the Contacts data model.

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 values 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 extraFieldStmtH 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] personLuid This optional parameter specifies a personLuid filter to use when building the statement handle. If 0, the statement will include all extra fields in the datamodel. If set to a valid personLuid, it will only retrieve extra fields that have been added for that person.
[out] extraFieldsStmtH 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 ExtraFieldItems 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_extrafields_statement_begin_with_columns (  AlpDmlH  dmlH,
AlpLuid  personLuid,
const AlpContactsDmlColumnType *  columnTypes,
int16_t  numColumnTypes,
AlpDmlStatementH *  extraFieldsStmtH,
int32_t *  numResults
) 
 

Creates and initializes a new AlpDmlStatementH that can be used to iterate over a set of ExtraFieldItem's in the Contacts data model 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 values 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 extraFieldStmtH 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] personLuid This optional parameter specifies a personLuid filter to use when building the statement handle. If 0, the statement will include all extra fields in the datamodel. If set to a valid personLuid, it will only retrieve extra fields that have been added for that person.
[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] extraFieldsStmtH 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 ExtraFieldItems 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_listview_statement_begin (  AlpDmlH  dmlH,
AlpLuid  categoryLuid,
AlpLuid  distributionLuid,
bool  unfiled,
const char *const *  contactTypes,
int16_t  numContactTypes,
AlpContactsDmlOrderByType  orderBy,
int32_t  limit,
int32_t  offset,
const char *  filterBy,
bool  filterDataOnly,
AlpDmlStatementH *  listViewStmtH,
int32_t *  totalPersons,
int32_t *  totalItems
) 
 

Creates and initializes a new AlpDmlStatementH that can be used to iterate over a set of specific PersonItem and ContactItem fields needed by the Contacts list view in the Contacts data model.

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 values from items in the statement.

If there are no records found that match the search critereon ALP_STATUS_CONTACTS_DML_NO_RECORDS will be returned, and the listViewStmtH 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] categoryLuid This optional parameter specifies a categoryLuid filter to use when building the statement handle. If 0, then the statement will include "All" PersonItems. Otherwise it will only include items that are a member of the given category.
[in] distributionLuid This optional parameter specifies a distribution list luid filter to use when building the statement handle. If non-zero it will only include items that have this distribution list luid; categoryLuid, unfiled and contactTypes are ignored.
[in] unfiled If true, then categoryLuid is ignored and only records that have no category memberships are allowed.
[in] contactTypes An array of ContactType strings that the PersonItem must have in order to be included in the statement. For example, if the array includes the strings "kContactsTypePhone" and "kContactsTypeURL", then the statement handle will only include PersonItems that have a ContactItem with either one of those two ContactTypes set for it. If NULL, then associated ContactItems' ContactTypes will not be used to filter the list.
[in] numContactTypes The number of strings in contactTypes array. If contactTypes is NULL, this parameter is ignored.
[in] orderBy An enum specifying how the PersonItems in the statement handle are to be sorted
[in] limit Places an upper bound on the number of rows returned in the result. Zero means no limit.
[in] offset If limit is non-zero then specifies how many rows to skip at the beginning of the result set.
[in] filterBy If non-NULL then data is filtered by this prefix on firstname, lastname, company and englishname.
[in] filterDataOnly If true then only firstname, lastname, company and englishname are fetched.
[out] listViewStmtH The address of a statement handle that is to be allocated and initialized by this routine. This parameter is optional, and if NULL, this value won't be computed or set.
[out] totalPersons Pointer to an integer that will be used to store the total number of PersonItems found matching the filter parameters supplied. This parameter is optional, and if NULL, this value won't be computed or set.
[out] totalItems Pointer to an integer that will be used to store the total number of items 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_listview_statement_begin2 (  AlpDmlH  dmlH,
AlpLuid  categoryLuid,
AlpLuid  distributionLuid,
bool  unfiled,
const char *const *  contactTypes,
int16_t  numContactTypes,
AlpContactsDmlOrderByType  orderBy,
int32_t  limit,
int32_t  offset,
const char *  filterBy,
AlpDmlStatementH *  listViewStmtH,
int32_t *  totalPersons
) 
 

alp_status_t alp_contacts_dml_person_statement_begin (  AlpDmlH  dmlH,
AlpLuid  personLuid,
AlpLuid  categoryLuid,
bool  unfiled,
const char *const *  contactTypes,
int16_t  numContactTypes,
AlpContactsDmlOrderByType  orderBy,
AlpDmlStatementH *  personStmtH,
int32_t *  numResults
) 
 

Creates and initializes a new AlpDmlStatementH that can be used to iterate over a set of PersonItem's in the Contacts data model.

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 values 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] personLuid This optional parameter indicates the caller is only interested in a specific personLuid. In this case, all other filtering parameters (categoryLuid, unfiled, contactTypes, numContactTypes) are ignored.
[in] categoryLuid This optional parameter specifies a categoryLuid filter to use when building the statement handle. If negative, then the statement will include only "Unfiled" PersonItems. If 0, then the statement will include "All" PersonItems. Otherwise it will only include 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 allowed.
[in] contactTypes An array of ContactType strings that the PersonItem must have in order to be included in the statement. For example, if the array includes the strings "kContactsTypePhone" and "kContactsTypeURL", then the statement handle will only include PersonItems that have a ContactItem with either one of those two ContactTypes set for it. If NULL, then associated ContactItems' ContactTypes will not be used to filter the list.
[in] numContactTypes The number of strings in contactTypes array. If contactTypes is NULL, this parameter is ignored.
[in] orderBy An enum specifying how the PersonItems in the statement handle are to be sorted
[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_person_statement_begin_with_columns (  AlpDmlH  dmlH,
AlpLuid  personLuid,
AlpLuid  categoryLuid,
bool  unfiled,
const char *const *  contactTypes,
int16_t  numContactTypes,
AlpContactsDmlOrderByType  orderBy,
const AlpContactsDmlColumnType *  columnTypes,
int16_t  numColumnTypes,
AlpDmlStatementH *  personStmtH,
int32_t *  numResults
) 
 

Creates and initializes a new AlpDmlStatementH that can be used to iterate over a set of PersonItem's in the Contacts data model 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 values 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] personLuid This optional parameter indicates the caller is only interested in a specific personLuid. In this case, all other filtering parameters (categoryLuid, unfiled, contactTypes, numContactTypes) are ignored.
[in] categoryLuid This optional parameter specifies a categoryLuid filter to use when building the statement handle. If negative, then the statement will include only "Unfiled" PersonItems. If 0, then the statement will include "All" PersonItems. Otherwise it will only include 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 allowed.
[in] contactTypes An array of ContactType strings that the PersonItem must have in order to be included in the statement. For example, if the array includes the strings "kContactsTypePhone" and "kContactsTypeURL", then the statement handle will only include PersonItems that have a ContactItem with either one of those two ContactTypes set for it. If NULL, then associated ContactItems' ContactTypes will not be used to filter the list.
[in] numContactTypes The number of strings in contactTypes array. If contactTypes is NULL, this parameter is ignored.
[in] orderBy An enum specifying how the PersonItems in the statement handle are to be sorted
[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_statement_end (  AlpDmlStatementH  stmtH  ) 
 

Disposes of the statement handle.

Parameters:
[in,out] stmtH Statement handle
Returns:
ALP_STATUS_CONTACTS_DML_* error

alp_status_t alp_contacts_dml_statement_get_blob (  AlpDmlStatementH  stmtH,
AlpContactsDmlColumnType  column,
bool  copy,
void **  value,
int32_t *  size
) 
 

Retrieves a blob from a statement handle.

Given a statement handle that has been initialized and stepped using alp_contacts_dml_statement_next() where an item has been found, this function can be used to retrieve any integer field from the item located at the current statement position.

Note that unless copy is set to true, the value returned is only valid until the stmtH is closed with alp_contacts_dml_statement_end() or stepped with alp_contacts_dml_statement_next()

Parameters:
[in] stmtH Handle to a statement
[in] column Any column type that exists for the item type pointed to in the statement.
[in] copy If true, then this routine mallocs memory for value of size bytes. It's the responsibility of the caller to free it.
[out] value Pointer to data to read out from a field of the current item in the statement
[out] size size of the value item. Note that if the copy parameter is true, this is how much memory is allocated by the routine.
Remarks:
When fetching a SmallThumbnail you will get a GdkPixbuf* that must be freed by g_object_unref() rather than by free().
Returns:
ALP_STATUS_CONTACTS_DML_* error

alp_status_t alp_contacts_dml_statement_get_int32 (  AlpDmlStatementH  stmtH,
AlpContactsDmlColumnType  column,
int32_t *  value
) 
 

Retrieves an integer from a statement handle.

Given a statement handle that has been initialized and stepped using alp_contacts_dml_statement_next() where an item has been found, this function can be used to retrieve any integer field from the item located at the current statement position.

Parameters:
[in] stmtH Handle to a statement
[in] column Any column type that exists for the item type pointed to in the statement.
[out] value Pointer to an integer to read out from a field of the current item in the statement
Returns:
ALP_STATUS_CONTACTS_DML_* error

alp_status_t alp_contacts_dml_statement_get_luids (  AlpDmlStatementH  stmtH,
AlpLuid *  personLuid,
AlpLuid *  itemLuid
) 
 

Retrieves luids from a statement handle.

Given a statement handle that has been stepped using alp_contacts_dml_statement_next(), this routine fetches the PersonLuid and/or ItemLuid for the object at the statement's curent position:

PersonItem: personLuid is fetched All other item types: personLuid and itemLuid are fetched.

Parameters:
[in] stmtH Statement handle that has been initialized using any alp_contacts_dml_*_statement_init() API and stepped using alp_contacts_dml_statement_next() types contain a ItemLuid
[out] personLuid PersonLuid the object referenced by the statement handle is pare of. See above for a list that indicates which item types contain a PersonLuid. The caller can optionally pass in NULL if the statement handle is for a CustomLabelItem.
[out] itemLuid Luid of the object referenced by the statement handle is pare of. See above for a list that indicates which item types contain an ItemLuid. The caller can optionally pass in NULL if the statement handle is for a PersonItem. For DistributionItem's and distribution memberships the DistributionItemLuid is returned here.
Remarks:
A returned itemLuid is not guaranteed to be persistent and should not be stored. Use the Identifier value if you need to store a specific Contact, Address or ExtraField. A personLuid is persistent.
Returns:
ALP_STATUS_CONTACTS_DML_* error

alp_status_t alp_contacts_dml_statement_get_string (  AlpDmlStatementH  stmtH,
AlpContactsDmlColumnType  column,
bool  copy,
char **  value
) 
 

Retrieves a string from a statement handle.

Given a statement handle that has been initialized and stepped using alp_contacts_dml_statement_next() where an item has been found, this function can be used to retrieve any string field from the item located at the current statement position.

Parameters:
[in] stmtH Handle to a statement
[in] column Any column type that exists for the item type pointed to in the statement.
[in] copy If true, memory is allocated by this routine and the string is copied. It would be up to the caller to free the string. If false, value will just contain a pointer to the data in the stmtH handle which is only valid until calling alp_contacts_dml_statement_next().
[out] value Pointer to a string to read out from a field of the current item in the statement. It is allocated and must be free'd by the caller is copy is false.
Returns:
ALP_STATUS_CONTACTS_DML_* error

alp_status_t alp_contacts_dml_statement_next (  AlpDmlStatementH  stmtH  ) 
 

Given a statement handle initialized with an alp_contacts_dml_*_statement_init() API, this routine will step the statement forward to point to the next item in the sequence.

Note that you must call this API in order to get to the first element in the list.

Parameters:
[in] stmtH Statement handle that has been initialized with an alp_contacts_dml_*_statement_init() API
Returns:
ALP_STATUS_CONTACTS_DML_* error

alp_status_t alp_contacts_dml_thumbnail_statement_begin (  AlpDmlH  dmlH,
AlpLuid  personLuid,
AlpDmlStatementH *  thumbnailStmtH,
int32_t *  numResults
) 
 

Creates and initializes a new AlpDmlStatementH that can be used to iterate over a set of ThumbnailItem's in the Contacts data model.

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 values 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 thumbnailStmtH 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] personLuid This parameter specifies a personLuid filter to use when building the statement handle. If 0, the statement will include all thumbnails in the datamodel. If set to a valid personLuid, it will only retrieve thumbnails associated with that person.
[out] thumbnailStmtH 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 ExtraFieldItems 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_thumbnail_statement_begin_with_columns (  AlpDmlH  dmlH,
AlpLuid  personLuid,
const AlpContactsDmlColumnType *  columnTypes,
int16_t  numColumnTypes,
AlpDmlStatementH *  thumbnailStmtH,
int32_t *  numResults
) 
 

Creates and initializes a new AlpDmlStatementH that can be used to iterate over a set of ThumbnailItem's in the Contacts data model 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 values 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 thumbnailStmtH 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] personLuid This parameter specifies a personLuid filter to use when building the statement handle. If 0, the statement will include all thumbnails in the datamodel. If set to a valid personLuid, it will only retrieve thumbnails associated with that person.
[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] thumbnailStmtH 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 ExtraFieldItems 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

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

Copyright © 1999-2008 ACCESS CO., LTD. All rights reserved.