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

Статья
03/15/2023

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

Функция 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. При необходимости это может получить доступ к привязке 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".

Параметр lpServiceNameNULL эквивалентен параметру dwResolution значение RES_SERVICE. Функция работает во втором режиме, получая локальный адрес, к которому должна привязаться служба указанного типа. Функция сохраняет локальный адрес в localAddr член структуры CSADDR_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 является минимальным обязательным размером буфера.

Если lpAliasBufferNULL, lpdwAliasBufferLength бессмысленно, а также может быть NULL.

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

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

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

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

Замечания

Эта функция является более мощной версией функции gethostbyname. Функция GetAddressByName работает с несколькими службами имен.

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

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

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

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

Заметка

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

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows 2000 Профессиональный [только классические приложения]
минимальный поддерживаемый сервер	Windows 2000 Server [только классические приложения]
целевая платформа	Виндоус
заголовка	nspapi.h
библиотеки	Mswsock.lib
DLL	Mswsock.dll

См. также

Справочник Winsock

Поделиться через