Skip to content

GitLab

Commit 30330bc8 authored by Pekka Pessi's avatar Pekka Pessi
Browse files

sresolv: updated documentation. 

darcs-hash:20060914131438-65a35-ca7fc93f5ccb45147bb32d9c34d17fca844ce426.gz
parent 900ad089
Hide whitespace changes
Inline Side-by-side
Showing with 174 additions and 145 deletions
libsofia-sip-ua/sresolv/sofia-resolv/sres_record.h
View file @ 30330bc8
......@@ -60,8 +60,8 @@ typedef struct sres_common
uint16_t r_parsed; /**< Nonzero if parsed */
} sres_common_t;
/** Possible values for r_status (RCODE) */
enum {
/** Possible values for r_status (RCODE) in #sres_common */
enum sres_status {
SRES_OK = 0, /**< No error condition. */
SRES_FORMAT_ERR = 1, /**< Server could not interpret query. */
SRES_SERVER_ERR = 2, /**< Server error. */
......@@ -107,7 +107,7 @@ typedef struct sres_a_record
*/
typedef struct
{
uint8_t u6_addr[16]; /**< 16 byte array */
uint8_t u6_addr[16]; /**< Array of 16 octets. */
} sres_in6_t;
/** Aggregated address record for IPv6 (@RFC2874, deprecated). */
......@@ -186,60 +186,61 @@ union sres_record
sres_naptr_record_t sr_naptr[1]; /**< NAPTR record */
};
/** Record classes */
enum {
sres_class_in = 1,
sres_class_any = 255
enum sres_class {
sres_class_in = 1, /**< Internet (@b IN) */
sres_class_any = 255 /**< Any class */
};
enum {
sres_type_a = 1, /**< IPv4 address. */
sres_type_ns = 2, /**< Authoritative server. */
sres_type_mf = 4, /**< Mail forwarder. */
sres_type_cname = 5, /**< Canonical name. */
sres_type_soa = 6, /**< Start of authority zone. */
sres_type_mb = 7, /**< Mailbox domain name. */
sres_type_mg = 8, /**< Mail group member. */
sres_type_mr = 9, /**< Mail rename name. */
sres_type_null = 10, /**< Null resource record. */
sres_type_wks = 11, /**< Well known service. */
sres_type_ptr = 12, /**< Domain name pointer. */
sres_type_hinfo = 13, /**< Host information. */
sres_type_minfo = 14, /**< Mailbox information. */
sres_type_mx = 15, /**< Mail routing information. */
sres_type_txt = 16, /**< Text strings. */
sres_type_rp = 17, /**< Responsible person. */
sres_type_afsdb = 18, /**< AFS cell database. */
sres_type_x25 = 19, /**< X_25 calling address. */
sres_type_isdn = 20, /**< ISDN calling address. */
sres_type_rt = 21, /**< Router. */
sres_type_nsap = 22, /**< NSAP address. */
sres_type_nsap_ptr = 23, /**< Reverse NSAP lookup. */
sres_type_sig = 24, /**< Security signature. */
sres_type_key = 25, /**< Security key. */
sres_type_px = 26, /**< X.400 mail mapping. */
sres_type_gpos = 27, /**< ICBM record. */
sres_type_aaaa = 28, /**< IPv6 Address. */
sres_type_loc = 29, /**< Location Information. */
sres_type_nxt = 30, /**< Next domain. */
sres_type_eid = 31, /**< Endpoint identifier. */
sres_type_nimloc = 32, /**< Nimrod Locator. */
sres_type_srv = 33, /**< Server Selection. */
sres_type_atma = 34, /**< ATM Address */
sres_type_naptr = 35, /**< Naming Authority PoinTeR (@RFC2915) */
sres_type_kx = 36, /**< Key Exchange */
sres_type_cert = 37, /**< Certification record */
sres_type_a6 = 38, /**< IPv6 address (deprecates AAAA) */
sres_type_dname = 39, /**< Non-terminal DNAME (for IPv6) */
sres_type_sink = 40, /**< Kitchen sink (experimental) */
sres_type_opt = 41, /**< EDNS 0 option (@RFC2671) */
enum sres_qtypes {
sres_type_a = 1, /**< IPv4 address (#sres_a_record). */
sres_type_ns = 2, /**< Authoritative server. */
sres_type_mf = 4, /**< Mail forwarder. */
sres_type_cname = 5, /**< Canonical name (#sres_cname_record). */
sres_type_soa = 6, /**< Start of authority zone (#sres_soa_record). */
sres_type_mb = 7, /**< Mailbox domain name. */
sres_type_mg = 8, /**< Mail group member. */
sres_type_mr = 9, /**< Mail rename name. */
sres_type_null = 10, /**< Null resource record. */
sres_type_wks = 11, /**< Well known service. */
sres_type_ptr = 12, /**< Domain name pointer (#sres_ptr_record). */
sres_type_hinfo = 13, /**< Host information. */
sres_type_minfo = 14, /**< Mailbox information. */
sres_type_mx = 15, /**< Mail routing information. */
sres_type_txt = 16, /**< Text strings. */
sres_type_rp = 17, /**< Responsible person. */
sres_type_afsdb = 18, /**< AFS cell database. */
sres_type_x25 = 19, /**< X_25 calling address. */
sres_type_isdn = 20, /**< ISDN calling address. */
sres_type_rt = 21, /**< Router. */
sres_type_nsap = 22, /**< NSAP address. */
sres_type_nsap_ptr = 23, /**< Reverse NSAP lookup. */
sres_type_sig = 24, /**< Security signature. */
sres_type_key = 25, /**< Security key. */
sres_type_px = 26, /**< X.400 mail mapping. */
sres_type_gpos = 27, /**< ICBM record. */
sres_type_aaaa = 28, /**< IPv6 Address (#sres_aaaa_record). */
sres_type_loc = 29, /**< Location Information. */
sres_type_nxt = 30, /**< Next domain. */
sres_type_eid = 31, /**< Endpoint identifier. */
sres_type_nimloc = 32, /**< Nimrod Locator. */
sres_type_srv = 33, /**< Server Selection (@RFC2782,
#sres_srv_record). */
sres_type_atma = 34, /**< ATM Address */
sres_type_naptr = 35, /**< Naming Authority PoinTeR (@RFC2915,
#sres_naptr_record) */
sres_type_kx = 36, /**< Key Exchange */
sres_type_cert = 37, /**< Certification record */
sres_type_a6 = 38, /**< IPv6 address (deprecates AAAA) */
sres_type_dname = 39, /**< Non-terminal DNAME (for IPv6) */
sres_type_sink = 40, /**< Kitchen sink (experimental) */
sres_type_opt = 41, /**< EDNS 0 option (@RFC2671) */
sres_qtype_tsig = 250, /**< Transaction signature. */
sres_qtype_ixfr = 251, /**< Incremental zone transfer. */
sres_qtype_axfr = 252, /**< Transfer zone of authority. */
sres_qtype_mailb = 253, /**< Transfer mailbox records. */
sres_qtype_maila = 254, /**< Transfer mail agent records. */
sres_qtype_any = 255 /**< Wildcard match. */
sres_qtype_tsig = 250, /**< Transaction signature. */
sres_qtype_ixfr = 251, /**< Incremental zone transfer. */
sres_qtype_axfr = 252, /**< Transfer zone of authority. */
sres_qtype_mailb = 253, /**< Transfer mailbox records. */
sres_qtype_maila = 254, /**< Transfer mail agent records. */
sres_qtype_any = 255 /**< Wildcard match. */
};
/** Convert type to its name. */
......
libsofia-sip-ua/sresolv/sres.c
View file @ 30330bc8
......@@ -799,12 +799,40 @@ sres_resolver_get_async(sres_resolver_t const *res,
/**Send a DNS query.
*
* Sends a DNS query with specified @a type and @a 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.
* Sends a DNS query with specified @a type and @a domain to the DNS server.
* When an answer is received, the @a callback function is called with
* @a 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.
*
* @param res pointer to resolver
* @param callback function called when query is answered or times out
* @param context pointer given as an extra argument to @a callback function
* @param type record type to query (see #sres_qtypes)
* @param 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 @b 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.
*
* @sa sres_search(), sres_blocking_query(), sres_query_make()
* @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.
*
* @sa sres_search(), sres_blocking_query(), sres_cached_answers()
*
* @ERRORS
* @ERROR EFAULT @a res or @a domain point outside the address space
......@@ -850,11 +878,14 @@ sres_query(sres_resolver_t *res,
*
* Sends DNS queries with specified @a type and @a name to the DNS server.
* If the @a 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.
* appended to the name and resulting domain name are also queried. When
* answer to all the search domains is received, the @a callback function
* is called with @a 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.
*
* @param res pointer to resolver object
* @param callback pointer to completion function
......@@ -867,7 +898,7 @@ sres_query(sres_resolver_t *res,
* @ERROR ENAMETOOLONG @a domain is longer than SRES_MAXDNAME
* @ERROR ENOMEM memory exhausted
*
* @sa sres_query(), sres_blocking_search()
* @sa sres_query(), sres_blocking_search(), sres_search_cached_answers().
*/
sres_query_t *
sres_search(sres_resolver_t *res,
......@@ -961,9 +992,20 @@ sres_search(sres_resolver_t *res,
*
* Send a query to DNS server with specified @a type and domain name formed
* from the socket address @a 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.
* 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.
*
* @param res pointer to resolver
* @param callback function called when query is answered or times out
* @param context pointer given as an extra argument to @a callback function
* @param type record type to query (or sres_qtype_any for any record)
* @param addr socket address structure
*
* The @a type should be #sres_type_ptr. The @a addr should contain either
* IPv4 (AF_INET) or IPv6 (AF_INET6) address.
*
* If the "options"
*/
sres_query_t *
sres_query_sockaddr(sres_resolver_t *res,
......@@ -986,13 +1028,7 @@ sres_query_sockaddr(sres_resolver_t *res,
/** Make a DNS query.
*
* Sends a DNS query with specified @a type and @a 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 @a socket is valid,
* otherwise it behaves exactly like sres_query().
* @deprecated Use sres_query() instead.
*/
sres_query_t *
sres_query_make(sres_resolver_t *res,
......@@ -1007,14 +1043,7 @@ sres_query_make(sres_resolver_t *res,
/** Make a reverse DNS query.
*
* Send a query to DNS server with specified @a type and domain name formed
* from the socket address @a 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 @a socket is valid,
* otherwise it behaves exactly like sres_query_sockaddr().
* @deprecated Use sres_query_sockaddr() instead.
*/
sres_query_t *
sres_query_make_sockaddr(sres_resolver_t *res,
......
libsofia-sip-ua/sresolv/sresolv.docs
View file @ 30330bc8
......@@ -19,7 +19,7 @@ An alternative interface is defined by <sofia-resolv/sres.h>,
The policy for caching non-authoritave entries should be solved.
@section sresolv_oveview Using Sofia Resolver
@section sresolv_overview 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
......@@ -27,7 +27,7 @@ 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. Third option is to
@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
......@@ -42,7 +42,8 @@ however.
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_create(). The provided @ref su_root_t "root object" takes care
of calling the sres_query() and sres_query_sockaddr() callback functions.
@code
#include <sofia-sip/sresolv.h>
......@@ -104,62 +105,6 @@ void sres_free_answer(sres_resolver_t *res, sres_record_t *answer);
@endcode
@subsection sofia_sip_sresolv_h_example Using Sofia Resolver
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>.
......@@ -192,9 +137,9 @@ void *sres_resolver_get_userdata(sres_resolver_t const *res);
@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.
The blocking interface defined in <sofia-resolv/sres.h> makes it possible to
use Sofia resolver synchronously, that is, the function call making the DNS
query does not return until the query is responded or it times out.
@code
#include <sys/types.h>
......@@ -241,4 +186,58 @@ int sres_resolver_error(sres_resolver_t *res, int socket);
@endcode
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
*/
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment