WSHIoctl function
[ This function is obsolete for Windows Server 2003, Windows Vista, and later, and is no longer supported. ]
The WSHIoctl function returns information or carries out a particular operation specified by the given IoControlCode.
Syntax
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
);
Parameters
HelperDllSocketContext [in]
Pointer to a per-socket context area, allocated and initialized by the WSH DLL WSHOpenSocket or WSHOpenSocket2 function.SocketHandle [in]
Specifies a handle to the socket that is the target of the requested operation.TdiAddressObjectHandle [in]
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 [in]
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 [in]
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, whether 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 [in]
Pointer to an input buffer for the operation requested by the given IoControlCode.InputBufferLength [in]
Specifies the length in bytes of the buffer at InputBuffer.OutputBuffer [in]
Pointer 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 [in]
Specifies the length in bytes of the buffer at OutputBuffer.NumberOfBytesReturned [out]
On return, specifies the number of bytes copied into the buffer at OutputBuffer.Overlapped [in]
Specifies a pointer to a WSAOVERLAPPED structure to facilitate asynchronous I/O.CompletionRoutine [in]
Specifies a pointer to a WSAOVERLAPPED_COMPLETION_ROUTINE provided by the caller.NeedsCompletion [out]
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:
| Return code | Description |
|---|---|
| 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 nonblocking socket. |
Remarks
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 about WSAIoctl or custom control codes, see the Microsoft Windows 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 signaled 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.
Requirements
Target platform |
Desktop |
Header |
Wsahelp.h (include Wsahelp.h) |