Loading...
Searching...
No Matches
sres.h File Reference

Sofia DNS Resolver. More...

`#include <stdarg.h>`
`#include "sofia-resolv/sres_config.h"`
Include dependency graph for sres.h:

Go to the source code of this file.

## Macros

#define | SOFIA_RESOLV_SRES_H
| Defined when <sofia-resolv/sres.h> has been included.

## Typedefs

typedef union sres_record | sres_record_t
| Type representing any DNS record.
typedef struct sres_cache | sres_cache_t
| Opaque type of DNS cache object.
typedef struct sres_resolver_s | sres_resolver_t
| Opaque type of DNS resolver object.
typedef struct sres_context_s | sres_context_t
| Application-defined type for sres_query_t context.
typedef struct sres_query_s | sres_query_t
| Opaque type of DNS query object.
typedef void | sres_answer_f(sres_context_t *context, sres_query_t *query, sres_record_t **answers)
| Prototype for callback function.

## Enumerations

enum | { SRES_RETRANSMIT_INTERVAL , SRES_RETRANSMIT_INTERVAL , SRES_RETRY_INTERVAL , SRES_RETRY_INTERVAL , SRES_MAX_RETRY_COUNT , SRES_MAX_RETRY_COUNT , SRES_MAX_SEARCH , SRES_MAX_SEARCH , SRES_MAX_NAMESERVERS , SRES_MAX_NAMESERVERS , SRES_MAXDNAME , SRES_MAXDNAME , SRES_MAX_SORTLIST }

## Functions

SRESPUBFUN sres_resolver_t * | sres_resolver_new (char const *resolv_conf_path)
| New resolver object.
SRESPUBFUN sres_resolver_t * | sres_resolver_copy (sres_resolver_t *)
| Copy a resolver.
SRESPUBFUN sres_resolver_t * | sres_resolver_new_with_cache (char const *conf_file_path, sres_cache_t *cache, char const *options,...)
| New resolver object.
SRESPUBFUN sres_resolver_t * | sres_resolver_new_with_cache_va (char const *conf_file_path, sres_cache_t *cache, char const *options, va_list va)
| New resolver object.
SRESPUBFUN sres_resolver_t * | sres_resolver_ref (sres_resolver_t *res)
| Increase reference count on a resolver object.
SRESPUBFUN void | sres_resolver_unref (sres_resolver_t *res)
| Decrease the reference count on a resolver object.
SRESPUBFUN int | sres_resolver_update (sres_resolver_t *res, int always)
| Re-read resolv.conf if needed.
SRESPUBFUN void * | sres_resolver_set_userdata (sres_resolver_t *res, void *userdata)
| Set userdata pointer.
SRESPUBFUN void * | sres_resolver_get_userdata (sres_resolver_t const *res)
| Get userdata pointer.
SRESPUBFUN sres_query_t * | sres_query (sres_resolver_t *res, sres_answer_f *callback, sres_context_t *context, uint16_t type, char const *domain)
| Make a DNS query.
SRESPUBFUN sres_query_t * | sres_search (sres_resolver_t *res, sres_answer_f *callback, sres_context_t *context, uint16_t type, char const *name)
| Search DNS.
SRESPUBFUN sres_query_t * | sres_query_sockaddr (sres_resolver_t *res, sres_answer_f *callback, sres_context_t *context, uint16_t type, struct sockaddr const *addr)
| Make a reverse DNS query.
SRESPUBFUN sres_query_t * | sres_query_make (sres_resolver_t *res, sres_answer_f *callback, sres_context_t *context, int dummy, uint16_t type, char const *domain)
| Make a DNS query with socket.
SRESPUBFUN sres_query_t * | sres_query_make_sockaddr (sres_resolver_t *res, sres_answer_f *callback, sres_context_t *context, int dummy, uint16_t type, struct sockaddr const *addr)
| Make a reverse DNS query with socket.
SRESPUBFUN void | sres_query_bind (sres_query_t *q, sres_answer_f *callback, sres_context_t *context)
| Rebind a DNS query.
SRESPUBFUN sres_record_t ** | sres_cached_answers (sres_resolver_t *res, uint16_t type, char const *domain)
| Get a list of matching (type/domain) records from cache.
SRESPUBFUN sres_record_t ** | sres_search_cached_answers (sres_resolver_t *res, uint16_t type, char const *name)
| Search for a list of matching (type/name) records from cache.
SRESPUBFUN sres_record_t ** | sres_cached_answers_sockaddr (sres_resolver_t *res, uint16_t type, struct sockaddr const *addr)
| Get a list of matching (type/domain) records from cache.
SRESPUBFUN int | sres_set_cached_srv_priority (sres_resolver_t *res, char const *domain, char const *target, uint16_t port, uint32_t newttl, uint16_t newprio)
| Modify the priority of the specified SRV records.
SRESPUBFUN int | sres_blocking_query (sres_resolver_t *res, uint16_t type, char const *domain, int ignore_cache, sres_record_t ***return_records)
| Send a query, wait for answer, return results.
SRESPUBFUN int | sres_blocking_search (sres_resolver_t *res, uint16_t type, char const *name, int ignore_cache, sres_record_t ***return_records)
| Search DNS, return results.
SRESPUBFUN int | sres_blocking_query_sockaddr (sres_resolver_t *res, uint16_t type, struct sockaddr const *addr, int ignore_cache, sres_record_t ***return_records)
| Send a a reverse DNS query, wait for answer, return results.
SRESPUBFUN int | sres_is_blocking (sres_resolver_t *res)
| Return true (and set resolver in blocking mode) if resolver can block.
SRESPUBFUN int | sres_sort_answers (sres_resolver_t *, sres_record_t **answers)
| Sort the list of records.
SRESPUBFUN int | sres_filter_answers (sres_resolver_t *res, sres_record_t **answers, uint16_t type)
| Filter and sort the list of records.
SRESPUBFUN void | sres_free_answers (sres_resolver_t *, sres_record_t **answers)
| Free the list records.
SRESPUBFUN void | sres_free_answer (sres_resolver_t *res, sres_record_t *answer)
| Free and zero one record.

