WSANSPIoctl

A version of this page is also available for

Windows Embedded CE 6.0 R3

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.

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.

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

See Also

Reference

WSALookupServiceBegin (Windows Sockets)
WSALookupServiceEnd (Windows Sockets)