Table of Contents

Table of Chapters

13 Other API

13.1 - ICMPv6 callbacks

ICMPv6 provides the potential for the receipt a number of informational packets the may be useful to applications and higher layer protocol code (e.g. raw sockets). These received ICMPv6 packets may be accessed by installing optional callback routines. There are two such routines, icmp6_callback and ping6_callback. Each is a pointer to a routine, having the following C definition:

int (*icmp6_callback)(PACKET);

Code that sets these pointers should first save the present value of the pointer as the "next callback". If the "next callback" pointer is non-null, it means that another code module has set the pointer and expects access to the received packet. In this case, the callback routine should "daisy-chain" to the non-null value, passing the unchanged received packet to "next callback".

The received packet is responsible for freeing the PACKET structure if the callback routine is the last (or only) routine in the daisy-chain as indicated by the "next callback" value being NULL. The PACKET structure should be freed (via a call to pk_free(pkt)) or have other arrangements made to ensure that it eventually returns to the free buffer queues.

Note that ping6_callback will generally be set by the IPv6 "ping" application

13.2 - IP6EQ(), IP6CPY(),

IP6EQ() and IP6CPY() are primitives to manipulate IPv6 addresses. In addition to providing a mechanism for efficient per-port implementations, they are also designed to detect programming errors where IPv6 addresses and pointers to addresses are inadvertently confused. To this end, they should generally be implemented as C functions (possible in-line), or in-line assembly language code. Default definitions of these routines are included in h/ipv6.h, however these defaults are inefficient and do not check the parameters. They should only be used during initial prototyping of a port.

The recommended implementation method is to provide these two routines with other names (e.g. ip6cpy and ip6eq), and #define them to IP6EQ() and IP6CPY(). This enforces global type checking of the passed IPv6 address parameters, and prevents the inefficient default macros in ipv6.h from being used.

Here are the reference definitions from the Windows port ipport.h_h file:

struct in6_addr;   /* predecl */
extern void ip6cpy(struct in6_addr * dest, struct in6_addr * src);
#define IP6CPY(a,b) ip6cpy(a,b)
extern  int ip6eq(struct in6_addr * dest, struct in6_addr * src);
#define IP6EQ(a,b) ip6eq(a,b)

Intel 386 Assembly versions of these are in win32/osport.c.

IP6CPY(destination, source) copies an IPv6 address from the second pointer passed to the first pointer passed. It is meant to replace the simple assignment operator that was useful with IPv4 addresses. Since the passed addresses are always 128 bits long, the best implementation is probably to do four get/put sequences of 32 bits each. CPUs that have a fast built-in string move operation (such as Intel x86) may opt to use that instead.

IP6EQ(addr1, addr2 ) does a fast compare of the two IPv6 addresses. It returns TRUE if the IP addresses match exactly, and FALSE is they do not. Most often the addresses passed will not match, so the code should be optimized accordingly. Also, mismatches are more likely near the end of the IPv6 addresses than at the beginning. Optimize accordingly.

13.3 Utility functions

A number of utility functions are provided for the IPv6 programmer.

The following are implemented as defined by rfc2533.

inet_ntop()convert a numeric address into a text string suitable for presentation
inet_pton()convert an address in its standard text presentation form into its numeric binary form

Following functions can be use to determine the type of IPv6 address.

IP6_MCASTADDR(ipaddr)check if ipaddr is a multicast address
IP6_GLOBADDR(ipaddr)check if ipaddr is a global address
IP6_LINKADDR(ipaddr)check if ipaddr is a link-local address
IP6_SITEADDR(ipaddr)check if ipaddr is a site-local address
NOTE: Site Local addressing has been deprecated.
IP6_MCASTSCOPE(ipaddr)identify IPv6 multicast scope

Name

ip6_addrcango()

Syntax

int ip6_addrcango(struct sockaddr_in6 *dest);;

Description

Given a struct sockaddr_in6, this function will determine if there is an "up" interface to use for that address. Under IPv6, IP addresses have to pass through duplicate address detection on the link, before they can be used on an interface even if the interface is "up". Hence there can be short times during system startup in which the interface may be up, but a given address cannot be used.

Returns

Returns 1 if the packet can be transmitted, 0 otherwise.

Name

ip6_matchmyaddr()

Syntax

struct ip6_inaddr *ip6_matchmyaddr(ip6_addr * dest, NET ifp);

Description

Given an ip6_addr, this function will return our source address of the matching type to the destination address, where the IF is up.

Returns

Our best matching source IP address.