NAME

Net::DSML::filter.pm - A perl module that supplies a Net::DSML::Filter object that is used by a Net::DSML object.

VERSION

This document describes Net::DSML::filter version 0.002

SYNOPSIS

filter.pm - A perl module that supplies several different LDAP DSML filter types.

This module is used in conjunction with the Net::DSML module which does LDAP DSML queries to a LDAP directory server.

The DSML xml format is very strict and unforgiving of errors. Because of this I have made the calling of these filter methods strict also. The methods expect variables to be in a certain order.

Also methods are expected to be called in a certain order also.

The following is an example of building a simple subString filter.

 # Create the filter object.
 my $webfilter = Net::DSML::filter->new(debug => 1);

 # put the subString xml elements on the filter string
 $webfilter->subString( { type => "initial", 
                          attribute => "uid", 
                          value => "Bugs" } );

 # Get the resulting filter
 $filter = $webfilter->getFilter();

The following is an example of building a compound equalityMatch filter.

 # Create the filter object.
 my $webfilter = filter->new(debug => 1);

 # Put the <filter> element on the filter string
 $webfilter->start();  

 # Use the "and" to make compound filter
 $webfilter->and();
 
 # put the equalityMatch xml elements on the filter string
 $webfilter->equalityMatch({ attribute => "sn", 
                             value => "Bunny" } );

 # put the equalityMatch xml elements on the filter string
 $webfilter->equalityMatch( { attribute => "givenname", 
                               value => "jay" } );

 # Put the ending and </and> element on the filter string
 $webfilter->endand();

 # Put the </filter> element on the filter string
 $webfilter->terminate();

 # Get the resulting filter
 $filter = $webfilter->getFilter();

The following is an example of building a complex compound equalityMatch filter.

 # Create the filter object.
 my $webfilter = Net::DSML::filter->new(debug => 1);

 # Put the <filter> element on the filter string
 $webfilter->start();  

 # Use the "and" to make compound filter
 $webfilter->and();

 # put the equalityMatch xml elements on the filter string
 $webfilter->equalityMatch( { attribute => "sn", 
                              value => "Bunny" } );

 # Use the "not" to make more complex compound filter
 $webfilter->not();

 # put the equalityMatch xml elements on the filter string
 $webfilter->equalityMatch( { attribute => "givenname", 
                              value => "jay" } );

 # Put the ending not </not> element on the filter string
 $webfilter->endnot();

 # Put the ending and </and> element on the filter string
 $webfilter->endand();

 # Put the </filter> element on the filter string
 $webfilter->terminate();

 # Get the resulting filter
 $filter = $webfilter->getFilter();

By combining the and, or , and not methods you can make some very complex filters.

DESCRIPTION

The Net::DSML::filter module is used the build the DSML xml filter string that is the by the Net::DSML module when building a complete DSML xml string that will be send to a DSML http server that is usually located on a LDAP directory server.

INTERFACE

new ( {OPTIONS} )

The new method is the constructor for a new filter object.

Example: $filter = Net::DSML::filter->new({ debug => 1 } );

This method has 1 valid option, debug; value of 1 or 0. This will enable debug messages to be printed to standard out.

debug ( {OPTIONS} )

The method debug sets or returns the object debug flag.

If there is one required input option.

 Input option:  value 1 or 0.  Default is 0.

 $return = $dsml->debug( 1 );

Method output; Returns debug value.

error ()

The error method returns error message that is stored in the object. Any error message will be associated with the last filter module operation.

No input options.

Example: $filter->error();

getFilter ()

The getFilter method returns the last filter string that was created.

No input options.

Example: $filter->getFilter();

setFilter ( {OPTIONS} )

The setFilter method sets the objects filter string. This could be used as a base to continue building the filter string.

Example: $filter->setFilter($value);

There is 1 input option ($value): user created filter string.

reset ()

The reset method will reset the filter string to a null, or blank, value.

No input options.

Example: $filter->reset();

subString ( {OPTIONS} )

The method subString sets up a DSML substring filter.

There are 3 required input options.

 Input option "type":  String that contains the type of substring 
 search that is being preformed; final, any, initial.
 Input option "attribute": String that contains the attribute name 
 that controls the search.
 Input option  "value": String that contains the value of the 
 attribute.

 $return = $filter->subString( type => "initial, 
                               attribute => "cn", 
                               value => "Bugs Bunny" );