WSPDuplicateSocket function

[アーティクル]
06/19/2017

WSPDuplicateSocket retrieves a WSAPROTOCOL_INFOW structure that can be used to create a new socket descriptor for a shared socket in the context of another process.

Syntax

int WSPDuplicateSocket(
  _In_  SOCKET              s,
  _In_  DWORD               dwProcessId,
  _Out_ LPWSAPROTOCOL_INFOW lpProtocolInfo,
  _Out_ LPINT               lpErrno
);

Parameters

s [in]
Descriptor that identifies a shared socket.
dwProcessId [in]
Identifier of the target process that is to use the shared socket. This identifier can be set anywhere in the range from 0 to 0xFFFFFFFF.
lpProtocolInfo [out]
Pointer to a WSAPROTOCOL_INFOW structure that receives the protocol information that can be used to create a descriptor for the shared socket.
lpErrno [out]
Pointer to a variable that receives the error code.

Return value

Returns zero if successful; otherwise, returns SOCKET_ERROR and, at lpErrno, one of the following error codes:

Return code	Description
WSAENETDOWN	Network subsystem failed.
WSAEINVAL	One of the specified parameters was invalid.
WSAEMFILE	No more socket descriptors available.
WSAENOBUFS	No buffer space is available; the socket cannot be created.
WSAENOTSOCK	Descriptor is not a socket.

Note that a SAN service provider does not support the WSAEINPROGRESS error code for WSPDuplicateSocket because the switch never issues cancel blocking calls to a SAN service provider.

Remarks

The Windows Sockets switch that resides in a source process calls the SAN service provider's WSPDuplicateSocket function to obtain a special WSAPROTOCOL_INFOW structure. The switch uses some interprocess communications (IPC) mechanism to pass the contents of the special WSAPROTOCOL_INFOW to an application that resides in a destination process. The switch in this destination process in turn calls the SAN service provider's WSPSocket function and passes the special WSAPROTOCOL_INFOW to obtain a duplicate descriptor for the shared underlying socket. Note that the switch in the destination process can only use the special WSAPROTOCOL_INFOW once.

The SAN service provider in the source process context must create a WSAPROTOCOL_INFOW structure that a call to the SAN service provider's WSPSocket function in the destination process context can use successfully. The SAN service provider's WSPDuplicateSocket function must return a WSAPROTOCOL_INFOW structure that defines characteristics of the common underlying socket. The SAN service provider can use the dwProviderReserved member of WSAPROTOCOL_INFOW to store any useful context information, including a duplicate handle.

The switch in a destination process calls the SAN service provider's WSPSocket function to create a duplicate descriptor for the shared underlying socket. The SAN service provider must call the switch's WPUCreateSocketHandle function to allocate a descriptor for the new socket. The SAN service provider must store the descriptor returned by the switch in the SAN service provider's internal data structure for the new socket. Finally, the SAN service provider returns its own descriptor for the socket to complete the WSPSocket call. The application in the destination process must supply the SAN service provider's internal descriptor for the new socket when calling the SAN service provider's functions, while the SAN service provider must supply the switch's socket descriptor in upcalls.

For more information about WPUCreateSocketHandle, see the Microsoft Windows SDK documentation.

The following table illustrates a typical scenario for establishing and using a shared socket.

Source Process	Destination Process
1) WSPSocket, WSPConnect
2) Request destination process ID
	3) Receive process ID request and respond
4) Receive process ID
5) Call WSPDuplicateSocket to get special WSAPROTOCOL_INFOW
6) Send WSAPROTOCOL_INFOW to destination
	7) Receive WSAPROTOCOL_INFOW
	8) Call WSPSocket to create descriptor for shared socket
	9) Use shared socket for data exchange
	10) Call WSPDuplicateSocket back to the original process
	11) Send WSAPROTOCOL_INFOW back to source
13) Receive WSAPROTOCOL_INFOW	12) Call WSPCloseSocket to close shared socket descriptor (but not the socket itself)
14) Call WSPSocket to transfer socket access control back and possibly create new SAN provider socket descriptor
15) Call WSPCloseSocket to close the original socket descriptor if different from the new one
16) Gracefully terminate the session
17) Call WSPCloseSocket to finally close the socket and associated connection

Note Although instances of the switch running in different processes can independently use their own descriptors that reference a shared socket for I/O data exchange, these instances of the switch cannot concurrently access the shared socket. The switch implements an access control mechanism. This mechanism ensures that after the switch calls the WSPDuplicateSocket function, the switch does not access the shared socket again until the switch calls the WSPSocket function to explicitly create again a descriptor for the shared socket. Note that a typical scenario for using a shared socket is for a controlling process to create that socket and establish connections to that socket. The controlling process then hands off that socket to other processes that perform I/O data exchange. Such a scenario typically involves the following two socket-duplication operations:

A controlling process duplicates a socket to pass the socket handle to a target process for data exchange
The target process duplicates the socket to return the socket handle to the controlling process for graceful connection closure.

Because socket descriptors are duplicated, and not the underlying shared socket, all the state associated with a socket is held in common across all duplicate descriptors. For example, if an option value on a descriptor for a shared socket is set in a WSPSetSockOpt call, that option value is subsequently visible from each duplicate descriptor using a WSPGetSockOpt call. A process can call WSPCloseSocket on a duplicate socket descriptor in order to release that descriptor. However, the underlying shared socket remains open until WSPCloseSocket is called on the last remaining descriptor.

Requirements

Target platform	Desktop
Version	Requires Windows Sockets version 2.0.
Header	Ws2spi.h (include Ws2spi.h)