Developer

API Reference

IResFile_GetNamedChildren()

Brew Release
Brew MP 1.0.2
See Also
IResFile Interface IResFile_GetNamed()
Description

Gets the names of all children of the provided parent. The names will be returned in a null terminated set of null terminated strings. Also returned will be the total number of children found.
If buf is NULL, the number of children found will be returned in pnrElem, and the total size of the buffer required for all of the names will be returned in plen.
If plen is NULL, only the number of children found will be returned in pnrElem.
The parent name can be given as a variable set of null terminated string arguments. Each string specifies one or more levels in the naming tree. A simple string without '.' characters specifies a single level in the naming tree where as a dot separated set of names in a string specify a series of names in the naming tree.
To specify the 'Root' of the dictionary in order to retrieve the names of the top-level children, use a string containing a single dot ( "." ) for the parent name.
Retrieving the names of children for "Main.Intro.Properties" could be accomplished by the following sequence of commands:
      IResFile_GetNamedChildren(piResFile, NULL, pLength, pNumChildren, "Main.Intro.Properties", 0);

after this command, the value "pLength" can be used to allocate a buffer. A second command:
      
      IResFile_GetNamedChildren(piResFile, pNewBuf, pLength, pNumChildren, "Main.Intro.Properties", 0);

would then return the names of all children.
Note that this buffer contains a number of null terminated strings, and a final null terminating character marking the end of the set. So a parent which has 2 children named "Child1" and "Child2", respectively, would return the following buffer:
{'C','h','i','l','d','1',\0,'C','h','i','l','d','2',\0,\0}
The number of elements would be 2, and the buffer size would be 15.
Retrieving the names of the top-level children (those under the root level), could be accomplished by the following commands:
      IResFile_GetNamedChildren(piResFile, NULL, &nLength, &nNumChildren, ".", 0);

      // -- allocate buffer 'pBuffer' here --

      IResFile_GetNamedChildren(piResFile, pBuffer, &nLength, &nNumChildren, ".", 0);

Which would fill the buffer 'pBuffer' with the names of the top-level children.
Parameters
  • pif
    []:
    [in] A pointer to an IResFile object.
  • buf
    []:
    [in/out] A pointer to a buffer which will receive the children names.
  • plen
    []:
    [in/out] A pointer to the total size of the output buffer.
  • pnrElem
    []:
    [out] A pointer to the number of children found ...: [in] Null-terminated string list of names (see above)

Interface
Prototype
   int IResFile_GetNamedChildren(IResFile *pif, void *buf, uint32 *plen, uint32 *pnrElem, ...)
Return
   AEE_SUCCESS:       Named resource was found and loaded
   AEE_EBADPARM:      An argument was invalid, or the buffer size was too small for the result
   AEE_EBADSTATE:     Resource file is not open 
   AEE_EUNABLETOLOAD: Named parent resource could not be resolved or loaded

Side Effect
None
Comment
This function is a shortcut function for the interface function IResFile_GetNamedChildrenV() which takes an actual vararg parameter.
If multiple resource files were opened in IResFile_Open(), all of the applicable children will be returned for a given parent. In our example above, if "Main.Intro.Properties" existed in 2 resource files, the combined list of children (without duplicates) will be returned.
Note: plen and pnrElem can be output as 0 if the parent has no children. Callers should watch for this before allocating memory.
  • Follow