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:
- 94 WSACleanup()
93 WSACancelBlockingCall()Description Cancel a blocking call which is currently in progress. WSACancelBlockingCall() is only available for WinSock 1.1 apps (that is, if at least one thread within the process negotiates version 1.0 or 1.1 at WSAStartup()). Important Note: This function is for backwards compatibility with WinSock 1.1 and is not considered part of the WinSock 2 specification. WinSock 2 applications should not use this function. #include int WSAAPI WSACancelBlockingCall ( void ); Remarks This function cancels any outstanding blocking operation for this thread. It is normally used in two situations: (1) An application is processing a message which has been received while a blocking call is in progress. In this case, WSAIsBlocking() will be true. (2) A blocking call is in progress, and WinSock has called back to the application's "blocking hook" function (as established by WSASetBlockingHook()). In each case, the original blocking call will terminate as soon as possible with the error WSAEINTR. (In (1), the termination will not take place until Windows message scheduling has caused control to revert to the blocking routine in WinSock. In (2), the blocking call will be terminated as soon as the blocking hook function completes.) In the case of a blocking connect()operation, WinSock will terminate the blocking call as soon as possible, but it may not be possible for the socket resources to be released until the connection has completed (and then been reset) or timed out. This is likely to be noticeable only if the application immediately tries to open a new socket (if no sockets are available), or to connect() to the same peer. Canceling an accept() or a select() call does not adversely impact the sockets passed to these calls. Only the particular call fails; any operation that was legal before the cancel is legal after the cancel, and the state of the socket is not affected in any way. Canceling any operation other than accept() and select() can leave the socket in an indeterminate state. If an application cancels a blocking operation on a socket, the only operation that the application can depend on being able to perform on the socket is a call to closesocket(), although other operations may work on some WinSock implementations. If an application desires maximum portability, it must be careful not to depend on performing operations after a cancel. An application may reset the connection by setting the timeout on SO_LINGER to 0 and calling closesocket(). If a cancel operation compromised the integrity of a SOCK_STREAM's data stream in any way, the WinSock provider will reset the connection and fail all future operations other than closesocket() with WSAECONNABORTED. Return Value The value returned by WSACancelBlockingCall() is 0 if the operation was successfully canceled. Otherwise the value SOCKET_ERROR is returned, and a specific error number may be retrieved by calling WSAGetLastError(). Comments Note that it is possible that the network operation completes before the WSACancelBlockingCall() is processed, for example if data is received into the user buffer at interrupt time while the application is in a blocking hook. In this case, the blocking operation will return successfully as if WSACancelBlockingCall() had never been called. Note that the WSACancelBlockingCall() still succeeds in this case; the only way to know with certainty that an operation was actually canceled is to check for a return code of WSAEINTR from the blocking call. Error Codes WSANOTINITIALISED A successful WSAStartup() must occur before using this API. WSAENETDOWN The network subsystem has failed. WSAEINVAL Indicates that there is no outstanding blocking call. WSAEOPNOTSUPP The caller is not a WinSock 1.0 or 1.1 client. 94 WSACleanup()Description Terminate use of the WinSock DLL. #include int WSAAPI WSACleanup ( void ); Remarks An application or DLL is required to perform a successful WSAStartup() call before it can use WinSock services. When it has completed the use of WinSock, the application or DLL must call WSACleanup() to deregister itself from a WinSock implementation and allow the implementation to free any resources allocated on behalf of the application or DLL. Any pending blocking or asynchronous calls issued by any thread in this process are canceled without posting any notification messages, or signaling any event objects. Any pending overlapped send and receive operations (WSASend()/WSASendTo()/WSARecv()/WSARecvFrom() with an overlapped socket) issued by any thread in this process are also canceled without setting the event object or invoking the completion routine, if specified. In this case, the pending overlapped operations fail with the error status WSA_OPERATION_ABORTED. Any sockets open when WSACleanup() is called are reset and automatically deallocated as if closesocket() was called; sockets which have been closed with closesocket() but which still have pending data to be sent may be affected--the pending data may be lost if the WinSock DLL is unloaded from memory as the application exits. To insure that all pending data is sent an application should use shutdown() to close the connection, then wait until the close completes before calling closesocket() and WSACleanup(). All resources and internal state, such as queued un-posted messages, must be deallocated so as to be available to the next user. There must be a call to WSACleanup() for every successful call to WSAStartup() made by a task. Only the final WSACleanup() for that task does the actual cleanup; the preceding calls simply decrement an internal reference count in the WinSock DLL. Return Value The return value is 0 if the operation was successful. Otherwise the value SOCKET_ERROR is returned, and a specific error number may be retrieved by calling WSAGetLastError(). Comments Attempting to call WSACleanup() from within a blocking hook and then failing to check the return code is a common programming error in WinSock 1.1 applications. If an application needs to quit while a blocking call is outstanding, the application must first cancel the blocking call with WSACancelBlockingCall() then issue the WSACleanup() call once control has been returned to the application. In a multithreaded environment, WSACleanup() terminates WinSock operations for all threads. 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. See Also closesocket(), shutdown(), WSAStartup() Download 1.64 Mb. Share with your friends:
|