NAME

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

SYNOPSIS

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

DESCRIPTION

To initialize the Item 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();
    my @items = $search->GetItems();
    foreach $item (@items) {
      ...
    }
    .
    .
    .
  }

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

To create a new IQ Search Item to send to the server:

  use Net::Jabber;

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

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

  $client->Send($iq);

Using $Item 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

$jid    = $item->GetJID();
$jidJID = $item->GetJID("jid");
$name   = $item->GetName();
$first  = $item->GetFirst();
$given  = $item->GetGiven();
$last   = $item->GetLast();
$family = $item->GetFamily();
$nick   = $item->GetNick();
$email  = $item->GetEmail();

%result = $item->GetResult();

@item   = $item->GetTree();
$str    = $item->GetXML();

Creation functions

    $item->SetItem(jid=>'bob@jabber.org',
		   name=>'Bob',
		   first=>'Bob',
		   last=>'Smith',
		   nick=>'bob',
		   email=>'bob@hotmail.com');

    $item->SetJID('bob@jabber.org');
    $item->SetName('Bob Smith');
    $item->SetFirst('Bob');
    $item->SetGiven('Bob');
    $item->SetLast('Smith');
    $item->SetFamily('Smith');
    $item->SetNick('bob');
    $item->SetEmail('bob@bobworld.com');

Test functions

$test = $item->DefinedName();
$test = $item->DefinedFirst();
$test = $item->DefinedGiven();
$test = $item->DefinedLast();
$test = $item->DefinedFamily();
$test = $item->DefinedNick();
$test = $item->DefinedEmail();

METHODS

Retrieval functions

GetJID()      - returns either a string with the Jabber Identifier,
GetJID("jid")   or a Net::Jabber::JID object for the account that is 
                listed in this <item/>.  To get the JID object set the 
                string to "jid", otherwise leave blank for the text
                string.

GetName() - returns a string with the full name of the account being 
            returned.

GetFirst() - returns a string with the first name of the account being 
             returned.

GetGiven() - returns a string with the given name of the account being 
             returned.

GetLast() - returns a string with the last name of the jabber account 
            being returned.

GetFamily() - returns a string with the family name of the jabber 
              account being returned.

GetNick() - returns a string with the nick of the jabber account being 
            returned.

GetEmail() - returns a string with the email of the jabber account being 
             returned.

GetResult() - returns a hash with all of the valid fields set.  Here is
              the way the hash might look.

                $result{last} = "Smith";
                $result{first} = "Bob";

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

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

Creation functions

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

SetJID(string) - sets the Jabber Identifier.  You can either pass a
SetJID(JID)      string or a JID object.  They must be valid Jabber 
                 Identifiers or the server will return an error message.
                 (ie.  jabber:bob@jabber.org/Silent Bob, etc...)

SetName(string) - sets the name this search item should show in the
                  search.

SetFirst(string) - sets the first name this search item should show 
                   in the search.

SetGiven(string) - sets the given name this search item should show 
                   in the search.

SetLast(string) - sets the last name this search item should show in
                  the search.

SetFamily(string) - sets the family name this search item should show 
                    in the search.

SetNick(string) - sets the nick this search item should show in the
                  search.

SetEmail(string) - sets the email this search item should show in the
                   search.

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.