Network Component  Version 7.19.0
MDK Middleware for IPv4 and IPv6 Networking

Common functions for all Interfaces. More...

Typedefs

typedef void(* netARP_cb_t) (netARP_Event event)
 ARP Probe Event callback function. More...
 
typedef void(* netNDP_cb_t) (netNDP_Event event)
 NDP Probe Event callback function. More...
 

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...
 
netStatus netARP_CacheIP (uint32_t if_id, const uint8_t *ip4_addr, netARP_CacheType type)
 Determine whether the ARP table has MAC address resolved for requested IP address. [thread-safe]. More...
 
netStatus netARP_CacheMAC (uint32_t if_id, const uint8_t *mac_addr)
 Determine whether the ARP table has IP address resolved for requested MAC address. [thread-safe]. More...
 
netStatus netARP_GetIP (uint32_t if_id, const uint8_t *mac_addr, uint8_t *ip4_addr)
 Get IP address from the ARP cache. [thread-safe]. More...
 
netStatus netARP_GetMAC (uint32_t if_id, const uint8_t *ip4_addr, uint8_t *mac_addr)
 Get MAC address from the ARP cache. [thread-safe]. More...
 
netStatus netARP_Probe (uint32_t if_id, const uint8_t *ip4_addr, netARP_cb_t cb_func)
 Determine whether the IP address is already in use. [thread-safe]. More...
 
netStatus netARP_ProbeX (uint32_t if_id, const uint8_t *ip4_addr)
 Determine whether the IP address is already in use in blocking mode. [thread-safe]. More...
 
netStatus netARP_ClearCache (uint32_t if_id)
 Flush or clear the local ARP cache. [thread-safe]. More...
 
netStatus netIGMP_Join (uint32_t if_id, const uint8_t *ip4_addr)
 Join this host to a host group specified with IP address. [thread-safe]. More...
 
netStatus netIGMP_Leave (uint32_t if_id, const uint8_t *ip4_addr)
 Leave a host group specified with IP address. [thread-safe]. More...
 
netStatus netDHCP_Enable (uint32_t if_id)
 Enable Dynamic Host Configuration at runtime. [thread-safe]. More...
 
netStatus netDHCP_Disable (uint32_t if_id)
 Disable Dynamic Host Configuration at runtime. [thread-safe]. More...
 
netStatus netDHCP_SetOption (uint32_t if_id, uint8_t option, const uint8_t *val, uint32_t len)
 Set DHCP Option value at runtime. [thread-safe]. More...
 
netStatus netNBNS_Resolve (uint32_t if_id, const char *name, uint8_t *ip4_addr)
 Resolve IP address of a host from a NetBIOS hostname. [thread-safe]. More...
 
netStatus netNBNS_ClearCache (uint32_t if_id)
 Flush or clear the local NBNS cache. [thread-safe]. More...
 
netStatus netNDP_CacheIP (uint32_t if_id, const uint8_t *ip6_addr)
 Determine whether neighbor cache has MAC address resolved for requested IP address. [thread-safe]. More...
 
netStatus netNDP_GetIP (uint32_t if_id, const uint8_t *mac_addr, uint8_t *ip6_addr)
 Get IP address from neighbor discovery cache. [thread-safe]. More...
 
netStatus netNDP_GetMAC (uint32_t if_id, const uint8_t *ip6_addr, uint8_t *mac_addr)
 Get MAC address from neighbor discovery cache. [thread-safe]. More...
 
netStatus netNDP_Probe (uint32_t if_id, const uint8_t *ip6_addr, netNDP_cb_t cb_func)
 Determine whether the IP address is already in use. [thread-safe]. More...
 
netStatus netNDP_ProbeX (uint32_t if_id, const uint8_t *ip6_addr)
 Determine whether the IP address is already in use in blocking mode. [thread-safe]. More...
 
netStatus netNDP_ClearCache (uint32_t if_id)
 Flush or clear the local NDP cache. [thread-safe]. More...
 
netStatus netDHCP6_Enable (uint32_t if_id, netDHCP6_Mode mode)
 Enable Dynamic Host Configuration version 6 at runtime. [thread-safe]. More...
 
netStatus netDHCP6_Disable (uint32_t if_id)
 Disable Dynamic Host Configuration version 6 at runtime. [thread-safe]. More...
 
netStatus netICMP_SetNoEcho (uint32_t if_id, bool no_echo)
 Enable or disable ICMP Echo response. [thread-safe]. More...
 
netStatus netICMP6_SetNoEcho (uint32_t if_id, bool no_echo)
 Enable or disable ICMPv6 Echo response. [thread-safe]. More...
 

Description

Common functions for all Interfaces.

In the Network Component, the Common interface API is responsible for various Application/Internet/Link layer protocols such as ARP, NDP, IGMP, and DHCP. In the Network Component v7, these protocols are supported for IPv4 and IPv6 connections (where applicable).

Typedef Documentation

◆ netARP_cb_t

void(* netARP_cb_t)(netARP_Event event)

ARP Probe Event callback function.

Parameters
[in]event- Probe event as defined in netARP_Event.
Returns
none.

Is the type definition for the Probe callback function. Users must provide the function. The callback function uses the event argument to signal one of the following Probe events:

