tfInterfaceSetOptions

Jump to: navigation, search

Table of Contents >> Programmer's Reference


#include <trsocket.h>


int tfInterfaceSetOptions (
ttUserInterface interfaceHandle,
int optionName,
void TM_FAR * optionValuePtr,
int optionLength
);


Function Description

Configure interface options. optionValuePtr points to a variable of type as described below. optionLength contains the size of that variable.


Possible Options

Option Name Option Value
TM_DEV_OPTIONS_BOOT_RETRIES Total number of BOOTP/DHCP requests to send without receiving a response from a BOOTP/DHCP server. Specifying a value of TM_DEV_BOOT_INF indicates that the stack should retry sending the BOOTP/DHCPv4 requests indefinitely.

Data Type: unsigned char

Default: 6

TM_DEV_OPTIONS_BOOT_TIMEOUT Base number of seconds for a BOOTP/DHCP request timeout. BOOTP/DHCP timeouts increase with each retransmission, so if this value is set to two seconds, the first timeout will be two seconds, the second will be four seconds, the third will be eight seconds, etc.

Data Type: unsigned char

Default: 4 seconds

TM_DEV_OPTIONS_NO_IGMPV2_RA Accept or drop IGMPv2 queries that do not carry the router alert option. Only valid when TM_USE_IGMPV3 is defined.

Data Type: unsigned char

Default: 0 (Drop)

TM_DEV_OPTIONS_RECV_COPY Make the Treck stack (inside the tfRecvInterface() function) copy received driver buffers whose sizes are smaller than the value pointed to by optionValuePtr into a newly allocated buffer. Option is disallowed on a Point-to-Point (i.e. SLIP, or PPP) interface since the SLIP and PPP link layer copy the data into a newly allocated buffer.

Data Type: unsigned short

TM_DEV_OPTIONS_SCAT_RECV_LENGTH Valid only if TM_USE_DRV_SCAT_RECV is defined. Set the minimum number of bytes at the head of a packet that have to be contiguous. If a scattered recv buffer is received from the driver with a first link length below that minimum, that minimum number of bytes (but no more than the total length of the buffer) is copied into a new stack allocated buffer.

Data Type: unsigned short

Default: TM_DEV_DEF_RECV_CONT_HDR_LENGTH

TM_DEV_OPTIONS_XMIT_TASK Turn on/off usage of a transmit task. Option can only be used when device/interface is not opened/configured. Cannot turn on this option if the device/interface transmit queue is used.

Data Type: unsigned short

Default: Off

TM_DEV_OPTIONS_NO_DHCP_RELEASE When set to 1, this option disables DHCP release messages when the specified interface or DHCP is stopped. When set to 0 (default), DHCP release messages are enabled for these events.

Data Type: unsigned char

TM_DEV_OPTIONS_BOOT_ARP_RETRIES This specifies the number of ARP probe retries before configuring a DHCP/BOOTP address. When set to -1, ARP probes are disabled. When set to 0 (default), the default of TM_MAX_PROBE is used. When set to -2, ARP probes are disabled, and the Treck stack DHCP client will signal the user via the userDhcpOfferNotify function (ttUserDhcpOfferCBFunc function prototype), and event TM_DHCP_EVENT_REQUEST_ACKED) when the stack receives the ACK of the DHCP request from the server

Data Type: int

TM_DEV_OPTIONS_BOOT_ARP_INTVL This specifies the interval, in seconds, between ARP probes (when enabled) prior to configuring a DHCP/BOOTP address. When set to 0 (default), the default value of TM_PROBE_INTERVAL / TM_UL(1000) is used.

Data Type: unsigned char

TM_DEV_OPTIONS_BOOT_ARP_INTVL_MSECS This specifies the interval, in milliseconds, between ARP probes (when enabled) prior to configuring a DHCP/BOOTP address. When set to 0 (default), the default value of TM_PROBE_INTERVAL is used.

Data Type: ttUser32Bit

