/linkedfs/usr/lib/perl5/vendor_perl/5.8.4/Net/Jabber/Protocol.pm

Large files files are truncated, but you can click here to view the full file

##############################################################################
#
#  This library is free software; you can redistribute it and/or
#  modify it under the terms of the GNU Library General Public
#  License as published by the Free Software Foundation; either
#  version 2 of the License, or (at your option) any later version.
#
#  This library is distributed in the hope that it will be useful,
#  but WITHOUT ANY WARRANTY; without even the implied warranty of
#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
#  Library General Public License for more details.
#
#  You should have received a copy of the GNU Library General Public
#  License along with this library; if not, write to the
#  Free Software Foundation, Inc., 59 Temple Place - Suite 330,
#  Boston, MA  02111-1307, USA.
#
#  Jabber
#  Copyright (C) 1998-1999 The Jabber Team http://jabber.org/
#
##############################################################################

package Net::Jabber::Protocol;

=head1 NAME

Net::Jabber::Protocol - Jabber Protocol Library

=head1 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.

=head1 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.

=head2 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::Jabber 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::Jabber, 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.
               

=head2 Basic Functions

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

      or

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


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

    $Con->SetMessageCallBacks(normal=>\&messageNormalCB,
                              chat=>\&messageChatCB);

    $Con->SetPresenceCallBacks(available=>\&presenceAvailableCB,
                               unavailable=>\&presenceUnavailableCB);

    $Con->SetIQCallBacks("jabber:iq:roster"=>
                                             {
                                                 get=>\&iqRosterGetCB,
                                                 set=>\&iqRosterSetCB,
                                                 result=>\&iqRosterResultCB,
                                             },
                                             etc...
                                            );

    $Con->SetXPathCallBacks("/message[@type='chat']"=>&messageChatCB,
                            "/message[@type='chat']"=>&otherMessageChatCB,
                            ...
                           );

    $Con->RemovePathCallBacks("/message[@type='chat']"=>&otherMessageChatCB);

    $Con->Info(name=>"Jarl",
               version=>"v0.6000");

    $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();

=head2 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);

=head2 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"]}]);

=head2 Message Functions

    $Con->MessageSend(to=>"bob@jabber.org",
                      subject=>"Lunch",
                      body=>"Let's go grab some...\n",
                      thread=>"ABC123",
                      priority=>10);

=head2 Presence Functions

    $Con->PresenceSend();
    $Con->PresenceSend(type=>"unavailable");
    $Con->PresenceSend(show=>"away");
    $Con->PresenceSend(signature=>...signature...);

=head2 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");

=head2 Presence DB Functions

    $Con->PresenceDBParse(Net::Jabber::Presence);

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

    $Con->PresenceDBClear();

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

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

=head2 IQ  Functions

=head2 Agents Functions

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

=head2 Auth Functions

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

=head2 Browse Functions

    %hash = $Con->BrowseRequest(jid=>"jabber.org");
    %hash = $Con->BrowseRequest(jid=>"jabber.org",
                                timeout=>10);

    $id = $Con->BrowseRequest(jid=>"jabber.org",
                              mode=>"nonblock");

    $id = $Con->BrowseRequest(jid=>"jabber.org",
                              mode=>"passthru");

=head2 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);

=head2 Bystreams Functions

    %hash = $Con->ByteStreamsProxyRequest(jid=>"proxy.server"); 
    %hash = $Con->ByteStreamsProxyRequest(jid=>"proxy.server",
                                          timeout=>10); 

    $id = $Con->ByteStreamsProxyRequest(jid=>"proxy.server",
                                        mode=>"nonblock");

    $id = $Con->ByteStreamsProxyRequest(jid=>"proxy.server",
                                        mode=>"passthru");

    
    %hash = $Con->ByteStreamsProxyParse($query);

    
    $status = $Con->ByteStreamsProxyActivate(sid=>"stream_id",
                                             jid=>"proxy.server"); 
    $status = $Con->ByteStreamsProxyActivate(sid=>"stream_id",
                                             jid=>"proxy.server",
                                            timeout=>10); 

    $id = $Con->ByteStreamsProxyActivate(sid=>"stream_id",
                                         jid=>"proxy.server",
                                        mode=>"nonblock");

    $id = $Con->ByteStreamsProxyActivate(sid=>"stream_id",
                                         jid=>"proxy.server",
                                        mode=>"passthru"); 


    $jid = $Con->ByteStreamsOffer(sid=>"stream_id",
                                  streamhosts=>[{jid=>"jid",
                                                 host=>"host",
                                                 port=>"port",
                                                 zeroconf=>"zero",
                                                },
                                                ...
                                               ],
                                  jid=>"bob\@jabber.org"); 
    $jid = $Con->ByteStreamsOffer(sid=>"stream_id",
                                  streamhosts=>[{},{},...],
                                  jid=>"bob\@jabber.org",
                                  timeout=>10); 

    $id = $Con->ByteStreamsOffer(sid=>"stream_id",
                                 streamhosts=>[{},{},...],
                                 jid=>"bob\@jabber.org",
                                 mode=>"nonblock");

    $id = $Con->ByteStreamsOffer(sid=>"stream_id",
                                 streamhosts=>[{},{},...],
                                 jid=>"bob\@jabber.org",
                                 mode=>"passthru");
 
