Coldwave Documentation

Appearance

Network Interface ​

Transport-agnostic accessor functions for network interfaces.

These functions operate on any registered link-layer interface (Ethernet, PPP/PPPoS, ...) via an opaque handle, so application code can query and configure addressing without caring about the underlying medium.

Types ​

Name
structif_extra_info_t
Common extra-info structure for any network interface.
typedef void *if_handle

Functions Overview ​

Name
int8_tif_ip(if_handle handle, uint32_t * ip_addr, uint32_t * gw, uint32_t * netmask)
Reads the IPv4 configuration of an interface.
int8_tif_set_ip(if_handle handle, uint32_t * ip_addr, uint32_t * gw, uint32_t * netmask)
Assigns a static IPv4 configuration to an interface.
int8_tif_set_default(if_handle handle)
Selects handle as the system's default network interface.
if_handleif_get_default(void )
Returns the handle of the current default network interface.
int8_tif_set_info(if_handle handle, const if_extra_info_t * info)
Updates the link-layer metadata of an interface.
int8_tif_get_info(if_handle handle, if_extra_info_t * info)
Reads the link-layer metadata of an interface.
unsignedif_get_xmit_count(if_handle handle)
Returns the number of frames transmitted on handle since interface start.
unsignedif_get_recv_count(if_handle handle)
Returns the number of frames received on handle since interface start.

Types Documentation ​

typedef if_handle ​

cpp
typedef void* if_handle;

Opaque handle representing a network interface.

Function Details ​

function if_ip ​

cpp
int8_t if_ip(
    if_handle handle,
    uint32_t * ip_addr,
    uint32_t * gw,
    uint32_t * netmask
)

Reads the IPv4 configuration of an interface.

Parameters:

  • handle Interface handle.
  • ip_addr Receives the interface IPv4 address (network byte order). May be NULL.
  • gw Receives the default gateway. May be NULL.
  • netmask Receives the netmask. May be NULL.

Return: 0 on success, negative on error.

function if_set_ip ​

cpp
int8_t if_set_ip(
    if_handle handle,
    uint32_t * ip_addr,
    uint32_t * gw,
    uint32_t * netmask
)

Assigns a static IPv4 configuration to an interface.

Parameters:

  • handle Interface handle.
  • ip_addr Pointer to the new IPv4 address (network byte order), or NULL.
  • gw Pointer to the new default gateway, or NULL.
  • netmask Pointer to the new netmask, or NULL.

Return: 0 on success, negative on error.

Pass NULL for any of the address pointers to leave that part of the configuration unchanged.

function if_set_default ​

cpp
int8_t if_set_default(
    if_handle handle
)

Selects handle as the system's default network interface.

Parameters:

  • handle Interface handle.

Return: 0 on success, negative on error.

Subsequent outbound traffic without an explicit route uses this interface.

function if_get_default ​

cpp
if_handle if_get_default(
    void 
)

Returns the handle of the current default network interface.

Return: Default interface handle, or NULL if none is configured.

function if_set_info ​

cpp
int8_t if_set_info(
    if_handle handle,
    const if_extra_info_t * info
)

Updates the link-layer metadata of an interface.

Parameters:

  • handle Interface handle.
  • info New metadata to apply.

Return: 0 on success, negative on error.

function if_get_info ​

cpp
int8_t if_get_info(
    if_handle handle,
    if_extra_info_t * info
)

Reads the link-layer metadata of an interface.

Parameters:

  • handle Interface handle.
  • info Caller-provided buffer that receives the metadata.

Return: 0 on success, negative on error.

function if_get_xmit_count ​

cpp
unsigned if_get_xmit_count(
    if_handle handle
)

Returns the number of frames transmitted on handle since interface start.

function if_get_recv_count ​

cpp
unsigned if_get_recv_count(
    if_handle handle
)

Returns the number of frames received on handle since interface start.