ITabletContextP::UseNamedSharedMemoryCommunications method

Article
01/07/2021

Sets up shared memory communication for the tablet context.

Syntax

HRESULT UseNamedSharedMemoryCommunications(
  [in]  DWORD  pid,
  [in]  LPCSTR pszCallerSid,
  [in]  LPCSTR pszCallerIntegritySid,
  [out] DWORD  *pdwEventMoreDataId,
  [out] DWORD  *pdwEventClientReadyId,
  [out] DWORD  *pdwMutexAccessId,
  [out] DWORD  *pdwFileMappingId
);

Parameters

pid [in]: The process ID of the client that accesses shared memory.
pszCallerSid [in]: The security identifier of the function caller.
pszCallerIntegritySid [in]: The security identifier that can verify the integrity of the calling function.
pdwEventMoreDataId [out]: An integer used to construct the name of an event. The event indicates whether there is more data.
pdwEventClientReadyId [out]: An integer used to construct the name of an event. The event signals that the client is ready to receive data. The event is signaled after processing new data.
pdwMutexAccessId [out]: A pointer to the access identifier of the shared memory.
pdwFileMappingId [out]: An integer that identifies the shared memory.

Return value

If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

Remarks

The UseNamedSharedMemoryCommunications method is part of the Tablet PC shared memory protocol. A client without elevated privileges passes in a security identifier (SID) and an integrity level security identifier (IL-SID) so that the Tablet service can use access control lists (ACL) to access the shared memory objects. If the client has elevated privileges, it should use UseSharedMemoryCommunications, which is the API that is called if the service already has an elevated privilege.

The SHAREDMEMORY_HEADER structure stores the shared memory header.

The SHAREDMEMORY_HEADER structure is cast from the data referenced by the file mapping. The raw packet data follows the SHAREDMEMORY_HEADER. Raw packet data can be read off of the shared memory when the event referenced by pdwEventClientReadyId is raised.

The following list describes the sequence of events for accessing and using shared memory.

The client raises the clientReady event.
The client waits for the moreData event.
The client acquires the mutex.
The client reads packet data from the section of shared memory that follows the header. Serial numbers appear in the shared memory after the packet data.
The client handles data depending on the value of dwEvent.
The client writes -1 (0xFFFFFFFF) into dwEvent.
The client releases the mutex.
The client raises the clientReady event.

The event names are created by formatting the output of this method. The following definitions can be used in conjunction with sprintf or its equivalent to create the event names.

#define WISPTIS_SM_MORE_DATA_EVENT_NAME     _T("wisptis-1-%d-%u")
#define WISPTIS_SM_CLIENT_DONE_EVENT_NAME   _T("wisptis-2-%d-%u")
#define WISPTIS_SM_SECTION_NAME             _T("wisptis-3-%d-%u")
#define WISPTIS_SM_THREAD_EVENT_NAME        _T("wisptis-4-%u")

In each definition, the %d section is replaced with the process ID, and the %u section is replaced with the integer returned in pdwEventMoreDataId or pdwEventClientReadyId.

Requirements

Requirement	Value
Minimum supported client	Windows Vista [desktop apps only]
Minimum supported server	None supported
Library	Wisptis.exe