NAME

Net::Jabber::Query - Jabber Query Library

SYNOPSIS

Net::Jabber::Query is a companion to the Net::Jabber::IQ module. It
provides the user a simple interface to set and retrieve all 
parts of a Jabber IQ Query.

DESCRIPTION

Net::Jabber::Query differs from the other Net::Jabber::* modules in that
the XMLNS of the query is split out into more submodules under
Query.  For specifics on each module please view the documentation
for each Net::Jabber::Query::* module.  The available modules are:

  Net::Jabber::Query::Agent      - Agent Namespace
  Net::Jabber::Query::Agents     - Supported Agents list from server
  Net::Jabber::Query::Auth       - Simple Client Authentication
  Net::Jabber::Query::AutoUpdate - Auto-Update for clients
  Net::Jabber::Query::Fneg       - Feature Negotiation
  Net::Jabber::Query::Oob        - Out of Bandwidth File Transfers
  Net::Jabber::Query::Register   - Registration requests
  Net::Jabber::Query::Roster     - Buddy List management
  Net::Jabber::Query::Time       - Client Time
  Net::Jabber::Query::Version    - Client Version

Each of these modules provide Net::Jabber::Query with the functions
to access the data.  By using delegates and the AUTOLOAD function
the functions for each namespace is used when that namespace is
active.

To access a Query object you must create an IQ object and use the
access functions there to get to the Query.  To initialize the IQ with 
a Jabber <iq/> you must pass it the XML::Parser Tree array from the 
Net::Jabber::Client module.  In the callback function for the iq
you can access the query tag by doing the following:

  use Net::Jabber;

  sub iqCB {
    my $iq = new Net::Jabber::IQ(@_);
    my $query = $mesage->GetQuery();
    .
    .
    .
  }

You now have access to all of the retrieval functions available.

To create a new iq to send to the server:

  use Net::Jabber;

  my $iq = new Net::Jabber::IQ();
  $query = $iq->NewQuery("jabber:iq:register");

Now you can call the creation functions for the Query as defined in the
proper namespaces.  See below for the general <query/> functions, and
in each query module for those functions.

For more information about the array format being passed to the CallBack
please read the Net::Jabber::Client documentation.

Basic functions

$Query->SetDelegates("com:ti:foo"=>"TI::Foo",
                     "bar:foo"=>"Foo::Bar");

Retrieval functions

$xmlns     = $IQ->GetXMLNS();

$str       = $IQ->GetXML();
@iq        = $IQ->GetTree();

Creation functions

$Query->SetXMLNS("jabber:iq:roster");

METHODS

Basic functions

SetDelegates(hash) - sets the appropriate delegate for each namespace
                     in the list.  Format is namspace=>package.  When
                     a function is called against the Query object and
                     it is not defined in this package, the delegate
                     is searched for that function.  This allows for
                     easy development of a package to handle new <query/>
                     tags for what ever application.

Retrieval functions

GetXMLNS() - returns a string with the namespace of the query that
             the <iq/> contains.

GetXML() - returns the XML string that represents the <iq/>. This 
           is used by the Send() function in Client.pm to send
           this object as a Jabber IQ.

GetTree() - returns an array that contains the <iq/> tag in XML::Parser 
            Tree format.

Creation functions

SetXMLNS(string) - sets the xmlns of the <query/> to the string.

CUSTOM Query MODULES

Part of the flexability of this module is that you can write your own
module to handle a new namespace if you so choose.  The SetDelegates
function is your way to register the xmlns and which module will
provide the missing access functions.

To register your namespace and module, you can either create an IQ
object and register it once, or you can use the SetDelegates
function in Client.pm to do it for you:

  my $query = new Net::Jabber::Query();
  $query->SetDelegates("blah:blah"=>"Blah::Blah");

or

  my $Client = new Net::Jabber::Client();
  $Client->SetQueryDelegates("blah:blah"=>"Blah::Blah");

Once you have the delegate registered you need to define the access
functions.  Here is a an example module:

  package Blah::Blah;

  sub new {
    my $proto = shift;
    my $class = ref($proto) || $proto;
    my $self = { };
    $self->{VERSION} = $VERSION;
    bless($self, $proto);
    return $self;
  }

  sub SetBlah {
    shift;
    my $self = shift;
    my ($blah) = @_;
    return &Net::Jabber::SetXMLData("single",$self->{QUERY},"blah","$blah",{});
  }

  sub GetBlah {
    shift;
    my $self = shift;
    return &Net::Jabber::GetXMLData("value",$self->{QUERY},"blah","");
  }

  1;

Now when you create a new Query object and call GetBlah on that object
it will AUTOLOAD the above function and handle the request.

AUTHOR

By Ryan Eatmon in May of 2000 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.