TM_DEV_OPTIONS_BOOT_ARP_TIMEOUT This specifies the number of seconds to wait after sending the first ARP probe / ARP request before finishing DHCP/BOOTP address configuration. When set to 0 (default), the default value is such that the timeout will occur after the last probe has been sent after the interval time has elapsed.

Data Type: unsigned char .

TM_DEV_OPTIONS_BOOT_PK_HOST_NM When set to 1, this option instructs the DHCP client to use the host name as provided by the DHCP server when building the host name option in the DHCP request. If the server did not send a host name option or if this option is set to 0 (default), then the DHCP client will use the host name as provided by the user instead. Default value for this option is 0.

Data Type: unsigned char

TM_DEV_OPTIONS_BOOT_PK_DOMAIN_NM When set to 1, this option instructs the DHCP client to use the domain name as provided by the DHCP server when building the FQDN option in the DHCP request. In that case the host name in the FQDN option will be picked according to the TM_DEV_OPTIONS_BOOT_PK_HOST_NM option (see above). If the server did not send a domain name option or if this option is set to 0 (default), then the DHCP client will use the FQDN as provided by the user instead. Default value for this option is 0.

Data Type: unsigned char .

TM_DEV_OPTIONS_FORWARDING When set to 1, IP forwarding is enabled on the specified interface. When set to 0, IP forwarding is disabled on the specified interface.

Data Type: unsigned char

TM_DEV_OPTIONS_MCAST_FORWARDING Use this NAT related option to enable IP multicast forwarding on an interface and, more importantly, identify the inner interface to be used for multicast forwarding. The inner interface will be paired with the public interface you specify in tfNatConfig() or tfNatConfigNapt(). If you don't set this option on the inner interface, NAT multicast forwarding will not happen. You can also call this function to enable/disable multicast forwarding on a public interface, but the code will recognize it as public assuming you have made a prior call to tfNatConfig() on the interface. See the main page for details.

Data Type: unsigned char
Default: 0 (disabled)

TM_DEV_OPTIONS_MCAST_FORW_ADDR Use this NAT related option to specify the public address to use for IP multicast forwarding (when a multicast packet from an inner host gets forwarded to the outside, Treck needs to change the source address in the IP header to be an public address). When tfNatConfig() is called, the first configured address on the public interface will become the default public address for IP multicast forwarding. If you call tfNatConfigNapt(), this option is not needed. See the main page for details.

Data Type: ttUserIpAddress

TM_DEV_OPTIONS_FILTER Determines whether IP Filtering is enabled or disabled on the given interface for both incoming and outgoing packets.

Default: 0 (disabled)

Data Type: unsigned char

TM_DEV_OPTIONS_FILTER_INCOMING Determines whether IP Filtering is enabled or disabled on the given interface for incoming packets.

Default: 0 (disabled)

Data Type: unsigned char

TM_DEV_OPTIONS_FILTER_OUTGOING Determines whether IP Filtering is enabled or disabled on the given interface for outgoing packets.

Default: 0 (disabled)

Data Type: unsigned char

TM_DEV_OPTIONS_FILTER_IGMP Determines whether IGMP Filtering is enabled or disabled for the given interface.

Default: 0 (disabled)

Data Type: unsigned char

TM_DEV_OPTIONS_NO_GRAT_ARP Determines whether a gratuitous ARP is sent when the given interface is opened. Must be set before the interface is opened. Default: 0 (gratuitous ARP is sent)

Data Type: unsigned char

TM_DEV_OPTIONS_PPP_SERVER_TIMEOUT Allow the PPP server to start LCP, if the client fails to connect within the set delay (in seconds). Code enabled only if TM_USE_PPP_SERVER_START is defined. Default: 0 (the PPP server waits for the PPP client LCP configuration request.)

Data Type: int

TM_6_DEV_OPTIONS_DHCP_RAPID_CMT When set to 1, the Treck DHCPv6 client will send the Rapid Commit option in the Solicit message to indicate that the client is willing to accept an immediate Reply message containing addresses and other configuration information. When set to 0, the client will use the standard four message exchange for DHCPv6 server discovery and assignment of addresses and other configuration information.

To use this option, you must compile with macro TM_6_DHCP_USE_RAPID_COMMIT defined in your trsystem.h file.

