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

Статья
08/27/2023

Функция WSASetService регистрирует или удаляет из реестра экземпляр службы в одном или нескольких пространствах имен.

Синтаксис

INT WSAAPI WSASetServiceA(
  [in] LPWSAQUERYSETA   lpqsRegInfo,
  [in] WSAESETSERVICEOP essoperation,
  [in] DWORD            dwControlFlags
);

Параметры

[in] lpqsRegInfo

Указатель на сведения о службе для регистрации или отмены регистрации.

[in] essoperation

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

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

[in] dwControlFlags

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

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

Flag

Значение

SERVICE_MULTIPLE

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

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

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

Код ошибки	Значение
WSAEACCES	Вызывающая подпрограмма не имеет достаточных привилегий для установки службы.
WSAEINVAL	Один или несколько обязательных параметров были недопустимыми или отсутствуют.
WSANOTINITIALISED	Ws2_32.dll не инициализирована. Приложение должно сначала вызвать WSAStartup , прежде чем вызывать функции Сокетов Windows.
WSA_NOT_ENOUGH_MEMORY	Недостаточно памяти для выполнения операции.

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

Доступные значения для essOperation и dwControlFlags объединяются для управления функцией WSASetService , как показано в следующей таблице.

Операция	Флаги	Служба уже существует	Служба не существует
RNRSERVICE_REGISTER	None	Перезаписывает объект . Использует только указанные адреса. Объект зарегистрирован.	Создает новый объект. Использует только указанные адреса. Объект зарегистрирован.
RNRSERVICE_REGISTER	SERVICE_MULTIPLE	Обновляет объект. Добавляет новые адреса в существующий набор. Объект зарегистрирован.	Создает новый объект. Использует все указанные адреса. Объект зарегистрирован.
RNRSERVICE_DEREGISTER	None	Удаляет все адреса, но не удаляет объект из пространства имен. Объект удаляется из реестра.	WSASERVICE_NOT_FOUND
RNRSERVICE_DEREGISTER	SERVICE_MULTIPLE	Обновляет объект. Удаляет только указанные адреса. Если нет адресов, объект помечается как ОТМЕНА РЕГИСТРАЦИИ. Не удаляет объект из пространства имен.	WSASERVICE_NOT_FOUND
RNRSERVICE_DELETE	None	Удаляет объект из пространства имен.	WSASERVICE_NOT_FOUND
RNRSERVICE_DELETE	SERVICE_MULTIPLE	Удаляет только указанные адреса. Удаляет объект из пространства имен только в том случае, если адресов не остается.	WSASERVICE_NOT_FOUND

Публикация служб в каталогах, таких как службы Active Directory, ограничена на основе списков управления доступом (ACL). Дополнительные сведения см. в разделе Проблемы безопасности для публикации службы.

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

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

Примечание Если используются символьные строки ANSI, существует вероятность того, что данные WSAQUERYSET в lpqsRegInfo могут не содержать никаких результатов после возврата этой функцией. Это связано с тем, что версия ANSI этого метода , WSASetServiceA, преобразует данные ANSI в WSAQUERYSET в Юникод внутренне, но не преобразует результаты обратно в ANSI. Это в первую очередь влияет на транспорты, которые возвращают "дескриптор записи службы", используемый для уникальной идентификации записи. Чтобы обойти эту проблему, приложения должны использовать строковые данные Юникода в WSAQUERYSET при вызове этой функции.

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

В следующей таблице описано, как данные свойств службы представлены в структуре WSAQUERYSET . Поля с меткой (необязательно) могут содержать пустой указатель.

Член WSAQUERYSET	Описание свойства службы
dwSize	Для параметра должно быть задано значение sizeof (WSAQUERYSET). Это механизм управления версиями.
dwOutputFlags	Неприменимо и игнорируется.
lpszServiceInstanceName	Строка, на который указывает ссылка, содержит имя экземпляра службы.
lpServiceClassId	Идентификатор GUID, соответствующий этому классу службы.
lpVersion	(Необязательно) Предоставляет номер версии экземпляра службы.
lpszComment	(Необязательно) Необязательная строка комментария.
dwNameSpace	См. таблицу ниже.
lpNSProviderId	См. таблицу ниже.
lpszContext	(Необязательно) Указывает начальную точку запроса в иерархическом пространстве имен.
dwNumberOfProtocols	Не обрабатывается.
lpafpProtocols	Не обрабатывается.
lpszQueryString	Не обрабатывается.
dwNumberOfCsAddrs	Количество элементов в массиве CSADDR_INFO структур, на которые ссылается lpcsaBuffer.
lpcsaBuffer	Указатель на массив CSADDR_INFO структур, содержащих адреса, прослушиваемые службой.
lpBlob	(Необязательно) Это указатель на сущность конкретного поставщика.

Как показано ниже, сочетание элементов dwNameSpace и lpNSProviderId определяет, что эта функция влияет на поставщиков пространств имен.

dwNameSpace	lpNSProviderId	Область влияния
Не учитывается	Отличное от NULL	Указанный поставщик пространства имен.
Допустимый идентификатор пространства имени	Null	Все поставщики пространства имен, поддерживающие указанное пространство имен.
NS_ALL	Null	Все поставщики пространства имен.

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

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

Примечание

Заголовок winsock2.h определяет WSASetService в качестве псевдонима, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОД. Использование псевдонима, не зависящий от кодирования, с кодом, который не является нейтральным для кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или времени выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.

Требования

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