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:
| Return code | Description |
|---|---|
| WSAENETDOWN | Network subsystem failed. |
| WSAEFAULT | The lpBuffers parameter is not totally contained in a valid part of the user address space. |
| WSAENOBUFS | SAN service provider reports a buffer deadlock. |
| WSAENOTCONN | Socket is not connected. |
| WSAENOTSOCK | Descriptor is not a socket. |
| WSAESHUTDOWN | Socket has been shut down; it is not possible for the WSPSend function to send data on a socket after the socket has been shut down. |
| WSAEINVAL | The switch either did not create the socket with the overlapped flag or previously call the WSPBind function to bind the socket. |
| WSAECONNABORTED | The connection to the remote peer was terminated due to a time-out or other failure. |
| WSAECONNRESET | The connection was reset by the remote peer. |
| WSA_IO_PENDING | The SAN service provider successfully initiated an overlapped send operation and will indicate completion at a later time. |
| WSA_OPERATION_ABORTED | The overlapped operation was canceled, because the socket was closed. |
Note that a SAN service provider does not support the following error codes for WSPSend:
| Return code | Description |
|---|---|
| WSAEACCES | Broadcast addresses are not supported. |
| WSAEINPROGRESS | The Windows Sockets switch never issues cancel blocking calls to a SAN service provider. |
| WSAENETRESET | Detecting a broken connection from the remote host resetting is not supported. |
| WSAEOPNOTSUPP | The socket is the appropriate type. |
| WSAEWOULDBLOCK | The Windows Sockets switch uses overlapped sockets. |
| WSAEMSGSIZE | The current version of Windows Sockets Direct does not support SAN service providers handling sockets that send datagrams. |
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
Target platform |
Desktop |
Version |
Requires Windows Sockets version 2.0. |
Header |
Ws2spi.h (include Ws2spi.h) |
See also