Platform SDK: Windows Sockets
WSAIoctl
The Windows Sockets WSAIoctl function controls the mode of a socket.int WSAIoctl(
SOCKET s,
DWORD dwIoControlCode,
LPVOID lpvInBuffer,
DWORD cbInBuffer,
LPVOID lpvOutBuffer,
DWORD cbOutBuffer,
LPDWORD lpcbBytesReturned,
LPWSAOVERLAPPED lpOverlapped,
LPWSAOVERLAPPED_COMPLETION_ROUTINE lpCompletionRoutine
);
Parameters
s
[in] Descriptor identifying a socket.
dwIoControlCode
[in] Control code of operation to perform.
lpvInBuffer
[in] Pointer to the input buffer.
cbInBuffer
[in] Size of the input buffer.
lpvOutBuffer
[out] Pointer to the output buffer.
cbOutBuffer
[in] Size of the output buffer.
lpcbBytesReturned
[out] Pointer to actual number of bytes of output.
lpOverlapped
[in] Pointer to a WSAOVERLAPPED structure (ignored for nonoverlapped sockets).
lpCompletionRoutine
[in] Pointer to the completion routine called when the operation has been completed (ignored for nonoverlapped sockets).
Return Values
Upon successful completion, the WSAIoctl returns zero. Otherwise, a value of SOCKET_ERROR is returned, and a specific error code can be retrieved by calling WSAGetLastError.Error code Meaning
WSAENETDOWN The network subsystem has failed.
WSAEFAULT The lpvInBuffer, lpvOutBuffer lpcbBytesReturned, lpOverlapped, or lpCompletionRoutine argument is not totally contained in a valid part of the user address space, or the cbInBuffer or cbOutBuffer argument is too small.
WSAEINVAL dwIoControlCode is not a valid command, or a supplied input parameter is not acceptable, or the command is not applicable to the type of socket supplied.
WSAEINPROGRESS The function is invoked when a callback is in progress.
WSAENOTSOCK The descriptor s is not a socket.
WSAEOPNOTSUPP The specified ioctl command cannot be realized. (For example, the FLOWSPEC structures specified in SIO_SET_QOS cannot be satisfied.)
WSA_IO_PENDING An overlapped operation was successfully initiated and completion will be indicated at a later time.
WSAEWOULDBLOCK The socket is ed as nonblocking and the requested operation would block.
Res
The WSAIoctl function is used to set or retrieve operating parameters associated with the socket, the transport protocol, or the communications subsystem.If both lpOverlapped and lpCompletionRoutine are NULL, the socket in this function will be treated as a nonoverlapped socket. For a nonoverlapped socket, lpOverlapped and lpCompletionRoutine parameters are ignored, which cause the function to behave like the standard ioctlsocket function except that WSAIoctl can block if socket s is in blocking mode. If socket s is in nonblocking mode, this function can return WSAEWOULDBLOCK when the specified operation cannot be finished immediately. In this case, the application may change the socket to blocking mode and reissue the request or wait for the corresponding network event (such as FD_ROUTING_INTERFACE_CHANGE or FD_ADDRESS_LIST_CHANGE in the case of SIO_ROUTING_INTERFACE_CHANGE or SIO_ADDRESS_LIST_CHANGE) using a Windows message (using WSAAsyncSelect) -based or event (using WSAEventSelect)-based notification mechanism.For overlapped sockets, operations that cannot be completed immediately will be initiated, and completion will be indicated at a later time. The final completion status is retrieved through WSAGetOverlappedResult. The lpcbBytesReturned parameter is ignored.Any IOCTL may block indefinitely, depending on the service provider's implementation. If the application cannot tolerate blocking in a WSAIoctl call, overlapped I/O would be advised for IOCTLs that are especially likely to block including: SIO_FINDROUTE
SIO_FLUSH
SIO_GET_QOS
SIO_GET_GROUP_QOS
SIO_SET_QOS
SIO_SET_GROUP_QOS
SIO_ROUTING_INTERFACE_CHANGE
SIO_ADDRESS_LIST_CHANGESome protocol-specific IOCTLs may also be especially likely to block. Check the relevant protocol-specific annex for any available information.It is possible to adopt an encoding scheme that preserves the currently defined ioctlsocket opcodes while providing a convenient way to partition the opcode identifier space in as much as the dwIoControlCode parameter is now a 32-bit entity. The dwIoControlCode parameter is built to allow for protocol and vendor independence when adding new control codes while retaining backward compatibility with the Windows Sockets 1.1 and Unix control codes. The dwIoControlCode parameter has the following form.I O V T Vendor/address family code
3 3 2 2 2 2 2 2 2 2 2 2 1 1 1 1 1 1 1 1 1 1
1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0
I is set if the input buffer is valid for the code, as with IOC_IN.O is set if the output buffer is valid for the code, as with IOC_OUT. Codes with both input and output parameters set both I and O.V is set if there are no parameters for the code, as with IOC_VOID.T is a 2-bit quantity that defines the type of IOCTL. The following values are defined:0 The IOCTL is a standard Unix IOCTL code, as with FIONREAD and FIONBIO.1 The IOCTL is a generic Windows Sockets 2 IOCTL code. New IOCTL codes defined for Windows Sockets 2 will have T == 1.2 The IOCTL applies only to a specific address family.3 The IOCTL applies only to a specific vendor's provider. This type allows companies to be assigned a vendor number that appears in the Vendor/Address family parameter. Then, the vendor can define new IOCTLs specific to that vendor without having to register the IOCTL with a clearinghouse, thereby providing vendor flexibility and privacy.Vendor/Address family An 11-bit quantity that defines the vendor who owns the code (if T == 3) or that contains the address family to which the code applies (if T == 2). If this is a Unix IOCTL code (T == 0) then this parameter has the same value as the code on Unix. If this is a generic Windows Sockets 2 IOCTL (T == 1) then this parameter can be used as an extension of the code parameter to provide additional code values.Code The 16-bit quantity that contains the specific IOCTL code for the operation.The following Unix IOCTL codes (commands) are supported. FIONBIO
Enable or disable nonblocking mode on socket s. lpvInBuffer points at an unsigned long, which is nonzero if nonblocking mode is to be enabled and zero if it is to be disabled. When a socket is created, it operates in blocking mode (that is, nonblocking mode is disabled). This is consistent with BSD sockets.
The WSAAsyncSelect or WSAEventSelect routine automatically sets a socket to nonblocking mode. If WSAAsyncSelect or WSAEventSelect has been issued on a socket, then any attempt to use WSAIoctl to set the socket back to blocking mode will fail with WSAEINVAL. To set the socket back to blocking mode, an application must first disable WSAAsyncSelect by calling WSAAsyncSelect with the lEvent parameter equal to zero, or disable WSAEventSelect by calling WSAEventSelect with the lNetworkEvents parameter equal to zero. FIONREAD
Determine the amount of data that can be read atomically from socket s. lpvOutBuffer points at an unsigned long in which WSAIoctl stores the result. If s is stream oriented (for example, type SOCK_STREAM), FIONREAD returns the total amount of data that can be read in a single receive operation; this is normally the same as the total amount of data queued on the socket (since data stream is byte-oriented, this is not guaranteed). If s is message oriented (for example, type SOCK_DGRAM), FIONREAD returns the size of the first datagram (message) queued on the socket.
SIOCATMARK
Determine whether or not all OOB data has been read. This applies only to a socket of stream-style (for example, type SOCK_STREAM) that has been configured for inline reception of any OOB data (SO_OOBINLINE). If no OOB data is waiting to be read, the operation returns TRUE. Otherwise, it returns FALSE, and the next receive operation performed on the socket will retrieve some or all of the data preceding the ; the application should use the SIOCATMARK operation to determine whether any remains. If there is any normal data preceding the urgent (out of band) data, it will be received in order. (Note that recv operations will never mix OOB and normal data in the same call.) lpvOutBuffer points at a BOOL in which WSAIoctl stores the result.
The following Windows Sockets 2 commands are supported. SIO_ASSOCIATE_HANDLE (opcode setting: I, T==1)
Associate this socket with the specified handle of a companion interface. The input buffer contains the integer value corresponding to the manifest constant for the companion interface (for example, TH_NETDEV and TH_TAPI.), followed by a value that is a handle of the specified companion interface, along with any other required information. Refer to the appropriate section in the Windows Sockets 2 Protocol-Specific Annex (a separate document) for details specific to a particular companion interface. The total size is reflected in the input buffer length. No output buffer is required. The WSAENOPROTOOPT error code is indicated for service providers that do not support this ioctl. The handle associated by this ioctl can be retrieved using SIO_TRANSLATE_HANDLE.
A companion interface might be used, for example, if a particular provider provides (1) a great deal of additional controls over the behavior of a socket and (2) the controls are provider-specific enough that they do not map to existing Windows Socket functions or ones likely to be defined in the future. It is recommend that the Component Object Model (COM) be used instead of this ioctl to discover and track other interfaces that might be supported by a socket. This ioctl is present for (reverse) compatibility with systems where COM is not available or cannot be used for some other reason. SIO_ENABLE_CIRCULAR_QUEUEING (opcode setting: V, T==1)
Indicates to the underlying message-oriented service provider that a newly arrived message should never be dropped because of a buffer queue overflow. Instead, the oldest message in the queue should be eliminated in order to accommodate the newly arrived message. No input and output buffers are required. Note that this ioctl is only valid for sockets associated with unreliable, message-oriented protocols. The WSAENOPROTOOPT error code is indicated for service providers that do not support this ioctl.
SIO_FIND_ROUTE (opcode setting: O, T==1)
When issued, this ioctl requests that the route to the remote address specified as a SOCKADDR in the input buffer be discovered. If the address already exists in the local cache, its entry is invalidated. In the case of Novell's IPX, this call initiates an IPX GetLocalTarget (GLT), which queries the network for the given remote address.
SIO_FLUSH (opcode setting: V, T==1)
Discards current contents of the sending queue associated with this socket. No input and output buffers are required. The WSAENOPROTOOPT error code is indicated for service providers that do not support this ioctl.
SIO_GET_BROADCAST_ADDRESS (opcode setting: O, T==1)
This ioctl fills the output buffer with a SOCKADDR structure containing a suitable broadcast address for use with sendto/WSASendTo.
SIO_GET_EXTENSION_FUNCTION_POINTER (opcode setting: O, I, T==1)
Retrieve a pointer to the specified extension function supported by the associated service provider. The input buffer contains a globally unique identifier (GUID) whose value identifies the extension function in question. The pointer to the desired function is returned in the output buffer. Extension function identifiers are established by service provider vendors and should be included in vendor documentation that describes extension function capabilities and semantics.
SIO_GET_QOS (opcode setting: O, T==1)
Reserved for future use with sockets. Retrieve the QOS structure associated with the socket. The input buffer is optional. Some protocols (for example, RSVP) allow the input buffer to be used to qualify a quality of service request. The QOS structure will be copied into the output buffer. The output buffer must be sized large enough to be able to contain the full QOS structure. The WSAENOPROTOOPT error code is indicated for service providers that do not support quality of service.
A sender may not call SIO_GET_QOS until the socket is connected. A receiver may call SEO_GET_QOS soon as it is bound. SIO_GET_GROUP_QOS (opcode setting: O, I, T==1)
Reserved.
SIO_MULTIPOINT_LOOPBACK (opcode setting: I, T==1)
Controls whether data sent in a multipoint session will also be received by the same socket on the local host. A value of TRUE causes loopback reception to occur while a value of FALSE prohibits this. By default, loopback is enabled.
SIO_MULTICAST_SCOPE (opcode setting: I, T==1)
Specifies the scope over which multicast transmissions will occur. Scope is defined as the number of routed network segments to be covered. A scope of zero would indicate that the multicast transmission would not be placed on the wire but could be disseminated across sockets within the local host. A scope value of one (the default) indicates that the transmission will be placed on the wire, but will not cross any routers. Higher scope values determine the number of routers that can be crossed. Note that this corresponds to the time-to-live (TTL) parameter in IP multicasting. By default, scope is 1.
SIO_RCVALL
Enables a socket to receive all IP packets on the network. The socket handle passed to the WSAIoctl function must be of AF_INET address family, SOCK_RAW socket type, and IPPROTO_IP protocol. The socket also must be bound to an explicit local interface, which means that you cannot bind to INADDR_ANY.
Once the socket is bound and the ioctl set, calls to the WSARecv or recv functions return IP datagrams passing through the given interface. Note that you must supply a sufficiently large buffer. Setting this ioctl requires Administrator privilege on the local machine. SIO_RCVALL is available in Windows 2000 and later versions of Windows. SIO_RCVALL_MCAST
Enables a socket to receive all multicast IP traffic on the network (that is, all IP packets destined for IP addresses in the range of 224.0.0.0 to 239.255.255.255). The socket handle passed to the WSAIoctl function must be of AF_INET address family, SOCK_RAW socket type, and IPPROTO_UDP protocol. The socket also must be bound to an explicit local interface, which means that you cannot bind to INADDR_ANY.
Once the socket is bound and the ioctl set, calls to the WSARecv or recv functions return multicast IP datagrams passing through the given interface. Note that you must supply a sufficiently large buffer. Setting this ioctl requires Administrator privilege on the local machine. SIO_RCVALL_MCAST is available only in Windows 2000 and later versions of Windows. SIO_RCVALL_IGMPMCAST
Enables a socket to receive all IGMP multicast IP traffic on the network, without receiving other multicast IP traffic. The socket handle passed to the WSAIoctl function must be of AF_INET address family, SOCK_RAW socket type, and IPPROTO_IGMP protocol. The socket also must be bound to an explicit local interface, which means that you cannot bind to INADDR_ANY.
Once the socket is bound and the ioctl set, calls to the WSARecv or recv functions return multicast IP datagrams passing through the given interface. Note that you must supply a sufficiently large buffer. Setting this ioctl requires Administrator privilege on the local machine. SIO_RCVALL_IGMPMCAST is available only in Windows 2000 and later versions of Windows. SIO_KEEPALIVE_VALS
Enables the per-connection setting of keep-alive option, keepalive time, and keepalive interval. The argument structure for SIO_KEEPALIVE_VALS is as follows:
/* Argument structure for SIO_KEEPALIVE_VALS */
struct tcp_keepalive {
u_long onoff;
u_long keepalivetime;
u_long keepaliveinterval;
};
SIO_SET_QOS (opcode setting: I, T==1)
Associate the supplied QOS structure with the socket. No output buffer is required, the QOS structure will be obtained from the input buffer. The WSAENOPROTOOPT error code is indicated for service providers that do not support quality of service.
SIO_SET_GROUP_QOS (opcode setting: I, T==1)
Reserved.
SIO_TRANSLATE_HANDLE (opcode setting: I, O, T==1)
To obtain a corresponding handle for socket s that is valid in the context of a companion interface (for example, TH_NETDEV and TH_TAPI). A manifest constant identifying the companion interface along with any other needed parameters are specified in the input buffer. The corresponding handle will be available in the output buffer upon completion of this function. Refer to the appropriate section in Windows Sockets 2 Protocol-Specific Annex for details specific to a particular companion interface. The WSAENOPROTOOPT error code is indicated for service providers that do not support this ioctl for the specified companion interface. This ioctl retrieves the handle associated using SIO_TRANSLATE_HANDLE.
It is recommend that the Component Object Model (COM) be used instead of this ioctl to discover and track other interfaces that might be supported by a socket. This ioctl is present for backward compatibility with systems where COM is not available or cannot be used for some other reason. SIO_ROUTING_INTERFACE_QUERY (opcode setting: I, O, T==1)
To obtain the address of the local interface (represented as SOCKADDR structure) which should be used to send to the remote address specified in the input buffer (as SOCKADDR). Remote multicast addresses may be submitted in the input buffer to get the address of the preferred interface for multicast transmission. In any case, the interface address returned may be used by the application in a subsequent bind() request.
Note that routes are subject to change. Therefore, applications cannot rely on the information returned by SIO_ROUTING_INTERFACE_QUERY to be persistent. Applications may register for routing change notifications through the SIO_ROUTING_INTERFACE_CHANGE IOCTL which provides for notification through either overlapped I/O or FD_ROUTING_INTERFACE_CHANGE event. The following sequence of actions can be used to guarantee that the application always has current routing interface information for a given destination: Issue SIO_ROUTING_INTERFACE_CHANGE IOCTL
Issue SIO_ROUTING_INTERFACE_QUERY IOCTL
Whenever SIO_ROUTING_INTERFACE_CHANGE IOCTL notifies the application of routing change (either through overlapped I/O or by signaling FD_ROUTING_INTERFACE_CHANGE event), the whole sequence of actions should be repeated.
If output buffer is not large enough to contain the interface address, SOCKET_ERROR is returned as the result of this IOCTL and WSAGetLastError returns WSAEFAULT. The required size of the output buffer will be returned in lpcbBytesReturned in this case. Note the WSAEFAULT error code is also returned if the lpvInBuffer, lpvOutBuffer or lpcbBytesReturned parameter is not totally contained in a valid part of the user address space. If the destination address specified in the input buffer cannot be reached through any of the available interfaces, SOCKET_ERROR is returned as the result of this IOCTL and WSAGetLastError returns WSAENETUNREACH or even WSAENETDOWN if all of the network connectivity is lost. SIO_ROUTING_INTERFACE_CHANGE (opcode setting: I, T==1)
To receive notification of the interface change that should be used to reach the remote address in the input buffer (specified as a SOCKADDR structure). No output information will be provided upon completion of this IOCTL; the completion merely indicates that routing interface for a given destination has changed and should be queried again through SIO_ROUTING_INTERFACE_QUERY.
It is assumed (although not required) that the application uses overlapped I/O to be notified of routing interface change through completion of SIO_ROUTING_INTERFACE_CHANGE request. Alternatively, if the SIO_ROUTING_INTERFACE_CHANGE IOCTL is issued on nonblocking socket and without overlapped parameters (lpOverlapped / CompletionRoutine are set NULL), it will complete immediately with error WSAEWOULDBLOCK, and the application can then wait for routing change events through call to WSAEventSelect or WSAAsyncSelect with FD_ROUTING_INTERFACE_CHANGE bit set in the network event bitmask. It is recognized that routing information remains stable in most cases so that requiring the application to keep multiple outstanding IOCTLs to get notifications about all destinations that it is interested in as well as having service provider to keep track of all them will unnecessarily tie significant system resources. This situation can be avoided by extending the meaning of the input parameters and relaxing the service provider requirements as follows: The application can specify a protocol family specific wildcard address (same as one used in bind call when requesting to bind to any available address) to request notifications of any routing changes. This allows the application to keep only one outstanding SIO_ROUTING_INTERFACE_CHANGE for all the sockets/destinations it has and then use SIO_ROUTING_INTERFACE_QUERY to get the actual routing information.
Service provider has the option to ignore the information supplied by the application in the input buffer of the SIO_ROUTING_INTERFACE_CHANGE (as though the application specified a wildcard address) and complete the SIO_ROUTING_INTERFACE_CHANGE IOCTL or signal FD_ROUTING_INTERFACE_CHANGE event in the event of any routing information change (not just the route to the destination specified in the input buffer).
SIO_ADDRESS_LIST_QUERY (opcode setting: I, O, T==1)
To obtain a list of local transport addresses of the socket's protocol family to which the application can bind. The list returned in the output buffer using the following format:
typedef struct _SOCKET_ADDRESS_LIST {
INT iAddressCount;
SOCKET_ADDRESS Address[1];
} SOCKET_ADDRESS_LIST, FAR * LPSOCKET_ADDRESS_LIST;
Members:
iAddressCount - number of address structures in the list;
Address - array of protocol family specific address structures.
Note In Win32 Plug-n-Play environments addresses can be added and removed dynamically. Therefore, applications cannot rely on the information returned by SIO_ADDRESS_LIST_QUERY to be persistent. Applications may register for address change notifications through the SIO_ADDRESS_LIST_CHANGE IOCTL which provides for notification through either overlapped I/O or FD_ADDRESS_LIST_CHANGE event. The following sequence of actions can be used to guarantee that the application always has current address list information: Issue SIO_ADDRESS_LIST_CHANGE IOCTL
Issue SIO_ADDRESS_LIST_QUERY IOCTL
Whenever SIO_ADDRESS_LIST_CHANGE IOCTL notifies the application of address list change (either through overlapped I/O or by signaling FD_ADDRESS_LIST_CHANGE event), the whole sequence of actions should be repeated.
If output buffer is not large enough to contain the address list, SOCKET_ERROR is returned as the result of this IOCTL and WSAGetLastError returns WSAEFAULT. The required size of the output buffer will be returned in lpcbBytesReturned in this case. Note the WSAEFAULT error code is also returned if the lpvInBuffer, lpvOutBuffer,or lpcbBytesReturned parameter is not totally contained in a valid part of the user address space. SIO_ADDRESS_LIST_CHANGE (opcode setting: T==1)
To receive notification of changes in the list of local transport addresses of the socket's protocol family to which the application can bind. No output information will be provided upon completion of this IOCTL; the completion merely indicates that list of available local address has changed and should be queried again through SIO_ADDRESS_LIST_QUERY.
It is assumed (although not required) that the application uses overlapped I/O to be notified of change by completion of SIO_ADDRESS_LIST_CHANGE request. Alternatively, if the SIO_ADDRESS_LIST_CHANGE IOCTL is issued on a nonblocking socket and without overlapped parameters (lpOverlapped / lpCompletionRoutine are set to NULL), it will complete immediately with error WSAEWOULDBLOCK. The application can then wait for address list change events through a call to WSAEventSelect or WSAAsyncSelect with FD_ADDRESS_LIST_CHANGE bit set in the network event bitmask. If an overlapped operation completes immediately, WSAIoctl returns a value of zero and the lpcbBytesReturned parameter is updated with the number of bytes in the output buffer. If the overlapped operation is successfully initiated and will complete later, this function returns SOCKET_ERROR and indicates error code WSA_IO_PENDING. In this case, lpcbBytesReturned is not updated. When the overlapped operation completes the amount of data in the output buffer is indicated either through the cbTransferred parameter in the completion routine (if specified), or through the lpcbTransfer parameter in WSAGetOverlappedResult.When called with an overlapped socket, the lpOverlapped parameter must be valid for the duration of the overlapped operation. The lpOverlapped parameter contains the address of a WSAOVERLAPPED structure. If the lpCompletionRoutine parameter is NULL, the hEvent parameter of lpOverlapped is signaled when the overlapped operation completes if it contains a valid event object handle. An application can use WSAWaitForMultipleEvents or WSAGetOverlappedResult to wait or poll on the event object.If lpCompletionRoutine is not NULL, the hEvent parameter is ignored and can be used by the application to pass context information to the completion routine. A caller that passes a non-NULL lpCompletionRoutine and later calls WSAGetOverlappedResult for the same overlapped I/O request may not set the fWait parameter for that invocation of WSAGetOverlappedResult to TRUE. In this case, the usage of the hEvent parameter is undefined, and attempting to wait on the hEvent parameter would produce unpredictable results.The prototype of the completion routine is as follows:void CALLBACK CompletionRoutine(
IN DWORD dwError,
IN DWORD cbTransferred,
IN LPWSAOVERLAPPED lpOverlapped,
IN DWORD dwFlags
);
This CompletionRoutine is a placeholder for an application-defined or library-defined function. The dwError parameter specifies the completion status for the overlapped operation as indicated by lpOverlapped. The cbTransferred parameter specifies the number of bytes returned. Currently, there are no flag values defined and dwFlags will be zero. The CompletionRoutine function does not return a value.Returning from this function allows invocation of another pending completion routine for this socket. The completion routines can be called in any order, not necessarily in the same order the overlapped operations are completed.Compatibility
The IOCTL codes with T == 0 are a subset of the IOCTL codes used in Berkeley sockets. In particular, there is no command that is equivalent to FIOASYNC.Requirements
Version: Requires Windows Sockets 2.0.
Header: Declared in Winsock2.h.
Library: Use Ws2_32.lib.See Also
Windows Sockets Programming Considerations Overview, Microsoft Windows-Specific Extension Functions, getsockopt, ioctlsocket, setsockopt, socket, WSASocketBuilt on Friday, May 12, 2000Requirements
Version: Requires Windows Sockets 2.0.
Header: Declared in Winsock2.h.
Library: Use Ws2_32.lib.
See Also
Windows Sockets Programming Considerations Overview, Microsoft Windows-Specific Extension Functions, getsockopt, ioctlsocket, setsockopt, socket, WSASocket
============
希望这个对你有帮助：）
解决方案 »
免费领取超大流量手机卡，每月29元包185G流量+100分钟通话, 中国电信官方发货