Developer

API Reference

PFNFREEHANDLER

Brew Release
Brew MP 1.0.2
See Also
- IHandler Interface
- IHandler_SetHandler()
- HANDLERDESC_Free()
- HandlerDesc
Description
This type definition specifies the prototype for the function pointer an application may register for the purpose of releasing private storage allocated for use specifically by a custom event handler. The private data utilized by an object implementing the handler interface is considered to be opaque, and could point to an arbitrarily complex data structure with its own unique storage requirements. The PFNFREEHANDLER callback function allows a handler to release "deep storage. This memory free handler will be called upon releasing the object implementing the handler interface. The pointer passed into the PFNFREEHANDLER callback may be freed in whatever manner is appropriate for the needs of the storage block. For example, then this pointer accesses a data structure containing "deep storage", the PFNFREEHANDLER would likely free each of the memory blocks pointed to from fields within this complex structure.
Members
  • pCxt:  A pointer to private data allocated and managed by the caller that
              has registered a custom handler.  This data pointer will be passed
              into the PFNFREEHANDLER to allow the callback to free any complex
              memory allocations associated with the storage block.
    
Definition
    typedef void (*PFNFREEHANDLER)(void *pCxt);
Comment
The PFNFREEHANDLER is registered by an object implementing the handler interface by initializing the 'pfnFree' field of a HandlerDesc data structure and calling that object's implementation of the IHandler_SetHandler() function. This will hook the PFNFREEHANDLER into that object's object release process. Upon registering the PFNFREEHANDLER, IHandler_SetHandler() will return a pointer to a HandlerDesc data structure that contains a pointer to the memory free that would have been called had the new handler not been registered. The PFNFREEHANDLER function should pass this HandlerDesc pointer to the old memory free handler by calling HANDLERDESC_Free() in order to ensure that normal memory disposal will still take place.
When the installed free function is called by the IHandler, it must NOT call back into the object through the context pointer (pCxt). For example, in a free function installed for a form, you must not call an IForm function with the form pointer, because the form is in the process of being destroyed and is in an indeterminate state. The free function should only use the pointer to access the installed handler's own members that need to be cleaned up.
  • Follow