NAME¶
AnyEvent::XMPP::IM::Contact - Instant messaging roster contact
SYNOPSIS¶
my $con = AnyEvent::XMPP::IM::Connection->new (...);
...
my $ro = $con->roster;
if (my $c = $ro->get_contact ('test@example.com')) {
$c->make_message ()->add_body ("Hello there!")->send;
}
DESCRIPTION¶
This module represents a class for contact objects which populate a roster
(AnyEvent::XMPP::IM::Roster.
There are two types of 'contacts' that are managed by this class. The first are
contacts that are on the users roster, and the second are contacts that are
not on the users roster.
To find our whether this is a contact which is actually available as roster item
in the users roster, you should consult the "is_on_roster" method
(see below).
Another special kind of contact is the contact which stands for ourself and is
mostly only used for keeping track of our own presences and resources. But
note that even if the "is_me" method returns true, the
"is_on_roster" method might also return a true value, in case we
have a roster item of ourself on the roster (which might happen in rare cases
:).
You can get an instance of this class only by calling the
"get_contact" function on a roster object.
METHODS¶
- send_update ($cb, %upd)
- This method updates a contact. If the request is finished
it will call $cb. If it resulted in an error the first argument of that
callback will be a AnyEvent::XMPP::Error::IQ object.
The %upd hash should have one of the following keys and defines what parts
of the contact to update:
- name => $name
- Updates the name of the contact. $name = '' erases the
contact.
- add_group => $groups
- Adds the contact to the groups in the array reference
$groups.
- remove_group => $groups
- Removes the contact from the groups in the array reference
$groups.
- groups => $groups
- This sets the groups of the contact. $groups should be an
array reference of the groups.
- send_subscribe ()
- This method sends this contact a subscription request.
- send_subscribed ()
- This method accepts a contact's subscription request.
- send_unsubscribe ()
- This method sends this contact a unsubscription
request.
- send_unsubscribed ()
- This method sends this contact a unsubscription request
which unsubscribes ones own presence from him (he wont get any further
presence from us).
- update ($item)
- This method wants a AnyEvent::XMPP::Node in $item which
should be a roster item received from the server. The method will update
the contact accordingly and return it self.
- update_presence ($presence)
- This method updates the presence of contacts on the roster.
$presence must be a AnyEvent::XMPP::Node object and should be a presence
packet.
- get_presence ($jid)
- This method returns a presence of this contact if it is
available. The return value is an instance of AnyEvent::XMPP::IM::Presence
or undef if no such presence exists.
- get_presences
- Returns all presences of this contact in form of
AnyEvent::XMPP::IM::Presence objects.
- get_priority_presence
- Returns the presence with the highest priority.
- groups
- Returns the list of groups (strings) this contact is
in.
- jid
- Returns the bare JID of this contact.
- name
- Returns the (nick)name of this contact.
- is_on_roster ()
- Returns 1 if this is a contact that is officially on the
roster and not just a contact we've received presence information
for.
- is_me
- Returns a true value when this contacts stands for ourself
and is only used for receiving presences of our own resources.
- subscription
- Returns the subscription state of this contact, which can
be one of:
'none', 'to', 'from', 'both'
If the contact isn't on the roster anymore this method returns:
'remove'
- ask
- Returns 'subscribe' if we asked this contact for
subscription.
- subscription_pending
- Returns true if this contact has a pending subscription.
That means: the contact has to aknowledge the subscription.
- nickname
- Returns the nickname of this contact (or, if none is set in
the roster, it returns the node part of the JID)
- make_message (%args)
- This method returns a AnyEvent::XMPP::IM::Message object
with the to field set to this contacts JID.
%args are further arguments for the message constructor.
AUTHOR¶
Robin Redeker, "<elmex at ta-sa.org>", JID: "<elmex at
jabber.org>"
COPYRIGHT & LICENSE¶
Copyright 2007, 2008 Robin Redeker, all rights reserved.
This program is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.