Benny Prijono | e0312a7 | 2005-11-18 00:16:43 +0000 | [diff] [blame] | 1 | /* $Id$ */
|
Benny Prijono | e722461 | 2005-11-13 19:40:44 +0000 | [diff] [blame] | 2 | /*
|
Benny Prijono | e0312a7 | 2005-11-18 00:16:43 +0000 | [diff] [blame] | 3 | * Copyright (C) 2003-2006 Benny Prijono <benny@prijono.org>
|
Benny Prijono | e722461 | 2005-11-13 19:40:44 +0000 | [diff] [blame] | 4 | *
|
Benny Prijono | e0312a7 | 2005-11-18 00:16:43 +0000 | [diff] [blame] | 5 | * This program is free software; you can redistribute it and/or modify
|
| 6 | * it under the terms of the GNU General Public License as published by
|
| 7 | * the Free Software Foundation; either version 2 of the License, or
|
| 8 | * (at your option) any later version.
|
Benny Prijono | e722461 | 2005-11-13 19:40:44 +0000 | [diff] [blame] | 9 | *
|
Benny Prijono | e0312a7 | 2005-11-18 00:16:43 +0000 | [diff] [blame] | 10 | * This program is distributed in the hope that it will be useful,
|
Benny Prijono | e722461 | 2005-11-13 19:40:44 +0000 | [diff] [blame] | 11 | * but WITHOUT ANY WARRANTY; without even the implied warranty of
|
Benny Prijono | e0312a7 | 2005-11-18 00:16:43 +0000 | [diff] [blame] | 12 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
| 13 | * GNU General Public License for more details.
|
Benny Prijono | e722461 | 2005-11-13 19:40:44 +0000 | [diff] [blame] | 14 | *
|
Benny Prijono | e0312a7 | 2005-11-18 00:16:43 +0000 | [diff] [blame] | 15 | * You should have received a copy of the GNU General Public License
|
| 16 | * along with this program; if not, write to the Free Software
|
| 17 | * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
|
Benny Prijono | e722461 | 2005-11-13 19:40:44 +0000 | [diff] [blame] | 18 | */
|
| 19 | #ifndef __PJSIP_SIP_REG_H__
|
| 20 | #define __PJSIP_SIP_REG_H__
|
| 21 |
|
| 22 | /**
|
| 23 | * @file sip_reg.h
|
| 24 | * @brief SIP Registration Client
|
| 25 | */
|
| 26 |
|
| 27 | #include <pjsip/sip_types.h>
|
| 28 | #include <pjsip/sip_auth.h>
|
| 29 | #include <pjsip_mod_ua/sip_ua.h>
|
| 30 |
|
| 31 | PJ_BEGIN_DECL
|
| 32 |
|
| 33 | /**
|
| 34 | * @defgroup PJSUA_REGC SIP Registration Client
|
| 35 | * @ingroup PJSUA
|
| 36 | * @{
|
| 37 | * \brief
|
| 38 | * API for performing registration for user agent.
|
| 39 | */
|
| 40 |
|
| 41 | /** Typedef for client registration data. */
|
| 42 | typedef struct pjsip_regc pjsip_regc;
|
| 43 |
|
| 44 | /** Maximum contacts in registration. */
|
| 45 | #define PJSIP_REGC_MAX_CONTACT 10
|
| 46 |
|
| 47 | /** Expiration not specified. */
|
| 48 | #define PJSIP_REGC_EXPIRATION_NOT_SPECIFIED ((pj_uint32_t)0xFFFFFFFFUL)
|
| 49 |
|
| 50 | /** Buffer to hold all contacts. */
|
| 51 | #define PJSIP_REGC_CONTACT_BUF_SIZE 512
|
| 52 |
|
| 53 | /** Structure to hold parameters when calling application's callback.
|
| 54 | * The application's callback is called when the client registration process
|
| 55 | * has finished.
|
| 56 | */
|
| 57 | struct pjsip_regc_cbparam
|
| 58 | {
|
| 59 | pjsip_regc *regc;
|
| 60 | void *token;
|
| 61 | int code;
|
| 62 | pj_str_t reason;
|
| 63 | pjsip_rx_data *rdata;
|
| 64 | int contact_cnt;
|
| 65 | int expiration;
|
| 66 | pjsip_contact_hdr *contact[PJSIP_REGC_MAX_CONTACT];
|
| 67 | };
|
| 68 |
|
| 69 |
|
| 70 | /** Type declaration for callback to receive registration result. */
|
| 71 | typedef void pjsip_regc_cb(struct pjsip_regc_cbparam *param);
|
| 72 |
|
| 73 |
|
| 74 | /**
|
| 75 | * Get the module instance for client registration module.
|
| 76 | *
|
| 77 | * @return client registration module.
|
| 78 | */
|
| 79 | PJ_DECL(pjsip_module*) pjsip_regc_get_module(void);
|
| 80 |
|
| 81 |
|
| 82 | /**
|
| 83 | * Create client registration structure.
|
| 84 | *
|
| 85 | * @param endpt Endpoint, used to allocate pool from.
|
| 86 | * @param token A data to be associated with the client registration struct.
|
| 87 | * @param cb Pointer to callback function to receive registration status.
|
| 88 | *
|
| 89 | * @return client registration structure.
|
| 90 | */
|
| 91 | PJ_DECL(pjsip_regc*) pjsip_regc_create( pjsip_endpoint *endpt, void *token,
|
| 92 | pjsip_regc_cb *cb);
|
| 93 |
|
| 94 |
|
| 95 | /**
|
| 96 | * Destroy client registration structure. If a registration transaction is
|
| 97 | * in progress, then the structure will be deleted only after a final response
|
| 98 | * has been received, and in this case, the callback won't be called.
|
| 99 | *
|
| 100 | * @param regc The client registration structure.
|
| 101 | */
|
| 102 | PJ_DECL(void) pjsip_regc_destroy(pjsip_regc *regc);
|
| 103 |
|
| 104 | /**
|
| 105 | * Get the memory pool associated with a registration client handle.
|
| 106 | *
|
| 107 | * @param regc The client registration structure.
|
| 108 | * @return pool handle.
|
| 109 | */
|
| 110 | PJ_DECL(pj_pool_t*) pjsip_regc_get_pool(pjsip_regc *regc);
|
| 111 |
|
| 112 | /**
|
| 113 | * Initialize client registration structure with various information needed to
|
| 114 | * perform the registration.
|
| 115 | *
|
| 116 | * @param regc The client registration structure.
|
| 117 | * @param from_url The person performing the registration, must be a SIP URL type.
|
| 118 | * @param to_url The address of record for which the registration is targetd, must
|
| 119 | * be a SIP/SIPS URL.
|
| 120 | * @param ccnt Number of contacts in the array.
|
| 121 | * @param contact Array of contacts.
|
| 122 | * @param expires Default expiration interval (in seconds) to be applied for
|
| 123 | * contact URL that doesn't have expiration settings. If the
|
| 124 | * value PJSIP_REGC_EXPIRATION_NOT_SPECIFIED is given, then
|
| 125 | * no default expiration will be applied.
|
| 126 | * @return zero on success.
|
| 127 | */
|
| 128 | PJ_DECL(pj_status_t) pjsip_regc_init(pjsip_regc *regc,
|
| 129 | const pj_str_t *srv_url,
|
| 130 | const pj_str_t *from_url,
|
| 131 | const pj_str_t *to_url,
|
| 132 | int ccnt,
|
| 133 | const pj_str_t contact[],
|
| 134 | pj_uint32_t expires);
|
| 135 |
|
| 136 |
|
| 137 | /**
|
| 138 | * Set authentication credentials to use by this registration.
|
| 139 | *
|
| 140 | * @param dlg The registration structure.
|
| 141 | * @param count Number of credentials in the array.
|
| 142 | * @param cred Array of credentials.
|
| 143 | *
|
| 144 | * @return Zero on success.
|
| 145 | */
|
| 146 | PJ_DECL(pj_status_t) pjsip_regc_set_credentials( pjsip_regc *regc,
|
| 147 | int count,
|
| 148 | const pjsip_cred_info cred[] );
|
| 149 |
|
| 150 | /**
|
| 151 | * Create REGISTER request for the specified client registration structure.
|
| 152 | *
|
| 153 | * After successfull registration, application can inspect the contacts in
|
| 154 | * the client registration structure to list what contacts are associaciated
|
| 155 | * with the address of record being targeted in the registration.
|
| 156 | *
|
| 157 | * @param regc The client registration structure.
|
| 158 | * @param autoreg If non zero, the library will automatically refresh the
|
| 159 | * next registration until application unregister.
|
| 160 | *
|
| 161 | * @return SIP REGISTER request.
|
| 162 | */
|
| 163 | PJ_DECL(pjsip_tx_data*) pjsip_regc_register(pjsip_regc *regc, pj_bool_t autoreg);
|
| 164 |
|
| 165 |
|
| 166 | /**
|
| 167 | * Create REGISTER request to unregister all contacts from server records.
|
| 168 | *
|
| 169 | * @param regc The client registration structure.
|
| 170 | *
|
| 171 | * @return SIP REGISTER request.
|
| 172 | */
|
| 173 | PJ_DECL(pjsip_tx_data*) pjsip_regc_unregister(pjsip_regc *regc);
|
| 174 |
|
| 175 | /**
|
| 176 | * Update Contact details in the client registration structure.
|
| 177 | *
|
| 178 | * @param regc The client registration structure.
|
| 179 | * @param ccnt Number of contacts.
|
| 180 | * @param contact Array of contacts.
|
| 181 | * @return zero if sucessfull.
|
| 182 | */
|
| 183 | PJ_DECL(pj_status_t) pjsip_regc_update_contact( pjsip_regc *regc,
|
| 184 | int ccnt,
|
| 185 | const pj_str_t contact[] );
|
| 186 |
|
| 187 | /**
|
| 188 | * Update the expires value.
|
| 189 | *
|
| 190 | * @param regc The client registration structure.
|
| 191 | * @param expires The new expires value.
|
| 192 | * @return zero on successfull.
|
| 193 | */
|
| 194 | PJ_DECL(pj_status_t) pjsip_regc_update_expires( pjsip_regc *regc,
|
| 195 | pj_uint32_t expires );
|
| 196 |
|
| 197 | /**
|
| 198 | * Sends outgoing REGISTER request.
|
| 199 | * The process will complete asynchronously, and application
|
| 200 | * will be notified via the callback when the process completes.
|
| 201 | *
|
| 202 | * @param regc The client registration structure.
|
| 203 | * @param tdata Transmit data.
|
| 204 | */
|
| 205 | PJ_DECL(void) pjsip_regc_send(pjsip_regc *regc, pjsip_tx_data *tdata);
|
| 206 |
|
| 207 |
|
| 208 | PJ_END_DECL
|
| 209 |
|
| 210 | #endif /* __PJSIP_REG_H__ */
|