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
|
|
| );
|
|
| 3
| 3
| 2
| 2 2
| 2 2 2 2 2 2 2 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
| O
| V
| T
| Vendor/Address Family
| Code
|
The ioctl is a standard Unix ioctl code, as with FIONREAD and FIONBIO.
The ioctl is a generic Windows Sockets 2 ioctl code. New ioctl codes defined
for Windows Sockets 2 will have T == 1.
The ioctl applies only to a specific address family.
The ioctl applies only to a specific vendor's provider. This type allows
companies to be assigned a vendor number which appears in the
Vendor/Address family field, and 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 which defines the vendor who owns the code (if T == 3) or which 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
Windows Sockets 2 ioctl (T == 1) then this field can be used as an extension of the "code" field to provide
additional code values.
Code The specific ioctl code for the operation.
The following Unix commands are supported:
Parameters
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 which 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 which may be read in a single receive operation; this is
normally the same as the total amount of data queued on the socket. 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 out-of-band data has been read. This applies only
to a socket of stream style (for example, type SOCK_STREAM) which has been
configured for in-line reception of any out-of-band data (SO_OOBINLINE). If no
out-of-band 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 "mark"; 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 receive operations will never mix out-of-band 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:
Parameters
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 which 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 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 which do not support this
ioctl.
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
which 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 which 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)
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 QOS 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
which do not support QOS.
SIO_GET_GROUP_QOS (opcode setting: O, I, T==1)
Retrieve the QOS structure associated with the socket group to which this
socket belongs. The input buffer is optional. Some protocols (for example, RSVP)
allow the input buffer to be used to qualify a QOS request. The QOS structure
will be copied into the output buffer. If this socket does not belong to an
appropriate socket group, the SendingFlowspec and ReceivingFlowspec fields of the returned QOS structure are set to NULL. The WSAENOPROTOOPT error
code is indicated for service providers which do not support QOS.
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.
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 may be crossed. Note that this corresponds to the time-to-live
(TTL) parameter in IP multicasting.
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 which do not support QOS.
SIO_SET_GROUP_QOS (opcode setting: I, T==1)
Establish the supplied QOS structure with the socket group to which this
socket belongs. No output buffer is required, the QOS structure will be obtained
from the input buffer. The WSAENOPROTOOPT error code is indicated for service
providers which do not support QOS, or if the socket descriptor specified is not
the creator of the associated socket group.
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 the Windows Sockets 2 Protocol-Specific Annex for details specific to a particular companion interface. The WSAENOPROTOOPT
error code is indicated for service providers which do not support this ioctl
for the specified companion interface.
If an overlapped operation completes immediately, this function 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
WSAOVERLAPPED structure has the following form:
typedef struct _WSAOVERLAPPED {
DWORD Internal; // reserved
DWORD InternalHigh; // reserved
DWORD Offset; // reserved
DWORD OffsetHigh; // reserved
WSAEVENT hEvent;
} WSAOVERLAPPED, FAR * LPWSAOVERLAPPED;
If the lpCompletionRoutine parameter is NULL, the hEvent field 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 field is ignored and can be used by the application to pass context
information to the completion routine.
The prototype of the completion routine is as follows:
- oid CALLBACK CompletionRoutine(
IN DWORD
IN DWORD cbTransferred,
IN LPWSAOVERLAPPED lpOverlapped,
IN DWORD dwFlags
); CompletionRoutine is a placeholder for an application-defined or library-defined function. dwError specifies the completion status for the overlapped operation as indicated by lpOverlapped. cbTransferred specifies the number of bytes returned. Currently there are no flag values defined and dwFlags will be zero. This function does not return a value. Returning from this function allows invocation of another pending completion routine for this socket. The completion routines may 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 which is equivalent to FIOASYNC. Return Values Upon successful completion, the WSAIoctl returns zero. Otherwise, a value of SOCKET_ERROR is returned, and a specific error code may be retrieved by calling WSAGetLastError. Error Codes
| WSAENETDOWN
| The network subsystem has failed.
|
| WSAEFAULT
| The lpvInBuffer, lpvOutBuffer or lpcbBytesReturned 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 examle, the flow
specifications specified in SIO_SET_QOS or SIO_SET_GROUP_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 marked as nonblocking and the requested operation would block.
|
- Software for developers
-
Delphi Components
.Net Components
Software for Android Developers - More information resources
-
MegaDetailed.Net
Unix Manual Pages
Delphi Examples - Databases for Amazon shops developers
-
Amazon Categories Database
Browse Nodes Database