Event Description
netARP_EventSuccess Remote host responded to ARP probe.
netARP_EventTimeout Probe session has timed out, remote host did not respond.

Parameter for:

◆ netNDP_cb_t

void(* netNDP_cb_t)(netNDP_Event event)

NDP Probe Event callback function.

Parameters
[in]event- Probe event as defined in netNDP_Event.
Returns
none.

Is the type definition for the Probe callback function. Users must provide the function. The callback function uses the event argument to signal one of the following Probe events:

Event Description
netNDP_EventSuccess Remote host responded to NDP probe.
netNDP_EventTimeout Probe session has timed out, remote host did not respond.

Parameter for:

Function Documentation

◆ netARP_CacheIP()

netStatus netARP_CacheIP ( uint32_t  if_id,
const uint8_t *  ip4_addr,
netARP_CacheType  type 
)

Determine whether the ARP table has MAC address resolved for requested IP address. [thread-safe].

Parameters
[in]if_idInterface identification (class and number).
[in]ip4_addrrequested IPv4 address.
[in]typeaddress cache type.
Returns
status code that indicates the execution status of the function.

The function netARP_CacheIP determines whether the ARP table has a MAC (Ethernet) address entry for the requested IP address. If an entry does not exist, the function forces the Network Core to resolve and cache the MAC address into the internal ARP table buffer. To resolve the MAC address, the Network Core sends an ARP request to the network.

The argument if_id is the Interface Identification number for which to check the ARP table.

The argument ip4_addr points to a buffer containing the four octets of the dotted decimal IPv4 address to be resolved.

The argument type specifies whether the IP address is fixed or temporary. This consequently determines whether or not the Network Core automatically refreshes the IP address entry in the ARP cache.

Type Description
netARP_CacheTemporaryIP The IP address is temporary, and thus Network removes the IP address entry from the ARP cache after a timeout.
netARP_CacheFixedIP The IP address is fixed, and thus Network's ARP module automatically refreshes the IP address entry after the timeout.

Possible netStatus return values:

  • netOK: MAC address resolved successfully.
  • netInvalidParameter: Invalid parameter provided.
  • netBusy: MAC address resolving in progress.
  • netError: Gateway IP address is undefined.
Note
  • This function can only be used with IPv4. For IPv6 similar functionality is provided by netNDP_CacheIP.
  • Only the Ethernet and WiFi interfaces use the netARP_CacheIP function. There is no ARP protocol for the PPP or SLIP interface.

Code Example

uint8_t mac_addr [NET_ADDR_ETH_LEN];
uint8_t ip4_addr [NET_ADDR_IP4_LEN];
..
netIP_aton ("192.168.0.100", NET_ADDR_IP4, ip4_addr);
while (netARP_GetMAC (NET_IF_CLASS_ETH | 0, ip4_addr, mac_addr) != netOK) {
// Requested IP address not yet cached
osDelay (1000);
}

◆ netARP_CacheMAC()

netStatus netARP_CacheMAC ( uint32_t  if_id,
const uint8_t *  mac_addr 
)

Determine whether the ARP table has IP address resolved for requested MAC address. [thread-safe].

Parameters
[in]if_idInterface identification (class and number).
[in]mac_addrrequested MAC address.
Returns
status code that indicates the execution status of the function.

The function netARP_CacheMAC determines whether the ARP table has an IP address entry for the requested MAC (Ethernet) address mac_addr. If an entry does not exist, the function forces the Network Core to resolve and cache the IP address into the internal ARP table buffer. To resolve the IP address, the Network Core sends an inverse ARP request to the network.

The argument if_id is the Interface Identification number for which to check the ARP table.

The argument mac_addr points to a buffer containing the six octets of the MAC address to be resolved.

Possible netStatus return values:

  • netOK: IP address resolved successfully.
  • netInvalidParameter: Invalid parameter provided.
  • netBusy: IP address resolving in progress.
  • netError: Local IP address is undefined.
Note
  • This function can only be used with IPv4. There is no similar functionality for IPv6.
  • Only the Ethernet and WiFi interfaces use the netARP_CacheMAC function. There is no ARP protocol for the PPP or SLIP interface.

Code Example

uint8_t mac_addr [NET_ADDR_ETH_LEN];
uint8_t ip4_addr [NET_ADDR_IP4_LEN];
..
netMAC_aton ("1E-30-6C-A2-45-5E", mac_addr);
if (netARP_GetIP (NET_IF_CLASS_ETH | 0, mac_addr, ip4_addr) != netOK) {
// Requested MAC address not yet cached
}

◆ netARP_ClearCache()

netStatus netARP_ClearCache ( uint32_t  if_id)

Flush or clear the local ARP cache. [thread-safe].

Parameters
[in]if_idInterface identification (class and number).
Returns
status code that indicates the execution status of the function.

The function netARP_ClearCache flushes all resolved MAC addresses from the local ARP cache. You can use this function when the cache holds outdated values that are no longer valid.

The argument if_id is the Interface Identification number for which to clear the ARP cache table.

Possible netStatus return values:

  • netOK: Operation completed successfully.
  • netInvalidParameter: Invalid parameter provided.
  • netBusy: ARP internal process is in progress.