Default: 0 (disabled)

Data Type: unsigned char

TM_6_DEV_OPTIONS_DHCP_FQDN_FULL Used to save a fully qualified (e.g., fqdn1.treck.com) domain name to be given to the DHCPv6 server as a hint. To send a partial domain name instead (e.g., fqdn1), use TM_6_DEV_OPTIONS_DHCP_FQDN_PART. The DHCPv6 server is not required to respect this hint. Additional calls using this option will overwrite previous values. To reset this value, pass in an empty string (not a null pointer).

Default: Empty string (no hint is given to the server)

Data Type: char * (i.e., a string)

TM_6_DEV_OPTIONS_DHCP_FQDN_PART Identical to TM_6_DEV_OPTIONS_DHCP_FQDN_PART, except used for a partial name (e.g., fqdn1) rather than a fully qualified domain name (e.g., fqdn1.treck.com).
TM_6_DEV_OPTIONS_DHCP_FQDN_S_BIT Configures the "S" bit of the flags field of the FQDN option for DHCPv6. If set, the "S" bit instructs the server to perform AAAA RR DNS updates. If not set, the “S” bit indicates that the client will handle the updates. The server is not required to respect this request.

Default: 1 (server should handle updates)

Data Type: unsigned char

TM_6_DEV_OPTIONS_DHCP_FQDN_N_BIT Configures the "N" bit of the flags field of the FQDN option for DHCPv6. If set, the "N" bit instructs the server NOT to do any DNS updates. If cleared, the server will handle the PTR RR and possibly the AAAA RR (depending on the status of the "S" bit) updates. If the "N" bit is set to 1, the "S" bit must be set to 0.

Default: 0 (Server handles DNS updates)

Data Type: unsigned char

TM_DEV_OPTIONS_DHCP_SND_BIN_FQDN When set to 1, Treck will send the FQDN option in binary format when it is composed of at least one server-provided value. Default: 0 (Always use ASCII format when building the FQDN from at least one server-provided value)

Data Type: unsigned char

TM_DEV_OPTIONS_DHCP_FQDN_NOSPLIT Prevent a long DHCP FQDN option from being sent as multiple options. Set this interface option to 1 if your domain name is very long (more than 252 characters) and you are interacting with a DHCP server that does not support option concatenation. In this case, the long FQDN option will not be sent on this interface.

Data Type: unsigned char
Default: 0

TM_6_DEV_OPTIONS_NO_AUTOCONFIG When set to 1, IPv6 site-local and global address auto configuration is disabled. Default: 0 (Always perform site-local and global address auto configuration)

Data Type: unsigned char

TM_DEV_OPTIONS_DHCP_COLLECT_TIME Set the time limit in seconds that the interface will continue to collect DHCP offers after the first offer is received. Restrictions: Use prior to starting DHCP.

Data Type: int

Default: 15 seconds.

TM_DEV_OPTIONS_DHCP_COLLECT_CACHE Set the upper limit on the number of DHCP offers that can be held in the offer cache. Restrictions: Use prior to starting DHCP. Use with callback feature only.

Data Type: int

Default: 1.

TM_DEV_OPTIONS_DHCP_MIN_OVERLOAD If you enable the DHCP option overload feature by uncommenting TM_USE_DHCP_SEND_OVERLOAD in trsystem.h, you can change the default overload threshold. By default, when option overloading is enabled, DHCP messages that exceed 548 bytes in length (more than 312 bytes of options) will be subject to option overloading (some options will be moved to the unused sname and file fields to shrink the overall message size).

Data Type: int

Default: 548 (can be overridden by defining TM_DHCP_SEND_OVERLOAD_THRESHOLD in trsystem.h).

TM_6_DEV_OPTIONS_NO_INIT_DELAY If set to a non-zero value, this option will prevent Treck from delaying before sending the Neighbor Advertisement messages for a newly configured address. Also, it will prevent Treck from sending Router Solicitation messages. This behavior violates the RFC.

