ParseNetworkString function (Windows)

Applies to: desktop apps only

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

DWORD WINAPI ParseNetworkString(
  __in       const WCHAR *NetworkString,
  __in       DWORD Types,
  __out_opt  PNET_ADDRESS_INFO AddressInfo,
  __out_opt  USHORT *PortNumber,
  __out_opt  BYTE *PrefixLength
);

Parameters

NetworkString [in]

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

Types [in]

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.

 

AddressInfo [out, optional]

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.

PortNumber [out, optional]

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.

PrefixLength [out, optional]

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.

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 SOCKADDR_IN, SOCKADDR_IN6, and SOCKADDR structures are used in 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

See also

NET_ADDRESS_FORMAT

NET_ADDRESS_INFO

SOCKADDR

SOCKADDR_IN

SOCKADDR_IN6

Send comments about this topic to Microsoft

Build date: 2/3/2012