tf6GetLocalIpAddress

Jump to: navigation, search

Table of Contents >> IPv6 Programmer's Reference


#include <trsocket.h>


int tf6GetLocalIpAddress (
ttUserInterface interfaceHandle,
const struct sockaddr_storage * destIpAddrPtr,
tt6LocalIpAddressCursorPtr addrCursorPtr,
int initCursorFlag,
struct sockaddr_storage * localIpAddrPtr
);


Function Description

This function only supports IPv6. This function is called to retrieve a local IP address appropriate for use/communication with the specified destination IP address from the list of multi-homed IPv6 addresses associated with the specified interface. There may be more than one matching local IP address in that list for the specified interface and destination IP address, in which case this function may be called multiple times to retrieve each appropriate local IP address one at a time, setting initCursorFlag appropriately as described below. Alternatively, if the caller only wants to retrieve the first/best match, addrCursorPtr may be set to NULL to indicate that no iteration is desired.

The default mode of operation is to return preferred IPv6 addresses first, and next to return deprecated IPv6 addresses if there are any. You can disable the use of deprecated addresses by calling tfSetTreckOptions() to enable the option TM_6_OPTION_IP_DEPRECATE_ADDR, in which case tf6GetLocalIpAddress() does not return deprecated IPv6 addresses. Note that after this function is called, bind() must still be called to associate the local IP address with a socket so that it is used in communications on that socket.

When the destination IPv6 address is a global scope unicast IPv6 address, this function may be called to search all interfaces for the best matching local IPv6 address by setting interfaceHandle to NULL. This API has visibility to all IPv6 addresses configured on the interface, including those auto-configured by IPv6 stateless address auto-configuration.

([RFC 2462], [RFC 2893], [RFC 2893], [RFC 2893], [RFC 2462], [RFC 2462], [RFC 3056], [RFC 3056])



Parameters

  • interfaceHandle
    Interface handle of the outgoing interface for which we want to select an appropriate local IPv6 address. When the destination IPv6 address is a global scope unicast IPv6 address, interfaceHandle may be set to NULL, in which case the outgoing interface is determined by doing a longest prefix match on the destination IPv6 address, and then the global scope IPv6 addresses configured on that interface are returned in longest prefix match order.
  • destIpAddrPtr
    Pointer to the destination IPv6 address with which we want to communicate.
  • addrCursorPtr
    Pointer to a cursor used to iterate through the list of multihomed IPv6 addresses associated with the specified interface. addrCursorPtr may be set to NULL to indicate that no iteration is desired, otherwise the memory that this points to must be allocated by the caller, i.e. a local variable of type tt6LocalIpAddressCursor in the caller's address space. This function uses the cursor to keep track of where to restart the search in the multi-homed IPv6 address list each time it is called to find the next appropriate local IP address. Therefore, the caller must not change the cursor value, since this function updates it each time it is called to keep track of the state of the iteration.
  • initCursorFlag
    Must be set to 1 (i.e. non-zero) the first time this function is called for a specific combination of interface and destination IP address, otherwise set to 0. When initCursorFlag is set to 1, this function initializes the cursor (pointed to by addrCursorPtr) to point to the beginning of the list of multihomed IPv6 addresses associated with the specified interface, and therefore starts the search for an appropriate local IP address at the beginning of this list. To retrieve additional appropriate IP addresses, initCursorFlag must be set to 0 on subsequent calls to this function so that the cursor can properly iterate through the list.
  • localIpAddrPtr
    When this function returns 0 (i.e. success), localIpAddrPtr points to a local IP address appropriate for use/communication with the specified destination IP address. The memory that this points to must be allocated by the caller, i.e. a local variable in the caller's address space. If there is more than one appropriate local/source IP address, they may be retrieved individually by calling this function multiple times, specifying the same interface and destination IP address each time, and each time specifying the correct value for initCursorFlag as described above.


Returns

  • 0
    Success.
  • TM_EINVAL
    One of the following:
  • One of the parameters was invalid. Either an invalid interface handle was specified
  • The cursor (pointed to by addrCursorPtr) is set to an invalid value and initCursorFlag is not 1
  • One of the pointers passed in as parameters (i.e. destIpAddrPtr, addrCursorPtr, selectedLocalIpAddrPtr) was NULL
  • The specified destination IP address (pointed to by destIpAddrPtr) was an invalid IPv6 address.
  • TM_ENETDOWN
    Interface is not configured.
  • TM_ENOENT
    There was no appropriate local IP address found; iteration of the multi-homed IPv6 address list is complete.
  • TM_EAFNOSUPPORT
    The specified destination IP address (pointed to by destIpAddrPtr) was not an IPv6 address, i.e. destIpAddrPtr->addrFamily != AF_INET6


Table of Contents >> IPv6 Programmer's Reference