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