B.6. WDS High-Level API

This section describes the WDS API defined in the WinDriver/include/wds_lib.h header file.

B.6.1. WDS_SharedBufferAlloc()

Purpose

Allocates a memory buffer that can be shared between the user mode and the kernel mode ("shared buffer"), and returns user-mode and kernel-mode virtual address space mappings of the allocated buffer.

[Note]
This function provides a useful method for sharing data between a user-mode application and a Kernel PlugIn driver.
Prototype
DWORD DLLCALLCONV WDS_SharedBufferAlloc(
    UINT64 qwBytes,
    DWORD dwOptions,
    WD_KERNEL_BUFFER **ppBuf);
Parameters
NameTypeInput/Output
qwBytesUINT64Input
dwOptionsDWORDInput
ppBufWD_KERNEL_BUFFER**Output
Description
NameDescription
qwBytesThe size of the buffer to allocate, in bytes
dwOptions

Kernel buffer options bit-mask, which can consist of a combination of the enumeration values listed below.

KER_BUF_ALLOC_NON_CONTIG:Allocates a non contiguous buffer
KER_BUF_ALLOC_CONTIG:Allocates a physically contiguous buffer
KER_BUF_ALLOC_CACHED:Allocates a cached buffer. This option can be set with KER_BUF_ALLOC_NON_CONTIG or KER_BUF_ALLOC_CONTIG buffer

ppBuf Pointer to a WD_KERNEL_BUFFER [B.7.11] pointer, to be filled by the function.
The caller should use *ppBuf->pUserAddr usermode mapped address. When the buffer is no longer needed, (*ppBuf) should be passed to WDS_SharedBufferFree() [B.6.2].
[Note]
The KER_BUF_ALLOC_NON_CONTIG option is valid only as part of "WinDriver for Server" API and requires "WinDriver for Server" license. Note that "WinDriver for Server" APIs are included in WinDriver evaluation version.
Return Value

Returns WD_STATUS_SUCCESS (0) on success, or an appropriate error code otherwise [B.11].

Remarks
  • This function is currently only supported from the user mode.
  • This function is supported only for Windows and Linux.

B.6.2. WDS_SharedBufferFree()

Purpose

Frees a shared buffer that was allocated by a previous call to WDS_SharedBufferAlloc() [B.6.1].

Prototype
DWORD DLLCALLCONV WDS_SharedBufferFree(
    WD_KERNEL_BUFFER *pBuf);
Parameters
NameTypeInput/Output
pBufWD_KERNEL_BUFFER *Input
Description
NameDescription
pBuf Pointer to a WD_KERNEL_BUF [B.7.11] structure, received within the *ppBuf parameter of a previous call to WDS_SharedBufferAlloc() [B.6.1]
Return Value

Returns WD_STATUS_SUCCESS (0) on success, or an appropriate error code otherwise [B.11].

Remarks
  • This function is currently only supported from the user mode.
  • This function is supported only for Windows and Linux.

B.6.3. WDS_SharedBufferGet()

Purpose

Retrieves a shared buffer which was allocated by another process.

[Note]
This API is not part of the standard WinDriver APIs, and is not included in the standard version of WinDriver. It is part of "WinDriver for Server" API and requires "WinDriver for Server" license. Note that "WinDriver for Server" APIs are included in WinDriver evaluation version.
Prototype
DWORD DLLCALLCONV WDS_SharedBufferGet(
    DWORD hKerBuf, 
    WD_KERNEL_BUFFER **ppKerBuf);
[Note]
Before calling this API, the calling process should recieve the global buffer handle via WinDriver IPC mechanism from the process that allocated the buffer.
[Note]
Once the process finish using the shared buffer, it should release it using the regular free method- WDS_SharedBufferFree() [B.6.2].
Parameters
NameTypeInput/Output
hKerBufDWORDInput
ppKerBufWD_KERNEL_BUFFER**Output
Description
NameDescription
hKerBuf Kernel buffer handle.
ppKerBuf Pointer to a pointer to a kernel buffer information structure [B.7.11], which is associated with hKerBuf.
Return Value

Returns WD_STATUS_SUCCESS (0) on success, or an appropriate error code otherwise [B.11].

B.6.4. WDS_SharedBufferGetGlobalHandle Macro

Purpose

Utility macro that returns a kernel buffer global handle that can be used for buffer sharing between multiple processes.

Prototype
WDS_SharedBufferGetGlobalHandle(pKerBuf)
Parameters
NameTypeInput/Output
pKerBufWD_KERNEL_BUFFER*Input
Description
NameDescription
pKerBuf Pointer to a kernel buffer information structure [B.7.11]
Return Value

Kernel buffer handle of pKerBuf.