1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
|
/*
* Jitsi, the OpenSource Java VoIP and Instant Messaging client.
*
* Distributable under LGPL license.
* See terms of license at gnu.org.
*/
package net.java.sip.communicator.service.protocol;
import java.util.*;
import net.java.sip.communicator.service.protocol.event.*;
/**
* 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.
* <p>
* 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.
*<p>
* 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 AccountID
*/
public interface ProtocolProviderService
{
/**
* 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).
*/
public static final String BIND_RETRIES_PROPERTY_NAME
= "net.java.sip.communicator.service.protocol.BIND_RETRIES";
/**
* 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).
*/
public static final int BIND_RETRIES_DEFAULT_VALUE = 50;
/**
* Starts the registration process. Connection details such as
* registration server, user name/number are provided through the
* configuration service through implementation specific properties.
*
* @param 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).
*/
public void register(SecurityAuthority authority)
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).
*/
public void unregister()
throws OperationFailedException;
/**
* Indicates whether or not this provider is registered
* @return true if the provider is currently registered and false otherwise.
*/
public boolean isRegistered();
/**
* Returns the state of the registration of this protocol provider with the
* corresponding registration service.
* @return ProviderRegistrationState
*/
public RegistrationState getRegistrationState();
/**
* 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.
*
* @return a String containing the short name of the protocol this service
* is implementing (most often that would be a name in ProtocolNames).
*/
public String getProtocolName();
/**
* Returns the protocol display name. This is the name that would be used
* by the GUI to display the protocol name.
*
* @return a String containing the display name of the protocol this service
* is implementing
*/
public String getProtocolDisplayName();
/**
* Returns the protocol logo icon.
* @return the protocol logo icon
*/
public ProtocolIcon getProtocolIcon();
/**
* 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.
* @param listener the listener to register.
*/
public void addRegistrationStateChangeListener(
RegistrationStateChangeListener listener);
/**
* Removes the specified listener.
* @param listener the listener to remove.
*/
public void removeRegistrationStateChangeListener(
RegistrationStateChangeListener listener);
/**
* 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.
*
* @return a {@link Map} containing instances of all supported operation
* sets mapped against their class names (e.g.
* <tt>OperationSetPresence.class.getName()</tt> associated with a
* <tt>OperationSetPresence</tt> instance).
*/
public Map<String, OperationSet> getSupportedOperationSets();
/**
* Returns the operation set corresponding to the specified class or
* <tt>null</tt> if this operation set is not supported by the provider
* implementation.
*
* @param <T> the type which extends <tt>OperationSet</tt> and which is to
* be retrieved
* @param opsetClass the <tt>Class</tt> of the operation set that we're
* looking for.
* @return returns an OperationSet of the specified <tt>Class</tt> if the
* underlying implementation supports it or null otherwise.
*/
public <T extends OperationSet> T getOperationSet(Class<T> opsetClass);
/**
* Makes the service implementation close all open sockets and release
* any resources that it might have taken and prepare for shutdown/garbage
* collection.
*/
public void shutdown();
/**
* A hashcode allowing usage of protocol providers as keys in Hashtables.
* @return an int that may be used when storing protocol providers as
* hashtable keys.
*/
public int hashCode();
/**
* Returns the AccountID that uniquely identifies the account represented by
* this instance of the ProtocolProviderService.
* @return the id of the account represented by this provider.
*/
public AccountID getAccountID();
/**
* Indicate if the signaling transport of this protocol instance uses a
* secure (e.g. via TLS) connection.
*
* @return True when the connection is secured, false otherwise.
*/
public boolean isSignalingTransportSecure();
/**
* Returns the "transport" protocol of this instance used to carry the
* control channel for the current protocol service.
*
* @return The "transport" protocol of this instance: UDP, TCP, TLS or
* UNKNOWN.
*/
public TransportProtocol getTransportProtocol();
}
|
