Qore openldap Module  1.0
 All Classes Namespaces Functions Variables Groups
OpenLdap::LdapClient Class Reference

The LdapClient class. More...

List of all members.

Public Member Functions

nothing add (string dn, hash attrs, *timeout timeout_ms)
 add ldap an entry and attributes
 bind (hash bind, *timeout timeout_ms)
 bind to the server with the given authentication parameters
bool compare (string dn, string attr, softlist vals, *timeout timeout_ms)
 check ldap attribute values; if any errors occur (entry does not exist, etc), an LDAP-ERROR exception will be thrown
 constructor (string uri, *hash options)
 Creates a new LdapClient object and establishes a connection to the server with optional bind parameters.
 copy ()
 Creates a new LdapClient object based on the original.
nothing del (string dn, *timeout timeout_ms)
 delete ldap entries; if any errors occur (entry does not exist, etc), an LDAP-ERROR exception will be thrown
 destructor ()
 unbinds from the LDAP server (if a connection has been established) and destroys the object
string getUri ()
 returns the URI string used to connect to the LDAP server
bool isSecure ()
 returns True if the connection to the server is secure, False if not
nothing modify (string dn, softlist mods, *timeout timeout_ms)
 modify (add, replace, delete) ldap attributes; if any errors occur (entry does not exist, etc), an LDAP-ERROR exception will be thrown
nothing passwd (string dn, string oldpwd, string newpwd, *timeout timeout_ms)
 changes the LDAP password of a user
nothing rename (string dn, string newrdn, string newparent, softbool deleteoldrdn=True, *timeout timeout_ms)
 renames entries in the Directory Information Tree
hash search (hash h, *timeout timeout_ms)
 performs a search on the LDAP server

Static Public Member Functions

static getInfo ()
 Returns a hash with information about the openldap library.

Detailed Description

The LdapClient class.

Restrictions:
Qore::PO_NO_NETWORK

Member Function Documentation

nothing OpenLdap::LdapClient::add ( string  dn,
hash  attrs,
*timeout  timeout_ms 
)

add ldap an entry and attributes

Give the new entry's objectclass as an attribute; an attribute value can be a list to add multiple values to an attribute

Example:
$ldap.add("uid=temp,ou=people,dc=example,dc=com", ("objectclass": "inetorgperson", "sn": "Test", "cn": "test test"));
Parameters:
dnthe distinguished name of the entry to add
attrsa hash of new attributes; the keys are attribute names and the values are the attribute values
timeout_ms,:an optional timeout in milliseconds (1/1000 second); if no timeout is given or a timeout of 0 is given, the default timeout for the LdapClient object is used instead; note that like all Qore functions and methods taking timeout values, a relative date/time value can be used to make the units clear (i.e. 20s = twenty seconds, etc.); integers are treated as values in milliseconds, relative date/time values have a maximum resolution of 1 millisecond
Note:
strings are converted to UTF-8 before sending to the server if necessary
Exceptions:
LDAP-NO-CONTEXTthe LDAP session is not connected or the session context is not bound
LDAP-ADD-ERRORmissing attribute value
LDAP-ERRORan error occurred performing the add operation
ENCODING-CONVERSION-ERRORthis exception could be thrown if there is an error converting any string's encoding to UTF-8 before sending to the server
OpenLdap::LdapClient::bind ( hash  bind,
*timeout  timeout_ms 
)

bind to the server with the given authentication parameters

The current session is disconnected before binding again.

Example:
$ldap.bind($h);
Parameters:
binda hash of bind parameters, allowed keys are:
  • binddn: the dinstinguished name to use to bind to the LDAP server
  • password: the password to use for the connection
