Linphone address

SIP address parser API. More...

## Typedefs

typedef enum _LinphoneTransportType | LinphoneTransportType
| Enum describing transport type for LinphoneAddress.
typedef struct _LinphoneAddress | LinphoneAddress
| Object that represents a parsed SIP address.

## Enumerations

enum | _LinphoneTransportType { LinphoneTransportUdp = 0 , LinphoneTransportTcp = 1 , LinphoneTransportTls = 2 , LinphoneTransportDtls = 3 }
| Enum describing transport type for LinphoneAddress.

## Functions

LinphoneAddress * | linphone_core_create_address (LinphoneCore *core, const char *address)
| Create a LinphoneAddress object by parsing the user supplied address, given as a string.
LinphoneAddress * | linphone_address_new (const char *address)
| Constructs a LinphoneAddress object by parsing the user supplied address, given as a string.
LinphoneAddress * | linphone_address_clone (const LinphoneAddress *address)
| Clones a LinphoneAddress object.
LinphoneAddress * | linphone_address_ref (LinphoneAddress *address)
| Increment reference count of LinphoneAddress object.
void | linphone_address_unref (LinphoneAddress *address)
| Decrement reference count of LinphoneAddress object.
bool_t | linphone_address_is_valid (const LinphoneAddress *address)
| Returns if address is valid.
const char * | linphone_address_get_scheme (const LinphoneAddress *address)
| Returns the address scheme, normally "sip".
const char * | linphone_address_get_display_name (const LinphoneAddress *address)
| Returns the display name.
LinphoneStatus | linphone_address_set_display_name (LinphoneAddress *address, const char *display_name)
| Sets the display name.
const char * | linphone_address_get_username (const LinphoneAddress *address)
| Returns the username.
LinphoneStatus | linphone_address_set_username (LinphoneAddress *address, const char *username)
| Sets the username.
const char * | linphone_address_get_domain (const LinphoneAddress *address)
| Returns the domain name.
LinphoneStatus | linphone_address_set_domain (LinphoneAddress *address, const char *domain)
| Sets the domain.
int | linphone_address_get_port (const LinphoneAddress *address)
| Get port number as an integer value, 0 if not present.
LinphoneStatus | linphone_address_set_port (LinphoneAddress *address, int port)
| Sets the port number.
LinphoneTransportType | linphone_address_get_transport (const LinphoneAddress *address)
| Get the transport.
LinphoneStatus | linphone_address_set_transport (LinphoneAddress *address, LinphoneTransportType transport)
| Set a transport.
bool_t | linphone_address_get_secure (const LinphoneAddress *address)
| Returns whether the address refers to a secure location (sips) or not.
void | linphone_address_set_secure (LinphoneAddress *address, bool_t enabled)
| Make the address refer to a secure location (sips scheme)
bool_t | linphone_address_is_sip (const LinphoneAddress *address)
| returns whether the address is a routable SIP address or not
const char * | linphone_address_get_method_param (const LinphoneAddress *address)
| Get the value of the method parameter.
void | linphone_address_set_method_param (LinphoneAddress *address, const char *method_param)
| Set the value of the method parameter.
const char * | linphone_address_get_password (const LinphoneAddress *address)
| Get the password encoded in the address.
void | linphone_address_set_password (LinphoneAddress *address, const char *password)
| Set the password encoded in the address.
void | linphone_address_clean (LinphoneAddress *address)
| Removes address's tags and uri headers so that it is displayable to the user.
char * | linphone_address_as_string (const LinphoneAddress *address)
| Returns the address as a string.
char * | linphone_address_as_string_uri_only (const LinphoneAddress *address)
| Returns the SIP uri only as a string, that is display name is removed.
bool_t | linphone_address_weak_equal (const LinphoneAddress *address1, const LinphoneAddress *address2)
| Compare two LinphoneAddress ignoring tags and headers, basically just domain, username, and port.
bool_t | linphone_address_equal (const LinphoneAddress *address1, const LinphoneAddress *address2)
| Compare two LinphoneAddress taking the tags and headers into account.
const char * | linphone_address_get_header (const LinphoneAddress *address, const char *header_name)
| Get the header encoded in the address.
void | linphone_address_set_header (LinphoneAddress *address, const char *header_name, const char *header_value)
| Set a header into the address.
bool_t | linphone_address_has_param (const LinphoneAddress *address, const char *param_name)
| Tell whether a parameter is present in the address.
const char * | linphone_address_get_param (const LinphoneAddress *address, const char *param_name)
| Get the value of a parameter of the address.
void | linphone_address_set_param (LinphoneAddress *address, const char *param_name, const char *param_value)
| Set the value of a parameter of the address.
void | linphone_address_set_params (LinphoneAddress *address, const char *params)
bool_t | linphone_address_has_uri_param (const LinphoneAddress *address, const char *uri_param_name)
| Tell whether a parameter is present in the URI of the address.
const char * | linphone_address_get_uri_param (const LinphoneAddress *address, const char *uri_param_name)
| Get the value of a parameter of the URI of the address.
void | linphone_address_set_uri_param (LinphoneAddress *address, const char *uri_param_name, const char *uri_param_value)
| Set the value of a parameter of the URI of the address.
void | linphone_address_set_uri_params (LinphoneAddress *address, const char *params)
| Set the value of the parameters of the URI of the address.
void | linphone_address_remove_uri_param (LinphoneAddress *address, const char *uri_param_name)
| Removes the value of a parameter of the URI of the address.
MS2_DEPRECATED void | linphone_address_destroy (LinphoneAddress *address)
| Destroys a LinphoneAddress object (actually calls linphone_address_unref()).
MS2_DEPRECATED bool_t | linphone_address_is_secure (const LinphoneAddress *address)
| Returns true if address refers to a secure location (sips)