Note
  • This function can only be used with IPv4. For IPv6 similar functionality is provided by netNDP_ClearCache.
  • Only the Ethernet and WiFi interfaces use the netARP_ClearCache function. There is no ARP protocol for the PPP or SLIP interface.

Code Example

// All entries flushed from ARP cache for ETH0 interface
}

◆ netARP_GetIP()

netStatus netARP_GetIP ( uint32_t  if_id,
const uint8_t *  mac_addr,
uint8_t *  ip4_addr 
)

Get IP address from the ARP cache. [thread-safe].

Parameters
[in]if_idInterface identification (class and number).
[in]mac_addrrequested MAC address.
[out]ip4_addrresolved IPv4 address.
Returns
status code that indicates the execution status of the function.

The function netARP_GetIP determines the resolved IP address for a specific MAC address.

The argument if_id is the Interface Identification number for which to check the ARP table.

The argument mac_addr points to a buffer containing the six octets of the MAC address to be resolved.

The argument ip4_addr points to a buffer that stores the resolved IPv4 address.

Possible netStatus return values:

  • netOK: IP address copied to a buffer.
  • netInvalidParameter: Invalid parameter provided.
  • netError: Requested MAC address not found in ARP table.

Refer to

Note
  • This function can only be used with IPv4. For IPv6 similar functionality is provided by netNDP_GetIP.
  • Only the Ethernet and WiFi interfaces use the netARP_GetIP function. There is no ARP protocol for the PPP or SLIP interface.

Code Example (see netARP_CacheMAC)

◆ netARP_GetMAC()

netStatus netARP_GetMAC ( uint32_t  if_id,
const uint8_t *  ip4_addr,
uint8_t *  mac_addr 
)

Get MAC address from the ARP cache. [thread-safe].

Parameters
[in]if_idInterface identification (class and number).
[in]ip4_addrrequested IPv4 address.
[out]mac_addrresolved MAC address.
Returns
status code that indicates the execution status of the function.

The function netARP_GetMAC determines the resolved MAC address for a specific IP address.

The argument if_id is the Interface Identification number for which to check the ARP table.

The argument ip4_addr points to a buffer containing four octets of the dotted decimal IPv4 address to be resolved.

The argument mac_addr points to a buffer that stores the resolved six octets of the MAC address.

Possible netStatus return values:

  • netOK: MAC address copied to a buffer.
  • netInvalidParameter: Invalid parameter provided.
  • netError: Requested IP address not found in ARP table.

Refer to

Note
  • This function can only be used with IPv4. For IPv6 similar functionality is provided by netNDP_GetMAC.
  • Only the Ethernet and WiFi interfaces use the netARP_GetMAC function. There is no ARP protocol for the PPP or SLIP interface.

Code Example

uint8_t ip4_addr [NET_ADDR_IP4_LEN] = { 192, 168, 0, 100 };
uint8_t mac_addr [NET_ADDR_ETH_LEN];
char addr_ascii[18];
..
if (netARP_GetMAC (NET_IF_CLASS_ETH | 0, ip4_addr, mac_addr) == netOK) {
netIP_ntoa (NET_ADDR_IP4, ip4_addr, addr_ascii, sizeof (addr_ascii));
printf ("Requested IP address: %s\n", addr_ascii);
netMAC_ntoa (mac_addr, addr_ascii, sizeof (addr_ascii));
printf ("Cached MAC address: %s\n", addr_ascii);
}

◆ netARP_Probe()

netStatus netARP_Probe ( uint32_t  if_id,
const uint8_t *  ip4_addr,
netARP_cb_t  cb_func 
)

Determine whether the IP address is already in use. [thread-safe].

Parameters
[in]if_idInterface identification (class and number).
[in]ip4_addrrequested IPv4 address.
[in]cb_funccallback function to call, when probe session ends.
Returns
status code that indicates the execution status of the function.

The function netARP_Probe determines whether the requested IPv4 address is already used in local area network. You can use this function to check for IPv4 address collisions.

The argument if_id is the Interface Identification number for which to check the IPv4 address.

The argument ip4_addr points to a buffer containing four octets of the dotted decimal IPv4 address to be checked.

The argument cb_func points to an event callback function called by the Network Core when the probe session ends. Refer to netARP_cb_t.

Possible netStatus return values:

  • netOK: Probe process started successfully.
  • netInvalidParameter: Invalid parameter provided.
  • netBusy: Probe process is busy.

Refer to

Note
  • This function can only be used with IPv4. For IPv6 similar functionality is provided by netNDP_Probe.
  • Only the Ethernet and WiFi interfaces use the netARP_Probe function. There is no ARP protocol for the PPP or SLIP interface.

Code Example

uint8_t ip4_addr[NET_ADDR_IP4_LEN] = { 192, 168, 0, 100 };
static void probe_callback (netARP_Event event) {
switch (event) {
printf ("Response received, IP address is in use.\n");
break;
printf ("Probe timeout, no response.\n");
break;
}
}
..
if (netARP_Probe (NET_IF_CLASS_ETH | 0, ip4_addr, probe_callback) == netOK) {
printf("Probe started.\n");
}
else {
printf("Probe not ready or bad parameters.\n");
}

◆ netARP_ProbeX()

netStatus netARP_ProbeX ( uint32_t  if_id,
const uint8_t *  ip4_addr 
)