## Detailed Description

Sofia DNS Resolver.

Author
  Pekka Pessi Pekka.nosp@m..Pes.nosp@m.si@no.nosp@m.kia..nosp@m.com,
  Teemu Jalava Teemu.nosp@m..Jal.nosp@m.ava@n.nosp@m.okia.nosp@m..com,
  Mikko Haataja ext-M.nosp@m.ikko.nosp@m..A.Ha.nosp@m.ataj.nosp@m.a@nok.nosp@m.ia.c.nosp@m.om.

Include Context
  #include <sys/types.h>
  #include <sys/socket.h>
  #include <netinet/in.h>
  #include <sofia-resolv/sres.h>
  sres.h
  Sofia DNS Resolver.

## Typedef Documentation

## sres_answer_f

typedef void sres_answer_f(sres_context_t *context, sres_query_t *query, sres_record_t **answers)

Prototype for callback function.

This kind of function is called when a query is completed. The called function is responsible for freeing the list of answers and it must (eventually) call sres_free_answers().

## Enumeration Type Documentation

## anonymous enum

anonymous enum

Enumerator
SRES_RETRANSMIT_INTERVAL | Resolver timer interval in milliseconds.
SRES_RETRANSMIT_INTERVAL | Resolver timer interval in milliseconds.
SRES_RETRY_INTERVAL | Initial retry interval in seconds.
SRES_RETRY_INTERVAL | Initial retry interval in seconds.
SRES_MAX_RETRY_COUNT | Maximum number of retries sent.
SRES_MAX_RETRY_COUNT | Maximum number of retries sent.
SRES_MAX_SEARCH | Maximum number of search domains.
SRES_MAX_SEARCH | Maximum number of search domains.
SRES_MAX_NAMESERVERS | Maximum number of nameservers.
SRES_MAX_NAMESERVERS | Maximum number of nameservers.
SRES_MAXDNAME | Maximum length of domain name.
SRES_MAXDNAME | Maximum length of domain name.
SRES_MAX_SORTLIST | Maximum length of sortlist.

