# 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)
LinphoneAddress * | linphone_core_get_primary_contact_parsed (LinphoneCore *lc)
const char * | linphone_core_get_identity (LinphoneCore *lc)
const char * | linphone_registration_state_to_string (LinphoneRegistrationState cs)
LinphoneProxyConfig * | linphone_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)
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)
void | linphone_proxy_config_enableregister (LinphoneProxyConfig *obj, bool_t val)
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:

            LinphoneProxyConfig* proxy_cfg;
            /*create proxy config*/
            proxy_cfg = linphone_proxy_config_new();
            /*parse identity*/
            LinphoneAddress *from = linphone_address_new("sip:toto@sip.titi.com");
            LinphoneAuthInfo *info;
            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"
                                    ,linphone_registration_state_to_string(cstate)
                                    ,linphone_proxy_config_get_identity(cfg)
                                    ,linphone_proxy_config_get_addr(cfg));
    }

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

            LinphoneProxyConfig* proxy_cfg;
            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.

typedef enum _LinphoneRegistrationState LinphoneRegistrationState

LinphoneRegistrationState describes proxy registration states.

## Enumeration Type Documentation

enum _LinphoneRegistrationState

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:

  | cs | sate

LinphoneProxyConfig * linphone_proxy_config_new | ( |  | ) |

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@example.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:

  | obj | object pointer
  | val | if true, registration will be engaged

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:

  | obj | object pointer
  | val | if true, publish will be engaged

void linphone_proxy_config_set_dial_escape_plus | ( | LinphoneProxyConfig * | cfg,
|  | bool_t | val |
| ) |  |  |

Sets whether liblinphone should replace "+" by "00" 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.

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> )

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.

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

void linphone_proxy_config_enableregister | ( | LinphoneProxyConfig * | obj,
|  | bool_t | val |
| ) |  |  |

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

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.