WSPRdmaRead function

WSPRdmaRead transfers data from an RDMA buffer in an address space accessible by a socket's remote peer to a buffer in an address space accessible only by the local socket.

Syntax

int WSPRdmaRead(
  _In_     SOCKET                             s,
  _In_     LPWSABUFEX                         lpBuffers,
  _In_     DWORD                              dwBufferCount,
  _In_     LPVOID                             lpTargetBufferDescriptor,
  _In_     DWORD                              dwTargetDescriptorLength,
  _In_     DWORD                              dwTargetBufferOffset,
  _Out_    LPDWORD                            lpdwNumberOfBytesRead,
  _In_     DWORD                              dwFlags,
  _In_opt_ LPWSAOVERLAPPED                    lpOverlapped,
  _In_opt_ LPWSAOVERLAPPED_COMPLETION_ROUTINE lpCompletionRoutine,
  _In_     LPWSATHREADID                      lpThreadId,
  _Out_    LPINT                              lpErrno
);

Parameters

• s [in]
  Descriptor that identifies a connected socket.

• lpBuffers [in]
  Pointer to an array of WSABUFEX structures. Each WSABUFEX structure contains members that describe a previously registered buffer in the buffer array. This buffer array receives transferred data. Each buffer was registered in a call to the WSPRegisterMemory function.

• dwBufferCount [in]
  Number of WSABUFEX structures at lpBuffers.

• lpTargetBufferDescriptor [in]
  Pointer to a memory block that contains a descriptor. This descriptor identifies an RDMA buffer in the address space accessible by the socket's remote peer. This descriptor was returned from a previous call to the WSPRegisterRdmaMemory function. Data is transferred from this RDMA buffer to the buffer at lpBuffers.

• dwTargetDescriptorLength [in]
  Size, in bytes, of the memory block at lpTargetBufferDescriptor.

• dwTargetBufferOffset [in]
  Offset, in bytes, into the RDMA buffer at which to begin the data transfer. The descriptor at lpTargetBufferDescriptor identifies this RDMA buffer. Data is transferred from this RDMA buffer to the buffer at lpBuffers.

• lpdwNumberOfBytesRead [out]
  Pointer to a variable that receives the number of bytes that WSPRdmaRead transfers from the RDMA buffer to the buffer at lpBuffers.

• dwFlags [in]
  Set of flags that specify how the call is made.

• lpOverlapped [in, optional]
  Pointer to a WSAOVERLAPPED structure that provides a communication medium between the initiation of an overlapped I/O operation and its subsequent completion. Ignored for nonoverlapped sockets.

• lpCompletionRoutine [in, optional]
  Pointer to the completion routine that the SAN service provider can initiate after the data transfer operation completes. Ignored for nonoverlapped sockets. The switch specifies NULL for a completion routine. To see the prototype for a completion routine, see WSPIoctl.

• lpThreadId [in]
  Pointer to a WSATHREADID structure that the SAN service provider can use in a subsequent call to the WPUQueueApc function to arrange for the execution of the completion routine at lpCompletionRoutine. A WSATHREADID structure identifies a thread. Because the switch specifies NULL for a completion routine, the SAN service provider does not use lpThreadId. For more information about WPUQueueApc, see the Microsoft Windows SDK documentation.

• lpErrno [out]
  Pointer to a variable that receives the error code.

Return value

Returns zero, if successful and the data transfer operation completed immediately; otherwise, returns SOCKET_ERROR and, at lpErrno, one of the following error codes:

Remarks

The Windows Sockets switch calls WSPRdmaRead to transfer data from the RDMA buffer that is identified by the descriptor at lpTargetBufferDescriptor to the buffer at lpBuffers on the local computer. This RDMA buffer is in the address space for the remote peer connection. The switch at the remote peer connection calls the WSPRegisterRdmaMemory function to register this RDMA buffer for read access. The switch at the remote peer connection then calls the WSPSend function to send to the local switch a control message that indicates the location of this RDMA buffer. The local switch can then call the WSPRdmaRead function to transfer data to a receiving buffer at lpBuffers.

A SAN service provider receives WSPRdmaRead requests only from the switch, but never directly from an application. The switch always calls the SAN service provider's WSPRdmaRead function in an overlapped manner. In this call, the switch always specifies an overlapped structure and NULL for a completion routine. In the call to the WSPRdmaRead function, the switch posts RDMA and receiving buffers for the data transfer operation. If the data transfer operation cannot complete immediately, the operation proceeds, but WSPRdmaRead returns with the WSA_IO_PENDING error code. The switch later calls the SAN service provider's WSPGetOverlappedResult function and passes a pointer to the overlapped structure to retrieve the final completion status.

The array of WSABUFEX structures at lpBuffers is transient. If the data transfer operation completes in an overlapped manner, the SAN service provider must capture these WSABUFEX structures before it returns from the WSPRdmaRead function with the WSA_IO_PENDING error code. This requirement enables applications to build stack-based WSABUFEX arrays.

Overlapped Socket I/O

If the data transfer operation completes immediately, the SAN service provider returns from the WSPRdmaRead function with a value of zero and specifies the number of bytes transferred from RDMA to receiving buffers at lpdwNumberOfBytesRead. If the SAN service provider successfully initiated the data transfer operation and will indicate completion at a later time, it returns from WSPRdmaRead with a value of SOCKET_ERROR and specifies the WSA_IO_PENDING error code at lpErrno. Note that, in this case, the SAN service provider does not specify a value at lpdwNumberOfBytesRead. After the data transfer operation completes, the switch calls the SAN service provider's WSPGetOverlappedResult function and passes a pointer to a variable in which the SAN service provider specifies the number of bytes transferred from RDMA to receiving buffers.

The overlapped structure at lpOverlapped must be valid for the duration of the data transfer operation. If multiple data transfer operations are outstanding simultaneously, each must reference a separate overlapped structure.

As mentioned previously, the switch always specifies an overlapped structure and NULL for a completion routine whenever it calls the SAN service provider's WSPRdmaRead function in an overlapped manner. Because the switch specifies NULL for a completion routine, the SAN service provider must call the WPUCompleteOverlappedRequest function in the context of an arbitrary thread to complete the request. If the low order bit of the hEvent member in the WSAOVERLAPPED structure is set, the switch specifically requests to not be notified upon completion of the I/O request. Therefore, the SAN service provider is not required to call the WPUCompleteOverlappedRequest function to complete the I/O request. In this case, the switch calls the WSPGetOverlappedResult function to poll for completion. For more information, see the GetQueuedCompletionStatus function in the Windows SDK documentation.

For more information about WPUCompleteOverlappedRequest, see the Windows SDK documentation.

Completion indications can be delivered in any order and not necessarily in the same order that the overlapped operations are completed.

Requirements

See also

WSABUFEX

WSAOVERLAPPED

WSPGetOverlappedResult

WSPRegisterMemory

WSPRegisterRdmaMemory

WSPRdmaWrite

WSPSend

Send comments about this topic to Microsoft