=head2 Disco Functions

    %hash = $Con->DiscoInfoRequest(jid=>"jabber.org");
    %hash = $Con->DiscoInfoRequest(jid=>"jabber.org",
                                   node=>"node...");
    %hash = $Con->DiscoInfoRequest(jid=>"jabber.org",
                                   node=>"node...",
                                   timeout=>10);

    $id = $Con->DiscoInfoRequest(jid=>"jabber.org",
                                 mode=>"nonblock");
    $id = $Con->DiscoInfoRequest(jid=>"jabber.org",
                                 node=>"node...",
                                 mode=>"nonblock");

    $id = $Con->DiscoInfoRequest(jid=>"jabber.org",
                                 mode=>"passthru");
    $id = $Con->DiscoInfoRequest(jid=>"jabber.org",
                                 node=>"node...",
                                 mode=>"passthru");

    
    %hash = $Con->DiscoInfoParse($query);


    %hash = $Con->DiscoItemsRequest(jid=>"jabber.org");
    %hash = $Con->DiscoItemsRequest(jid=>"jabber.org",
                                    timeout=>10);

    $id = $Con->DiscoItemsRequest(jid=>"jabber.org",
                                  mode=>"nonblock");

    $id = $Con->DiscoItemsRequest(jid=>"jabber.org",
                                  mode=>"passthru");

    
    %hash = $Con->DiscoItemsParse($query);

=head2 Feature Negotiation Functions

  
    %hash = $Con->FeatureNegRequest(jid=>"jabber.org",
                                    features=>{ feat1=>["opt1","opt2",...],
                                                feat2=>["optA","optB",...]
                                              }
                                   );
    %hash = $Con->FeatureNegRequest(jid=>"jabber.org",
                                    features=>{ ... },
                                    timeout=>10);

    $id = $Con->FeatureNegRequest(jid=>"jabber.org",
                                  features=>{ ... },
                                  mode=>"nonblock");

    $id = $Con->FeatureNegRequest(jid=>"jabber.org",
                                  features=>{ ... },
                                  mode=>"passthru");

    my $query = $self->FeatureNegQuery(\{ ... });
    $iq->AddQuery($query);

    %hash = $Con->FeatureNegParse($query);  

=head2 File Transfer Functions

    $method = $Con->FileTransferOffer(jid=>"bob\@jabber.org",
                                      sid=>"stream_id",
                                      filename=>"/path/to/file",
                                      methods=>["http://jabber.org/protocol/si/profile/bytestreams",
                                                "jabber:iq:oob",
                                                ...
                                               ]
                                     );
    $method = $Con->FileTransferOffer(jid=>"bob\@jabber.org",
                                      sid=>"stream_id",
                                      filename=>"/path/to/file",
                                      methods=>\@methods,
                                      timeout=>"10");

    $id = $Con->FileTransferOffer(jid=>"bob\@jabber.org",
                                  sid=>"stream_id",
                                  filename=>"/path/to/file",
                                  methods=>\@methods,
                                  mode=>"nonblock");

    $id = $Con->FileTransferOffer(jid=>"bob\@jabber.org",
                                  sid=>"stream_id",
                                  filename=>"/path/to/file",
                                  methods=>\@methods,
                                  mode=>"passthru");

=head2 Last Functions

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

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

    %result = $Con->LastQuery(to=>"bob@jabber.org",
                              mode=>"block",
                              timeout=>10);
    %result = $Con->LastQuery(mode=>"block",
                              timeout=>10);

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

    $seconds = $Con->LastActivity();

=head2 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");

    @result = $Con->RegisterSendData("users.jabber.org",
                                     first=>"Bob",
                                     last=>"Smith",
                                     nick=>"bob",
                                     email=>"foo@bar.net");


