Provided by: libnet-xmpp-perl_1.02-3_all bug

NAME

       Net::XMPP::Protocol - XMPP Protocol Module

SYNOPSIS

         Net::XMPP::Protocol is a module that provides a developer easy
         access to the XMPP Instant Messaging protocol.  It provides high
         level functions to the Net::XMPP 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::XMPP::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::XMPP is written
         please see the help for Net::XMPP itself.

         For more information on writing a Client see Net::XMPP::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::XMPP 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::XMPP, 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::XMPP qw( Client );
           $Con = new Net::XMPP::Client();                  # From
           $status = $Con->Connect(hostname=>"jabber.org"); # Net::XMPP::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::XMPP::Presence);

           $Con->PresenceDBDelete("bob\@jabber.org");
           $Con->PresenceDBDelete(Net::XMPP::JID);

           $Con->PresenceDBClear();

           $presence  = $Con->PresenceDBQuery("bob\@jabber.org");
           $presence  = $Con->PresenceDBQuery(Net::XMPP::JID);

           @resources = $Con->PresenceDBResources("bob\@jabber.org");
           @resources = $Con->PresenceDBResources(Net::XMPP::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::XMPP::IQ);

           $Con->RosterDBAdd("bob\@jabber.org",
                             name=>"Bob",
                             groups=>["foo"]
                            );

           $Con->RosterDBRemove("bob\@jabber.org");
           $Con->RosterDBRemove(Net::XMPP::JID);

           $Con->RosterDBClear();

           if ($Con->RosterDBExists("bob\@jabber.org")) { ...
           if ($Con->RosterDBExists(Net::XMPP::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::XMPP::JID);

           $value = $Con->RosterDBQuery("bob\@jabber.org","name");
           $value = $Con->RosterDBQuery(Net::XMPP::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
                                              registered 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::XMPP
                                              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::XMPP::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::XMPP 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::XMPP::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::XMPP::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::XMPP matches the xpath,
                                                then it calls the function with
                                                two arguments:
                                                  the session ID, and the
                                                  Net::XMPP::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::XMPP 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::XMPP 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::XMPP::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::XMPP::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::XMPP::xxxxx object
                                           or an XML string.  Returns the
                                           proper Net::XMPP::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::XMPP::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::XMPP::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::XMPP::Namespaces for the
                                       full documentation on this
                                       subject.

   Message Functions
           MessageSend(hash) - takes the hash and passes it to SetMessage in
                               Net::XMPP::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::XMPP::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::XMPP::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::XMPP::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::XMPP::JID) - delete thes JID entry
                                                       from the DB.

           PresenceDBClear() - delete all entries in the database.

           PresenceDBQuery(string|Net::XMPP::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::XMPP::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::XMPP::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::XMPP::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::XMPP::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::XMPP::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::XMPP::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::XMPP::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::XMPP::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::XMPP::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::XMPP::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::XMPP::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::XMPP::JID object.

           RosterDBJIDs() - returns a list of Net::XMPP::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::XMPP::JID objects
                                      that represents all of the JIDs in the
                                      specified roster group.

           RosterDBNonGroupJIDs() - returns a list of Net::XMPP::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::XMPP::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::XMPP::JID object.

AUTHOR

       Ryan Eatmon

COPYRIGHT

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