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

Статья
08/28/2023

Функция NSPv2SetServiceEx регистрирует или отменяет регистрацию имени или экземпляра службы в пространстве имен поставщика службы пространства имен версии 2 (NSPv2).

Синтаксис

LPNSPV2SETSERVICEEX Lpnspv2setserviceex;

void Lpnspv2setserviceex(
  [in] HANDLE hAsyncCall,
  [in] LPGUID lpProviderId,
  [in] LPWSAQUERYSET2W lpqsRegInfo,
  [in] WSAESETSERVICEOP essOperation,
  [in] DWORD dwControlFlags,
  [in] LPVOID lpvClientSessionArg
)
{...}

Параметры

[in] hAsyncCall

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

[in] lpProviderId

Указатель на GUID конкретного поставщика пространства имен, в котором зарегистрировано имя или служба.

[in] lpqsRegInfo

Сведения о свойстве, обновляемые после регистрации.

[in] essOperation

Тип запрошенной операции.

Этот параметр может быть одним из значений типа перечисления WSAESETSERVICEOP , определенного в файле заголовка Winsock2.h .

Значение	Значение
RNRSERVICE_REGISTER 0	Зарегистрируйте службу. Для пространства имен SAP, используемого в среде NetWare, это означает отправку периодической широковещательной рассылки. Это nop для пространства имен DNS. Для постоянных хранилищ данных это означает обновление сведений об адресе.
RNRSERVICE_DEREGISTER 1	Отмените регистрацию службы. Для пространства имен SAP это означает прекращение отправки периодической широковещательной рассылки. Это nop для пространства имен DNS. Для постоянных хранилищ данных это означает удаление сведений об адресе.
RNRSERVICE_DELETE 2	Удалите службу из динамических имен и постоянных пробелов. Для служб, представленных несколькими структурами CSADDR_INFO (с использованием флага SERVICE_MULTIPLE), будет удален только указанный адрес, который должен точно соответствовать соответствующей структуре CSADDR_INFO, предоставленной при регистрации службы.

[in] dwControlFlags

Набор флагов, управляющий запрошенной операцией.

Возможные значения для этого параметра определяются в файле заголовка Winsock2.h .

Значение	Значение
SERVICE_MULTIPLE 0x00000001	Управление область операции. Если это значение задано, действие выполняется только в заданном наборе адресов. Операция регистрации не делает недействительными существующие адреса, а отмена регистрации делает недействительными только указанный набор адресов. Если это значение отсутствует, адреса служб управляются как группа. Регистрация или отмена регистрации делает недействительными все существующие адреса перед добавлением заданного набора адресов.

Значение

SERVICE_MULTIPLE

0x00000001

Управление область операции.

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

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

[in] lpvClientSessionArg

Указатель на сеанс клиента.

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

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

Код ошибки	Значение
WSA_NOT_ENOUGH_MEMORY	Недостаточно памяти для выполнения этой операции.
WSAEACCES	Вызывающая подпрограмма не имеет достаточных привилегий для установки службы.
WSAEINVAL	Один или несколько параметров были недопустимыми или отсутствуют для этого поставщика.
WSAEOPNOTSUPP	Операция не поддерживается. Эта ошибка возвращается, если поставщик пространства имен не реализует эту функцию. Эта ошибка также может быть возвращена, если указанная команда dwControlCode является нераспознанной.
WSASERVICE_NOT_FOUND	Служба неизвестна. Служба не найдена в указанном пространстве имен.

Функция NSPv2Startup вызывается каждый раз, когда новый клиентский процесс начинает использовать поставщик пространства имен. Поставщики могут использовать аргумент сеанса клиента, на который указывает параметр ppvClientSessionArg , для хранения сведений об этом сеансе. Этот аргумент сеанса клиента можно передать в функцию NSPv2SetServiceEx в параметре lpvClientSessionArg .

Функция NSPv2SetServiceEx является необязательной в зависимости от требований поставщика NSPv2. Если функция NSPv2SetServiceEx не реализована, указатель на функцию NSPv2 может быть на функцию-заглушку, которая всегда возвращает NO_ERROR.

В следующей таблице перечислены возможные сочетания значений для параметров essOperation и dwControlFlags .

