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

[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

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

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

Большинство вызовов 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

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

[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, который возвращает следующее расширенное значение ошибки.

Комментарии

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

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

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

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

Требования

См. также раздел

CSADDR_INFO

Функции Winsock

Справочник по Winsock

getaddrinfo

Gethostbyname