NAME

Net::XMPP::Query - XMPP Query Module

SYNOPSIS

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

DESCRIPTION

Net::XMPP::Query differs from the other modules in that its behavior
and available functions are based off of the XML namespace that is
set in it.  The current supported namespaces are:

  urn:ietf:params:xml:ns:xmpp-bind
  urn:ietf:params:xml:ns:xmpp-session
  jabber:iq:roster

For more information on what these namespaces are for read the IETF
XMPP-Core and XMPP-IM RFCs.

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

A Net::XMPP::IQ object is passed to the callback function for the
message.  Also, the first argument to the callback functions is the
session ID from XML::Streams.  There are some cases where you might
want this information, like if you created a Client that connects to
two servers at once, or for writing a mini server.

  use Net::XMPP qw(Client);

  sub iqCB {
    my ($sid,$IQ) = @_;
    my $query = $IQ->GetQuery();
    .
    .
    .
  }

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

To create a new iq to send to the server:

  use Net::XMPP;

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

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.

METHODS

Retrieval functions

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

             $xmlns  = $IQ->GetXMLNS();

GetQuery() - since the behavior of this module depends on the
             namespace, a Query object may contain Query objects.
             This helps to leverage code reuse by making children
             behave in the same manner.  More than likely this
             function will never be called.

             @query = GetQuery()

Creation functions

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

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

In an effort to make maintaining this document easier, I am not going to go into full detail on each of these functions. Rather I will present the functions in a list with a type in the first column to show what they return, or take as arugments. Here is the list of types I will use:

string  - just a string
array   - array of strings
flag    - this means that the specified child exists in the
          XML <child/> and acts like a flag.  get will return
          0 or 1.
JID     - either a string or Net::XMPP::JID object.
objects - creates new objects, or returns an array of
          objects.
master  - this desribes a function that behaves like the
          SetMessage() function in Net::XMPP::Message.
          It takes a hash and sets all of the values defined,
          and the Set returns a hash with the values that
          are defined in the object.

urn:ietf:params:xml:ns:xmpp-bind

Type     Get               Set               Defined
=======  ================  ================  ==================
jid      GetJID()          SetJID()          DefinedJID()
string   GetResource()     SetResource()     DefinedResource()
master   GetBind()         SetBind()

urn:ietf:params:xml:ns:xmpp-session

Type     Get               Set               Defined
=======  ================  ================  ==================
master   GetSession()      SetSession()

jabber:iq:roster

Type     Get               Set               Defined
=======  ================  ================  ==================
objects                    AddItem()
objects  GetItems()

jabber:iq:roster - item objects

Type     Get               Set               Defined
=======  ================  ================  ==================
string   GetAsk()          SetAsk()          DefinedAsk()
array    GetGroup()        SetGroup()        DefinedGroup()
JID      GetJID()          SetJID()          DefinedJID()
string   GetName()         SetName()         DefinedName()
string   GetSubscription() SetSubscription() DefinedSubscription()
master   GetItem()         SetItem()

CUSTOM NAMESPACES

Part of the flexability of this module is that you can define your own
namespace.  For more information on this topic, please read the
Net::XMPP::Namespaces man page.

AUTHOR

Ryan Eatmon

COPYRIGHT

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