NAME

Net::LDAPxs - XS version of Net::LDAP

SYNOPSIS

  use Net::LDAPxs;

  $ldap = Net::LDAPxs->new('www.example.com');

  $ldap->bind('cn=Manager,dc=example,dc=com', password => 'secret');

  $mesg = $ldap->search( base   => 'ou=language,dc=example,dc=com',
                         filter => '(|(cn=aperture)(cn=shutter_speed))'
                       );

  @entries = $mesg->entries();

  foreach my $entry (@entries) {
      foreach my $attr ($entry->attributes()) {
          foreach my $val ($entry->get_value($attr)) {
              print "$attr, $val\n";
          }
      }
  }

  $ldap->unbind;

DESCRIPTION

Net::LDAPxs is using XS code to glue LDAP C API Perl code. The purpose of developing this module is to thoroughly improve the performance of Net::LDAP. According to the simple test using Devel::NYTProf, it can enhance the performance by nearly 30 times. In order to benefit the migration from Net::LDAP to Net::LDAPxs, functions and user interfaces of Net::LDAPxs keep the same as Net::LDAP, which means people who migrate from Net::LDAP to Net::LDAPxs are able to leave their code unchanged excepting altering the module name.

CONSTRUCTOR

new ( HOST, OPTIONS )

HOST can be a host name or an IP address without path information.

port => ( number ) (Default: 389)

Port connect to the LDAP server.

scheme => 'ldap' | 'ldaps' | 'ldapi' (Default: ldap)

Example

  $ldap = Net::LDAPxs->new('www.example.com',
                           port    => '389',
                           scheme  => 'ldap',
                           version => 3
                          );

METHODS

Currently, not all methods of Net::LDAP are supported by Net::LDAPxs. Here is a list of implemented methods.

bind ( DN, OPTIONS )

async => 1

Perform the bind operation asynchronously.

Example

  $mesg = $ldap->bind('cn=Manager,dc=example,dc=com', password => 'secret');
  die $mesg->errstr if $mesg->err;

unbind ( )

Example

  $ldap->unbind;

search ( ID, OPTIONS )

base => ( DN )

A base option is a DN which is the start search point.

filter => ( a string )

A filter is a string which format complies the RFC1960. If no filter presents, the default value is (objectClass=top).

Example

  (cn=Babs Jensen)
  (!(cn=Tim Howes))
  (&(objectClass=Person)(|(sn=Jensen)(cn=Babs J*)))
  (o=univ*of*mich*)

scope => 'base' | 'one' | 'sub'

The default value is 'sub' which means it will search all subtrees. 'base' means only search the base object. 'one' means only search one level below the base object.

sizelimit => ( number )

A sizelimit is the maximum number of entries will be returned as a result of the search. The default value is 0, denots no restriction is applied.

attrs => ( attributes )

A list of attributes to be returned for each entry. The value is normally a reference to an array which contains the preferred attributes.

Example

  $mesg = $ldap->search( base      => 'ou=language,dc=example,dc=com',
                         filter    => '(|(cn=aperture)(cn=shutter_speed))',
                         scope     => 'one',
                         sizelimit => 0,
                         attrs     => \@attrs
                       );
  die $mesg->errstr if $mesg->err;

control => ( CONTROL )

A control is a reference to a HASH which may contain the three elements "type", "value" and "critical".

For more information see Net::LDAPxs::Control.

Example

  use Net::LDAPxs::Control;

  $ctrl = Net::LDAPxs::Control->new(
          type  => '1.2.840.113556.1.4.473',
          value => 'sn -cn',
          critical => 0
          );

  $msg = $ldap->search( base    => $base,
                        control => $ctrl );

compare ( DN, OPTIONS )

Compare values in an attribute in the entry given by DN on the server. DN is a string. If the compare is failed, errstr() method can be used to fetch the reason for the failure.

attrs => attributeType

The name of the attribute type to compare.

value => attributeValue

The attribute value to compare with.

Example

  $mesg = $ldap->compare( 'ou=people,dc=example,dc=com',
                          attr  => 'gidNumber',
                          value => '65534'
                        );
  die $mesg->errstr if $mesg->err;

add ( DN, OPTIONS )

Add a new entry to the LDAP directiory. DN is a string.

attrs => VALUE

VALUE should be a hash reference.

Example

  my %attrs = (
    uid => 'Lionel',
    cn  => 'Lionel',
    sn  => 'Luthor',
    uidNumber    => '65534',
    gidNumber    => '65534',
    homeDirectory => '/home/Lionel',
    loginShell  => '/bin/bash',
    objectClass => [qw(inetOrgPerson posixAccount top)]
  );

  $mesg = $ldap->add( 'uid=Lionel,ou=people,dc=example,dc=com',
                      attrs => \%attrs );
  die $mesg->errstr if $mesg->err;

