Net::XMPP::Protocol - phpMan

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 = Net::XMPP::Client->new();                  # 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 AT 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 AT jabber.org");

        $Con->Subscription(type=>"unsubscribe",
                           to=>"bob AT jabber.org");

        $Con->Subscription(type=>"subscribed",
                           to=>"bob AT jabber.org");

        $Con->Subscription(type=>"unsubscribed",
                           to=>"bob AT 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 AT 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 AT 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
          SetErrorCode(string)

        set a useful error message before you return an undef to the caller.

    SetCallBacks
          SetCallBacks(message=>function,
                         presence=>function,
                         iq=>function,
                         send=>function,
                         receive=>function,
                         update=>function)

        sets the callback functions for the top level tags listed. The
        available tags to look for are <message/>, <presence/>, and <iq/>.
        If a packet is received 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
          SetPresenceCallBacks(type=>function etc...)

        sets the callback functions for 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
            SetMessageCallBacks(type=>function, etc...)

        sets the callback functions for 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
          SetIQCallBacks(namespace=>{
                             get=>function,
                             set=>function,
                             result=>function
                           },
                           etc...)

        sets the callback functions for the specified namespace. The
        function takes namespaces as the main key, and lets you specify a
        function for each type of packet 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
          SetXPathCallBacks(xpath=>function, etc...)

        registers a callback function 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
         RemoveXPathCallBacks(xpath=>function, etc...)

        unregisters a callback function for each xpath specified.

    SetDirectXPathCallBacks
         SetDirectXPathCallBacks(xpath=>function, etc...)

        registers a callback function 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
          RemoveDirectXPathCallBacks(xpath=>function, etc...)

        unregisters a callback function for each xpath specified.

    Process
            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
            Send(object, ignoreActivity)
            Send(string, ignoreActivity)

        takes either a Net::XMPP::xxxxx object or an XML string as an
        argument and sends it to the server. If you set ignoreActivty to 1,
        then the XML::Stream module will not record this packet as couting
        towards user activity.

  ID Functions
    SendWithID
            SendWithID(object)
            SendWithID(string)

        takes either a Net::XMPP::xxxxx object or an XML string as an
        argument, adds the next available ID number and sends that packet to
        the server. Returns the ID number assigned.

    SendAndReceiveWithID
            SendAndReceiveWithID(object, timeout)
            SendAndReceiveWithID(string, timeout)

        uses SendWithID and WaitForID to provide a complete way to send and
        receive packets with IDs. Can take 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
         ReceivedID(integer)

        returns 1 if a packet has been received with specified ID, 0
        otherwise.

    GetID
            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
          WaitForID(integer, timeout)

        blocks until a packet with the ID is received. 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
            AddNamespace(ns=>string,
                         tag=>string,
                         xpath=>hash)

        This function is very complex. It is a little too complex to 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
            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
          PresenceSend()
          PresenceSend(hash, signature=>string)

        No arguments will send an empty Presence to the server to tell it
        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
         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
         PresenceDB()

        Tell the object to initialize the callbacks to automatically
        populate the Presence DB.

    PresenceDBParse
          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
          PresenceDBDelete(string|Net::XMPP::JID)

        delete thes JID entry from the DB.

    PresenceDBClear
         PresenceDBClear()

        delete all entries in the database.

    PresenceDBQuery
          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
          PresenceDBResources(string|Net::XMPP::JID)

        returns an array of resources in order from highest priority to
        lowest.

  IQ Functions
  Auth Functions
    AuthSend
            AuthSend(username=>string,
                     password=>string,
                     resource=>string)

        takes all of the information and builds a Net::XMPP::IQ::Auth
        packet. 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
         RegisterRequest(to=>string,  timeout=>int)
         RegisterRequest()

        send an <iq/> request to the specified server/transport, if not
        specified it 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
          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
            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
            RosterParse(IQ object)

        returns a hash that contains the roster parsed into the following
        data structure:

          $roster{'bob AT jabber.org'}->{name}
                              - Name you stored in the roster

          $roster{'bob AT jabber.org'}->{subscription}
                              - Subscription status
                                (to, from, both, none)

          $roster{'bob AT jabber.org'}->{ask}
                              - The ask status from this user
                                (subscribe, unsubscribe)

          $roster{'bob AT jabber.org'}->{groups}
                              - Array of groups that
                                bob AT jabber.org is in

    RosterGet
          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
          RosterRequest()

        sends an empty Net::XMPP::IQ::Roster tag to the server so the server
        will send the Roster to the client.

    RosterAdd
            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
         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
            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
            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
          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
          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
         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
          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
            RosterDBGroupExists(group)

        return 1 if the group is a group in the roster DB, undef otherwise.

    RosterDBGroupJIDs
            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
          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
          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
    Originally authored by Ryan Eatmon.

    Previously maintained by Eric Hacker.

    Currently maintained by Darian Anthony Patrick.

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