## Detailed Description

SIP address parser API.

This api is useful for manipulating SIP addresses ('from' or 'to' headers).

## Typedef Documentation

## LinphoneAddress

typedef struct _LinphoneAddress LinphoneAddress

Object that represents a parsed SIP address.

A SIP address is made of display name, username, domain name, port, and various uri headers (such as tags). It looks like 'Alice <sip:alice.nosp@m.@exa.nosp@m.mple..nosp@m.net>'.

You can create an address using linphone_factory_create_address() or linphone_core_interpret_url_2() and both will return a NULL object if it doesn't match the grammar defined by the standard.

This object is used in almost every other major objects to identity people (including yourself) & servers.

The LinphoneAddress has methods to extract and manipulate all parts of the address.

## Function Documentation

## linphone_address_as_string()

char * linphone_address_as_string | ( | const LinphoneAddress * | address | ) |

Returns the address as a string.

The returned char * must be freed by the application. Use ms_free().

Parameters

  address | a LinphoneAddress object.

Returns
  a string representation of the address.

## linphone_address_as_string_uri_only()

char * linphone_address_as_string_uri_only | ( | const LinphoneAddress * | address | ) |

Returns the SIP uri only as a string, that is display name is removed.

The returned char * must be freed by the application. Use ms_free().

Parameters

  address | a LinphoneAddress object.

Returns
  a string representation of the address.

## linphone_address_clean()

void linphone_address_clean | ( | LinphoneAddress * | address | ) |

Removes address's tags and uri headers so that it is displayable to the user.

Parameters

  address | a LinphoneAddress object.

## linphone_address_clone()

LinphoneAddress * linphone_address_clone | ( | const LinphoneAddress * | address | ) |

Clones a LinphoneAddress object.

Parameters

  address | a LinphoneAddress object to clone.

Returns
  a new LinphoneAddress object.

## linphone_address_destroy()

MS2_DEPRECATED void linphone_address_destroy | ( | LinphoneAddress * | address | ) |

Destroys a LinphoneAddress object (actually calls linphone_address_unref()).

Deprecated
  04/09/17 Use linphone_address_unref() instead

## linphone_address_equal()

bool_t linphone_address_equal | ( | const LinphoneAddress * | address1,
|  | const LinphoneAddress * | address2 )

Compare two LinphoneAddress taking the tags and headers into account.

Parameters

  address1 | LinphoneAddress object.
  address2 | LinphoneAddress object.

Returns
  Boolean value telling if the LinphoneAddress objects are equal.

See also
  linphone_address_weak_equal()

## linphone_address_get_display_name()

const char * linphone_address_get_display_name | ( | const LinphoneAddress * | address | ) |

Returns the display name.

Parameters

  address | a LinphoneAddress object.

Returns
  the display name if any, NULL otherwise.

## linphone_address_get_domain()

const char * linphone_address_get_domain | ( | const LinphoneAddress * | address | ) |

Returns the domain name.

Parameters

  address | a LinphoneAddress object.

Returns
  the domain name if any, NULL otherwise.

## linphone_address_get_header()

const char * linphone_address_get_header | ( | const LinphoneAddress * | address,
|  | const char * | header_name )

Get the header encoded in the address.

Parameters

  address | a LinphoneAddress object.
  header_name | the header name.

Returns
  the header value or NULL if it doesn't exists.

## linphone_address_get_method_param()

const char * linphone_address_get_method_param | ( | const LinphoneAddress * | address | ) |

