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.
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.
4 POD Errors
The following errors were encountered while parsing the POD:
- Around line 237:
'=item' outside of any '=over'
- Around line 259:
You forgot a '=back' before '=head1'
- Around line 264:
'=item' outside of any '=over'
- Around line 555:
You forgot a '=back' before '=head1'
You forgot a '=back' before '=head1'