blob: 7cc896cac6390d71f47395094b57c9b7cf527abe (
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
|
/*
* SIP Communicator, 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;
/**
* 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 suppord 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 suppord persistent
* presence.
*/
public ContactGroup getParentContactGroup();
/**
* Returns a reference to the protocol provider that created the contact.
* @return a refererence 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();
}
|
