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

All Known Implementing Classes:

AbstractProtocolProviderService, MockProvider, ProtocolProviderServiceDictImpl, ProtocolProviderServiceGibberishImpl, ProtocolProviderServiceIcqImpl, ProtocolProviderServiceIrcImpl, ProtocolProviderServiceJabberImpl, ProtocolProviderServiceMsnImpl, ProtocolProviderServiceRssImpl, ProtocolProviderServiceSipImpl, ProtocolProviderServiceSSHImpl, ProtocolProviderServiceYahooImpl, ProtocolProviderServiceZeroconfImpl

public interface ProtocolProviderService

The ProtocolProvider interface should be implemented by bundles that wrap Instant Messaging and telephony protocol stacks. It gives the user interface a way to plug into these stacks and receive notifications on status change and incoming calls, as well as deliver user requests for establishing or ending calls, putting peers on hold and etc.

An instance of a ProtocolProviderService corresponds to a particular user account and all operations performed through a provider (sending messages, modifying contact lists, receiving calls)would pertain to this particular user account.

ProtocolProviderService instances are created through the provider factory. Each protocol provider is assigned a unique AccountID instance that uniquely identifies it. Account id's for different accounts are guaranteed to be different and in the same time the ID of a particular account against a given service over any protocol will always be the same (so that we detect attempts for creating the same account twice.)

Author:

Emil Ivov

See Also:

AccountID

Field Summary

static int	BIND_RETRIES_DEFAULT_VALUE The default number of binds that a Protocol Provider Service Implementation should execute in case a port is already bound to (each retry would be on a new random port).
static String	BIND_RETRIES_PROPERTY_NAME The name of the property containing the number of binds that a Protocol Provider Service Implementation should execute in case a port is already bound to (each retry would be on a new random port).

Method Summary

