Loading...
Searching...
No Matches
ip-utils.h File Reference
Core

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...

## Functions

Janus helper methods to resolve external addresses
int | janus_network_resolve_address (const char *host, struct sockaddr_storage *address)
| Wrapper inet_pton or getaddrinfo to fill a struct sockaddr_storage structure from an address.

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

enum | janus_network_query_options { janus_network_query_options_none = 0 , janus_network_query_options_name = 1 , janus_network_query_options_ipv4 = 2 , janus_network_query_options_ipv6 = 4 , janus_network_query_options_any_ip = 6 , janus_network_query_options_any = 7 }
typedef enum janus_network_query_options | janus_network_query_options
typedef struct janus_network_query_config | janus_network_query_config
| Internal object representation of a network device query (configuration).
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.
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.
int | janus_network_prepare_device_query (const char *user_value, const janus_network_query_options query_mode, janus_network_query_config *query)
| Initialise a network device query.
int | janus_network_prepare_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.
const struct ifaddrs * | janus_network_query_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.
int | janus_network_get_devices_ipv4 (const struct ifaddrs *ifa, const janus_network_query_config *query, struct in_addr *result)
| Copies the IPv4 address from a network interface description to the given result structure.
int | janus_network_get_devices_ipv6 (const struct ifaddrs *ifa, const janus_network_query_config *query, struct in6_addr *result)
| Copies the IPv6 address from a network interface description to the given result structure.
int | janus_network_get_device_address (const struct ifaddrs *ifa, janus_network_address *result)
| Copies the IP address from a network interface description to the given result structure.
void | janus_network_address_nullify (janus_network_address *a)
| Set the given network address to a null/nil value.
int | janus_network_address_is_null (const janus_network_address *a)
| Test if a given network address is null-valued.
int | janus_network_address_from_sockaddr (struct sockaddr *s, janus_network_address *a)
| Convert a struct sockaddr to a janus_network_address.
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.
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.
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.
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.
int | janus_network_string_is_valid_address (janus_network_query_options addr_type, const char *user_value)
| Test if a given IP address string is a valid address of the specified type.
int | janus_network_string_to_address (janus_network_query_options addr_type, const char *user_value, janus_network_address *result)
| Convert an IP address string to a janus_network_address instance.
int | janus_network_lookup_interface (const struct ifaddrs *ifas, const char *iface, janus_network_address *result)
| Convert an interface name or IP address to a janus_network_address instance.
int | janus_network_detect_local_ip (janus_network_query_options addr_type, janus_network_address *result)
| Helper method to find a valid local IP address, that is an address that can be used to communicate.
char * | janus_network_detect_local_ip_as_string (janus_network_query_options addr_type)
| Wrapper to janus_network_detect_local_ip that returns a string instead.

## 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

Copyright
  GNU General Public License v3

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_network_address

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.

See also
  man 7 ip
  man 7 ipv6
  `janus_network_get_device_address`

## janus_network_address_string_buffer

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.

See also
  man 7 ip
  man 7 ipv6
  `janus_network_address_to_string_buffer`

## janus_network_query_config

typedef struct janus_network_query_config janus_network_query_config

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

## janus_network_query_options

typedef enum janus_network_query_options janus_network_query_options

## Enumeration Type Documentation

## janus_network_query_options

enum janus_network_query_options

Enumerator
janus_network_query_options_none |
janus_network_query_options_name |
janus_network_query_options_ipv4 |
janus_network_query_options_ipv6 |
janus_network_query_options_any_ip |
janus_network_query_options_any |

## Function Documentation

## janus_network_address_from_sockaddr()

int janus_network_address_from_sockaddr | ( | struct sockaddr * | s,
|  | janus_network_address * | a )

Convert a struct sockaddr to a janus_network_address.

Parameters

  s | The struct sockaddr to convert
  a | The address to write to

Returns
  0 on success, or -EINVAL otherwise.

## 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

  a | The address to check

Returns
  A positive integer if the given address is null-valued, 0 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

  a | The 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

  b | The buffer to check

Returns
  A positive integer if the given buffer is null-valued, 0 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

  b | The 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

  b | The 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

  a | The address to convert
  buf | A 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_network_detect_local_ip()

int janus_network_detect_local_ip | ( | janus_network_query_options | addr_type,
|  | janus_network_address * | result )

Helper method to find a valid local IP address, that is an address that can be used to communicate.

