If no error occurs, this function returns zero. If an error occurs, a value of SOCKET_ERROR is returned, and a specific error code can be retrieved by calling the WSAGetLastErrorfunction.

The following table shows a list of possible error codes.

This function is used to set or retrieve operating parameters associated with the socket, the transport protocol, or the communications subsystem.

If both lpOverlappedand lpCompletionRoutineare NULL, the socket in this function will be treated as a nonoverlapped socket. For a nonoverlapped socket, lpOverlappedand lpCompletionRoutineparameters are ignored, which cause the function to behave like the standard ioctlsocketfunction except that WSAIoctlcan block if socket sis in blocking mode.

If socket sis 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 an event-based notification mechanism (using WSAEventSelect).

The overlapped structures are updated with the receive results, and the associated event is signalled.

For overlapped sockets, operations that cannot be completed immediately will be initiated and completion will be indicated at a later time. In Windows Embedded CE, the completion routine will not be called. Only the event mechanism can be used. The lpcbBytesReturnedparameter is ignored.

Any IOCTL may block indefinitely, depending on the service provider's implementation. If the application cannot tolerate blocking in a WSAIoctlcall, overlapped I/O would be advised for the following IOCTLs that are especially likely to block SIO_ROUTING_INTERFACE_CHANGE or SIO_ADDRESS_LIST_CHANGE.

Some 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 ioctlsocketoperation codes while providing a convenient way to partition the operation code identifier space in as much as the dwIoControlCodeparameter is now a 32-bit entity. The dwIoControlCodeparameter is built to allow for protocol and vendor independence when adding new control codes, while retaining backward compatibility with the Winsock 1.1 and Unix control codes. The following table shows the form for the dwIoControlCodeparameter.

Iis set if the input buffer is valid for the code, as with IOC_IN.

Ois set if the output buffer is valid for the code, as with IOC_OUT. Codes with both input and output parameters set both Iand O.

Vis set if there are no parameters for the code, as with IOC_VOID.

Tis a 2-bit quantity that defines the type of IOCTL.

The following values are defined for T:

• 0– The IOCTL is a standard Unix IOCTL code, as with FIONREAD and FIONBIO.
  
  
• 1– The IOCTL is a generic Winsock IOCTL code. New IOCTL codes defined for Winsock 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 familyfield. 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 field has the same value as the code on Unix. If this is a generic Winsock IOCTL ( T == 1), then this field 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

FIONBIO enables or disables nonblocking mode on socket s. lpvInBufferpoints 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 WSAEventSelectroutines automatically set a socket to nonblocking mode. If WSAEventSelecthas been issued on a socket, then any attempt to use WSAIoctlto set the socket back to blocking mode will fail with WSAEINVAL. To set the socket back to blocking mode, an application must first disable WSAEventSelectby calling WSAEventSelectwith the lNetworkEventsparameter equal to zero.

FIONREAD

FIONREAD determines the amount of data that can be read atomically from socket s. lpvOutBufferpoints at an unsigned long in which WSAIoctlstores the result. If sis 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 typically the same as the total amount of data queued on the socket (because the data stream is byte-oriented, this is not guaranteed). If socket sis message-oriented (for example, type SOCK_DGRAM), FIONREAD returns the size of the first datagram (message) queued on the socket.

The Windows Embedded CE service provider does not support the SIO_FLUSH command. If an overlapped operation completes immediately, WSAIoctlreturns a value of zero and the lpcbBytesReturnedparameter 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, lpcbBytesReturnedis not updated. When the overlapped operation completes, the amount of data in the output buffer is indicated either through the cbTransferredparameter in the completion routine (if specified) or through the l pcbTransferparameter in WSAGetOverlappedResult.

When called with an overlapped socket, the lpOverlappedparameter must be valid for the duration of the overlapped operation. The lpOverlappedparameter contains the address of a WSAOVERLAPPEDstructure.

If the lpCompletionRoutineparameter is NULL, the hEventparameter of lpOverlappedis signaled when the overlapped operation completes if it contains a valid event object handle. An application can use WSAGetOverlappedResultto wait or poll on the event object.

If lpCompletionRoutineis not NULL, the hEventparameter is ignored and can be used by the application to pass context information to the completion routine. A caller that passes a non-NULL lpCompletionRoutineand later calls WSAGetOverlappedResultfor the same overlapped I/O request may not set the fWaitparameter for that invocation of WSAGetOverlappedResultto TRUE. In this case, the usage of the hEventparameter is undefined and attempting to wait on the hEventparameter would produce unpredictable results.

The prototype of the callback function is as follows:

	Copy Code
dwError cbTransferred lpOverlapped dwFlags

CompletionRoutineis a placeholder for an application-defined or library-defined function. The dwErrorparameter specifies the completion status for the overlapped operation as indicated by lpOverlapped. The cbTransferredparameter specifies the number of bytes returned. Currently, there are no flag values defined and dwFlagswill be zero. The CompletionRoutinefunction 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.

The IOCTL codes with T == 0are a subset of the IOCTL codes used in Berkeley sockets. In particular, there is no command that is equivalent to FIOASYNC.

The WSAIoctland ioctlsocketfunctions control the mode of a socket. WSAIoctlrequires Winsock 2.2 and allows overlapped or asynchronous operation. The ioctlsocketfunction can be used with Winsock 1.1 or later. The following Bluetooth-specific IOCTL codes are available:

• SIO_RFCOMM_COMM_PARAMETERS sets or queries modem attributes. The structures used and calling semantics are the same as TDI_ACTION RFCOMM_COMM_PARAMETERS.
  
  
• SIO_RFCOMM_WAIT_MODEM_STATUS gets the current status of the modem. The semantics are the same as TDI_ACTION RFCOMM_MODEM_STATUS.