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 addressbook feature and is used
as data for the `MagicSearch` object. If your proxy supports it, you can
also use it to subscribe to presence information.
Objects are stored in a `FriendList`, which is in turn stored inside the
`Core`. They can be stored in 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...

## Nested Class Summary

Nested Classes
Modifier and Type
Interface
Description
`static enum`
`Friend.Capability`

## Method Summary

Modifier and Type
Method
Description
`void`
`addAddress(Address address)`
Adds an address in this friend.
`void`
`addListener(FriendListener listener)`
`void`
`addPhoneNumber(String phoneNumber)`
Adds a phone number in this friend.
`void`
`addPhoneNumberWithLabel(FriendPhoneNumber phoneNumber)`
Adds a `FriendPhoneNumber` to this friend.
`boolean`
`createVcard(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.
`String`
`dumpVcard()`
Returns the a string matching the vCard inside the friend, if any.
`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(Friend.Capability 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.
`FriendDevice[]`
`getDevices()`
Returns a list of `FriendDevice` for this friend, for all known
addresses.
`FriendDevice[]`
`getDevicesForAddress(Address address)`
Returns a list of `FriendDevice` for this friend and a specific address.
`String`
`getFirstName()`
Gets the first name for this friend if vCard exists.
`FriendList`
`getFriendList()`
Check that the given friend is in a friend list.
`SubscribePolicy`
`getIncSubscribePolicy()`
get current subscription policy for this `Friend`
`boolean`
`getIsReadOnly()`
Gets whether this friend is read only or not.
`String`
`getJobTitle()`
Gets the contact's job title from its vCard.
`String`
`getLastName()`
Gets the last name for this friend if vCard exists.
`String`
`getName()`
Gets the display name for this friend.
`long`
`getNativePointer()`
Gets the native pointer used by this class to make native method calls.
`String`
`getNativeUri()`
Gets the contact's native URI.
`String`
`getOrganization()`
Gets the contact's organization from its vCard.
`String[]`
`getPhoneNumbers()`
Returns a list of phone numbers for this friend.
`FriendPhoneNumber[]`
`getPhoneNumbersWithLabel()`
Returns a list of `FriendPhoneNumber` for this friend.
`String`
`getPhoto()`
Gets the contact's picture URI.
`PresenceModel`
`getPresenceModel()`
Get the presence model of a friend.
`PresenceModel`
`getPresenceModelForUriOrTel(String uriOrTel)`
Get the presence model for a specific SIP URI or phone number of a friend.
`String`
`getRefKey()`
Get the reference key of a friend.
`SecurityLevel`
`getSecurityLevel()`
Returns the security level of a friend which is the lowest among all devices we
know for it.
`SecurityLevel`
`getSecurityLevelForAddress(Address address)`
Returns the security level of a friend for a given address which is the lowest
among all devices we know for that address.
`boolean`
`getStarred()`
Gets if the friend is to be considered as important for the user.
`SubscriptionState`
`getSubscriptionState()`
Get subscription state of a friend.
`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(Friend.Capability capability)`
Returns whether or not a friend has a capbility.
`boolean`
`hasCapabilityWithVersion(Friend.Capability capability, float version)`
Returns whether or not a friend has a capbility with a given version.
`boolean`
`hasCapabilityWithVersionOrMore(Friend.Capability capability, float version)`
Returns whether or not a friend has a capbility with a given version or more.
`boolean`
`hasPhoneNumber(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
`void`
`remove()`
Removes a friend from its friend list and from the resource list if it exists.
`void`
`removeAddress(Address address)`
Removes an address in this friend.
`void`
`removeListener(FriendListener listener)`
`void`
`removePhoneNumber(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`
`setFirstName(String firstName)`
Sets the first name for this friend is available.
`int`
`setIncSubscribePolicy(SubscribePolicy policy)`
Configure incoming subscription policy for this friend.
`void`
`setJobTitle(String jobTitle)`
Sets the contact's job title.
`int`
`setLastName(String lastName)`
Sets the last name for this friend if vCard is available.
`int`
`setName(String name)`
Sets the display name for this friend.
`void`
`setNativeUri(String nativeUri)`
Sets the contact's native URI.
`void`
`setOrganization(String organization)`
Sets the contact's organization.
`void`
`setPhoto(String pictureUri)`
Sets the contact's picture URI.
`void`
`setPresenceModel(PresenceModel presence)`
Set the presence model of a friend.
`void`
`setPresenceModelForUriOrTel(String uriOrTel, PresenceModel presence)`
Set the presence model for a specific SIP URI or phone number of a friend.
`void`
`setRefKey(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(Object data)`
Sets the object to store in this object user's data
`void`
`setVcard(Vcard vcard)`
Binds a vCard object to a friend.
`String`
`toString()`

## Method Details

### 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.
It will return the "most open" presence found if more than one presence model
are found.

Returns:
  The `ConsolidatedPresence` of the friend

### getCore

@NonNull Core getCore()
Returns the `Core` object managing this friend, if any.

Returns:
  the `Core` object associated.

### getDevices

@NonNull FriendDevice[] getDevices()
Returns a list of `FriendDevice` for this friend, for all known
addresses.

Returns:
  A list of `FriendDevice`.

### getFirstName

@Nullable String getFirstName()
Gets the first name for this friend if vCard exists.

Returns:
  The first name of this friend.

### setFirstName

int setFirstName(@Nullable String firstName)
Sets the first name for this friend is available.

Parameters:
  `firstName` - the first name to set
Returns:
  0 if successful, -1 otherwise

### getFriendList

@Nullable FriendList getFriendList()
Check that the given friend is in a friend list.

Returns:
  The `FriendList` the friend is in if any, null otherwise.

### 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.

### getIsReadOnly

boolean getIsReadOnly()
Gets whether this friend is read only or not.
A friend is read-only if the `FriendList` to which it belongs is
read-only.

Returns:
  true if the friend is attached to an existing `FriendList` which
  is in read-only mode, false otherwise.

### getJobTitle

@Nullable String getJobTitle()
Gets the contact's job title from its vCard.
This is a shortcut to `getVcard()` and `Vcard.getJobTitle()`.

Returns:
  the job_title set if any & vCard is available, null otherwise.

### setJobTitle

void setJobTitle(@Nullable String jobTitle)
Sets the contact's job title.
This is a shortcut to `getVcard()` and `Vcard.setJobTitle(java.lang.String)`.

Parameters:
  `jobTitle` - The job title to store in Friend's vCard.

### getLastName

@Nullable String getLastName()
Gets the last name for this friend if vCard exists.

Returns:
  The last name of this friend.

### setLastName

int setLastName(@Nullable String lastName)
Sets the last name for this friend if vCard is available.

Parameters:
  `lastName` - the last name to set
Returns:
  0 if successful, -1 otherwise

### getName

@Nullable String getName()
Gets the display name for this friend.

Returns:
  The display name of this friend.

### setName

int setName(@Nullable String name)
Sets the display name for this friend.

Parameters:
  `name` - the display name to set
Returns:
  0 if successful, -1 otherwise

### getNativeUri

@Nullable String getNativeUri()
Gets the contact's native URI.

Returns:
  the native URI set if any, null otherwise.

### setNativeUri

void setNativeUri(@Nullable String nativeUri)
Sets the contact's native URI.

Parameters:
  `nativeUri` - the URI that matches the contact on the native system.

### getOrganization

@Nullable String getOrganization()
Gets the contact's organization from its vCard.
This is a shortcut to `getVcard()` and `Vcard.getOrganization()`.

Returns:
  The organization set if any and vCard is available, null otherwise.

### setOrganization

void setOrganization(@Nullable 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 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 String getPhoto()
Gets the contact's picture URI.

Returns:
  the picture URI set if any, null otherwise.

### setPhoto

void setPhoto(@Nullable 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.
If a friend has more than one SIP address and phone number, this method will
return the most recent presence model using `PresenceModel.getTimestamp()`.

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 String getRefKey()
Get the reference key of a friend.

Returns:
  The reference key of the friend.

### setRefKey

void setRefKey(@Nullable String key)
Set the reference key of a friend.

Parameters:
  `key` - The reference key to use for the friend.

### getSecurityLevel

SecurityLevel getSecurityLevel()
Returns the security level of a friend which is the lowest among all devices we
know for it.

Returns:
  A `SecurityLevel`, which is the lowest among all known devices.

### 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 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 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.

### dumpVcard

@Nullable String dumpVcard()
Returns the a string matching the vCard inside the friend, if any.

Returns:
  the vCard as a string or null.

### 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(Friend.Capability capability)
Returns the version of a friend's capbility.

Parameters:
  `capability` - `Friend.Capability` object
Returns:
  the version of a friend's capbility.

### getDevicesForAddress

@NonNull FriendDevice[] getDevicesForAddress(@NonNull Address address)
Returns a list of `FriendDevice` for this friend and a specific address.

Parameters:
  `address` - `Address` object
Returns:
  A list of `FriendDevice`.

### getPresenceModelForUriOrTel

@Nullable PresenceModel getPresenceModelForUriOrTel(@NonNull 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.

### getSecurityLevelForAddress

SecurityLevel getSecurityLevelForAddress(@NonNull Address address)
Returns the security level of a friend for a given address which is the lowest
among all devices we know for that address.

Parameters:
  `address` - `Address` object
Returns:
  A `SecurityLevel`, which is the lowest among all known devices
  for that address.

### hasCapability

boolean hasCapability(Friend.Capability capability)
Returns whether or not a friend has a capbility.

Parameters:
  `capability` - `Friend.Capability` object
Returns:
  whether or not a friend has a capbility

### hasCapabilityWithVersion

boolean hasCapabilityWithVersion(Friend.Capability capability, float version)
Returns whether or not a friend has a capbility with a given version.

Parameters:
  `capability` - `Friend.Capability` 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(Friend.Capability capability, float version)
Returns whether or not a friend has a capbility with a given version or more.

Parameters:
  `capability` - `Friend.Capability` 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 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 its friend list and from the resource list if it exists.

### removeAddress

void removeAddress(@NonNull Address address)
Removes an address in this friend.

Parameters:
  `address` - `Address` object

### removePhoneNumber

void removePhoneNumber(@NonNull 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 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

### addListener

void addListener(FriendListener listener)

### removeListener

void removeListener(FriendListener listener)

### setUserData

void setUserData(Object data)
Sets the object to store in this object user's data

Parameters:
  `data` - the object to store

### getUserData

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

String toString()

Overrides:
  `toString` in class `Object`