Функция обратного вызова LPNSPIOCTL (ws2spi.h)

Статья
08/28/2023

Функция NSPIoctl отправляет IOCTL поставщику службы пространства имен.

Синтаксис

LPNSPIOCTL Lpnspioctl;

INT Lpnspioctl(
  [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]      LPWSATHREADID lpThreadId
)
{...}

Параметры

[in] hLookup

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

[in] dwControlCode

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

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

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

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

Значение

SIO_NSP_NOTIFY_CHANGE

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

[in] lpvInBuffer

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

[in, out] cbInBuffer

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

[out] lpvOutBuffer

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

[in] cbOutBuffer

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

[out] lpcbBytesReturned

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

[in] lpCompletion

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

[in] lpThreadId

Указатель на структуру WSATHREADID , которая будет использоваться поставщиком в последующем вызове WPUQueueApc. Поставщик должен хранить указанную структуру WSATHREADID (не указатель), пока не будет возвращена функция WPUQueueApc .

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

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

Функция NSPIoctl должна возвращать SOCKET_ERROR (т. е. 1), если подпрограмма завершается сбоем, и она должна задать соответствующий код ошибки с помощью WSASetLastError.

Код ошибки WSA_IO_PENDING указывает, что перекрывающаяся операция была успешно инициирована и что завершение будет указано позже. Любой другой код ошибки указывает, что не была инициирована перекрывающаяся операция и не будет никаких указаний завершения.

Код ошибки	Описание
WSA_INVALID_HANDLE	Параметр hLookup не был допустимым дескриптором запроса, возвращенным NSPLookupServiceBegin.
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 (опрос), чтобы указать, что набор запросов остается действительным.

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

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

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

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

SIO_NSP_NOTIFY_CHANGE

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Требования


Минимальная версия клиента	Windows XP [только классические приложения]
Минимальная версия сервера	Windows Server 2003 [только классические приложения]
Целевая платформа	Windows
Header	ws2spi.h