phpman > perldoc > Net::XMPP::Protocol(3pm)

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.