NAME

Net::XMPP3::Protocol - XMPP Protocol Module

SYNOPSIS


            
              
              Net::XMPP3::Protocol is a module that provides a developer easy
access to the XMPP Instant Messaging protocol.  It provides high
level functions to the Net::XMPP3 Client object.  These functions are
inherited by that modules.

DESCRIPTION


            
              
              Protocol.pm seeks to provide enough high level APIs and automation of
the low level APIs that writing a XMPP Client in Perl is trivial.  For
those that wish to work with the low level you can do that too, but
those functions are covered in the documentation for each module.
Net::XMPP3::Protocol provides functions to login, send and receive
messages, set personal information, create a new user account, manage
the roster, and disconnect.  You can use all or none of the functions,
there is no requirement.
For more information on how the details for how Net::XMPP3 is written
please see the help for Net::XMPP3 itself.
For more information on writing a Client see Net::XMPP3::Client.

Modes


            
              
              Several of the functions take a mode argument that let you specify how
the function should behave:
  block - send the packet with an ID, and then block until an answer
          comes back.  You can optionally specify a timeout so that
          you do not block forever.
  nonblock - send the packet with an ID, but then return that id and
             control to the master program.  Net::XMPP3 is still
             tracking this packet, so you must use the CheckID function
             to tell when it comes in.  (This might not be very
             useful...)
  passthru - send the packet with an ID, but do NOT register it with
             Net::XMPP3, then return the ID.  This is useful when
             combined with the XPath function because you can register
             a one shot function tied to the id you get back.

Basic Functions


            
              
              use Net::XMPP3 qw( Client );
$Con = new Net::XMPP3::Client();                  # From
$status = $Con->Connect(hostname=>"jabber.org"); # Net::XMPP3::Client
$Con->SetCallBacks(send=>\&sendCallBack,
                   receive=>\&receiveCallBack,
                   message=>\&messageCallBack,
                   iq=>\&handleTheIQTag);
$Con->SetMessageCallBacks(normal=>\&messageNormalCB,
                          chat=>\&messageChatCB);
$Con->SetPresenceCallBacks(available=>\&presenceAvailableCB,
                           unavailable=>\&presenceUnavailableCB);
$Con->SetIQCallBacks("custom-namespace"=>
                                         {
                                             get=>\&iqCustomGetCB,
                                             set=>\&iqCustomSetCB,
                                             result=>\&iqCustomResultCB,
                                         },
                                         etc...
                                        );
$Con->SetXPathCallBacks("/message[@type='chat']"=>&messageChatCB,
                        "/message[@type='chat']"=>&otherMessageChatCB,
                        ...
                       );
$Con->RemoveXPathCallBacks("/message[@type='chat']"=>&otherMessageChatCB);
$Con->SetDirectXPathCallBacks("/anything"=>&anythingCB,
                              "/anotherthing[@foo='bar']"=>&anotherthingFooBarCB,
                              ...
                             );
$Con->RemoveDirectXPathCallBacks("/message[@type='chat']"=>&otherMessageChatCB);
$error = $Con->GetErrorCode();
$Con->SetErrorCode("Timeout limit reached");
$status = $Con->Process();
$status = $Con->Process(5);
$Con->Send($object);
$Con->Send("<tag>XML</tag>");
$Con->Send($object,1);
$Con->Send("<tag>XML</tag>",1);
$Con->Disconnect();

ID Functions


            
              
              $id         = $Con->SendWithID($sendObj);
$id         = $Con->SendWithID("<tag>XML</tag>");
$receiveObj = $Con->SendAndReceiveWithID($sendObj);
$receiveObj = $Con->SendAndReceiveWithID($sendObj,
                                         10);
$receiveObj = $Con->SendAndReceiveWithID("<tag>XML</tag>");
$receiveObj = $Con->SendAndReceiveWithID("<tag>XML</tag>",
                                         5);
$yesno      = $Con->ReceivedID($id);
$receiveObj = $Con->GetID($id);
$receiveObj = $Con->WaitForID($id);
$receiveObj = $Con->WaitForID($id,
                              20);

