ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/cvsroot/Net-XMPP2/lib/Net/XMPP2/IM/Contact.pm
Revision: 1.7
Committed: Mon Jun 25 07:56:52 2007 UTC (19 years, 5 months ago) by elmex
Branch: MAIN
Changes since 1.6: +7 -2 lines
Log Message:
sime fixes and changes

File Contents

# User Rev Content
1 elmex 1.1 package Net::XMPP2::IM::Contact;
2     use strict;
3 elmex 1.6 use Net::XMPP2::Util qw/split_jid/;
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 elmex 1.5 =head2 send_subscribed ()
119    
120     This method accepts a contact's subscription request.
121    
122     =cut
123    
124     sub send_subscribed {
125     my ($self) = @_;
126     $self->{connection}->send_presence ('subscribed', undef, to => $self->jid);
127     }
128    
129 elmex 1.3 =head2 send_unsubscribe ()
130    
131     This method sends this contact a unsubscription request.
132    
133     =cut
134    
135     sub send_unsubscribe {
136     my ($self) = @_;
137     $self->{connection}->send_presence ('unsubscribe', undef, to => $self->jid);
138     }
139    
140 elmex 1.5 =head2 send_unsubscribed ()
141    
142     This method sends this contact a unsubscription request which unsubscribes
143     ones own presence from him (he wont get any further presence from us).
144    
145     =cut
146    
147     sub send_unsubscribed {
148     my ($self) = @_;
149     $self->{connection}->send_presence ('unsubscribed', undef, to => $self->jid);
150     }
151    
152    
153 elmex 1.3 =head2 update ($item)
154    
155     This method wants a L<Net::XMPP2::Node> in C<$item> which
156     should be a roster item received from the server. The method will
157     update the contact accordingly and return it self.
158    
159     =cut
160    
161     sub update {
162     my ($self, $item) = @_;
163    
164     my ($jid, $name, $subscription, $ask) =
165     (
166     $item->attr ('jid'),
167     $item->attr ('name'),
168     $item->attr ('subscription'),
169     $item->attr ('ask')
170     );
171    
172     $self->{name} = $name;
173     $self->{subscription} = $subscription;
174     $self->{groups} = [ map { $_->text } $item->find_all ([qw/roster group/]) ];
175     $self->{ask} = $ask;
176    
177 elmex 1.2 $self
178 elmex 1.1 }
179    
180 elmex 1.3 =head2 update_presence ($presence)
181    
182     This method updates the presence of contacts on the roster.
183     C<$presence> must be a L<Net::XMPP2::Node> object and should be
184     a presence packet.
185    
186     =cut
187    
188     sub update_presence {
189     my ($self, $node) = @_;
190    
191     my $type = $node->attr ('type');
192     my $jid = $node->attr ('from');
193     # XXX: should check whether C<$jid> is nice JID.
194    
195     $self->touch_presence ($jid);
196    
197     my $old;
198     my $new;
199     if ($type eq 'unavailable') {
200     $old = $self->remove_presence ($jid);
201     } else {
202     $old = $self->touch_presence ($jid)->update ($node);
203     $new = $self->touch_presence ($jid);
204     }
205    
206     ($self, $old, $new)
207     }
208    
209 elmex 1.1 sub remove_presence {
210     my ($self, $jid) = @_;
211     my $sjid = Net::XMPP2::Util::stringprep_jid ($jid);
212     delete $self->{presences}->{$sjid}
213     }
214    
215     sub touch_presence {
216     my ($self, $jid) = @_;
217     my $sjid = Net::XMPP2::Util::stringprep_jid ($jid);
218    
219     unless (exists $self->{presences}->{$sjid}) {
220     $self->{presences}->{$sjid} =
221     Net::XMPP2::IM::Presence->new (connection => $self->{connection}, jid => $jid);
222     }
223     $self->{presences}->{$sjid}
224     }
225    
226     =head2 get_presence ($jid)
227    
228     This method returns a presence of this contact if
229     it is available. The return value is an instance of L<Net::XMPP2::IM::Presence>
230     or undef if no such presence exists.
231    
232     =cut
233    
234     sub get_presence {
235     my ($self, $jid) = @_;
236     my $sjid = Net::XMPP2::Util::stringprep_jid ($jid);
237     $self->{presences}->{$sjid}
238     }
239    
240     =head2 get_presences
241    
242     Returns all presences of this contact in form of
243     L<Net::XMPP2::IM::Presence> objects.
244    
245     =cut
246    
247     sub get_presences { values %{$_[0]->{presences}} }
248    
249 elmex 1.6 =head2 get_priority_presence
250    
251     Returns the presence with the highest priority.
252    
253     =cut
254    
255     sub get_priority_presence {
256     my ($self) = @_;
257    
258     my (@pres) =
259     sort {
260     $self->{presences}->{$b}->priority <=> $self->{presences}->{$a}->priority
261     } keys %{$self->{presences}};
262    
263     return unless defined $pres[0];
264     $self->{presences}->{$pres[0]}
265     }
266    
267 elmex 1.1 =head2 groups
268    
269     Returns the list of groups (strings) this contact is in.
270    
271     =cut
272    
273     sub groups {
274     @{$_[0]->{groups} || []}
275     }
276    
277     =head2 jid
278    
279     Returns the bare JID of this contact.
280    
281     =cut
282    
283     sub jid {
284     $_[0]->{jid}
285     }
286    
287     =head2 name
288    
289     Returns the (nick)name of this contact.
290    
291     =cut
292    
293     sub name {
294     $_[0]->{name}
295     }
296    
297 elmex 1.2 =head2 is_on_roster ()
298    
299     Returns 1 if this is a contact that is officially on the
300     roster and not just a contact we've received presence information
301     for.
302    
303     =cut
304    
305     sub is_on_roster {
306     my ($self) = @_;
307     $self->{subscription} && $self->{subscription} ne ''
308     }
309    
310 elmex 1.1 =head2 subscription
311    
312     Returns the subscription state of this contact, which
313     can be one of:
314    
315     'none', 'to', 'from', 'both'
316    
317 elmex 1.3 If the contact isn't on the roster anymore this method
318     returns:
319    
320     'remove'
321    
322 elmex 1.1 =cut
323    
324     sub subscription {
325     $_[0]->{subscription}
326     }
327    
328 elmex 1.3 =head2 subscription_pending
329    
330     Returns true if this contact has a pending subscription.
331     That means: the contact has to aknowledge the subscription.
332    
333     =cut
334    
335     sub subscription_pending {
336     my ($self) = @_;
337     $self->{ask}
338     }
339    
340 elmex 1.6 =head2 nickname
341    
342     Returns the nickname of this contact.
343    
344     =cut
345    
346     sub nickname {
347     my ($self) = @_;
348 elmex 1.7 my $n = $self->name;
349    
350     if ($n eq '') {
351     my ($user) = split_jid $self->jid;
352     $n = $user;
353     }
354     $n
355 elmex 1.6 }
356    
357 elmex 1.1 sub make_message {
358     my ($self) = @_;
359     Net::XMPP2::IM::Message->new (
360     connection => $self->{connection},
361     to => $self->jid
362     );
363     }
364    
365     sub debug_dump {
366     my ($self) = @_;
367     printf "- %-30s [%-20s] (%s)\n",
368     $self->jid,
369     $self->name || '',
370     $self->subscription;
371    
372     for ($self->get_presences) {
373     $_->debug_dump;
374     }
375     }
376    
377 elmex 1.4 =head1 AUTHOR
378    
379     Robin Redeker, C<< <elmex at ta-sa.org> >>
380    
381     =head1 COPYRIGHT & LICENSE
382    
383     Copyright 2007 Robin Redeker, all rights reserved.
384    
385     This program is free software; you can redistribute it and/or modify it
386     under the same terms as Perl itself.
387    
388     =cut
389    
390     1; # End of Net::XMPP2::Contact