tfNgOpenInterface

Jump to: navigation, search

Table of Contents >> IPv6 Programmer's Reference


#include <trsocket.h>


int tfNgOpenInterface (
ttUserInterface interfaceHandle,
const struct sockaddr_storage * ipAddrPtr,
int prefixLen,
int flags,
int ipv6Flags,
int buffersPerFrameCount,
tt6DevAddrNotifyFuncPtr dev6AddrNotifyFuncPtr
);


Function Description

Next Generation API replaces tfOpenInterface(). This API is a wrapper function for tfNgConfigInterface() specifying a multi-home index of 0. If it has not already been started, this API starts the IPv4 part of an interface if the specified address is an IPv4 address (or an IPv4-mapped IPv6 address), starts the IPv6 part of an interface if the specified address is an IPv6 address, and starts both IPv4 and IPv6 if the specified address is an IPv4-compatible IPv6 address.

Starting the IPv6 part of an interface causes IPv6 stateless address auto-configuration to be invoked, if an interface ID has been set on the interface, to dynamically assign IPv6 addresses to the interface. If an IPv6 address is specified, it may be all 0's (i.e. the IPv6 unspecified address), in which case no IPv6 address is manually configured on the interface. However, the IPv6 part of the interface is started to attempt IPv6 stateless address auto-configuration. Note that in this case, the device flag TM_DEV_IP_USER_BOOT should not be specified since IPv6 does not have any equivalent of the API tfFinishOpenInterface().

When you are running the Treck stack in dual IP layer mode and the specified address is an IPv4-compatible IPv6 address, it is configured on the interface at the same multi-home index in both the IPv4 and IPv6 address lists to support automatic tunneling. For example, if you call this API to configure an IPv4-compatible IPv6 address, this API checks both IPv6 and IPv4 address lists to make sure that the slot indexed by multi-home index 0 is available in both, then configures the IPv4-compatible IPv6 address in the IPv6 address list at multi-home index 0, and the embedded IPv4 address (i.e. the low-order 32 bits of the IPv6 address) in the IPv4 address list at multi-home index 0. This is done to support automatic tunneling since automatic tunneling requires us to implement the IPv4 endpoint of the tunnel on the interface and the tunnel endpoint is the embedded IPv4 address. If the slot in the IPv4 address list indexed by the specified multi-home index is already configured with a different IPv4 address, this API returns TM_ENOSPC to indicate that configuration of the IPv4-compatible IPv6 address failed because the specified multi-home index was not available to configure. When configuring an IPv4-compatible IPv6 address, the specified prefix length must be the IPv6 prefix length, rather than the IPv4 prefix length. That is, the configured prefix length for an IPv4-compatible IPv6 address must be greater than 96.

When the stack is operating in dual IPv4/IPv6 mode, in order to support automatic tunneling, if a global IPv4 address is acquired via BOOTP/DHCP, an IPv4-compatible IPv6 address corresponding to the acquired address is also configured at the same IPv6 multi-home index. For instance, if the first IPv4 multi-home entry is configured via DHCP, the stack will automatically attempt to configure a corresponding IPv4-compatible IPv6 address at the first IPv6 multi-home entry. However, if another IPv6 address is already configured at the first multi-home entry, the IPv4-compatible IPv6 address cannot be added. Please note that this behavior may be disabled with the TM_6_DEV_OPTIONS_NO_DHCP_CONF option through tfInterfaceSetOptions().

Since this API is used to manually configure addresses, multiHomeIndex may not be greater than or equal to TM_MAX_IPS_PER_IF.

Note Note: Note that the macro TM_MAX_IPS_PER_IF is not publicly accessible unless you explicitly define it in your trsystem.h file. One possible alternative is to use the TM_NT_MAX_IPS_PER_IF macro if you have TM_USE_NETSTAT defined in your trsystem.h file.

If dev6AddrNotifyFuncPtr is non-null, then the user wants to be notified of IPv6-specific address configuration events via a user-defined notify function. IPv6 is different from IPv4 with regards to address configuration, because every IPv6 address configured on the interface must first go through Duplicate Address Detection to confirm that no other node is using that tentative address before the address may be configured on the interface ([RFC 2462]). Also, IPv6 addresses which are auto-configured using stateless address auto-configuration have preferred and valid lifetimes, and when they become invalid, they are un-configured from the interface. The address configuration events you can be notified of consist of the status of Duplicate Address Detection, as well as IPv6 address state transitions from preferred to deprecated, and to invalid:



