WSANSPIoctl
A version of this page is also available for
4/8/2010
This function enables developers to make I/O control calls to a registered namespace.
Syntax
int WSAAPI WSANSPIoctl(
HANDLE hLookup,
DWORD dwControlCode,
LPVOID lpvInBuffer,
DWORD cbInBuffer,
LPVOID lpvOutBuffer,
DWORD cbOutBuffer,
LPDWORD lpcbBytesReturned,
LPWSACOMPLETION lpCompletion
);
Parameters
- hLookup
[in] Lookup handle returned from a call to the WSALookupServiceBegin (Windows Sockets) function.
- dwControlCode
[in] Control code of the operation to perform.
- lpvInBuffer
[in] Pointer to the input buffer.
- cbInBuffer
[in, out] Size of the input buffer, in bytes.
- lpvOutBuffer
[out] Pointer to the output buffer.
- cbOutBuffer
[in, out] Pointer to an integral value for the size of the output buffer.
- lpcbBytesReturned
[out] Pointer to the number of bytes returned.
- lpCompletion
[in] Pointer to a WSACOMPLETION structure, used for asynchronous processing. Set lpCompletion to NULL to force blocking (synchronous) execution.
Return Value
Success returns NO_ERROR. Failure returns SOCKET_ERROR. A specific error code can be retrieved by calling the WSAGetLastError function. The following table describes the error codes.
| Error code | Description |
|---|---|
WSA_INVALID_HANDLE |
hLookup was not a valid query handle returned by WSALookupServiceBegin. |
WSA_IO_PENDING |
An overlapped operation was successfully initiated and completion will be indicated at a later time. |
WSAEFAULT |
The lpvInBuffer, cbInBuffer, lpvOutBuffer, cbOutBuffer, or lpCompletion argument is not totally contained in a valid part of the user address space. Alternatively, the cbInBuffer or cbOutBuffer argument is too small, and the argument is modified to reflect the required allocation size. |
WSAENETDOWN |
A supplied parameter is not acceptable, or the operation inappropriately returns results from multiple namespaces when it does not make sense for the specified operation. |
WSAEOPNOTSUPP |
The network subsystem has failed. |
WSAEWOULDBLOCK |
The socket is not using overlapped I/O, asynchronous processing, yet the lpCompletion parameter is non-NULL. |
Remarks
This function is used to set or retrieve operating parameters associated with a namespace query handle.
Any IOCTL may block indefinitely, depending upon the relevant namespace's implementation. If an application cannot tolerate blocking in a WSANSPIoctl function call, overlapped I/O is advised and completion is subsequently indicated through the mechanism specified in the lpCompletion parameter, which is a pointer to a WSACOMPLETION structure. If lpCompletion is NULL, the WSANSPIoctl function executes as a blocking call.
To make a WSANSPIoctl function call nonblocking and return immediately, set WSACOMPLETION::Type to NSP_NOTIFY_IMMEDIATELY.
Note
All I/O initiated by a given thread is cancelled when that thread exits. For overlapped sockets, pending asynchronous operations can fail if the thread is closed before the operations complete. For more information, see ExitThread.
The following IOCTL code is supported:
SIO_NSP_NOTIFY_CHANGE
Note
The default providers in Windows Embedded CE support only the NSP_NOTIFY_IMMEDIATELY and NSP_NOTIFY_EVENT completion types. Third party providers may support other completion types.
This operation checks if the query results returned using calls to the WSALookupServiceBegin (Windows Sockets) and WSALookupServiceNext (Windows Sockets) functions remain valid. If lpCompletion is NULL, this operation is a poll and returns immediately. If the query set remains valid, error code WSAEWOULDBLOCK is returned as notification that the invalidation requires asynchronous notification and lpCompletion is NULL. If the query set has changed and is invalid, NO_ERROR is returned. This indicates success in polling for invalidation of the query set.
Not all name resolution protocols are able to support this feature, and therefore, this function call may fail with error code WSAEOPNOTSUPP. A query that contains data from multiple providers cannot call this IOCTL, and will return error code WSAEINVAL.
The lpvInBuffer, cbInBuffer, lpvOutBuffer, and cbOutBuffer parameters are ignored.
Some protocols may simply cache the information locally and invalidate it after some time, in which case notification may be issued to indicate the local cache has been invalidated.
For name resolution protocols where changes are infrequent, it is possible for a namespace service provider to indicate a global change event that may not be applicable to the query on which change notification was requested and issued.
Immediate poll operations are usually much less expensive because they do not require a notification object. In most cases, this is implemented as a simple Boolean variable check. Asynchronous notification, however, may necessitate the creation of dedicated worker thread(s) and/or inter-process communication channel(s), depending on namespace service provider implementation, and will incur processing overhead related to the notification object involved with signaling the change event.
To cancel an asynchronous notification request, end the original query with a WSALookupServiceEnd (Windows Sockets) function call on the affected query handle. Canceling asynchronous notification for LUP_NOTIFY_HWND will not post any message, however, an overlapped operation will be completed and notification will be delivered with the error WSA_OPERATION_ABORTED.
Requirements
| Header | winsock2.h |
| Library | Ws2.lib |
| Windows Embedded CE | Windows CE .NET 4.0 and later |
| Windows Mobile | Windows Mobile Version 5.0 and later |
See Also
Reference
WSALookupServiceBegin (Windows Sockets)
WSALookupServiceEnd (Windows Sockets)