Network Component  Version 7.10.0
MDK Middleware for IPv4 and IPv6 Networking
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Common Interface API

Generic functions for all kinds of interfaces help to get or set interface options. More...

Content

 Enumerations
 Common enumerations for all Interfaces.
 

Functions

netStatus netIF_GetOption (uint32_t if_id, netIF_Option option, uint8_t *buf, uint32_t buf_len)
 Get the current value of an Interface option. [thread-safe]. More...
 
netStatus netIF_SetOption (uint32_t if_id, netIF_Option option, const uint8_t *buf, uint32_t buf_len)
 Set the value of an Interface option. [thread-safe]. More...
 
netStatus netIF_SetDefault (uint32_t if_id, netIF_Version ip_version)
 Set default network interface for Internet access. [thread-safe]. More...
 

Description

Generic functions for all kinds of interfaces help to get or set interface options.

These functions are used to read various interface settings (such as the IP4 address, subnet mask, default gateway etc.), and to change these settings at run time. For example, you can read the IP address assigned via DHCP using the netIF_GetOption function, or change a static IP address using the netIF_SetOption function.

Function Documentation

netStatus netIF_GetOption ( uint32_t  if_id,
netIF_Option  option,
uint8_t *  buf,
uint32_t  buf_len 
)

Get the current value of an Interface option. [thread-safe].

Parameters
[in]if_idInterface identification (class and number).
[in]optionInterface option as specified by netIF_Option.
[out]bufbuffer to store the option value to.
[in]buf_lenlength of buffer.
Returns
status code that indicates the execution status of the function.

The function netIF_GetOption retrieves the current value of an option for the interface specified by if_id.

The argument if_id is composed of the network interface class identifier and an interface number (or-ed). The interface class identifier is specified with the following defines:

The argument buf points to a buffer that will be used to store the value of the option.

The argument buf_len specifies the length of the buffer buf.

Possible netStatus return values:

  • netOK: Option retrieved successfully.
  • netInvalidParameter: Invalid parameter or not supported option provided.

Code Example

uint8_t ip4_addr[NET_ADDR_IP4_LEN];
netIF_GetOption (NET_IF_CLASS_ETH | 0, netIF_OptionIP4_Address, ip4_addr, sizeof (ip4_addr));
netStatus netIF_SetDefault ( uint32_t  if_id,
netIF_Version  ip_version 
)

Set default network interface for Internet access. [thread-safe].

Parameters
[in]if_idInterface identification (class and number).
[in]ip_versionIP version as specified by netIF_Version.
Returns
status code that indicates the execution status of the function.

The function netIF_SetDefault sets the default interface to the interface specified by if_id. The default interface is used for Internet access.

The argument if_id is composed of the network interface class identifier and an interface number (or-ed). The interface class identifier is specified with the following defines:

The argument ip_version specifies the Internet Protocol version IPv4 or IPv6, for which the default interface is to be set.

Possible netStatus return values:

  • netOK: Default interface successfully set.
  • netInvalidParameter: Invalid parameter provided.

Code Example

// Use PPP interface for Internet access
netStatus netIF_SetOption ( uint32_t  if_id,
netIF_Option  option,
const uint8_t *  buf,
uint32_t  buf_len 
)

Set the value of an Interface option. [thread-safe].

Parameters
[in]if_idInterface identification (class and number).
[in]optionInterface option as specified by netIF_Option.
[in]bufbuffer containing the option value.
[in]buf_lenlength of buffer.
Returns
status code that indicates the execution status of the function.

The function netIF_SetOption sets different options for the interface identified by the argument if_id.

The argument if_id is composed of the network interface class identifier and an interface number (or-ed). The interface class identifier is specified with the following defines:

The argument option specifies the interface option that is to be set (see below).

The argument buf points to a buffer containing the value of the option to be set.

The argument buf_len specifies the actual length of the buffer buf and must match the length of the corresponding option as specified with argument option (see below).

Option Description Length
netIF_OptionMAC_Address Ethernet MAC Address 6 bytes
netIF_OptionVLAN_Identifier Ethernet VLAN Identifier 2 bytes
netIF_OptionIP4_MTU IPv4 Maximum Transmission Unit 2 bytes
netIF_OptionIP4_Address IPv4 Address 4 bytes
netIF_OptionIP4_SubnetMask IPv4 Subnet mask 4 bytes
netIF_OptionIP4_DefaultGateway IPv4 Default Gateway 4 bytes
netIF_OptionIP4_PrimaryDNS IPv4 Primary DNS 4 bytes
netIF_OptionIP4_SecondaryDNS IPv4 Secondary DNS 4 bytes
netIF_OptionIP6_MTU IPv6 Maximum Transmission Unit 2 bytes
netIF_OptionIP6_LinkLocalAddress IPv6 Link-local Address 16 bytes
netIF_OptionIP6_StaticAddress IPv6 Static Address 16 bytes
netIF_OptionIP6_DynamicAddress IPv6 Dynamic Address 16 bytes
netIF_OptionIP6_SubnetPrefixLengthIPv6 Subnet Prefix-length 1 byte
netIF_OptionIP6_DefaultGateway IPv6 Default Gateway 16 bytes
netIF_OptionIP6_PrimaryDNS IPv6 Primary DNS 16 bytes
netIF_OptionIP6_SecondaryDNS IPv6 Secondary DNS 16 bytes

Possible netStatus return values:

  • netOK: Option successfully set.
  • netInvalidParameter: Invalid parameter or not supported option provided.

The option netIF_OptionIP4_MTU sets the maximum transmission unit for the interface (MTU). The valid values for the MTU option depend on the network inteface and are as follows:

  • 576 - 1500 for Ethernet interface,
  • 576 - 1500 for PPP interface,
  • 296 - 1500 for SLIP interface.

IPv4 fragmentation is enabled if the option value is nonzero. Option value 0 disables IPv4 fragmentation.

The option netIF_OptionVLAN_Identifier sets the Virtual LAN for the Ethernet interface (VLAN). Valid VLAN ID is from 1 to 4093. Option value 0 disables VLAN.

Note
Ethernet MAC address setting fails if the multicast bit is set. Multicast bit is bit-0 of the first MAC address byte.

Code Example

uint8_t mac_addr[NET_ADDR_ETH_LEN] = { 0x1e, 0x30, 0x6c, 0xa2, 0x45, 0x5e };
uint16_t eth_mtu = 1480;
netIF_SetOption (NET_IF_CLASS_ETH | 0, netIF_OptionMAC_Address, mac_addr, sizeof (mac_addr));
netIF_SetOption (NET_IF_CLASS_ETH | 0, netIF_OptionIP4_MTU, (uint8_t *)&eth_mtu, sizeof (eth_mtu));