IPv6 Address Configuration Events

  • TM_6_DEV_ADDR_CONFIG_STARTED
    Configuration of the IPv6 address has been started. Duplicate Address Detection is being performed on the tentative address.
  • TM_6_DEV_ADDR_CONFIG_FAILED
    Duplicate Address Detection failed. A different node is already using the tentative address we tried to configure, therefore configuration failed.
  • TM_6_DEV_ADDR_CONFIG_COMPLETE
    Duplicate Address Detection succeeded. Configuration of the IPv6 address on the interface completed successfully.
  • TM_6_DEV_ADDR_DUP_DETECTED
    The Treck stack detected that a different node is using one of your IPv6 addresses that was successfully configured (i.e. for which the TM_6_DEV_ADDR_CONFIG_COMPLETE event has occurred). It is up to the user to specify what recovery, if any, is performed when this event occurs. ([RFC 2462])
  • TM_6_DEV_ADDR_PREFERRED
    An auto-configured IPv6 address has transitioned state from deprecated to preferred.
  • TM_6_DEV_ADDR_DEPRECATED
    An auto-configured IPv6 address has transitioned state from preferred to deprecated.
  • TM_6_DEV_ADDR_INVALIDATED
    An auto-configured IPv6 address has transitioned state to invalid, and has been unconfigured from the interface.
  • TM_6_DEV_ADDR_ALL_RELEASED
    An DHCPv6 address has been released and unconfigured from the interface.
  • TM_6_DEV_ADDR_ALL_DECLINED
    An DHCPv6 address has been declined and not configured on the interface.
  • TM_6_DEV_DHCP_KEY_NOT_FOUND
    DHCPv6 client does not have the key requested by the server to complete the authentication process.
  • TM_6_DEV_DHCP_KEY_EXPIRED
    DHCPv6 client has the key requested by the server, but it has expired and the client is not able to complete the authentication process.



After an IPv6 address has been configured on the interface there is still the possibility that another node will use an IPv6 address that we have already configured. If the user has specified a non-null value for dev6AddrNotifyFuncPtr and the Treck stack detects that another node is using an IPv6 address that we have already configured, then the user is notified of the TM_6_DEV_ADDR_DUP_DETECTED event. It is up to the user to specify what recovery, if any, is performed ([RFC 2462]).

For example, when you are notified of the TM_6_DEV_ADDR_DUP_DETECTED event, you could un-configure the conflicting IPv6 address by calling tfNgUnConfigInterface(). However, this would impact any applications which are currently using that IPv6 address. Note: if the only link-local scope IPv6 address on the interface is un-configured, the IPv6 part of the interface will be disabled.

If you are notified of the event TM_6_DEV_ADDR_CONFIG_FAILED for a link-local scope IPv6 address, this likely indicates that the IPv6 part of the interface was disabled due to an interface ID conflict. In which case calling tfCheckOpenInterface() with protocolFamily set to PF_INET6 returns TM_EPERM. Recovery usually entails either setting a different interface ID by calling tf6Eui64SetInterfaceId() and then attempting to restart the IPv6 part of the interface by calling tfNgOpenInterface() specifying an IPv6 address of all 0's (i.e. the IPv6 unspecified address), or manually configuring a link-local IPv6 address on the interface. However, it is possible that you get this failure because your network controller hardware does not support filtering of its own multicasts, but instead does loopback of its own multicasts which would cause Duplicate Address Detection to always fail. If this is the case, then specifying the IPv6-specific device flag TM_6_DEV_MCAST_HW_LOOPBACK in ipv6Flags should fix the problem. Note that generally you want to avoid setting this device flag since it causes Duplicate Address Detection to not be as robust.


Please see the function prototype for dev6AddrNotifyFuncPtr.


By default, Duplicate Address Detection will be performed for every IPv6 address configured on the interface.

