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

Статья
08/27/2023

Функция 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.

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

Значение

SIO_NSP_NOTIFY_CHANGE

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

[in] lpvInBuffer

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

[in, out] cbInBuffer

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

[out] lpvOutBuffer

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

[in] cbOutBuffer

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

[out] lpcbBytesReturned

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

[in] lpCompletion

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

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

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

Код ошибки	Описание
WSA_INVALID_HANDLE	Параметр hLookup не является допустимым дескриптором запроса, возвращенным WSALookupServiceBegin.
WSA_IO_PENDING	Перекрываемая операция была успешно инициирована, а завершение будет указано позже.
WSAEFAULT	Аргумент lpvInBuffer, cbInBuffer, lpvOutBuffer, cbOutBuffer или lpCompletion не полностью содержится в допустимой части адресного пространства пользователя. Кроме того, аргумент cbInBuffer или cbOutBuffer слишком мал, и аргумент изменяется для отражения требуемого размера выделения.
WSAEINVAL	Указанный параметр недопустим, или операция некорректно возвращает результаты из нескольких пространств имен, если это не имеет смысла для указанной операции.
WSAENETDOWN	Произошел сбой сетевой подсистемы.
WSAEOPNOTSUPP	Операция не поддерживается. Эта ошибка возвращается, если поставщик пространства имен не реализует эту функцию. Эта ошибка также может быть возвращена, если указанная команда dwControlCode является нераспознанной.
WSAEWOULDBLOCK	Сокет не использует перекрывающиеся операции ввода-вывода (асинхронная обработка), но параметр lpCompletion не имеет значения NULL. Эта ошибка используется в качестве специального уведомления для SIO_NSP_NOTIFY_CHANGE IOCTL, если параметр lpCompletion имеет значение NULL (опрос), чтобы указать, что набор запросов остается действительным.

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

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

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

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

SIO_NSP_NOTIFY_CHANGE

Поставщики пространств имен Майкрософт, поддерживающие этот 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.

Примечание Все операции ввода-вывода, инициированные данным потоком, отменяются при выходе из этого потока. Для перекрывающихся сокетов ожидающие асинхронные операции могут завершиться сбоем, если поток закрывается до завершения операций. Дополнительные сведения см. в разделе ExitThread .

Windows Phone 8. Эта функция поддерживается для приложений Магазина Windows Phone Windows Phone 8 и более поздних версий.

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

Требования

Требование	Значение
Минимальная версия клиента	Windows 8.1, Windows Vista [классические приложения \| Приложения UWP]
Минимальная версия сервера	Windows Server 2003 [классические приложения \| Приложения UWP]
Целевая платформа	Windows
Header	winsock2.h