tfOpenInterface

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 tfNgOpenInterface().


#include <trsocket.h>


int tfOpenInterface (
ttUserInterface interfaceHandle,
ttUserIpAddress ipAddress,
ttUserIpAddress netMask,
int flags,
int bufferPerFrameCount
);


Function Description

This function is used to configure an interface with an IP address, and net mask (either supernet or subnet). It must be called before the interface can be used. An example would be:


errorCode = tfOpenInterface(myInterfaceHandle,
                            inet_addr("1.2.3.4"),
                            inet_addr("255.255.255.0"),
                            0,
                            1);


Warning Warning: tfConfigInterface() is deprecated for the first multihome. Please use tfOpenInterface() for the first configuration on an interface.


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.


Flags

Value Meaning
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.
TM_DEV_MCAST_ENB This device supports multicast addresses.
TM_DEV_IP_FORW_ENB Allow IP Forwarding to and from this device.
TM_DEV_IP_FORW_DBROAD_ENB Allow forwarding of IP directed broadcasts 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_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_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_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.


Returns

  • TM_ENOERROR
    Success.
  • TM_EADDRNOTAVAIL
    Attempt to configure the device with a broadcast address.
  • TM_EINPROGRESS
    tfOpenInterface() 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 tfOpenInterface() 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 client 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 tfOpenInterface() 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

tfOpenInterface() 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 tfOpenInterface(), otherwise the call will fail with error code TM_EPERM. An example of a configuration using the DHCP protocol would be:

errorCode = tfOpenInterface(myInterfaceHandle,
                            (ttUserIpAddress)0,
                            (ttUserIpAddress)0,
                            TM_DEV_IP_DHCP,
                            1);


Checking on completion of DHCP or BOOTP configuration

  • Synchronous check: The user can make multiple calls to tfOpenInterface() to determine when the configuration has completed.. Additional calls to tfOpenInterface() will return TM_EINPROGRESS as long as the BOOTP/DHCP server has not replied. tfOpenInterface() 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 tfOpenInterface(). See tfUseDhcp() (respectively tfUseBootp()) for details.


Table of Contents >> Programmer's Reference