IP Address Programming

The following sections provide sample code describing how to manipulate IP address (IPv4 and IPv6).

Include Files

Wherever you want to manipulate IP address, you should include one or many of these files:

Include file	Description
IP/IPv4/net_ipv4.h	Functions used for IPv4 API.
IP/IPv6/net_ipv6.h	Functions used for IPv6 API.
Souce/net_ascii.h	Functions and Macro used for conversion utilities API.

Configuration

Some parameters should be configured and/or optimized for your project requirements. Please refer to sections IPv4 Layer Configuration and IPv6 Layer Configuration for further details.

API Reference

IP Address Configuration Functions

Those functions are related to the configuration and removal of IP address on an Interface.

Function name	Description
IPv4
`NetIPv4_CfgAddrAdd`	Add a statically-configured IPv4 host address, subnet mask, and default gateway to an interface.
`NetIPv4_CfgAddrRemove`	Remove a configured IPv4 host address from an interface.
`NetIPv4_CfgAddrRemoveAll`	Remove all configured IPv4 host address(es) from an interface.
IPv6
`NetIPv6_AddrAutoCfgEn`	Enable the IPv6 Stateless Address Auto-Configuration procedure.
`NetIPv6_AddrAutoCfgDis`	Disable the IPv6 Stateless Address Auto-Configuration procedure.
`NetIPv6_AddrAutoCfgHookSet`	Set the hook function to received the IPv6 Stateless Address Auto-Configuration process result.
`NetIPv6_CfgAddrAdd`	Add a statically-configured IPv6 host address to an interface.
`NetIPv6_CfgAddrHookSet`	Set the hook function to received the IPv6 Static Address Configuration process result.
`NetIPv6_CfgAddrRemove`	Remove a configured IPv6 host address & multicast solicited mode address from an interface.
`NetIPv6_CfgAddrRemoveAll`	Remove all configured IPv6 host address(es) from an interface.

Interface Configured IP Address Functions

Those functions are associated to information on interface configured IP address.

Function Name	Description
IPv4
`NetIPv4_GetAddrHost`	Get an interface’s configured IPv4 host address(es).
`NetIPv4_GetAddrSrc`	Get corresponding configured IPv4 host address to use as source address for a remote IPv4 address.
`NetIPv4_GetAddrDfltGateway`	Get the default gateway IPv4 address for a host’s configured IPv4 address.
`NetIPv4_GetAddrSubnetMask`	Get the IPv4 address subnet mask for a host’s configured IPv4 address.
`NetIPv4_IsAddrHost`	Validate an IPv4 address as one the host’s IPv4 address(es).
`NetIPv4_IsAddrHostCfgd()`	Validate an IPv4 address as one the host’s configured IPv4 address(es).
`NetIPv4_IsAddrsHostCfgdOnIF()`	Check if any IPv4 address(es) are configured on an interface.
IPv6
`NetIPv6_GetAddrHost`	Get an interface's configured IPv6 host address(es).
`NetIPv6_GetAddrSrc`	Find the best matched source address in the IPv6 configured host addresses for the specified destination address.
`NetIPv6_IsAddrHostCfgd()`	Validate an IPv6 address as a configured IPv6 host address on an enabled interface.
`NetIPv6_IsAddrsCfgdOnIF()`	Validate if any IPv6 host addresses are configured on a specific interface.

Generic IP Address Information Functions

Those functions gives you generic information on a specific IP address.

Function Name	Description
IPv4
`NetIPv4_IsAddrBroadcast()`	Validate an IPv4 address as the limited broadcast IPv4 address.
`NetIPv4_IsAddrClassA()`	Validate an IPv4 address as a Class-A IPv4 address.
`NetIPv4_IsAddrClassB()`	Validate an IPv4 address as a Class-B IPv4 address.
`NetIPv4_IsAddrClassC()`	Validate an IPv4 address as a Class-C IPv4 address.
`NetIPv4_IsAddrLocalHost()`	Validate an IPv4 address as a Localhost IPv4 address.
`NetIPv4_IsAddrLocalLink()`	Validate an IPv4 address as a link-local IPv4 address.
`NetIPv4_IsAddrThisHost()`	Validate an IPv4 address as the ‘This Host’ initialization IPv4 address.
`NetIPv4_IsValidAddrHost()`	Validate an IPv4 address as a valid IPv4 host address.
`NetIPv4_IsValidAddrHostCfgd()`	Validate an IPv4 address as a valid, configurable IPv4 host address.
`NetIPv4_IsValidAddrSubnetMask()`	Validate an IPv4 address subnet mask.
IPv6
`NetIPv6_GetAddrMatchingLen()`	Compute the number of identical most significant bits of two IPv6 addresses.
`NetIPv6_GetAddrScope()`	Get the scope of a specific IPv6 address.
`NetIPv6_IsValidAddrHost()`	Validate an IPv6 host address.
`NetIPv6_IsAddrLinkLocal()`	Validate an IPv6 address as a link-local IPv6 address.
`NetIPv6_IsAddrSiteLocal()`	Validate an IPv6 address as a site-local address.
`NetIPv6_IsAddrMcast()`	Validate an IPv6 address as a multicast address.
`NetIPv6_IsAddrMcastSolNode()`	Validate an IPv6 address as a solicited node multicast address.
`NetIPv6_IsAddrMcastAllNodes()`	Validate an IPv6 address as the all nodes multicast address.
`NetIPv6_IsAddrMcastAllRouters()`	Validate an IPv6 address as the all routers multicast address.
`NetIPv6_IsAddrMcastRsvd()`	Validate the IPv6 address as a a reserved multicast IPv6 address.
`NetIPv6_IsAddrUnspecified()`	Validate an IPv6 address as the unspecified IPv6 address.
`NetIPv6_IsAddrLoopback()`	Validate an IPv6 address as the IPv6 loopback address.