Get the value of the method parameter.

Parameters

  address | a LinphoneAddress object.

Returns
  the value of the parameter or NULL.

## linphone_address_get_param()

const char * linphone_address_get_param | ( | const LinphoneAddress * | address,
|  | const char * | param_name )

Get the value of a parameter of the address.

Parameters

  address | a LinphoneAddress object.
  param_name | The name of the parameter.

Returns
  The value of the parameter or NULL if it doesn't exists.

## linphone_address_get_password()

const char * linphone_address_get_password | ( | const LinphoneAddress * | address | ) |

Get the password encoded in the address.

It is used for basic authentication (not recommended).

Parameters

  address | a LinphoneAddress object.

Returns
  the password if any, NULL otherwise.

## linphone_address_get_port()

int linphone_address_get_port | ( | const LinphoneAddress * | address | ) |

Get port number as an integer value, 0 if not present.

Parameters

  address | a LinphoneAddress object.

Returns
  the port set in the address or 0 if not present.

## linphone_address_get_scheme()

const char * linphone_address_get_scheme | ( | const LinphoneAddress * | address | ) |

Returns the address scheme, normally "sip".

Parameters

  address | a LinphoneAddress object.

Returns
  the scheme if any, NULL otherwise.

## linphone_address_get_secure()

bool_t linphone_address_get_secure | ( | const LinphoneAddress * | address | ) |

Returns whether the address refers to a secure location (sips) or not.

Parameters

  address | a LinphoneAddress object.

Returns
  TRUE if address refers to a secure location, FALSE otherwise

## linphone_address_get_transport()

LinphoneTransportType linphone_address_get_transport | ( | const LinphoneAddress * | address | ) |

Get the transport.

Parameters

  address | a LinphoneAddress object.

Returns
  a LinphoneTransportType, default value if not set is UDP.

## linphone_address_get_uri_param()

const char * linphone_address_get_uri_param | ( | const LinphoneAddress * | address,
|  | const char * | uri_param_name )

Get the value of a parameter of the URI of the address.

Parameters

  address | a LinphoneAddress object.
  uri_param_name | The name of the parameter.

Returns
  The value of the parameter or NULL if it doesn't exists.

## linphone_address_get_username()

const char * linphone_address_get_username | ( | const LinphoneAddress * | address | ) |

Returns the username.

Parameters

  address | a LinphoneAddress object.

Returns
  the username name if any, NULL otherwise.

## linphone_address_has_param()

bool_t linphone_address_has_param | ( | const LinphoneAddress * | address,
|  | const char * | param_name )

Tell whether a parameter is present in the address.

Parameters

  address | a LinphoneAddress object.
  param_name | The name of the parameter.

Returns
  A boolean value telling whether the parameter is present in the address

## linphone_address_has_uri_param()

bool_t linphone_address_has_uri_param | ( | const LinphoneAddress * | address,
|  | const char * | uri_param_name )

Tell whether a parameter is present in the URI of the address.

Parameters

  address | a LinphoneAddress object.
  uri_param_name | The name of the parameter.

Returns
  A boolean value telling whether the parameter is present in the URI of the address

## linphone_address_is_secure()

MS2_DEPRECATED bool_t linphone_address_is_secure | ( | const LinphoneAddress * | address | ) |

Returns true if address refers to a secure location (sips)

Deprecated
  04/09/17 use linphone_address_get_secure()

## linphone_address_is_sip()

bool_t linphone_address_is_sip | ( | const LinphoneAddress * | address | ) |

returns whether the address is a routable SIP address or not

Parameters

  address | a LinphoneAddress object.

Returns
  TRUE if it is a routable SIP address, FALSE otherwise

## linphone_address_is_valid()

bool_t linphone_address_is_valid | ( | const LinphoneAddress * | address | ) |

Returns if address is valid.

Parameters

  address | a LinphoneAddress object.

Returns
  the scheme if any, NULL otherwise.

## linphone_address_new()

LinphoneAddress * linphone_address_new | ( | const char * | address | ) |

Constructs a LinphoneAddress object by parsing the user supplied address, given as a string.

Parameters

  address | an address to parse.

Returns
  a LinphoneAddress if parsing is successful, NULL otherwise.

## linphone_address_ref()

LinphoneAddress * linphone_address_ref | ( | LinphoneAddress * | address | ) |

Increment reference count of LinphoneAddress object.

Parameters

  address | a LinphoneAddress object.

Returns
  the same LinphoneAddress object.

## linphone_address_remove_uri_param()

void linphone_address_remove_uri_param | ( | LinphoneAddress * | address,
|  | const char * | uri_param_name )

