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

Статья
03/15/2023

[GetAddressByName больше недоступен для использования с сокетов Windows 2. Вместо этого используйте функции, описанные в разделе Разрешение имен, независимых от протокола.]

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

Синтаксис

INT GetAddressByNameA(
  [in]           DWORD                dwNameSpace,
  [in]           LPGUID               lpServiceType,
  [in, optional] LPSTR                lpServiceName,
  [in, optional] LPINT                lpiProtocols,
  [in]           DWORD                dwResolution,
  [in, optional] LPSERVICE_ASYNC_INFO lpServiceAsyncInfo,
  [out]          LPVOID               lpCsaddrBuffer,
  [in, out]      LPDWORD              lpdwBufferLength,
  [in, out]      LPSTR                lpAliasBuffer,
  [in, out]      LPDWORD              lpdwAliasBufferLength
);

Параметры

[in] dwNameSpace

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

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

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

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

[in] lpServiceType

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

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

[in, optional] lpServiceName

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

Присвоение lpServiceNameзначения NULL эквивалентно установке dwResolution на RES_SERVICE. Функция работает во втором режиме, получая локальный адрес, к которому должна привязаться служба указанного типа. Функция сохраняет локальный адрес в члене LocalAddrCSADDR_INFO структур, хранящихся в *lpCsaddrBuffer.

Если параметр dwResolution имеет значение RES_SERVICE, функция игнорирует параметр lpServiceName .

Если для dwNameSpace задано значение NS_DNS, *lpServiceName — это имя узла.

[in, optional] lpiProtocols

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

Если для lpiProtocols задано значение NULL, функция извлекает сведения обо всех доступных протоколах.

[in] dwResolution

Набор битовых флагов, указывающих аспекты процесса разрешения имен служб. Определены следующие битовые флаги.

Значение	Значение
RES_SERVICE	Если задано значение , функция получает адрес, к которому должна привязаться служба указанного типа. Это эквивалентно присвоению параметру lpServiceNameзначения NULL. Если этот флаг не задан, происходит обычное разрешение имен.
RES_FIND_MULTIPLE	Если этот флаг установлен, операционная система выполняет расширенный поиск всех пространств имен службы. Он запрашивает каждое соответствующее пространство имен для разрешения имени службы. Если этот флаг не установлен, операционная система перестает искать адреса службы сразу после их обнаружения.
RES_SOFT_SEARCH	Этот флаг действителен, если пространство имен поддерживает несколько уровней поиска. Если этот флаг действителен и установлен, операционная система выполняет простой и быстрый поиск пространства имен. Это полезно, если приложению требуется только легко найти адреса для службы. Если этот флаг является допустимым и четким, операционная система выполняет более обширный поиск пространства имен.

Значение

RES_SERVICE

Если задано значение , функция получает адрес, к которому должна привязаться служба указанного типа. Это эквивалентно присвоению параметру lpServiceNameзначения NULL.

Если этот флаг не задан, происходит обычное разрешение имен.

RES_FIND_MULTIPLE

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

RES_SOFT_SEARCH

Этот флаг действителен, если пространство имен поддерживает несколько уровней поиска.

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

Если этот флаг является допустимым и четким, операционная система выполняет более обширный поиск пространства имен.

[in, optional] lpServiceAsyncInfo

Зарезервировано для использования в будущем; Для параметра должно быть задано значение NULL.

[out] lpCsaddrBuffer

Указатель на буфер для получения одной или нескольких CSADDR_INFO структур данных. Количество структур, записанных в буфер, зависит от объема информации, найденной при попытке разрешения. Следует предположить, что будет записано несколько структур, хотя во многих случаях будет только одна.

[in, out] lpdwBufferLength

Указатель на переменную, которая при входе указывает размер буфера, на который указывает lpCsaddrBuffer, в байтах.

После вывода эта переменная содержит общее количество байтов, необходимых для хранения массива CSADDR_INFO структур. Если это значение меньше или равно входное значение *lpdwBufferLength и функция выполнена успешно, это число байтов, фактически хранящихся в буфере. Если это значение больше входного значения *lpdwBufferLength, буфер был слишком мал, а выходное значение *lpdwBufferLength — минимальный требуемый размер буфера.

[in, out] lpAliasBuffer

Указатель на буфер для получения сведений о псевдониме для сетевой службы.

Если пространство имен поддерживает псевдонимы, функция сохраняет массив строк имен с нулевым завершением в буфер, на который указывает lpAliasBuffer. В конце списка имеется двойной признак конца с нулевым значением. Первое имя в массиве — это основное имя службы. Следующие имена являются псевдонимами. Примером пространства имен, поддерживающего псевдонимы, является DNS.

Если пространство имен не поддерживает псевдонимы, оно сохраняет в буфере двойной признак конца с нулевым значением.

Этот параметр является необязательным и может иметь значение NULL.

[in, out] lpdwAliasBufferLength

Указатель на переменную, которая при входе указывает размер буфера в элементах (символах), на который указывает lpAliasBuffer.

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

Если lpAliasBuffer имеет значение NULL, lpdwAliasBufferLength не имеет смысла и может иметь значение NULL.

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

Если функция выполняется успешно, возвращаемое значение — это количество CSADDR_INFO структур данных, записанных в буфер, на который указывает lpCsaddrBuffer.

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

Код ошибки	Значение
ERROR_INSUFFICIENT_BUFFER	Буфер, на который указывает lpCsaddrBuffer , был слишком мал для получения всех соответствующих CSADDR_INFO структур. Вызовите функцию с буфером, по крайней мере равным значению, возвращаемого в *lpdwBufferLength.

Примечание Функция gethostbyname стала нерекомендуемой из-за введения функции getaddrinfo . Разработчикам, создающих приложения Windows Sockets 2, рекомендуется использовать функцию getaddrinfo вместо gethostbyname.

Функция GetAddressByName позволяет клиенту получить адрес сокетов Windows для сетевой службы. Клиент указывает интересующую службу по типу службы и имени службы.

Многие службы имен поддерживают префикс или суффикс по умолчанию, которые поставщик служб имен учитывает при разрешении имен служб. Например, если в пространстве имен DNS домен называется "nt.microsoft.com", а в качестве входных данных указан ftp millikan, программное обеспечение DNS не сможет разрешить "millikan", но успешно разрешает "millikan.nt.microsoft.com".

Обратите внимание, что функция GetAddressByName может искать адрес службы двумя способами: в определенном пространстве имен или в наборе пространств имен по умолчанию. Используя пространство имен по умолчанию, администратор может указать, что определенные пространства имен будут искать адреса служб, только если они указаны по имени. Администратор или программа установки пространства имен также может управлять порядком поиска по пространствам имен.

Примечание

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

Требования

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