![]() |
Network Component
Version 7.5.0
MDK Middleware for IPv4 and IPv6 Networking
|
Functions of the Ethernet Interface. 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... | |
Enumerations | |
enum | netARP_Event { netARP_EventSuccess = 0, netARP_EventTimeout } |
ARP Probe Callback Events. More... | |
enum | netNDP_Event { netNDP_EventSuccess = 0, netNDP_EventTimeout } |
NDP Probe Callback Events. More... | |
Functions | |
netStatus | netARP_CacheIP (uint32_t if_num, 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_num, 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_num, 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_num, 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_num, const uint8_t *ip4_addr, netARP_cb_t cb_func) |
Determine whether the IP address is already in use. [thread-safe]. More... | |
netStatus | netNDP_CacheIP (uint32_t if_num, 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_num, 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_num, 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_num, const uint8_t *ip6_addr, netNDP_cb_t cb_func) |
Determine whether the IP address is already in use. [thread-safe]. More... | |
netStatus | netIGMP_Join (uint32_t if_num, 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_num, const uint8_t *ip4_addr) |
Leave a host group specified with IP address. [thread-safe]. More... | |
netStatus | netDHCP_Enable (uint32_t if_num) |
Enable Dynamic Host Configuration at runtime. [thread-safe]. More... | |
netStatus | netDHCP_Disable (uint32_t if_num) |
Disable Dynamic Host Configuration at runtime. [thread-safe]. More... | |
netStatus | netDHCP_SetOption (uint32_t if_num, uint8_t option, const uint8_t *val, uint32_t len) |
Set DHCP Option value at runtime. [thread-safe]. More... | |
netStatus | netDHCP6_Enable (uint32_t if_num, netDHCP6_Mode mode) |
Enable Dynamic Host Configuration version 6 at runtime. [thread-safe]. More... | |
netStatus | netDHCP6_Disable (uint32_t if_num) |
Disable Dynamic Host Configuration version 6 at runtime. [thread-safe]. More... | |
netStatus | netETH_SendRaw (uint32_t if_num, const uint8_t *buf, uint32_t len) |
Send raw Ethernet data. [thread-safe]. More... | |
Functions of the Ethernet Interface.
In the Network Component, the Ethernet 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).
To get or set Ethernet options, use the generic netIF_GetOption and netIF_SetOption. The available options are as follows:
Option | Description |
---|---|
netIF_OptionMAC_Address | Ethernet MAC Address |
netIF_OptionIP4_MTU | IPv4 Maximum Transmission Unit |
netIF_OptionIP4_Address | IPv4 Address |
netIF_OptionIP4_SubnetMask | IPv4 Subnet mask |
netIF_OptionIP4_DefaultGateway | IPv4 Default Gateway |
netIF_OptionIP4_PrimaryDNS | IPv4 Primary DNS |
netIF_OptionIP4_SecondaryDNS | IPv4 Secondary DNS |
netIF_OptionIP6_MTU | IPv6 Maximum Transmission Unit |
netIF_OptionIP6_LinkLocalAddress | IPv6 Link-local Address |
netIF_OptionIP6_StaticAddress | IPv6 Static Address |
netIF_OptionIP6_DynamicAddress | IPv6 Dynamic Address |
netIF_OptionIP6_SubnetPrefixLength | IPv6 Subnet Prefix-length |
netIF_OptionIP6_DefaultGateway | IPv6 Default Gateway |
netIF_OptionIP6_PrimaryDNS | IPv6 Primary DNS |
netIF_OptionIP6_SecondaryDNS | IPv6 Secondary DNS |
The callback function netETH_Notify informs the user application about state changes on the Ethernet link.
The Address Resolution Protocol (ARP) is used to resolve network layer (IP) addresses to link layer (MAC) addresses. It is being used in IPv4 networks only. In IPv6 networks, Neighbor Discovery Protocol (NDP) is used instead.
The Network Component provides five functions for ARP. Two functions are working on the ARP table, two functions actually resolve the IP or MAC address and one function that checks whether the IP address is already in use. netARP_CacheIP determines whether the ARP table has a MAC address resolved for a certain IP address. netARP_CacheMAC determines whether the ARP table has an IP address resolved for a certain MAC address. To retrieve the MAC address for an IP address from the ARP table, use netARP_GetMAC, while netARP_GetIP provides the IP address for a given MAC address. To verify that the IP address is not used in local area network, use netARP_Probe.
The Neighbor Discovery Protocol (NDP) operates on the link layer and is responsible for
It is available for IPv6 only.
The function netNDP_CacheIP checks if the NDP table has a MAC address resolved for a certain IPv6 address. To retrieve this MAC address, use netNDP_GetMAC. To retrieve an IPv6 address for any given MAC address, use netNDP_GetIP. To verify that the IPv6 address is not used in local area network, use netNDP_Probe.
The Internet Group Management Protocol (IGMP) is used to do IP Multicasting. This means that an IP datagram is sent to a "host group". A multicast datagram is delivered to all the members of its destination host group. IGMPv1 and IGMPv2 protocol specification are supported in the Network Component. It is available for IPv4 only.
To add a host to a certain host group, use netIGMP_Join. To leave a host group, netIGMP_Leave is used.
The Dynamic Host Configuration Protocol (DHCP) is used for dynamically distributing network configuration parameters, such as IP addresses for interfaces and services. Using DHCP, network nodes request IP addresses and networking parameters automatically from a DHCP server, eliminating the need to configure these settings manually (refer to IP Address Assignment for more information). Although DHCP is specified for IPv4 and IPv6 networks, the Network Component is only supporting IPv4 networks at the moment.
Like all services, the DHCP is normally started automatically if NET_START_SERVICE
is set to 1 in the Net_Config.c configuration file. If it is disabled, DHCP needs to be started manually in the user application using netDHCP_Enable. At runtime, it is always possible to stop DHCP using the function netDHCP_Disable. In this case, the Network Core will revert the IP address of the node to the static IP address specified in the Net_Config_ETH_n.h file.
The callback function netDHCP_Notify notifies the user application of DHCP events or extended DHCP options. This function is optional and not required for a default DHCP client configuration. However, if your application requires the ability to react on changes of the IP address, you need to implement this function in the user code.
void(* netARP_cb_t)(netARP_Event event) |
ARP Probe Event callback function.
[in] | event | - Probe event as defined in netARP_Event. |
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:
void(* netNDP_cb_t)(netNDP_Event event) |
NDP Probe Event callback function.
[in] | event | - Probe event as defined in netNDP_Event. |
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:
enum netARP_Event |
enum netNDP_Event |
netStatus netARP_CacheIP | ( | uint32_t | if_num, |
const uint8_t * | ip4_addr, | ||
netARP_CacheType | type | ||
) |
Determine whether the ARP table has MAC address resolved for requested IP address. [thread-safe].
[in] | if_num | interface_number. |
[in] | ip4_addr | requested IPv4 address. |
[in] | type | address cache type. |
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_num is the Ethernet interface 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. |
Code Example
netStatus netARP_CacheMAC | ( | uint32_t | if_num, |
const uint8_t * | mac_addr | ||
) |
Determine whether the ARP table has IP address resolved for requested MAC address. [thread-safe].
[in] | if_num | interface_number. |
[in] | mac_addr | requested MAC address. |
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_num is the Ethernet interface 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.
Code Example
netStatus netARP_GetIP | ( | uint32_t | if_num, |
const uint8_t * | mac_addr, | ||
uint8_t * | ip4_addr | ||
) |
Get IP address from the ARP cache. [thread-safe].
[in] | if_num | interface_number. |
[in] | mac_addr | requested MAC address. |
[out] | ip4_addr | resolved IPv4 address. |
The function netARP_GetIP determines the resolved IP address for a specific MAC address.
The argument if_num is the Ethernet interface 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.
Refer to
Code Example (see netARP_CacheMAC)
netStatus netARP_GetMAC | ( | uint32_t | if_num, |
const uint8_t * | ip4_addr, | ||
uint8_t * | mac_addr | ||
) |
Get MAC address from the ARP cache. [thread-safe].
[in] | if_num | interface_number. |
[in] | ip4_addr | requested IPv4 address. |
[out] | mac_addr | resolved MAC address. |
The function netARP_GetMAC determines the resolved MAC address for a specific IP address.
The argument if_num is the Ethernet interface 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.
Refer to
Code Example
netStatus netARP_Probe | ( | uint32_t | if_num, |
const uint8_t * | ip4_addr, | ||
netARP_cb_t | cb_func | ||
) |
Determine whether the IP address is already in use. [thread-safe].
[in] | if_num | interface_number. |
[in] | ip4_addr | requested IPv4 address. |
[in] | cb_func | callback function to call, when probe session ends. |
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_num is the Ethernet interface 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.
Refer to
Code Example
netStatus netDHCP6_Disable | ( | uint32_t | if_num | ) |
Disable Dynamic Host Configuration version 6 at runtime. [thread-safe].
[in] | if_num | interface_number. |
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_num specifies the Ethernet interface for which DHCPv6 is to be disabled.
Code Example
netStatus netDHCP6_Enable | ( | uint32_t | if_num, |
netDHCP6_Mode | mode | ||
) |
Enable Dynamic Host Configuration version 6 at runtime. [thread-safe].
[in] | if_num | interface_number. |
[in] | mode | DHCPv6 operation mode. |
The function netDHCP6_Enable enables the DHCPv6 service at runtime.
The argument if_num specifies the Ethernet interface 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.
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.Code Example (see netDHCP6_Disable)
netStatus netDHCP_Disable | ( | uint32_t | if_num | ) |
Disable Dynamic Host Configuration at runtime. [thread-safe].
[in] | if_num | interface_number. |
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_num specifies the Ethernet interface for which DHCP is to be disabled.
Code Example
netStatus netDHCP_Enable | ( | uint32_t | if_num | ) |
Enable Dynamic Host Configuration at runtime. [thread-safe].
[in] | if_num | interface_number. |
The function netDHCP_Enable enables the DHCP service at runtime.
The argument if_num specifies the Ethernet interface for which DHCP is to be enabled.
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.Code Example (see netDHCP_Disable)
netStatus netDHCP_SetOption | ( | uint32_t | if_num, |
uint8_t | option, | ||
const uint8_t * | val, | ||
uint32_t | len | ||
) |
Set DHCP Option value at runtime. [thread-safe].
[in] | if_num | interface_number. |
[in] | option | DHCP option code. |
[in] | val | pointer to option value. |
[in] | len | length of option value in bytes. |
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_num specifies the Ethernet interface 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.
Code Example
netStatus netETH_SendRaw | ( | uint32_t | if_num, |
const uint8_t * | buf, | ||
uint32_t | len | ||
) |
Send raw Ethernet data. [thread-safe].
[in] | if_num | interface_number. |
[in] | buf | buffer containing the data. |
[in] | len | length of data in bytes. |
The function netETH_SendRaw sends the raw ethernet data to a remote machine. The data must contain ethernet header and payload data. This allows the users to implement additional ethernet protocols, which are not supported by the network library.
The argument if_num specifies the Ethernet interface which is used for sending.
The argument buf points to a buffer containing ethernet raw data.
The argument len specifies the number of data bytes to send.
Code Example
netStatus netIGMP_Join | ( | uint32_t | if_num, |
const uint8_t * | ip4_addr | ||
) |
Join this host to a host group specified with IP address. [thread-safe].
[in] | if_num | interface_number. |
[in] | ip4_addr | group IPv4 address. |
The function netIGMP_Join requests that a host should become a member of the host group identified by ip4_addr.
The argument if_num is the interface 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.
Code Example
netStatus netIGMP_Leave | ( | uint32_t | if_num, |
const uint8_t * | ip4_addr | ||
) |
Leave a host group specified with IP address. [thread-safe].
[in] | if_num | interface_number. |
[in] | ip4_addr | group IPv4 address. |
The function netIGMP_Leave requests a host to give up its membership in a host group.
The argument if_num is the host interface 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.
Code Example
netStatus netNDP_CacheIP | ( | uint32_t | if_num, |
const uint8_t * | ip6_addr | ||
) |
Determine whether neighbor cache has MAC address resolved for requested IP address. [thread-safe].
[in] | if_num | interface_number. |
[in] | ip6_addr | requested IPv6 address. |
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_num is the Ethernet interface number for which to cache the NDP table.
The argument ip6_addr points to a buffer containing the IPv6 address.
Code Example
netStatus netNDP_GetIP | ( | uint32_t | if_num, |
const uint8_t * | mac_addr, | ||
uint8_t * | ip6_addr | ||
) |
Get IP address from neighbor discovery cache. [thread-safe].
[in] | if_num | interface_number. |
[in] | mac_addr | requested MAC address. |
[out] | ip6_addr | resolved IPv6 address. |
The function netNDP_GetIP determines the resolved IPv6 address for a specific MAC address.
The argument if_num is the Ethernet interface 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.
Code Example
netStatus netNDP_GetMAC | ( | uint32_t | if_num, |
const uint8_t * | ip6_addr, | ||
uint8_t * | mac_addr | ||
) |
Get MAC address from neighbor discovery cache. [thread-safe].
[in] | if_num | interface_number. |
[in] | ip6_addr | requested IPv6 address. |
[out] | mac_addr | resolved MAC address. |
The function netNDP_GetMAC determines the resolved MAC address for a specific IPv6 address.
The argument if_num is the Ethernet interface 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.
Code Example
netStatus netNDP_Probe | ( | uint32_t | if_num, |
const uint8_t * | ip6_addr, | ||
netNDP_cb_t | cb_func | ||
) |
Determine whether the IP address is already in use. [thread-safe].
[in] | if_num | interface_number. |
[in] | ip6_addr | requested IPv6 address. |
[in] | cb_func | callback function to call, when probe session ends. |
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_num is the Ethernet interface 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.
Refer to
Code Example