Developer

API Reference

ITRIGMLELEMENT_AttachData()

deprecated
Items marked as deprecated have been replaced by a more powerful, alternative feature. Deprecated interfaces include a reference to the replacement interface, which should be used for all new application development. Deprecated features are still supported for backward compatibility, but should be avoided when developing new applications.
Brew Release
Brew MP 1.0.2
See Also
ITRIGMLELEMENT_GetAttachedData()
Description
Attaches a caller-allocated data context to a Trigml element.
Parameters
  • po
    []:
    The Trigml element to which to attach the context.
  • classId
    []:
    The class ID of the extension attaching the context.
  • data
    []:
    The data context to attach. Pass NULL to free an old data context without attaching a new one, the old data context will be freed using the associated pFreeFn supplied when the data context was registered.
  • pFreeFn
    []:
    Address of the function to be called when the data context is to be freed.
Interface
ITRIGMLELEMENT
Prototype
   int ITRIGMLELEMENT_AttachData(ITrigmlElement* po, AEECLSID classId, void* data, FreeITrigmlElementAttachedDataFn* pFreeFn);
Return
   SUCCESS if the data context was successfully attached.
   ENOMEMORY if the data context could not be attached due to a memory
   shortage.  In this case, it is the caller's responsibility to decide whether
   to free the context.
Comment
This function is provides a Trigml extension with the means to attach a private data context to any Trigml element. The extension should allocate the buffer however it wishes, then call ITRIGMLELEMENT_AttachData(), providing the extension's own class ID as an identifier for the buffer (different extensions can attach their own data contexts to the same element).
When the element is destroyed, the supplied FreeITrigmlElementAttachedDataFn is called with the extension class ID and attached data pointer as parameters. The function should free or release any data or objects stored in the context, and then then free the context itself (so if you allocated it with MALLOC(), the supplied FreeITrigmlElementAttachedDataFn should FREE() it). If no action is required on freeing the data (i.e. the lifecycle of the data context is managed elsewhere), you can pass NULL as the FreeITrigmlElementAttachedDataFn.
Calling ITRIGMLELEMENT_AttachData() a second time with the same class ID will cause the original data context to be freed before the new one is attached. To cause the a data context to be freed before the element is destroyed, call ITRIGMLELEMENT_AttachData() a second time and pass NULL as the new data context pointer.
  • Follow