timeout_ms,:an optional timeout in milliseconds (1/1000 second); if no timeout is given or a timeout of 0 is given, the default timeout for the LdapClient object is used instead; note that like all Qore functions and methods taking timeout values, a relative date/time value can be used to make the units clear (i.e. 20s = twenty seconds, etc.); integers are treated as values in milliseconds, relative date/time values have a maximum resolution of 1 millisecond
Note:
strings are converted to UTF-8 before sending to the server if necessary
Exceptions:
LDAP-NO-CONTEXTthe LDAP session is not connected or the session context is not bound
LDAP-BIND-ERRORparameter type error or 'password' given with no 'binddn' value
LDAP-ERRORan error occurred performing the bind
ENCODING-CONVERSION-ERRORthis exception could be thrown if there is an error converting any string's encoding to UTF-8 before sending to the server
bool OpenLdap::LdapClient::compare ( string  dn,
string  attr,
softlist  vals,
*timeout  timeout_ms 
)

check ldap attribute values; if any errors occur (entry does not exist, etc), an LDAP-ERROR exception will be thrown

Example:
my bool $b = $ldap.compare("uid=temp,ou=people,dc=example,dc=com", "uidnumber", 1000);
Parameters:
dnthe distinguished name of the entry to find for the attribute value comparison
attrthe name of the attribute for the value comparison
valsa single string or a list of strings of values to compare; if any value is not a string it will be converted to a string
timeout_ms,:an optional timeout in milliseconds (1/1000 second); if no timeout is given or a timeout of 0 is given, the default timeout for the LdapClient object is used instead; note that like all Qore functions and methods taking timeout values, a relative date/time value can be used to make the units clear (i.e. 20s = twenty seconds, etc.); integers are treated as values in milliseconds, relative date/time values have a maximum resolution of 1 millisecond
Returns:
True if the value(s) match, False if not
Note:
strings are converted to UTF-8 before sending to the server if necessary
Exceptions:
LDAP-NO-CONTEXTthe LDAP session is not connected or the session context is not bound
LDAP-ERRORan error occurred performing the comparison operation
ENCODING-CONVERSION-ERRORthis exception could be thrown if there is an error converting any string's encoding to UTF-8 before sending to the server
OpenLdap::LdapClient::constructor ( string  uri,
*hash  options 
)

Creates a new LdapClient object and establishes a connection to the server with optional bind parameters.

A connection to the server is made with an empty search request even if no bind parameters are given. To ensure that a secure TLS connection is made to the server regardless of the scheme given in the URI, set the "starttls" argument to True.

Example:
my LdapClient $ldap("ldaps://ldap.example.com:389", ("starttls": True, "timeout": 20s));

Each LdapClient object represents a connection to the server. Individual requests are wrapped in mutual exclusion locks to ensure atomicity and thread-safety, therefore if sharing a single LdapClient object between multiple threads, simultaneous requests will block if another request is already in progress.

Parameters:
urithe URI of the ldap server (ex: "ldaps://ldap.example.com")
optionsan optional hash of optional parameters, allowed keys are:
  • binddn: the dinstinguished name to use to bind to the LDAP server
  • password: the password to use for the connection
  • timeout: the default timeout for ldap operations; note that like all Qore functions and methods taking timeout values, a relative date/time value can be used to make the units clear (i.e. 20s = twenty seconds, etc.); integers are treated as values in milliseconds, relative date/time values have a maximum resolution of 1 millisecond
  • no-referrals: (boolean) do not follow referrals (the default is to follow referrals)
  • starttls: (boolean) if set, then a STARTTLS command will be executed if a secure connection is not already established; note that setting this option will ensure a secure connection regardless of the scheme in the URI. If a secure connection has already been established (for example by using a "ldaps" scheme in the URI), then this parameter is ignored
Note:
If no "timeout" option is given, a default timeout value of 60 seconds is set automatically
strings are converted to UTF-8 before sending to the server if necessary
Exceptions:
LDAP-ERRORan error occurred creating the ldap session context
ENCODING-CONVERSION-ERRORthis exception could be thrown if there is an error converting any string's encoding to UTF-8 before sending to the server
OpenLdap::LdapClient::copy ( )

Creates a new LdapClient object based on the original.

Example:
my LdapClient $ldap2 = $ldap.copy();
Exceptions:
LDAP-ERRORan error occurred copying the ldap session context
nothing OpenLdap::LdapClient::del ( string  dn,
*timeout  timeout_ms 
)

