Geoff Chappell - Software Analyst
This function releases an inner object’s interface.
VOID SHWeakReleaseInterface (
IUnknown *punkOuter,
IUnknown **ppunk);
The punkOuter argument is an interface pointer to an outer object.
The ppunk argument provides the address of a variable in which the caller may hold an interface pointer to an inner object.
If the variable at ppunk holds NULL, then there is no interface pointer to the inner object, and the function does nothing. Otherwise, the function adds a reference to the outer object, clears the interface pointer and releases whatever the interface pointer had been pointing to.
The function seems intended to ease some bookkeeping with COM aggregation. An outer (aggregating) object contains an inner (aggregable) object such that the inner object’s interfaces seem to be those of the outer object. Reference counting for the pair requires that whenever an interface pointer to the inner object is released, the reference returns to the outer object’s IUnknown interface.
The SHWeakReleaseInterface function seems intended to ease some bookkeeping with COM aggregation. An outer (aggregating) object contains an inner (aggregable) object such that the inner object’s interfaces seem to be those of the outer object. Part of the technique is that the inner object implements an explicit IUnknown interface that gives access to its other interfaces, but has all its other interfaces delegate their IUnknown methods to an outer IUnknown interface provided by the outer object. Proper reference counting demands the following rule, which Microsoft’s page Aggregation (COM) expresses as:
To free this pointer, the outer object calls its controlling IUnknown AddRef method, followed by Release on inner object’s pointer.
Using the SHWeakReleaseInterface function conveniently deals with both steps as one.
The SHWeakReleaseInterface function is exported from SHLWAPI.DLL as ordinal 268 in version 5.00 and higher.
Though this function dates from as long ago as 1999, it was still not documented by Microsoft as late as the January 2007 edition of the Windows Vista Software Development Kit (SDK).
Before Windows Vista, the SHWeakReleaseInterface function was imported by BROWSEUI.DLL, SHDOCVW.DLL and SHELL32.DLL. Since SHDOCVW is beyond debate as being part of Internet Explorer, the only way that this function can be exempt from needing to be documented among the Settlement Program Interfaces is that Microsoft does not count SHLWAPI as part of any Windows Operating System Product for the terms of the settlement. For Windows Vista, Microsoft evades the compliance issue. Where use of the function by BROWSEUI and SHDOCVW is transferred to or reproduced in the new DLL named IEFRAME, the latter does not import the function from SHLWAPI but instead calls its own copy.
Windows Vista also sees this function acquire new use, in TWEXT.DLL, which is the Time Warp namespace extension and is responsible for the Previous Versions tab in the Properties dialog for files.