SHMapHandle

This function duplicates a handle, given 32-bit process identifiers for the source and target processes.

Declaration

HANDLE
SHMapHandle (
    HANDLE hSourceHandle,
    DWORD dwSourceProcessId,
    DWORD dwTargetProcessId,
    DWORD dwDesiredAccess,
    DWORD dwOptions);

Parameters

The handle to be duplicated is given by the hSourceHandle argument in the context of the process that is given as a 32-bit process identifier (PID) by the dwSourceProcessId argument.

The dwTargetProcessId argument provides the PID of the process whose context is to gain a duplicate of the given handle.

The dwDesiredAccess argument provides the access rights that are desired for the duplicate handle in the target process.

The dwOptions argument provides options for the duplication operation. It can be zero or a bit-wise combination of the documented values DUPLICATE_CLOSE_SOURCE and DUPLICATE_SAME_ACCESS.

Return Value

If successful, the function returns the duplicate handle, which is meaningful in the context of the given target process. Otherwise, the function returns NULL.

Behaviour

The SHMapHandle function may best be seen as a repackaging of the standard API function DuplicateHandle for ease of use in code that knows processes by their PIDs. The work of obtaining handles to the source and target processes is then an internal matter for SHMapHandle.

If the hSourceHandle argument is NULL, then there is no handle to duplicate and the function fails.

The function attempts to obtain a handle (in the context of the current process, with at least PROCESS_DUP_HANDLE rights) for each of the processes given by the dwSourceProcessId and  dwTargetProcessId arguments. The function fails if it cannot obtain both such handles.

No provision exists for asking that the duplicate handle be inheritable.

Current implementations necessarily create the duplicate handle with the same access rights as the given handle, whatever is given in the dwDesiredAccess and dwOptions arguments. (Specifically, the DUPLICATE_SAME_ACCESS option is forced for the function’s internal call to DuplicateHandle.)

Availability

The SHMapHandle function is exported from SHLWAPI.DLL as ordinal 11 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.