Функция ParseNetworkString (iphlpapi.h)

Статья
08/24/2023

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

Синтаксис

IPHLPAPI_DLL_LINKAGE DWORD ParseNetworkString(
  [in]            const WCHAR       *NetworkString,
  [in]            DWORD             Types,
  [out, optional] PNET_ADDRESS_INFO AddressInfo,
  [out, optional] USHORT            *PortNumber,
  [out, optional] BYTE              *PrefixLength
);

Параметры

[in] NetworkString

Указатель на сетевую строку, завершаемую значением NULL, для анализа.

[in] Types

Тип строки IP-сети для анализа. Этот параметр состоит из одного из типов сетевых строк, определенных в файле заголовка Iphlpapi.h .

Значение	Значение
NET_STRING_IPV4_ADDRESS 0x00000001	Параметр NetworkString указывает на IPv4-адрес, используя стандартную десятичную нотацию с точками в Интернете. Сетевой порт или префикс не может быть представлен в строке сетевого адреса. Пример сетевой строки: 192.168.100.10
NET_STRING_IPV4_SERVICE 0x00000002	Параметр NetworkString указывает на службу IPv4, используя стандартную десятичную нотацию с точками в Интернете. Сетевой порт требуется как часть сетевой строки. Префикс не должен присутствовать в строке сети. Пример сетевой строки: 192.168.100.10:80
NET_STRING_IPV4_NETWORK 0x00000004	Параметр NetworkString указывает на сеть IPv4, используя стандартную десятичную нотацию с точками в Интернете. Сетевой префикса, который использует нотацию CIDR, должен быть частью строки сетевого адреса. Сетевой порт не может быть представлен в строке сетевого адреса. Пример сетевой строки: 192.168.100/24
NET_STRING_IPV6_ADDRESS 0x00000008	Параметр NetworkString указывает на IPv6-адрес с использованием стандартной шестнадцатеричной кодировки Интернета. Идентификатор области IPv6 может присутствовать в строке сетевого адреса. Сетевой порт или префикс не может быть представлен в строке сетевого адреса. Пример сетевой строки: 21DA:00D3:0000:2F3B:02AA:00FF:FE28:9C5A%2
NET_STRING_IPV6_ADDRESS_NO_SCOPE 0x00000008	Параметр NetworkString указывает на IPv6-адрес с использованием стандартной шестнадцатеричной кодировки Интернета. Идентификатор область IPv6 не должен присутствовать в строке сети. Сетевой порт или префикс не может быть представлен в строке сетевого адреса. Пример сетевой строки: 21DA:00D3:0000:2F3B:02AA:00FF:FE28:9C5A
NET_STRING_IPV6_SERVICE 0x00000020	Параметр NetworkString указывает на службу IPv6 с использованием стандартной шестнадцатеричной кодировки Интернета. Сетевой порт требуется как часть сетевой строки. Идентификатор области IPv6 может присутствовать в строке сетевого адреса. Префикс не должен присутствовать в строке сети. Ниже приведен пример строки сети с идентификатором область: [21DA:00D3:0000:2F3B:02AA:00FF:FE28:9C5A%2]:8080
NET_STRING_IPV6_SERVICE_NO_SCOPE 0x00000040	Параметр NetworkString указывает на службу IPv6 с использованием стандартной шестнадцатеричной кодировки Интернета. Сетевой порт требуется как часть сетевой строки. Идентификатор область IPv6 не должен присутствовать в строке сети. Префикс не должен присутствовать в строке сети. Пример сетевой строки: 21DA:00D3:0000:2F3B:02AA:00FF:FE28:9C5A:8080
NET_STRING_IPV6_NETWORK 0x00000080	Параметр NetworkString указывает на сеть IPv6 с использованием стандартной шестнадцатеричной кодировки Интернета. Префикс сети в нотации CIDR является частью строки сетевого адреса. Сетевой порт или ИД области действия не может быть представлен в строке сетевого адреса. Пример сетевой строки: 21DA:D3::/48
NET_STRING_NAMED_ADDRESS 0x00000100	Параметр NetworkString указывает на интернет-адрес, используя dns-имя. Сетевой порт или префикс не может быть представлен в строке сетевого адреса. Пример сетевой строки: www.microsoft.com
NET_STRING_NAMED_SERVICE 0x00000200	Параметр NetworkString указывает на интернет-службу, используя DNS-имя. В строке сети должен присутствовать сетевой порт. Пример сетевой строки: www.microsoft.com:80
NET_STRING_IP_ADDRESS 0x00000009	Параметр NetworkString указывает на IPv4-адрес, использующий стандартную десятичную нотацию с точками в Интернете или IPv6-адрес, использующий стандартную шестнадцатеричную кодировку Интернета. Идентификатор области IPv6 может присутствовать в строке сетевого адреса. Сетевой порт или префикс не может быть представлен в строке сетевого адреса. Этот тип соответствует типам NET_STRING_IPV4_ADDRESS или NET_STRING_IPV6_ADDRESS .
NET_STRING_IP_ADDRESS_NO_SCOPE 0x00000011	Параметр NetworkString указывает на IPv4-адрес, использующий стандартную десятичную нотацию Интернета, или IPv6-адрес, использующий стандартную шестнадцатеричную кодировку Интернета. Идентификатор область IPv6 не должен присутствовать в строке сети. Сетевой порт или префикс не может быть представлен в строке сетевого адреса. Этот тип соответствует типам NET_STRING_IPV4_ADDRESS или NET_STRING_IPV6_ADDRESS_NO_SCOPE .
NET_STRING_IP_SERVICE 0x00000022	Параметр NetworkString указывает на службу IPv4 или службу IPv6. Сетевой порт требуется как часть сетевой строки. Идентификатор области IPv6 может присутствовать в строке сетевого адреса. Префикс не должен присутствовать в строке сети. Этот тип соответствует типам NET_STRING_IPV4_SERVICE или NET_STRING_IPV6_SERVICE .
NET_STRING_IP_SERVICE_NO_SCOPE 0x00000042	Параметр NetworkString указывает на службу IPv4 или службу IPv6. Сетевой порт требуется как часть сетевой строки. Идентификатор область IPv6 не должен присутствовать в строке сети. Префикс не должен присутствовать в строке сети. Этот тип соответствует типам NET_STRING_IPV4_SERVICE или NET_STRING_IPV6_SERVICE_NO_SCOPE .
NET_STRING_IP_NETWORK 0x00000084	Параметр NetworkString указывает на сеть IPv4 или IPv6. Префикс сети в нотации CIDR является частью строки сетевого адреса. В сети не должно быть сетевого порта или идентификатора область. Этот тип соответствует типам NET_STRING_IPV4_NETWORK или NET_STRING_IPV6_NETWORK .
NET_STRING_ANY_ADDRESS 0x00000209	Параметр NetworkString указывает на IPv4-адрес в стандартной десятичной нотации Интернета с точками, IPv6-адрес в стандартной шестнадцатеричной кодировке Интернета или DNS-имя. Идентификатор область IPv6 может присутствовать в строке сети для IPv6-адреса. Сетевой порт или префикс не может быть представлен в строке сетевого адреса. Этот тип соответствует типам NET_STRING_NAMED_ADDRESS или NET_STRING_IP_ADDRESS .
NET_STRING_ANY_ADDRESS_NO_SCOPE 0x00000211	Параметр NetworkString указывает на IPv4-адрес в стандартной десятичной нотации Интернета с точками, IPv6-адрес в стандартной шестнадцатеричной кодировке Интернета или DNS-имя. Идентификатор область IPv6 не должен присутствовать в строке сети для IPv6-адреса. Сетевой порт или префикс не может быть представлен в строке сетевого адреса. Этот тип соответствует типам NET_STRING_NAMED_ADDRESS или NET_STRING_IP_ADDRESS_NO_SCOPE .
NET_STRING_ANY_SERVICE 0x00000222	Параметр NetworkString указывает на службу IPv4 или службу IPv6, используя нотацию IP-адреса или DNS-имя. Сетевой порт требуется как часть сетевой строки. Идентификатор области IPv6 может присутствовать в строке сетевого адреса. Префикс не должен присутствовать в строке сети. Этот тип соответствует типам NET_STRING_NAMED_SERVICE или NET_STRING_IP_SERVICE .
NET_STRING_ANY_SERVICE_NO_SCOPE 0x00000242	Параметр NetworkString указывает на службу IPv4 или службу IPv6, используя нотацию IP-адреса или DNS-имя. Сетевой порт требуется как часть сетевой строки. Идентификатор область IPv6 не должен присутствовать в строке сети. Префикс не должен присутствовать в строке сети. Этот тип соответствует типам NET_STRING_NAMED_SERVICE или NET_STRING_IP_SERVICE_NO_SCOPE .