delete ( DN )

Delete the entry given by DN from the server. DN is a string.

Example

  $mesg = $ldap->delete( 'uid=Lionel,ou=people,dc=example,dc=com' );
  die $mesg->errstr if $mesg->err;

moddn ( DN, OPTIONS )

Rename the entry given by DN which should be a string.

newrdn => RDN

This value should be a new RDN to assign to DN.

deleteoldrdn => 1

This option should be passed if the existing RDN is to be deleted.

newsuperior => NEWDN

If given this value should be the DN of the new superior for DN.

Example

  $mesg = $ldap->moddn( uid=Lionel,ou=people,dc=example,dc=com, 
                        newrdn => 'uid=Peter' );
  die $mesg->errstr if $mesg->err;

modify ( DN, OPTIONS )

Modify the contents of the entry given by DN which should be a string.

add => { ATTR => VALUE, ... }

Add more attributes or values to the entry. VALUE should be a string if only a single value is wanted in the attribute, or a reference to an array of strings if multiple values are wanted.

  %attrs = ( cn => ['buy', 'purchase'],
    description => 'to own something' );
  $mesg = $ldap->modify( $dn, add => \%attrs );
  die $mesg->errstr if $mesg->err;

delete => [ ATTR, ... ]

Delete complete attributes from the entry.

  # Delete attributes
  $mesg = $ldap->modify( $dn, delete => { description => [] } );
  die $mesg->errstr if $mesg->err;
  
  # Delete a group of attributes
  %attrs = (
      cn => ['Lex', 'Lionel'],
      sn => 'Luther'
  );
  $mesg = $ldap->modify( $dn, delete => \%attrs );

delete => { ATTR => VALUE, ... }

Delete individual values from an attribute. VALUE should be a string if only a single value is being deleted from the attribute, or a reference to an array of strings if multiple values are being deleted.

If VALUE is a reference to an empty array or all existing values of the attribute are being deleted, then the attribute will be deleted from the entry.

  $mesg = $ldap->modify( $dn,
    delete => {
      description => 'List of members',
      member      => [
        'cn=member1,ou=people,dc=example,dc=com',    # Remove members
        'cn=member2,ou=people,dc=example,dc=com',
      ],
      seeAlso => [],   # Remove attribute
    }
  );

replace => { ATTR => VALUE, ... }

Replace any existing values in each given attribute with VALUE. VALUE should be a string if only a single value is wanted in the attribute, or a reference to an array of strings if multiple values are wanted. A reference to an empty array will remove the entire attribute. If the attribute does not already exist in the entry, it will be created.

  $mesg = $ldap->modify( $dn,
    replace => {
      description => 'New List of members', # Change the description
      member      => [ # Replace whole list with these
        'cn=member1,ou=people,dc=example,dc=com',   
        'cn=member2,ou=people,dc=example,dc=com',
      ],
      seeAlso => [],   # Remove attribute
    }
  );

increment => { ATTR => VALUE, ... }

Atomically increment the existing value in each given attribute by the provided VALUE. The attributes need to have integer syntax, or be otherwise "incrementable". Note this will only work if the server advertizes support for LDAP_FEATURE_MODIFY_INCREMENT.

  $mesg = $ldap->modify( $dn,
    increment => {
      uidNumber => 1 # increase the uidNumber by 1
    }
  );

changes => [ OP => [ ATTR => VALUE ], ... ]

This is an alternative to add, delete, replace and increment where the whole operation can be given in a single argument. OP should be add, delete, replace or increment. VALUE should be either a string or a reference to an array of strings, as before.

Use this form if you want to control the order in which the operations will be performed.

  $mesg = $ldap->modify( $dn,
    changes => [
      add => [
        description => 'A description',
        member      => $newMember,
      ],
      delete => { seeAlso => [] },
      add => { anotherAttribute => $value },
    ]
  );

DEVELOPMENT STAGE

This module is currently in production. The advanced features will be available soon.

BUGS and RECOMMENDATIONS

Any bugs and recommendation is welcome. Please send directly to my email address listed below. Bugs and functions will be updated at least every one month.

ACKNOWLEDGEMENTS

A special thanks to Larry Wall <larry@wall.org> for convincing me that no development could be made to the Perl community without people's contribution.

AUTHOR

Pan Yu <xiaocong[AT]vip.163.com>

COPYRIGHT AND LICENSE

Copyright (C) 2008-2010 by Pan Yu. All rights reserved.

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