API Reference | developer.brewmp.com API Reference | developer.brewmp.com

Developer

API Reference

PIM_ICONTACTSRECORD

Brew Release
Brew MP 1.0.2
See Also
pim_IContacts, pim_IContacts_CreateRecord()
Description
The pim_IContactsRecord interface is used to represent a contact that is stored in the different pim_IContacts implementations that access EFS and card based phonebooks.
A contacts record is a collection of name/value pairs arranged in a tree structure. Field names are strings, values are UTF-16 encoded wide-strings. Applications use this interface to build up a contacts record, then use the pim_IContacts interface to write the record to a particular phonebook.
Contacts record fields are accessed via a uri that uniquely identifies them. The root level of the contacts records contains a single instance of the top level fields - either one of the default fields defined in the pim_IContacts implementation documentation or a custom field created via the pim_IContacts interface, assuming custom fields are supported by the implementation. Multiple isntances of a particular field are stored as children of the top level field, each indentified via a unique path. For example, a pim_IContactsRecord may contain the following data:

   Name                                Uri
      1     
         Type = L"FIRSTNAME"           Name/1/Type
         Value = L"John"               Name/1/Value
      2
         Type = L"LASTNAME"            Name/2/Type
         Value = L"Smith"              Name/2/Value
   Phone
      1
         Type = L"CELL"                Phone/1/Type
         Value = L"9995555678"         Phone/1/Value
      2
         Type = L"HOME"                Phone/2/Type
         NumberPlan = L"Private"       Phone/2/NumberPlan
         Value = L"9995551234"         Phone/2/Value

A uri of "Name/1/Value" would be used to access the first name, "John". A uri of "Phone/2/Numberplan" would be used to access the number plan of the Home phone number - "Private".
A uri of "" (empty string) can be used to iterate over all of the subfields, returning "Name/" and "Phone/". Iterating over "Phone/" would reveal the Phone subfields, "1/" and "2/". Iterating over "Phone/2/" would reveal "Phone/2/Type", "Phone/2/NumberPlan" and "Phone/2/Value".
Different pim_IContacts implementations access different phone books and support different subsets of fields. The fields and subfields a pim_IContacts implementation supports are documented in the implementation's documentation, and constants for each are defined in the pim_IContacts .bid file.
It is up to the caller to insure that all mandatory fields and no unsupported fields exist in a record before it's written to a device. Failure to do so will result in errors from the pim_IContacts interface when the record is written to the underlying contacts device. Developers can refer to the class documentation of the pim_IContacts object they're using to discover what fields are supported and which fields are mandatory.