Tristan Matthews | 0a329cc | 2013-07-17 13:20:14 -0400 | [diff] [blame] | 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 | |