Geoff Chappell - Software Analyst
This function destroys a shared memory area.
BOOL
SHFreeShared (
HANDLE hData,
DWORD dwProcessId);
The hData argument is a handle to the shared memory.
The dwProcessId argument is the process identifier (PID) of the process that provides the context for interpreting the given handle.
The function returns a non-zero value if successful, else FALSE.
If the hData argument is NULL, the function returns TRUE.
The function treats the hData and dwProcessId arguments as a pair that together identify the shared memory. In general, hData will have been the result of some earlier call to SHAllocShared (possibly in some other process) and dwProcessId will have been the last of the arguments given in that same call to SHAllocShared.
The handle refers to a file-mapping object that contains the shared memory. However, the handle is meaningful in the context of the given process, which need not be the current process. The function duplicates the given handle into the context of the current process, simultaneously closing the given handle. The function then closes the duplicate handle.
Once this function is called, the handle given by hData should be regarded as invalid. There should be no further attempts to access the shared memory by passing this handle to SHLockShared or SHLockSharedEx. Existing access to the shared memory, through views that have not yet been unmapped, remains valid. The file-mapping object gets released and the shared memory area destroyed when all outstanding views are eventually unmapped.
The SHFreeShared function is exported from SHLWAPI.DLL as ordinal 10 in version 4.71 and higher.
Though this function dates from as long ago as 1997, it was still not documented by Microsoft in the MSDN Library at least as late as the CD edition dated January 2004.
The function also exists indirectly as an export from SHELL32.DLL. Indeed, this existence predates its implementation in SHLWAPI. The NT releases of SHELL32 version 4.00, as long ago as 1996, and all releases of later SHELL32 versions export SHFreeShared as ordinal 523. From SHELL32 version 4.71, the implementation in SHELL32 is just a jump to the corresponding implementation imported from SHLWAPI. Late builds of SHELL32 version 6.00 export the function by name. This change may be related to Microsoft’s programme of documenting interfaces for compliance with a consent decree. A SHELL32 function named SHFreeShared was documented among the Settlement Program Interfaces in December 2002. The function is said there to require SHELL32 “version 5.0 or later”, as if to ignore three years or more of earlier existence.