Determine whether the IP address is already in use in blocking mode. [thread-safe].

Parameters
[in]if_idInterface identification (class and number).
[in]ip4_addrrequested IPv4 address.
Returns
status code that indicates the execution status of the function.

The blocking function netARP_ProbeX determines whether the requested IPv4 address is already used in local area network. You can use this function to check for IPv4 address collisions.

The argument if_id is the Interface Identification number for which to check the IPv4 address.

The argument ip4_addr points to a buffer containing four octets of the dotted decimal IPv4 address to be checked.

Possible netStatus return values:

  • netOK: Response received, IP address is in use.
  • netTimeout: Probe timeout, no reponse received.

Refer to

Note
  • This function can only be used with IPv4. For IPv6 similar functionality is provided by netNDP_ProbeX.
  • Only the Ethernet and WiFi interfaces use the netARP_ProbeX function. There is no ARP protocol for the PPP or SLIP interface.

Code Example

uint8_t ip4_addr[NET_ADDR_IP4_LEN] = { 192, 168, 0, 100 };
if (netARP_ProbeX (NET_IF_CLASS_ETH | 0, ip4_addr) == netOK) {
printf ("Response received, IP address is in use.\n");
}
else {
printf ("Probe timeout, no response received.\n");
}

◆ netDHCP6_Disable()

netStatus netDHCP6_Disable ( uint32_t  if_id)

Disable Dynamic Host Configuration version 6 at runtime. [thread-safe].

Parameters
[in]if_idInterface identification (class and number).
Returns
status code that indicates the execution status of the function.

The function netDHCP6_Disable permanently disables the DHCPv6 service at runtime. To enable the DHCPv6 client again, you must call netDHCP6_Enable.

The argument if_id specifies the Interface Identification number for which DHCPv6 is to be disabled.

Possible netStatus return values:

  • netOK: DHCPv6 client disabled successfully.
  • netInvalidParameter: Invalid interface number provided.
Note
  • You can use the function only when the Dynamic Host Configuration for IPv6 is enabled in the Net_Config_ETH_n.h or Net_Config_WiFi_n.h configuration file.
  • The DHCPv6 service works for IPv6 only.

Code Example

if (use_dhcp6 == false)
// Use a pre-defined static IP address
}
else {
// Use DHCPv6 assigned IP address, stateful mode
}

◆ netDHCP6_Enable()

netStatus netDHCP6_Enable ( uint32_t  if_id,
netDHCP6_Mode  mode 
)

Enable Dynamic Host Configuration version 6 at runtime. [thread-safe].

Parameters
[in]if_idInterface identification (class and number).
[in]modeDHCPv6 operation mode.
Returns
status code that indicates the execution status of the function.

The function netDHCP6_Enable enables the DHCPv6 service at runtime.

The argument if_id specifies the Interface Identification number for which DHCPv6 is to be enabled.

The argument mode specifies whether DHCPv6 client runs in stateful mode with IPv6 address assignment, or in stateless mode with no IPv6 address assignment. In stateless mode, DHCPv6 client obtains only additional information, such as DNS name servers.

Possible netStatus return values:

  • netOK: DHCPv6 client enabled successfully.
  • netInvalidParameter: Invalid interface number provided.
  • netError: DHCPv6 client internal error.
Note
  • If you set the NET_START_SERVICE to 1 in Net_Config.c, all selected services will be started automatically. Thus, you only need to call this function, if you have either stopped the DHCPv6 service previously using netDHCP6_Disable or have set NET_START_SERVICE to 0.
  • The DHCPv6 service works for IPv6 only.

Code Example (see netDHCP6_Disable)

◆ netDHCP_Disable()

netStatus netDHCP_Disable ( uint32_t  if_id)

Disable Dynamic Host Configuration at runtime. [thread-safe].

Parameters
[in]if_idInterface identification (class and number).
Returns
status code that indicates the execution status of the function.

The function netDHCP_Disable permanently disables the DHCP service at runtime. To enable the DHCP client again, you must call netDHCP_Enable.

The argument if_id specifies the Interface Identification number for which DHCP is to be disabled.

Possible netStatus return values:

  • netOK: DHCP client disabled successfully.
  • netInvalidParameter: Invalid interface number provided.
Note
  • You can use the function only when the Dynamic Host Configuration for IPv4 is enabled in the Net_Config_ETH_n.h or Net_Config_WiFi_n.h configuration file.
  • The DHCP service works for IPv4 only.

Code Example

if (use_dhcp == false)
// Use a pre-defined static IP address
}
else {
// Use DHCP assigned IP address
}

◆ netDHCP_Enable()

netStatus netDHCP_Enable ( uint32_t  if_id)

Enable Dynamic Host Configuration at runtime. [thread-safe].

Parameters
[in]if_idInterface identification (class and number).
Returns
status code that indicates the execution status of the function.

The function netDHCP_Enable enables the DHCP service at runtime.

The argument if_id specifies the Interface Identification number for which DHCP is to be enabled.

Possible netStatus return values:

  • netOK: DHCP client enabled successfully.
  • netInvalidParameter: Invalid interface number provided.
  • netError: DHCP client internal error.
