factory.h 12.1 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22
/*
linphone
Copyright (C) 2016 Belledonne Communications <info@belledonne-communications.com>

This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
*/

#ifndef LINPHONE_FACTORY_H
#define LINPHONE_FACTORY_H

23
#include "linphone/types.h"
24

25
#ifdef __cplusplus
26 27 28 29 30 31 32 33 34 35 36 37 38 39 40
extern "C" {
#endif

/**
 * @addtogroup initializing
 * @{
 */

/**
 * Create the #LinphoneFactory if that has not been done and return
 * a pointer on it.
 * @return A pointer on the #LinphoneFactory
 */
LINPHONE_PUBLIC LinphoneFactory *linphone_factory_get(void);

Simon Morlat's avatar
Simon Morlat committed
41 42 43 44 45 46
/**
 * Clean the factory. This function is generally useless as the factory is unique per process, however
 * calling this function at the end avoid getting reports from belle-sip leak detector about memory leaked in linphone_factory_get().
 */
LINPHONE_PUBLIC void linphone_factory_clean(void);

47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84
/**
 * Instanciate a #LinphoneCore object.
 *
 * The LinphoneCore object is the primary handle for doing all phone actions.
 * It should be unique within your application.
 * @param factory The #LinphoneFactory singleton.
 * @param cbs a #LinphoneCoreCbs object holding your application callbacks. A reference
 * will be taken on it until the destruciton of the core or the unregistration
 * with linphone_core_remove_cbs().
 * @param config_path a path to a config file. If it does not exists it will be created.
 *        The config file is used to store all settings, call logs, friends, proxies... so that all these settings
 *	       become persistent over the life of the LinphoneCore object.
 *	       It is allowed to set a NULL config file. In that case LinphoneCore will not store any settings.
 * @param factory_config_path a path to a read-only config file that can be used to
 *        to store hard-coded preference such as proxy settings or internal preferences.
 *        The settings in this factory file always override the one in the normal config file.
 *        It is OPTIONAL, use NULL if unneeded.
 * @see linphone_core_new_with_config
 */
LINPHONE_PUBLIC LinphoneCore *linphone_factory_create_core(const LinphoneFactory *factory, LinphoneCoreCbs *cbs,
						const char *config_path, const char *factory_config_path);

/**
 * Instantiates a LinphoneCore object with a given LpConfig.
 *
 * @param factory The #LinphoneFactory singleton.
 * The LinphoneCore object is the primary handle for doing all phone actions.
 * It should be unique within your application.
 * @param cbs a #LinphoneCoreCbs object holding your application callbacks. A reference
 * will be taken on it until the destruciton of the core or the unregistration
 * with linphone_core_remove_cbs().
 * @param config a pointer to an LpConfig object holding the configuration of the LinphoneCore to be instantiated.
 * @see linphone_core_new
 */
LINPHONE_PUBLIC LinphoneCore *linphone_factory_create_core_with_config(const LinphoneFactory *factory, LinphoneCoreCbs *cbs, LinphoneConfig *config);

/**
 * Instanciate a #LinphoneCoreCbs object.
85
 * @return a new #LinphoneCoreCbs.
86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113
 */
LINPHONE_PUBLIC LinphoneCoreCbs *linphone_factory_create_core_cbs(const LinphoneFactory *factory);

/**
 * Parse a string holding a SIP URI and create the according #LinphoneAddress object.
 * @param factory The #LinphoneFactory singleton.
 * @param addr A string holding the SIP URI to parse.
 * @return A new #LinphoneAddress.
 */
LINPHONE_PUBLIC LinphoneAddress *linphone_factory_create_address(const LinphoneFactory *factory, const char *addr);

/**
 * Creates a #LinphoneAuthInfo object.
 * The object can be created empty, that is with all arguments set to NULL.
 * Username, userid, password, realm and domain can be set later using specific methods.
 * At the end, username and passwd (or ha1) are required.
 * @param factory The #LinphoneFactory singleton.
 * @param username The username that needs to be authenticated
 * @param userid The userid used for authenticating (use NULL if you don't know what it is)
 * @param passwd The password in clear text
 * @param ha1 The ha1-encrypted password if password is not given in clear text.
 * @param realm The authentication domain (which can be larger than the sip domain. Unfortunately many SIP servers don't use this parameter.
 * @param domain The SIP domain for which this authentication information is valid, if it has to be restricted for a single SIP domain.
 * @return A #LinphoneAuthInfo object. linphone_auth_info_destroy() must be used to destroy it when no longer needed. The LinphoneCore makes a copy of LinphoneAuthInfo
 * passed through linphone_core_add_auth_info().
 */
LINPHONE_PUBLIC LinphoneAuthInfo *linphone_factory_create_auth_info(const LinphoneFactory *factory, const char *username, const char *userid, const char *passwd, const char *ha1, const char *realm, const char *domain);

114 115 116 117 118 119 120
/**
 * Create a LinphoneCallCbs object that holds callbacks for events happening on a call.
 * @param[in] factory LinphoneFactory singletion object
 * @return A new LinphoneCallCbs object
 */
LINPHONE_PUBLIC LinphoneCallCbs * linphone_factory_create_call_cbs(const LinphoneFactory *factory);

121 122 123 124 125 126 127
/**
 * Create an empty #LinphoneVcard.
 * @return a new #LinphoneVcard.
 * @ingroup initializing
 */
LINPHONE_PUBLIC LinphoneVcard *linphone_factory_create_vcard(LinphoneFactory *factory);

128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151
/**
 * Create a LinphoneVideoDefinition from a given width and height
 * @param[in] factory LinphoneFactory singleton object
 * @param[in] width The width of the created video definition
 * @param[in] height The height of the created video definition
 * @return A new LinphoneVideoDefinition object
 */
LINPHONE_PUBLIC LinphoneVideoDefinition * linphone_factory_create_video_definition(const LinphoneFactory *factory, unsigned int width, unsigned int height);

/**
 * Create a LinphoneVideoDefinition from a given standard definition name
 * @param[in] factory LinphoneFactory singleton object
 * @param[in] name The standard definition name of the video definition to create
 * @return A new LinphoneVideoDefinition object
 */
LINPHONE_PUBLIC LinphoneVideoDefinition * linphone_factory_create_video_definition_from_name(const LinphoneFactory *factory, const char *name);

/**
 * Get the list of standard video definitions supported by Linphone.
 * @param[in] factory LinphoneFactory singleton object
 * @return \bctbx_list{LinphoneVideoDefinition}
 */
LINPHONE_PUBLIC const bctbx_list_t * linphone_factory_get_supported_video_definitions(const LinphoneFactory *factory);

152 153 154 155 156
/**
 * Get the top directory where the resources are located.
 * @param[in] factory LinphoneFactory object
 * @return The path to the top directory where the resources are located
 */
Simon Morlat's avatar
Simon Morlat committed
157
LINPHONE_PUBLIC const char * linphone_factory_get_top_resources_dir(const LinphoneFactory *factory);
158 159 160 161 162 163 164 165 166 167 168 169 170 171

/**
 * Set the top directory where the resources are located.
 * If you only define this top directory, the other resources directory will automatically be derived form this one.
 * @param[in] factory LinphoneFactory object
 * @param[in] path The path to the top directory where the resources are located
 */
LINPHONE_PUBLIC void linphone_factory_set_top_resources_dir(LinphoneFactory *factory, const char *path);

/**
 * Get the directory where the data resources are located.
 * @param[in] factory LinphoneFactory object
 * @return The path to the directory where the data resources are located
 */
Simon Morlat's avatar
Simon Morlat committed
172
LINPHONE_PUBLIC const char * linphone_factory_get_data_resources_dir(LinphoneFactory *factory);
173 174 175 176 177 178 179 180 181 182 183 184 185

/**
 * Set the directory where the data resources are located.
 * @param[in] factory LinphoneFactory object
 * @param[in] path The path where the data resources are located
 */
LINPHONE_PUBLIC void linphone_factory_set_data_resources_dir(LinphoneFactory *factory, const char *path);

/**
 * Get the directory where the sound resources are located.
 * @param[in] factory LinphoneFactory object
 * @return The path to the directory where the sound resources are located
 */
Simon Morlat's avatar
Simon Morlat committed
186
LINPHONE_PUBLIC const char * linphone_factory_get_sound_resources_dir(LinphoneFactory *factory);
187 188 189 190 191 192 193 194 195 196 197 198 199

/**
 * Set the directory where the sound resources are located.
 * @param[in] factory LinphoneFactory object
 * @param[in] path The path where the sound resources are located
 */
LINPHONE_PUBLIC void linphone_factory_set_sound_resources_dir(LinphoneFactory *factory, const char *path);

/**
 * Get the directory where the ring resources are located.
 * @param[in] factory LinphoneFactory object
 * @return The path to the directory where the ring resources are located
 */
Simon Morlat's avatar
Simon Morlat committed
200
LINPHONE_PUBLIC const char * linphone_factory_get_ring_resources_dir(LinphoneFactory *factory);
201 202 203 204 205 206 207 208 209 210 211 212 213

/**
 * Set the directory where the ring resources are located.
 * @param[in] factory LinphoneFactory object
 * @param[in] path The path where the ring resources are located
 */
LINPHONE_PUBLIC void linphone_factory_set_ring_resources_dir(LinphoneFactory *factory, const char *path);

/**
 * Get the directory where the image resources are located.
 * @param[in] factory LinphoneFactory object
 * @return The path to the directory where the image resources are located
 */
Simon Morlat's avatar
Simon Morlat committed
214
LINPHONE_PUBLIC const char * linphone_factory_get_image_resources_dir(LinphoneFactory *factory);
215 216 217 218 219 220 221 222 223 224 225 226 227

/**
 * Set the directory where the image resources are located.
 * @param[in] factory LinphoneFactory object
 * @param[in] path The path where the image resources are located
 */
LINPHONE_PUBLIC void linphone_factory_set_image_resources_dir(LinphoneFactory *factory, const char *path);

/**
 * Get the directory where the mediastreamer2 plugins are located.
 * @param[in] factory LinphoneFactory object
 * @return The path to the directory where the mediastreamer2 plugins are located, or NULL if it has not been set
 */
Simon Morlat's avatar
Simon Morlat committed
228
LINPHONE_PUBLIC const char * linphone_factory_get_msplugins_dir(LinphoneFactory *factory);
229 230 231 232 233 234 235 236

/**
 * Set the directory where the mediastreamer2 plugins are located.
 * @param[in] factory LinphoneFactory object
 * @param[in] path The path to the directory where the mediastreamer2 plugins are located
 */
LINPHONE_PUBLIC void linphone_factory_set_msplugins_dir(LinphoneFactory *factory, const char *path);

237 238
/**
 * Creates an object LinphoneErrorInfo.
239
 * @param[in] factory LinphoneFactory object
240 241
 * @return  LinphoneErrorInfo object.
 */
242
LINPHONE_PUBLIC  LinphoneErrorInfo *linphone_factory_create_error_info(LinphoneFactory *factory);
243 244 245 246 247 248 249

/**
 * Creates an object LinphoneRange.
 * @param[in] factory LinphoneFactory object
 * @return  LinphoneRange object.
 */
LINPHONE_PUBLIC LinphoneRange *linphone_factory_create_range(LinphoneFactory *factory);
250 251 252 253 254 255 256 257 258 259 260 261 262 263

/**
 * Creates an object LinphoneTransports.
 * @param[in] factory LinphoneFactory object
 * @return  LinphoneTransports object.
 */
LINPHONE_PUBLIC LinphoneTransports *linphone_factory_create_transports(LinphoneFactory *factory);

/**
 * Creates an object LinphoneVideoActivationPolicy.
 * @param[in] factory LinphoneFactory object
 * @return  LinphoneVideoActivationPolicy object.
 */
LINPHONE_PUBLIC LinphoneVideoActivationPolicy *linphone_factory_create_video_activation_policy(LinphoneFactory *factory);
264 265 266 267 268 269 270 271 272 273 274 275 276 277 278

/**
 * Gets the user data in the LinphoneFactory object
 * @param[in] factory the LinphoneFactory
 * @return the user data
*/
LINPHONE_PUBLIC void *linphone_factory_get_user_data(const LinphoneFactory *factory);

/**
 * Sets the user data in the LinphoneFactory object
 * @param[in] factory the LinphoneFactory object
 * @param[in] data the user data
*/
LINPHONE_PUBLIC void linphone_factory_set_user_data(LinphoneFactory *factory, void *data);

279 280 281 282 283 284 285
/***
 * Returns a bctbx_list_t of all DialPlans
 * @param[in] factory the LinphoneFactory object
 * @return \bctbx_list{DialPlan} a list of DialPlan
 */
LINPHONE_PUBLIC const bctbx_list_t * linphone_factory_get_dial_plans(LinphoneFactory *factory);

286 287 288 289
/**
 * @}
 */

290
#ifdef __cplusplus
291 292 293 294 295
}
#endif


#endif // LINPHONE_FACTORY_H