delete ldap entries; if any errors occur (entry does not exist, etc), an LDAP-ERROR exception will be thrown

Example:
$ldap.del("uid=temp,ou=people,dc=example,dc=com");
Parameters:
dnthe distinguished name of the entry to delete
timeout_ms,:an optional timeout in milliseconds (1/1000 second); if no timeout is given or a timeout of 0 is given, the default timeout for the LdapClient object is used instead; note that like all Qore functions and methods taking timeout values, a relative date/time value can be used to make the units clear (i.e. 20s = twenty seconds, etc.); integers are treated as values in milliseconds, relative date/time values have a maximum resolution of 1 millisecond
Note:
strings are converted to UTF-8 before sending to the server if necessary
Exceptions:
LDAP-NO-CONTEXTthe LDAP session is not connected or the session context is not bound
LDAP-ERRORan error occurred performing the delete operation
ENCODING-CONVERSION-ERRORthis exception could be thrown if there is an error converting any string's encoding to UTF-8 before sending to the server
OpenLdap::LdapClient::destructor ( )

unbinds from the LDAP server (if a connection has been established) and destroys the object

Example:
delete $ldap;
static OpenLdap::LdapClient::getInfo ( )
static

Returns a hash with information about the openldap library.

Code Flags:
CONSTANT
Returns:
a hash with information about the openldap library with the following keys:
  • ApiVersion: the API version number
  • Protocol: the protocol number
  • VendorName: the vendor of the library
  • VendorVersion: the version of the library
  • Extensions: a list of extensions supported (strings)
  • ApiFeature: a hash with a single key; the API feature name, where the value is the feature version
string OpenLdap::LdapClient::getUri ( )

returns the URI string used to connect to the LDAP server

Code Flags:
CONSTANT
Example:
my string $uri = $ldap.getUri();
Returns:
the URI string used to connect to the LDAP server
bool OpenLdap::LdapClient::isSecure ( )

returns True if the connection to the server is secure, False if not

Code Flags:
RET_VALUE_ONLY
Example:
my bool $b = $ldap.isSecure();
Returns:
True if the connection to the server is secure, False if not
Exceptions:
LDAP-NO-CONTEXTthe LDAP session is not connected or the session context is not bound
nothing OpenLdap::LdapClient::modify ( string  dn,
softlist  mods,
*timeout  timeout_ms 
)

modify (add, replace, delete) ldap attributes; if any errors occur (entry does not exist, etc), an LDAP-ERROR exception will be thrown

Example:
$ldap.modify("uid=temp,ou=people,dc=example,dc=com", ("mod": LDAP_MOD_ADD, "attr": "someattr", "value": "new-value"));
Parameters:
dnthe distinguished name of the entry to modify
modsa hash or list of hashes of modifications to make; each hash is made up of the following keys:
  • mod: a modification action; see LDAP Modify Constants for possible values
  • attr: the attribute to modify
  • [value]: the value to add or replace
timeout_ms,:an optional timeout in milliseconds (1/1000 second); if no timeout is given or a timeout of 0 is given, the default timeout for the LdapClient object is used instead; note that like all Qore functions and methods taking timeout values, a relative date/time value can be used to make the units clear (i.e. 20s = twenty seconds, etc.); integers are treated as values in milliseconds, relative date/time values have a maximum resolution of 1 millisecond
Note:
strings are converted to UTF-8 before sending to the server if necessary
Exceptions:
LDAP-NO-CONTEXTthe LDAP session is not connected or the session context is not bound
LDAP-MODIFY-ERRORinvalid mod hash format; missing value for add or replace operation
LDAP-ERRORan error occurred performing the modify operation
ENCODING-CONVERSION-ERRORthis exception could be thrown if there is an error converting any string's encoding to UTF-8 before sending to the server
nothing OpenLdap::LdapClient::passwd ( string  dn,
string  oldpwd,
string  newpwd,
*timeout  timeout_ms 
)

changes the LDAP password of a user