Note
  • If you set the NET_START_SERVICE to 1 in Net_Config.c, all selected services will be started automatically. Thus, you only need to call this function, if you have either stopped the DHCP service previously using netDHCP_Disable or have set NET_START_SERVICE to 0.
  • The DHCP service works for IPv4 only.

Code Example (see netDHCP_Disable)

◆ netDHCP_SetOption()

netStatus netDHCP_SetOption ( uint32_t  if_id,
uint8_t  option,
const uint8_t *  val,
uint32_t  len 
)

Set DHCP Option value at runtime. [thread-safe].

Parameters
[in]if_idInterface identification (class and number).
[in]optionDHCP option code.
[in]valpointer to option value.
[in]lenlength of option value in bytes.
Returns
status code that indicates the execution status of the function.

The function netDHCP_SetOption changes DHCP client options at runtime. To change a DHCP option, DHCP client must be disabled with a call to netDHCP_Disable, and enabled again after the call to netDHCP_SetOption with netDHCP_Enable.

The argument if_id specifies the Interface Identification number for which DHCP option is to be set.

The argument option specifies a DHCP option to be set. The following options are supported:

Option Description Minimum length
NET_DHCP_OPTION_CLIENT_ID Client-identifier option 2 bytes

The argument val is a pointer to user provided DHCP option value. If argument val is NULL, default DHCP option value is used instead of the user provided. Default DHCP Client-identifier option is Ethernet MAC address.

The argument len contains the length of the option value in bytes.

Possible netStatus return values:

  • netOK: Option successfully set.
  • netInvalidParameter: Invalid parameter provided.
  • netWrongState: DHCP client is running.
Note
  • You can use the function only when the Dynamic Host Configuration for IPv4 is enabled in the Net_Config_ETH_n.h or Net_Config_WiFi_n.h configuration file.
  • The DHCP service works for IPv4 only.

Code Example

// Type = 255, IAID = 01020304, DUID = 13169
uint8_t user_cid[] = { 0xFF, 1, 2, 3, 4, 0x33, 0x71 };

◆ netICMP6_SetNoEcho()

netStatus netICMP6_SetNoEcho ( uint32_t  if_id,
bool  no_echo 
)

Enable or disable ICMPv6 Echo response. [thread-safe].

Parameters
[in]if_idInterface identification (class and number).
[in]no_echonew state of NoEcho attribute:
  • true= disable ICMPv6 echo response,
  • false= enable ICMPv6 echo response.
Returns
status code that indicates the execution status of the function.

The function netICMP6_SetNoEcho enables or disables the Echo response on the interface at runtime.

The argument if_id specifies the Interface Identification number for which ICMPv6 Echo response mode is to be changed.

The argument no_echo switches the NoEcho response mode on (true) or off (false).

Possible netStatus return values:

  • netOK: Echo response mode changed successfully.
  • netInvalidParameter: Invalid interface number provided.

Code Example

// Disable IPv6 Echo response for ETH0

◆ netICMP_SetNoEcho()

netStatus netICMP_SetNoEcho ( uint32_t  if_id,
bool  no_echo 
)

Enable or disable ICMP Echo response. [thread-safe].

Parameters
[in]if_idInterface identification (class and number).
[in]no_echonew state of NoEcho attribute:
  • true= disable ICMP echo response,
  • false= enable ICMP echo response.
Returns
status code that indicates the execution status of the function.

The function netICMP_SetNoEcho enables or disables the Echo response on the interface at runtime.

The argument if_id specifies the Interface Identification number for which ICMP Echo response mode is to be changed.

The argument no_echo switches the NoEcho response mode on (true) or off (false).

Possible netStatus return values:

  • netOK: Echo response mode changed successfully.
  • netInvalidParameter: Invalid interface number provided.

Code Example

// Disable IPv4 Echo response for ETH0

◆ netIF_GetOption()

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 specifies the Interface Identification number.

The argument option specifies the interface option that is to be retrieved (see netIF_SetOption).

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));

◆ netIF_SetDefault()

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 specifies th Interface Identification number.

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

◆ netIF_SetOption()

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 specifies the Interface Identification number.

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_SubnetPrefixLength IPv6 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.
  • Link Local address setting is not possible, because the link local address is managed within the network library.

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));

◆ netIGMP_Join()

netStatus netIGMP_Join ( uint32_t  if_id,
const uint8_t *  ip4_addr 
)

Join this host to a host group specified with IP address. [thread-safe].

Parameters
[in]if_idInterface identification (class and number).
[in]ip4_addrgroup IPv4 address.
Returns
status code that indicates the execution status of the function.

The function netIGMP_Join requests that a host should become a member of the host group identified by ip4_addr.

The argument if_id is the Interface Identification number of the host.

The argument ip4_addr points to the address of the group. Before any datagrams destined to a particular group can be received, an upper-layer protocol must ask the IP module to join that group.

Possible netStatus return values:

  • netOK: Joining the group successful.
  • netInvalidParameter: Invalid parameter provided.
  • netError: No free entries in IGMP table.
Note
  • This function can only be used with IPv4. Currently, no similar functionality is provided for IPv6.
  • Only the Ethernet and WiFi interfaces use the netIGMP_Join function. There is no IGMP protocol for the PPP or SLIP interface.

Code Example

