SHFreeShared

Declaration

Parameters

The dwProcessId argument is the process
identifier (PID) of the process that provides the context for interpreting the
given handle.

Return Value

The function returns a non-zero value if successful, else FALSE.

Behaviour

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.

Availability

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.

This page was created on 3rd September 2004 and was last
modified on 15th March 2007.