Add support for ICE/STUN/TURN in res_rtp_asterisk and chan_sip.
[asterisk/asterisk.git] / res / pjproject / pjsip / include / pjsip-ua / sip_regc.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_REG_H__
21 #define __PJSIP_SIP_REG_H__
22
23 /**
24  * @file sip_regc.h
25  * @brief SIP Registration Client
26  */
27
28 #include <pjsip/sip_types.h>
29 #include <pjsip/sip_auth.h>
30 #include <pjsip/sip_transport.h>
31
32
33 /**
34  * @defgroup PJSUA_REGC Client Registration
35  * @ingroup PJSIP_HIGH_UA
36  * @brief High Layer API for performing client registration.
37  * @{
38  *
39  * This provides API for performing client registration. Application must
40  * link with  <b>pjsip-ua</b> static library to use this API.
41
42  */
43
44
45 PJ_BEGIN_DECL
46
47 /** Typedef for client registration data. */
48 typedef struct pjsip_regc pjsip_regc;
49
50 /** Maximum contacts in registration. */
51 #define PJSIP_REGC_MAX_CONTACT  10
52
53 /** Expiration not specified. */
54 #define PJSIP_REGC_EXPIRATION_NOT_SPECIFIED     ((pj_uint32_t)0xFFFFFFFFUL)
55
56 /** Buffer to hold all contacts. */
57 #define PJSIP_REGC_CONTACT_BUF_SIZE     512
58
59 /** Structure to hold parameters when calling application's callback.
60  *  The application's callback is called when the client registration process
61  *  has finished.
62  */
63 struct pjsip_regc_cbparam
64 {
65     pjsip_regc          *regc;      /**< Client registration structure.     */
66     void                *token;     /**< Arbitrary token set by application */
67
68     /** Error status. If this value is non-PJ_SUCCESS, some error has occured.
69      *  Note that even when this contains PJ_SUCCESS the registration might
70      *  have failed; in this case the \a code field will contain non
71      *  successful (non-2xx status class) code
72      */
73     pj_status_t          status;
74     int                  code;      /**< SIP status code received.          */
75     pj_str_t             reason;    /**< SIP reason phrase received.        */
76     pjsip_rx_data       *rdata;     /**< The complete received response.    */
77     int                  expiration;/**< Next expiration interval.          */
78     int                  contact_cnt;/**<Number of contacts in response.    */
79     pjsip_contact_hdr   *contact[PJSIP_REGC_MAX_CONTACT]; /**< Contacts.    */
80 };
81
82
83 /** Type declaration for callback to receive registration result. */
84 typedef void pjsip_regc_cb(struct pjsip_regc_cbparam *param);
85
86 /**
87  * Client registration information.
88  */
89 struct pjsip_regc_info
90 {
91     pj_str_t    server_uri; /**< Server URI,                                */
92     pj_str_t    client_uri; /**< Client URI (From header).                  */
93     pj_bool_t   is_busy;    /**< Have pending transaction?                  */
94     pj_bool_t   auto_reg;   /**< Will register automatically?               */
95     int         interval;   /**< Registration interval (seconds).           */
96     int         next_reg;   /**< Time until next registration (seconds).    */
97     pjsip_transport *transport; /**< Last transport used.                   */
98 };
99
100 /**
101  * @see pjsip_regc_info
102  */
103 typedef struct pjsip_regc_info pjsip_regc_info;
104
105
106 /**
107  * Get the module instance for client registration module.
108  *
109  * @return          client registration module.
110  */
111 PJ_DECL(pjsip_module*) pjsip_regc_get_module(void);
112
113
114 /**
115  * Create client registration structure.
116  *
117  * @param endpt     Endpoint, used to allocate pool from.
118  * @param token     A data to be associated with the client registration struct.
119  * @param cb        Pointer to callback function to receive registration status.
120  * @param p_regc    Pointer to receive client registration structure.
121  *
122  * @return          PJ_SUCCESS on success.
123  */
124 PJ_DECL(pj_status_t) pjsip_regc_create( pjsip_endpoint *endpt, void *token,
125                                         pjsip_regc_cb *cb, 
126                                         pjsip_regc **p_regc);
127
128
129 /**
130  * Destroy client registration structure. If a registration transaction is
131  * in progress, then the structure will be deleted only after a final response
132  * has been received, and in this case, the callback won't be called.
133  *
134  * @param regc      The client registration structure.
135  *
136  * @return          PJ_SUCCESS on success.
137  */
138 PJ_DECL(pj_status_t) pjsip_regc_destroy(pjsip_regc *regc);
139
140 /**
141  * Get registration info.
142  *
143  * @param regc      The client registration structure.
144  * @param info      Client registration info.
145  *
146  * @return          PJ_SUCCESS on success.
147  */
148 PJ_DECL(pj_status_t) pjsip_regc_get_info( pjsip_regc *regc,
149                                           pjsip_regc_info *info );
150
151
152 /**
153  * Get the memory pool associated with a registration client handle.
154  *
155  * @param regc      The client registration structure.
156  * @return pool     handle.
157  */
158 PJ_DECL(pj_pool_t*) pjsip_regc_get_pool(pjsip_regc *regc);
159
160 /**
161  * Initialize client registration structure with various information needed to
162  * perform the registration.
163  *
164  * @param regc      The client registration structure.
165  * @param srv_url   Server URL.
166  * @param from_url  The person performing the registration, must be a SIP URL type.
167  * @param to_url    The address of record for which the registration is targetd, must
168  *                  be a SIP/SIPS URL.
169  * @param ccnt      Number of contacts in the array.
170  * @param contact   Array of contacts, each contact item must be formatted
171  *                  as described in RFC 3261 Section 20.10:
172  *                  When the header field value contains a display 
173  *                  name, the URI including all URI parameters is 
174  *                  enclosed in "<" and ">".  If no "<" and ">" are 
175  *                  present, all parameters after the URI are header
176  *                  parameters, not URI parameters.  The display name 
177  *                  can be tokens, or a quoted string, if a larger 
178  *                  character set is desired.
179  * @param expires   Default expiration interval (in seconds) to be applied for
180  *                  contact URL that doesn't have expiration settings. If the
181  *                  value PJSIP_REGC_EXPIRATION_NOT_SPECIFIED is given, then 
182  *                  no default expiration will be applied.
183  * @return          zero on success.
184  */
185 PJ_DECL(pj_status_t) pjsip_regc_init(pjsip_regc *regc,
186                                      const pj_str_t *srv_url,
187                                      const pj_str_t *from_url,
188                                      const pj_str_t *to_url,
189                                      int ccnt,
190                                      const pj_str_t contact[],
191                                      pj_uint32_t expires);
192
193 /**
194  * Set the number of seconds to refresh the client registration before
195  * the registration expires.
196  *
197  * @param regc      The registration structure.
198  * @param delay     The number of seconds to refresh the client
199  *                  registration before the registration expires.
200  *
201  * @return          PJ_SUCCESS on success.
202  */
203 PJ_DECL(pj_status_t)
204 pjsip_regc_set_delay_before_refresh( pjsip_regc *regc,
205                                      pj_uint32_t delay );
206
207
208 /**
209  * Set authentication credentials to use by this registration.
210  *
211  * @param regc      The registration structure.
212  * @param count     Number of credentials in the array.
213  * @param cred      Array of credentials.
214  *
215  * @return          PJ_SUCCESS on success.
216  */
217 PJ_DECL(pj_status_t) pjsip_regc_set_credentials( pjsip_regc *regc,
218                                                  int count,
219                                                  const pjsip_cred_info cred[] );
220
221 /**
222  * Set authentication preference.
223  *
224  * @param regc      The registration structure.
225  * @param pref      Authentication preference.
226  *
227  * @return          PJ_SUCCESS on success.
228  */
229 PJ_DECL(pj_status_t) pjsip_regc_set_prefs( pjsip_regc *regc,
230                                            const pjsip_auth_clt_pref *pref);
231
232 /**
233  * Set route set to be used for outgoing requests.
234  *
235  * @param regc      The client registration structure.
236  * @param route_set List containing Route headers.
237  *
238  * @return          PJ_SUCCESS on success.
239  */
240 PJ_DECL(pj_status_t) pjsip_regc_set_route_set(pjsip_regc *regc,
241                                               const pjsip_route_hdr*route_set);
242
243
244 /**
245  * Lock/bind client registration to a specific transport/listener. 
246  * This is optional, as normally transport will be selected automatically
247  * based on the destination of requests upon resolver completion. 
248  * When the client registration is explicitly bound to the specific 
249  * transport/listener, all UAC transactions originated by the client
250  * registration will use the specified transport/listener when sending 
251  * outgoing requests.
252  *
253  * Note that this doesn't affect the Contact header set for this client
254  * registration. Application must manually update the Contact header if
255  * necessary, to adjust the address according to the transport being
256  * selected.
257  *
258  * @param regc      The client registration instance.
259  * @param sel       Transport selector containing the specification of
260  *                  transport or listener to be used by this session
261  *                  to send requests.
262  *
263  * @return          PJ_SUCCESS on success, or the appropriate error code.
264  */
265 PJ_DECL(pj_status_t) pjsip_regc_set_transport(pjsip_regc *regc,
266                                               const pjsip_tpselector *sel);
267
268 /**
269  * Release the reference to current transport being used by the regc, if any.
270  * The regc keeps the reference to the last transport being used in order
271  * to prevent it from being destroyed. In some situation however, such as
272  * when the transport is disconnected, it is necessary to instruct the
273  * regc to release this reference so that the transport can be destroyed.
274  * See https://trac.pjsip.org/repos/ticket/1481 for background info.
275  *
276  * @param regc      The client registration instance.
277  *
278  * @return          PJ_SUCCESS on success, or the appropriate error code.
279  */
280 PJ_DECL(pj_status_t) pjsip_regc_release_transport(pjsip_regc *regc);
281
282 /**
283  * Add headers to be added to outgoing REGISTER requests.
284  *
285  * @param regc      The client registration structure.
286  * @param hdr_list  List containing SIP headers to be added for all outgoing
287  *                  REGISTER requests.
288  *
289  * @return          PJ_SUCCESS on success.
290  */
291 PJ_DECL(pj_status_t) pjsip_regc_add_headers(pjsip_regc *regc,
292                                             const pjsip_hdr *hdr_list);
293
294
295 /**
296  * Create REGISTER request for the specified client registration structure.
297  *
298  * After successfull registration, application can inspect the contacts in
299  * the client registration structure to list what contacts are associaciated
300  * with the address of record being targeted in the registration.
301  *
302  * @param regc      The client registration structure.
303  * @param autoreg   If non zero, the library will automatically refresh the
304  *                  next registration until application unregister.
305  * @param p_tdata   Pointer to receive the REGISTER request.
306  *
307  * @return          PJ_SUCCESS on success.
308  */
309 PJ_DECL(pj_status_t) pjsip_regc_register(pjsip_regc *regc, pj_bool_t autoreg,
310                                          pjsip_tx_data **p_tdata);
311
312
313 /**
314  * Create REGISTER request to unregister the contacts that were previously
315  * registered by this client registration.
316  *
317  * @param regc      The client registration structure.
318  * @param p_tdata   Pointer to receive the REGISTER request.
319  *
320  * @return          PJ_SUCCESS on success.
321  */
322 PJ_DECL(pj_status_t) pjsip_regc_unregister(pjsip_regc *regc,
323                                            pjsip_tx_data **p_tdata);
324
325 /**
326  * Create REGISTER request to unregister all contacts from server records.
327  * Note that this will unregister all registered contact for the AOR
328  * including contacts registered by other user agents. To only unregister
329  * contact registered by this client registration instance, use
330  * #pjsip_regc_unregister() instead.
331  *
332  * @param regc      The client registration structure.
333  * @param p_tdata   Pointer to receive the REGISTER request.
334  *
335  * @return          PJ_SUCCESS on success.
336  */
337 PJ_DECL(pj_status_t) pjsip_regc_unregister_all(pjsip_regc *regc,
338                                                pjsip_tx_data **p_tdata);
339
340 /**
341  * Update Contact details in the client registration structure. For each
342  * contact, if the contact is not found in existing contact, it will be
343  * added to the Contact list. If it matches existing contact, nothing
344  * will be added. This function will also mark existing contacts which
345  * are not specified in the new contact list as to be removed, by adding
346  * "expires=0" parameter to these contacts.
347  *
348  * Once the contact list has been updated, application must update the
349  * registration by creating a new REGISTER request and send it to the
350  * registrar. This request will contain both old and new contacts; the
351  * old contacts will have it's expires parameter set to zero to instruct
352  * the registrar to remove the bindings.
353  *
354  * @param regc      The client registration structure.
355  * @param ccnt      Number of contacts.
356  * @param contact   Array of contacts, each contact item must be formatted
357  *                  as described in RFC 3261 Section 20.10:
358  *                  When the header field value contains a display 
359  *                  name, the URI including all URI parameters is 
360  *                  enclosed in "<" and ">".  If no "<" and ">" are 
361  *                  present, all parameters after the URI are header
362  *                  parameters, not URI parameters.  The display name 
363  *                  can be tokens, or a quoted string, if a larger 
364  *                  character set is desired.
365  * @return          PJ_SUCCESS if sucessfull.
366  */
367 PJ_DECL(pj_status_t) pjsip_regc_update_contact( pjsip_regc *regc,
368                                                 int ccnt,
369                                                 const pj_str_t contact[] );
370
371 /**
372  * Update the expires value. The next REGISTER request will contain
373  * new expires value for the registration.
374  *
375  * @param regc      The client registration structure.
376  * @param expires   The new expires value.
377  * @return          zero on successfull.
378  */
379 PJ_DECL(pj_status_t) pjsip_regc_update_expires( pjsip_regc *regc,
380                                                 pj_uint32_t expires );
381
382 /**
383  * Sends outgoing REGISTER request.
384  * The process will complete asynchronously, and application
385  * will be notified via the callback when the process completes.
386  *
387  * @param regc      The client registration structure.
388  * @param tdata     Transmit data.
389  *
390  * @return          PJ_SUCCESS on success.
391  */
392 PJ_DECL(pj_status_t) pjsip_regc_send(pjsip_regc *regc, pjsip_tx_data *tdata);
393
394
395 PJ_END_DECL
396
397 /**
398  * @}
399  */
400
401 #endif  /* __PJSIP_REG_H__ */