++ed by:

2 non-PAUSE users.

Ryan Eatmon

NAME

Net::Jabber::Query::Filter::Rule - Jabber IQ Filter Rule Module

SYNOPSIS

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

DESCRIPTION

  To initialize the Rule with a Jabber <iq/> and then access the filter
  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 $filter = $iq->GetQuery();
      my @rules = $filter->GetRules();
      foreach $rule (@rules) {
        ...
      }
      .
      .
      .
    }

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

  To create a new IQ Filter Rule to send to the server:

    use Net::Jabber;

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

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

    $client->Send($iq);

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

    %conditions  = $rule->GetConditions();
    $body        = $rule->GetBody();
    $from        = $rule->GetFrom();
    $resource    = $rule->GetResource();
    $show        = $rule->GetShow();
    $size        = $rule->GetSize();
    $subject     = $rule->GetSubject();
    $time        = $rule->GetTime();
    $type        = $rule->GetType();
    $unavailable = $rule->GetUnavailable();

    %actions     = $rule->GetActions();
    $drop        = $rule->GetDrop();
    $edit        = $rule->GetEdit();
    $error       = $rule->GetError();
    $reply       = $rule->GetReply();
    $forward     = $rule->GetForward();
    $offline     = $rule->GetOffline();

    $continue    = $rule->GetContinue();

Creation functions

    $rule->SetRule(unavailable=>1,
                   offline=>1);
    $rule->SetRule(from=>"bob\@jabber.org",
                   forward=>"me\@jabber.org/Pager");
    $rule->SetRule(from=>"ex-wife\@jabber.org",
                   reply=>"I don't want to talk you...");

    $rule->SetBody("free");                              # Future condition
    $rule->SetFrom("bob");                               # Future condition
    $rule->SetResource("Home");                          # Future condition
    $rule->SetShow("dnd");                               # Future condition
    $rule->SetSize(1024);                                # Future condition
    $rule->SetSubject("sex");                            # Future condition
    $rule->SetTime("20000502T01:01:01");                 # Future condition
    $rule->SetType("chat");                              # Future condition
    $rule->SetUnavailable();

    $rule->SetDrop();
    $rule->SetEdit();                                    # Future Action
    $rule->SetError("This JID is not a valid address");
    $rule->SetForward("foo\@bar.com/FooBar");
    $rule->SetOffline();
    $rule->SetReply("I don't want to talk you...");

    $rule->SetContinue();

Defined functions

    $test = $rule->DefinedBody();
    $test = $rule->DefinedFrom();
    $test = $rule->DefinedResource();
    $test = $rule->DefinedShow();
    $test = $rule->DefinedSize();
    $test = $rule->DefinedSubject();
    $test = $rule->DefinedTime();
    $test = $rule->DefinedType();
    $test = $rule->DefinedUnavailable();

    $test = $rule->DefinedDrop();
    $test = $rule->DefinedEdit();
    $test = $rule->DefinedError();
    $test = $rule->DefinedForward();
    $test = $rule->DefinedOffline();
    $test = $rule->DefinedReply();

    $test = $rule->DefinedContinue();

METHODS

Retrieval functions

  GetConditions() - returns a hash with the condition name and the value
                    of the tag as the value in the hash.  For example:

                      $conditions{unavailable} = 1;
                      $conditions{resource} = "Pager";
                      $conditions{type} = "chat";

  GetBody() - returns the string that the <rule/> uses to match in the body
              for this condition.
              **** This condition is still under development ****
              **** in mod_filter.                            ****

  GetFrom() - returns the string that the <rule/> uses to match in the from
              for this condition.
              **** This condition is still under development ****
              **** in mod_filter.                            ****

  GetResource() - returns the string that the <rule/> uses to match in the
                  resource of the to for this condition.
                  **** This condition is still under development ****
                  **** in mod_filter.                            ****

  GetShow() - returns the string that the <rule/> uses to match in the show
              for this condition.
              **** This condition is still under development ****
              **** in mod_filter.                            ****

  GetSize() - returns the string that the <rule/> uses to match in the size
              for this condition.
              **** This condition is still under development ****
              **** in mod_filter.                            ****

  GetSubject() - returns the string that the <rule/> uses to match in the
                 subject for this condition.
                 **** This condition is still under development ****
                 **** in mod_filter.                            ****

  GetTime() - returns the string that the <rule/> uses to match the time
              for this condition.
              **** This condition is still under development ****
              **** in mod_filter.                            ****

  GetType() - returns the string that the <rule/> uses to match the type
              for this condition.
              **** This condition is still under development ****
              **** in mod_filter.                            ****

  GetUnavailable() - returns 1 if this condition is set, 0 otherwise.
                     This condition is used to specify that you are
                     unavailable.

  GetActions() - returns a hash with the condition name and the value
                 of the tag as the value in the hash.  For example:
    
                    $actions{reply} = "I'm not in the office right now.";
                    $actions{continue} = 1;

  GetDrop() - returns 1 if the message is to be dropped, 0 otherwise.

  GetEdit() - **** This condition is still under development ****
              **** in mod_filter.                            ****

  GetError() - returns the string that the <rule/> uses to return in
               error message.

  GetReply() - returns the string that is sent for this action.

  GetForward() - returns the JID of the account to forward the message
                 to for this action.

  GetOffline() - returns 1 if the message is to go to the offline message
                 list, 0 otherwise.

  GetContinue() - returns 1 if there is a <continue/> tag in the <rule/>,
                  0 otherwise.  This allows you to chain multiple actions
                  in order for one set of conditions.

