ntxMapRtSharedMemoryEx

Obtains a pointer to a shared memory object.

LPVOID ntxMapRtSharedMemoryEx(
    NTXHANDLE hSegment,
    DWORD dwFlags
);

Parameters

hSegment

Handle to the memory area allocated by the RT application.

dwFlags

Specifies the properties of the mapped view to the RT shared memory. Possible flags include:

`NTX_MAP_WRITE`	The mapping is writeable. Mappings are always readable;
`NTX_MAP_UNALIGNED`	Allows the mapping of non page-aligned segments. If this is omitted and the segment boundary is not page-aligned, the status E_ALIGNMENT is returned.

Remarks

Mapping consumes resources in the Windows process. You can use ntxUnmapRtSharedMemory to return resources.

You can map an address space multiple times. Each operation returns the same pointer value. The first unmap invalidates this pointer.

If the NTX application must operate on data that contains RTHANDLEs, you must convert the handles using ntxImportRtHandle.

Due to Windows limitations, the maximum size you can map in a single call is as follows:

Windows XP 32-bit - 0x03ff8000 bytes
Windows XP 64-bit - 0x01ff0000 bytes
Windows Vista - 0x7ffff000 bytes
Windows 7 and up - 0xfffff000 bytes

The actual size that you can map depends on the free virtual address space available in your Windows process.

Warning: NTX maintains a cache of mapped memory handles for efficiency. This means that if you attempt to remap a handle that is already mapped, the call will return the cached value rather than recalculating the mapping. This in turn means that it is essential to call ntxUnmapRtSharedMemory when you are finished with a memory handle, otherwise if that handle value is reused and passed back to Windows the results will be unpredictable.

Return Values

A pointer to the address space specified in hSegment.: Success.
NULL: Failure.

Status

E_TYPE 0x8002: hSegment is not an address space.
E_ALIGNMENT 0x80f1: hSegment is not page-aligned on both ends and the NTX_MAP_UNALIGNED value was not specified in dwFlags.
E_LOCATION 0x8f02: hSegment is located in an RT kernel that does not share memory with the host of the NTX application.
E_STATE 0x0007: A call to ntxMapRtSharedMemoryEx (or equivalent operation) was previously made with a different value for dwFlags
E_NTX_INTERNAL_ERROR 0x1001: The DLL could not contact the RT kernel to complete the request.

Requirements

Versions	Defined in	Include	Link to
INtime 3.0	intime/nt/include/ntx.h	ntx.h	ntx.lib
INtime 4.01 (for 64-bit Windows)	intime/nt/include/ntx.h	ntx.h	ntx64.lib