liblinphone  3.6.1
Typedefs | Enumerations | Functions
Managing proxies

Typedefs

typedef struct _LinphoneProxyConfig LinphoneProxyConfig
 
typedef enum
_LinphoneRegistrationState 
LinphoneRegistrationState
 

Enumerations

enum  _LinphoneRegistrationState {
  LinphoneRegistrationNone,
  LinphoneRegistrationProgress,
  LinphoneRegistrationOk,
  LinphoneRegistrationCleared,
  LinphoneRegistrationFailed
}
 

Functions

int linphone_core_set_primary_contact (LinphoneCore *lc, const char *contact)
 
const char * linphone_core_get_primary_contact (LinphoneCore *lc)
 
void linphone_core_set_guess_hostname (LinphoneCore *lc, bool_t val)
 
bool_t linphone_core_get_guess_hostname (LinphoneCore *lc)
 
LinphoneAddresslinphone_core_get_primary_contact_parsed (LinphoneCore *lc)
 
const char * linphone_core_get_identity (LinphoneCore *lc)
 
const char * linphone_registration_state_to_string (LinphoneRegistrationState cs)
 
LinphoneProxyConfiglinphone_proxy_config_new (void)
 
int linphone_proxy_config_set_server_addr (LinphoneProxyConfig *obj, const char *server_addr)
 
int linphone_proxy_config_set_identity (LinphoneProxyConfig *obj, const char *identity)
 
int linphone_proxy_config_set_route (LinphoneProxyConfig *obj, const char *route)
 
void linphone_proxy_config_expires (LinphoneProxyConfig *obj, int expires)
 
void linphone_proxy_config_enable_register (LinphoneProxyConfig *obj, bool_t val)
 
void linphone_proxy_config_edit (LinphoneProxyConfig *obj)
 
int linphone_proxy_config_done (LinphoneProxyConfig *obj)
 
void linphone_proxy_config_enable_publish (LinphoneProxyConfig *obj, bool_t val)
 
void linphone_proxy_config_set_dial_escape_plus (LinphoneProxyConfig *cfg, bool_t val)
 
void linphone_proxy_config_set_dial_prefix (LinphoneProxyConfig *cfg, const char *prefix)
 
bool_t linphone_proxy_config_is_registered (const LinphoneProxyConfig *obj)
 
const char * linphone_proxy_config_get_route (const LinphoneProxyConfig *obj)
 
const char * linphone_proxy_config_get_identity (const LinphoneProxyConfig *obj)
 
bool_t linphone_proxy_config_publish_enabled (const LinphoneProxyConfig *obj)
 
const char * linphone_proxy_config_get_addr (const LinphoneProxyConfig *obj)
 
int linphone_proxy_config_get_expires (const LinphoneProxyConfig *obj)
 
bool_t linphone_proxy_config_register_enabled (const LinphoneProxyConfig *obj)
 
void linphone_proxy_config_refresh_register (LinphoneProxyConfig *obj)
 
const char * linphone_proxy_config_get_contact_parameters (const LinphoneProxyConfig *obj)
 
void linphone_proxy_config_set_contact_parameters (LinphoneProxyConfig *obj, const char *contact_params)
 
bool_t linphone_proxy_config_get_dial_escape_plus (const LinphoneProxyConfig *cfg)
 
const char * linphone_proxy_config_get_dial_prefix (const LinphoneProxyConfig *cfg)
 
void linphone_proxy_config_destroy (LinphoneProxyConfig *cfg)
 
int linphone_proxy_config_normalize_number (LinphoneProxyConfig *proxy, const char *username, char *result, size_t result_len)
 
void linphone_core_refresh_registers (LinphoneCore *lc)
 
LinphoneProxyConfiglinphone_core_create_proxy_config (LinphoneCore *lc)
 
int linphone_dial_plan_lookup_ccc_from_e164 (const char *e164)
 
int linphone_dial_plan_lookup_ccc_from_iso (const char *iso)
 
int linphone_core_add_proxy_config (LinphoneCore *lc, LinphoneProxyConfig *cfg)
 
void linphone_core_remove_proxy_config (LinphoneCore *lc, LinphoneProxyConfig *cfg)
 
void linphone_core_clear_proxy_config (LinphoneCore *lc)
 
void linphone_core_set_default_proxy (LinphoneCore *lc, LinphoneProxyConfig *config)
 