[out, optional] AddressInfo

При успешном выполнении функция возвращает указатель на структуру NET_ADDRESS_INFO , содержащую проанализированные сведения об IP-адресе, если в этом параметре не был передан указатель NULL .

[out, optional] PortNumber

При успешном выполнении функция возвращает указатель на проанализированный сетевой порт в порядке узла, если в этом параметре не был передан указатель NULL . Если сетевой порт отсутствует в параметре NetworkString , возвращается указатель на нулевое значение.

[out, optional] PrefixLength

При успешном выполнении функция возвращает указатель на проанализированную длину префикса, если в этом параметре не был передан указатель NULL . Если префикс отсутствует в параметре NetworkString , возвращается указатель на значение -1.

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

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

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

Код возврата	Описание
ERROR_INSUFFICIENT_BUFFER	Буфер, передаваемый в функцию, слишком мал. Эта ошибка возвращается, если буфер, на который указывает параметр AddressInfo , слишком мал для хранения проанализированного сетевого адреса.
ERROR_INVALID_PARAMETER	В функцию передан недопустимый параметр. Эта ошибка возвращается, если в параметре NetworkString передается указатель NULL.

Функция ParseNetworkString анализирует входную сетевую строку, переданную в параметре NetworkString , и проверяет, является ли она законным представлением одного из строковых типов, как указано в аргументе Types . Если строка соответствует типу и его спецификации, функция выполняется успешно и при необходимости может вернуть проанализированный результат вызывающему объекту в необязательных параметрах AddressInfo, PortNumber и PrefixLength , если эти параметры не являются указателями NULL .

Функция ParseNetworkString может анализировать представления IPv4- или IPv6-адресов, служб и сетей, а также именованных интернет-адресов и служб с помощью DNS-имен.

Структура NET_ADDRESS_INFO , на которую указывает параметр AddressInfo . Структуры SOCKADDR_IN и SOCKADDR определяются в файле заголовка Ws2def.h , который автоматически включается в файл заголовка Winsock2.h . Структура SOCKADDR_IN6 определяется в файле заголовка Ws2ipdef.h , который автоматически включается в файл заголовка Ws2tcpip.h . Чтобы использовать функцию ParseNetworkString и структуру NET_ADDRESS_INFO , файлы заголовков Winsock2.h и Ws2tcpip.h должны быть включены перед файлом заголовка Iphlpapi.h .

Требования


Минимальная версия клиента	Windows Vista [только классические приложения]
Минимальная версия сервера	Windows Server 2008 [только классические приложения]
Целевая платформа	Windows
Header	iphlpapi.h
Библиотека	Iphlpapi.lib
DLL	Iphlpapi.dll