void Server_Thread (void *arg) {
SOCKADDR_IN recaddr;
int32_t sock, sd, res, addrlen;
int32_t type = (int32_t)arg;
char dbuf[10];
const uint8_t ip4_addr[NET_ADDR_IP4_LEN] = { 238, 0, 100, 1 };
char ip_ascii[16];
if (netIGMP_Join (NET_IF_CLASS_ETH | 0, ip4_addr) == netOK) {
netIP_ntoa (NET_ADDR_IP4, ip4_addr, ip_ascii, sizeof(ip_ascii));
printf ("This Host is a member of group: %s\n", ip_ascii);
}
else {
printf ("Failed to join a host group.\n");
}
while (1) {
// Setup network parameters
memset (&addr, 0, sizeof(addr));
// Accept only IPv4 connections
addr.sin_port = htons(SOCK_PORT);
// Create socket
sock = socket (addr.sin_family, type, 0);
// Bind address and port to socket
uint8_t mcast_ip1[NET_ADDR_IP4_LEN] = {239, 128, 0, 1};
addr.sin_addr.s_b1 = mcast_ip1[0];
addr.sin_addr.s_b2 = mcast_ip1[1];
addr.sin_addr.s_b3 = mcast_ip1[2];
addr.sin_addr.s_b4 = mcast_ip1[3];
bind (sock, (SOCKADDR *)&addr, sizeof(addr));
listen (sock, 1);
sd = accept (sock, NULL, NULL);
closesocket (sock);
sock = sd;
while (1) {
res = recv (sock, dbuf, sizeof (dbuf), 0);
if (res <= 0) {
break;
}
if (dbuf[0] == BLINKLED) {
LED_SetOut (dbuf[1]);
}
}
closesocket (sock);
}
}

◆ netIGMP_Leave()

netStatus netIGMP_Leave ( uint32_t  if_id,
const uint8_t *  ip4_addr 
)

Leave a host group specified with IP address. [thread-safe].

Parameters
[in]if_idInterface identification (class and number).
[in]ip4_addrgroup IPv4 address.
Returns
status code that indicates the execution status of the function.

The function netIGMP_Leave requests a host to give up its membership in a host group.

The argument if_id is the host Interface Identification number.

The argument ip4_addr points to the host group. After the upper-layer has requested to leave the host group, datagrams destined to a particular group can not be received, but are silently discarded by the IP-layer.

Possible netStatus return values:

  • netOK: Leaving the group successful.
  • netInvalidParameter: Invalid parameter provided.
  • netError: Not member of requested host group.
Note
  • This function can only be used with IPv4. Currently, no similar functionality is provided for IPv6.
  • Only the Ethernet and WiFi interfaces use the netIGMP_Leave function. There is no IGMP protocol for the PPP or SLIP interface.

Code Example

const uint8_t ip4_addr[NET_ADDR_IP4_LEN] = { 238, 0, 100, 1 };
char ip_ascii[16];
..
if (netIGMP_Leave (NET_IF_CLASS_ETH | 0, ip4_addr) == netOK) {
netIP_ntoa (NET_ADDR_IP4, ip4_addr, ip_ascii, sizeof(ip_ascii));
printf ("This Host has left the group: %s\n", ip_ascii);
}
else {
printf ("Failed to leave a group, this host is not a member.\n");
}

◆ netNBNS_ClearCache()

netStatus netNBNS_ClearCache ( uint32_t  if_id)

Flush or clear the local NBNS cache. [thread-safe].

Parameters
[in]if_idInterface identification (class and number).
Returns
status code that indicates the execution status of the function.

The function netNBNS_ClearCache flushes all resolved IP addresses from the local NBNS cache. You can use this function when the cache holds outdated values that are no longer valid.

The argument if_id is the Interface Identification number for which to clear the NBNS cache table.

Possible netStatus return values:

  • netOK: Operation completed successfully.
  • netInvalidParameter: Invalid parameter provided.
  • netError: NBNS protocol not enabled for this interface.
  • netBusy: NBNS internal process is in progress.
Note
  • This function can only be used with IPv4. Currently, no similar functionality is provided for IPv6.
  • Only the Ethernet and WiFi interfaces use the netNBNS_ClearCache function. There is no NBNS protocol for the PPP or SLIP interface.

Code Example

// All entries flushed from NBNS cache for ETH0 interface
}

◆ netNBNS_Resolve()

netStatus netNBNS_Resolve ( uint32_t  if_id,
const char *  name,
uint8_t *  ip4_addr 
)

Resolve IP address of a host from a NetBIOS hostname. [thread-safe].

Parameters
[in]if_idInterface identification (class and number).
[in]nameNetBIOS hostname, a null-terminated string.
[out]ip4_addrresolved IPv4 address.
Returns
status code that indicates the execution status of the function.

The blocking function netNBNS_Resolve resolves the IP address of a host from a host name on the local network. It starts the NBNS client, sends a broadcast request to all hosts that are on local network and returns the resolved IP address. If the host is already resolved and cached in local NBNS cache, the function returns immediately with the IP address.

The argument if_id is the host Interface Identification number.

The argument name is a pointer to a null-terminated string that specifies the host name. The argument name can also be "localhost" or the local system host name. In this case the NBNS client returns immediately with the loopback IP address: "127.0.0.1"

