Edit

ParseNetworkString function (iphlpapi.h)

  • Article

The ParseNetworkString function parses the input network string and checks whether it is a legal representation of the specified IP network string type. If the string matches a type and its specification, the function can optionally return the parsed result.

Syntax

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
);

Parameters

[in] NetworkString

A pointer to the NULL-terminated network string to parse.

[in] Types

The type of IP network string to parse. This parameter consists of one of network string types as defined in the Iphlpapi.h header file.

Value Meaning
NET_STRING_IPV4_ADDRESS
0x00000001
 The NetworkString parameter points to an IPv4 address using Internet standard dotted-decimal notation. A network port or prefix must not be present in the network string.

An example network string is the following:

192.168.100.10
NET_STRING_IPV4_SERVICE
0x00000002
 The NetworkString parameter points to an IPv4 service using Internet standard dotted-decimal notation. A network port is required as part of the network string. A prefix must not be present in the network string.

An example network string is the following:

192.168.100.10:80
NET_STRING_IPV4_NETWORK
0x00000004
 The NetworkString parameter points to an IPv4 network using Internet standard dotted-decimal notation. A network prefix that uses the Classless Inter-Domain Routing (CIDR) notation is required as part of the network string. A network port must not be present in the network string.

An example network string is the following:

192.168.100/24
NET_STRING_IPV6_ADDRESS
0x00000008
 The NetworkString parameter points to an IPv6 address using Internet standard hexadecimal encoding. An IPv6 scope ID may be present in the network string. A network port or prefix must not be present in the network string.

An example network string is the following:

21DA:00D3:0000:2F3B:02AA:00FF:FE28:9C5A%2
NET_STRING_IPV6_ADDRESS_NO_SCOPE
0x00000008
 The NetworkString parameter points to an IPv6 address using Internet standard hexadecimal encoding. An IPv6 scope ID must not be present in the network string. A network port or prefix must not be present in the network string.

An example network string is the following:

21DA:00D3:0000:2F3B:02AA:00FF:FE28:9C5A
NET_STRING_IPV6_SERVICE
0x00000020
 The NetworkString parameter points to an IPv6 service using Internet standard hexadecimal encoding. A network port is required as part of the network string. An IPv6 scope ID may be present in the network string. A prefix must not be present in the network string.

An example network string with a scope ID is the following:

[21DA:00D3:0000:2F3B:02AA:00FF:FE28:9C5A%2]:8080
NET_STRING_IPV6_SERVICE_NO_SCOPE
0x00000040
 The NetworkString parameter points to an IPv6 service using Internet standard hexadecimal encoding. A network port is required as part of the network string. An IPv6 scope ID must not be present in the network string. A prefix must not be present in the network string.

An example network string is the following:

21DA:00D3:0000:2F3B:02AA:00FF:FE28:9C5A:8080
NET_STRING_IPV6_NETWORK
0x00000080
 The NetworkString parameter points to an IPv6 network using Internet standard hexadecimal encoding. A network prefix in CIDR notation is required as part of the network string. A network port or scope ID must not be present in the network string.

An example network string is the following:

21DA:D3::/48
NET_STRING_NAMED_ADDRESS
0x00000100
 The NetworkString parameter points to an Internet address using a Domain Name System (DNS) name. A network port or prefix must not be present in the network string.

An example network string is the following:

www.microsoft.com
NET_STRING_NAMED_SERVICE
0x00000200
 The NetworkString parameter points to an Internet service using a DNS name. A network port must be present in the network string.

An example network string is the following:

www.microsoft.com:80
NET_STRING_IP_ADDRESS
0x00000009
 The NetworkString parameter points to an IPv4 address using Internet standard dotted-decimal notation or an IPv6 address using the Internet standard hexadecimal encoding. An IPv6 scope ID may be present in the network string. A network port or prefix must not be present in the network string.

This type matches either the NET_STRING_IPV4_ADDRESS or NET_STRING_IPV6_ADDRESS types.
NET_STRING_IP_ADDRESS_NO_SCOPE
0x00000011
 The NetworkString parameter points to an IPv4 address using Internet standard dotted-decimal notation or an IPv6 address using Internet standard hexadecimal encoding. An IPv6 scope ID must not be present in the network string. A network port or prefix must not be present in the network string.

This type matches either the NET_STRING_IPV4_ADDRESS or NET_STRING_IPV6_ADDRESS_NO_SCOPE types.
NET_STRING_IP_SERVICE
0x00000022
 The NetworkString parameter points to an IPv4 service or IPv6 service. A network port is required as part of the network string. An IPv6 scope ID may be present in the network string. A prefix must not be present in the network string.

