AnyEvent::XMPP::IM::Contact - Instant messaging roster contact

       Robin Redeker, "<elmex at ta-sa.org>", JID: "<elmex at jabber.org>"

       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.

perl v5.38.2                                       2024-08-03                   AnyEvent::XMPP::IM::Contact(3pm)

       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.

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.

       AnyEvent::XMPP::IM::Contact - Instant messaging roster contact

          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;
          }