WSADuplicateSocketA function (winsock2.h)
The WSADuplicateSocket function returns a WSAPROTOCOL_INFO structure that can be used to create a new socket descriptor for a shared socket. The WSADuplicateSocket function cannot be used on a QOS-enabled socket.
Syntax
int WSAAPI WSADuplicateSocketA(
[in] SOCKET s,
[in] DWORD dwProcessId,
[out] LPWSAPROTOCOL_INFOA lpProtocolInfo
);
Parameters
[in] s
Descriptor identifying the local socket.
[in] dwProcessId
Process identifier of the target process in which the duplicated socket will be used.
[out] lpProtocolInfo
Pointer to a buffer, allocated by the client, that is large enough to contain a WSAPROTOCOL_INFO structure. The service provider copies the protocol information structure contents to this buffer.
Return value
If no error occurs, WSADuplicateSocket returns zero. Otherwise, a value of SOCKET_ERROR is returned, and a specific error code can be retrieved by calling WSAGetLastError.
| Error code | Meaning |
|---|---|
| A successful WSAStartup call must occur before using this function. | |
| The network subsystem has failed. | |
| Indicates that one of the specified parameters was invalid. | |
| A blocking Windows Sockets 1.1 call is in progress, or the service provider is still processing a callback function. | |
| No more socket descriptors are available. | |
| No buffer space is available. The socket cannot be created. | |
| The descriptor is not a socket. | |
| The lpProtocolInfo parameter is not a valid part of the user address space. |
Remarks
The WSADuplicateSocket function is used to enable socket sharing between processes. A source process calls WSADuplicateSocket to obtain a special WSAPROTOCOL_INFO structure. It uses some interprocess communications (IPC) mechanism to pass the contents of this structure to a target process, which in turn uses it in a call to WSASocket to obtain a descriptor for the duplicated socket. The special WSAPROTOCOL_INFO structure can only be used once by the target process.
Sockets can be shared among threads in a given process without using the WSADuplicateSocket function because a socket descriptor is valid in all threads of a process.
One possible scenario for establishing and handing off a shared socket is illustrated in the following table.
| Source process | IPC | Destination process |
|---|---|---|
| 1) WSASocket, WSAConnect | ||
| 2) Request target process identifier | ==> | |
| 3) Receive process identifier request and respond | ||
| 4) Receive process identifier | <== | |
| 5) Call WSADuplicateSocket to get a special WSAPROTOCOL_INFO structure | ||
| 6) Send WSAPROTOCOL_INFO structure to target | ||
| ==> | 7) Receive WSAPROTOCOL_INFO structure | |
| 8) Call WSASocket to create shared socket descriptor. | ||
| 9) Use shared socket for data exchange | ||
| 10) closesocket | <== |
The descriptors that reference a shared socket can be used independently for I/O. However, the Windows Sockets interface does not implement any type of access control, so it is up to the processes involved to coordinate their operations on a shared socket. Shared sockets are typically used to having one process that is responsible for creating sockets and establishing connections, and other processes that are responsible for information exchange.
All of the state information associated with a socket is held in common across all the descriptors because the socket descriptors are duplicated and not the actual socket. For example, a setsockopt operation performed using one descriptor is subsequently visible using a getsockopt from any or all descriptors. Both the source process and the destination process should pass the same flags to their respective WSASocket function calls. If the source process uses the socket function to create the socket, the destination process must pass the WSA_FLAG_OVERLAPPED flag to its WSASocket function call. A process can call closesocket on a duplicated socket and the descriptor will become deallocated. The underlying socket, however, will remain open until closesocket is called by the last remaining descriptor.
Notification on shared sockets is subject to the usual constraints of WSAAsyncSelect and WSAEventSelect. Issuing either of these calls using any of the shared descriptors cancels any previous event registration for the socket, regardless of which descriptor was used to make that registration. Thus, a shared socket cannot deliver FD_READ events to process A and FD_WRITE events to process B. For situations when such tight coordination is required, developers would be advised to use threads instead of separate processes.
Windows 8.1 and Windows Server 2012 R2: The WSADuplicateSocketW function is supported for Windows Store apps on Windows 8.1, Windows Server 2012 R2, and later.
Note
The winsock2.h header defines WSADuplicateSocket as an alias which automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows 8.1, Windows Vista [desktop apps | UWP apps] |
| Minimum supported server | Windows Server 2003 [desktop apps | UWP apps] |
| Target Platform | Windows |
| Header | winsock2.h |
| Library | Ws2_32.lib |
| DLL | Ws2_32.dll |