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.