Windows* Sockets 2 Application Programming Interface An Interface for Transparent Network Programming Under Microsoft Windowstm revision 2 August 7, 1997
Download 1.64 Mb.
|
- Navigate this page:
- 98 WSADuplicateSocket()
97 WSACreateEvent()Description Creates a new event object. #include WSAEVENT WSAAPI WSACreateEvent( void ); Remarks The event object created by this function is manual reset, with an initial state of nonsignaled. WinSock 2 event objects are system objects in Win32 environments. Therefore, if a Win32 application desires auto reset events, it may call the native CreateEvent() Win32 API directly. The scope of an event object is limited to the process in which it is created. Return Value If the function succeeds, the return value is the handle of the event object. If the function fails, the return value is WSA_INVALID_EVENT. To get extended error information, call WSAGetLastError(). Error Codes WSANOTINITIALISED A successful WSAStartup() must occur before using this API. WSAENETDOWN The network subsystem has failed. WSAEINPROGRESS A blocking WinSock 1.1 call is in progress, or the service provider is still processing a callback function. WSA_NOT_ENOUGH_MEMORY Not enough free memory available to create the event object. See Also WSACloseEvent(), WSAEnumNetworkEvents(), WSAEventSelect(), WSAGetOverlappedResult(), WSARecv(), WSARecvFrom(), WSAResetEvent(), WSASend(), WSASendTo(), WSASetEvent(), WSAWaitForMultipleEvents(). 98 WSADuplicateSocket()Description Return a WSAPROTOCOL_INFO structure that can be used to create a new socket descriptor for a shared socket. #include int WSAAPI WSADuplicateSocket ( IN SOCKET s, IN DWORD dwProcessId, OUT LPWSAPROTOCOL_INFO lpProtocolInfo ); s Specifies the local socket descriptor. dwProcessId Specifies the ID of the target process for which the shared socket will be used. lpProtocolInfo A pointer to a buffer allocated by the client that is large enough to contain a WSAPROTOCOL_INFO struct. The service provider copies the protocol info struct contents to this buffer. Remarks This 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. Note that the special WSAPROTOCOL_INFO structure may only be used once by the target process. Note that sockets may be shared amongst threads in a given process without using the WSADuplicateSocket() function, since a socket descriptor is valid in all of a process’ threads. One possible scenario for establishing and using a shared socket in a handoff mode is illustrated below:
Return Value If no error occurs, WSADuplicateSocket() returns zero. Otherwise, a value of SOCKET_ERROR is returned, and a specific error code may be retrieved by calling WSAGetLastError(). Comments The descriptors that reference a shared socket may be used independently as far as I/O is concerned. However, the WinSock 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. A typical use for shared sockets is to have one process that is responsible for creating sockets and establishing connections, hand off sockets to other processes which are responsible for information exchange. Since what is duplicated are the socket descriptors and not the underlying socket, all of the state associated with a socket is held in common across all the descriptors. For example a setsockopt() operation performed using one descriptor is subsequently visible using a getsockopt() from any or all descriptors. A process may 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, for example, 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, it is suggested that developers use threads instead of separate processes. Error Codes WSANOTINITIALISED A successful WSAStartup() must occur before using this API. WSAENETDOWN The network subsystem has failed. WSAEINVAL Indicates that one of the specified parameters was invalid. WSAEINPROGRESS A blocking WinSock 1.1 call is in progress, or the service provider is still processing a callback function. WSAEMFILE No more socket descriptors are available. WSAENOBUFS No buffer space is available. The socket cannot be created. WSAENOTSOCK The descriptor is not a socket. WSAEFAULT The lpProtocolInfo argument is not a valid part of the user address space. See Also WSASocket() Download 1.64 Mb. Share with your friends:
|