Skip to content
GitLab
Menu
Projects
Groups
Snippets
Loading...
Help
Help
Support
Community forum
Keyboard shortcuts
?
Submit feedback
Contribute to GitLab
Sign in
Toggle navigation
Menu
Open sidebar
BC
public
external
sofia-sip
Commits
30330bc8
Commit
30330bc8
authored
Sep 14, 2006
by
Pekka Pessi
Browse files
sresolv: updated documentation.
darcs-hash:20060914131438-65a35-ca7fc93f5ccb45147bb32d9c34d17fca844ce426.gz
parent
900ad089
Changes
3
Hide whitespace changes
Inline
Side-by-side
Showing
3 changed files
with
174 additions
and
145 deletions
+174
-145
libsofia-sip-ua/sresolv/sofia-resolv/sres_record.h
libsofia-sip-ua/sresolv/sofia-resolv/sres_record.h
+55
-54
libsofia-sip-ua/sresolv/sres.c
libsofia-sip-ua/sresolv/sres.c
+58
-29
libsofia-sip-ua/sresolv/sresolv.docs
libsofia-sip-ua/sresolv/sresolv.docs
+61
-62
No files found.
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_ove
r
view 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 S
ofia
resolv
er 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 <s
ofia
-
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
*/
Write
Preview
Markdown
is supported
0%
Try again
or
attach a new file
.
Attach a file
Cancel
You are about to add
0
people
to the discussion. Proceed with caution.
Finish editing this message first!
Cancel
Please
register
or
sign in
to comment