The argument ip4_addr specifies a user-provided address buffer that will receive the resolved IP address.

Possible netStatus return values:

  • netOK: Host name successfully resolved.
  • netInvalidParameter: Invalid parameter provided.
  • netError: NBNS protocol not enabled for this interface.
  • netBusy: NBNS client is busy.
  • netTimeout: Timed out with no response received.
Note
  • This function can only be used with IPv4. Currently, no similar functionality is provided for IPv6.
  • Only the Ethernet and WiFi interfaces use the netNBNS_Resolve function. There is no NBNS protocol for the PPP or SLIP interface.

Code Example

uint8_t ip4_addr[NET_ADDR_IP4_LEN];
char ip_ascii[16];
if (netNBNS_Resolve (NET_IF_CLASS_ETH | 0, "MCB4300", ip4_addr) == netOK) {
// Success, 'ip4_addr' holds resolved IP address
netIP_ntoa (NET_ADDR_IP4, ip4_addr, ip_ascii, sizeof(ip_ascii));
printf("IP Address: %s\n", ip_ascii);
}
else {
printf ("Error resolving host on local network.\n");
}

◆ netNDP_CacheIP()

netStatus netNDP_CacheIP ( uint32_t  if_id,
const uint8_t *  ip6_addr 
)

Determine whether neighbor cache has MAC address resolved for requested IP address. [thread-safe].

Parameters
[in]if_idInterface identification (class and number).
[in]ip6_addrrequested IPv6 address.
Returns
status code that indicates the execution status of the function.

The function netNDP_CacheIP determines whether the NDP table has already an entry for the requested IPv6 address ip6_addr. If an entry does not exist, the function forces the Network Core to resolve and cache the IP address into the internal NDP table buffer.

The argument if_id is the Interface Identification number for which to cache the NDP table.

The argument ip6_addr points to a buffer containing the IPv6 address.

Possible netStatus return values:

  • netOK: MAC address resolved successfully.
  • netInvalidParameter: Invalid parameter provided.
  • netError: Gateway IPv6 address is undefined.
Note
  • This function can only be used with IPv6. For IPv4 similar functionality is provided by netARP_CacheIP.
  • Only the Ethernet and WiFi interfaces use the netNDP_CacheIP function. There is no NDP protocol for the PPP or SLIP interface.

Code Example

uint8_t mac_addr [NET_ADDR_ETH_LEN];
uint8_t ip6_addr [NET_ADDR_IP6_LEN];
..
netIP_aton ("fe80::1c30:6cff:fea2:455e", NET_ADDR_IP6, ip6_addr);
if (netNDP_GetMAC (NET_IF_CLASS_ETH | 0, ip6_addr, mac_addr) != netOK) {
// Requested IP address not yet cached
netNDP_CacheIP (0, ip6_addr);
}

◆ netNDP_ClearCache()

netStatus netNDP_ClearCache ( uint32_t  if_id)

Flush or clear the local NDP cache. [thread-safe].

Parameters
[in]if_idInterface identification (class and number).
Returns
status code that indicates the execution status of the function.

The function netNDP_ClearCache flushes all resolved MAC addresses from the local NDP cache. You can use this function when the cache holds outdated values that are no longer valid.

The argument if_id is the Interface Identification number for which to clear the NDP cache table.

Possible netStatus return values:

  • netOK: Operation completed successfully.
  • netInvalidParameter: Invalid parameter provided.
  • netBusy: NDP internal process is in progress.
Note
  • This function can only be used with IPv6. For IPv4 similar functionality is provided by netARP_ClearCache.
  • Only the Ethernet and WiFi interfaces use the netNDP_ClearCache function. There is no NDP protocol for the PPP or SLIP interface.

Code Example

// All entries flushed from NDP cache for ETH0 interface
}

◆ netNDP_GetIP()

netStatus netNDP_GetIP ( uint32_t  if_id,
const uint8_t *  mac_addr,
uint8_t *  ip6_addr 
)

Get IP address from neighbor discovery cache. [thread-safe].

Parameters
[in]if_idInterface identification (class and number).
[in]mac_addrrequested MAC address.
[out]ip6_addrresolved IPv6 address.
Returns
status code that indicates the execution status of the function.

The function netNDP_GetIP determines the resolved IPv6 address for a specific MAC address.

The argument if_id is the Interface Identification number to be used.

The argument mac_addr points to a buffer containing the MAC address.

The argument ip6_addr points to a buffer that stores the resolved IPv6 address.

Possible netStatus return values:

  • netOK: IPv6 address copied to a buffer.
  • netInvalidParameter: Invalid parameter provided.
  • netError: Requested MAC address not found in NDP table.
Note
  • This function can only be used with IPv6. For IPv4 similar functionality is provided by netARP_GetIP.
  • Only the Ethernet and WiFi interfaces use the netNDP_GetIP function. There is no NDP protocol for the PPP or SLIP interface.

Code Example

uint8_t mac_addr [NET_ADDR_ETH_LEN];
uint8_t ip6_addr [NET_ADDR_IP6_LEN];
..
netMAC_aton ("1E-30-6C-A2-45-5E", mac_addr);
if (netNDP_GetIP (NET_IF_CLASS_ETH | 0, mac_addr, ip6_addr) == netOK) {
// MAC address found in ND cache
}

