NAME

WARNING

SYNOPSIS

  use Net::LDAP::Express;

  eval {
    my $ldap =
      Net::LDAP::Express->new(host => 'localhost',
                              bindDN => 'cn=admin,ou=People,dc=me',
                              bindpw => 'secret',
                              base   => 'ou=People,dc=me',
                              searchattrs => [qw(cn uid loginname)],
                              %parms) ; # params for Net::LDAP::new
  } ;

  if ($@) {
    die "Can't connect to ldap server: $@" ;
  }

  my $filter = '(|(loginname=~bronto)(|(cn=~bronto)(uid=~bronto)))' ;
  my $entries ;
  # These all return the same array of Net::LDAP::Entry objects
  $entries = $ldap->search(filter => $filter) ; # uses new()'s base
  $entries = $ldap->search(base   => 'ou=People,dc=me',
                           filter => $filter) ;
  $entries = $ldap->simplesearch('bronto') ; # uses new()'s searchattrs

  # Now elaborate results:
  foreach my $entry (@$entries) {
    modify_something_in_this($entry) ;
  }

  # You often want to update a set of entries
  foreach my $entry (@$entries) {
    die "Error updating entry" unless defined $ldap->update($entry) ;
  }

  # but I think you'll prefer this way:
  my $result = $ldap->update(@$entries) ;
  unless (@$result == @$entries) {
    print "Error updating entries: ",$ldap->error,
          "; code ",$ldap->errcode,".\n\n" ;
  }

  # Add an entry, or an array of them, works as above:
  die $ldap->error unless $ldap->add_many(@some_other_entries) ;

  # rename an entry: sometimes you simply want to change a name
  # and nothing else...
  $ldap->rename($entry,$newrdn) ;

  # Ask for just a few attributes, sort results
  $ldap = Net::LDAP::Express->new(host        => $server,
                                  port        => $port,
                                  base        => $base,
                                  bindDN      => $binddn,
                                  bindpw      => $bindpw,
                                  onlyattrs   => \@only,
                                  sort_by     => \@sortby,
                                  searchattrs => \@search) ;
  my $entries = $ldap->simplesearch('person') ;

DESCRIPTION

Net::LDAP is a great module for working with directory servers, but it's a bit overkill when you want to do simple short scripts or have big programs that always do the same job again and again, say: open an authenticated connection to a directory server, search entries against the same attributes each time and in the same way (e.g.: approx search against the three attributes cn, uid and loginname). With Net::LDAP this would mean:

• connect to the directory server using new();
• authenticate with bind() ;
• compose a search filter, and pass it to search(), along with the base subtree;
• perform the search getting a Net::LDAP::Search object;
• verify that the search was successful using the code() or is_error() method on the search object;
• if the search was successful, extract the entries from the Search object, for example with entries or shift_entry.

With Net::LDAP::Express this is done with:

• connect, authenticate, define default search subtree and simple-search attributes with the new() method;
• pass the simplesearch method a search string to be matched against the attributes defined with searchattrs in new() and check the return value: if it was successful you have a reference to an array of Net::LDAP::Entry objects, if it was unsuccessful you get undef, and you can check what the error was with the error() method (or the error code with errcode) ;

CONSTRUCTOR

new(%parms)

Creates a Net::LDAP::Express object. Accepts all the parameters that are legal to Net::LDAP::new but the directory server name/address is specified via the "host" parameter. Specific Net::LDAP::Express parameters are therefore:

REDEFINED METHODS

search

search works exactly as Net::LDAP::search(), with a few changes:

NEW METHODS

add_many

Takes one or more Net::LDAP::Entry objects, returns a reference to an array of Net::LDAP::Entry objects that successfully made it on the directory server. You can check if every entry has been added by comparing the length of the input list against the length of the output list. Use the error and/or errorcode methods to see what went wrong.

delete_many

Works the same way as "add_many", but it deletes entries instead :-)

rename($entry,$newrdn)

Renames an entry; $entry can be a Net::LDAP::Entry or a DN, $newrdn is a new value for the RDN. Returns $entry for success, undef on failure.

update(@entries)

update takes a list of Net::LDAP::Entry objects as arguments and commits changes on the directory server. Returns a reference to an array of updated entries.

NOTE: if you want to modify an entry, say $e, remember to call "$e->changetype('modify')" on it before doing any changes; the defined changetype at object creation is "add" at the moment, which results in "update" trying to create new entries. This could be addressed by Net::LDAP::Express in the future, maybe.

simplesearch($searchstring)

Searches entries using the new()'s search* and base parameters. Takes a search string as argument. Returns a reference to an array of entries on success, undef on error.

error

Returns last error's name

errcode

Returns last error's code

AUTHOR

"sort_by" feature kindly suggested by John Woodell

Original patch for exact matching (code and documentation) was kindly contributed by Gordon Lack.

SEE ALSO