Функция WSANSPIoctl (winsock2.h)

Функция WSANSPIoctl windows Sockets позволяет разработчикам выполнять вызовы элементов управления вводом-выводом в зарегистрированное пространство имен.

Синтаксис

INT WSAAPI WSANSPIoctl(
  [in]      HANDLE          hLookup,
  [in]      DWORD           dwControlCode,
  [in]      LPVOID          lpvInBuffer,
  [in, out] DWORD           cbInBuffer,
  [out]     LPVOID          lpvOutBuffer,
  [in]      DWORD           cbOutBuffer,
  [out]     LPDWORD         lpcbBytesReturned,
  [in]      LPWSACOMPLETION lpCompletion
);

Параметры

[in] hLookup

Дескриптор подстановки, возвращенный при предыдущем вызове функции WSALookupServiceBegin .

[in] dwControlCode

Управляющий код выполняемой операции.

Значения, которые могут использоваться для параметра dwControlCode , определяются поставщиком пространства имен.

Следующее значение поддерживается несколькими поставщиками пространств имен Майкрософт, включая поставщик пространства имен Network Location Awareness (NS_NLA). Этот IOCTL определяется в файле заголовка Winsock2.h.

[in] lpvInBuffer

Указатель на входной буфер.

[in, out] cbInBuffer

Размер входного буфера (в байтах).

[out] lpvOutBuffer

Указатель на выходной буфер.

[in] cbOutBuffer

Размер выходного буфера (в байтах).

[out] lpcbBytesReturned

Указатель на количество возвращаемых байтов.

[in] lpCompletion

Указатель на структуру WSACOMPLETION , используемую для асинхронной обработки. Присвойте lpCompletion значение NULL, чтобы принудительно блокировать (синхронное) выполнение.

Возвращаемое значение

Успех возвращает NO_ERROR. Сбой возвращает SOCKET_ERROR, и конкретный код ошибки можно получить, вызвав функцию WSAGetLastError . В следующей таблице описаны коды ошибок.

Комментарии

Функция WSANSPIoctl используется для задания или извлечения операционных параметров, связанных с дескриптором запроса, для поставщика пространства имен. Параметр hLookup — это дескриптор запроса поставщика пространства имен, ранее возвращенного функцией WSALookupServiceBegin (не дескриптором сокета).

Любой IOCTL, отправленный поставщику пространства имен, может блокироваться на неопределенный срок в зависимости от реализации пространства имен. Если приложение не допускает блокировки в вызове функции WSANSPIoctl , следует использовать перекрывающийся ввод-вывод, а параметр lpCompletion должен указывать на структуру WSACOMPLETION . Чтобы функция WSANSPIoctl вызывала неблокировку и возвращала немедленно, задайте для элемента Type структуры WSACOMPLETIONзначение NSP_NOTIFY_IMMEDIATELY.

Если lpCompletion имеет значение NULL, функция WSANSPIoctl выполняется как блокирующий вызов. Поставщик пространства имен должен возвращать немедленно и не блокировать. Но каждое пространство имен отвечает за применение этого поведения.

Следующий код IOCTL поддерживается несколькими поставщиками пространства имен Майкрософт:

SIO_NSP_NOTIFY_CHANGE

Эта операция проверяет, являются ли по-прежнему допустимыми результаты, возвращаемые при предыдущих вызовах с помощью параметра hLookup . Эти предыдущие вызовы включают первоначальный вызов функции WSALookupServiceBegin для получения параметра hLookup . Эти предыдущие вызовы также могут включать вызовы функции WSALookupServiceNext с использованием параметра hLookup .

Поставщики пространств имен Майкрософт, поддерживающие этот IOCTL, включают следующие.

• NS_NLA — поставщик пространства имен NLA.
• NS_PNRPNAME — поставщик пространства имен PNRP.
• NS_PNRPCLOUD — поставщик облачного пространства имен PNRP.

Могут быть установлены другие сторонние поставщики пространств имен, которые также поддерживают этот IOCTL.

