Loading...
Searching...
No Matches
su_localinfo.h File Reference
Socket Functions

Interface for obtaining local addresses. More...

`#include <sofia-sip/su.h>`
Include dependency graph for su_localinfo.h:

Go to the source code of this file.

## Data Structures

struct | su_localinfo_s
| Local address info structure. More...

## Macros

#define | SU_LOCALINFO_H
| Defined when <sofia-sip/su_localinfo.h> has been included.

## Typedefs

typedef struct su_localinfo_s | su_localinfo_t
| Local address info structure.

## Enumerations

enum | { LI_V4MAPPED , LI_CANONNAME , LI_NAMEREQD , LI_NUMERIC , LI_DOWN , LI_IFNAME }
| Flags for su_getlocalinfo() - li_flags. More...
enum | { LI_SCOPE_HOST , LI_SCOPE_LINK , LI_SCOPE_SITE , LI_SCOPE_GLOBAL }
| Localinfo scope - li_scope. More...
enum | { ELI_NOADDRESS , ELI_MEMORY , ELI_FAMILY , ELI_RESOLVER , ELI_SYSTEM , ELI_BADHINTS , ELI_NOERROR }
| Localinfo error codes. More...

## Functions

int | su_getlocalinfo (su_localinfo_t const *hints, su_localinfo_t **res)
| Request local address information.
void | su_freelocalinfo (su_localinfo_t *)
| Free local address information.
char const * | su_gli_strerror (int error)
| Describe su_localinfo errors.
su_localinfo_t * | su_copylocalinfo (su_localinfo_t const *li0)
| Copy a localinfo structure.
int | su_sockaddr_scope (su_sockaddr_t const *su, socklen_t sulen)
| Return the scope of address in the sockaddr structure.

## Detailed Description

Interface for obtaining local addresses.

Author
  Pekka Pessi Pekka.nosp@m..Pes.nosp@m.si@no.nosp@m.kia..nosp@m.com

Date
  Created: Thu Aug 10 18:58:01 2000 ppessi

## Enumeration Type Documentation

## anonymous enum

anonymous enum

Flags for su_getlocalinfo() - li_flags.

Enumerator
LI_V4MAPPED | IPv4 addresses will be mapped as IPv6.
LI_CANONNAME | Get domain name corresponding to the local address.
LI_NAMEREQD | Do not return addresses not in DNS. Implies LI_CANONNAME.
LI_NUMERIC | Instead of domain name, use numeric form.
LI_DOWN | Include interfaces even if they are down (new in 1.12.2).
LI_IFNAME | Get interface name.

## anonymous enum

anonymous enum

Localinfo scope - li_scope.

Enumerator
LI_SCOPE_HOST | Host-local address, valid within host.
LI_SCOPE_LINK | Link-local address.
LI_SCOPE_SITE | Site-local address.
LI_SCOPE_GLOBAL | Global address.

## anonymous enum

anonymous enum

Localinfo error codes.

Enumerator
ELI_NOADDRESS | No matching address.
ELI_MEMORY | Memory allocation error.
ELI_FAMILY | Unknown address family.
ELI_RESOLVER | Error when resolving address.
ELI_SYSTEM | System error.
ELI_BADHINTS | Invalid value for hints.
ELI_NOERROR | No error.

## Function Documentation

## su_copylocalinfo()

su_localinfo_t * su_copylocalinfo | ( | su_localinfo_t const * | li0 | ) |

Copy a localinfo structure.

Copy a localinfo structure.

## su_freelocalinfo()

void su_freelocalinfo | ( | su_localinfo_t * | tbf | ) |

Free local address information.

Free a list of su_localinfo_t structures obtained with su_getlocalinfo() or su_copylocalinfo() along with socket addresses and strings associated with them.

See also
  su_getlocalinfo(), su_copylocalinfo(), su_localinfo_t

## su_getlocalinfo()

int su_getlocalinfo | ( | su_localinfo_t const * | hints,
|  | su_localinfo_t ** | return_localinfo )

Request local address information.

Gather the network interfaces and the addresses corresponding to them, check if they match to the search criteria specifed by hints and return a list of matching local address information in the return_localinfo. The local address information may include IPv4/IPv6 addresses, interface name, interface index, address scope, and domain names corresponding to the local addresses.

Parameters

  [in] | hints | specifies selection criteria
  [out] | return_localinfo | return list of local addresses

Selection criteria - hints

The selection criteria hints is used to select which addresses are returned and what kind of information is included in the res list.

Selection by flags - hints->li_flags

The hints->li_flags contain flags, which can be combined with bit-wise or. The currently defined flags are as follows:

- LI_V4MAPPED: when returning IPv4 addresses, map them as IPv6 addresses. If this flag is specified, IPv4 addresses are returned even if hints->li_family is set to `AF_INET6`.
- LI_CANONNAME: return the domain name (DNS PTR) corresponding to the local address in li_canonname.
- LI_NAMEREQD: Do not return addresses not in DNS.
- LI_NUMERIC: instead of domain name, return the text presentation of the addresss in li_canonname.
- LI_DOWN: include interfaces and their addresses even if the interfaces are down. New in 1.12.2.
- LI_IFNAME: return the interface name in li_ifname.

Selection by address family - hints->li_family

The address family can have three values: 0, AF_INET and AF_INET6. If address family hints->li_family, both IPv4 and IPv6 addresses are returned.

Selection by interface index - hints->li_index

If the field hints->li_index is non-zero, only the addresses assigned to the interface with given index are returned. The list of interface indices and names can be obtained by the function `su_if_names()`.

Selection by interface name - hints->li_ifname

If the field hints->li_ifname is not NULL, only the addresses assigned to the named interface are returned. The list of interface names can be obtained by the function `su_if_names()`.

Selection by address scope - hints->li_scope

If the field hints->li_scope is nonzero, only the addresses with matching scope are returned. The different address scopes can be combined with bitwise or. They are defined as follows

- LI_SCOPE_HOST: host-local address, valid within host (::1, 127.0.0.1/8)
- LI_SCOPE_LINK: link-local address, valid within link (IP6 addresses with prefix fe80::/10, IP4 addresses in net 169.254.0.0/16).
- LI_SCOPE_SITE: site-local address, addresses valid within organization (IPv6 addresses with prefix fec::/10, private IPv4 addresses in nets 10.0.0.0/8, 172.16.0.0/12, and 192.168.0.0/16 as defined in RFC 1918)
- LI_SCOPE_GLOBAL: global address.

For instance, setting hints->li_scope to `LI_SCOPE_GLOBAL` | `LI_SCOPE_SITE`, both the global and site-local addresses are returned.

See also
  RFC 1918, RFC 4291, su_sockaddr_scope()

Selection by domain name - hints->li_canonname

If this field is non-null, the domain name (DNS PTR) corresponding to local IP addresses should match to the name given in this field.

Returns
  Zero (ELI_NOERROR) when successful, or negative error code when failed.

Diagnostics
  Use su_gli_strerror() in order to obtain a string describing the error code returned by su_getlocalinfo().

## su_gli_strerror()

char const * su_gli_strerror | ( | int | error | ) |

Describe su_localinfo errors.

The function su_gli_strerror() returns a string describing the error condition indicated by the code that was returned by the function su_getlocalinfo().

Parameters

  error | error code returned by su_getlocalinfo()

Returns
  A pointer to string describing the error condition.

Sofia-SIP 1.12.11devel - Copyright (C) 2006 Nokia Corporation. All rights reserved. Licensed under the terms of the GNU Lesser General Public License.