WSPRegisterMemory function
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 accessMEM_WRITE
Write accessMEM_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) |
See also
WSPMemoryRegistrationCacheCallback