WSHIoctl
INT
WSHIoctl(
IN PVOID HelperDllSocketContext,
IN SOCKET SocketHandle,
IN HANDLE TdiAddressObjectHandle,
IN HANDLE TdiConnectionObjectHandle,
IN DWORD IoControlCode,
IN LPVOID InputBuffer,
IN DWORD InputBufferLength,
IN LPVOID OutputBuffer,
IN DWORD OutputBufferLength,
OUT LPDWORD NumberOfBytesReturned,
IN LPWSAOVERLAPPED Overlapped,
IN LPWSAOVERLAPPED_COMPLETION_ROUTINE CompletionRoutine,
OUT LPBOOL NeedsCompletion
);
WSHIoctl returns information or carries out a particular operation
specified by the given IoControlCode.
Parameters
-
HelperDllSocketContext
-
Points to a per-socket context area, allocated and initialized by the WSH DLL WSHOpenSocket
or WSHOpenSocket2 function.
-
SocketHandle
-
Specifies a handle to the socket that is the target of the requested
operation.
-
TdiAddressObjectHandle
-
Specifies the handle to a file object representing the open transport address
for the socket. If the socket is not currently bound to an address, this
parameter is NULL.
-
TdiConnectionObjectHandle
-
Specifies the handle to a file object representing the connection endpoint
associated with the socket. If the socket is not currently connected, this
parameter is NULL.
-
IoControlCode
-
Specifies an SIO_XXX code requesting a specific operation. The
following are possible system-defined IoControlCodes:
-
SIO_FIND_ROUTE
-
Requests that the route to this socket be determined. InputBuffer will
be NULL. However, OutputBuffer must not be null.
-
SIO_FLUSH
-
Requests that the current contents of the send queue for the socket be
flushed. InputBuffer and OutputBuffer will be NULL.
-
SIO_MULTIPOINT_LOOPBACK
-
Requests that, whenever data is sent on a multipoint session socket, the data
also be sent to the socket on the local host if the data in InputBuffer
is TRUE. Otherwise, the socket is requested to terminate that behavior.
-
SIO_MULTICAST_SCOPE
-
Sets, for the socket specified, wheter data sent on a multipoint sessions
socket will cross routers. If the InputBuffer contains zero, no data
should be sent except to multipoint session members on the local host. The
value one indicates that no routers should be crossed. Values greater than one
indicate that n-1 routers may be crossed when data is sent.
A helper DLL also can define its own codes.
-
InputBuffer
-
Points to an input buffer for the operation requested by the given IoControlCode.
-
InputBufferLength
-
Specifies the length in bytes of the buffer at InputBuffer.
-
OutputBuffer
-
Points to an output buffer for the operation requested by the given IoControlCode.
This buffer is used to return information or query results to the caller.
-
OutputBufferLength
-
Specifies the length in bytes of the buffer at OutputBuffer.
-
NumberOfBytesReturned
-
On return, specifies the number of bytes copied into the buffer at OutputBuffer.
-
Overlapped
-
Specifies a pointer to a WSAOVERLAPPED structure to facilitate asynchronous
I/O.
-
CompletionRoutine
-
Specifies a pointer to a WSAOVERLAPPED_COMPLETION_ROUTINE provided by the
caller.
-
NeedsCompletion
-
On output, specifies whether the service provider should perform I/O
completion operations for overlapped requests.
Return Value
-
WSHIoctl returns zero to indicate successful operation. Otherwise, it
returns a Winsock Error code, as outlined in the following:
-
WSAENETDOWN
Specifies that the network has failed.
-
WSAEFAULT
-
Specifies that one or more of the buffers at InputBuffer or OutputBuffer
are too small for successful operation.
-
WSAEINVAL
-
Specifies that the IoControlCode is not a valid command or that a
supplied parameter is invalid.
-
WSAEINPROGRESS
-
Specifies that WSHIoctl was called while there was a completion routine
callback in progress. This error can be returned only if the helper DLL
handles I/O completion of overlapped requests itself.
-
WSAEOPNOTSUPP
-
Specifies that a normally valid IoControlCode is inappropriate to this
socket. This generally indicates that the requested operation is not supported
by the underlying protocol.
-
WSA_IO_PENDING
-
Specifies that the request is still in progress and will be completed at a
later time. This error code can be returned only if overlapped information has
been supplied at Overlapped or OverlappedRoutine.
-
WSAEWOULDBLOCK
-
Specifies that this operation would block the socket but the socket has been
marked as a non-blocking socket.
Comments
WSHIoctl is called by the service provider to satisfy several types of
requests. In addition, it is possible for a helper DLL to support operations
designated by privately defined I/O control codes specific to a protocol that
the helper DLL supports. Such privately defined codes will be transmitted to
the helper DLL by WSAIoctl. For more information on WSAIoctl or
custom control codes, see the Win32 SDK.
Because some operations that are normally requested through WSHIoctl
can require a significant amount of time to complete, an overlapped I/O
mechanism is provided. A caller either specifies a WSAOVERLAPPED structure in Overlapped
or specifies a callback routine in OverlappedRoutine.
When such an I/O operation is completed, the helper DLL can either handle I/O
completion in the overlapped manner itself, or allow the service provider to
handle such operations. This is controlled by the NeedsCompletion
parameter.
If the helper DLL chooses to handle the I/O completion itself, the following
guidelines apply:
-
If a completion routine is specified in OverlappedRoutine, the
structure provided at Overlapped should be ignored.
-
If a completion routine is not specified, then the Overlapped parameter
is used. The event handle provided in this structure should be signalled to
indicate to the caller that the I/O has completed.
-
When calling a completion routine provided at OverlappedRoutine, the
number of bytes transferred, normally returned in NumberOfBytesReturned
and an error code (zero indicating success) must be passed as the defined
parameters to this caller-supplied I/O completion routine.