net.java.sip.communicator.service.protocol
Interface CallPeer

All Known Implementing Classes:

AbstractCallPeer, CallPeerGibberishImpl, CallPeerGTalkImpl, CallPeerJabberImpl, CallPeerSipImpl, MediaAwareCallPeer, MockCallPeer

public interface CallPeer

The CallPeer is an interface that represents peers in a call. Users of the UIService need to implement this interface (or one of its default implementations such DefaultCallPeer) in order to be able to register call peer in the user interface.

For SIP calls for example, it would be necessary to create a CallPeerSipImpl class that would provide sip specific implementations of various methods (getAddress() for example would return the peer's sip URI).

Author:

Emil Ivov, Lubomir Marinov, Yana Stamcheva

Field Summary

static long	CALL_DURATION_START_TIME_UNKNOWN The constant indicating that a CallPeer has not yet transitioned into a state marking the beginning of a participation in a Call or that such a transition may have happened but the time of its occurrence is unknown.
static String	MUTE_PROPERTY_NAME The mute property name.

Method Summary

void	addCallPeerConferenceListener(CallPeerConferenceListener listener) Adds a specific CallPeerConferenceListener to the list of listeners interested in and notified about changes in conference-related information such as this peer acting or not acting as a conference focus and conference membership details.
void	addCallPeerListener(CallPeerListener listener) Allows the user interface to register a listener interested in changes
void	addCallPeerSecurityListener(CallPeerSecurityListener listener) Allows the user interface to register a listener interested in security status changes.
void	addConferenceMembersSoundLevelListener(ConferenceMembersSoundLevelListener listener) Adds a specific SoundLevelListener to the list of listeners interested in and notified about changes in conference members sound level.
void	addPropertyChangeListener(PropertyChangeListener listener) Allows the user interface to register a listener interested in property changes.
void	addStreamSoundLevelListener(SoundLevelListener listener) Adds a specific SoundLevelListener to the list of listeners interested in and notified about changes in stream sound level related information.
String	getAddress() Returns a String locator for that peer.
Call	getCall() Returns a reference to the call that this peer belongs to.
long	getCallDurationStartTime() Gets the time at which this CallPeer transitioned into a state (likely CallPeerState.CONNECTED) marking the start of the duration of the participation in a Call.
URL	getCallInfoURL() Returns a URL pointing to a location with call control information or null if such an URL is not available for the current call peer.
int	getConferenceMemberCount() Gets the number of ConferenceMembers currently known to this peer if it is acting as a conference focus.
ConferenceMember[]	getConferenceMembers() Gets the ConferenceMembers currently known to this peer if it is acting as a conference focus.
Contact	getContact() Returns the contact corresponding to this peer or null if no particular contact has been associated.
CallPeerSecurityStatusEvent	getCurrentSecuritySettings() Returns the currently used security settings of this CallPeer.
String	getDisplayName() Returns a human readable name representing this peer.
byte[]	getImage() The method returns an image representation of the call peer (e.g.
String	getPeerID() Returns a unique identifier representing this peer.
ProtocolProviderService	getProtocolProvider() Returns the protocol provider that this peer belongs to.
CallPeerState	getState() Returns an object representing the current state of that peer.
String	getURI() Returns full URI of the address.
boolean	isConferenceFocus() Determines whether this peer is acting as a conference focus and thus may provide information about ConferenceMember such as getConferenceMembers() and getConferenceMemberCount().
boolean	isMute() Determines whether the audio stream (if any) being sent to this peer is mute.
void	removeCallPeerConferenceListener(CallPeerConferenceListener listener) Removes a specific CallPeerConferenceListener from the list of listeners interested in and notified about changes in conference-related information such as this peer acting or not acting as a conference focus and conference membership details.
void	removeCallPeerListener(CallPeerListener listener) Unregisters the specified listener.
void	removeCallPeerSecurityListener(CallPeerSecurityListener listener) Unregisters the specified listener.
void	removeConferenceMembersSoundLevelListener(ConferenceMembersSoundLevelListener listener) Removes a specific SoundLevelListener of the list of listeners interested in and notified about changes in conference members sound level.
void	removePropertyChangeListener(PropertyChangeListener listener) Unregisters the specified property change listener.
void	removeStreamSoundLevelListener(SoundLevelListener listener) Removes a specific SoundLevelListener of the list of listeners interested in and notified about changes in stream sound level related information.
String	toString() Returns a string representation of the peer in the form of Display Name <address>;status=CallPeerStatus

Field Detail

CALL_DURATION_START_TIME_UNKNOWN

static final long CALL_DURATION_START_TIME_UNKNOWN

The constant indicating that a CallPeer has not yet transitioned into a state marking the beginning of a participation in a Call or that such a transition may have happened but the time of its occurrence is unknown.

See Also:

Constant Field Values

MUTE_PROPERTY_NAME

static final String MUTE_PROPERTY_NAME

The mute property name.

See Also:

Constant Field Values

Method Detail

getPeerID

String getPeerID()

Returns a unique identifier representing this peer. Identifiers returned by this method should remain unique across calls. In other words, if it returned the value of "A" for a given peer it should not return that same value for any other peer and return a different value even if the same person (address) is participating in another call. Values need not remain unique after restarting the program.

Returns:

an identifier representing this call peer.

getCall

Call getCall()

Returns a reference to the call that this peer belongs to.

Returns:

a reference to the call containing this peer.

getDisplayName

String getDisplayName()

Returns a human readable name representing this peer.

Returns:

a String containing a name for that peer.

getAddress

String getAddress()

Returns a String locator for that peer. A locator might be a SIP URI, an IP address or a telephone number.

Returns:

the peer's address or phone number.

getURI

String getURI()

Returns full URI of the address. For example sip:user@domain.org or xmpp:user@domain.org.

Returns:

full URI of the address

getState

CallPeerState getState()

Returns an object representing the current state of that peer. CallPeerState may vary among CONNECTING, RINGING, CALLING, BUSY, CONNECTED, and others, and it reflects the state of the connection between us and that peer.

Returns:

a CallPeerState instance representing the peer's state.

addCallPeerListener

void addCallPeerListener(CallPeerListener listener)

Allows the user interface to register a listener interested in changes

Parameters:

listener - a listener instance to register with this peer.

removeCallPeerListener

void removeCallPeerListener(CallPeerListener listener)

Unregisters the specified listener.

Parameters:

listener - the listener to unregister.

addCallPeerSecurityListener

void addCallPeerSecurityListener(CallPeerSecurityListener listener)

Allows the user interface to register a listener interested in security status changes.

Parameters:

listener - a listener instance to register with this peer

removeCallPeerSecurityListener

void removeCallPeerSecurityListener(CallPeerSecurityListener listener)

Unregisters the specified listener.

Parameters:

listener - the listener to unregister

addPropertyChangeListener

void addPropertyChangeListener(PropertyChangeListener listener)

Allows the user interface to register a listener interested in property changes.

Parameters:

listener - a property change listener instance to register with this peer.

removePropertyChangeListener

void removePropertyChangeListener(PropertyChangeListener listener)

Unregisters the specified property change listener.

Parameters:

listener - the property change listener to unregister.

getCallDurationStartTime

long getCallDurationStartTime()

Gets the time at which this CallPeer transitioned into a state (likely CallPeerState.CONNECTED) marking the start of the duration of the participation in a Call.

Returns:

the time at which this CallPeer transitioned into a state marking the start of the duration of the participation in a Call or CALL_DURATION_START_TIME_UNKNOWN if such a transition has not been performed

toString

String toString()

Returns a string representation of the peer in the form of
Display Name <address>;status=CallPeerStatus

Overrides:

toString in class Object

Returns:

a string representation of the peer and its state.

getImage

byte[] getImage()

The method returns an image representation of the call peer (e.g. a photo). Generally, the image representation is acquired from the underlying telephony protocol and is transferred over the network during call negotiation.

Returns:

byte[] a byte array containing the image or null if no image is available.

getProtocolProvider

ProtocolProviderService getProtocolProvider()

Returns the protocol provider that this peer belongs to.

Returns:

a reference to the ProtocolProviderService that this peer belongs to.

getContact

Contact getContact()

Returns the contact corresponding to this peer or null if no particular contact has been associated.

Returns:

the Contact corresponding to this peer or null if no particular contact has been associated.

getCallInfoURL

URL getCallInfoURL()

Returns a URL pointing to a location with call control information or null if such an URL is not available for the current call peer.

Returns:

a URL link to a location with call information or a call control web interface related to this peer or null if no such URL is available.

isMute

boolean isMute()

Determines whether the audio stream (if any) being sent to this peer is mute.

Returns:

true if an audio stream is being sent to this peer and it is currently mute; false, otherwise

isConferenceFocus

boolean isConferenceFocus()

Determines whether this peer is acting as a conference focus and thus may provide information about ConferenceMember such as getConferenceMembers() and getConferenceMemberCount().

Returns:

true if this peer is acting as a conference focus; false, otherwise

getConferenceMembers

ConferenceMember[] getConferenceMembers()

Gets the ConferenceMembers currently known to this peer if it is acting as a conference focus.

Returns:

an array of ConferenceMembers describing the members of a conference managed by this peer if it is acting as a conference focus. If this peer is not acting as a conference focus or it does but there are currently no members in the conference it manages, an empty array is returned.

getConferenceMemberCount

int getConferenceMemberCount()

Gets the number of ConferenceMembers currently known to this peer if it is acting as a conference focus.

Returns:

the number of ConferenceMembers currently known to this peer if it is acting as a conference focus. If this peer is not acting as a conference focus or it does but there are currently no members in the conference it manages, a value of zero is returned.

addCallPeerConferenceListener

void addCallPeerConferenceListener(CallPeerConferenceListener listener)

Adds a specific CallPeerConferenceListener to the list of listeners interested in and notified about changes in conference-related information such as this peer acting or not acting as a conference focus and conference membership details.

Parameters:

listener - a CallPeerConferenceListener to be notified about changes in conference-related information. If the specified listener is already in the list of interested listeners (i.e. it has been previously added), it is not added again.

removeCallPeerConferenceListener

void removeCallPeerConferenceListener(CallPeerConferenceListener listener)

Removes a specific CallPeerConferenceListener from the list of listeners interested in and notified about changes in conference-related information such as this peer acting or not acting as a conference focus and conference membership details.

Parameters:

listener - a CallPeerConferenceListener to no longer be notified about changes in conference-related information

addStreamSoundLevelListener

void addStreamSoundLevelListener(SoundLevelListener listener)

Adds a specific SoundLevelListener to the list of listeners interested in and notified about changes in stream sound level related information.

Parameters:

listener - the SoundLevelListener to add

removeStreamSoundLevelListener

void removeStreamSoundLevelListener(SoundLevelListener listener)

Removes a specific SoundLevelListener of the list of listeners interested in and notified about changes in stream sound level related information.

Parameters:

listener - the SoundLevelListener to remove

addConferenceMembersSoundLevelListener

void addConferenceMembersSoundLevelListener(ConferenceMembersSoundLevelListener listener)

Adds a specific SoundLevelListener to the list of listeners interested in and notified about changes in conference members sound level.

Parameters:

listener - the SoundLevelListener to add

removeConferenceMembersSoundLevelListener

void removeConferenceMembersSoundLevelListener(ConferenceMembersSoundLevelListener listener)

Removes a specific SoundLevelListener of the list of listeners interested in and notified about changes in conference members sound level.

Parameters:

listener - the SoundLevelListener to remove

getCurrentSecuritySettings

CallPeerSecurityStatusEvent getCurrentSecuritySettings()

Returns the currently used security settings of this CallPeer.

Returns:

the CallPeerSecurityStatusEvent that contains the current security settings.