If set to zero, this option will cause Treck to comply with the RFC and insert a delay before sending the Neighbor Advertisement for the newly configured address. Furthermore, it will cause Treck to send Router Solicitation messages.

TM_6_DEV_OPTIONS_DAD_NO_WAIT Typically, Duplicate Address Detection (DAD) of a new address (see RFC 4861 and RFC 4862) requires a node to send Neighbor Solicitation and Advertisement messages, each separated by a 1 second delay to allow another node with the same address to respond. This option allows the user to remove the delay between the two messages. This behavior violates the RFC.

Set this option to zero (the default) for normal operation. Set it non-zero if you need to use the address immediately and have confidence in your node's right to use the address, as might be the case after a reboot or wakeup from a low power sleep.

This option affects only the interface's link-local autoconfigured address and any address manually configured with the TM_6_DEV_IP_TEMPORARY or TM_6_DEV_IP_FAST_BOOT options (see tfNgOpenInterface()).

To use this option, you must compile with macros TM_6_USE_DAD and TM_6_DAD_ALLOW_NO_WAIT defined in your trsystem.h file.

This option does not affect the initial delay prior to starting DAD. For that, you would also need to set the TM_6_DEV_OPTIONS_NO_INIT_DELAY option, mentioned above.

Data Type: unsigned char

Default: 0

TM_6_DEV_OPTIONS_NO_DEST_UNREACH Disable ICMP destination unreachable messages. This option has been added for ICMPv6 to support the following requirement in RFC 4443 section 3.1: "For security reasons, it is recommended that implementations SHOULD allow sending of ICMP destination unreachable messages to be disabled, preferably on a per-interface basis."
TM_DEV_OPTIONS_IP_PROMISCUOUS The user can use this option when calling tfInterfaceSetOptions() to enable/disable promiscuous mode at the IP level on the given device. The user can also use this option when calling tfInterfaceGetOptions() to retrieve the current status of the IP-level promiscuous mode setting for the device.

Data Type: unsigned char

Default: 0 (disabled)

TM_DEV_OPTIONS_FORWARD_REFLECT The user can use this option when calling tfInterfaceSetOptions() to enable/disable forwarding (reflecting) of packets to the same device on which the packets were received. The user can also use this option when calling tfInterfaceGetOptions() to retrieve the current status for the device.
TM_6_DEV_OPTIONS_IP_PROMISCUOUS The user can use this option when calling tfInterfaceSetOptions() to enable/disable promiscuous mode at the IPv6 level on the given device. The user can also use this option when calling tfInterfaceGetOptions() to retrieve the current status of the IPv6-level promiscuous mode setting for the device.

Data Type: unsigned char

Default: 0 (disabled)

TM_6_DEV_OPTIONS_FILTER Determines whether Filtering is enabled or disabled on the given interface for both incoming and outgoing packets.

Data Type: unsigned char

Default: 0 (disabled)

TM_6_DEV_OPTIONS_FILTER_INCOMING Determines whether Filtering is enabled or disabled on the given interface for incoming packets.

Data Type: unsigned char

Default: 0 (disabled)

TM_6_DEV_OPTIONS_FILTER_OUTGOING Determines whether Filtering is enabled or disabled on the given interface for outgoing packets.

Data Type: unsigned char

Default: 0 (disabled)

TM_6_DEV_OPTIONS_NO_DHCP_CONF When acquiring an IPv4 address via DHCP/BOOTP, do not automatically configure an IPv4-compatible IPv6 address.
TM_6_DEV_OPTIONS_USE_TEMPADDR Set the level of support for RFC 4941, Privacy Extensions for Stateless Address Autoconfiguration in IPv6. Refer to the Main Article for details on this feature. Acceptable values for this option are:
  • TM_6_OPTION_TEMPADDR_DISABLE (0) - Temporary addresses will not be generated for this interface.
  • TM_6_OPTION_TEMPADDR_ENABLE (1) - Temporary addresses will be generated but public addresses will be used in preference to temporary addresses.
  • TM_6_OPTION_TEMPADDR_PREFER (2) - Temporary addresses will be generated and used in preference to public addresses.