=head2 Roster Functions

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


=head2 RPC Functions

    $query = $Con->RPCEncode(type=>"methodCall",
                             methodName=>"methodName",
                             params=>[param,param,...]);
    $query = $Con->RPCEncode(type=>"methodResponse",
                             params=>[param,param,...]);
    $query = $Con->RPCEncode(type=>"methodResponse",
                             faultCode=>4,
                             faultString=>"Too many params");

    @response = $Con->RPCParse($iq);

    @response = $Con->RPCCall(to=>"dataHouse.jabber.org",
                              methodname=>"numUsers",
                              params=>[ param,param,... ]
                             );

    $Con->RPCResponse(to=>"you\@jabber.org",
                      params=>[ param,param,... ]);

    $Con->RPCResponse(to=>"you\@jabber.org",
                      faultCode=>"4",
                      faultString=>"Too many parameters"
                     );

    $Con->RPCSetCallBacks(myMethodA=>\&methoda,
                          myMethodB=>\&do_somthing,
                          etc...
                         );

=head2 Search Functions

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

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

    $Con->SearchSendData("users.jabber.org",
                         first=>"Bob",
                         last=>"",
                         nick=>"bob",
                         email=>"");

=head2 Time Functions

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

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

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

=head2 Version Functions

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

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

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

=head2 Multi-User Chat Functions

    $Con->MUCJoin(room=>"jabber",
                  server=>"conference.jabber.org",
                  nick=>"nick");

    $Con->MUCJoin(room=>"jabber",
                  server=>"conference.jabber.org",
                  nick=>"nick",
                  password=>"secret");

=head1 METHODS