Если параметр lpCompletion имеет значение NULL, этот IOCTL реализует специальное поведение. Если параметр lpCompletion имеет значение NULL для этого IOCTL, эта операция является опросом и возвращается немедленно. Если набор запросов остается действительным, WSAEWOULDBLOCK возвращается как уведомление о том, что набор запросов остается действительным. Если набор запросов изменился и является недопустимым, возвращается NO_ERROR , указывающий на успешное выполнение опроса для аннулирования набора запросов.

Если параметр lpCompletion не имеет значения NULL и указывает на структуру WSACOMPLETION , функция WSANSPIoctl возвращает WSA_IO_PENDING , если перекрывающаяся операция была успешно инициирована и завершение будет указано позже. Метод, указанный в структуре WSACOMPLETION , используется для уведомления приложения о том, что набор запросов по-прежнему действителен.

Не все протоколы разрешения имен поддерживают эту функцию, поэтому вызов функции может завершиться ошибкой при использовании WSAEOPNOTSUPP. Запрос, содержащий данные от нескольких поставщиков, не может вызвать этот IOCTL и вернет WSAEINVAL.

Параметры lpvInBuffer, cbInBuffer, lpvOutBuffer и cbOutBuffer в настоящее время игнорируются поставщиками пространств имен Майкрософт.

Для однопоточных приложений типичный метод использования функции WSANSPIoctl выглядит следующим образом. Вызовите функцию WSANSPIoctl с параметром dwControlCode , имеющим значение SIO_NSP_NOTIFY_CHANGE без процедуры завершения (параметр lpCompletion имеет значение NULL) после каждого вызова функции WSALookupServiceNext , чтобы убедиться, что данные запроса по-прежнему действительны. Если данные становятся недопустимыми, вызовите функцию WSALookupServiceEnd , чтобы закрыть дескриптор запроса. Вызовите функцию WSALookupServiceBegin , чтобы получить новый дескриптор запроса и начать запрос снова.

Для многопоточных приложений типичный метод использования функции WSANSPIoctl выглядит следующим образом. Вызовите функцию WSANSPIoctl с параметром dwControlCode , который имеет значение SIO_NSP_NOTIFY_CHANGE с подпрограммой завершения после первоначального вызова функции WSALookupServiceBegin . Приложение будет использовать механизм уведомления, указанный в подпрограмме завершения, чтобы получать уведомления о том, что данные больше не являются допустимыми. Одним из распространенных механизмов является использование события, указанного в подпрограмме завершения. Если данные становятся недопустимыми, вызовите функцию WSALookupServiceEnd , чтобы закрыть дескриптор запроса. Вызовите функции WSALookupServiceBegin и WSANSPIoctl , чтобы получить новый дескриптор запроса и начать запрос снова.

Некоторые протоколы могут просто кэшировать сведения локально и сделать их недействительными через некоторое время. В этом случае может быть выдано уведомление о том, что локальный кэш был признан недействительным.

Для протоколов разрешения имен, в которых изменения происходят редко, поставщик пространства имен может указать глобальное событие изменения, которое может быть неприменимо к запросу, по которому было запрошено и выдано уведомление об изменении.

Операции немедленного опроса обычно гораздо дешевле, так как для них не требуется объект уведомления. В большинстве случаев это реализуется как простая логическая переменная проверка. Однако асинхронное уведомление может потребовать создания выделенных рабочих потоков и (или) каналов обмена данными между процессами в зависимости от реализации службы поставщика пространства имен. Это приведет к дополнительным затратам на обработку объекта уведомления, связанного с сигналом о событии изменения.

Чтобы отменить асинхронный запрос на уведомление, завершите исходный запрос вызовом функции WSALookupServiceEnd для затронутого дескриптора запроса. Отмена асинхронного уведомления для LUP_NOTIFY_HWND не будет отправлять сообщения, однако будет завершена перекрывающаяся операция, и уведомление будет доставлено с ошибкой WSA_OPERATION_ABORTED.

Windows 8.1 и Windows Server 2012 R2. Эта функция поддерживается для приложений Магазина Windows в Windows 8.1, Windows Server 2012 R2 и более поздних версий.

Требования

См. также раздел

ExitThread

WSACOMPLETION

WSAGetLastError

WSALookupServiceBegin

WSALookupServiceEnd

WSALookupServiceNext

Функции Winsock