WSPSend

IT

WSPSend function

            This topic has not yet been rated – Rate this topic

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.