=head2 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.

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

                                       Net::Jabber defines a few default
                                       callbacks for various types and
                                       namespaces:

                                       jabber:iq:last(get) -
                                         replies with the current last
                                         activity
                                       jabber:iq:last(result) -
                                         reformats the <iq/> into a
                                         <message/> and submits it as
                                         if the packet was received.

                                       jabber:iq:rpc(set) -
                                         calls the rpc method and
                                         returns the response

                                       jabber:iq:time(get) -
                                         replys with the current time
                                       jabber:iq:time(result) -
                                         reformats the <iq/> into a
                                         <message/> and submits it as
                                         if the packet was received.

                                       jabber:iq:version(get) -
                                         replys with the info for the
                                         Client/Component (as defined
                                         in the Info function)
                                       jabber:iq:version(result) -
                                         reformats the <iq/> into a
                                         <message/> and submits it as
                                         if the packet was received.

    SetXPathCallBacks(xpath=>function, - registers a callback function for
                        etc...)          each xpath specified.  If
                                         Net::Jabber matches the xpath,
                                         then it calls the function with
                                         two arguments:
                                           the session ID, and the
                                           Net::Jabber::Message object.

                                         Xpaths are rooted at each packet:
                                           /message[@type="chat"]
                                           /iq/*[xmlns="jabber:iq:roster"][1]
                                           ...

    RemoveXPathCallBacks(xpath=>function, - unregisters a callback function
                        etc...)             for each xpath specified.

    Info(name=>string,    - Set some information so that Net::Jabber
         version=>string)   can auto-reply to some packets for you to
                            reduce the work you have to do.

                            NOTE: This requires that you use the
                            SetIQCallBacks methodology and not the
                            SetCallBacks for <iq/> packets.

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

=head2 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.

=head2 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.

=head2 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::Jabber::Presence module.
                                      Optionally, you can specify a
                                      signature and a jabber:x:signed
                                      will be placed in the <presence/>.

=head2 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

=head2 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.

    PresenceDBClear() - delete all entries in the database.

    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.

=head2 IQ Functions

=head2 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.

=head2 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.

=head2 Browse Functions

    BrowseRequest(jid=>string, - sends a jabber:iq:browse request to
                  mode=>string,  the jid passed as an argument.
                  timeout=>int)  Returns a hash with the resulting
                                 tree if mode is set to "block":

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

                                 See MODES above for using the mode
                                 and timeout.

=head2 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.

=head2 Bytestreams Functions

    ByteStreamsProxyRequest(jid=>string, - sends a bytestreams request
                            mode=>string,  to the jid passed as an
                            timeout=>int)  argument.  Returns an array
                                           ref with the resulting tree
                                           if mode is set to "block".

                                           See ByteStreamsProxyParse
                                           for the format of the
                                           resulting tree.

                                           See MODES above for using
                                           the mode and timeout.

    ByteStreamsProxyParse(Net::Jabber::Query) - parses the query and
                                                returns an array ref
                                                to the resulting tree:

                $host[0]->{jid} = "bytestreams1.proxy.server";
                $host[0]->{host} = "proxy1.server";
                $host[0]->{port} = "5006";
                $host[1]->{jid} = "bytestreams2.proxy.server";
                $host[1]->{host} = "proxy2.server";
                $host[1]->{port} = "5007";
                ...

    ByteStreamsProxyActivate(jid=>string, - sends a bytestreams activate
                             sid=>string,   to the jid passed as an
                             mode=>string,  argument.  Returns 1 if the
                             timeout=>int)  proxy activated (undef if
                                            it did not) if mode is set
                                            to "block".

                                            sid is the stream id that
                                            is being used to talk about
                                            this stream.

                                            See MODES above for using
                                            the mode and timeout.

    ByteStreamsOffer(jid=>string,         - sends a bytestreams offer
                     sid=>string,           to the jid passed as an
                     streamhosts=>arrayref  argument.  Returns the jid
                     mode=>string,          of the streamhost that the
                     timeout=>int)          user selected if mode is set
                                            to "block".

                                            streamhosts is the same
                                            format as the array ref
                                            returned from
                                            ByteStreamsProxyParse.

                                            See MODES above for using
                                            the mode and timeout.

=head2 Disco Functions

    DiscoInfoRequest(jid=>string, - sends a disco#info request to
                     node=>string,  the jid passed as an argument,
                     mode=>string,  and the node if specified.
                     timeout=>int)  Returns a hash with the resulting
                                    tree if mode is set to "block".

                                    See DiscoInfoParse for the format
                                    of the resulting tree.
                                    
                                    See MODES above for using the mode
                                    and timeout.

    DiscoInfoParse(Net::Jabber::Query) - parses the query and
                                         returns a hash ref
                                         to the resulting tree:

             $info{identity}->[0]->{category} = "groupchat";
             $info{identity}->[0]->{name} = "Public Chatrooms";
             $info{identity}->[0]->{type} = "public";

             $info{identity}->[1]->{category} = "groupchat";
             $info{identity}->[1]->{name} = "Private Chatrooms";
             $info{identity}->[1]->{type} = "private";

             $info{feature}->{http://jabber.org/protocol/disco#info} = 1;
             $info{feature}->{http://jabber.org/protocol/muc#admin} = 1;
                                    
    DiscoItemsRequest(jid=>string, - sends a disco#items request to
                      mode=>string,  the jid passed as an argument.
                      timeout=>int)  Returns a hash with the resulting
                                     tree if mode is set to "block".

                                     See DiscoItemsParse for the format
                                     of the resulting tree.
                                    
                                     See MODES above for using the mode
                                     and timeout.

    DiscoItemsParse(Net::Jabber::Query) - parses the query and
                                          returns a hash ref
                                          to the resulting tree:

             $items{jid}->{node} = name;

             $items{"proxy.server"}->{""} = "Bytestream Proxy Server";
             $items{"conf.server"}->{"public"} = "Public Chatrooms";
             $items{"conf.server"}->{"private"} = "Private Chatrooms";

=head2 Feature Negotiation Functions

    FeatureNegRequest(jid=>string,       - sends a feature negotiation to
                      features=>hash ref,  the jid passed as an argument,
                      mode=>string,        using the features specified.
                      timeout=>int)        Returns a hash with the resulting
                                           tree if mode is set to "block".

                                           See DiscoInfoQuery for the format
                                           of the features hash ref.
                                    
                                           See DiscoInfoParse for the format
                                           of the resulting tree.
                                    
                                           See MODES above for using the mode
                                           and timeout.

    FeatureNegParse(Net::Jabber::Query) - parses the query and
                                          returns a hash ref
                                          to the resulting tree:

             $features->{feat1} = ["opt1","opt2",...];
             $features->{feat2} = ["optA","optB",...];
             ....

                                          If this is a result:

             $features->{feat1} = "opt2";
             $features->{feat2} = "optA";
             ....

    FeatureNeqQuery(hash ref) - takes a hash ref and turns it into a
                                feature negotiation query that you can
                                AddQuery into your packaet.  The format
                                of the hash ref is as follows:

             $features->{feat1} = ["opt1","opt2",...];
             $features->{feat2} = ["optA","optB",...];
             ....

=head2 File Transfer Functions

    FileTransferOffer(jid=>string,         - sends a file transfer stream
                      sid=>string,           initiation to the jid passed
  …

Large files files are truncated, but you can click here to view the full file