++ed by:

2 non-PAUSE users.

Ryan Eatmon

NAME

Net::Jabber::Query::Search - Jabber IQ Search Module

SYNOPSIS

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

DESCRIPTION

  To initialize the IQ with a Jabber <iq/> and then access the search
  query you must pass it the XML::Parser Tree array from the 
  Net::Jabber::Client module.  In the callback function for the iq:

    use Net::Jabber;

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

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

  To create a new IQ search to send to the server:

    use Net::Jabber;

    $client = new Net::Jabber::Client();
    ...

    $iq = new Net::Jabber::IQ();
    $search = $iq->NewQuery("jabber:iq:search");
    ...

    $client->Send($iq);

  Using $search you can call the creation functions below to populate the 
  tag before sending it.

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

Retrieval functions

    $name         = $search->GetName();
    $first        = $search->GetFirst();
    $given        = $search->GetGiven();
    $last         = $search->GetLast();
    $family       = $search->GetFamily();
    $nick         = $search->GetNick();
    $email        = $search->GetEmail();
    $key          = $search->GetKey();
    $instructions = $search->GetInstructions();

    %fields       = $search->GetFields();

    @items        = $search->GetItems();
    @itemTrees    = $search->GetItemTrees();
    %results      = $search->GetResults();

    $truncated    = $search->GetTruncated();

Creation functions

    $search->SetSearch(key=>"somekey",
                       name=>"",
                       first=>"",
                       last=>"",
                       nick=>"bob",
                       email=>"");
    $search->SetSearch(instructions=>"Fill in a field to search".
                                     " for any matching Jabber users.",
                       key=>"somekey",
                       name=>"",
                       first=>"",
                       last=>"",      
                       nick=>"",
                       email=>"");

    $search->SetInstructions("Fill out the form...");
    $search->SetKey("somekey");
    $search->SetName("");
    $search->SetFirst("Bob");
    $search->SetGiven("Bob");
    $search->SetLast("Smith");
    $search->SetFamily("Smith");
    $search->SetNick("");
    $search->SetEmail("");

    $search->SetTruncated();

    $item   = $search->AddItem();
    $item   = $search->AddItem(jid=>"bob\@jabber.org",
                               name=>"Bob Smith",
                               first=>"Bob",
                               last=>"Smith",
                               nick=>"bob");

Test fucntions

    $test = $search->DefinedName();
    $test = $search->DefinedFirst();
    $test = $search->DefinedGiven();
    $test = $search->DefinedLast();
    $test = $search->DefinedFamily();
    $test = $search->DefinedNick();
    $test = $search->DefinedEmail();
    $test = $search->DefinedKey();
    $test = $search->DefinedInstructions();

    $test = $search->DefinedTruncated();

METHODS

Retrieval functions

  GetInstructions() - returns a string that contains the instructions
                      for using this search query.

  GetKey() - returns a string that contains the value of key from the
             search agent.

  GetName() - returns a string that contains the value of name in the
              search query.

  GetFirst() - returns a string that contains the value of first in the
               search query.

  GetGiven() - returns a string that contains the value of given name
               in the search query.

  GetLast() - returns a string that contains the value of last in the
              search query.

  GetFamily() - returns a string that contains the value of the family 
                name in the search query.

  GetNick() - returns a string that contains the value of nick in the
              search query.

  GetEmail() - returns a string that contains the value of email in the
               search query.

  GetFields() - returns a hash that contains the fields required by the
                sender in $hash{tag} = value format.

  GetItems() - returns an array of Net::Jabber::Query::Search::Item 
               objects. These can be modified or accessed with the 
               functions available to them.

  GetItemTrees() - returns an array of XML::Parser objects that contain
                   the data for each item.

  GetResults() - returns an hash that represents the data in the Item
                 trees.  The hash looks like this:

                   $results{jid1}->{field1} = "value1";
                                   {field2} = "value2";
                                   {field3} = "value3";
                   $results{jid2}->{field1} = "value1";
                                   {field2} = "value2";
                                   {field3} = "value3";

  GetTruncated() - returns a string that contains the value of truncated in 
                   the search query.

Creation functions

  SetSearch(instructions=>string, - set multiple fields in the <query/>
            key=>string,            at one time.  This is a cumulative
            name=>string,           and overwriting action.  If you
            first=>string,          set the "name" twice, the second
            given=>string,          setting is what is used.  If you set
            last=>string,           the first, and then set the
            family=>string)         last then both will be in the
            nick=>string,           search.  For valid settings read
            email=>string)          the specific Set functions below.

  SetInstructions(string) - sets the value of the instructions in the 
                            <query/>.

  SetKey(string) - sets the value of key in the <query/>.

  SetName(string) - sets the value of name in the <query/>.  If "" then
                    it creates an empty tag.

  SetFirst(string) - sets the value of first in the <query/>.  If "" then
                     it creates an empty tag.

  SetGiven(string) - sets the value of given in the <query/>.  If "" then
                     it creates an empty tag.

  SetLast(string) - sets the value of last in the <query/>.  If "" then
                    it creates an empty tag.

  SetFamily(string) - sets the value of family in the <query/>.  If "" then
                      it creates an empty tag.

  SetNick(string) - sets the value of nick in the <query/>.  If "" then
                    it creates an empty tag.

  SetEmail(string) - sets the value of email in the <query/>.  If "" then
                     it creates an empty tag.

  SetTruncated() - adds a <truncated/> tag to the <query/> to indicate that
                   the search results were truncated.

  AddItem(hash) - creates and returns a new Net::Jabbber::Query::Search::Item
                  object.  The argument hash is passed to the SetItem 
                  function.  Check the Net::Jabber::Query::Search::Item
                  for valid values.

Test functions

  DefinedInstructions() - returns 1 if there is a <instructions/> in 
                          the query, 0 if not.

  DefinedKey() - returns 1 if there is a <key/> in the query, 0 if not.

  DefinedName() - returns 1 if there is a <name/> in the query, 0 if not.

  DefinedFirst() - returns 1 if there is a <first/> in the query, 0 if not.

  DefinedGiven() - returns 1 if there is a <given/> in the query, 0 if not.

  DefinedLast() - returns 1 if there is a <last/> in the query, 0 if not.

  DefinedFamily() - returns 1 if there is a <family/> in the query, 0 if not.

  DefinedNick() - returns 1 if there is a <nick/> in the query, 0 if not.

  DefinedEmail() - returns 1 if there is a <email/> in the query, 0 if not.

  DefinedTruncated() - returns 1 if there is a <truncated/> in the query, 
                       0 if not.

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.