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" );

Method output; Returns true on success; false on error, error message can be gotten with error property.

present ( {OPTIONS} )

The method present sets up a DSML present filter.

There is 1 required input option.

 Input option "attribute": String that contains the attribute name 
 that controls the search.

 $return = $filter->present(  { attribute => "cn" } );

Method output; Returns true on success; false on error, error message can be gotten with error property.

equalityMatch ( {OPTIONS} )

The method equalityMatch sets up a DSML equality match filter.

There are 2 required input options.

 Input option "attribute": String that contains the attribute name 
 that controls the search.
 Input option  "value": String that contains the attribute value.

 $return = $filter->equalityMatch( { attribute => "sn", 
                                     value => "Bunny"  } );

Method output; Returns true on success; false on error, error message can be gotten with error property.

greaterOrEqual ( {OPTIONS} )

The method greaterOrEqual sets up a DSML greater or equal filter.

There are 2 required input options.

 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->greaterOrEqual( { attribute => "uid", 
                                      value => "bugs" } );

Method output; Returns true on success; false on error, error message can be gotten with error property.

lessOrEqual ( {OPTIONS} )

The method lessOrEqual sets up a DSML less or equal filter.

There are 2 required input options.

 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->lessOrEqual( { attribute => "uid", 
                                   value => "turkey" } );

Method output; Returns true on success; false on error, error message can be gotten with error property.

approxMatch ( {OPTIONS} )

The method approxMatch sets up a DSML approximate match filter.

There are 2 required input options.

 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->approxMatch( { attribute => "uid", 
                                   value => "bird" } );

Method output; Returns true on success; false on error, error message can be gotten with error property.

extensibleMatch ( {OPTIONS} )

The method extensibleMatch sets up a DSML extensibleMatch filter.

There is 1 required input options. There are 3 required optional options.

 $return = $filter->extensibleMatch( { value =>" ",
                                       name => " ",
                                       matchingRule => " ",
                                       dnAttributes => " " } );

Method output; Returns true on success; false on error, error message can be gotten with error property.

Input option "value": String that contains the value of the attribute. Required. Input option "matchingRule": String that contains the value of the matchingRule. Optional. Input option "dnAttributes": String that contains the boolean value of true or false. Optional. Input option "name": String that contains the name string. Optional.

or ()

The method or sets up a beginning or element of a DSML or filter.

There are no required input options.

$return = $filter->or();

Method output; Always returns true for success.

endor ()

The method endor sets up a ending or element of a DSML or filter.

There are no required input options.

$return = $filter->endor();

Method output; Always returns true for success.

and ()

The method and sets up a beginning and element of a DSML and filter.

There are no required input options.

$return = $filter->and();

Method output; Always return true for success.

endand ()

The method endand sets up a ending and element of a DSML and filter.

There are no required input options.

$return = $filter->endand();

Method output; Always returns true for success.

not ()

The method not sets up a beginning not element of a DSML not filter.

There are no required input options.

$return = $filter->not();

Method output; Always return true for success.

endnot ()

The method endnot sets up the ending not element of a DSML not filter.

There are no required input options.

$return = $filter->endnot();

Method output; Always returns true for success.

DIAGNOSTICS

All of the error messages should be self explantory.

Error message here, perhaps with %s placeholders

[Description of error here]

Another error message here

[Description of error here]

[Et cetera, et cetera]

CONFIGURATION AND ENVIRONMENT

Net::DSML::filter requires no configuration files or environment variables.

DEPENDENCIES

This module depends on the following modules.

INCOMPATIBILITIES

None known or reported.

BUGS AND LIMITATIONS

No known limitations. No bugs have been reported.

Please report any bugs or feature requests to bug-net-clif@rt.cpan.org, or through the web interface at http://rt.cpan.org.

GENERAL

Since the script is in PERL, feel free to modify it if it does not meet your needs. This is one of the main reasons I did it in PERL. If you make an addition to the code that you feel other individuals could use let me know about it. I may incorporate your code into my code.

AUTHOR

Clif Harden <charden@pobox.com>

LICENCE AND COPYRIGHT

Copyright (c) 2006, Clif Harden <charden@pobox.com>. All rights reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic.

DISCLAIMER OF WARRANTY

BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.