◆ netNDP_GetMAC()

netStatus netNDP_GetMAC ( uint32_t  if_id,
const uint8_t *  ip6_addr,
uint8_t *  mac_addr 
)

Get MAC address from neighbor discovery cache. [thread-safe].

Parameters
[in]if_idInterface identification (class and number).
[in]ip6_addrrequested IPv6 address.
[out]mac_addrresolved MAC address.
Returns
status code that indicates the execution status of the function.

The function netNDP_GetMAC determines the resolved MAC address for a specific IPv6 address.

The argument if_id is the Interface Identification number to be used.

The argument ip6_addr points to a buffer containing the IPv6 address.

The argument mac_addr points to a buffer that stores the resolved six octets of the MAC address.

Possible netStatus return values:

  • netOK: MAC address copied to a buffer.
  • netInvalidParameter: Invalid parameter provided.
  • netError: Requested IPv6 address not found in NDP table.
Note
  • This function can only be used with IPv6. For IPv4 similar functionality is provided by netARP_GetMAC.
  • Only the Ethernet and WiFi interfaces use the netNDP_GetMAC function. There is no NDP protocol for the PPP or SLIP interface.

Code Example

uint8_t ip6_addr [NET_ADDR_IP6_LEN];
uint8_t mac_addr [NET_ADDR_ETH_LEN];
char addr_ascii[40];
..
netIP_aton ("fe80::1c30:6cff:fea2:455e", NET_ADDR_IP6, ip6_addr);
if (netNDP_GetMAC (NET_IF_CLASS_ETH | 0, ip6_addr, mac_addr) == netOK) {
printf ("Requested IP address: %s\n", addr_ascii);
netMAC_ntoa (mac_addr, addr_ascii, sizeof (addr_ascii));
printf ("Resolved MAC address: %s\n", addr_ascii);
}

◆ netNDP_Probe()

netStatus netNDP_Probe ( uint32_t  if_id,
const uint8_t *  ip6_addr,
netNDP_cb_t  cb_func 
)

Determine whether the IP address is already in use. [thread-safe].

Parameters
[in]if_idInterface identification (class and number).
[in]ip6_addrrequested IPv6 address.
[in]cb_funccallback function to call, when probe session ends.
Returns
status code that indicates the execution status of the function.

The function netNDP_Probe determines whether the requested IPv6 address is already used in local area network. You can use this function to check for IPv6 address collisions.

The argument if_id is the Interface Identification number for which to check the IPv6 address.

The argument ip6_addr points to a buffer containing the IPv6 address to be checked.

The argument cb_func points to an event callback function called by the Network Core when the probe session ends. Refer to netNDP_cb_t.

Possible netStatus return values:

  • netOK: Probe process started successfully.
  • netInvalidParameter: Invalid parameter provided.
  • netBusy: Probe process is busy.

Refer to

Note
  • This function can only be used with IPv6. For IPv4 similar functionality is provided by netARP_Probe.
  • Only the Ethernet and WiFi interfaces use the netNDP_Probe function. There is no NDP protocol for the PPP or SLIP interface.

Code Example

uint8_t ip6_addr[NET_ADDR_IP6_LEN];
static void probe_callback (netNDP_Event event) {
switch (event) {
printf ("Response received, IP address is in use.\n");
break;
printf ("Probe timeout, no response.\n");
break;
}
}
..
netIP_aton ("fe80::1c30:6cff:fea2:455e", NET_ADDR_IP6, ip6_addr);
if (netNDP_Probe (NET_IF_CLASS_ETH | 0, ip6_addr, probe_callback) == netOK) {
printf("Probe started.\n");
}
else {
printf("Probe not ready or bad parameters.\n");
}

◆ netNDP_ProbeX()

netStatus netNDP_ProbeX ( uint32_t  if_id,
const uint8_t *  ip6_addr 
)

Determine whether the IP address is already in use in blocking mode. [thread-safe].

Parameters
[in]if_idInterface identification (class and number).
[in]ip6_addrrequested IPv6 address.
Returns
status code that indicates the execution status of the function.

The blocking function netNDP_ProbeX determines whether the requested IPv6 address is already used in local area network. You can use this function to check for IPv6 address collisions.

The argument if_id is the Interface Identification number for which to check the IPv6 address.

The argument ip6_addr points to a buffer containing the IPv6 address to be checked.

Possible netStatus return values:

  • netOK: Response received, IP address is in use.
  • netTimeout: Probe timeout, no reponse received.

Refer to

Note
  • This function can only be used with IPv6. For IPv4 similar functionality is provided by netARP_Probe.
  • Only the Ethernet and WiFi interfaces use the netNDP_Probe function. There is no NDP protocol for the PPP or SLIP interface.

Code Example

uint8_t ip6_addr[NET_ADDR_IP6_LEN];
netIP_aton ("fe80::1c30:6cff:fea2:455e", NET_ADDR_IP6, ip6_addr);
if (netNDP_ProbeX (NET_IF_CLASS_ETH | 0, ip6_addr) == netOK) {
printf ("Response received, IP address is in use.\n");
}
else {
printf ("Probe timeout, no response received.\n");
}