Success returns NO_ERROR. Failure returns SOCKET_ERROR. A specific error code can be retrieved by calling the WSAGetLastErrorfunction. The following table describes the error codes.

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 WSANSPIoctlfunction 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 WSANSPIoctlfunction 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.