Namespace Functions


            
              
              $Con->AddNamespace(ns=>"foo:bar",
                   tag=>"myfoo",
                   xpath=>{Foo=>{ path=> "foo/text()" },
                           Bar=>{ path=> "bar/text()" },
                           FooBar=>{ type=> "master" },
                          }
                  );

Message Functions


            
              
              $Con->MessageSend(to=>"bob@jabber.org",
                  subject=>"Lunch",
                  body=>"Let's go grab some...\n",
                  thread=>"ABC123",
                  priority=>10);

Presence Functions


            
              
              $Con->PresenceSend();
$Con->PresenceSend(type=>"unavailable");
$Con->PresenceSend(show=>"away");
$Con->PresenceSend(signature=>...signature...);

Subscription Functions


            
              
              $Con->Subscription(type=>"subscribe",
                   to=>"bob@jabber.org");
$Con->Subscription(type=>"unsubscribe",
                   to=>"bob@jabber.org");
$Con->Subscription(type=>"subscribed",
                   to=>"bob@jabber.org");
$Con->Subscription(type=>"unsubscribed",
                   to=>"bob@jabber.org");

Presence DB Functions


            
              
              $Con->PresenceDB();
$Con->PresenceDBParse(Net::XMPP3::Presence);
$Con->PresenceDBDelete("bob\@jabber.org");
$Con->PresenceDBDelete(Net::XMPP3::JID);
$Con->PresenceDBClear();
$presence  = $Con->PresenceDBQuery("bob\@jabber.org");
$presence  = $Con->PresenceDBQuery(Net::XMPP3::JID);
@resources = $Con->PresenceDBResources("bob\@jabber.org");
@resources = $Con->PresenceDBResources(Net::XMPP3::JID);

IQ Functions

Auth Functions


            
              
              @result = $Con->AuthSend();
@result = $Con->AuthSend(username=>"bob",
                         password=>"bobrulez",
                         resource=>"Bob");

Register Functions


            
              
              %hash   = $Con->RegisterRequest();
%hash   = $Con->RegisterRequest(to=>"transport.jabber.org");
%hash   = $Con->RegisterRequest(to=>"transport.jabber.org",
                                timeout=>10);
@result = $Con->RegisterSend(to=>"somewhere",
                             username=>"newuser",
                             resource=>"New User",
                             password=>"imanewbie",
                             email=>"newguy@new.com",
                             key=>"some key");

Roster Functions


            
              
              $Roster = $Con->Roster();
%roster = $Con->RosterParse($iq);
%roster = $Con->RosterGet();
$Con->RosterRequest();
$Con->RosterAdd(jid=>"bob\@jabber.org",
                name=>"Bob");
$Con->RosterRemove(jid=>"bob@jabber.org");

Roster DB Functions


            
              
              $Con->RosterDB();
$Con->RosterDBParse(Net::XMPP3::IQ);
$Con->RosterDBAdd("bob\@jabber.org",
                  name=>"Bob",
                  groups=>["foo"]
                 );
