SHAllocShared

This function creates a memory object for sharing data among processes.

Declaration

HANDLE
SHAllocShared (
    LPCVOID lpData,
    DWORD dwSize,
    DWORD dwProcessId);

Parameters

The optional lpData argument provides the address of data to copy into the shared memory, or is NULL.

The dwSize argument provides the size of the shared memory area. If lpData is not NULL, then dwSize is also the number of bytes that will be copied from lpData when initialising the shared memory area.

The dwProcessId argument provides the process identifier (PID) of a process that is to participate in the sharing.

Return Value

If successful, the function returns a handle in the context of the given process. This handle may subsequently be given among the inputs to the other SHLWAPI functions that manage shared memory.

Otherwise, the function returns NULL.

Behaviour

The shared memory area lies within an unnamed file-mapping object backed by the paging file. The location of the shared memory within the file-mapping object is not formally specified. (Current implementations have a 16-byte header preceding the shared memory.) The function fails if it cannot create a sufficiently large file-mapping object or if it cannot map a view of that object into the current process’s address space.

If the lpData argument is not NULL, the function also copies dwSize bytes from lpData to the shared memory area within the file-mapping object.

The function tries to obtain in the context of the process given by the dwProcessId argument a handle to the file-mapping object. This is the handle that the function returns. It is clearly not intended that this handle be used directly to map a view of the file-mapping object, but should instead be treated as meaningful only to the other SHLWAPI functions that manage shared memory.

Availability

The SHAllocShared function is exported from SHLWAPI.DLL as ordinal 7 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 SHAllocShared as ordinal 520. 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 _SHAllocShared 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.