ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/cvsroot/Net-XMPP2/lib/Net/XMPP2/IM/Contact.pm
Revision: 1.3
Committed: Sun Apr 22 14:36:52 2007 UTC (19 years, 7 months ago) by elmex
Branch: MAIN
Changes since 1.2: +162 -16 lines
Log Message:
implemented addition/removal/update of roster items and
first functionality for subscription.

File Contents

# User Rev Content
1 elmex 1.1 package Net::XMPP2::IM::Contact;
2     use strict;
3     use Net::XMPP2::Util;
4 elmex 1.3 use Net::XMPP2::Namespaces qw/xmpp_ns/;
5 elmex 1.1 use Net::XMPP2::IM::Presence;
6     use Net::XMPP2::IM::Message;
7    
8     =head1 NAME
9    
10     Net::XMPP2::IM::Contact - A instant messaging roster contact
11    
12     =head1 SYNOPSIS
13    
14     my $con = Net::XMPP2::IM::Connection->new (...);
15     ...
16     my $ro = $con->roster;
17     if (my $c = $ro->get_contact ('test@example.com')) {
18     $c->make_message ()->add_body ("Hello there!")->send;
19     }
20    
21     =head1 DESCRIPTION
22    
23     This module represents a class for contact objects which populate
24     a roster (L<Net::XMPP2::IM::Roster>.
25    
26     You can get an instance of this class only by calling the C<get_contact>
27     function on a roster object.
28    
29     =cut
30    
31    
32     sub new {
33     my $this = shift;
34     my $class = ref($this) || $this;
35     bless { @_ }, $class;
36     }
37    
38 elmex 1.3 =head2 send_update ($cb, %upd)
39    
40     This method updates a contact. If the request is finished
41     it will call C<$cb>. If it resulted in an error the first argument
42     of that callback will be a L<Net::XMPP2::Error::IQ> object.
43    
44     The C<%upd> hash should have one of the following keys and defines
45     what parts of the contact to update:
46    
47     =over 4
48    
49     =item name => $name
50    
51     Updates the name of the contact. C<$name> = '' erases the contact.
52    
53     =item add_group => $groups
54    
55     Addes the contact to the groups in the arrayreference C<$groups>.
56    
57     =item remove_group => $groups
58    
59     Removes the contact from the groups in the arrayreference C<$groups>.
60    
61     =item groups => $groups
62    
63     This sets the groups of the contact. C<$groups> should be an array reference
64     of the groups.
65    
66     =back
67    
68     =cut
69    
70     sub send_update {
71     my ($self, $cb, %upd) = @_;
72    
73     if ($upd{groups}) {
74     $self->{groups} = $upd{groups};
75     }
76     for my $g (@{$upd{add_group} || []}) {
77     push @{$self->{groups}}, $g unless grep { $g eq $_ } $self->groups;
78     }
79     for my $g (@{$upd{remove_group} || []}) {
80     push @{$self->{groups}}, grep { $g ne $_ } $self->groups;
81     }
82    
83     $self->{connection}->send_iq (
84     set => sub {
85     my ($w) = @_;
86     $w->addPrefix (xmpp_ns ('roster'), '');
87     $w->startTag ([xmpp_ns ('roster'), 'query']);
88     $w->startTag ([xmpp_ns ('roster'), 'item'],
89     jid => $self->jid,
90     (defined $upd{name} ? (name => $upd{name}) : ())
91     );
92     for ($self->groups) {
93     $w->startTag ([xmpp_ns ('roster'), 'group']);
94     $w->characters ($_);
95     $w->endTag;
96     }
97     $w->endTag;
98     $w->endTag;
99     },
100     sub {
101     my ($node, $error) = @_;
102     $cb->($error) if $cb
103     }
104     );
105     }
106    
107     =head2 send_subscribe ()
108    
109     This method sends this contact a subscription request.
110    
111     =cut
112    
113     sub send_subscribe {
114     my ($self) = @_;
115     $self->{connection}->send_presence ('subscribe', undef, to => $self->jid);
116     }
117    
118     =head2 send_unsubscribe ()
119    
120     This method sends this contact a unsubscription request.
121    
122     =cut
123    
124     sub send_unsubscribe {
125     my ($self) = @_;
126     $self->{connection}->send_presence ('unsubscribe', undef, to => $self->jid);
127     }
128    
129     =head2 update ($item)
130    
131     This method wants a L<Net::XMPP2::Node> in C<$item> which
132     should be a roster item received from the server. The method will
133     update the contact accordingly and return it self.
134    
135     =cut
136    
137     sub update {
138     my ($self, $item) = @_;
139    
140     my ($jid, $name, $subscription, $ask) =
141     (
142     $item->attr ('jid'),
143     $item->attr ('name'),
144     $item->attr ('subscription'),
145     $item->attr ('ask')
146     );
147    
148     $self->{name} = $name;
149     $self->{subscription} = $subscription;
150     $self->{groups} = [ map { $_->text } $item->find_all ([qw/roster group/]) ];
151     $self->{ask} = $ask;
152    
153 elmex 1.2 $self
154 elmex 1.1 }
155    
156 elmex 1.3 =head2 update_presence ($presence)
157    
158     This method updates the presence of contacts on the roster.
159     C<$presence> must be a L<Net::XMPP2::Node> object and should be
160     a presence packet.
161    
162     =cut
163    
164     sub update_presence {
165     my ($self, $node) = @_;
166    
167     my $type = $node->attr ('type');
168     my $jid = $node->attr ('from');
169     # XXX: should check whether C<$jid> is nice JID.
170    
171     $self->touch_presence ($jid);
172    
173     my $old;
174     my $new;
175     if ($type eq 'unavailable') {
176     $old = $self->remove_presence ($jid);
177     } else {
178     $old = $self->touch_presence ($jid)->update ($node);
179     $new = $self->touch_presence ($jid);
180     }
181    
182     ($self, $old, $new)
183     }
184    
185 elmex 1.1 sub remove_presence {
186     my ($self, $jid) = @_;
187     my $sjid = Net::XMPP2::Util::stringprep_jid ($jid);
188     delete $self->{presences}->{$sjid}
189     }
190    
191     sub touch_presence {
192     my ($self, $jid) = @_;
193     my $sjid = Net::XMPP2::Util::stringprep_jid ($jid);
194    
195     unless (exists $self->{presences}->{$sjid}) {
196     $self->{presences}->{$sjid} =
197     Net::XMPP2::IM::Presence->new (connection => $self->{connection}, jid => $jid);
198     }
199     $self->{presences}->{$sjid}
200     }
201    
202     =head2 get_presence ($jid)
203    
204     This method returns a presence of this contact if
205     it is available. The return value is an instance of L<Net::XMPP2::IM::Presence>
206     or undef if no such presence exists.
207    
208     =cut
209    
210     sub get_presence {
211     my ($self, $jid) = @_;
212     my $sjid = Net::XMPP2::Util::stringprep_jid ($jid);
213     $self->{presences}->{$sjid}
214     }
215    
216     =head2 get_presences
217    
218     Returns all presences of this contact in form of
219     L<Net::XMPP2::IM::Presence> objects.
220    
221     =cut
222    
223     sub get_presences { values %{$_[0]->{presences}} }
224    
225     =head2 groups
226    
227     Returns the list of groups (strings) this contact is in.
228    
229     =cut
230    
231     sub groups {
232     @{$_[0]->{groups} || []}
233     }
234    
235     =head2 jid
236    
237     Returns the bare JID of this contact.
238    
239     =cut
240    
241     sub jid {
242     $_[0]->{jid}
243     }
244    
245     =head2 name
246    
247     Returns the (nick)name of this contact.
248    
249     =cut
250    
251     sub name {
252     $_[0]->{name}
253     }
254    
255 elmex 1.2 =head2 is_on_roster ()
256    
257     Returns 1 if this is a contact that is officially on the
258     roster and not just a contact we've received presence information
259     for.
260    
261     =cut
262    
263     sub is_on_roster {
264     my ($self) = @_;
265     $self->{subscription} && $self->{subscription} ne ''
266     }
267    
268 elmex 1.1 =head2 subscription
269    
270     Returns the subscription state of this contact, which
271     can be one of:
272    
273     'none', 'to', 'from', 'both'
274    
275 elmex 1.3 If the contact isn't on the roster anymore this method
276     returns:
277    
278     'remove'
279    
280 elmex 1.1 =cut
281    
282     sub subscription {
283     $_[0]->{subscription}
284     }
285    
286 elmex 1.3 =head2 subscription_pending
287    
288     Returns true if this contact has a pending subscription.
289     That means: the contact has to aknowledge the subscription.
290    
291     =cut
292    
293     sub subscription_pending {
294     my ($self) = @_;
295     $self->{ask}
296     }
297    
298 elmex 1.1 sub make_message {
299     my ($self) = @_;
300     Net::XMPP2::IM::Message->new (
301     connection => $self->{connection},
302     to => $self->jid
303     );
304     }
305    
306     sub debug_dump {
307     my ($self) = @_;
308     printf "- %-30s [%-20s] (%s)\n",
309     $self->jid,
310     $self->name || '',
311     $self->subscription;
312    
313     for ($self->get_presences) {
314     $_->debug_dump;
315     }
316     }
317    
318     1;