Modifying IO Behavior

So far, we have described how to query and set the attributes of a socket using options. In the rest of this chapter, we will consider how you might modify the I/O behavior of a socket. There are two functions with which you can modify the I/O behavior—ioctlsocket() and WSAIoctl(). These functions are defined in Winsock2.pas, and their prototypes are listed as follows:

function ioctlsocket(s: TSocket; cmd: Longint; var argp: u_long): Integer; stdcall;

function WSAIoctl(s: TSocket; dwIoControlCode: DWORD; lpvInBuffer: LPVOID; cblnBuffer: DWORD; lpvOutBuffer: LPVOID; cbOutBuffer: DWORD; var lpcbBytesReturned: DWORD; lpOverlapped: LPWSAOVERLAPPED; lpCompletionRoutine: LPWSAOVERLAPPED_COMPLETION_ROUTINE): Integer; stdcall;

As you can see, the WSAIoctl() function, which is part of the Winsock 2 implementation, packs more power and functionality than ioctlsocket(), but we will consider ioctlsocket() first as an introduction.

The first parameter refers to the socket, s, with which you want to work. The second parameter, cmd, is the command that the function is to execute. The third parameter, argp, stores the result of the operation on that socket.

The function ioctlsocket() supports the following commands: FIONBIO, FIONREAD, and SIOCATMARK. These commands are present in all versions of Winsock. Calling ioctlsocket() with the FIONBIO command enables or disables non-blocking mode on a socket (refer to Chapter 5).

The FIONREAD command determines the amount of data that can be read from socket s. On a stream socket (e.g., SOCK_STREAM), argp points to an unsigned long integer in which ioctlsocket() will store the result. The function returns the size of the data that may be read in a single receive operation, which may not be the same as the total amount of data queued on the socket. On a datagram socket (SOCK_DGRAM), the function returns the size of the first datagram queued on the socket, which might not be the same size as subsequent datagrams.

You should use FIONREAD on a socket that has the socket option SO_OOB-INLINE already set. That is, the socket has been set to receive out-of-band data (refer to Chapter 5). When you call ioctlsocket() with this command, the function determines if the data queued on the socket is out-of-band data or normal data. If data to be read is out-of-band, the function will return a TRUE value in the argp parameter. (For WSAIoctl(), the Boolean result points to the lpvOutBuffer parameter, which we will describe later.)

As we have seen from the implementation, WSAIoctl() is more complex to use than ioctlsocket(). However, at the price of complexity, not only can you use WSAIoctl() either to set or retrieve operating parameters for the specified socket, you can use it to set or retrieve the underlying transport protocol.

The first parameter, s, is the socket. The second parameter, dwIoControlCode, defines the operational code to execute. For a listing of these commands, refer to Table 6-5. The third and fourth parameters, lpvInBuffer and cbInBuffer, are input buffers. The first is a pointer to the value to which you pass, and the second is a pointer to the size of the first buffer. Similarly, the fifth parameter, lpvOutBuffer, is a pointer to an output buffer that receives the data, and the sixth parameter, cbOutBuffer, is the size of the output buffer. lpcbBytesReturned indicates the number of bytes returned. Finally, if you set the lpOverlapped and lpCompletionRoutine parameters to NIL, the function will treat the socket, s, as a non-overlapped socket. You should use WSAIoctl() for overlapped I/O operations, in which case the parameters lpOverlapped and lpCompletionRoutine must point to a valid overlapped structure and a callback routine, respectively.

In addition to the tasks described so far, you can use the ioctlsocket() and WSAIoctl() functions for QOS and multicast applications, which are beyond the scope of this tome.

Table 6-5: Commands for ioctlsocket() and WSAIoctl()

Command

Platform

Function

Input

Output

Winsock Version

CIRCULAR

QUEUEING

Windows 2000 and NT 4.0

WSAIoctl

Boolean

Boolean

2 and later

If the incoming buffer overflows, discard oldest message first.

SIO FIND ROUTE

Not supported

WSAIoctl

TSockAddrIn

Boolean

2 and later

Verifies that a route to the given address exists.

SIO_FLUSH

Windows 2000 and NT 4.0

WSAIoctl

None

None

2 and later

Determines whether OOB data has been read.

SIO GET

BROADCAST_

ADDRESS

Windows 2000 and NT 4.0

WSAIoctl

None

TSockAddrIn

2 and later

Returns a broadcast address for the address family of the socket.

SIO_GET_ EXTENSION FUNCTION POINTER

All Win32 platforms

WSAIoctl

Tguid

Function pointer

2 and later

