Fork me on GitHub
Data Structures
ip-utils.h File Reference

IP address related utility functions (headers) More...

#include <ifaddrs.h>
#include <netinet/in.h>
Include dependency graph for ip-utils.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  janus_network_query_config
 Internal object representation of a network device query (configuration). More...
 
struct  janus_network_address
 Structure to hold network addresses in a tagged union which should be IPv4 and IPv6 compatible. Use the family member (either AF_INET or AF_INET6) to determine which type of address is contained. More...
 
struct  janus_network_address_string_buffer
 Structure to hold human readable forms of network addresses in a tagged union which should be IPv4 and IPv6 compatible. Use the family member (either AF_INET or AF_INET6) to determine which type of representation is contained. More...
 

Janus helper methods to match names and addresses with network interfaces/devices.

enum  janus_ip_network_query_options {
  janus_ip_network_query_options_none = 0, janus_ip_network_query_options_name = 1, janus_ip_network_query_options_ipv4 = 2, janus_ip_network_query_options_ipv6 = 4,
  janus_ip_network_query_options_any_ip = 6, janus_ip_network_query_options_any = 7
}
 
typedef enum janus_ip_network_query_options janus_ip_network_query_options
 
typedef struct janus_network_query_config janus_network_query_config
 Internal object representation of a network device query (configuration). More...
 
typedef struct janus_network_address janus_network_address
 Structure to hold network addresses in a tagged union which should be IPv4 and IPv6 compatible. Use the family member (either AF_INET or AF_INET6) to determine which type of address is contained. More...
 
typedef struct janus_network_address_string_buffer janus_network_address_string_buffer
 Structure to hold human readable forms of network addresses in a tagged union which should be IPv4 and IPv6 compatible. Use the family member (either AF_INET or AF_INET6) to determine which type of representation is contained. More...
 
int janus_prepare_network_device_query (const char *user_value, const janus_ip_network_query_options query_mode, janus_network_query_config *query)
 Initialise a network device query. More...
 
int janus_prepare_network_device_query_default (const char *user_value, janus_network_query_config *query)
 Initialise a network device query with default query options. This function will Initialise the query to accept any supported match type. More...
 
const struct ifaddrs * janus_query_network_devices (const struct ifaddrs *ifas, const janus_network_query_config *query)
 Look up network devices matching the given query. The first matching device is returned, so to find all matching devices simply pass the ifa_next of the returned device in a subsequent call to this function to find more matches. More...
 
int janus_get_network_devices_ipv4 (const struct ifaddrs *ifa, const janus_network_query_config *query, struct in_addr *result)
 Copies the IPv4 address from a network inteface description to the given result structure. More...
 
int janus_get_network_devices_ipv6 (const struct ifaddrs *ifa, const janus_network_query_config *query, struct in6_addr *result)
 Copies the IPv6 address from a network inteface description to the given result structure. More...
 
int janus_get_network_device_address (const struct ifaddrs *ifa, janus_network_address *result)
 Copies the IP address from a network interface description to the given result structure. More...
 
void janus_network_address_nullify (janus_network_address *a)
 Set the given network address to a null/nil value. More...
 
int janus_network_address_is_null (const janus_network_address *a)
 Test if a given network address is null-valued. More...
 
int janus_network_address_to_string_buffer (const janus_network_address *a, janus_network_address_string_buffer *buf)
 Convert the given network address to a form which can be used to extract a human readable network address from. More...
 
void janus_network_address_string_buffer_nullify (janus_network_address_string_buffer *b)
 Set the given network address string buffer to a null/nil value. More...
 
int janus_network_address_string_buffer_is_null (const janus_network_address_string_buffer *b)
 Test if a given network address string buffer is null-valued. More...
 
const char * janus_network_address_string_from_buffer (const janus_network_address_string_buffer *b)
 Extract the human readable representation of a network address from a given buffer. More...
 

Detailed Description

IP address related utility functions (headers)

Author
Johan Ouwerkerk jm.ou.nosp@m.werk.nosp@m.erk@g.nosp@m.mail.nosp@m..com

Provides functions to query for network devices with a given device name or address. Devices may be looked up by either a device name or by the IPv4 or IPv6 address of the configured network interface. This functionality may be used to bind to user configurable network devices instead of relying on unpredictable implementation defined defaults.

Parsing IPv4/IPv6 addresses is robust against malformed input.

See also
man 3 getifaddrs
man 3 inet_pton

Core

Typedef Documentation

◆ janus_ip_network_query_options

◆ janus_network_address

Structure to hold network addresses in a tagged union which should be IPv4 and IPv6 compatible. Use the family member (either AF_INET or AF_INET6) to determine which type of address is contained.

See also
man 7 ip
man 7 ipv6
janus_get_network_device_address

◆ janus_network_address_string_buffer

Structure to hold human readable forms of network addresses in a tagged union which should be IPv4 and IPv6 compatible. Use the family member (either AF_INET or AF_INET6) to determine which type of representation is contained.

See also
man 7 ip
man 7 ipv6
janus_network_address_to_string_buffer

◆ janus_network_query_config

Internal object representation of a network device query (configuration).

Enumeration Type Documentation

◆ janus_ip_network_query_options

Enumerator
janus_ip_network_query_options_none 
janus_ip_network_query_options_name 
janus_ip_network_query_options_ipv4 
janus_ip_network_query_options_ipv6 
janus_ip_network_query_options_any_ip 
janus_ip_network_query_options_any 