## Function Documentation

## sres_blocking_query()

SRESPUBFUN int sres_blocking_query | ( | sres_resolver_t * | res,
|  | uint16_t | type,
|  | char const * | domain,
|  | int | ignore_cache,
|  | sres_record_t *** | return_records )

Send a query, wait for answer, return results.

Send a query, wait for answer, return results.

Sends a DNS query with specified type and domain to the DNS server, if ignore_cache is not given or no records are found from cache. Function returns an error record with nonzero status if no response is received from DNS server.

Parameters

  res | pointer to resolver object
  type | record type to search (or sres_qtype_any for any record)
  domain | domain name to query
  ignore_cache | ignore cached answers if nonzero
  return_records | return-value parameter for dns records

Return values

  >0 | if query was responded
  0 | if result was found from cache
  -1 | upon error

Errors:

\n EFAULT res or domain point outside the address space

\n ENAMETOOLONG domain is longer than SRES_MAXDNAME

\n ENETDOWN no DNS servers configured

\n ENOMEM memory exhausted

\n EOPNOTSUPP resolver res is in asynchronous mode

See also
  sres_query(), sres_blocking_search()

Note
  A blocking query converts a resolver object permanently into blocking mode. If you need to make blocking and non-blocking queries, use sres_resolver_copy() to make a separate resolver object for blocking queries.

## sres_blocking_query_sockaddr()

SRESPUBFUN int sres_blocking_query_sockaddr | ( | sres_resolver_t * | res,
|  | uint16_t | type,
|  | struct sockaddr const * | addr,
|  | int | ignore_cache,
|  | sres_record_t *** | return_records )

Send a a reverse DNS query, wait for answer, return results.

Send a a reverse DNS query, wait for answer, return results.

Sends a reverse DNS query with specified type and domain to the DNS server if ignore_cache is not given or no cached records are found from the cache. Function returns an error record with nonzero status if no response is received from DNS server.

Return values

  >0 | if query was responded
  0 | if result was found from cache
  -1 | upon error

Errors:

\n EFAULT res or addr point outside the address space

\n ENOMEM memory exhausted

\n ENETDOWN no DNS servers configured

\n EOPNOTSUPP resolver res is in asynchronous mode

See also
  sres_blocking_query(), sres_query_sockaddr(), sres_cached_answers_sockaddr()

Note
  A blocking query converts a resolver object permanently into blocking mode. If you need to make blocking and non-blocking queries, use sres_resolver_copy() to make a separate resolver object for blocking queries.

## sres_blocking_search()

SRESPUBFUN int sres_blocking_search | ( | sres_resolver_t * | res,
|  | uint16_t | type,
|  | char const * | name,
|  | int | ignore_cache,
|  | sres_record_t *** | return_records )

Search DNS, return results.

Search for name with specified type and name from the DNS server. If the name does not contain enought dots, the search domains are appended to the name and resulting domain name are also queried.

Parameters

  res | pointer to resolver object
  type | record type to search (or sres_qtype_any for any record)
  name | host or domain name to search from DNS
  ignore_cache | ignore cached answers if nonzero
  return_records | return-value parameter for dns records

Return values

  >0 | if query was responded
  0 | if result was found from cache
  -1 | upon error

Errors:

\n EFAULT res or domain point outside the address space

\n ENAMETOOLONG domain is longer than SRES_MAXDNAME

\n ENETDOWN no DNS servers configured

\n ENOMEM memory exhausted

\n EOPNOTSUPP resolver res is in asynchronous mode

See also
  sres_blocking_query(), sres_search()

Note
  A blocking query converts a resolver object permanently into blocking mode. If you need to make blocking and non-blocking queries, use sres_resolver_copy() to make a separate resolver object for blocking queries.

## sres_cached_answers()

SRESPUBFUN sres_record_t ** sres_cached_answers | ( | sres_resolver_t * | res,
|  | uint16_t | type,
|  | char const * | domain )

Get a list of matching (type/domain) records from cache.

Returns
  pointer to an array of pointers to cached records, or NULL if no entry was found.