Parameters

  addr_type | The type of address you're interested in (janus_network_query_options_ipv4, janus_network_query_options_ipv6 or janus_network_query_options_any_ip)
  result | Pointer to a valid janus_network_address instance that will contain the result

Returns
  0 in case of success, -EINVAL otherwise

## janus_network_detect_local_ip_as_string()

char * janus_network_detect_local_ip_as_string | ( | janus_network_query_options | addr_type | ) |

Wrapper to janus_network_detect_local_ip that returns a string instead.

Note
  The string is allocated with g_strdup and so needs to be freed by the caller

Parameters

  addr_type | The type of address you're interested in (janus_network_query_options_ipv4, janus_network_query_options_ipv6 or janus_network_query_options_any_ip)

Returns
  0 in case of success, -EINVAL otherwise

## janus_network_get_device_address()

int janus_network_get_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_network_get_devices_ipv4()

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

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

Parameters

  ifa | The network interface description to grab the IPv4 address from. It should be obtained with janus_network_query_devices().
  query | A description of the criteria to look for when determining whether or not a network interface is a match
  result | Pointer 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_network_query_devices`

## janus_network_get_devices_ipv6()

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

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

Parameters

  ifa | The network interface description to grab the IPv6 address from. It should be obtained with janus_network_query_devices().
  query | A description of the criteria to look for when determining whether or not a network interface is a match
  result | Pointer 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_network_query_devices`

## janus_network_lookup_interface()

int janus_network_lookup_interface | ( | const struct ifaddrs * | ifas,
|  | const char * | iface,
|  | janus_network_address * | result )

Convert an interface name or IP address to a janus_network_address instance.

Parameters

  ifas | The list of interfaces to look into (e.g., as returned from getifaddrs)
  iface | The interface name or IP address to look for
  result | Pointer to a valid janus_network_address instance that will contain the result

Returns
  0 in case of success, -EINVAL otherwise

## janus_network_prepare_device_query()

int janus_network_prepare_device_query | ( | const char * | user_value,
|  | const janus_network_query_options | query_mode,
|  | janus_network_query_config * | query )

Initialise a network device query.

Parameters

  user_value | The user-supplied string which is supposed to describe either the device name or its IP address.
  query_mode | (A mask of) Options describing the supported 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.
  query | The 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_network_query_options`

## janus_network_prepare_device_query_default()

int janus_network_prepare_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_value | The user-supplied string which is supposed to describe either the device name or its IP address.
  query | The query object to configure.

Returns
  0 on success, or -EINVAL if any of the arguments are NULL

See also
  `janus_network_prepare_device_query`

## janus_network_query_devices()

const struct ifaddrs * janus_network_query_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

  ifas | The first node of the list of network interfaces to search through. This should be obtained (indirectly) from `getifaddrs()`.
  query | A description of the criteria to look for when determining 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

## janus_network_resolve_address()

int janus_network_resolve_address | ( | const char * | host,
|  | struct sockaddr_storage * | address )

Wrapper inet_pton or getaddrinfo to fill a struct sockaddr_storage structure from an address.

Note
  The method will only do inet_pton if it detects a numeric address, and will perform a getaddrinfo otherwise. Notice that, since the request is synchronous, it may have to wait for a DNS response to that request.

Parameters

  host | The address to resolve
  address | A pointer to the struct sockaddr_storage to write the result to

Returns
  0 in case of success, a negative integer otherwise

## janus_network_string_is_valid_address()

int janus_network_string_is_valid_address | ( | janus_network_query_options | addr_type,
|  | const char * | user_value )

Test if a given IP address string is a valid address of the specified type.

Parameters

  addr_type | The type of address you're interested in (janus_network_query_options_ipv4, janus_network_query_options_ipv6 or janus_network_query_options_any_ip)
  user_value | The IP address string to check

Returns
  A positive integer if the given string is a valid address, 0 otherwise.

## janus_network_string_to_address()

int janus_network_string_to_address | ( | janus_network_query_options | addr_type,
|  | const char * | user_value,
|  | janus_network_address * | result )

Convert an IP address string to a janus_network_address instance.

Parameters

  addr_type | The type of address you're interested in (janus_network_query_options_ipv4, janus_network_query_options_ipv6 or janus_network_query_options_any_ip)
  user_value | The IP address string to check
  result | Pointer to a valid janus_network_address instance that will contain the result

Returns
  0 in case of success, -EINVAL otherwise