Linphone address

Typedefs
typedef enum _LinphoneTransportType	LinphoneTransportType
typedef struct _LinphoneAddress	LinphoneAddress

Enumerations
enum	_LinphoneTransportType {   LinphoneTransportUdp = 0 ,   LinphoneTransportTcp = 1 ,   LinphoneTransportTls = 2 ,   LinphoneTransportDtls = 3 }

Functions
MS2_DEPRECATED LinphoneAddress *	linphone_core_create_address (LinphoneCore *core, const char *address)
LinphoneAddress *	linphone_address_new (const char *address)
LinphoneAddress *	linphone_address_clone (const LinphoneAddress *address)
LinphoneAddress *	linphone_address_ref (LinphoneAddress *address)
void	linphone_address_unref (LinphoneAddress *address)
bool_t	linphone_address_is_valid (const LinphoneAddress *address)
const char *	linphone_address_get_scheme (const LinphoneAddress *address)
const char *	linphone_address_get_display_name (const LinphoneAddress *address)
LinphoneStatus	linphone_address_set_display_name (LinphoneAddress *address, const char *display_name)
const char *	linphone_address_get_username (const LinphoneAddress *address)
LinphoneStatus	linphone_address_set_username (LinphoneAddress *address, const char *username)
const char *	linphone_address_get_domain (const LinphoneAddress *address)
LinphoneStatus	linphone_address_set_domain (LinphoneAddress *address, const char *domain)
int	linphone_address_get_port (const LinphoneAddress *address)
LinphoneStatus	linphone_address_set_port (LinphoneAddress *address, int port)
LinphoneTransportType	linphone_address_get_transport (const LinphoneAddress *address)
LinphoneStatus	linphone_address_set_transport (LinphoneAddress *address, LinphoneTransportType transport)
bool_t	linphone_address_get_secure (const LinphoneAddress *address)
void	linphone_address_set_secure (LinphoneAddress *address, bool_t enabled)
bool_t	linphone_address_is_sip (const LinphoneAddress *address)
const char *	linphone_address_get_method_param (const LinphoneAddress *address)
void	linphone_address_set_method_param (LinphoneAddress *address, const char *method_param)
const char *	linphone_address_get_password (const LinphoneAddress *address)
void	linphone_address_set_password (LinphoneAddress *address, const char *password)
void	linphone_address_clean (LinphoneAddress *address)
char *	linphone_address_as_string (const LinphoneAddress *address)
char *	linphone_address_as_string_uri_only (const LinphoneAddress *address)
char *	linphone_address_as_string_uri_only_ordered (const LinphoneAddress *address)
bool_t	linphone_address_weak_equal (const LinphoneAddress *address1, const LinphoneAddress *address2)
bool_t	linphone_address_equal (const LinphoneAddress *address1, const LinphoneAddress *address2)
const char *	linphone_address_get_header (const LinphoneAddress *address, const char *header_name)
void	linphone_address_set_header (LinphoneAddress *address, const char *header_name, const char *header_value)
bool_t	linphone_address_has_param (const LinphoneAddress *address, const char *param_name)
const char *	linphone_address_get_param (const LinphoneAddress *address, const char *param_name)
void	linphone_address_set_param (LinphoneAddress *address, const char *param_name, const char *param_value)
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)
const char *	linphone_address_get_uri_param (const LinphoneAddress *address, const char *uri_param_name)
void	linphone_address_set_uri_param (LinphoneAddress *address, const char *uri_param_name, const char *uri_param_value)
void	linphone_address_set_uri_params (LinphoneAddress *address, const char *params)
void	linphone_address_remove_uri_param (LinphoneAddress *address, const char *uri_param_name)
bool_t	linphone_address_lesser (const LinphoneAddress *address, const LinphoneAddress *other)
MS2_DEPRECATED void	linphone_address_destroy (LinphoneAddress *address)
MS2_DEPRECATED bool_t	linphone_address_is_secure (const LinphoneAddress *address)

Detailed Description

SIP address parser API.

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

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

char * linphone_address_as_string_uri_only_ordered

(

const LinphoneAddress *

address

)

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

This function always returns a string whose URI parameters has a constant order allowing to easily compute hashes for example. 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

TRUE is the address is valid, FALSE otherwise

linphone_address_lesser()

bool_t linphone_address_lesser	(	const LinphoneAddress *	address,
		const LinphoneAddress *	other
	)

Compare two addresses.

Parameters

address	a LinphoneAddress object.
other	an other LinphoneAddress object.

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

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

Creates 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 created LinphoneAddress object

Deprecated:

04/06/2024 use linphone_factory_create_address().