blob: 96915cdf09920d1a30781bfd1ac40369565c471e (
plain)
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
|
/*
* 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.*;
/**
* This class represents the notion of a Contact or Buddy, that is widely used
* in instant messaging today. From a protocol point of view, a contact is
* generally considered to be another user of the service that proposes the
* protocol. Instances of Contact could be used for delivery of presence
* notifications or when addressing instant messages.
*
* @author Emil Ivov
*/
public interface Contact
{
/**
* Returns a String that can be used for identifying the contact. The
* exact contents of the string depends on the protocol. In the case of
* SIP, for example, that would be the SIP uri (e.g. sip:alice@biloxi.com)
* in the case of icq - a UIN (12345653) and for AIM a screenname (mysname).
* Jabber (and hence Google) would be having e-mail like addresses.
* @return a String id representing and uniquely identifying the contact.
*/
public String getAddress();
/**
* Returns a String that could be used by any user interacting modules for
* referring to this contact. An alias is not necessarily unique but is
* often more human readable than an address (or id).
* @return a String that can be used for referring to this contact when
* interacting with the user.
*/
public String getDisplayName();
/**
* Returns a byte array containing an image (most often a photo or an avatar)
* that the contact uses as a representation.
* @return byte[] an image representing the contact.
*/
public byte[] getImage();
/**
* Returns the status of the contact as per the last status update we've
* received for it. Note that this method is not to perform any network
* operations and will simply return the status received in the last
* status update message. If you want a reliable way of retrieving someone's
* status, you should use the <tt>queryContactStatus()</tt> method in
* <tt>OperationSetPresence</tt>.
* @return the PresenceStatus that we've received in the last status update
* pertaining to this contact.
*/
public PresenceStatus getPresenceStatus();
/**
* Returns a reference to the contact group that this contact is currently
* a child of or null if the underlying protocol does not support persistent
* presence.
* @return a reference to the contact group that this contact is currently
* a child of or null if the underlying protocol does not support persistent
* presence.
*/
public ContactGroup getParentContactGroup();
/**
* Returns a reference to the protocol provider that created the contact.
* @return a reference to an instance of the ProtocolProviderService
*/
public ProtocolProviderService getProtocolProvider();
/**
* Determines whether or not this contact is being stored by the server.
* Non persistent contacts are common in the case of simple, non-persistent
* presence operation sets. They could however also be seen in persistent
* presence operation sets when for example we have received an event
* from someone not on our contact list. Non persistent contacts are
* volatile even when coming from a persistent presence op. set. They would
* only exist until the application is closed and will not be there next
* time it is loaded.
* @return true if the contact is persistent and false otherwise.
*/
public boolean isPersistent();
/**
* Determines whether or not this contact has been resolved against the
* server. Unresolved contacts are used when initially loading a contact
* list that has been stored in a local file until the presence operation
* set has managed to retrieve all the contact list from the server and has
* properly mapped contacts to their on-line buddies.
* @return true if the contact has been resolved (mapped against a buddy)
* and false otherwise.
*/
public boolean isResolved();
/**
* Returns a String that can be used to create a unresolved instance of
* this contact. Unresolved contacts are created through the
* createUnresolvedContact() method in the persistent presence operation
* set. The method may also return null if no such data is required and
* the contact address is sufficient for restoring the contact.
* <p>
* @return A <tt>String</tt> that could be used to create a unresolved
* instance of this contact during a next run of the application, before
* establishing network connectivity or null if no such data is required.
*/
public String getPersistentData();
/**
* Return the current status message of this contact.
*
* @return the current status message
*/
public String getStatusMessage();
/**
* Indicates if this contact supports resources.
*
* @return <tt>true</tt> if this contact supports resources, <tt>false</tt>
* otherwise
*/
public boolean supportResources();
/**
* Returns a collection of resources supported by this contact or null
* if it doesn't support resources.
*
* @return a collection of resources supported by this contact or null
* if it doesn't support resources
*/
public Collection<ContactResource> getResources();
/**
* Adds the given <tt>ContactResourceListener</tt> to listen for events
* related to contact resources changes.
*
* @param l the <tt>ContactResourceListener</tt> to add
*/
public void addResourceListener(ContactResourceListener l);
/**
* Removes the given <tt>ContactResourceListener</tt> listening for events
* related to contact resources changes.
*
* @param l the <tt>ContactResourceListener</tt> to rmove
*/
public void removeResourceListener(ContactResourceListener l);
/**
* Returns the persistent contact address.
*
* @return the address of the contact.
*/
public String getPersistableAddress();
}
|
