Функция GetServiceA (nspapi.h)

Статья
08/25/2023

Функция GetService извлекает сведения о сетевой службе в контексте набора пространств имен по умолчанию или указанного пространства имен. Сетевая служба указывается по ее типу и имени. Сведения о службе получаются в виде набора NS_SERVICE_INFO структур данных.

Примечание Функция GetService — это специальное расширение Корпорации Майкрософт для спецификации Windows Sockets 1.1. Эта функция является устаревшей. Для удобства разработчиков Windows Sockets 1.1 этот справочный материал включен.

Примечание Функции, описанные в разделе Разрешение имен, независимых от протокола , предоставляют эквивалентные функции в сокетах Windows 2.

Синтаксис

INT GetServiceA(
  [in]           DWORD                dwNameSpace,
  [in]           LPGUID               lpGuid,
  [in]           LPSTR                lpServiceName,
  [in]           DWORD                dwProperties,
  [out]          LPVOID               lpBuffer,
  [in, out]      LPDWORD              lpdwBufferSize,
  [in, optional] LPSERVICE_ASYNC_INFO lpServiceAsyncInfo
);

Параметры

[in] dwNameSpace

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

Используйте одну из следующих констант, чтобы указать пространство имен.

Значение	Значение
NS_DEFAULT	Набор пространств имен по умолчанию. Операционная система запрашивает каждое пространство имен в этом наборе. Набор пространств имен по умолчанию обычно включает все пространства имен, установленные в системе. Однако системные администраторы могут исключить определенные пространства имен из набора. NS_DEFAULT — это значение, которое большинство приложений должны использовать для dwNameSpace.
NS_DNS	Система доменных имен, используемая в Интернете для разрешения имен узлов.
NS_NETBT	Уровень NetBIOS через TCP/IP. Все операционные системы регистрируют свои имена компьютеров в NetBIOS. Это пространство имен используется для разрешения имени компьютера в IP-адрес с помощью этой регистрации. Обратите внимание, что NS_NETBT могут получить доступ к WINS-серверу для выполнения разрешения.
NS_SAP	Протокол NetWare Service Advertising. При необходимости он может получить доступ к привязке NetWare. NS_SAP — это динамическое пространство имен, позволяющее регистрирование служб.
NS_TCPIP_HOSTS	Ищет имена узлов и IP-адреса в <файле systemroot>\system32\drivers\etc\hosts.
NS_TCPIP_LOCAL	Локальные механизмы разрешения имен TCP/IP, включая сравнение с именем локального узла и поиск имен узлов и IP-адресов в кэше сопоставлений между узлами и IP-адресами.

Большинство вызовов GetService должны использовать специальное значение NS_DEFAULT. Это позволяет клиенту обойтись без сведений о доступных пространствах имен в интернете. Системный администратор определяет доступ к пространству имен. Пространства имен могут приходить и уходить без необходимости знать об изменениях.

[in] lpGuid

Указатель на глобальный уникальный идентификатор (GUID), указывающий тип сетевой службы. Файл заголовка Svcguid.h содержит типы служб GUID из многих известных служб в пространствах имен DNS и SAP.

Файл заголовка Svcguid.h не включается автоматически в файл заголовка Winsock2.h .

[in] lpServiceName

Указатель на строку, завершающуюся с нуля, которая уникально представляет имя службы. Например, "MY SNA SERVER".

[in] dwProperties

Набор битовых флагов, указывающих сведения о службе, извлекаемые функцией. Каждая из этих констант битового флага, кроме PROP_ALL, соответствует определенному члену структуры данных SERVICE_INFO . Если флаг установлен, функция помещает сведения в соответствующий член структур данных, хранящихся в *lpBuffer. Определены следующие битовые флаги.

Значение	Значение
PROP_COMMENT	Если этот флаг установлен, функция сохраняет данные в элементе lpComment структур данных, хранящихся в *lpBuffer.
PROP_LOCALE	Если этот флаг установлен, функция сохраняет данные в элементе lpLocale структур данных, хранящихся в *lpBuffer.
PROP_DISPLAY_HINT	Если этот флаг установлен, функция сохраняет данные в элементе dwDisplayHint структур данных, хранящихся в *lpBuffer.
PROP_VERSION	Если этот флаг установлен, функция сохраняет данные в элементе dwVersion структур данных, хранящихся в *lpBuffer.
PROP_START_TIME	Если этот флаг установлен, функция сохраняет данные в элементе dwTime структур данных, хранящихся в *lpBuffer.
PROP_MACHINE	Если этот флаг установлен, функция сохраняет данные в элементе lpMachineName структур данных, хранящихся в *lpBuffer.
PROP_ADDRESSES	Если этот флаг установлен, функция сохраняет данные в элементе lpServiceAddress структур данных, хранящихся в *lpBuffer.
PROP_SD	Если этот флаг установлен, функция сохраняет данные в элементе ServiceSpecificInfo структур данных, хранящихся в *lpBuffer.
PROP_ALL	Если этот флаг установлен, функция сохраняет данные во всех членах структур данных, хранящихся в *lpBuffer.

[out] lpBuffer

Указатель на буфер для получения массива NS_SERVICE_INFO структур и связанных сведений о службе. Каждая структура NS_SERVICE_INFO содержит сведения о службе в контексте определенного пространства имен. Обратите внимание, что если dwNameSpace NS_DEFAULT, функция сохраняет несколько структур в буфере; В противном случае сохраняется только одна структура.

Каждая структура NS_SERVICE_INFO содержит SERVICE_INFO структуру. Члены этих SERVICE_INFO структур будут содержать допустимые данные на основе битовых флагов, заданных в параметре dwProperties . Если соответствующий битовый флаг элемента не задан в dwProperties, значение элемента не определено.

Функция сохраняет NS_SERVICE_INFO структуры в последовательном массиве, начиная с начала буфера. Указатели в структурах SERVICE_INFO указывают на сведения, хранящиеся в буфере между концом NS_SERVICE_INFO структур и концом буфера.

[in, out] lpdwBufferSize

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

[in, optional] lpServiceAsyncInfo

Зарезервировано для последующего использования. Необходимо задать значение NULL.

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

Если функция выполнена успешно, возвращаемое значение — это количество NS_SERVICE_INFO структур, хранящихся в *lpBuffer. Ноль означает, что структуры не были сохранены.

Если функция завершается сбоем, возвращается значение SOCKET_ERROR ( – 1). Чтобы получить расширенные сведения об ошибке, вызовите Метод GetLastError, который возвращает одно из следующих расширенных значений ошибки.

Код ошибки	Значение
ERROR_INSUFFICIENT_BUFFER	Буфер, на который указывает lpBuffer, слишком мал для получения всей запрошенной информации. Вызовите функцию с буфером по крайней мере равным значению, возвращаемого в *lpdwBufferSize.
ERROR_SERVICE_NOT_FOUND	Указанная служба не найдена или указанное пространство имен не используется. В этом случае возвращаемое значение функции равно нулю.

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

Требования

Требование	Значение
Минимальная версия клиента	Windows 2000 Professional [только классические приложения]
Минимальная версия сервера	Windows 2000 Server [только классические приложения]
Целевая платформа	Windows
Header	nspapi.h
Библиотека	Mswsock.lib
DLL	Mswsock.dll