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

Developer

API Reference

ISETTINGS_GETCHILDNAME()

Brew Release
Brew MP 1.0.2
See Also
Error Codes ISettings ISettings_GetNumChildren
Description
This method returns the name of the Nth child under the specified settings subtree. The name is returned as a NULL-terminated string. Children that represent settings subtrees are recognized by a trailing delimiter in their names.
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.
Params
_me
[]:
[in] A pointer to the ISettings object.
key
[]:
[in] A NULL-terminated string representing the settings subtree over which to enumerate.
nChild
[]:
[in] 1-based index specifying which child name to retrieve.
result
[]:
[out] If resultLen is set to 0, this parameter is ignored. Otherwise, this buffer is filled with as much of the requested data as will fit, along with a NULL for termination.
resultLen
[]:
[in] The total size (in bytes) of the result buffer, or 0 to query for required buffer size only.
resultLenReq
[]:
[out] On return, resultLenReq is set to the buffer size required to allow the complete child name and terminating NULL character to be stored. May also be NULL if the caller doesn't care to know.
Interface
Prototype
  •    int ISettings_GetChildName(ISettings *_me, 
                                  const char *key, 
                                  int child,
                                  char *result,
                                  int resultLen,
                                  int *resultLenReq);
    
Return
  • AEE_SUCCESS : The child name was successfully retrieved. AEE_EBADITEM : The requested settings subtree or child does not exist. AEE_EUNSUPPORTED : The operation isn't supported by the implementation. AEE_EPRIVLEVEL : The caller does not have sufficient privileges for this operation. Error code : Otherwise.
Side Effect
  • None
Comments
Retrieving the names of children for "mail/accounts" may be accomplished with the following sequence of commands. Note that an initial call to ISettings_GetNumChildren() is used to determine how many mail accounts exist. A loop then iterates over each, calling ISettings_GetChildName() once to determine the size of the child's name, then a second time to read the value. For example: const char gpszUri[] = "mail/accounts"; int nNumChildren; // retrieve the total number of mail accounts if (AEE_SUCCESS == ISettings_GetNumChildren(_me, gpszUri, &nNumChildren)) { while (nNumChildren) { int nLenReq; // determine size of the current child if (AEE_SUCCESS == ISettings_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 = ISettings_GetChildName(_me, gpszUri, nNumChildren, pAccount, nLenReq, NULL)); if (AEE_SUCCESS == nErr) { // do something with this data } // release the buffer FREE(pAccount); // next child nNumChildren--; } } } }