tfConfigInterface

Jump to: navigation, search

Table of Contents >> Programmer's Reference

Note Note: The content on this page has been deprecated.
For the new content, please see tfNgConfigInterface().


#include <trsocket.h>


int tfConfigInterface (
ttUserInterface interfaceHandle,
ttUserIpAddress ipAddress,
ttUserIpAddress netMask,
int flags,
int buffersPerFrameCount,
unsigned char mHomeIndex
);


Function Description

This function is used to configure an interface with an IP address, and net mask (either supernet or subnet). Can be used for multiple IP addresses on an interface (multihoming). It must be called before the interface can be used.

An example would be:


errorCode = tfConfigInterface(myInterfaceHandle,
                              inet_addr("1.2.3.4"),
                              inet_addr("255.255.255.0"),
                              0,
                              1,
                              (unsigned char)0);


Warning Warning: tfConfigInterface() is deprecated for the first multihome. Please use tfOpenInterface() for the first multihome configuration, instead of tfConfigInterface().


Parameters

  • interfaceHandle
    The device entry as returned by tfAddInterface().
  • ipAddress
    The IP address for this interface.
  • netMask
    The netmask for this device (subnet or supernet).
  • flags
    Special flags for this device OR'ed together (see below).
  • 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.
  • mHomeIndex
    The index for this IP address for multihoming. Zero must be the first multihome index used.


Flags

Value Meaning
TM_DEV_IP_BOOTP Configure IP address using BOOTP client protocol. tfUseBootp() needs to have been called first.
TM_DEV_IP_DHCP Configure IP address using DHCP client protocol. tfUseDhcp() needs to have been called first. If TM_DEV_DHCP_INFO_ONLY is also specified, you must provide the IP address in ipAddress; the DHCP client will retrieve the remaining configuration parameters.
TM_DEV_DHCP_INFO_ONLY If a user has obtained an IP address through some other means (e.g. manual configuration), the TM_DEV_DHCP_INFO_ONLY flag can be set to send a DHCPINFORM message to obtain the remaining configuration parameters (e.g. default router, DNS servers). The TM_DEV_IP_DHCP flag must also be set and a non-zero ipAddress must be provided.
TM_DEV_IP_FORW_DBROAD_ENB Allow forwarding of IP directed broadcasts to and from this device.
TM_DEV_IP_FORW_ENB Allow IP Forwarding to and from this device.
TM_DEV_IP_FORW_MCAST_ENB Allow forwarding of IP multicast messages to and from this device.
TM_DEV_IP_NO_CHECK Allow the Treck stack to function in promiscuous mode, where all packets received by this interface will be handed to the application without checking for an IP address match on the incoming interface.
TM_DEV_IP_USER_BOOT Allow the user to temporarily configure the interface with a zero IP address, to allow the user to use a proprietary protocol to retrieve an IP address from the network.
TM_DEV_MCAST_ENB This device supports multicast addresses.
TM_DEV_SCATTER_SEND_ENB This device supports sending data in multiple buffers per frame. If this flag is set, then the buffersPerFrameCount should be bigger than 1. This flag should always be set for SLIP or PPP serial devices.


Returns

  • TM_ENOERROR
    Success.
  • TM_EADDRNOTAVAIL
    Attempt to configure the device with a broadcast address.
  • TM_EINPROGRESS
    tfConfigInterface() has not completed. This error will be returned for a DHCP or BOOTP configuration for example.
  • TM_ENOBUFS
    Not enough memory to complete the operation.
  • TM_EINVAL
    Bad parameter, or the first configuration should be for multihome index 0. Note that a zero IP address is allowed for Ethernet if the BOOTP, DHCP, or USER_BOOT flag is on, or for PPP.
  • TM_EALREADY
    A previous call to tfConfigInterface() has not yet completed.
  • TM_EPERM
    User atempted to configure an IP address via DHCP (respectively BOOTP) without having called tfUseDhcp() (respectively tfUseBootp()) successfully first.
  • TM_EMFILE
    Not enough sockets to open the BOOTP client UDP socket (TM_IP_DEV_BOOTP or TM_IP_DEV_DHCP configurations only).
  • TM_EADDRINUSE
    Another socket is already bound to the BOOTP clietn UDP port. (TM_IP_DEV_BOOTP or TM_IP_DEV_DHCP configurations only.)
  • TM_ETIMEDOUT
    DHCP or BOOTP request timed out.
  • TM_EAGAIN
    A PPP session is currently closing. Call tfConfigInterface() again after receiving notification that the previous session has ended.
  • (Other)
    Error value passed through from the device driver open function.


DHCP or BOOTP configuration

tfConfigInterface() with a TM_DEV_IP_DHCP (respectively TM_DEV_IP_BOOTP) flag will send a DHCP (respectively BOOTP) request to a DHCP/BOOTP server, and will return with TM_EINPROGRESS.

Note that tfUseDhcp() (respectively tfUseBootp()) needs to have been called prior to calling tfConfigInterface(), otherwise the call will fail with error code TM_EPERM. An example of a configuration using the DHCP protocol would be:

errorCode = tfConfigInterface(myInterfaceHandle,
                              (ttUserIpAddress)0,
                              (ttUserIpAddress)0,
                              TM_DEV_IP_DHCP,
                              1,
                              (unsigned char)0);


Checking on completion of DHCP or BOOTP configuration

  • Synchronous check: The user can make multiple calls to tfConfigInterface() to determine when the configuration has completed. Additional calls to tfConfigInterface() will return TM_EINPROGRESS as long as the BOOTP/DHCP server has not replied. tfConfigInterface() will return TM_ENOERROR if the BOOTP/DHCP server has replied and the configuration has completed.
  • Asynchronous check: To avoid this synchronous poll, the user can provide a user call back function to tfUseDhcp() (respectively tfUseBootp()), that will be called upon completion of tfConfigInterface(). See tfUseDhcp() (respectively tfUseBootp()) for details.


Table of Contents >> Programmer's Reference