Errors:

\n ENAMETOOLONG domain is longer than SRES_MAXDNAME

\n ENOENT no cached records were found

\n EFAULT res or domain point outside the address space

\n ENOMEM memory exhausted

## sres_cached_answers_sockaddr()

SRESPUBFUN sres_record_t ** sres_cached_answers_sockaddr | ( | sres_resolver_t * | res,
|  | uint16_t | type,
|  | struct sockaddr const * | addr )

Get a list of matching (type/domain) records from cache.

Get a list of matching (type/domain) records from cache.

Parameters

  res | pointer to resolver
  type | record type to query (or sres_qtype_any for any record)
  addr | socket address structure

The type should be sres_type_ptr. The addr should contain either IPv4 (AF_INET) or IPv6 (AF_INET6) address.

If the SRES_OPTIONS environment variable, RES_OPTIONS environment variable or an "options" entry in resolv.conf file contains an option "ip6-dotint", the IPv6 addresses are resolved using suffix ".ip6.int" instead of default ".ip6.arpa".

Return values

  pointer | to an array of pointers to cached records, or NULL if no entry was found.

Errors:

\n EAFNOSUPPORT address family specified in addr is not supported

\n ENOENT no cached records were found

\n EFAULT res or addr point outside the address space

\n ENOMEM memory exhausted

## sres_filter_answers()

SRESPUBFUN int sres_filter_answers | ( | sres_resolver_t * | res,
|  | sres_record_t ** | answers,
|  | uint16_t | type )

Filter and sort the list of records.

Filter and sort the list of records.

## sres_free_answers()

SRESPUBFUN void sres_free_answers | ( | sres_resolver_t * | res,
|  | sres_record_t ** | answers )

Free the list records.

Free the list records.

The array of records can be returned by sres_cached_answers() or given by callback function.

## sres_query()

SRESPUBFUN sres_query_t * sres_query | ( | sres_resolver_t * | res,
|  | sres_answer_f * | callback,
|  | sres_context_t * | context,
|  | uint16_t | type,
|  | char const * | domain )

Make a DNS query.

Make a DNS query.

Sends a DNS query with specified type and domain to the DNS server. When an answer is received, the callback function is called with context and returned records as arguments.

The sres resolver takes care of retransmitting the query if a root object is associate with the resolver or if sres_resolver_timer() is called in regular intervals. It generates an error record with nonzero status if no response is received.

Parameters

  res | pointer to resolver
  callback | function called when query is answered or times out
  context | pointer given as an extra argument to callback function
  type | record type to query (see sres_qtypes)
  domain | name to query

Query types also indicate the record type of the result. Any record can be queried with sres_qtype_any. Well-known query types understood and decoded by sres include sres_type_a, sres_type_aaaa, sres_type_cname, sres_type_ptr sres_type_soa, sres_type_aaaa, sres_type_srv, and sres_type_naptr.

Deprecated query type sres_type_a6 is also decoded.

Note
  The domain name is not concatenated with the domains from seach path or with the local domain. Use sres_search() in order to try domains in search path.

See also
  sres_search(), sres_blocking_query(), sres_cached_answers(), sres_query_sockaddr()

Errors:

\n EFAULT res or domain point outside the address space

\n ENAMETOOLONG domain is longer than SRES_MAXDNAME

\n ENETDOWN no DNS servers configured

\n ENOMEM memory exhausted

## sres_query_bind()

SRESPUBFUN void sres_query_bind | ( | sres_query_t * | query,
|  | sres_answer_f * | callback,
|  | sres_context_t * | context )

Rebind a DNS query.

Rebind a DNS query.

Parameters

  query | pointer to a query object to bind
  callback | pointer to new callback function (may be NULL)
  context | pointer to callback context (may be NULL)

## sres_query_make()

SRESPUBFUN sres_query_t * sres_query_make | ( | sres_resolver_t * | res,
|  | sres_answer_f * | callback,
|  | sres_context_t * | context,
|  | int | dummy,
|  | uint16_t | type,
|  | char const * | domain )

