Skip to content

GitLab

Commit 8b5d7e8d authored by Pekka Pessi's avatar Pekka Pessi
Browse files
Options

Updates sresolv documentation. 

darcs-hash:20060427133155-65a35-e8f58e74d778b32b5f198d5f27fb3bebc2b3445d.gz
parent 23757553
Hide whitespace changes
Inline Side-by-side
Showing with 258 additions and 70 deletions
libsofia-sip-ua/sresolv/Doxyfile
View file @ 8b5d7e8d
PROJECT_NAME = "sresolv"
OUTPUT_DIRECTORY = ../docs/html/sresolv
INPUT = sresolv.docs . sofia-sip
INPUT = sofia-sip sofia-resolv sresolv.docs .
@INCLUDE = ../docs/Doxyfile.conf
TAGFILES += ../docs/doxytags_su=../su
ALIASES += CFILE="@internal @file" IFILE="@internal @file"
TAGFILES += ../docs/doxytags_su=../su
GENERATE_TAGFILE = ../docs/doxytags_sresolv
PREDEFINED += SRES_CONTEXT_T="struct sres_context_s"
\ No newline at end of file
libsofia-sip-ua/sresolv/sofia-resolv/sres.h
View file @ 8b5d7e8d
......@@ -34,7 +34,8 @@
*
* @par Include Context
* @code
* #include <stdint.h>
* #include <sys/types.h>
* #include <sys/socket.h>
* #include <netinet/in.h>
* #include <sofia-resolv/sres.h>
* @endcode
......@@ -79,26 +80,26 @@ enum {
#ifndef SRES_RECORD_T
#define SRES_RECORD_T
/** Type representing any DNS record. */
typedef union sres_record sres_record_t;
#endif
#ifndef SRES_CACHE_T
#define SRES_CACHE_T
typedef struct sres_cache_s sres_cache_t;
/** Opaque type of DNS cache object. */
typedef struct sres_cache sres_cache_t;
#endif
/** Opaque type of DNS resolver object. */
typedef struct sres_resolver_s sres_resolver_t;
#ifndef SRES_ASYNC_T
#define SRES_ASYNC_T struct sres_async_s
#endif
typedef SRES_ASYNC_T sres_async_t;
#ifndef SRES_CONTEXT_T
#define SRES_CONTEXT_T struct sres_context_s
#endif
/** Application-defined type for sres_query_t context. */
typedef SRES_CONTEXT_T sres_context_t;
/** Opaque type of DNS query object. */
typedef struct sres_query_s sres_query_t;
struct sockaddr;
......@@ -109,18 +110,22 @@ sres_resolver_t *sres_resolver_new(char const *resolv_conf_path);
/** Copy a resolver. */
sres_resolver_t *sres_resolver_copy(sres_resolver_t *);
/** New resolver object. */
sres_resolver_t *
sres_resolver_new_with_cache(char const *conf_file_path,
sres_cache_t *cache,
char const *options, ...);
/** New resolver object. */
sres_resolver_t *
sres_resolver_new_with_cache_va(char const *conf_file_path,
sres_cache_t *cache,
char const *options, va_list va);
/** Increase reference count on a resolver object. */
sres_resolver_t *sres_resolver_ref(sres_resolver_t *res);
/** Decrease the reference count on a resolver object. */
void sres_resolver_unref(sres_resolver_t *res);
/** Re-read resolv.conf if needed */
......@@ -149,14 +154,14 @@ sres_query_t *sres_query(sres_resolver_t *res,
uint16_t type,
char const *domain);
/** Make a DNS query. */
/** Make a reverse DNS query. */
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 DNS query with socket. */
/** Make a DNS query with socket. @deprecated */
sres_query_t *sres_query_make(sres_resolver_t *res,
sres_answer_f *callback,
sres_context_t *context,
......@@ -164,7 +169,7 @@ sres_query_t *sres_query_make(sres_resolver_t *res,
uint16_t type,
char const *domain);
/** Make a reverse DNS query with socket. */
/** Make a reverse DNS query with socket. @deprecated */
sres_query_t *sres_query_make_sockaddr(sres_resolver_t *res,
sres_answer_f *callback,
sres_context_t *context,
......@@ -177,10 +182,12 @@ void sres_query_bind(sres_query_t *q,
sres_answer_f *callback,
sres_context_t *context);
/**Get a list of matching (type/domain) records from cache. */
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. */
sres_record_t **sres_cached_answers_sockaddr(sres_resolver_t *res,
uint16_t type,
struct sockaddr const *addr);
......@@ -197,7 +204,6 @@ int sres_blocking_query_sockaddr(sres_resolver_t *res,
struct sockaddr const *addr,
sres_record_t ***return_records);
/** Get a list of matching records from cache. */
/** Sort the list of records */
int sres_sort_answers(sres_resolver_t *res, sres_record_t **answers);
......
libsofia-sip-ua/sresolv/sofia-resolv/sres_async.h
View file @ 8b5d7e8d
......@@ -25,16 +25,18 @@
#ifndef SOFIA_RESOLV_SRES_ASYNC_H
/** Defined when <sofia-resolv/sres_async.h> has been included. */
#define SOFIA_RESOLV_SRES_ASYNC_H
/**
* @file sofia-resolv/sres_async.h
*
* Asynchronous interface for Sofia DNS Resolver.
*
* @author Pekka Pessi <Pekka.Pessi@nokia.com>,
* @author Pekka Pessi <Pekka.Pessi@nokia.com>
*
* @par Include Context
* @code
* #include <stdint.h>
* #include <sys/types.h>
* #include <sys/socket.h>
* #include <netinet/in.h>
* #include <sofia-resolv/sres.h>
* #include <sofia-resolv/sres_async.h>
......@@ -43,8 +45,14 @@
*/
#ifdef __cplusplus
extern "C" { }
extern "C" {
#endif
#ifndef SRES_ASYNC_T
#define SRES_ASYNC_T struct sres_async_s
#endif
/** Application-defined type for context used by asynchronous operation. */
typedef SRES_ASYNC_T sres_async_t;
/** Prototype for update function.
*
......
libsofia-sip-ua/sresolv/sofia-resolv/sres_cache.h
View file @ 8b5d7e8d
......@@ -32,8 +32,8 @@
*
* @par Include Context
* @code
* #include <stdint.h>
* #include <sys/types.h>
* #include <sys/socket.h>
* #include <netinet/in.h>
* #include <sofia-resolv/sres_cache.h>
* @endcode
......@@ -46,11 +46,13 @@ extern "C" {
#ifndef SRES_CACHE_T
#define SRES_CACHE_T
typedef struct sres_cache_s sres_cache_t;
/** Opaque type of DNS cache object. */
typedef struct sres_cache sres_cache_t;
#endif
#ifndef SRES_RECORD_T
#define SRES_RECORD_T
/** Type representing any DNS record. */
typedef union sres_record sres_record_t;
#endif
......
libsofia-sip-ua/sresolv/sofia-resolv/sres_record.h
View file @ 8b5d7e8d
......@@ -32,7 +32,8 @@
*
* @par Include Context
* @code
* #include <stdint.h>
* #include <sys/types.h>
* #include <sys/socket.h>
* #include <netinet/in.h>
* #include <sofia-resolv/sres_record.h>
* @endcode
......@@ -45,10 +46,10 @@ extern "C" {
#ifndef SRES_RECORD_T
#define SRES_RECORD_T
/** Type representing any DNS record. */
typedef union sres_record sres_record_t;
#endif
typedef struct sres_common sres_common_t;
typedef struct sres_generic sres_generic_t;
typedef struct sres_soa_record sres_soa_record_t;
typedef struct sres_a_record sres_a_record_t;
......@@ -59,8 +60,8 @@ typedef struct sres_ptr_record sres_ptr_record_t;
typedef struct sres_srv_record sres_srv_record_t;
typedef struct sres_naptr_record sres_naptr_record_t;
/** Common part of DNS record */
struct sres_common
/** Common part of all DNS records. */
typedef struct sres_common
{
int r_refcount; /**< Number of references to this record */
char *r_name; /**< Domain name */
......@@ -71,7 +72,7 @@ struct sres_common
uint32_t r_ttl; /**< Time-to-live */
uint16_t r_rdlen; /**< Length of record data */
uint16_t r_parsed; /**< Nonzero if parsed */
};
} sres_common_t;
/** Possible values for r_status (RCODE) */
enum {
......@@ -173,7 +174,7 @@ struct sres_naptr_record
char *na_replace;
};
/** Union of different records */
/** Union of different DNS records */
union sres_record
{
sres_common_t sr_record[1];
......
libsofia-sip-ua/sresolv/sofia-sip/sresolv.h
View file @ 8b5d7e8d
......@@ -22,12 +22,12 @@
*
*/
#ifndef SRESOLV_SOFIA_H
#ifndef SRESOLV_H
/** Defined when <sofia-sip/sresolv.h> has been included. */
#define SRESOLV_SOFIA_H
#define SRESOLV_H
/**
* @file sresolv_sofia.h Easy API for Sofia DNS Resolver.
* @file sresolv.h Easy API for Sofia DNS Resolver.
*
* @author Pekka Pessi <Pekka.Pessi@nokia.com>,
* @author Teemu Jalava <Teemu.Jalava@nokia.com>,
......@@ -49,27 +49,30 @@ SOFIA_BEGIN_DECLS
/** Filter tag matching any sresolv tag. */
#define SRESOLVTAG_ANY() srestag_any, ((tag_value_t)0)
extern tag_typedef_t srestag_any;
SOFIAPUBVAR tag_typedef_t srestag_any;
extern tag_typedef_t srestag_resolv_conf;
SOFIAPUBVAR tag_typedef_t srestag_resolv_conf;
/** Path of resolv.conf file. */
#define SRESTAG_RESOLV_CONF(x) srestag_resolv_conf, tag_str_v((x))
extern tag_typedef_t srestag_resolv_conf_ref;
SOFIAPUBVAR tag_typedef_t srestag_resolv_conf_ref;
#define SRESTAG_RESOLV_CONF_REF(x) srestag_resolv_conf_ref, tag_str_vr(&(x))
extern tag_typedef_t srestag_cache;
SOFIAPUBVAR tag_typedef_t srestag_cache;
/** Pointer to existing #sres_cache_t object. */
#define SRESTAG_CACHE(x) srestag_cache, tag_ptr_v((x))
extern tag_typedef_t srestag_cache_ref;
SOFIAPUBVAR tag_typedef_t srestag_cache_ref;
#define SRESTAG_CACHE_REF(x) srestag_cache_ref, tag_ptr_vr(&(x), (x))
/** Create a resolver object using @a root reactor. */
sres_resolver_t *sres_resolver_create(su_root_t *root,
char const *resolv_conf,
tag_type_t, tag_value_t, ...);
SOFIAPUBFUN sres_resolver_t *sres_resolver_create(su_root_t *root,
char const *resolv_conf,
tag_type_t, tag_value_t,
...);
/** Destroy a resolver object. */
int sres_resolver_destroy(sres_resolver_t *res);
SOFIAPUBFUN int sres_resolver_destroy(sres_resolver_t *res);
/* Return socket used by root. @deprecated */
int sres_resolver_root_socket(sres_resolver_t *res);
SOFIAPUBFUN int sres_resolver_root_socket(sres_resolver_t *res);
SOFIA_END_DECLS
......
libsofia-sip-ua/sresolv/sres.c
View file @ 8b5d7e8d
......@@ -115,7 +115,7 @@ typedef struct sres_config sres_config_t;
typedef struct sres_server sres_server_t;
typedef struct sres_nameserver sres_nameserver_t;
/** EDNS0 support */
/** EDNS0 support. @internal */
enum edns {
edns_not_tried = -1,
edns_not_supported = 0,
......@@ -507,7 +507,7 @@ sres_resolver_t *sres_resolver_copy(sres_resolver_t *res)
return sres_resolver_new_internal(cnffile, cache, options);
}
/**Create a resolver.
/**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
......@@ -520,7 +520,8 @@ sres_resolver_t *sres_resolver_copy(sres_resolver_t *res)
*
* @param conf_file_path name of the resolv.conf configuration file
* @param cache optional pointer to a resolver cache
* @param options, ... list of resolv.conf directives (overriding conf_file)
* @param option, ... list of resolv.conf options directives
* (overriding options in conf_file)
*
* @par Environment Variables
* - LOCALDOMAIN overrides @c domain or @c search directives
......@@ -655,7 +656,7 @@ sres_resolver_new_internal(char const *conf_file_path,
return NULL;
}
/** Create a new reference to resolver. */
/** Increase reference count on a resolver object. */
sres_resolver_t *
sres_resolver_ref(sres_resolver_t *res)
{
......@@ -915,12 +916,20 @@ sres_query_make_sockaddr(sres_resolver_t *res,
}
void sres_query_bind(sres_query_t *q,
/** Bind a query with another callback and context pointer.
*
* @param query pointer to a query object to bind
* @param callback pointer to new callback function (may be NULL)
* @param context pointer to callback context (may be NULL)
*/
void sres_query_bind(sres_query_t *query,
sres_answer_f *callback,
sres_context_t *context)
{
q->q_callback = callback;
q->q_context = context;
if (query) {
query->q_callback = callback;
query->q_context = context;
}
}
/**Get a list of matching (type/domain) records from cache.
......@@ -1057,6 +1066,11 @@ void sres_free_answer(sres_resolver_t *res, sres_record_t *answer)
sres_cache_free_one(res->res_cache, answer);
}
/** Free and zero an array of records.
*
* The array of records can be returned by sres_cached_answers() or
* given by callback function.
*/
void
sres_free_answers(sres_resolver_t *res,
sres_record_t **answers)
......@@ -2017,6 +2031,7 @@ sres_query_report_error(sres_query_t *q,
* The function sresolver_timer() should be called in regular intervals. We
* recommend calling it in 500 ms intervals.
*
* @param res pointer to resolver object
* @param dummy argument for compatibility
*/
void sres_resolver_timer(sres_resolver_t *res, int dummy)
......@@ -2030,9 +2045,9 @@ void sres_resolver_timer(sres_resolver_t *res, int dummy)
now = time(&res->res_now);
SU_DEBUG_9(("sres_resolver_timer() called at %lu\n", (long) now));
if (res->res_queries->qt_used) {
SU_DEBUG_9(("sres_resolver_timer() called at %lu\n", (long) now));
/** Every time it is called it goes through all query structures, and
* retransmits all the query messages, which have not been answered yet.
*/
......@@ -2168,8 +2183,6 @@ int sres_no_update(sres_async_t *async, int new_socket, int old_socket)
}
/** Create connected sockets for resolver.
*
* @related sres_resolver_t
*/
int sres_resolver_sockets(sres_resolver_t *res,
int *return_sockets,
......
libsofia-sip-ua/sresolv/sres_cache.c
View file @ 8b5d7e8d
......@@ -94,7 +94,7 @@ struct sres_rr_hash_entry_s {
#define SRES_HENTRY_HASH(e) ((e)->rr_hash_key)
struct sres_cache_s
struct sres_cache
{
su_home_t cache_home[1];
time_t cache_cleaned;
......
libsofia-sip-ua/sresolv/sresolv.docs
View file @ 8b5d7e8d
......@@ -3,7 +3,11 @@
@section sresolv_meta Module Information
The Sofia @b sresolv module consists of an asynchronous DNS resolver with
EDNS extensions. The interface to library is defined in <sresolv.h>.
EDNS extensions. The interface to library is declared in <sofia-sip/sresolv.h>.
An alternative interface is defined by <sofia-resolv/sres.h>,
<sofia-resolv/sres_record.h>, <sofia-resolv/sres_async.h>, and
<sofia-resolv/sres_cache.h>.
@CONTACT Pekka Pessi <Pekka.Pessi@nokia.com>
......@@ -11,7 +15,11 @@ EDNS extensions. The interface to library is defined in <sresolv.h>.
@LICENSE LGPL
@section sresolv_oveview Using SResolv
@todo Caching Policy and Cache Poisoning
The policy for caching non-authoritave entries should be solved.
@section sresolv_oveview Using Sofia Resolver
The sresolv works usually asynchronously, in other words, it sends a query
to DNS server and returns immediately to the caller. When the query is
......@@ -19,35 +27,39 @@ completed, sresolv signals application through a callback function.
The application can either explicitly poll(2) or select(2) on file
descriptors used by resolver and call the driver functions, or it can use
@ref su_root_t "su root" a pointer to a su_root_t object.
@ref su_root_t "su root" a pointer to a su_root_t object. Third option is to
use resolver synchronously with sres_blocking_query().
There is an internal cache used by sresolv. The query functions add
records to the cache: using the cache is made similar as if receiving
entries directly from DNS server.
@code
Please note that you have to create a separate resolver object for each
thread using Sofia resolver. The resolver objects can share the cache,
however.
#include <sys/types.h>
#include <sys/socket.h>
#include <netinet/in.h>
@section sofia_sip_sresolv_h Interface in <sofia-sip/sresolv.h>
#include <sofia-resolv/sres.h>
The simple use of Sofia resolver driven from #su_root_t is defined in
<sofia-sip/sresolv.h>. The resolver object can be created with
sres_resolver_create() and
sres_resolver_t *sres_resolver_new(char const *resolv_conf_path);
sres_resolver_t *sres_resolver_ref(sres_resolver_t *res);
void sres_resolver_unref(sres_resolver_t *res);
@code
#include <sofia-sip/sresolv.h>
sres_resolver_t *sres_resolver_copy(sres_resolver_t *);
sres_resolver_t *sres_resolver_create(su_root_t *root,
char const *resolv_conf,
tag_type_t, tag_value_t, ...);
void *sres_resolver_set_userdata(sres_resolver_t *res, void *userdata);
void *sres_resolver_get_userdata(sres_resolver_t const *res);
int sres_resolver_destroy(sres_resolver_t *res);
int sres_resolver_sockets(sres_resolver_t const *res, int *sockets, int n);
void sres_resolver_timer(sres_resolver_t *, int socket);
@endcode
int sres_resolver_receive(sres_resolver_t *res, int socket);
int sres_resolver_error(sres_resolver_t *res, int socket);
@section sres_query Sending DNS Queries
The second part of interface is used when sending DNS queries:
@code
sres_query_t *sres_query(sres_resolver_t *res,
sres_answer_f *callback,
sres_context_t *context,
......@@ -65,7 +77,14 @@ sres_query_t *sres_query_sockaddr(sres_resolver_t *res,
void sres_query_bind(sres_query_t *q,
sres_answer_f *callback,
sres_context_t *context);
@endcode
@section sres_record Handling DNS Records
The third part is used to handle the records which were returned by DNS
query or stored into the cache:
@code
sres_record_t **sres_cached_answers(sres_resolver_t *res,
uint16_t type,
char const *domain);
......@@ -85,9 +104,141 @@ void sres_free_answer(sres_resolver_t *res, sres_record_t *answer);
@endcode
@todo Caching polioxy and Cache Poisoning
@subsection sofia_sip_sresolv_h_example Using Sofia Resolver
The policy for caching non-authoritave entries should be solved.
Here is a short code fragment showing how to use resolver driven from
#su_root_t:
*/
@code
#define SRES_CONTEXT_T struct context
#include <sofia-sip/sresolv.h>
...
struct context
{
...
su_root_t *root;
sres_resolver_t *sres;
sres_query_t *query;
...
} *context;
...
context->sres = sres_resolver_create(context->root, NULL, TAG_END());
...
sres_record_t *results;
results = sres_cached_answers(context->sres, sres_type_naptr, domain);
if (results) {
process_natpr(context, NULL, results);
}
else {
context->query = sres_query(context->sres,
process_natpr, context,
sres_type_naptr, domain);
if (!context->query)
process_naptr(context, NULL, NULL);
}
}
...
void process_natpr(sres_context_t *context,
sres_query_t *q,
sres_record_t *answers[])
{
sres_sort_answers(context->sres, answers);
...
sres_free_answers(context->sres, answers);
}
@endcode
@section sofia_resolv_sres_h Interface in <sofia-resolv/sres.h>
The generic interface to Sofia resolver is defined in <sofia-resolv/sres.h>.
The first part of interface consists of functions for handling resolver
objects:
@code
#include <sys/types.h>
#include <sys/socket.h>
#include <netinet/in.h>
#include <sofia-resolv/sres.h>
sres_resolver_t *sres_resolver_new(char const *resolv_conf_path);
sres_resolver_t *sres_resolver_new_with_cache(char const *conf_file_path,
sres_cache_t *cache,
char const *options, ...);
sres_resolver_t *sres_resolver_ref(sres_resolver_t *res);
void sres_resolver_unref(sres_resolver_t *res);
sres_resolver_t *sres_resolver_copy(sres_resolver_t *);
void *sres_resolver_set_userdata(sres_resolver_t *res, void *userdata);
void *sres_resolver_get_userdata(sres_resolver_t const *res);
@endcode
@subsection sresolv_blocking Using Sofia Resolver Synchronously
It is possible to use Sofia resolver synchronously, that is, the function
call making the DNS query does not return until the query is responded or
times out.
@code
#include <sys/types.h>
#include <sys/socket.h>
#include <netinet/in.h>
#include <sofia-resolv/sres.h>
int sres_blocking_query(sres_resolver_t *res,
uint16_t type,
char const *domain,
sres_record_t ***return_records);
int sres_blocking_query_sockaddr(sres_resolver_t *res,
uint16_t type,
struct sockaddr const *addr,
sres_record_t ***return_records);
@endcode
@subsection sresolv_async Asynchronous Interface in <sofia-resolv/sres_async.h>
It is also possible to use resolver asynchronously without #su_root_t object.
@code
#include <sys/types.h>
#include <sys/socket.h>
#include <netinet/in.h>
#include <sofia-resolv/sres_async.h>
sres_async_t *sres_resolver_set_async(sres_resolver_t *res,
sres_update_f *update,
sres_async_t *async,
int update_all);
sres_async_t *sres_resolver_get_async(sres_resolver_t const *res,
sres_update_f *update);
int sres_resolver_sockets(sres_resolver_t const *res, int *sockets, int n);
void sres_resolver_timer(sres_resolver_t *, int socket);
int sres_resolver_receive(sres_resolver_t *res, int socket);