Example:
$ldap.passwd("uid=test,ou=people,dc=example,dc=com", "oldpwd", "newpwd");
Parameters:
dnthe distinguished name of the user whose password to change
oldpwdthe old password
newpwdthe new password
timeout_ms,:an optional timeout in milliseconds (1/1000 second); if no timeout is given or a timeout of 0 is given, the default timeout for the LdapClient object is used instead; note that like all Qore functions and methods taking timeout values, a relative date/time value can be used to make the units clear (i.e. 20s = twenty seconds, etc.); integers are treated as values in milliseconds, relative date/time values have a maximum resolution of 1 millisecond
Note:
strings are converted to UTF-8 before sending to the server if necessary
Exceptions:
LDAP-NO-CONTEXTthe LDAP session is not connected or the session context is not bound
LDAP-ERRORan error occurred performing the password change operation
ENCODING-CONVERSION-ERRORthis exception could be thrown if there is an error converting any string's encoding to UTF-8 before sending to the server
nothing OpenLdap::LdapClient::rename ( string  dn,
string  newrdn,
string  newparent,
softbool  deleteoldrdn = True,
*timeout  timeout_ms 
)

renames entries in the Directory Information Tree

Example:
$ldap.rename("uid=test,ou=people,dc=example,dc=com", "uid=test1", "ou=people,dc=example,dc=com");
Parameters:
dnthe distinguished name of the entry to rename
newrdnthe new relative distinguished name of the entry
newparentthe distinguished name of the entry's new parent
deleteoldrdnif this argument is False, then the old relative distinguished name will be maintained along with the new name, if True (the default), then the old attributes are deleted
timeout_ms,:an optional timeout in milliseconds (1/1000 second); if no timeout is given or a timeout of 0 is given, the default timeout for the LdapClient object is used instead; note that like all Qore functions and methods taking timeout values, a relative date/time value can be used to make the units clear (i.e. 20s = twenty seconds, etc.); integers are treated as values in milliseconds, relative date/time values have a maximum resolution of 1 millisecond
Note:
strings are converted to UTF-8 before sending to the server if necessary
Exceptions:
LDAP-NO-CONTEXTthe LDAP session is not connected or the session context is not bound
LDAP-ERRORan error occurred performing the rename operation
ENCODING-CONVERSION-ERRORthis exception could be thrown if there is an error converting any string's encoding to UTF-8 before sending to the server
hash OpenLdap::LdapClient::search ( hash  h,
*timeout  timeout_ms 
)

performs a search on the LDAP server

Example:
my hash $h = $ldap.search(("base": "dc=example,dc=cp,", "filter": "(objectClass=*)", "attributes": "uid");
Parameters:
ha hash of search options with one or more of the following keys:
  • "base": the search base distinguished name for the search (ex: "dc=example,dc=com")
  • "filter": the search filter (ex: "(objectClass=*)")
  • "attributes": one or more attribute names; if this is present then only the given attributes will be returned
  • "scope": an integer giving the search scope; see LDAP Search Scope Constants for allowed values; note that if this key value is not present then LDAP_SCOPE_SUBTREE is used
timeout_ms,:an optional timeout in milliseconds (1/1000 second); if no timeout is given or a timeout of 0 is given, the default timeout for the LdapClient object is used instead; note that like all Qore functions and methods taking timeout values, a relative date/time value can be used to make the units clear (i.e. 20s = twenty seconds, etc.); integers are treated as values in milliseconds, relative date/time values have a maximum resolution of 1 millisecond
Returns:
a hash of the return value of the search; the hash is empty if no search results are available; the hash is keyed by Distinguished Names; each value is also a hash of attributes and attribute values
Note:
strings are converted to UTF-8 before sending to the server if necessary
Exceptions:
LDAP-NO-CONTEXTthe LDAP session is not connected or the session context is not bound
LDAP-ERRORan error occurred performing the search
ENCODING-CONVERSION-ERRORthis exception could be thrown if there is an error converting any string's encoding to UTF-8 before sending to the server

The documentation for this class was generated from the following file: