sofia-sip/su_localinfo.h File Reference

Detailed Description

Interface for obtaining local addresses.

Author:
Pekka Pessi <Pekka.Pessi@nokia-email.address.hidden>
Date:
Created: Thu Aug 10 18:58:01 2000 ppessi

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

Typedefs

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

Enumeration Type Documentation

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
 

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
 

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

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

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

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.10devel - Copyright (C) 2006 Nokia Corporation. All rights reserved. Licensed under the terms of the GNU Lesser General Public License.