IPv6 addresses which are auto-configured using the interface ID all share the same low-order 64 bits, set to the interface ID. Specifying the IPv6-specific device flag TM_6_DEV_OPTIMIZE_DAD causes Duplicate Address Detection to only be performed on the link-local scope address for the set of addresses that are auto-configured using the interface ID ([RFC 2462].


Parameters

  • interfaceHandle
    The device entry as returned by tfAddInterface().
  • ipAddrPtr
    A pointer to the sockaddr_storage structure containing the IPv4 or IPv6 address to be configured.
Warning Warning: This address must not be the link-local auto-configured address. If the user wishes to specify a link-local auto-configured address, they must use either the tf6Eui48SetInterfaceId() API or tf6Eui64SetInterfaceId() API and then call this function with an address of all 0's (i.e. the IPv6 unspecified address) or another manual address the user wishes to configure.
  • prefixLen
    The length (in bits) of the subnet prefix part of the address specified by ipAddrPtr. For an IPv6 address, the value specified must be in the range of 4 to 128, and will typically be 64. For an IPv4 address, the value specified is the number of most significant bits in the associated IPv4 netmask that are set to 1.
  • flags
    General device flags and IPv4-specific interface flags, same as the flag parameter passed to tfConfigInterface().
  • ipv6Flags
    IPv6-specific interface/device flags (see below)
Only device flags that start with "TM_6_DEV_" are set in ipv6Flags, all others are set in flags.
  • buffersPerFrameCount
    Number of scattered buffers allowed for each frame being sent out. If scattered buffers are not allowed by the driver, this number should be 1, otherwise it should be greater than 1.
  • dev6AddrNotifyFuncPtr
    The function to call to notify the user of IPv6-specific address configuration events, or TM_6_DEV_ADDR_NOTIFY_FUNC_NULL_PTR if notification is not desired.
The events are:
TM_6_DEV_ADDR_CONFIG_STARTED
TM_6_DEV_ADDR_CONFIG_FAILED
TM_6_DEV_ADDR_CONFIG_COMPLETE
TM_6_DEV_ADDR_DUP_DETECTED
TM_6_DEV_ADDR_PREFERRED
TM_6_DEV_ADDR_DEPRECATED
TM_6_DEV_ADDR_INVALIDATED


Note Note: When the Treck stack is run in dual IP layer mode, and the specified address is an IPv4-compatible IPv6 address, then it is configured on the interface at the same multi-home index in both the IPv4 and IPv6 address lists to support automatic tunneling.

ipv6Flags

Value Meaning
TM_6_DEV_IP_FAST_BOOT The configured static IPv6 address is temporary, pending autoconfiguration via DHCPv6 or Router Advertisement. When autoconfiguration results in the same address, your temporary address will be unconfigured automatically. You must define compile time macro TM_6_USE_FAST_TEMP_BOOT to enable the code that supports this flag. See Fast Reboot when using Autoconfigured Addresses for a full discussion.
TM_6_DEV_IP_FORW_ENB This enables IPv6 forwarding to and from this device.
TM_6_DEV_IP_FORW_MCAST_ENB This enables forwarding of IPv6 multicast messages to and from this device.
TM_6_DEV_IP_TEMPORARY The configured static IPv6 address is temporary. If the user sets this flag, the stack will prefer a dynamic IPv6 address (configured from a router advertisement) of the same scope, when picking an IPv6 source address.
TM_6_DEV_MCAST_HW_LOOPBACK This indicates that the network controller hardware does not support filtering of its own multicasts but instead does loopback of its own multicasts. Generally, you don't want to set this flag, since it causes Duplicate Address Detection to not be as robust.
TM_6_DEV_OPTIMIZE_DAD This enables optimization of Duplicate Address Detection so that, for IPv6 addresses generated via stateless address auto-configuration, we only perform Duplicate Address Detection on the link-local scope address.
TM_6_DEV_USER_DHCP The DHCPv6 client will be started on this interface when the interface is opened.
TM_6_DEV_USER_DHCP_CONF_OPEN This flag is set in conjunction with TM_6_DEV_USER_DHCP to instruct the client to do a Confirm and Reply message exchange rather than a standard exchange. You must define compile time macro TM_6_DHCP_USE_CONF_OPEN to enable the code that supports this option. If this option is set, you must also use tf6DhcpSetAddrOption() to set at least one address to send in the Confirm message. See Using the Confirm Message to Reboot the DHCPv6 Client for a full discussion.
TM_6_DEV_USER_DHCP_INFO_ONLY This flag is set in conjunction with TM_6_DEV_USER_DHCP to instruct the client to do an Information-Request exchange rather than a standard exchange. If this option is set, no addresses will be retrieved from the server.
TM_6_DEV_USER_DHCP_RTR_CTRLD The DHCPv6 client is controlled by the Managed and Other flags received in IPv6 Router Advertisements. When a router advertisement is received, the stack checks if either the M or the O flag is set. If the O flag (but not the M flag) is set, a DHCPv6 Info-Request packet is sent. If the M flag is set, full DHCPv6 address configuration occurs. Once the M flag has been received, the DHCPv6 address configuration will stay in effect until the interface in question has been closed, even if subsequent Router Advertisement packets are received in which the M flag is not set. If an O flag is received first, then an M flag is received subsequently, the DHCPv6 client will perform full address configuration upon receipt of the M flag.
TM_6_USE_AUTO_IID This enables auto interface ID.


Returns

  • TM_EINVAL
    multiHomeIndex was greater than or equal to TM_MAX_IPS_PER_IF or an invalid value was specified for prefixLen.
  • TM_EAFNOSUPPORT
    ipAddrPtr->addrFamily was set to an invalid value for address family; valid values are AF_INET and AF_INET6.
  • TM_EPERM
    You attempted to open the interface for IPv6, however there was no way to configure a link-local scope IPv6 address on the interface. Typically, this happens when you use the null link-layer, and you don't call tf6Eui64SetInterfaceId() to set the interface ID before attempting to open the interface for IPv6.
  • TM_ENOSPC
    Failed to configure an IPv4-compatible IPv6 because a different IPv4 address was already configured in the IPv4 address list at multi-home index 0.
  • TM_EINPROGRESS
    Configuration has not completed for multi-home index 0. If you are configuring an IPv6 address on the interface, then this error code could indicate that Duplicate Address Detection is still being performed.


Table of Contents >> IPv6 Programmer's Reference