Make a DNS query with socket.

Deprecated

Make a DNS query with socket.

Deprecated
  Use sres_query() instead.

## sres_query_make_sockaddr()

SRESPUBFUN sres_query_t * sres_query_make_sockaddr | ( | sres_resolver_t * | res,
|  | sres_answer_f * | callback,
|  | sres_context_t * | context,
|  | int | dummy,
|  | uint16_t | type,
|  | struct sockaddr const * | addr )

Make a reverse DNS query with socket.

Deprecated

Make a reverse DNS query with socket.

Deprecated
  Use sres_query_sockaddr() instead.

## sres_query_sockaddr()

SRESPUBFUN sres_query_t * sres_query_sockaddr | ( | sres_resolver_t * | res,
|  | sres_answer_f * | callback,
|  | sres_context_t * | context,
|  | uint16_t | type,
|  | struct sockaddr const * | addr )

Make a reverse DNS query.

Send a query to DNS server with specified type and domain name formed from the socket address addr. The sres resolver takes care of retransmitting the query if a root object is associate with the resolver or if sres_resolver_timer() is called in regular intervals. It generates an error record with nonzero status if no response is received.

Parameters

  res | pointer to resolver
  callback | function called when query is answered or times out
  context | pointer given as an extra argument to callback function
  type | record type to query (or sres_qtype_any for any record)
  addr | socket address structure

The type should be sres_type_ptr. The addr should contain either IPv4 (AF_INET) or IPv6 (AF_INET6) address.

If the SRES_OPTIONS environment variable, RES_OPTIONS environment variable, or an "options" entry in resolv.conf file contains an option "ip6-dotint", the IPv6 addresses are resolved using suffix ".ip6.int" instead of the standard ".ip6.arpa" suffix.

Errors:

\n EAFNOSUPPORT address family specified in addr is not supported

\n ENETDOWN no DNS servers configured

\n EFAULT res or addr point outside the address space

\n ENOMEM memory exhausted

See also
  sres_query(), sres_blocking_query_sockaddr(), sres_cached_answers_sockaddr()

## sres_resolver_copy()

SRESPUBFUN sres_resolver_t * sres_resolver_copy | ( | sres_resolver_t * | res | ) |

Copy a resolver.

Make a copy of resolver sharing the configuration and cache with old resolver.

## sres_resolver_get_userdata()

SRESPUBFUN void * sres_resolver_get_userdata | ( | sres_resolver_t const * | res | ) |

Get userdata pointer.

Returns
  Userdata pointer.

Errors:

\n EFAULT res points outside the address space

## sres_resolver_new()

SRESPUBFUN sres_resolver_t * sres_resolver_new | ( | char const * | conf_file_path | ) |

New resolver object.

New resolver object.

Allocate and initialize a new sres resolver object. The resolver object contains the parsed resolv.conf file, a cache object containing past answers from DNS, and a list of active queries. The default resolv.conf file can be overriden by giving the name of the configuration file as conf_file_path.

Parameters

  conf_file_path | name of the resolv.conf configuration file

Returns
  A pointer to a newly created sres resolver object, or NULL upon an error.

## sres_resolver_new_with_cache()

SRESPUBFUN sres_resolver_t * sres_resolver_new_with_cache | ( | char const * | conf_file_path,
|  | sres_cache_t * | cache,
|  | char const * | option,
|  |  | ... )

New resolver object.

Allocate and initialize a new sres resolver object. The resolver object contains the parsed resolv.conf file, a cache object containing past answers from DNS, and a list of active queries. The default resolv.conf file can be overriden by giving the name of the configuration file as conf_file_path.

It is also possible to override the values in the resolv.conf and RES_OPTIONS by giving the directives in the NULL-terminated list.

Parameters

  conf_file_path | name of the resolv.conf configuration file
  cache | optional pointer to a resolver cache (may be NULL)
  option,... | list of resolv.conf options directives (overriding options in conf_file)

Environment Variables
  - LOCALDOMAIN overrides `domain` or `search` directives
  - RES_OPTIONS overrides values of options in resolv.conf
  - SRES_OPTIONS overrides values of options in resolv.conf, RES_OPTIONS, and options, ... list given as argument for this function