int linphone_core_get_default_proxy (LinphoneCore *lc, LinphoneProxyConfig **config)
 
const MSList * linphone_core_get_proxy_config_list (const LinphoneCore *lc)
 

Detailed Description

User registration is controled by LinphoneProxyConfig settings.
Each LinphoneProxyConfig object can be configured with registration informations like proxy address , user id , refresh period , and so on.
A created proxy config using linphone_proxy_config_new(), once configured, must be added to LinphoneCore using function linphone_core_add_proxy_config().
It is recommended to set a default proxy config using function linphone_core_set_default_proxy(). Once done, if a proxy config has been configured with attribute enable register , next call to linphone_core_iterate() triggers a SIP register.
Registration status is reported by LinphoneRegistrationStateCb.

This pseudo code demonstrates basic registration operations:

/*create proxy config*/
/*parse identity*/
LinphoneAddress *from = linphone_address_new("sip:toto@sip.titi.com");
if (password!=NULL){
info=linphone_auth_info_new(linphone_address_get_username(from),NULL,"secret",NULL,NULL); /*create authentication structure from identity*/
linphone_core_add_auth_info(lc,info); /*add authentication info to LinphoneCore*/
}
// configure proxy entries
linphone_proxy_config_set_identity(proxy_cfg,identity); /*set identity with user name and domain*/
const char* server_addr = linphone_address_get_domain(from); /*extract domain address from identity*/
linphone_proxy_config_set_server_addr(proxy_cfg,server_addr); /* we assume domain = proxy server address*/
linphone_proxy_config_enable_register(proxy_cfg,TRUE); /*activate registration for this proxy config*/
linphone_address_destroy(from); /*release resource*/
linphone_core_add_proxy_config(lc,proxy_cfg); /*add proxy config to linphone core*/
linphone_core_set_default_proxy(lc,proxy_cfg); /*set to default proxy*/


Registration sate call back:

static void registration_state_changed(struct _LinphoneCore *lc, LinphoneProxyConfig *cfg, LinphoneRegistrationState cstate, const char *message){
printf("New registration state %s for user id [%s] at proxy [%s]\n"
}


Authentication:
Most of the time, registration requires authentication to succed. LinphoneAuthInfo info must be either added to LinphoneCore using function linphone_core_add_auth_info() before LinphoneProxyConfig is added to Linphone core, or on demand from call back AuthInfoRequested .

Unregistration:
Unregistration or any changes to LinphoneProxyConfig must be first started by a call to function linphone_proxy_config_edit() and validated by function linphone_proxy_config_done()
This pseudo code shows how to unregister a user associated to a LinphoneProxyConfig

linphone_core_get_default_proxy(lc,&proxy_cfg); /* get default proxy config*/
linphone_proxy_config_edit(proxy_cfg); /*start editing proxy configuration*/
linphone_proxy_config_enable_register(proxy_cfg,FALSE); /*de-activate registration for this proxy config*/
linphone_proxy_config_done(proxy_cfg); /*initiate REGISTER with expire = 0*/


A complete tutorial can be found at : Registration tutorial

Typedef Documentation

typedef struct _LinphoneProxyConfig LinphoneProxyConfig

The LinphoneProxyConfig object represents a proxy configuration to be used by the LinphoneCore object. Its fields must not be used directly in favour of the accessors methods. Once created and filled properly the LinphoneProxyConfig can be given to LinphoneCore with linphone_core_add_proxy_config(). This will automatically triggers the registration, if enabled.

The proxy configuration are persistent to restarts because they are saved in the configuration file. As a consequence, after linphone_core_new() there might already be a list of configured proxy that can be examined with linphone_core_get_proxy_config_list().

The default proxy (see linphone_core_set_default_proxy() ) is the one of the list that is used by default for calls.

LinphoneRegistrationState describes proxy registration states.

Enumeration Type Documentation

LinphoneRegistrationState describes proxy registration states.

Enumerator
LinphoneRegistrationNone 

Initial state for registrations

LinphoneRegistrationProgress 

Registration is in progress

LinphoneRegistrationOk 

Registration is successful

LinphoneRegistrationCleared 

Unregistration succeeded

LinphoneRegistrationFailed 

Registration failed

Function Documentation

int linphone_core_set_primary_contact ( LinphoneCore lc,
const char *  contact 
)

Sets the local "from" identity.

This data is used in absence of any proxy configuration or when no default proxy configuration is set. See LinphoneProxyConfig

const char* linphone_core_get_primary_contact ( LinphoneCore lc)

Returns the default identity when no proxy configuration is used.

void linphone_core_set_guess_hostname ( LinphoneCore lc,
bool_t  val 
)

Tells LinphoneCore to guess local hostname automatically in primary contact.

bool_t linphone_core_get_guess_hostname ( LinphoneCore lc)

Returns TRUE if hostname part of primary contact is guessed automatically.

LinphoneAddress* linphone_core_get_primary_contact_parsed ( LinphoneCore lc)

Same as linphone_core_get_primary_contact() but the result is a LinphoneAddress object instead of const char*

const char * linphone_core_get_identity ( LinphoneCore lc)

Returns the default identity SIP address.

This is an helper function:

If no default proxy is set, this will return the primary contact ( see linphone_core_get_primary_contact() ). If a default proxy is set it returns the registered identity on the proxy.

const char* linphone_registration_state_to_string ( LinphoneRegistrationState  cs)

Human readable version of the LinphoneRegistrationState

Parameters
cssate
LinphoneProxyConfig * linphone_proxy_config_new ( )
Deprecated:
, use linphone_core_create_proxy_config instead Creates an empty proxy config.
int linphone_proxy_config_set_server_addr ( LinphoneProxyConfig obj,
const char *  server_addr 
)

Sets the proxy address

Examples of valid sip proxy address are:

  • IP address: sip:87.98.157.38
  • IP address with port: sip:87.98.157.38:5062
  • hostnames : sip:sip.example.net
int linphone_proxy_config_set_identity ( LinphoneProxyConfig obj,
const char *  identity 
)

Sets the user identity as a SIP address.

This identity is normally formed with display name, username and domain, such as: Alice <sip:alice.nosp@m.@exa.nosp@m.mple..nosp@m.net> The REGISTER messages will have from and to set to this identity.

int linphone_proxy_config_set_route ( LinphoneProxyConfig obj,
const char *  route 
)

Sets a SIP route. When a route is set, all outgoing calls will go to the route's destination if this proxy is the default one (see linphone_core_set_default_proxy() ).

void linphone_proxy_config_expires ( LinphoneProxyConfig obj,
int  val 
)

Sets the registration expiration time in seconds.

void linphone_proxy_config_enable_register ( LinphoneProxyConfig obj,
bool_t  val 
)

Indicates either or not, REGISTRATION must be issued for this LinphoneProxyConfig .
In case this LinphoneProxyConfig has been added to LinphoneCore, follows the linphone_proxy_config_edit() rule.

Parameters
objobject pointer
valif true, registration will be engaged

Indicates whether a REGISTER request must be sent to the proxy.

void linphone_proxy_config_edit ( LinphoneProxyConfig obj)

Starts editing a proxy configuration.

Because proxy configuration must be consistent, applications MUST call linphone_proxy_config_edit() before doing any attempts to modify proxy configuration (such as identity, proxy address and so on). Once the modifications are done, then the application must call linphone_proxy_config_done() to commit the changes.

int linphone_proxy_config_done ( LinphoneProxyConfig obj)

Commits modification made to the proxy configuration.

void linphone_proxy_config_enable_publish ( LinphoneProxyConfig obj,
bool_t  val 
)

Indicates either or not, PUBLISH must be issued for this LinphoneProxyConfig .
In case this LinphoneProxyConfig has been added to LinphoneCore, follows the linphone_proxy_config_edit() rule.

Parameters
objobject pointer
valif true, publish will be engaged
void linphone_proxy_config_set_dial_escape_plus ( LinphoneProxyConfig cfg,
bool_t  val 
)

Sets whether liblinphone should replace "+" by international calling prefix in dialed numbers (passed to linphone_core_invite ).

void linphone_proxy_config_set_dial_prefix ( LinphoneProxyConfig cfg,
const char *  prefix 
)

Sets a dialing prefix to be automatically prepended when inviting a number with linphone_core_invite(); This dialing prefix shall usually be the country code of the country where the user is living.

bool_t linphone_proxy_config_is_registered ( const LinphoneProxyConfig obj)

Returns a boolean indicating that the user is sucessfully registered on the proxy.

const char * linphone_proxy_config_get_route ( const LinphoneProxyConfig obj)

Returns the route set for this proxy configuration.

const char * linphone_proxy_config_get_identity ( const LinphoneProxyConfig obj)

Returns the SIP identity that belongs to this proxy configuration.

The SIP identity is a SIP address (Display Name <sip:username@domain> )

bool_t linphone_proxy_config_publish_enabled ( const LinphoneProxyConfig obj)

Returns TRUE if PUBLISH request is enabled for this proxy.

const char * linphone_proxy_config_get_addr ( const LinphoneProxyConfig obj)

Returns the proxy's SIP address.

int linphone_proxy_config_get_expires ( const LinphoneProxyConfig obj)

Returns the duration of registration.

bool_t linphone_proxy_config_register_enabled ( const LinphoneProxyConfig obj)

Returns TRUE if registration to the proxy is enabled.

void linphone_proxy_config_refresh_register ( LinphoneProxyConfig obj)

Refresh a proxy registration. This is useful if for example you resuming from suspend, thus IP address may have changed.

const char * linphone_proxy_config_get_contact_parameters ( const LinphoneProxyConfig obj)

Returns previously set contact parameters.

void linphone_proxy_config_set_contact_parameters ( LinphoneProxyConfig obj,
const char *  contact_params 
)

Set optional contact parameters that will be added to the contact information sent in the registration.

Parameters
objthe proxy config object
contact_paramsa string contaning the additional parameters in text form, like "myparam=something;myparam2=something_else"

The main use case for this function is provide the proxy additional information regarding the user agent, like for example unique identifier or apple push id. As an example, the contact address in the SIP register sent will look like <sip:joe@1.nosp@m.5.12.nosp@m.8.128.nosp@m..93:50421;apple-push-id=43143-DFE23F-2323-FA2232>.

bool_t linphone_proxy_config_get_dial_escape_plus ( const LinphoneProxyConfig cfg)

Returns whether liblinphone should replace "+" by "00" in dialed numbers (passed to linphone_core_invite ).

const char * linphone_proxy_config_get_dial_prefix ( const LinphoneProxyConfig cfg)

Returns dialing prefix.

void linphone_proxy_config_destroy ( LinphoneProxyConfig obj)

Destroys a proxy config.

Note
: LinphoneProxyConfig that have been removed from LinphoneCore with linphone_core_remove_proxy_config() must not be freed.
int linphone_proxy_config_normalize_number ( LinphoneProxyConfig proxy,
const char *  username,
char *  result,
size_t  result_len 
)

normalize a human readable phone number into a basic string. 888-444-222 becomes 888444222

void linphone_core_refresh_registers ( LinphoneCore lc)

force registration refresh to be initiated upon next iterate

LinphoneProxyConfig* linphone_core_create_proxy_config ( LinphoneCore lc)

Create a proxy config with default value from Linphone core.

Parameters
lcLinphoneCore object
Returns
LinphoneProxyConfig with defualt value set
int linphone_dial_plan_lookup_ccc_from_e164 ( const char *  e164)

Function to get call country code from an e164 number, ex: +33952650121 will return 33

Parameters
e164phone number
Returns
call country code or -1 if not found
int linphone_dial_plan_lookup_ccc_from_iso ( const char *  iso)

Function to get call country code from ISO 3166-1 alpha-2 code, ex: FR returns 33

Parameters
isocountry code alpha2
Returns
call country code or -1 if not found
int linphone_core_add_proxy_config ( LinphoneCore lc,
LinphoneProxyConfig cfg 
)

Add a proxy configuration. This will start registration on the proxy, if registration is enabled.

void linphone_core_remove_proxy_config ( LinphoneCore lc,
LinphoneProxyConfig cfg 
)

Removes a proxy configuration.

LinphoneCore will then automatically unregister and place the proxy configuration on a deleted list. For that reason, a removed proxy does NOT need to be freed.

void linphone_core_clear_proxy_config ( LinphoneCore lc)

Erase all proxies from config.

void linphone_core_set_default_proxy ( LinphoneCore lc,
LinphoneProxyConfig config 
)

Sets the default proxy.

This default proxy must be part of the list of already entered LinphoneProxyConfig. Toggling it as default will make LinphoneCore use the identity associated with the proxy configuration in all incoming and outgoing calls.

int linphone_core_get_default_proxy ( LinphoneCore lc,
LinphoneProxyConfig **  config 
)

Returns the default proxy configuration, that is the one used to determine the current identity.

const MSList* linphone_core_get_proxy_config_list ( const LinphoneCore lc)

Returns an unmodifiable list of entered proxy configurations.