IP Address Conversion Utilities

Those functions allows conversion from a string representation of an IP address to the µC/TCP-IP IP stack address representation and vice-versa.

Function name	Description
`NetASCII_Str_to_IP`	Convert a string of an IPv4 or IPv6 address in their respective decimal notation to an IPv4 or IPv6 address.
`NetASCII_Str_to_IPv4`	Convert a string of an IPv4 address in dotted-decimal notation to an IPv4 address in host-order.
`NetASCII_Str_to_IPv6`	Convert a string of an IPv6 address in common-decimal notation to an IPv6 address.
`NetASCII_IPv4_to_Str`	Convert an IPv4 address in host-order into an IPv4 dotted-decimal notation ASCII string.
`NetASCII_IPv6_to_Str`	Convert an IPv6 address into an IPv6 colon-decimal notation ASCII string.

Hook Functions

IP Address Configuration Hook Functions

Function	Description
I Pv6 Static Address Configuration Hook	Receives the result of the Non-Blocking IPv6 Static Address Configuration process.
I Pv6 Stateless Address Auto-Configuration Hook	Receives the result of the IPv6 Stateless Address Auto-Configuration process.

IP Address Conversion

µC/TCP-IP contains functions to perform various string operations on IP addresses.

The following example shows how to use the NetASCII module in order to convert IP addresses to and from their dotted-decimal representations:

Listing - IP address string conversion

NET_IPv4_ADDR ipv4_addr;
NET_IPv6_ADDR ipv6_addr;
CPU_INT08U    ipv4_str[16];
CPU_INT08U    ipv6_str[40];
NET_ERR       err;

/* IPv4 */
(void)NetASCII_Str_to_IP((CPU_CHAR *)"192.168.1.65", &ipv4_addr, NET_IPv4_ADDR_SIZE, &err);
NetASCII_IPv4_to_Str(ipv4_addr, &ipv4_str[0], DEF_NO, &err);
/* IPv6 */ 
(void)NetASCII_Str_to_IP((CPU_CHAR *)"fe80::1111:1111", &ipv6_addr, NET_IPv6_ADDR_SIZE, &err);
NetASCII_IPv6_to_Str(&ipv6_addr, &ipv6_str[0], DEF_NO, &err);

Static IP Address Configuration On An Interface

See section IP Address Configuration for an example on how to configure a static IPv4 or IPv6 on a specific Interface.

Dynamic IP Address Configuration On An Interface

IPv4 address can be configured dynamically on an interface by integrating µC/DHCPc to your application.

If you want to develop your own network application to setup dynamic addressing, the IPv4 functions NetIPv4_CfgAddrAddDynamic, NetIPv4_CfgAddrAddDynamicStart, NetIPv4_CfgAddrAddDynamicStop should be used.

Dynamic address configuration is not yet available for IPv6.

Stateless Address Auto-Configuration

Only available for IPv6.

The IPv6 protocol defines an Auto-Configuration procedure allowing a network interface to set itself an IPv6 Link-Local address based on its Interface ID and also a IPv6 global address if an IPv6 router is present on the local network.

Refer to section Sample applications for examples on IPv6 Address Auto-Configuration.

IP Addressing with Socket Programming

When developing a network application that send and/or receive data, IP address handling will be required.

When you setup a server application, you MUST bind to an already configured IP address. This address will be used as the destination address for all the clients communicating with the server and will be used as the source address for the packets sent by the server.

You can use the function NetIPv4_GetAddrHost or NetIPv6_GetAddrHost to recover all the IPv4 or IPv6 addresses configured on a specific Interface.

You also have the option to bind to the wildcard address (0.0.0.0 for IPv4 and :: for IPv6). In that case, the server socket is not bound to any IP address in particular, therefore any packets send to the corresponding server port number will be received by the server regardless of the destination address. When sending packets, the µC/TCP-IP stack will take care of setting the best source address for the destination.

When you setup a client application, you MAY want to bind to a specific configured IP address. Knowing the destination IP address, you can use the function NetIPv4_GetAddrSrc or NetIPv6_GetAddrSrc to found the best suited configured IP address for your destination.

If you don't bound to an IP address, the µC/TCP-IP stack will take care of setting the source address of packets to send.

Refer to section Socket Programming for more information on using network sockets.