essOperation	dwControlFlags	Служба уже существует	Служба не существует
RNRSERVICE_REGISTER	None	Перезаписывает объект . Использует только указанные адреса. Объект имеет значение REGISTERED.	Создает новый объект. Использует только указанные адреса. Объект имеет значение REGISTERED.
RNRSERVICE_REGISTER	SERVICE_MULTIPLE	объект Обновления. Добавляет новые адреса в существующий набор. Объект имеет значение REGISTERED.	Создает новый объект. Использует все указанные адреса. Объект имеет значение REGISTERED.
RNRSERVICE_DEREGISTER	None	Удаляет все адреса, но не удаляет объект из пространства имен. Объект дерегистрирован.	WSASERVICE_NOT_FOUND
RNRSERVICE_DEREGISTER	SERVICE_MULTIPLE	объект Обновления. Удаляет только указанные адреса. Пометьте объект как DEREGISTERED только в том случае, если нет адресов. Не удаляется из пространства имен.	WSASERVICE_NOT_FOUND
RNRSERVICE_DELETE	None	Удаляет объект из пространства имен.	WSASERVICE_NOT_FOUND
RNRSERVICE_DELETE	SERVICE_MULTIPLE	Удаляет только указанные адреса. Удаляет объект из пространства имен, только если адресов не осталось.	WSASERVICE_NOT_FOUND

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

При использовании SERVICE_MULTIPLE приложение не должно позволять старым адресам оставаться в объекте . Это может произойти, если приложение прерывается без отправки запроса RNRSERVICE_DEREGISTER . Когда служба регистрируется, она должна хранить свои адреса. При следующем вызове служба должна явно отменить регистрацию этих старых адресов перед регистрацией новых адресов.

Если функция NSPv2SetServiceEx не реализована, вызовы этой функции должны быть перехвачены функцией-заглушки, которая возвращает WSAEOPNOTSUPP. Указатель функции NSPv2 на нереализованную функцию NSPv2SetServiceEx в структуре NSPV2_ROUTINE должен указывать на функцию-заглушку.

Свойства службы

В следующей таблице перечислены имена WSAQUERYSET2 членов и описано, как представляются данные свойств службы. Члены, помеченные как необязательные и зависящие от требований поставщика NSPv2, могут быть предоставлены в виде указателя **NULL**, если они не будут использоваться поставщиком пространства имен.

имя WSAQUERYSET2 участника	Описание свойства службы
dwSize	Задайте для параметра sizeof(WSAQUERYSET2). Это механизм управления версиями.
lpszServiceInstanceName	Строка, содержащая имя экземпляра службы.
lpVersion	Номер версии экземпляра службы. Этот член является необязательным и зависит от требований поставщика службы NSPv2.
lpszComment	Строка комментария. Этот член является необязательным и зависит от требований поставщика службы NSPv2.
dwNameSpace	Идентификатор пространства имен. Этот член является необязательным и зависит от требований поставщика службы NSPv2.
lpNSProviderId	Идентификатор поставщика. Обратите внимание, что идентификатор поставщика пространства имен также передается в параметре lpProviderId . Этот член является необязательным и зависит от требований поставщика службы NSPv2.
lpszContext	Начальная точка запроса в иерархическом пространстве имен. Этот член является необязательным и зависит от требований поставщика службы NSPv2.
dwNumberOfProtocols	Размер (в байтах) количества записей в массиве ограничений протокола. Этот элемент может быть равен нулю. Этот член является необязательным и зависит от требований поставщика службы NSPv2.
lpafpProtocols	Массив структур AFPROTOCOLS . Этот член является необязательным и зависит от требований поставщика службы NSPv2.
lpszQueryString	Некоторые пространства имен (например, whois++) поддерживают форматированные запросы, подобные SQL, содержащиеся в простой текстовой строке. Этот параметр используется для указания этой строки. Этот член является необязательным и зависит от требований поставщика службы NSPv2.
dwNumberOfCsAddrs	Количество элементов в массиве CSADDR_INFO структур, на которые ссылается lpcsaBuffer.
lpcsaBuffer	Указатель на массив CSADDR_INFO структур, содержащих адреса или адреса, прослушиваемые службой.
dwOutputFlags	Этот член является необязательным и зависит от требований поставщика службы NSPv2.
lpBlob	Указатель на сущность конкретного поставщика. Этот элемент является обязательным для пространства имен NS_EMAIL. Этот член является необязательным и зависит от требований к другим поставщикам служб NSPv2.

**Примечание** Допустимо, чтобы член **iProtocol** структуры CSADDR_INFO содержал константу манифеста **IPROTOCOL_ANY**, указывающую подстановочное значение. Поставщик пространства имен должен заменить допустимое значение для заданного семейства адресов и типа сокета.

Требования

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