ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/cvsroot/Net-XMPP2/lib/Net/XMPP2/IM/Contact.pm
Revision: 1.5
Committed: Sun Jun 24 10:41:58 2007 UTC (19 years, 5 months ago) by elmex
Branch: MAIN
Changes since 1.4: +24 -0 lines
Log Message:
finished subscription implementation and also added the possibility
of forwarding all events of an object to some other object
and forwarded all events from a IM::Connection to the Client.

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 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     =head2 groups
250    
251     Returns the list of groups (strings) this contact is in.
252    
253     =cut
254    
255     sub groups {
256     @{$_[0]->{groups} || []}
257     }
258    
259     =head2 jid
260    
261     Returns the bare JID of this contact.
262    
263     =cut
264    
265     sub jid {
266     $_[0]->{jid}
267     }
268    
269     =head2 name
270    
271     Returns the (nick)name of this contact.
272    
273     =cut
274    
275     sub name {
276     $_[0]->{name}
277     }
278    
279 elmex 1.2 =head2 is_on_roster ()
280    
281     Returns 1 if this is a contact that is officially on the
282     roster and not just a contact we've received presence information
283     for.
284    
285     =cut
286    
287     sub is_on_roster {
288     my ($self) = @_;
289     $self->{subscription} && $self->{subscription} ne ''
290     }
291    
292 elmex 1.1 =head2 subscription
293    
294     Returns the subscription state of this contact, which
295     can be one of:
296    
297     'none', 'to', 'from', 'both'
298    
299 elmex 1.3 If the contact isn't on the roster anymore this method
300     returns:
301    
302     'remove'
303    
304 elmex 1.1 =cut
305    
306     sub subscription {
307     $_[0]->{subscription}
308     }
309    
310 elmex 1.3 =head2 subscription_pending
311    
312     Returns true if this contact has a pending subscription.
313     That means: the contact has to aknowledge the subscription.
314    
315     =cut
316    
317     sub subscription_pending {
318     my ($self) = @_;
319     $self->{ask}
320     }
321    
322 elmex 1.1 sub make_message {
323     my ($self) = @_;
324     Net::XMPP2::IM::Message->new (
325     connection => $self->{connection},
326     to => $self->jid
327     );
328     }
329    
330     sub debug_dump {
331     my ($self) = @_;
332     printf "- %-30s [%-20s] (%s)\n",
333     $self->jid,
334     $self->name || '',
335     $self->subscription;
336    
337     for ($self->get_presences) {
338     $_->debug_dump;
339     }
340     }
341    
342 elmex 1.4 =head1 AUTHOR
343    
344     Robin Redeker, C<< <elmex at ta-sa.org> >>
345    
346     =head1 COPYRIGHT & LICENSE
347    
348     Copyright 2007 Robin Redeker, all rights reserved.
349    
350     This program is free software; you can redistribute it and/or modify it
351     under the same terms as Perl itself.
352    
353     =cut
354    
355     1; # End of Net::XMPP2::Contact