Package org.linphone.core

Interface Friend

public interface Friend

This object is used to store a SIP address.

Friend is mainly used to implement an adressbook feature, and are used
as data for the MagicSearch object. If your proxy supports it, you can
also use it to subscribe to presence information.
The objects are stored in a FriendList which are in turn stored inside
the Core. They can be stored inside a database if the path to it is
configured, otherwise they will be lost after the Core is destroyed.
Thanks to the vCard plugin, you can also store more information like phone
numbers, organization, etc...

Method Summary

Modifier and Type	Method	Description
void	addAddress(Address address)	Adds an address in this friend.
void	addListener(FriendListener listener)
void	addPhoneNumber(java.lang.String phoneNumber)	Adds a phone number in this friend.
void	addPhoneNumberWithLabel(FriendPhoneNumber phoneNumber)	Adds a FriendPhoneNumber to this friend.
boolean	createVcard(java.lang.String name)	Creates a vCard object associated to this friend if there isn't one yet and if the full name is available, either by the parameter or the one in the friend's SIP URI.
void	done()	Commits modification made to the friend configuration.
void	edit()	Starts editing a friend configuration.
Address	getAddress()	Get address of this friend.
Address[]	getAddresses()	Returns a list of Address for this friend.
int	getCapabilities()	Returns the capabilities associated to this friend.
float	getCapabilityVersion(FriendCapability capability)	Returns the version of a friend's capbility.
ConsolidatedPresence	getConsolidatedPresence()	Get the consolidated presence of a friend.
Core	getCore()	Returns the Core object managing this friend, if any.
SubscribePolicy	getIncSubscribePolicy()	get current subscription policy for this Friend
java.lang.String	getName()	Get the display name for this friend.
long	getNativePointer()	Gets the native pointer used by this class to make native method calls.
java.lang.String	getNativeUri()	Gets the contact's native URI.
java.lang.String	getOrganization()	Gets the contact's organization from it's vCard.
java.lang.String[]	getPhoneNumbers()	Returns a list of phone numbers for this friend.
FriendPhoneNumber[]	getPhoneNumbersWithLabel()	Returns a list of FriendPhoneNumber for this friend.
java.lang.String	getPhoto()	Gets the contact's picture URI.
PresenceModel	getPresenceModel()	Get the presence model of a friend.
PresenceModel	getPresenceModelForUriOrTel(java.lang.String uriOrTel)	Get the presence model for a specific SIP URI or phone number of a friend.
java.lang.String	getRefKey()	Get the reference key of a friend.
boolean	getStarred()	Gets if the friend is to be considered as important for the user.
SubscriptionState	getSubscriptionState()	Get subscription state of a friend.
java.lang.Object	getUserData()	Gets the object stored in this object user's data
Vcard	getVcard()	Returns the vCard object associated to this friend, if any.
boolean	hasCapability(FriendCapability capability)	Returns whether or not a friend has a capbility.
boolean	hasCapabilityWithVersion(FriendCapability capability, float version)	Returns whether or not a friend has a capbility with a given version.
boolean	hasCapabilityWithVersionOrMore(FriendCapability capability, float version)	Returns whether or not a friend has a capbility with a given version or more.
boolean	hasPhoneNumber(java.lang.String phoneNumber)	Returns whether a friend contains the given phone number.
boolean	inList()	Check that the given friend is in a friend list.
boolean	isPresenceReceived()	Tells whether we already received presence information for a friend.
boolean	isSubscribesEnabled()	get subscription flag value
Friend	newFromVcard(Vcard vcard)	Contructor same as linphone_friend_new + setAddress(org.linphone.core.Address)
void	remove()	Removes a friend from it's friend list and from the rc if exists.
void	removeAddress(Address address)	Removes an address in this friend.
void	removeListener(FriendListener listener)
void	removePhoneNumber(java.lang.String phoneNumber)	Removes a phone number in this friend.
void	removePhoneNumberWithLabel(FriendPhoneNumber phoneNumber)	Removes a FriendPhoneNumber from this friend.
void	save(Core core)	Saves a friend either in database if configured, otherwise in linphonerc.
int	setAddress(Address address)	Set Address for this friend.
int	setIncSubscribePolicy(SubscribePolicy policy)	Configure incoming subscription policy for this friend.
int	setName(java.lang.String name)	Set the display name for this friend.
void	setNativeUri(java.lang.String nativeUri)	Sets the contact's native URI.
void	setOrganization(java.lang.String organization)	Sets the contact's organization.
void	setPhoto(java.lang.String pictureUri)	Sets the contact's picture URI.
void	setPresenceModel(PresenceModel presence)	Set the presence model of a friend.
void	setPresenceModelForUriOrTel(java.lang.String uriOrTel, PresenceModel presence)	Set the presence model for a specific SIP URI or phone number of a friend.
void	setRefKey(java.lang.String key)	Set the reference key of a friend.
void	setStarred(boolean isStarred)	Sets if the friend is a user's favorite or important contact.
int	setSubscribesEnabled(boolean enable)	Configure Friend to subscribe to presence information.
void	setUserData(java.lang.Object data)	Sets the object to store in this object user's data
void	setVcard(Vcard vcard)	Binds a vCard object to a friend.
java.lang.String	toString()

