chan_sip: Isolate code that manages struct sip_route.
[asterisk/asterisk.git] / channels / sip / include / route.h
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2013, Digium, Inc.
5  *
6  * See http://www.asterisk.org for more information about
7  * the Asterisk project. Please do not directly contact
8  * any of the maintainers of this project for assistance;
9  * the project provides a web site, mailing lists and IRC
10  * channels for your use.
11  *
12  * This program is free software, distributed under the terms of
13  * the GNU General Public License Version 2. See the LICENSE file
14  * at the top of the source tree.
15  */
16
17 /*!
18  * \file
19  * \brief sip_route header file
20  */
21
22 #ifndef _SIP_ROUTE_H
23 #define _SIP_ROUTE_H
24
25 #include "asterisk/linkedlists.h"
26 #include "asterisk/strings.h"
27
28 /*!
29  * \brief Opaque storage of a sip route hop
30  */
31 struct sip_route_hop;
32
33 /*!
34  * \internal \brief Internal enum to remember last calculated
35  */
36 enum sip_route_type {
37         route_loose = 0,    /*!< The first hop contains ;lr or does not exist */
38         route_strict,       /*!< The first hop exists and does not contain ;lr */
39         route_invalidated,  /*!< strict/loose routing needs to be rechecked */
40 };
41
42 /*!
43  * \brief Structure to store route information
44  *
45  * \note This must be zero-filled on allocation
46  */
47 struct sip_route {
48         AST_LIST_HEAD_NOLOCK(, sip_route_hop) list;
49         enum sip_route_type type;
50 };
51
52 /*!
53  * \brief Add a new hop to the route
54  *
55  * \param route Route
56  * \param uri Address of this hop
57  * \param len Length of hop not including null terminator
58  * \param inserthead If true then inserted the new route to the top of the list
59  *
60  * \retval Pointer to null terminated copy of URI on success
61  * \retval NULL on error
62  */
63 const char *sip_route_add(struct sip_route *route, const char *uri, size_t len, int inserthead);
64
65 /*!
66  * \brief Add routes from header
67  *
68  * \note This procedure is for headers that require use of <brackets>.
69  */
70 void sip_route_process_header(struct sip_route *route, const char *header, int inserthead);
71
72 /*!
73  * \brief copy route-set
74  *
75  * \retval non-zero on failure
76  * \retval 0 on success
77  */
78 void sip_route_copy(struct sip_route *dst, const struct sip_route *src);
79
80 /*!
81  * \brief Free all routes in the list
82  */
83 void sip_route_clear(struct sip_route *route);
84
85 /*!
86  * \brief Verbose dump of all hops for debugging
87  */
88 void sip_route_dump(const struct sip_route *route);
89
90 /*!
91  * \brief Make the comma separated list of route hops
92  *
93  * \param route Source of route list
94  * \param formatcli Add's space after comma's, print's N/A if list is empty.
95  * \param skip Number of hops to skip
96  *
97  * \retval an allocated struct ast_str on success
98  * \retval NULL on failure
99  */
100 struct ast_str *sip_route_list(const struct sip_route *route, int formatcli, int skip)
101                 __attribute_malloc__ __attribute_warn_unused_result__;
102
103 /*!
104  * \brief Check if the route is strict
105  *
106  * \note The result is cached in route->type
107  */
108 int sip_route_is_strict(struct sip_route *route);
109
110 /*!
111  * \brief Get the URI of the route's first hop
112  */
113 const char *sip_route_first_uri(const struct sip_route *route);
114
115 /*!
116  * \brief Check if route has no URI's
117  */
118 #define sip_route_empty(route) AST_LIST_EMPTY(&(route)->list)
119
120 #endif