$Con->RosterDBRemove("bob\@jabber.org");
$Con->RosterDBRemove(Net::XMPP3::JID);
$Con->RosterDBClear();
if ($Con->RosterDBExists("bob\@jabber.org")) { ...
if ($Con->RosterDBExists(Net::XMPP3::JID)) { ...
@jids = $Con->RosterDBJIDs();
if ($Con->RosterDBGroupExists("foo")) { ...
@groups = $Con->RosterDBGroups();
@jids = $Con->RosterDBGroupJIDs("foo");
@jids = $Con->RosterDBNonGroupJIDs();
%hash = $Con->RosterDBQuery("bob\@jabber.org");
%hash = $Con->RosterDBQuery(Net::XMPP3::JID);
$value = $Con->RosterDBQuery("bob\@jabber.org","name");
$value = $Con->RosterDBQuery(Net::XMPP3::JID,"groups");

METHODS

Basic Functions


            
              
              GetErrorCode() - returns a string that will hopefully contain some
                 useful information about why a function returned
                 an undef to you.
SetErrorCode(string) - set a useful error message before you return
                       an undef to the caller.
SetCallBacks(message=>function,  - sets the callback functions for
             presence=>function,   the top level tags listed.  The
             iq=>function,         available tags to look for are
             send=>function,       <message/>, <presence/>, and
             receive=>function,    <iq/>.  If a packet is received
             update=>function)     with an ID which is found in the
                                   registerd ID list (see RegisterID
                                   below) then it is not sent to
                                   these functions, instead it
                                   is inserted into a LIST and can
                                   be retrieved by some functions
                                   we will mention later.
                                   send and receive are used to
                                   log what XML is sent and received.
                                   update is used as way to update
                                   your program while waiting for
                                   a packet with an ID to be
                                   returned (useful for GUI apps).
                                   A major change that came with
                                   the last release is that the
                                   session id is passed to the
                                   callback as the first argument.
                                   This was done to facilitate
                                   the Server module.
                                   The next argument depends on
                                   which callback you are talking
                                   about.  message, presence, and iq
                                   all get passed in Net::XMPP3
                                   objects that match those types.
                                   send and receive get passed in
                                   strings.  update gets passed
                                   nothing, not even the session id.
                                   If you set the function to undef,
                                   then the callback is removed from
                                   the list.
SetPresenceCallBacks(type=>function - sets the callback functions for
                     etc...)          the specified presence type.
                                      The function takes types as the
                                      main key, and lets you specify
                                      a function for each type of
                                      packet you can get.
                                        "available"
                                        "unavailable"
                                        "subscribe"
                                        "unsubscribe"
                                        "subscribed"
                                        "unsubscribed"
                                        "probe"
                                        "error"
                                      When it gets a <presence/>
                                      packet it checks the type=''
                                      for a defined callback.  If
                                      there is one then it calls the
                                      function with two arguments:
                                        the session ID, and the
                                        Net::XMPP3::Presence object.
                                      If you set the function to
                                      undef, then the callback is
                                      removed from the list.
                    NOTE: If you use this, which is a cleaner method,
                          then you must *NOT* specify a callback for
                          presence in the SetCallBacks function.
                                      Net::XMPP3 defines a few default
                                      callbacks for various types:
                                      "subscribe" -
                                        replies with subscribed
                                      "unsubscribe" -
                                        replies with unsubscribed
                                      "subscribed" -
                                        replies with subscribed
                                      "unsubscribed" -
                                        replies with unsubscribed
SetMessageCallBacks(type=>function, - sets the callback functions for
                    etc...)           the specified message type. The
                                      function takes types as the
                                      main key, and lets you specify
                                      a function for each type of
                                      packet you can get.
                                       "normal"
                                       "chat"
                                       "groupchat"
                                       "headline"
                                       "error"
                                     When it gets a <message/> packet
                                     it checks the type='' for a
                                     defined callback. If there is
                                     one then it calls the function
                                     with two arguments:
                                       the session ID, and the
                                       Net::XMPP3::Message object.
                                     If you set the function to
                                     undef, then the callback is
                                     removed from the list.
                   NOTE: If you use this, which is a cleaner method,
                         then you must *NOT* specify a callback for
                         message in the SetCallBacks function.
SetIQCallBacks(namespace=>{      - sets the callback functions for
                 get=>function,    the specified namespace. The
                 set=>function,    function takes namespaces as the
                 result=>function  main key, and lets you specify a
               },                  function for each type of packet
               etc...)             you can get.
                                     "get"
                                     "set"
                                     "result"
                                   When it gets an <iq/> packet it
                                   checks the type='' and the
                                   xmlns='' for a defined callback.
                                   If there is one then it calls
                                   the function with two arguments:
                                   the session ID, and the
                                   Net::XMPP3::xxxx object.
                                   If you set the function to undef,
                                   then the callback is removed from
                                   the list.
                   NOTE: If you use this, which is a cleaner method,
                         then you must *NOT* specify a callback for
                         iq in the SetCallBacks function.
SetXPathCallBacks(xpath=>function, - registers a callback function
                  etc...)            for each xpath specified.  If
                                     Net::XMPP3 matches the xpath,
                                     then it calls the function with
                                     two arguments:
                                       the session ID, and the
                                       Net::XMPP3::Message object.
                                     Xpaths are rooted at each
                                     packet:
                                       /message[@type="chat"]
                                       /iq/*[xmlns="jabber:iq:roster"][1]
                                       ...
RemoveXPathCallBacks(xpath=>function, - unregisters a callback
                     etc...)            function for each xpath
                                        specified.
SetDirectXPathCallBacks(xpath=>function, - registers a callback function
                        etc...)            for each xpath specified.  If
                                           Net::XMPP3 matches the xpath,
                                           then it calls the function with
                                           two arguments:
                                             the session ID, and the
                                             XML::Stream::Node object.
                                           Xpaths are rooted at each
                                           packet:
                                             /anything
                                             /anotherthing/foo/[1]
                                             ...
                                           The big difference between this
                                           and regular XPathCallBacks is
                                           the fact that this passes in
                                           the XML directly and not a
                                           Net::XMPP3 based object.
RemoveDirectXPathCallBacks(xpath=>function, - unregisters a callback
                           etc...)            function for each xpath
                                              specified.
Process(integer) - takes the timeout period as an argument.  If no
                   timeout is listed then the function blocks until
                   a packet is received.  Otherwise it waits that
                   number of seconds and then exits so your program
                   can continue doing useful things.  NOTE: This is
                   important for GUIs.  You need to leave time to
                   process GUI commands even if you are waiting for
                   packets.  The following are the possible return
                   values, and what they mean:
                       1   - Status ok, data received.
                       0   - Status ok, no data received.
                     undef - Status not ok, stop processing.
                   IMPORTANT: You need to check the output of every
                   Process.  If you get an undef then the connection
                   died and you should behave accordingly.
Send(object,         - takes either a Net::XMPP3::xxxxx object or
     ignoreActivity)   an XML string as an argument and sends it to
Send(string,           the server.  If you set ignoreActivty to 1,
     ignoreActivity)   then the XML::Stream module will not record
                       this packet as couting towards user activity.
=head2 ID Functions
SendWithID(object) - takes either a Net::XMPP3::xxxxx object or an
SendWithID(string)   XML string as an argument, adds the next
                     available ID number and sends that packet to
                     the server.  Returns the ID number assigned.
SendAndReceiveWithID(object,  - uses SendWithID and WaitForID to
                     timeout)   provide a complete way to send and
SendAndReceiveWithID(string,    receive packets with IDs.  Can take
                     timeout)   either a Net::XMPP3::xxxxx object
                                or an XML string.  Returns the
                                proper Net::XMPP3::xxxxx object
                                based on the type of packet
                                received.  The timeout is passed
                                on to WaitForID, see that function
                                for how the timeout works.
ReceivedID(integer) - returns 1 if a packet has been received with
                      specified ID, 0 otherwise.
GetID(integer) - returns the proper Net::XMPP3::xxxxx object based
                 on the type of packet received with the specified
                 ID.  If the ID has been received the GetID returns
                 0.
WaitForID(integer, - blocks until a packet with the ID is received.
          timeout)   Returns the proper Net::XMPP3::xxxxx object
                     based on the type of packet received.  If the
                     timeout limit is reached then if the packet
                     does come in, it will be discarded.
NOTE:  Only <iq/> officially support ids, so sending a <message/>, or
       <presence/> with an id is a risk.  The server will ignore the
       id tag and pass it through, so both clients must support the
       id tag for these functions to be useful.

Namespace Functions


            
              
              AddNamespace(ns=>string,  - This function is very complex.
             tag=>string,   It is a little too complex to
             xpath=>hash)   discuss within the confines of
                            this small paragraph.  Please
                            refer to the man page for
                            Net::XMPP3::Namespaces for the
                            full documentation on this
                            subject.

Message Functions


            
              
              MessageSend(hash) - takes the hash and passes it to SetMessage in
                    Net::XMPP3::Message (refer there for valid
                    settings).  Then it sends the message to the
                    server.

Presence Functions


            
              
              PresenceSend()                  - no arguments will send an empty
PresenceSend(hash,                Presence to the server to tell it
             signature=>string)   that you are available.  If you
                                  provide a hash, then it will pass
                                  that hash to the SetPresence()
                                  function as defined in the
                                  Net::XMPP3::Presence module.
                                  Optionally, you can specify a
                                  signature and a jabber:x:signed
                                  will be placed in the <presence/>.

Subscription Functions


            
              
              Subscription(hash) - taks the hash and passes it to SetPresence in
                     Net::XMPP3::Presence (refer there for valid
                     settings).  Then it sends the subscription to
                     server.
                     The valid types of subscription are:
                       subscribe    - subscribe to JID's presence
                       unsubscribe  - unsubscribe from JID's presence
                       subscribed   - response to a subscribe
                       unsubscribed - response to an unsubscribe

Presence DB Functions


            
              
              PresenceDB() - Tell the object to initialize the callbacks to
               automatically populate the Presence DB.
PresenceDBParse(Net::XMPP3::Presence) - for every presence that you
                                         receive pass the Presence
                                         object to the DB so that
                                         it can track the resources
                                         and priorities for you.
                                         Returns either the presence
                                         passed in, if it not able
                                         to parsed for the DB, or the
                                         current presence as found by
                                         the PresenceDBQuery
                                         function.
PresenceDBDelete(string|Net::XMPP3::JID) - delete thes JID entry
                                            from the DB.
PresenceDBClear() - delete all entries in the database.
PresenceDBQuery(string|Net::XMPP3::JID) - returns the NX::Presence
                                           that was last received for
                                           the highest priority of
                                           this JID.  You can pass
                                           it a string or a NX::JID
                                           object.
PresenceDBResources(string|Net::XMPP3::JID) - returns an array of
                                               resources in order
                                               from highest priority
                                               to lowest.

IQ Functions

Auth Functions


            
              
              AuthSend(username=>string, - takes all of the information and
         password=>string,   builds a Net::XMPP3::IQ::Auth packet.
         resource=>string)   It then sends that packet to the
                             server with an ID and waits for that
                             ID to return.  Then it looks in
                             resulting packet and determines if
                             authentication was successful for not.
                             The array returned from AuthSend looks
                             like this:
                               [ type , message ]
                             If type is "ok" then authentication
                             was successful, otherwise message
                             contains a little more detail about the
                             error.

IQ::Register Functions


            
              
              RegisterRequest(to=>string,  - send an <iq/> request to the specified
                timeout=>int)  server/transport, if not specified it
RegisterRequest()              sends to the current active server.
                               The function returns a hash that
                               contains the required fields.   Here
                               is an example of the hash:
                               $hash{fields}    - The raw fields from
                                                  the iq:register.
                                                  To be used if there
                                                  is no x:data in the
                                                  packet.
                               $hash{instructions} - How to fill out
                                                     the form.
                               $hash{form}   - The new dynamic forms.
                               In $hash{form}, the fields that are
                               present are the required fields the
                               server needs.
RegisterSend(hash) - takes the contents of the hash and passes it
                     to the SetRegister function in the module
                     Net::XMPP3::Query jabber:iq:register namespace.
                     This function returns an array that looks like
                     this:
                        [ type , message ]
                     If type is "ok" then registration was
                     successful, otherwise message contains a
                     little more detail about the error.

Roster Functions


            
              
              Roster() - returns a Net::XMPP3::Roster object.  This will automatically
           intercept all of the roster and presence packets sent from
           the server and give you an accurate Roster.  For more
           information please read the man page for Net::XMPP3::Roster.
RosterParse(IQ object) - returns a hash that contains the roster
                         parsed into the following data structure:
              $roster{'bob@jabber.org'}->{name}
                                  - Name you stored in the roster
              $roster{'bob@jabber.org'}->{subscription}
                                  - Subscription status
                                    (to, from, both, none)
              $roster{'bob@jabber.org'}->{ask}
                                  - The ask status from this user
                                    (subscribe, unsubscribe)
              $roster{'bob@jabber.org'}->{groups}
                                  - Array of groups that
                                    bob@jabber.org is in
RosterGet() - sends an empty Net::XMPP3::IQ::Roster tag to the
              server so the server will send the Roster to the
              client.  Returns the above hash from RosterParse.
RosterRequest() - sends an empty Net::XMPP3::IQ::Roster tag to the
                  server so the server will send the Roster to the
                  client.
RosterAdd(hash) - sends a packet asking that the jid be
                  added to the roster.  The hash format
                  is defined in the SetItem function
                  in the Net::XMPP3::Query jabber:iq:roster
                  namespace.
RosterRemove(hash) - sends a packet asking that the jid be
                     removed from the roster.  The hash
                     format is defined in the SetItem function
                     in the Net::XMPP3::Query jabber:iq:roster
                     namespace.

Roster DB Functions


            
              
              RosterDB() - Tell the object to initialize the callbacks to
             automatically populate the Roster DB.  If you do this,
             then make sure that you call RosterRequest() instead of
             RosterGet() so that the callbacks can catch it and
             parse it.
RosterDBParse(IQ object) - If you want to manually control the
                           database, then you can pass in all iq
                           packets with jabber:iq:roster queries to
                           this function.
RosterDBAdd(jid,hash) - Add a new JID into the roster DB.  The JID
                        is either a string, or a Net::XMPP3::JID
                        object.  The hash must be the same format as
                        the has returned by RosterParse above, and
                        is the actual hash, not a reference.
RosterDBRemove(jid) - Remove a JID from the roster DB. The JID is
                      either a string, or a Net::XMPP3::JID object.
RosterDBClear() - Remove all JIDs from the roster DB.
RosterDBExists(jid) - return 1 if the JID exists in the roster DB,
                      undef otherwise.  The JID is either a string,
                      or a Net::XMPP3::JID object.
RosterDBJIDs() - returns a list of Net::XMPP3::JID objects that
                 represents all of the JIDs in the DB.
RosterDBGroups() - returns the complete list of roster groups in the
                   roster.
RosterDBGroupExists(group) - return 1 if the group is a group in the
                             roster DB, undef otherwise.
RosterDBGroupJIDs(group) - returns a list of Net::XMPP3::JID objects
                           that represents all of the JIDs in the
                           specified roster group.
RosterDBNonGroupJIDs() - returns a list of Net::XMPP3::JID objects
                         that represents all of the JIDs not in a
                         roster group.
RosterDBQuery(jid) - returns a hash containing the data from the
                     roster DB for the specified JID.  The JID is
                     either a string, or a Net::XMPP3::JID object.
                     The hash format the same as in RosterParse
                     above.
RosterDBQuery(jid,key) - returns the entry from the above hash for
                         the given key.  The available keys are:
                           name, ask, subsrcription and groups
                         The JID is either a string, or a
                         Net::XMPP3::JID object.

AUTHOR

Ryan Eatmon

COPYRIGHT

This module is free software, you can redistribute it and/or modify it under the LGPL.

To install Net::XMPP3, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Net::XMPP3

CPAN shell

perl -MCPAN -e shell
install Net::XMPP3

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

Modes

Basic Functions

ID Functions

Namespace Functions

Message Functions

Presence Functions

Subscription Functions

Presence DB Functions

IQ Functions

Auth Functions

Register Functions

Roster Functions

Roster DB Functions

METHODS

Basic Functions

Namespace Functions

Message Functions

Presence Functions

Subscription Functions

Presence DB Functions

IQ Functions

Auth Functions

IQ::Register Functions

Roster Functions

Roster DB Functions

AUTHOR

COPYRIGHT

Module Install Instructions