Net::XMPP::Protocol(3)

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
                                       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::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.