WSPRegisterMemory function

Artikel
06/19/2017

WSPRegisterMemory registers a buffer that a socket can use as either the local source or the local target of a data transfer operation. A socket can use this buffer as the source in WSPRdmaWrite and WSPSend calls and the receiving buffer in WSPRdmaRead and WSPRecv calls.

Syntax

HANDLE WSPRegisterMemory(
  _In_  SOCKET s,
  _In_  PVOID  lpBuffer,
  _In_  DWORD  dwBufferLength,
  _In_  DWORD  dwFlags,
  _Out_ LPINT  lpErrno
);

Parameters

s [in]
Descriptor that identifies a connected socket.
lpBuffer [in]
Pointer to the memory buffer to register.
dwBufferLength [in]
Size, in bytes, of the memory buffer at lpBuffer.
dwFlags [in]
Set of flags that specify supplementary information about the memory buffer and registration options.
lpErrno [out]
Pointer to a variable that receives the error code.

Return value

Returns a valid handle to the memory buffer if successful; otherwise, returns NULL for the handle and, at lpErrno, one of the following error codes:

Return code	Description
WSANOBUFS	No memory resources available.
WSAEFAULT	lpBuffer is not contained completely within a valid part of the user-address space.
WSAEINVAL	Invalid flags specified.
WSAENOTCONN	Socket is not connected (connection-oriented sockets only).

Remarks

The Windows Sockets switch calls the WSPRegisterMemory function to register a memory buffer for use by a specific socket. The returned handle to the memory buffer is valid only in the context of the socket for which it was registered.

The switch can call the WSPRegisterMemory function more than once to register the same buffer for use with any number of sockets. A SAN service provider is not required to return a different handle to a memory buffer when the switch registers that memory buffer for use by another socket. However, the SAN service provider should maintain an internal reference count of the number of registered instances of that memory buffer. Calls to the SAN service provider's WSPDeregisterMemory function decrement this internal reference count. Only during the final call to WSPDeregisterMemory(when the SAN service provider's internal reference count for that buffer reaches zero) should the SAN service provider release all the resources that it used to register the buffer.

The switch specifies how the registered memory is to be accessed in dwFlags by specifying one of the following flags:

MEM_READ
Read access
MEM_WRITE
Write access
MEM_READWRITE
Both read and write access

The SAN service provider must obtain memory that can be accessed as specified in dwFlags.

The switch requires that the registered memory have read access if the switch subsequently calls the SAN service provider's WSPRdmaWrite and WSPSend functions. The switch requires that the registered memory buffer have write access if the switch subsequently calls the SAN service provider's WSPRdmaRead and WSPRecv functions.

Even though the switch registers memory buffers that it uses in all data transfer operations, the switch only explicitly uses handles to those memory buffers in RDMA data transfer operations. That is, the switch specifies such handles when calling a SAN service provider's WSPRdmaWrite and WSPRdmaRead functions for RDMA transfers. However, the switch does not specify such handles when calling a SAN service provider's WSPSend and WSPRecv functions for message-oriented transfers. A SAN service provider must maintain its own mapping of memory buffers to handles for message-oriented transfers.

A SAN service provider must prevent unauthorized access to memory that the switch registered for local access. Only the process that called WSPRegisterMemory to register memory should be allowed to access such memory. A SAN service provider must ensure that it does not inadvertently make such memory accessible to other processes running on the same computer or on other computers on the SAN.

Requirements

Target platform	Desktop
Version	Requires Windows Sockets version 2.2.
Header	Ws2san.h (include Ws2san.h)

Bagikan melalui