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:
- 103 WSAGetOverlappedResult()
- 104 WSAGetQOSByName()
102 WSAGetLastError()Description Get the error status for the last operation which failed. #include int WSAAPI WSAGetLastError ( void ); Remarks This function returns the last network error that occurred. When a particular WinSock function indicates that an error has occurred, this function should be called to retrieve the appropriate error code. This error code may be different from the error code obtained from getsockopt() SO_ERROR—which is socket-specific--since WSAGetLastError() is for all sockets (i.e., thread-specific).. A successful function call, or a call to WSAGetLastError(), does not reset the error code. To reset the error code, use the WSASetLastError() function call with iError set to zero (NOTE: getsockopt() SO_ERROR also resets the error code to zero) This function should not be used to check for an error value on receipt of an asynchronous message. In this case the error value is passed in the lParam field of the message, and this may differ from the value returned by WSAGetLastError(). Return Value The return value indicates the error code for this thread’s last WinSock operation that failed. See Also WSASetLastError(), getsockopt() 103 WSAGetOverlappedResult()Description Returns the results of an overlapped operation on the specified socket. #include BOOL WSAAPI WSAGetOverlappedResult ( IN SOCKET s, IN LPWSAOVERLAPPED lpOverlapped, OUT LPDWORD lpcbTransfer, IN BOOL fWait, OUT LPDWORD lpdwFlags ); s Identifies the socket. This is the same socket that was specified when the overlapped operation was started by a call to WSARecv(), WSARecvFrom(), WSASend(), WSASendTo(), or WSAIoctl(). lpOverlapped Points to a WSAOVERLAPPED structure that was specified when the overlapped operation was started. lpcbTransfer Points to a 32-bit variable that receives the number of bytes that were actually transferred by a send or receive operation, or by WSAIoctl(). fWait Specifies whether the function should wait for the pending overlapped operation to complete. If TRUE, the function does not return until the operation has been completed. If FALSE and the operation is still pending, the function returns FALSE and the WSAGetLastError() function returns WSA_IO_INCOMPLETE. The fWait parameter may be set to TRUE only if the overlapped operation selected event-based completion notification. lpdwFlags Points to a 32-bit variable that will receive one or more flags that supplement the completion status. If the overlapped operation was initiated via WSARecv() or WSARecvFrom(), this parameter will contain the results value for lpFlags parameter. Remarks The results reported by the WSAGetOverlappedResult() function are those of the specified socket's last overlapped operation to which the specified WSAOVERLAPPED structure was provided, and for which the operation's results were pending. A pending operation is indicated when the function that started the operation returns SOCKET_ERROR, and the WSAGetLastError() function returns WSA_IO_PENDING. When an I/O operation is pending, the function that started the operation resets the hEvent member of the WSAOVERLAPPED structure to the nonsignaled state. Then when the pending operation has been completed, the system sets the event object to the signaled state. If the fWait parameter is TRUE, WSAGetOverlappedResult() determines whether the pending operation has been completed by waiting for the event object to be in the signaled state. A client may set fWait parameter to TRUE only if it selected event-based completion notification when the IO operation was requested. If another form of notification was selected, the usage of the hEvent member of the WSAOVERLAPPED structure is different, and setting fWait to TRUE causes unpredictable results. Return Value If WSAGetOverlappedResult() succeeds, the return value is TRUE. This means that the overlapped operation has completed successfully and that the value pointed to by lpcbTransfer has been updated. If WSAGetOverlappedResult() returns FALSE, this means that either the overlapped operation has not completed or the overlapped operation completed but with errors, or that completion status could not be determined due to errors in one or more parameters to WSAGetOverlappedResult(). On failure, the value pointed to by lpcbTransfer will not be updated. Use WSAGetLastError() to determine the cause of the failure (either of WSAGetOverlappedResult() or of the associated overlapped operation). Error Codes WSANOTINITIALISED A successful WSAStartup() must occur before using this API. WSAENETDOWN The network subsystem has failed. WSAENOTSOCK The descriptor is not a socket. WSA_INVALID_HANDLE The hEvent field of the WSAOVERLAPPED structure does not contain a valid event object handle. WSA_INVALID_PARAMETER One of the parameters is unacceptable. WSA_IO_INCOMPLETE fWait is FALSE and the I/O operation has not yet completed. WSAEFAULT One or more of the lpOverlapped, lpcbTransfer, or lpdwFlags arguments are not a valid part of the user address space. See Also WSACreateEvent(), WSAWaitForMultipleEvents(), WSARecv(), WSARecvFrom(), WSASend(), WSASendTo(), WSAConnect(), WSAAccept(), WSAIoctl(). 104 WSAGetQOSByName()Description Initializes a QOS structure based on a named template, or retrieves an enumeration of the available template names. #include BOOL WSAAPI WSAGetQOSByName( IN SOCKET s, IN OUT LPWSABUF lpQOSName, OUT LPQOS lpQOS ); s A descriptor identifying a socket. lpQOSName Specifies the QOS template name, or supplies a buffer to retrieve an enumeration of the available template names. lpQOS A pointer to the QOS structure to be filled. Remarks Applications may use this function to initialize a QOS structure to a set of known values appropriate for a particular service class or media type. These values are stored in a template which is referenced by a well-known name. The client may retrieve these values by setting the buf member of the WSABUF indicated by lpQOSName to point to a string of non-zero length specifying a template name. In this case the usage of lpQOSName is IN only, and results are returned through lpQOS. Alternatively, the client may use this function to retrieve an enumeration of available template names. The client may do this by setting the buf member of the WSABUF indicated by lpQOSName to a zero-length null-terminated string. In this case the buffer indicated by buf is over-written with a sequence of as many null-terminated template names are available up to the number of bytes available in buf as indicated by the len member of the WSABUF indicated by lpQOSName. The list of names itself is terminated by a zero-length name. When WSAGetQOSByName() is used to retrieve template names, the lpQOS parameter is ignored. Return Value If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE. 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. WSAENOTSOCK The descriptor is not a socket. WSAEFAULT The lpQOSName or lpQOS arguments are not a valid part of the user address space, or the buffer length for lpQOS is too small. WSAEINVAL The specified QOS template name is invalid. See Also WSAConnect(), WSAAccept(), getsockopt(). Download 1.64 Mb. Share with your friends:
|