Associated Treck option: TM_6_OPTION_USE_TEMPADDR
Data Type: int
Default: TM_6_OPTION_TEMPADDR_DISABLE unless changed via tfInitTreckOptions() or tfSetTreckOptions()

TM_6_DEV_OPTIONS_TEMP_VALID_LFT Time from creation (seconds) that an autoconfigured temporary address remains valid. An address is removed from the interface when it becomes invalid. If you increase this number you should increase TM_6_MAX_TEMP_IPS_PER_IF.

Associated Treck option: TM_6_OPTION_TEMP_VALID_LFT
Data Type: ttUser32Bit
Default: 7 days unless changed via tfInitTreckOptions() or tfSetTreckOptions()

TM_6_DEV_OPTIONS_TEMP_PREFER_LFT Time from creation (seconds) that an autoconfigured temporary address remains preferred. This determines the rate at which preferred addresses become deprecated and new addresses are created. If you decrease this number you should increase TM_6_MAX_TEMP_IPS_PER_IF.

Associated Treck option: TM_6_OPTION_TEMP_PREFER_LFT
Data Type: ttUser32Bit
Default: 1 day unless changed via tfInitTreckOptions() or tfSetTreckOptions()

TM_6_DEV_OPTIONS_TEMP_MAX_DESYNC Maximum desynchronizing factor (seconds) for autoconfiguring temporary addresses. The desynchronizing factor is a randomly chosen value subtracted from the preferred lifetime to help reduce network congestion caused by simultaneous autoconfiguration of multiple interfaces.

Associated Treck option: TM_6_OPTION_TEMP_MAX_DESYNC
Data Type: ttUser32Bit
Default: 10 minutes unless changed via tfInitTreckOptions() or tfSetTreckOptions()

TM_6_DEV_OPTIONS_TEMP_MAX_RETRY Maximum attempts to generate and autoconfigure a valid temporary address. This is a limit on the number of consecutive Duplicate Address Detection failures. If this limit is reached, temporary address generation will be disabled for the interface.

Associated Treck option: TM_6_OPTION_TEMP_MAX_RETRY
Data Type: int
Default: 3 attempts unless changed via tfInitTreckOptions() or tfSetTreckOptions()

TM_6_DEV_OPTIONS_TEMP_SET_FILT Set or update a prefix filter. You can enable or disable temporary address autoconfiguration on an interface for one or more specific prefixes.

Data Type: tt6TempPrefixFilter
Default: temporary address autoconfiguration is not disabled for any specific prefixes

TM_6_DEV_OPTIONS_TEMP_RESET_FILT Purge the list of prefix filters. The option value is not used.
TM_6_DEV_OPTIONS_MLD_ROBUSTNESS Change the MLDv2 Robustness Variable for a given interface. The Robustness Variable controls the number of Multicast Listener State Change Reports sent per change. Set this value greater than the number of consecutive lost packets you expect on a link. Never set it less than 2.

Data Type: unsigned char
Default: 2

Example Code for Turning On the Usage of the Transmit Task

unsigned short optionValue;
 
optionValue = 1; /* turn option on */
 
errorCode = tfInterfaceSetOptions(myInterfaceHandle,
                                  TM_DEV_OPTIONS_XMIT_TASK,
                                  &optionValue,
                                  sizeof(unsigned short));


Parameters

  • interfaceHandle
    The interface handle of the interface to set the option on.
  • optionName
    The option to set. (See above.)
  • optionValuePtr
    The pointer to a user variable into which the option value is set. User variable is of data type described above.
  • optionLength
    The size of the user variable, which is the size of the option data type.


Returns

  • TM_ENOERROR
    Success.
  • TM_EINVAL
    Invalid optionName; invalid optionLength; or invalid optionValue for the option.
  • TM_EPERM
    If the option is TM_DEV_OPTIONS_RECV_COPY then this indicates that the interface/device is a Point-to-Point interface. If the option is TM_DEV_OPTIONS_XMIT_TASK then this indicates that the interface/device is already configured/opened or the interface/device transmit queue is used.


Table of Contents >> Programmer's Reference