Network interfaces

Common network interface API. More...

Detailed Description

Common network interface API.

This allows access to network interfaces regardless of the network stack implementation. The network stack must provide

• A definition for netif_get_name
• A definition for netif_get_opt
• A definition for netif_set_opt

The network stack should also register each interface via netif_register.

Modules
	Network interfaces compile configurations

Files
file	netif.h
	Common network interface API definitions.

Data Structures
struct	netif_t
	Network interface descriptor. More...

Functions
netif_t *	netif_iter (netif_t *last)
	Iterator for the interfaces. More...
int	netif_get_name (netif_t *netif, char *name)
	Gets name of an interface. More...
int16_t	netif_get_id (const netif_t *netif)
	Gets the numeric identifier of an interface. More...
netif_t *	netif_get_by_name (const char *name)
	Gets interface by name. More...
netif_t *	netif_get_by_id (int16_t id)
	Gets interface by a numeric identifier. More...
int	netif_get_opt (netif_t *netif, netopt_t opt, uint16_t context, void *value, size_t max_len)
	Gets option from an interface. More...
int	netif_set_opt (netif_t *netif, netopt_t opt, uint16_t context, void *value, size_t value_len)
	Sets option to an interface. More...
int	netif_register (netif_t *netif)
	Registers a network interface in the global interface list. More...
char *	netif_addr_to_str (const uint8_t *addr, size_t addr_len, char *out)
	Converts a hardware address to a human readable string. More...
size_t	netif_addr_from_str (const char *str, uint8_t *out)
	Parses a string of colon-separated hexadecimals to a hardware address. More...

Function Documentation

netif_addr_from_str()

size_t netif_addr_from_str	(	const char *	str,
		uint8_t *	out
	)

Parses a string of colon-separated hexadecimals to a hardware address.

The input format must be like xx:xx:xx:xx where xx will be the bytes of addr in hexadecimal representation.

Precondition

(out != NULL)

out MUST have allocated at least GNRC_NETIF_L2ADDR_MAXLEN bytes.

Parameters

[in]	str	A string of colon-separated hexadecimals.
[out]	out	The resulting hardware address. Must at least have GNRC_NETIF_L2ADDR_MAXLEN bytes allocated.

Returns

Actual length of out on success.

0, on failure.

netif_addr_to_str()

char* netif_addr_to_str	(	const uint8_t *	addr,
		size_t	addr_len,
		char *	out
	)

Converts a hardware address to a human readable string.

The format will be like xx:xx:xx:xx where xx are the bytes of addr in hexadecimal representation.

Precondition

(out != NULL) && ((addr != NULL) || (addr_len == 0))

out MUST have allocated at least 3 * addr_len bytes.

Parameters

[in]	addr	A hardware address.
[in]	addr_len	Length of addr.
[out]	out	A string to store the output in. Must at least have 3 * addr_len bytes allocated.

Returns

out.

netif_get_by_id()

netif_t* netif_get_by_id

(

int16_t

id

)

Gets interface by a numeric identifier.

Parameters

[in]

id

A numeric identifier.

Returns

The interface on success.

NULL if no interface with identifier id.

netif_get_by_name()

netif_t* netif_get_by_name

(

const char *

name

)

Gets interface by name.

Precondition

name != NULL

Parameters

[in]

name

The name of an interface as a zero-terminated. Must not be NULL.

Returns

The interface on success.

NULL if no interface is named name.

netif_get_id()

int16_t netif_get_id

(

const netif_t *

netif

)

Gets the numeric identifier of an interface.

Parameters

[in]

netif

A network interface.

Returns

The numeric identifier of an interface

-1 if netif is not registered

netif_get_name()

int netif_get_name	(	netif_t *	netif,
		char *	name
	)

Gets name of an interface.

Precondition

name != NULL

name holds at least CONFIG_NETIF_NAMELENMAX characters

Note

Supposed to be implemented by the networking module. name must be zero-terminated in the result!

Parameters

[in]	netif	A network interface.
[out]	name	The name of the interface. Must not be NULL. Must at least hold CONFIG_NETIF_NAMELENMAX bytes.

Returns

length of name on success

netif_get_opt()

int netif_get_opt	(	netif_t *	netif,
		netopt_t	opt,
		uint16_t	context,
		void *	value,
		size_t	max_len
	)

Gets option from an interface.

Note

Supposed to be implemented by the networking module

Parameters

[in]	netif	A network interface.
[in]	opt	Option type.
[in]	context	(Optional) context to the given option
[out]	value	Pointer to store the option's value in.
[in]	max_len	Maximal amount of byte that fit into value.

Returns

Number of bytes written to value.

< 0 on error, 0 on success.

netif_iter()

netif_t* netif_iter

(

netif_t *

last

)

Iterator for the interfaces.

Returns interface after last. To start use last == NULL.

Parameters

[in]

last

The previous interface. Use NULL to start iteration.

Returns

next network interface.

NULL, if there is no interface after last

netif_register()

int netif_register

(

netif_t *

netif

)

Registers a network interface in the global interface list.

Note

This functions should be called when initializing an interface.

Parameters

[in]

netif

Interface to be registered

Returns

0 on success

-EINVAL if netif is NULL.

netif_set_opt()

int netif_set_opt	(	netif_t *	netif,
		netopt_t	opt,
		uint16_t	context,
		void *	value,
		size_t	value_len
	)

Sets option to an interface.

Note

Supposed to be implemented by the networking module

Parameters

[in]	netif	A network interface.
[in]	opt	Option type.
[in]	context	(Optional) context to the given option
[in]	value	Pointer to store the option's value in.
[in]	value_len	The length of value.

Returns

Number of bytes used from value.

< 0 on error, 0 on success.