Add support for ICE/STUN/TURN in res_rtp_asterisk and chan_sip.
[asterisk/asterisk.git] / res / pjproject / pjsip / include / pjsip / sip_module.h
1 /* $Id$ */
2 /* 
3  * Copyright (C) 2008-2011 Teluu Inc. (http://www.teluu.com)
4  * Copyright (C) 2003-2008 Benny Prijono <benny@prijono.org>
5  *
6  * This program is free software; you can redistribute it and/or modify
7  * it under the terms of the GNU General Public License as published by
8  * the Free Software Foundation; either version 2 of the License, or
9  * (at your option) any later version.
10  *
11  * This program is distributed in the hope that it will be useful,
12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
14  * GNU General Public License for more details.
15  *
16  * You should have received a copy of the GNU General Public License
17  * along with this program; if not, write to the Free Software
18  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA 
19  */
20 #ifndef __PJSIP_SIP_MODULE_H__
21 #define __PJSIP_SIP_MODULE_H__
22
23 /**
24  * @file sip_module.h
25  * @brief Module helpers
26  */
27 #include <pjsip/sip_types.h>
28 #include <pj/list.h>
29
30 PJ_BEGIN_DECL
31
32 /**
33  * @defgroup PJSIP_MOD Modules
34  * @ingroup PJSIP_CORE_CORE
35  * @brief Modules are the primary means to extend PJSIP!
36  * @{
37  * Modules are the primary means to extend PJSIP. Without modules, PJSIP
38  * would not know how to handle messages, and will simply discard all
39  * incoming messages.
40  *
41  * Modules are registered by creating and initializing #pjsip_module 
42  * structure, and register the structure to PJSIP with 
43  * #pjsip_endpt_register_module().
44  *
45  * The <A HREF="/docs.htm">PJSIP Developer's Guide</A>
46  * has a thorough discussion on this subject, and readers are encouraged
47  * to read the document for more information.
48  */
49
50 /**
51  * The declaration for SIP module. This structure would be passed to
52  * #pjsip_endpt_register_module() to register the module to PJSIP.
53  */
54 struct pjsip_module
55 {
56     /** To allow chaining of modules in the endpoint. */
57     PJ_DECL_LIST_MEMBER(struct pjsip_module);
58
59     /**
60      * Module name to identify the module.
61      *
62      * This field MUST be initialized before registering the module.
63      */
64     pj_str_t name;
65
66     /**
67      * Module ID. Application must initialize this field with -1 before
68      * registering the module to PJSIP. After the module is registered,
69      * this field will contain a unique ID to identify the module.
70      */
71     int id;
72
73     /**
74      * Integer number to identify module initialization and start order with
75      * regard to other modules. Higher number will make the module gets
76      * initialized later.
77      *
78      * This field MUST be initialized before registering the module.
79      */
80     int priority;
81
82     /**
83      * Optional function to be called to initialize the module. This function
84      * will be called by endpoint during module registration. If the value
85      * is NULL, then it's equal to returning PJ_SUCCESS.
86      *
87      * @param endpt     The endpoint instance.
88      * @return          Module should return PJ_SUCCESS to indicate success.
89      */
90     pj_status_t (*load)(pjsip_endpoint *endpt);
91
92     /**
93      * Optional function to be called to start the module. This function
94      * will be called by endpoint during module registration. If the value
95      * is NULL, then it's equal to returning PJ_SUCCESS.
96      *
97      * @return          Module should return zero to indicate success.
98      */
99     pj_status_t (*start)(void);
100
101     /**
102      * Optional function to be called to deinitialize the module before
103      * it is unloaded. This function will be called by endpoint during 
104      * module unregistration. If the value is NULL, then it's equal to 
105      * returning PJ_SUCCESS.
106      *
107      * @return          Module should return PJ_SUCCESS to indicate success.
108      */
109     pj_status_t (*stop)(void);
110
111     /**
112      * Optional function to be called to deinitialize the module before
113      * it is unloaded. This function will be called by endpoint during 
114      * module unregistration. If the value is NULL, then it's equal to 
115      * returning PJ_SUCCESS.
116      *
117      * @param mod       The module.
118      *
119      * @return          Module should return PJ_SUCCESS to indicate success.
120      */
121     pj_status_t (*unload)(void);
122
123     /**
124      * Optional function to be called to process incoming request message.
125      *
126      * @param rdata     The incoming message.
127      *
128      * @return          Module should return PJ_TRUE if it handles the request,
129      *                  or otherwise it should return PJ_FALSE to allow other
130      *                  modules to handle the request.
131      */
132     pj_bool_t (*on_rx_request)(pjsip_rx_data *rdata);
133
134     /**
135      * Optional function to be called to process incoming response message.
136      *
137      * @param rdata     The incoming message.
138      *
139      * @return          Module should return PJ_TRUE if it handles the 
140      *                  response, or otherwise it should return PJ_FALSE to 
141      *                  allow other modules to handle the response.
142      */
143     pj_bool_t (*on_rx_response)(pjsip_rx_data *rdata);
144
145     /**
146      * Optional function to be called when transport layer is about to
147      * transmit outgoing request message.
148      *
149      * @param tdata     The outgoing request message.
150      *
151      * @return          Module should return PJ_SUCCESS in all cases. 
152      *                  If non-zero (or PJ_FALSE) is returned, the message 
153      *                  will not be sent.
154      */
155     pj_status_t (*on_tx_request)(pjsip_tx_data *tdata);
156
157     /**
158      * Optional function to be called when transport layer is about to
159      * transmit outgoing response message.
160      *
161      * @param tdata     The outgoing response message.
162      *
163      * @return          Module should return PJ_SUCCESS in all cases. 
164      *                  If non-zero (or PJ_FALSE) is returned, the message 
165      *                  will not be sent.
166      */
167     pj_status_t (*on_tx_response)(pjsip_tx_data *tdata);
168
169     /**
170      * Optional function to be called when this module is acting as 
171      * transaction user for the specified transaction, when the 
172      * transaction's state has changed.
173      *
174      * @param tsx       The transaction.
175      * @param event     The event which has caused the transaction state
176      *                  to change.
177      */
178     void (*on_tsx_state)(pjsip_transaction *tsx, pjsip_event *event);
179
180 };
181
182
183 /**
184  * Module priority guidelines.
185  */
186 enum pjsip_module_priority
187 {
188     /** 
189      * This is the priority used by transport layer.
190      */
191     PJSIP_MOD_PRIORITY_TRANSPORT_LAYER  = 8,
192
193     /**
194      * This is the priority used by transaction layer.
195      */
196     PJSIP_MOD_PRIORITY_TSX_LAYER        = 16,
197
198     /**
199      * This is the priority used by the user agent and proxy layer.
200      */
201     PJSIP_MOD_PRIORITY_UA_PROXY_LAYER   = 32,
202
203     /**
204      * This is the priority used by the dialog usages.
205      */
206     PJSIP_MOD_PRIORITY_DIALOG_USAGE     = 48,
207
208     /**
209      * This is the recommended priority to be used by applications.
210      */
211     PJSIP_MOD_PRIORITY_APPLICATION      = 64
212 };
213
214
215 /**
216  * @}
217  */
218
219 PJ_END_DECL
220
221 #endif  /* __PJSIP_SIP_MODULE_H__ */
222