This type matches either the NET_STRING_IPV4_SERVICE or NET_STRING_IPV6_SERVICE types.
NET_STRING_IP_SERVICE_NO_SCOPE
0x00000042
 The NetworkString parameter points to an IPv4 service or IPv6 service. A network port is required as part of the network string. An IPv6 scope ID must not be present in the network string. A prefix must not be present in the network string.

This type matches either the NET_STRING_IPV4_SERVICE or NET_STRING_IPV6_SERVICE_NO_SCOPE types.
NET_STRING_IP_NETWORK
0x00000084
 The NetworkString parameter points to an IPv4 or IPv6 network. A network prefix in CIDR notation is required as part of the network string. A network port or scope ID must not be present in the network.

This type matches either the NET_STRING_IPV4_NETWORK or NET_STRING_IPV6_NETWORK types.
NET_STRING_ANY_ADDRESS
0x00000209
 The NetworkString parameter points to an IPv4 address in Internet standard dotted-decimal notation, an IPv6 address in Internet standard hexadecimal encoding, or a DNS name. An IPv6 scope ID may be present in the network string for an IPv6 address. A network port or prefix must not be present in the network string.

This type matches either the NET_STRING_NAMED_ADDRESS or NET_STRING_IP_ADDRESS types.
NET_STRING_ANY_ADDRESS_NO_SCOPE
0x00000211
 The NetworkString parameter points to an IPv4 address in Internet standard dotted-decimal notation, an IPv6 address in Internet standard hexadecimal encoding, or a DNS name. An IPv6 scope ID must not be present in the network string for an IPv6 address. A network port or prefix must not be present in the network string.

This type matches either the NET_STRING_NAMED_ADDRESS or NET_STRING_IP_ADDRESS_NO_SCOPE types.
NET_STRING_ANY_SERVICE
0x00000222
 The NetworkString parameter points to an IPv4 service or IPv6 service using IP address notation or a DNS name. A network port is required as part of the network string. An IPv6 scope ID may be present in the network string. A prefix must not be present in the network string.

This type matches either the NET_STRING_NAMED_SERVICE or NET_STRING_IP_SERVICE types.
NET_STRING_ANY_SERVICE_NO_SCOPE
0x00000242
 The NetworkString parameter points to an IPv4 service or IPv6 service using IP address notation or a DNS name. A network port is required as part of the network string. An IPv6 scope ID must not be present in the network string. A prefix must not be present in the network string.

This type matches either the NET_STRING_NAMED_SERVICE or NET_STRING_IP_SERVICE_NO_SCOPE types.

[out, optional] AddressInfo

On success, the function returns a pointer to a NET_ADDRESS_INFO structure that contains the parsed IP address information if a NULL pointer was not passed in this parameter.

[out, optional] PortNumber

On success, the function returns a pointer to the parsed network port in host order if a NULL pointer was not passed in this parameter. If a network port was not present in the NetworkString parameter, then a pointer to a value of zero is returned.

[out, optional] PrefixLength

On success, the function returns a pointer to the parsed prefix length if a NULL pointer was not passed in this parameter. If a prefix was not present in the NetworkString parameter, then a pointer to a value of -1 is returned.

Return value

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is one of the following error codes.

Return code Description
ERROR_INSUFFICIENT_BUFFER
 The buffer passed to the function is too small. This error is returned if the buffer pointed to by the AddressInfo parameter is too small to hold the parsed network address.
ERROR_INVALID_PARAMETER
 An invalid parameter was passed to the function. This error is returned if a NULL pointer is passed in the NetworkString parameter

Remarks

The ParseNetworkString function parses the input network string passed in the NetworkString parameter and checks whether it is a legal representation of one of the string types as specified in the Types argument. If the string matches a type and its specification, the function succeeds and can optionally return the parsed result to the caller in the optional AddressInfo, PortNumber, and PrefixLength parameters when these parameters are not NULL pointers.

The ParseNetworkString function can parse representations of IPv4 or IPv6 addresses, services, and networks, as well as named Internet addresses and services using DNS names.

The NET_ADDRESS_INFO structure pointed to by the AddressInfo parameter. The SOCKADDR_IN and SOCKADDR structures are defined in the Ws2def.h header file which is automatically included by the Winsock2.h header file. The SOCKADDR_IN6 structure is defined in the Ws2ipdef.h header file which is automatically included by the Ws2tcpip.h header file. In order to use the ParseNetworkString function and the NET_ADDRESS_INFO structure, the Winsock2.h and Ws2tcpip.h header files must be included before the Iphlpapi.h header file.

Requirements

Requirement Value
Minimum supported client Windows Vista [desktop apps only]
Minimum supported server Windows Server 2008 [desktop apps only]
Target Platform Windows
Header iphlpapi.h
Library Iphlpapi.lib
DLL Iphlpapi.dll

See also

NET_ADDRESS_FORMAT

NET_ADDRESS_INFO

SOCKADDR

SOCKADDR_IN

SOCKADDR_IN6