Returns
  A pointer to a newly created sres resolver object, or NULL upon an error.

## sres_resolver_new_with_cache_va()

sres_resolver_t * sres_resolver_new_with_cache_va | ( | char const * | conf_file_path,
|  | sres_cache_t * | cache,
|  | char const * | option,
|  | va_list | va )

New resolver object.

Create a resolver.

Allocate and initialize a new sres resolver object.

This is a stdarg version of sres_resolver_new_with_cache().

New resolver object.

Allocate and initialize a new sres resolver object.

This is a stdarg version of sres_resolver_new_with_cache().

## sres_resolver_set_userdata()

SRESPUBFUN void * sres_resolver_set_userdata | ( | sres_resolver_t * | res,
|  | void * | userdata )

Set userdata pointer.

Returns
  New userdata pointer.

Errors:

\n EFAULT res points outside the address space

## sres_resolver_update()

SRESPUBFUN int sres_resolver_update | ( | sres_resolver_t * | res,
|  | int | always )

Re-read resolv.conf if needed.

Re-read resolv.conf if needed.

Return values

  0 | when successful
  -1 | upon an error

## sres_search()

SRESPUBFUN sres_query_t * sres_search | ( | sres_resolver_t * | res,
|  | sres_answer_f * | callback,
|  | sres_context_t * | context,
|  | uint16_t | type,
|  | char const * | name )

Search DNS.

Sends DNS queries with specified type and name to the DNS server. If the name does not contain enought dots, the search domains are appended to the name and resulting domain name are also queried. When answer to all the search domains is received, the callback function is called with context and combined records from answers as arguments.

The sres resolver takes care of retransmitting the queries if a root object is associate with the resolver or if sres_resolver_timer() is called in regular intervals. It generates an error record with nonzero status if no response is received.

Parameters

  res | pointer to resolver object
  callback | pointer to completion function
  context | argument given to the completion function
  type | record type to search (or sres_qtype_any for any record)
  name | host or domain name to search from DNS

Errors:

\n EFAULT res or domain point outside the address space

\n ENAMETOOLONG domain is longer than SRES_MAXDNAME

\n ENETDOWN no DNS servers configured

\n ENOMEM memory exhausted

See also
  sres_query(), sres_blocking_search(), sres_search_cached_answers().

## sres_search_cached_answers()

SRESPUBFUN sres_record_t ** sres_search_cached_answers | ( | sres_resolver_t * | res,
|  | uint16_t | type,
|  | char const * | name )

Search for a list of matching (type/name) records from cache.

Returns
  pointer to an array of pointers to cached records, or NULL if no entry was found.

Errors:

\n ENAMETOOLONG name or resulting domain is longer than SRES_MAXDNAME

\n ENOENT no cached records were found

\n EFAULT res or domain point outside the address space

\n ENOMEM memory exhausted

See also
  sres_search(), sres_cached_answers()

## sres_set_cached_srv_priority()

SRESPUBFUN int sres_set_cached_srv_priority | ( | sres_resolver_t * | res,
|  | char const * | domain,
|  | char const * | target,
|  | uint16_t | port,
|  | uint32_t | ttl,
|  | uint16_t | priority )

Modify the priority of the specified SRV records.

Modify the priority of the specified SRV records.

The SRV records with the domain name, target and port are matched and their priority value is adjusted. This function is used to implement greylisting of SIP servers.

Parameters

  res | pointer to resolver
  domain | domain name of the SRV record(s) to modify
  target | SRV target of the SRV record(s) to modify
  port | port number of SRV record(s) to modify (in host byte order)
  ttl | new ttl for SRV records of the domain
  priority | new priority value (0=highest, 65535=lowest)

See also
  sres_cache_set_srv_priority()

Since
  New in 1.12.8

## sres_sort_answers()

SRESPUBFUN int sres_sort_answers | ( | sres_resolver_t * | res,
|  | sres_record_t ** | answers )

Sort the list of records.

Sort the list of records.

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