Removes the value of a parameter of the URI of the address.

Parameters

  address | a LinphoneAddress object.
  uri_param_name | The name of the parameter.

## linphone_address_set_display_name()

LinphoneStatus linphone_address_set_display_name | ( | LinphoneAddress * | address,
|  | const char * | display_name )

Sets the display name.

Parameters

  address | a LinphoneAddress object.
  display_name | the display name to set.

## linphone_address_set_domain()

LinphoneStatus linphone_address_set_domain | ( | LinphoneAddress * | address,
|  | const char * | domain )

Sets the domain.

Parameters

  address | a LinphoneAddress object.
  domain | the domain to set.

## linphone_address_set_header()

void linphone_address_set_header | ( | LinphoneAddress * | address,
|  | const char * | header_name,
|  | const char * | header_value )

Set a header into the address.

Headers appear in the URI with '?', such as <sip:test@.nosp@m.linp.nosp@m.hone..nosp@m.org?SomeHeader=SomeValue>.

Parameters

  address | a LinphoneAddress object.
  header_name | the header name.
  header_value | the header value.

## linphone_address_set_method_param()

void linphone_address_set_method_param | ( | LinphoneAddress * | address,
|  | const char * | method_param )

Set the value of the method parameter.

Parameters

  address | a LinphoneAddress object.
  method_param | the value to set to the method parameter.

## linphone_address_set_param()

void linphone_address_set_param | ( | LinphoneAddress * | address,
|  | const char * | param_name,
|  | const char * | param_value )

Set the value of a parameter of the address.

Parameters

  address | a LinphoneAddress object.
  param_name | The name of the parameter.
  param_value | The new value of the parameter.

## linphone_address_set_password()

void linphone_address_set_password | ( | LinphoneAddress * | address,
|  | const char * | password )

Set the password encoded in the address.

It is used for basic authentication (not recommended).

Parameters

  address | a LinphoneAddress object.
  password | the password to set.

## linphone_address_set_port()

LinphoneStatus linphone_address_set_port | ( | LinphoneAddress * | address,
|  | int | port )

Sets the port number.

Parameters

  address | a LinphoneAddress object.
  port | the port to set in the address

## linphone_address_set_secure()

void linphone_address_set_secure | ( | LinphoneAddress * | address,
|  | bool_t | enabled )

Make the address refer to a secure location (sips scheme)

Parameters

  address | A LinphoneAddress object.
  enabled | TRUE if address is requested to be secure.

## linphone_address_set_transport()

LinphoneStatus linphone_address_set_transport | ( | LinphoneAddress * | address,
|  | LinphoneTransportType | transport )

Set a transport.

Parameters

  address | a LinphoneAddress object.
  transport | a LinphoneTransportType

## linphone_address_set_uri_param()

void linphone_address_set_uri_param | ( | LinphoneAddress * | address,
|  | const char * | uri_param_name,
|  | const char * | uri_param_value )

Set the value of a parameter of the URI of the address.

Parameters

  address | a LinphoneAddress object.
  uri_param_name | The name of the parameter.
  uri_param_value | The new value of the parameter.

## linphone_address_set_uri_params()

void linphone_address_set_uri_params | ( | LinphoneAddress * | address,
|  | const char * | params )

Set the value of the parameters of the URI of the address.

Parameters

  [in] | address | LinphoneAddress object
  [in] | params | The parameters string

## linphone_address_set_username()

LinphoneStatus linphone_address_set_username | ( | LinphoneAddress * | address,
|  | const char * | username )

Sets the username.

Parameters

  address | a LinphoneAddress object.
  username | the username to set.

## linphone_address_unref()

void linphone_address_unref | ( | LinphoneAddress * | address | ) |

Decrement reference count of LinphoneAddress object.

When dropped to zero, memory is freed.

Parameters

  address | a LinphoneAddress object.

## linphone_address_weak_equal()

bool_t linphone_address_weak_equal | ( | const LinphoneAddress * | address1,
|  | const LinphoneAddress * | address2 )

Compare two LinphoneAddress ignoring tags and headers, basically just domain, username, and port.

Parameters

  address1 | LinphoneAddress object.
  address2 | LinphoneAddress object.

Returns
  Boolean value telling if the LinphoneAddress objects are equal.

See also
  linphone_address_equal()

## linphone_core_create_address()

LinphoneAddress * linphone_core_create_address | ( | LinphoneCore * | core,
|  | const char * | address )

Create a LinphoneAddress object by parsing the user supplied address, given as a string.

Parameters

  core | LinphoneCore object
  address | String containing the user supplied address

Returns
  The create LinphoneAddress object