WSPSend function

WSPSend sends data on a connected socket.

Syntax

int WSPSend(
  _In_  SOCKET                             s,
  _In_  LPWSABUF                           lpBuffers,
  _In_  DWORD                              dwBufferCount,
  _Out_ LPDWORD                            lpNumberOfBytesSent,
  _In_  DWORD                              dwFlags,
  _In_  LPWSAOVERLAPPED                    lpOverlapped,
  _In_  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 WSABUF structures. This array must remain valid for the duration of the send operation. Each WSABUF structure describes a buffer. The switch registered each buffer in a previous call to the WSPRegisterMemory function.

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

• lpNumberOfBytesSent [out]
  Pointer to a variable that receives the number of bytes that WSPSend sent.

• dwFlags [in]
  Must be zero.

• lpOverlapped [in]
  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]
  Pointer to the completion routine that the SAN service provider might initiate after the send 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 might 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 send operation completed immediately; otherwise, returns SOCKET_ERROR and, at lpErrno, one of the following error codes:

Note that a SAN service provider does not support the following error codes for WSPSend:

Remarks

The Windows Sockets switch calls a SAN service provider's WSPSend function to transmit data on a connected socket. A SAN service provider receives WSPSend requests from the switch, but never directly from an application.

Typically during connection setup time, the switch calls the SAN service provider's WSPRegisterMemory extension function to preregister all memory for the buffer array that is the source of the outgoing data.

The switch specifies an overlapped structure and NULL for a completion routine if the switch calls the SAN service provider's WSPSend function in an overlapped manner. The switch calls WSPSend to post one or more buffers of data for transmission over the network. If the data-transmission operation cannot complete immediately, the operation proceeds, but WSPSend 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 buffer array that the switch supplies in a WSPSend call is a pointer to an array of WSABUF structures. The SAN service provider must transmit data in buffers in the order in which those buffers appear in the buffer array. The buffer array is transient. That is, if the WSPSend call returns without completing the data-transmission operation, the SAN service provider must capture the pointer to the array of WSABUF structures before returning from WSPSend. This requirement enables the switch to build stack-based buffer arrays.

The switch does not pass send message requests to the SAN service provider that exceed the size that the SAN service provider returns in WSPGetSockOpt calls for the value of the SO_MAX_MSG_SIZE socket option.

Note that the successful completion of a WSPSend call does not indicate that the SAN service provider successfully finished delivering data in the buffer array to the destination.

Overlapped Socket I/O

If the data transmission operation completes immediately, the SAN service provider returns from WSPSend with a value of zero and specifies the number of bytes transmitted at lpNumberOfBytesSent. If the SAN service provider successfully initiated the data transmission operation and will indicate completion at a later time, the SAN service provider returns from WSPSend with a value of SOCKET_ERROR and specifies the WSA_IO_PENDING error code at lpErrno. Note that in this case, a value is not specified at lpNumberOfBytesSent. After the data transmission operation completes, the switch calls the SAN service provider's WSPGetOverlappedResult function and passes a pointer to a variable to hold data transmission information. The SAN service provider specifies the number of bytes transmitted in this pointer.

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

As mentioned previously, the switch always specifies an event in an overlapped structure and NULL for a completion routine if the switch calls the SAN service provider's WSPSend function in an overlapped manner. The SAN service provider should call the WPUCompleteOverlappedRequest function in the context of an arbitrary thread to complete the data transmission operation. 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 data transmission operation. 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 Microsoft Windows SDK documentation.

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

The SAN service provider can deliver completion notifications in any order; the SAN service provider is not required to deliver notifications in the same order that overlapped operations are completed. However, the SAN service provider transmits data from posted buffers in the same order in which the switch supplies them.

Requirements

See also

WSABUF

WSAOVERLAPPED

WSPGetOverlappedResult

WSPGetSockOpt

WSPRegisterMemory

WSPSocket

Send comments about this topic to Microsoft