Product SiteDocumentation Site

3.7. PMAPI Programming Style and Interaction

The following sections describe the PMAPI programming style:
  • Variable length argument and results lists
  • Python specific issues
  • PMAPI error handling

3.7.1. Variable Length Argument and Results Lists

All arguments and results involving a “list of something” are encoded as an array with an associated argument or function value to identify the number of elements in the array. This encoding scheme avoids both the varargs approach and sentinel-terminated lists. Where the size of a result is known at the time of a call, it is the caller's responsibility to allocate (and possibly free) the storage, and the called function assumes that the resulting argument is of an appropriate size.
Where a result is of variable size and that size cannot be known in advance (for example, pmGetChildren, pmGetInDom, pmNameInDom, pmNameID, pmLookupText, pmLookupLabels and pmFetch), the underlying implementation uses dynamic allocation through malloc in the called function, with the caller responsible for subsequently calling free to release the storage when no longer required.
In the case of the result from pmFetch, there is a function (pmFreeResult) to release the storage, due to the complexity of the data structure and the need to make multiple calls to free in the correct sequence. Similarly, the pmLookupLabels function has an associated function (pmFreeLabelSets) to release the storage.
As a general rule, if the called function returns an error status, then no allocation is done, the pointer to the variable sized result is undefined, and free, pmFreeLabelSets, or pmFreeResult should not be called.