++ed by:

2 non-PAUSE users.

Ryan Eatmon

NAME

Net::Jabber::Protocol - Jabber Protocol Library

SYNOPSIS

  Net::Jabber::Protocol is a module that provides a developer easy
  access to the Jabber Instant Messaging protocol.  It provides high
  level functions to the Net::Jabber Client, Component, and Server
  objects.  These functions are automatically indluded in those modules
  through AUTOLOAD and delegates.

DESCRIPTION

  Protocol.pm seeks to provide enough high level APIs and automation of
  the low level APIs that writing a Jabber Client/Transport 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::Jabber::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::Jabber is written
  please see the help for Net::Jabber itself.

  For more information on writing a Client see Net::Jabber::Client.

  For more information on writing a Transport see Net::Jabber::Transport.

Basic Functions

    use Net::Jabber qw( Client );
    $Con = new Net::Jabber::Client();            # From
    $status = $Con->Connect(name=>"jabber.org"); # Net::Jabber::Client

      or

    use Net::Jabber qw( Component );
    $Con = new Net::Jabber::Component();         #
    $status = $Con->Connect(name=>"jabber.org",  # From
                            secret=>"bob");      # Net::Jabber::Component


    $Con->SetCallBacks(send=>\&sendCallBack,
                       receive=>\&receiveCallBack,
                       message=>\&messageCallBack,
                       iq=>\&handleTheIQTag);

    $error = $Con->GetErrorCode();
    $Con->SetErrorCode("Timeout limit reached");

    $Con->Process();
    $Con->Process(5);

    $Con->Send($object);
    $Con->Send("<tag>XML</tag>");

    $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->DefineNamespace(xmlns=>"foo:bar",
                          type=>"Query",
                          functions=>[{name=>"Foo",
                                       get=>"foo",
                                       set=>["scalar","foo"],
                                       defined=>"foo",
                                       hash=>"child-data"},
                                      {name=>"Bar",
                                       get=>"bar",
                                       set=>["scalar","bar"],
                                       defined=>"bar",
                                       hash=>"child-data"},
                                      {name=>"FooBar",
                                       get=>"__netjabber__:master",
                                       set=>["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();

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->PresenceDBParse(Net::Jabber::Presence);

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

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

    @resources = $Con->PresenceDBResources("bob\@jabber.org");
    @resources = $Con->PresenceDBResources(Net::Jabber::JID);

IQ Functions

IQ::Agents Functions

    %agents = $Con->AgentsGet();
    %agents = $Con->AgentsGet(to=>"transport.jabber.org");

IQ::Auth Functions

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

IQ::Browse Functions

    %hash = $Con->BrowseRequest("jabber.org");

IQ::Browse DB Functions

    $Con->BrowseDBDelete("jabber.org");
    $Con->BrowseDBDelete(Net::Jabber::JID);

    $presence  = $Con->BrowseDBQuery(jid=>"bob\@jabber.org");
    $presence  = $Con->BrowseDBQuery(jid=>Net::Jabber::JID);
    $presence  = $Con->BrowseDBQuery(jid=>"users.jabber.org",
                                     timeout=>10);
    $presence  = $Con->BrowseDBQuery(jid=>"conference.jabber.org",
                                     refresh=>1);

IQ::Last Functions

    $Con->LastQuery();
    $Con->LastQuery(to=>"bob@jabber.org");

    %result = $Con->LastQuery(waitforid=>1);
    %result = $Con->LastQuery(to=>"bob@jabber.org",
                              waitforid=>1);

    $Con->TimeSend(to=>"bob@jabber.org");

IQ::Register Functions

    %hash   = $Con->RegisterRequest();
    %hash   = $Con->RegisterRequest(to=>"transport.jabber.org");

    @result = $Con->RegisterSend(usersname=>"newuser",
                                 resource=>"New User",
                                 password=>"imanewbie",
                                 email=>"newguy@new.com",
                                 key=>"some key");

IQ::Roster Functions

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

IQ::Search Functions

    %fields = $Con->SearchRequest();
    %fields = $Con->SearchRequest(to=>"users.jabber.org");

    $Con->SearchSend(name=>"",
                     first=>"Bob",
                     last=>"",
                     nick=>"bob",
                     email=>"",
                     key=>"som key");

IQ::Time Functions

    $Con->TimeQuery();
    $Con->TimeQuery(to=>"bob@jabber.org");

    %result = $Con->TimeQuery(waitforid=>1);
    %result = $Con->TimeQuery(to=>"bob@jabber.org",
                              waitforid=>1);

    $Con->TimeSend(to=>"bob@jabber.org");

IQ::Version Functions

    $Con->VersionQuery();
    $Con->VersionQuery(to=>"bob@jabber.org");

    %result = $Con->VersionQuery(waitforid=>1);
    %result = $Con->VersionQuery(to=>"bob@jabber.org",
                                 waitforid=>1);

    $Con->VersionSend(to=>"bob@jabber.org",
                      name=>"Net::Jabber",
                      ver=>"1.0a",
                      os=>"Perl");

X Functions

    $Con->SXPMSend(to=>'bob@jabber.org',
                   type=>'chat',
                   boardheight=>400,
                   boardwidth=>400,
                   map=>{ '#'=>'',
                          ' '=>'None',
                          'a'=>'#FFFFFF',
                          'b'=>'#FF0000',
                          ...
                        }
                   data=>"4 .3 . 2 .2  .3 .4 ",
                   datawidth=>5
                  );

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
    SetCallBacks(xdb=>function,        <message/>, <presence/>, and
                 db:verify=>function,  <iq/>.  If a packet is received
                 db:result=>function)  with an ID which is found in the
    SetCallBacks(send=>function,       registerd ID list (see RegisterID
                 receive=>function,    below) then it is not sent to
                 update=>function)     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, iq,
                                       xdb, db:verify, and db:result
                                       all get passed in Net::Jabber
                                       objects that match those types.
                                       send and receive get passed in
                                       strings.  update gets passed
                                       nothing, not even the session id.

    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.

                       IMPORTANT: You need to check the output of every
                       Process.  If you get an undef or "" then the
                       connection died and you should behave accordingly.

    Send(object) - takes either a Net::Jabber::xxxxx object or an XML
    Send(string)   string as an argument and sends it to the server.

ID Functions

    SendWithID(object) - takes either a Net::Jabber::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::Jabber::xxxxx object
                                    or an XML string.  Returns the
                                    proper Net::Jabber::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::Jabber::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::Jabber::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

    DefineNamespace(xmlns=>string,    - This function is very complex.
                    type=>string,       It is a little too complex to
                    functions=>array)   discuss within the confines of
                                        this small paragraph.  Please
                                        refer to the man page for
                                        Net::Jabber::Namespaces for the
                                        full documentation on this
                                        subject.

Message Functions

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

Presence Functions

    PresenceSend() - sends an empty Presence to the server to tell it
                     that you are available

Subscription Functions

    Subscription(hash) - taks the hash and passes it to SetPresence in
                         Net::Jabber::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

    PresenceDBParse(Net::Jabber::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::Jabber::JID) - delete thes JID entry
                                                from the DB.

    PresenceDBQuery(string|Net::Jabber::JID) - returns the NJ::Presence
                                               that was last received for
                                               the highest priority of
                                               this JID.  You can pass
                                               it a string or a NJ::JID
                                               object.

    PresenceDBResources(string|Net::Jabber::JID) - returns an array of
                                                   resources in order
                                                   from highest priority
                                                   to lowest.

IQ Functions

IQ::Agents Functions

    AgentsGet(to=>string, - takes all of the information and
    AgentsGet()             builds a Net::Jabber::IQ::Agents packet.
                            It then sends that packet either to the
                            server, or to the specified transport,
                            with an ID and waits for that ID to return.
                            Then it looks in the resulting packet and
                            builds a hash that contains the values
                            of the agent list.  The hash is layed out
                            like this:  (NOTE: the jid is the key to
                            distinguish the various agents)

                              $hash{<JID>}->{order} = 4
                                          ->{name} = "ICQ Transport"
                                          ->{transport} = "ICQ #"
                                          ->{description} = "ICQ..blah.."
                                          ->{service} = "icq"
                                          ->{register} = 1
                                          ->{search} = 1
                                        etc...

                            The order field determines the order that
                            it came from the server in... in case you
                            care.  For more info on the valid fields
                            see the Net::Jabber::Query jabber:iq:agent
                            namespace.

IQ::Auth Functions

    AuthSend(username=>string, - takes all of the information and
             password=>string,   builds a Net::Jabber::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::Browse Functions

    BrowseRequest(jid=>string, - sends a jabber:iq:browse request to
                  timeout=>int)  the jid passed as an argument, and
                                 returns a hash with the resulting
                                 tree.  The format of the hash is:

                $browse{'category'} = "conference"
                $browse{'children'}->[0]
                $browse{'children'}->[1]
                $browse{'children'}->[11]
                $browse{'jid'} = "conference.jabber.org"
                $browse{'name'} = "Jabber.org Conferencing Center"
                $browse{'ns'}->[0]
                $browse{'ns'}->[1]
                $browse{'type'} = "public"

                                 The ns array is an array of the
                                 namespaces that this jid supports.
                                 The children array points to hashs
                                 of this form, and represent the fact
                                 that they can be browsed to.

                                 The timeout arguement is to tell the
                                 system how long to wait before giving
                                 up getting a reply back.

IQ::Browse DB Functions

    BrowseDBDelete(string|Net::Jabber::JID) - delete thes JID browse
                                              data from the DB.

    BrowseDBQuery(jid=>string | NJ::JID, - returns the browse data
                  timeout=>integer,        for the requested JID.  If
                  refresh=>0|1)            the DB does not contain
                                           the data for the JID, then
                                           it attempts to fetch the
                                           data via BrowseRequest().
                                           The timeout is passed to
                                           the BrowseRequest() call,
                                           and refresh tells the DB
                                           to request the data, even
                                           if it already has some.

IQ::Last Functions

    LastQuery(to=>string,     - asks the jid specified for its last
              waitforid=>0|1)   activity.  If the to is blank, then it
    LastQuery()                 queries the server.  Returns a hash with
                                the various items set if waitforid is set
                                to 1:

                                  $last{seconds} - Seconds since activity
                                  $last{message} - Message for activity

    LastSend(to=>string, - sends the specified last to the specified jid.
             hash)         the hash is the seconds and message as shown
                           in the Net::Jabber::Query man page.

IQ::Register Functions

    RegisterRequest(to=>string) - send an <iq/> request to the specified
    RegisterRequest()             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:form in the
                                                     packet.
                                  $hash{isntructions} - 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::Jabber::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.

IQ::Roster Functions

    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::Jabber::IQ::Roster tag to the
                  server so the server will send the Roster to the
                  client.  Returns the above hash from RosterParse.

    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::Jabber::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::Jabber::Query jabber:iq:roster
                         namespace.

IQ::Search Functions

    SearchRequest(to=>string) - send an <iq/> request to the specified
    SearchRequest()             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:

                                   $fields{intructions} = "do this..."
                                   $fields{key} = "some key"
                                   $fields{name} = ""
                                   ...

                                The fields that are present are the
                                required fields the server needs.  If
                                the hash is undefined then there was
                                an error with the request.

    SearchSend(to=>string|JID, - takes the contents of the hash and
               hash)             passes it to the SetSearch function
                                 in the Net::Jabber::Query
                                 jabber:iq:search namespace.  And then
                                 sends the packet.

IQ::Time Functions

    TimeQuery(to=>string,     - asks the jid specified for its localtime.
              waitforid=>0|1)   If the to is blank, then it queries the
    TimeQuery()                 server.  Returns a hash with the various
                                items set if waitforid is set to 1:

                                  $time{utc}     - Time in UTC
                                  $time{tz}      - Timezone
                                  $time{display} - Display string

    TimeSend(to=>string) - sends the current UTC time to the specified
                           jid.

IQ::Version Functions

    VersionQuery(to=>string,     - asks the jid specified for its
                 waitforid=>0|1)   client version information.  If the
    VersionQuery()                 to is blank, then it queries the
                                   server.  Returns ahash with the
                                   various items set if waitforid is
                                   set to 1:

                                     $version{name} - Name
                                     $version{ver}  - Version
                                     $version{os}   - Operating System/
                                                        Platform

    VersionSend(to=>string,   - sends the specified version information
                name=>string,   to the jid specified in the to.
                ver=>string,
                os=>string)

X Functions

    SXPMSend(to=>string,   - sends the specified sxpm information to the
             type=>string,   jid in the to with the message type being
             hash)           set in the type.  See the Net::Jabber::SXPM
                             module for valid values for the hash.
                             This function returns the
                             Net::Jabber::Message object sent to the jid.

AUTHOR

By Ryan Eatmon in May of 2001 for http://jabber.org

COPYRIGHT

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.