WSPRdmaWrite function

WSPRdmaWrite transfers data from a source buffer in an address space that is accessible only by a local socket to a target buffer in an address space that is accessible by the socket's remote peer.

Syntax

int WSPRdmaWrite(
  _In_     SOCKET                             s,
  _In_     LPWSABUFEX                         lpBuffers,
  _In_     DWORD                              dwBufferCount,
  _In_     LPVOID                             lpTargetBufferDescriptor,
  _In_     DWORD                              dwTargetDescriptorLength,
  _In_     DWORD                              dwTargetBufferOffset,
  _Out_    LPDWORD                            lpdwNumberOfBytesWritten,
  _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 source buffer array. 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 the target RDMA buffer in the address space that is accessible by the socket's remote peer. This descriptor was returned from a previous call to the WSPRegisterRdmaMemory function.

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

• dwTargetBufferOffset [in]
  Offset, in bytes, in the target RDMA buffer at which to begin the data transfer. The descriptor at lpTargetBufferDescriptor identifies this target RDMA buffer.

• lpdwNumberOfBytesWritten [out]
  Pointer to a variable that receives the number of bytes that WSPRdmaWrite transfers from source to target buffers.

• 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 the WSPRdmaWrite function to transfer data from the source buffer at lpBuffers on the local computer to the target buffer that is identified by the descriptor at lpTargetBufferDescriptor. This target buffer is in the address space for the remote peer connection. The switch at the remote peer connection calls the WSPRegisterRdmaMemory function to register the target buffer for write 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 target buffer. The local switch can then call the WSPRdmaWrite function to transfer data to the target buffer.

A SAN service provider receives WSPRdmaWrite requests only from the switch, but never directly from an application. The switch calls the SAN service provider's WSPRdmaWrite function only 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 WSPRdmaWrite function, the switch posts source and target buffers for the data transfer operation. If the data transfer operation cannot complete immediately, the operation proceeds, but WSPRdmaWrite 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 WSPRdmaWrite 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 WSPRdmaWrite function with a value of zero and, at lpdwNumberOfBytesWritten, specifies the number of bytes transferred from source to target buffers. If the SAN service provider successfully initiated the data transfer operation and will indicate completion at a later time, the SAN service provider returns from the WSPRdmaWrite function 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 lpdwNumberOfBytesWritten. After the data transfer operation completes, the switch calls the SAN service provider's WSPGetOverlappedResult function and passes a pointer to a variable that holds data transfer information. In this variable, the SAN service provider specifies the number of bytes transferred from source to target 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 the switch calls the SAN service provider's WSPRdmaWrite 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

WSPSend

Send comments about this topic to Microsoft