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

Developer

API Reference

PIM_ICONTACTSRECORD_GETCHILDNAME()

Brew Release
Brew MP 1.0.2
See Also
pim_IContactsRecord_GetNumChildren()
Description
This method returns the name of the Nth child under the specified field subtree. The name is returned as a NULL-terminated string. Children that represent field subtrees are recognized by a trailing delimiter in their names.
If the caller wants to iterate over the top-level fields, a key of "/" should be specified. Otherwise, the caller might pass in "/email/" as the key to iterate through the email fields in the record, or "/email/1/" to iterate over the subfields of the first email in the record.
This method always returns the total size of the buffer required for the complete child name plus a terminating NULL character in the resultLenReq parameter. If this method is called with a non-0 resultLen, it will fill the specified buffer with as much of the child name that will fit and NULL terminate the result. The caller is responsible for providing a valid buffer and an accurate buffer size in this case.
On return, the caller must verify that the child name was properly retrieved by checking that no error code was returned. The caller may also wish to verify that the complete child name was returned in the buffer by comparing the value passed in for resultLen with the value returned in the resultLenReq parameter.
Prototype
  •    int pim_IContactsRecord_GetChildName(
          pim_IContactsRecord *pif,
          const char *key,
          int child,
          char *result,
          int resultLen,
          int *resultLenReq);
    
Return
  • AEE_SUCCESS if the child name was successfully retrieved
    AEE_EBADITEM if the requested settings subtree or child does not exist
    AEE_EUNSUPPORTED if the operation isn't supported by the implementation
    Error code otherwise
Side Effect
  • None
Comments
Retrieving the names of children for "email" may be accomplished with the following sequence of commands. Note that an initial call to pim_IContactsRecord_GetNumChildren() is used to determine how many mail fields exist. A loop then iterates over each, calling this method once to determine the size of the child's name, then a second time to read the value. const char gpszUri[] = "email"; int nNumChildren; // retrieve the total number of mail accounts if (AEE_SUCCESS == pim_IContactsRecord_GetNumChildren( _me, gpszUri, &nNumChildren)) { while (nNumChildren) { int nLenReq; // determine size of the current child if (AEE_SUCCESS == pim_IContactsRecord_GetChildName( _me, gpszUri, nNumChildren, NULL, 0, &nLenReq)) { // allocate a buffer for this child char *pAccount = (char*) MALLOC(nLenReq); if (pAccount != NULL) { // get the name/value of the child nErr = pim_IContactsRecord_GetChildName( _me, gpszUri, nNumChildren, pAccount, nLenReq, NULL)); if (AEE_SUCCESS == nErr) { // do something with this data } // release the buffer FREE(pAccount); // next child nNumChildren--; } } } }