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.