Method Detail

getAddress

@Nullable
Address getAddress()

Get address of this friend.

note: the Address object returned is hold by the LinphoneFriend,
however calling several time this function may return different objects.

Returns:

the Address.

setAddress

int setAddress(@Nullable
               Address address)

Set Address for this friend.

Parameters:

address - the Address to set return 0 if successful, -1
otherwise

getAddresses

@NonNull
Address[] getAddresses()

Returns a list of Address for this friend.

Returns:

A list of Address.

getCapabilities

int getCapabilities()

Returns the capabilities associated to this friend.

Returns:

an int representing the capabilities of the friend

getConsolidatedPresence

ConsolidatedPresence getConsolidatedPresence()

Get the consolidated presence of a friend.

Returns:

The ConsolidatedPresence of the friend

getCore

@NonNull
Core getCore()

Returns the Core object managing this friend, if any.

Returns:

the Core object associated.

getIncSubscribePolicy

SubscribePolicy getIncSubscribePolicy()

get current subscription policy for this Friend

Returns:

the SubscribePolicy enum

setIncSubscribePolicy

int setIncSubscribePolicy(SubscribePolicy policy)

Configure incoming subscription policy for this friend.

Parameters:

policy - SubscribePolicy policy to apply.

Returns:

0

isPresenceReceived

boolean isPresenceReceived()

Tells whether we already received presence information for a friend.

Returns:

true if presence information has been received for the friend, false
otherwise.

getName

@Nullable
java.lang.String getName()

Get the display name for this friend.

Returns:

The display name of this friend.

setName

int setName(@Nullable
            java.lang.String name)

Set the display name for this friend.

Parameters:

name - the display name to set

Returns:

0 if successful, -1 otherwise

getNativeUri

@Nullable
java.lang.String getNativeUri()

Gets the contact's native URI.

Returns:

the native URI set if any, null otherwise.

setNativeUri

void setNativeUri(@Nullable
                  java.lang.String nativeUri)

Sets the contact's native URI.

Parameters:

nativeUri - the URI that matches the contact on the native system.

getOrganization

@Nullable
java.lang.String getOrganization()

Gets the contact's organization from it's vCard.

It's a shortcut to getVcard() and Vcard.getOrganization().

Returns:

the organization set if any & vCard is available, null otherwise.

setOrganization

void setOrganization(@Nullable
                     java.lang.String organization)

Sets the contact's organization.

It's a shortcut to getVcard() and Vcard.setOrganization(java.lang.String).

Parameters:

organization - the organization to store in Friend's vCard.

getPhoneNumbers

@NonNull
java.lang.String[] getPhoneNumbers()

Returns a list of phone numbers for this friend.

Returns:

A list of phone numbers as string.

getPhoneNumbersWithLabel

@NonNull
FriendPhoneNumber[] getPhoneNumbersWithLabel()

Returns a list of FriendPhoneNumber for this friend.

Returns:

A list of phone numbers as string.

getPhoto

@Nullable
java.lang.String getPhoto()

Gets the contact's picture URI.

Returns:

the picture URI set if any, null otherwise.

setPhoto

void setPhoto(@Nullable
              java.lang.String pictureUri)

Sets the contact's picture URI.

Parameters:

pictureUri - the picture URI to set.

getPresenceModel

@Nullable
PresenceModel getPresenceModel()

Get the presence model of a friend.

Returns:

A PresenceModel object, or null if the friend do not have
presence information (in which case he is considered offline).

setPresenceModel

void setPresenceModel(@Nullable
                      PresenceModel presence)

Set the presence model of a friend.

Parameters:

presence - The PresenceModel object to set for the friend

getRefKey

@Nullable
java.lang.String getRefKey()

Get the reference key of a friend.

Returns:

The reference key of the friend.

setRefKey

void setRefKey(@Nullable
               java.lang.String key)

Set the reference key of a friend.

Parameters:

key - The reference key to use for the friend.

getStarred

boolean getStarred()

Gets if the friend is to be considered as important for the user.

Returns:

true if the contact is a user's favorite, false otherwise.

setStarred

void setStarred(boolean isStarred)

Sets if the friend is a user's favorite or important contact.

Parameters:

isStarred - true if the friend is to be considered as important, false
otherwise.

isSubscribesEnabled

boolean isSubscribesEnabled()

get subscription flag value

Returns:

returns true is subscription is activated for this friend

setSubscribesEnabled

int setSubscribesEnabled(boolean enable)

Configure Friend to subscribe to presence information.

Parameters:

enable - if true this friend will receive subscription message

Returns:

0

getSubscriptionState

SubscriptionState getSubscriptionState()

Get subscription state of a friend.

Returns:

the SubscriptionState enum

getVcard

@Nullable
Vcard getVcard()

Returns the vCard object associated to this friend, if any.

Returns:

the Vcard or null.

setVcard

void setVcard(@Nullable
              Vcard vcard)

Binds a vCard object to a friend.

Parameters:

vcard - The Vcard object to bind

addAddress

void addAddress(@NonNull
                Address address)

Adds an address in this friend.

Parameters:

address - Address object

addPhoneNumber

void addPhoneNumber(@NonNull
                    java.lang.String phoneNumber)

Adds a phone number in this friend.

Parameters:

phoneNumber - number to add

addPhoneNumberWithLabel

void addPhoneNumberWithLabel(@NonNull
                             FriendPhoneNumber phoneNumber)

Adds a FriendPhoneNumber to this friend.

Parameters:

phoneNumber - the FriendPhoneNumber to add

createVcard

boolean createVcard(@Nullable
                    java.lang.String name)

Creates a vCard object associated to this friend if there isn't one yet and if
the full name is available, either by the parameter or the one in the friend's
SIP URI.

Parameters:

name - The full name of the friend or null to use the one from the
friend's SIP URI

Returns:

true if the vCard has been created, false if it wasn't possible (for
exemple if name and the friend's SIP URI are null or if the friend's SIP URI
doesn't have a display name), or if there is already one vcard

done

void done()

Commits modification made to the friend configuration.

edit

void edit()

Starts editing a friend configuration.

Because friend configuration must be consistent, applications MUST call edit()
before doing any attempts to modify friend configuration (such as setAddress(org.linphone.core.Address)
or setIncSubscribePolicy(org.linphone.core.SubscribePolicy)). Once the modifications are done, then the
application must call done() to commit the changes.