Function Documentation

◆ janus_get_network_device_address()

int janus_get_network_device_address ( const struct ifaddrs *  ifa,
janus_network_address result 
)

Copies the IP address from a network interface description to the given result structure.

Returns
0 on success, or -EINVAL if any argument is NULL or the given network interface does not correspond to an IP address.
See also
janus_network_address

◆ janus_get_network_devices_ipv4()

int janus_get_network_devices_ipv4 ( const struct ifaddrs *  ifa,
const janus_network_query_config query,
struct in_addr *  result 
)

Copies the IPv4 address from a network inteface description to the given result structure.

Parameters
ifaThe network interface description to grab the IPv4 address from. It should be obtained with janus_query_network_devices().
resultPointer to a structure to populate with the IPv4 address of the given network interface
Returns
0 on success, -EINVAL if any argument is NULL or the network interface description or the network device query do not correspond to an IPv4 configuration.
See also
man 7 ip
janus_query_network_devices

◆ janus_get_network_devices_ipv6()

int janus_get_network_devices_ipv6 ( const struct ifaddrs *  ifa,
const janus_network_query_config query,
struct in6_addr *  result 
)

Copies the IPv6 address from a network inteface description to the given result structure.

Parameters
ifaThe network interface description to grab the IPv6 address from. It should be obtained with janus_query_network_devices().
resultPointer to a structure to populate with the IPv6 address of the given network interface
Returns
0 on success, -EINVAL if any argument is NULL or the network interface description or the network device query do not correspond to an IPv6 configuration.
See also
man 7 ipv6
janus_query_network_devices

◆ janus_network_address_is_null()

int janus_network_address_is_null ( const janus_network_address a)

Test if a given network address is null-valued.

Parameters
aThe address to check
Returns
some a value which is true if the given address is null-valued, false otherwise.
See also
janus_network_address_nullify

◆ janus_network_address_nullify()

void janus_network_address_nullify ( janus_network_address a)

Set the given network address to a null/nil value.

Parameters
aThe address to nullify. Nothing is done if the pointer is NULL itself.
See also
janus_network_address_is_null

◆ janus_network_address_string_buffer_is_null()

int janus_network_address_string_buffer_is_null ( const janus_network_address_string_buffer b)

Test if a given network address string buffer is null-valued.

Parameters
bThe buffer to check
Returns
some a value which is true if the given buffer is null-valued, false otherwise.
See also
janus_network_address_string_buffer_nullify

◆ janus_network_address_string_buffer_nullify()

void janus_network_address_string_buffer_nullify ( janus_network_address_string_buffer b)

Set the given network address string buffer to a null/nil value.

Parameters
bThe address to nullify. Nothing is done if the pointer is NULL itself.
See also
janus_network_address_string_buffer_is_null

◆ janus_network_address_string_from_buffer()

const char* janus_network_address_string_from_buffer ( const janus_network_address_string_buffer b)

Extract the human readable representation of a network address from a given buffer.

Parameters
bThe buffer containing the given network
Returns
a pointer to the human readable representation of the network address inside the given buffer, or NULL if the buffer is invalid or NULL.
See also
janus_network_address_to_string_buffer

◆ janus_network_address_to_string_buffer()

int janus_network_address_to_string_buffer ( const janus_network_address a,
janus_network_address_string_buffer buf 
)

Convert the given network address to a form which can be used to extract a human readable network address from.

Parameters
aThe address to convert
bufA buffer to contain the human readable form.
Returns
0 on success, or -EINVAL if any argument is NULL.
See also
janus_network_address
janus_network_address_string_buffer
janus_network_address_string_from_buffer
man 3 inet_ntop

◆ janus_prepare_network_device_query()

int janus_prepare_network_device_query ( const char *  user_value,
const janus_ip_network_query_options  query_mode,
janus_network_query_config query 
)

Initialise a network device query.

Parameters
user_valueThe user-supplied string which is supposed to describe either the device name or its IP address.
query_mode(A mask of) Options describing the supoorted types of matches which should be accepted when performing a look up with this query. This can be used to restrict the query to 'by device name' or 'IPv4 only' type searches.
queryThe query object to configure.
Returns
0 on success or -EINVAL if any of the arguments are NULL or the given value to look for does not correspond to a valid IPv4/IPv6 address and matching by name is disabled.
See also
janus_ip_network_query_options

◆ janus_prepare_network_device_query_default()

int janus_prepare_network_device_query_default ( const char *  user_value,
janus_network_query_config query 
)

Initialise a network device query with default query options. This function will Initialise the query to accept any supported match type.

Parameters
user_valueThe user-supplied string which is supposed to describe either the device name or its IP address.
queryThe query object to configure.
Returns
0 on success, or -EINVAL if any of the arguments are NULL
See also
janus_prepare_network_device_query

◆ janus_query_network_devices()

const struct ifaddrs* janus_query_network_devices ( const struct ifaddrs *  ifas,
const janus_network_query_config query 
)

Look up network devices matching the given query. The first matching device is returned, so to find all matching devices simply pass the ifa_next of the returned device in a subsequent call to this function to find more matches.

Parameters
ifasThe first node of the list of network interfaces to search through. This should be obtained (indirectly) from getifaddrs().
queryA description of the criteria to look for when deteremining whether or not a network interface is a match.
Returns
a pointer to a node describing the matching network interface or NULL if no (further) match was found.
See also
man 3 getifaddrs