void	addRegistrationStateChangeListener(RegistrationStateChangeListener listener) Registers the specified listener with this provider so that it would receive notifications on changes of its state or other properties such as its local address and display name.
AccountID	getAccountID() Returns the AccountID that uniquely identifies the account represented by this instance of the ProtocolProviderService.
<T extends OperationSet> T	getOperationSet(Class<T> opsetClass) Returns the operation set corresponding to the specified class or null if this operation set is not supported by the provider implementation.
String	getProtocolDisplayName() Returns the protocol display name.
ProtocolIcon	getProtocolIcon() Returns the protocol logo icon.
String	getProtocolName() Returns the short name of the protocol that the implementation of this provider is based upon (like SIP, Jabber, ICQ/AIM, or others for example).
RegistrationState	getRegistrationState() Returns the state of the registration of this protocol provider with the corresponding registration service.
Collection<Class<? extends OperationSet>>	getSupportedOperationSetClasses() Returns a collection containing all operation sets classes supported by the current implementation.
Map<String,OperationSet>	getSupportedOperationSets() Returns an array containing all operation sets supported by the current implementation.
TransportProtocol	getTransportProtocol() Returns the "transport" protocol of this instance used to carry the control channel for the current protocol service.
int	hashCode() A hashcode allowing usage of protocol providers as keys in Hashtables.
boolean	isRegistered() Indicates whether or not this provider is registered
boolean	isSignalingTransportSecure() Indicate if the signaling transport of this protocol instance uses a secure (e.g.
void	register(SecurityAuthority authority) Starts the registration process.
void	removeRegistrationStateChangeListener(RegistrationStateChangeListener listener) Removes the specified listener.
void	shutdown() Makes the service implementation close all open sockets and release any resources that it might have taken and prepare for shutdown/garbage collection.
void	unregister() Ends the registration of this protocol provider with the current registration service.

Field Detail

BIND_RETRIES_PROPERTY_NAME

static final String BIND_RETRIES_PROPERTY_NAME

The name of the property containing the number of binds that a Protocol Provider Service Implementation should execute in case a port is already bound to (each retry would be on a new random port).

See Also:

Constant Field Values

BIND_RETRIES_DEFAULT_VALUE

static final int BIND_RETRIES_DEFAULT_VALUE

The default number of binds that a Protocol Provider Service Implementation should execute in case a port is already bound to (each retry would be on a new random port).

See Also:

Constant Field Values

Method Detail

register

void register(SecurityAuthority authority)
              throws OperationFailedException

Starts the registration process. Connection details such as registration server, user name/number are provided through the configuration service through implementation specific properties.

Parameters:

authority - the security authority that will be used for resolving any security challenges that may be returned during the registration or at any moment while wer're registered.

Throws:

OperationFailedException - with the corresponding code it the registration fails for some reason (e.g. a networking error or an implementation problem).

unregister

void unregister()
                throws OperationFailedException

Ends the registration of this protocol provider with the current registration service.

Throws:

OperationFailedException - with the corresponding code it the registration fails for some reason (e.g. a networking error or an implementation problem).

isRegistered

boolean isRegistered()

Indicates whether or not this provider is registered

Returns:

true if the provider is currently registered and false otherwise.

getRegistrationState

RegistrationState getRegistrationState()

Returns the state of the registration of this protocol provider with the corresponding registration service.

Returns:

ProviderRegistrationState

getProtocolName

String getProtocolName()

Returns the short name of the protocol that the implementation of this provider is based upon (like SIP, Jabber, ICQ/AIM, or others for example). If the name of the protocol has been enumerated in ProtocolNames then the value returned by this method must be the same as the one in ProtocolNames.

Returns:

a String containing the short name of the protocol this service is implementing (most often that would be a name in ProtocolNames).

getProtocolDisplayName

String getProtocolDisplayName()

Returns the protocol display name. This is the name that would be used by the GUI to display the protocol name.

Returns:

a String containing the display name of the protocol this service is implementing

getProtocolIcon

ProtocolIcon getProtocolIcon()

Returns the protocol logo icon.

Returns:

the protocol logo icon

addRegistrationStateChangeListener

void addRegistrationStateChangeListener(RegistrationStateChangeListener listener)

Registers the specified listener with this provider so that it would receive notifications on changes of its state or other properties such as its local address and display name.

Parameters:

listener - the listener to register.

removeRegistrationStateChangeListener

void removeRegistrationStateChangeListener(RegistrationStateChangeListener listener)

Removes the specified listener.

Parameters:

listener - the listener to remove.

getSupportedOperationSets

Map<String,OperationSet> getSupportedOperationSets()

Returns an array containing all operation sets supported by the current implementation. When querying this method users must be prepared to receive any subset of the OperationSet-s defined by this service. They MUST ignore any OperationSet-s that they are not aware of and that may be defined by future versions of this service. Such "unknown" OperationSet-s though not encouraged, may also be defined by service implementors.

Returns:

a Map containing instances of all supported operation sets mapped against their class names (e.g. OperationSetPresence.class.getName() associated with a OperationSetPresence instance).

getSupportedOperationSetClasses

Collection<Class<? extends OperationSet>> getSupportedOperationSetClasses()

Returns a collection containing all operation sets classes supported by the current implementation. When querying this method users must be prepared to receive any subset of the OperationSet-s defined by this service. They MUST ignore any OperationSet-s that they are not aware of and that may be defined by future versions of this service. Such "unknown" OperationSet-s though not encouraged, may also be defined by service implementors.

Returns:

a Collection containing instances of all supported operation set classes (e.g. OperationSetPresence.class.

getOperationSet

<T extends OperationSet> T getOperationSet(Class<T> opsetClass)

Returns the operation set corresponding to the specified class or null if this operation set is not supported by the provider implementation.

Type Parameters:

T - the type which extends OperationSet and which is to be retrieved

Parameters:

opsetClass - the Class of the operation set that we're looking for.

Returns:

returns an OperationSet of the specified Class if the underlying implementation supports it or null otherwise.

shutdown

void shutdown()

Makes the service implementation close all open sockets and release any resources that it might have taken and prepare for shutdown/garbage collection.

hashCode

int hashCode()

A hashcode allowing usage of protocol providers as keys in Hashtables.

Overrides:

hashCode in class Object

Returns:

an int that may be used when storing protocol providers as hashtable keys.

getAccountID

AccountID getAccountID()

Returns the AccountID that uniquely identifies the account represented by this instance of the ProtocolProviderService.

Returns:

the id of the account represented by this provider.

isSignalingTransportSecure

boolean isSignalingTransportSecure()

Indicate if the signaling transport of this protocol instance uses a secure (e.g. via TLS) connection.

Returns:

True when the connection is secured, false otherwise.

getTransportProtocol

TransportProtocol getTransportProtocol()

Returns the "transport" protocol of this instance used to carry the control channel for the current protocol service.

Returns:

The "transport" protocol of this instance: UDP, TCP, TLS or UNKNOWN.