getCapabilityVersion

float getCapabilityVersion(FriendCapability capability)

Returns the version of a friend's capbility.

Parameters:

capability - FriendCapability object

Returns:

the version of a friend's capbility.

getPresenceModelForUriOrTel

@Nullable
PresenceModel getPresenceModelForUriOrTel(@NonNull
                                          java.lang.String uriOrTel)

Get the presence model for a specific SIP URI or phone number of a friend.

Parameters:

uriOrTel - The SIP URI or phone number for which to get the presence model

Returns:

A PresenceModel object, or null if the friend do not have
presence information for this SIP URI or phone number.

hasCapability

boolean hasCapability(FriendCapability capability)

Returns whether or not a friend has a capbility.

Parameters:

capability - FriendCapability object

Returns:

whether or not a friend has a capbility

hasCapabilityWithVersion

boolean hasCapabilityWithVersion(FriendCapability capability,
                                 float version)

Returns whether or not a friend has a capbility with a given version.

Parameters:

capability - FriendCapability object

version - the version to test

Returns:

whether or not a friend has a capbility with a given version or -1.0 if
friend has not capability.

hasCapabilityWithVersionOrMore

boolean hasCapabilityWithVersionOrMore(FriendCapability capability,
                                       float version)

Returns whether or not a friend has a capbility with a given version or more.

Parameters:

capability - FriendCapability object

version - the version to test

Returns:

whether or not a friend has a capbility with a given version or more.

hasPhoneNumber

boolean hasPhoneNumber(@NonNull
                       java.lang.String phoneNumber)

Returns whether a friend contains the given phone number.

Parameters:

phoneNumber - the phone number to search for

Returns:

true if found, false otherwise

inList

boolean inList()

Check that the given friend is in a friend list.

Returns:

true if the friend is in a friend list, false otherwise.

remove

void remove()

Removes a friend from it's friend list and from the rc if exists.

removeAddress

void removeAddress(@NonNull
                   Address address)

Removes an address in this friend.

Parameters:

address - Address object

removePhoneNumber

void removePhoneNumber(@NonNull
                       java.lang.String phoneNumber)

Removes a phone number in this friend.

Parameters:

phoneNumber - number to remove

removePhoneNumberWithLabel

void removePhoneNumberWithLabel(@NonNull
                                FriendPhoneNumber phoneNumber)

Removes a FriendPhoneNumber from this friend.

Parameters:

phoneNumber - the FriendPhoneNumber to remove

save

void save(@NonNull
          Core core)

Saves a friend either in database if configured, otherwise in linphonerc.

Parameters:

core - the linphone core

setPresenceModelForUriOrTel

void setPresenceModelForUriOrTel(@NonNull
                                 java.lang.String uriOrTel,
                                 @Nullable
                                 PresenceModel presence)

Set the presence model for a specific SIP URI or phone number of a friend.

Parameters:

uriOrTel - The SIP URI or phone number for which to set the presence model

presence - The PresenceModel object to set

newFromVcard

@Nullable
Friend newFromVcard(@NonNull
                    Vcard vcard)

Contructor same as linphone_friend_new + setAddress(org.linphone.core.Address)

Parameters:

vcard - a Vcard object

Returns:

a new Friend which has its vCard attribute initialized from the
given vCard. This can be get by getVcard().

addListener

void addListener(FriendListener listener)

removeListener

void removeListener(FriendListener listener)

setUserData

void setUserData(java.lang.Object data)

Sets the object to store in this object user's data

Parameters:

data - the object to store

getUserData

java.lang.Object getUserData()

Gets the object stored in this object user's data

Returns:

the object store if any, null otherwise

getNativePointer

long getNativePointer()

Gets the native pointer used by this class to make native method calls.

Returns:

the nativer pointer, as long

toString

java.lang.String toString()

Overrides:

toString in class java.lang.Object