Retrieves a function pointer specific to the underlying provider.

SIO_CHK_QOS

Windows 2000

WSAIoctl

DWORD

DWORD

2 and later

Sets the QOS attributes for the socket.

SIO GET QOS

Windows 2000 and Windows 98

WSAIoctl

None

QOS structure

2 and later

Returns the QOS data structure for the socket.

SIO_SET_QOS

Windows 2000 and Windows 98

WSAIoctl

QOS structure

None

2 and later

Sets the QOS properties for the socket.

SIO MULTIPOINT LOOPBACK

All Win32 platforms

WSAIoctl

Boolean

Boolean

2 and later

Sets or gets whether the multicast data will be looped back to the socket.

SIO MULTI-CAST_SCOPE

All Win32 platforms

WSAIoctl

Integer

Integer

2 and later

Gets or sets the time to live (TTL) value for multicast data.

SIO_KEEP-ALIVE_VALS

Windows 2000

WSAIoctl

tcp keepalive structure

tcp_keepalive structure

2 and later

Sets the TCP keepalives active on each connection.

SIO_RCVALL

Windows 2000

WSAIoctl

Unsigned integer

None

2 and later

Receives all packets on the network.

SIO RCVALL M CAST

Windows 2000

WSAIoctl

Unsigned integer

None

2 and later

Receives all multicast packets on the network.

SIO RCVALL IGMPMCAST

Windows 2000

WSAIoctl

Unsigned integer

None

2 and later

Receives all IGMP packets on the network.

Command

Platform

Function

Input

Output

Winsock Version

INTERFACE

QUERY

Windows 2000

WSAIoctl

TSockAddrIn

None

2 and later

Determines whether OOB data has been read.

SIO ROUTING

INTERFACE

CHANGE

Windows 2000

WSAIoctl

TSockAddrIn

None

2 and later

Sends notification when an interface to a remote socket has changed.

SIO ADDRESS LIST QUERY

All Win32 platforms

WSAIoctl

None

TSOCKET ADDRESS LIST structure

2 and later

Returns a list of interfaces to which the socket can bind.

SIO GET INTER FACE LIST

All Win32 platforms

WSAIoctl

_INFO

structure

2 and later

Returns a list of local interfaces.

SO SSL GET CAPABILITIES

Windows CE

WSAIoctl

None

DWORD

1.1

Returns the Winsock security provider's capabilities.

SO SSL GET FLAGS

Windows CE

WSAIoctl

None

DWORD

1.1

Returns s-channel-specific flags for the socket.

SO SSL SET FLAGS

Windows CE

WSAIoctl

DWORD

None

1.1

Sets the socket's s-channel-specific flags.

SO SSL GET PROTOCOLS

Windows CE

WSAIoctl

None

SSLPROTO-COLS

1.1

Returns a list of protocols supported by the security provider.

SO SSL SET PROTOCOLS

Windows CE

WSAIoctl

SSLPROTO-COLS

None

1.1

Sets a list of protocols that the underlying provider should support.

SO SSL SET

VALIDATE

CERT_HOOK

Windows CE

WSAIoctl

SSLVALIDATE CERTHOOK

None

1.1

Sets the validation function for accepting SSL certificates.

SO SSL PERFORM HANDSHAKE

Windows CE

WSAIoctl

None

None

1.1

Initiates a secure handshake on a connected socket.

SIO GET NUM BER OF ATM DEVICES

Windows 2000

WSAIoctl

None

DWORD

2 and later

Returns the number of ATM adapters.

SIO GET ATM ADDRESS

Windows 2000

WSAIoctl

DWORD

TATM ADDRESS

2 and later

Returns the ATM address for the given device.

SIO ASSOCIATE PVC

Windows 2000

PARAMS

structure

None

2 and later

Associates socket with a permanent virtual circuit.

SIO GET ATM CONNECTION ID

Windows 2000?

WSAIoctl & ioctlsocket

None

TATM CONNECTION ID

2 and later

Determines whether OOB data has been read.

Before we give formal definitions of the functions discussed, here is a word about the examples. Unlike the previous chapters where we give examples of using the functions, we have a collection of examples to demonstrate the usage of these functions with different levels and options. Only two levels, SOL_ SOCKET and IPPROTO_IP, are used with getsockopt() and setsockopt() functions. For a demonstration on how to use the ioctlsocket() function with the FIONBIO option, please refer to Listing 5-4 in Chapter 5.

Was this article helpful?

0 0

Responses

  • LIA CAPON
    Where ioctlsocket is defined in delphi?
    2 years ago

Post a comment