Scope Tracing: A new facility for tracing scope enter/exit
[asterisk/asterisk.git] / include / asterisk / srv.h
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 1999 - 2013, Digium, Inc.
5  *
6  * Mark Spencer <markster@digium.com>
7  *
8  * See http://www.asterisk.org for more information about
9  * the Asterisk project. Please do not directly contact
10  * any of the maintainers of this project for assistance;
11  * the project provides a web site, mailing lists and IRC
12  * channels for your use.
13  *
14  * This program is free software, distributed under the terms of
15  * the GNU General Public License Version 2. See the LICENSE file
16  * at the top of the source tree.
17  */
18
19 /*
20  * DNS SRV record support
21  */
22
23 #ifndef _ASTERISK_SRV_H
24 #define _ASTERISK_SRV_H
25
26 /*! \file srv.h
27  *
28  * \brief Support for DNS SRV records, used in to locate SIP services.
29  *
30  * \note Note: This SRV record support will respect the priority and weight
31  *      elements of the records that are returned, but there are no provisions
32  *      for retrying or failover between records.
33  */
34
35 /*! \brief An opaque type, for lookup usage */
36 struct srv_context;
37
38 /*! \brief Retrieve set of SRV lookups, in order
39  *
40  * \param[in] context A pointer in which to hold the result
41  * \param[in] service The service name to look up
42  * \param[out] host Result host
43  * \param[out] port Associated TCP portnum
44  *
45  * \retval -1 Query failed
46  * \retval 0 Result exists in host and port
47  * \retval 1 No more results
48  */
49 extern int ast_srv_lookup(struct srv_context **context, const char *service, const char **host, unsigned short *port);
50
51 /*! \brief Cleanup resources associated with ast_srv_lookup
52  *
53  * \param context Pointer passed into ast_srv_lookup
54  */
55 void ast_srv_cleanup(struct srv_context **context);
56
57 /*! \brief Lookup entry in SRV records Returns 1 if found, 0 if not found, -1 on hangup
58  *
59  * Only do SRV record lookup if you get a domain without a port. If you get a port #, it's a DNS host name.
60  *
61  * \param chan Ast channel
62  * \param host host name (return value)
63  * \param hostlen Length of string "host"
64  * \param port Port number (return value)
65  * \param service Service tag for SRV lookup (like "_sip._udp" or "_stun._udp"
66  */
67 extern int ast_get_srv(struct ast_channel *chan, char *host, int hostlen, int *port, const char *service);
68
69 /*!
70  * \brief Get the number of records for a given SRV context
71  *
72  * \details
73  * This is meant to be used after calling ast_srv_lookup, so that
74  * one may retrieve the number of records returned during a specific
75  * SRV lookup.
76  *
77  * \param context The context returned by ast_srv_lookup
78  *
79  * \return Number of records in context
80  */
81 unsigned int ast_srv_get_record_count(struct srv_context *context);
82
83 /*!
84  * \brief Retrieve details from a specific SRV record
85  *
86  * \details
87  * After calling ast_srv_lookup, the srv_context will contain
88  * the data from several records. You can retrieve the data
89  * of a specific one by asking for a specific record number. The
90  * records are sorted based on priority and secondarily based on
91  * weight. See RFC 2782 for the exact sorting rules.
92  *
93  * \param context The context returned by ast_srv_lookup
94  * \param record_num The 1-indexed record number to retrieve
95  * \param[out] host The host portion of the record
96  * \param[out] port The port portion of the record
97  * \param[out] priority The priority portion of the record
98  * \param[out] weight The weight portion of the record
99  *
100  * \retval -1 Failed to retrieve information.
101  *      Likely due to an out of range record_num
102  * \retval 0 Success
103  */
104 int ast_srv_get_nth_record(struct srv_context *context, int record_num, const char **host,
105                 unsigned short *port, unsigned short *priority, unsigned short *weight);
106 #endif /* _ASTERISK_SRV_H */