sofia-resolv/sres.h File Reference


Detailed Description

Sofia DNS Resolver.

Author:
Pekka Pessi <Pekka.Pessi@nokia-email.address.hidden>,

Teemu Jalava <Teemu.Jalava@nokia-email.address.hidden>,

Mikko Haataja <ext-Mikko.A.Haataja@nokia-email.address.hidden>.

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

#include <stdarg.h>
#include "sofia-resolv/sres_config.h"

Include dependency graph for sres.h:

Go to the source code of this file.

Typedefs

typedef sres_record sres_record_t
 Type representing any DNS record.
typedef sres_cache sres_cache_t
 Opaque type of DNS cache object.
typedef sres_resolver_s sres_resolver_t
 Opaque type of DNS resolver object.
typedef sres_context_s sres_context_t
 Application-defined type for sres_query_t context.
typedef 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_RETRY_INTERVAL,
  SRES_MAX_RETRY_COUNT,
  SRES_MAX_SEARCH,
  SRES_MAX_NAMESERVERS,
  SRES_MAXDNAME,
  SRES_MAX_SORTLIST
}

Functions

SRESPUBFUN sres_resolver_tsres_resolver_new (char const *resolv_conf_path)
 New resolver object.
SRESPUBFUN sres_resolver_tsres_resolver_copy (sres_resolver_t *)
 Copy a resolver.
SRESPUBFUN sres_resolver_tsres_resolver_new_with_cache (char const *conf_file_path, sres_cache_t *cache, char const *options,...)
 New resolver object.
SRESPUBFUN sres_resolver_tsres_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_tsres_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_tsres_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_tsres_search (sres_resolver_t *res, sres_answer_f *callback, sres_context_t *context, uint16_t type, char const *name)
 Search DNS.
SRESPUBFUN sres_query_tsres_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_tsres_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_tsres_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_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.


Typedef Documentation

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

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


Function Documentation

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.

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

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.

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
See also:
sres_blocking_query(), sres_query_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.

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

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:
ENAMETOOLONG domain is longer than SRES_MAXDNAME
ENOENT no cached records were found
EFAULT res or domain point outside the address space
ENOMEM memory exhausted

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.

Return values:
pointer to an array of pointers to cached records, or NULL if no entry was found.
Errors:
EAFNOSUPPORT address family specified in addr is not supported
ENOENT no cached records were found
EFAULT res or addr point outside the address space
ENOMEM memory exhausted

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

Free the list records.

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

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.

Sends a DNS query with specified type and domain to the DNS server. The sres resolver takes care of retransmitting the query if sres_resolver_timer() is called in regular intervals. It generates an error record with nonzero status if no response is received.

See also:
sres_search(), sres_blocking_query(), sres_query_make()
Errors:
EFAULT res or domain point outside the address space
ENAMETOOLONG domain is longer than SRES_MAXDNAME
ENOMEM memory exhausted

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

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)

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

Make a DNS query with socket.

Sends a DNS query with specified type and domain to the DNS server. The sres resolver takes care of retransmitting the query if sres_resolver_timer() is called in regular intervals. It generates an error record with nonzero status if no response is received.

This function just makes sure that we have the socket is valid, otherwise it behaves exactly like sres_query().

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

Make a reverse DNS query with socket.

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 sres_resolver_timer() is called in regular intervals. It generates an error record with nonzero status if no response is received.

This function just makes sure that we have the socket is valid, otherwise it behaves exactly like 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 sres_resolver_timer() is called in regular intervals. It generates an error record with nonzero status if no response is received.

SRESPUBFUN sres_resolver_t* sres_resolver_copy ( sres_resolver_t res  ) 

Copy a resolver.

Make a copy of resolver with old

SRESPUBFUN void* sres_resolver_get_userdata ( sres_resolver_t const *  res  ) 

Get userdata pointer.

Returns:
Userdata pointer.
Errors:
EFAULT res points outside the address space

SRESPUBFUN sres_resolver_t* sres_resolver_new ( char const *  conf_file_path  ) 

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.

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

Allocate and initialize a new sres resolver object.

This is a stdarg version of sres_resolver_new_with_cache().

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

Set userdata pointer.

Returns:
New userdata pointer.
Errors:
EFAULT res points outside the address space

SRESPUBFUN int sres_resolver_update ( sres_resolver_t res,
int  always 
)

Re-read resolv.conf if needed.

Return values:
0 when successful
-1 upon an error

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.

The sres resolver takes care of retransmitting the queries 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:
EFAULT res or domain point outside the address space
ENAMETOOLONG domain is longer than SRES_MAXDNAME
ENOMEM memory exhausted
See also:
sres_query(), sres_blocking_search()

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:
ENAMETOOLONG name or resulting domain is longer than SRES_MAXDNAME
ENOENT no cached records were found
EFAULT res or domain point outside the address space
ENOMEM memory exhausted
See also:
sres_search(), sres_cached_answers()


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