res_pjproject: Add utility functions to convert between socket structures
[asterisk/asterisk.git] / include / asterisk / res_pjproject.h
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2016, Fairview 5 Engineering, LLC
5  *
6  * George Joseph <george.joseph@fairview5.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 #ifndef _RES_PJPROJECT_H
20 #define _RES_PJPROJECT_H
21
22 #include <pj/types.h>
23 #include <pj/pool.h>
24
25 struct ast_sockaddr;
26
27 /*!
28  * \brief Retrieve a pjproject build option
29  *
30  * \param option The build option requested
31  * \param format_string A scanf-style format string to parse the option value into
32  * \param ... Pointers to variables to receive the values parsed
33  *
34  * \retval The number of values parsed
35  *
36  * \since 13.8.0
37  *
38  * \note The option requested must be from those returned by pj_dump_config()
39  * which can be displayed with the 'pjsip show buildopts' CLI command.
40  *
41  *   <b>Sample Usage:</b>
42  *   \code
43  *
44  *   int max_hostname;
45  *
46  *   ast_sip_get_pjproject_buildopt("PJ_MAX_HOSTNAME", "%d", &max_hostname);
47  *
48  *   \endcode
49  *
50  */
51 int ast_pjproject_get_buildopt(char *option, char *format_string, ...) __attribute__((format(scanf, 2, 3)));
52
53 /*!
54  * \brief Begin PJPROJECT log interception for CLI output.
55  * \since 13.8.0
56  *
57  * \param fd CLI file descriptior to send intercepted output.
58  *
59  * \note ast_pjproject_log_intercept_begin() and
60  * ast_pjproject_log_intercept_end() must always be called
61  * in pairs.
62  *
63  * \return Nothing
64  */
65 void ast_pjproject_log_intercept_begin(int fd);
66
67 /*!
68  * \brief End PJPROJECT log interception for CLI output.
69  * \since 13.8.0
70  *
71  * \note ast_pjproject_log_intercept_begin() and
72  * ast_pjproject_log_intercept_end() must always be called
73  * in pairs.
74  *
75  * \return Nothing
76  */
77 void ast_pjproject_log_intercept_end(void);
78
79 /*!
80  * \brief Initialize the caching pool factory.
81  * \since 13.21.0
82  *
83  * \param cp Caching pool factory to initialize
84  * \param policy Pool factory policy
85  * \param max_capacity Total capacity to be retained in the cache.  Zero disables caching.
86  *
87  * \return Nothing
88  */
89 void ast_pjproject_caching_pool_init(pj_caching_pool *cp,
90         const pj_pool_factory_policy *policy, pj_size_t max_capacity);
91
92 /*!
93  * \brief Destroy caching pool factory and all cached pools.
94  * \since 13.21.0
95  *
96  * \param cp Caching pool factory to destroy
97  *
98  * \return Nothing
99  */
100 void ast_pjproject_caching_pool_destroy(pj_caching_pool *cp);
101
102 /*!
103  * \brief Fill a pj_sockaddr from an ast_sockaddr
104  * \since 13.24.0
105  *
106  * \param addr The source address to copy
107  * \param pjaddr The target address to receive the copied address
108  *
109  * \retval 0 Success
110  * \retval -1 Failure
111  */
112 int ast_sockaddr_to_pj_sockaddr(const struct ast_sockaddr *addr, pj_sockaddr *pjaddr);
113
114 /*!
115  * \brief Fill an ast_sockaddr from a pj_sockaddr
116  * \since 13.24.0
117  *
118  * \param addr The target address to receive the copied address
119  * \param pjaddr The source address to copy
120  *
121  * \retval 0 Success
122  * \retval -1 Failure
123  */
124 int ast_sockaddr_from_pj_sockaddr(struct ast_sockaddr *addr, const pj_sockaddr *pjaddr);
125
126 #endif /* _RES_PJPROJECT_H */