Creation functions

  SetRule(body=>string,      - set multiple fields in the <rule/>
          from=>string,        at one time.  This is a cumulative
          resource=>string,    and overwriting action.  If you
          show=>string,        set the "body" twice, the second
          size=>string,        setting is what is used.  If you set
          time=>string,        the show, and then set the
          type=>string,        offline then both will be in the
          unavailable=>0|1,    <rule/> tag.  For valid settings
          edit=>string,        read the specific Set functions below.
          error=>string,       
          forward=>string,
          offline=>0|1,
          reply=>string,
          continue=>0|1)

  SetBody(string) - sets the string that the <rule/> uses to match against
                    in the body.

  SetFrom(string) - sets the string that the <rule/> uses to match against
                    in the from.

  SetResource(string) - sets the string that the <rule/> uses to match
                        against in the resource of the from JID.

  SetShow(string) - sets the string that the <rule/> uses to match against
                    in the show.

  SetSize(string) - sets the string that the <rule/> uses to match against
                    for the size of the message.

  SetSubject(string) - sets the string that the <rule/> uses to match against
                       in the subject.

  SetTime(string) - sets the string that the <rule/> uses to match against
                    for the time the message is received.

  SetType(string) - sets the string that the <rule/> uses to match against
                    for the type of message.

  SetUnavailable() - adds an <unavailable/> to the <rule/> to match if you
                     are offline.

  SetDrop() - sets that the <rule/> should drop the message from the queue.

  SetEdit(string) - sets the string that the <rule/> uses to execute the edit
                    action on.

  SetError(string) - sets the string that goes into the error message for
                     this action.

  SetForward(string) - sets the JID that the message is forwarded to for
                       this action.

  SetOffline() - sets that the message goes into the offline queue.

  SetReply(string) - sets the string that goes into the reply message for
                     this action.

  SetContinue() - sets that this <rule/> is continued in the next <rule/>.

Defined functions

  DefinedBody() - returns 1 if there is a <body/> tag in the <rule/>,
                  0 otherwise.

  DefinedFrom() - returns 1 if there is a <from/> tag in the <rule/>,
                  0 otherwise.

  DefinedResource() - returns 1 if there is a <resource/> tag in the 
                      <rule/>, 0 otherwise.

  DefinedShow() - returns 1 if there is a <show/> tag in the <rule/>,
                  0 otherwise.

  DefinedSize() - returns 1 if there is a <size/> tag in the <rule/>,
                  0 otherwise.

  DefinedSubject() - returns 1 if there is a <subject/> tag in the 
                     <rule/>, 0 otherwise.

  DefinedTime() - returns 1 if there is a <time/> tag in the <rule/>,
                  0 otherwise.

  DefinedType() - returns 1 if there is a <type/> tag in the <rule/>,
                  0 otherwise.

  DefinedUnavailable() - returns 1 if there is a <unavailable/> tag 
                         in the <rule/>, 0 otherwise.

  DefinedDrop() - returns 1 if there is a <drop/> tag in the <rule/>,
                  0 otherwise.

  DefinedEdit() - returns 1 if there is a <edit/> tag in the <rule/>,
                  0 otherwise.

  DefinedError() - returns 1 if there is a <error/> tag in the <rule/>,
                  0 otherwise.

  DefinedForward() - returns 1 if there is a <forward/> tag in the <rule/>,
                  0 otherwise.

  DefinedOffline() - returns 1 if there is a <offline/> tag in the <rule/>,
                  0 otherwise.

  DefinedReply() - returns 1 if there is a <reply/> tag in the <rule/>,
                  0 otherwise.

  DefinedContinue() - returns 1 if there is a <continue/> tag in the <rule/>,
                  0 otherwise.

AUTHOR

By Ryan Eatmon in June 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.