## Access Control API Changes in ES 4.0

### 1, `ACL_LDAPDatabaseHandle()`

This function always logs an error message and returns LAS_EVAL_FAIL. Changes were made in ES 4.0 to support a pool of LDAP connections to each LDAP database defined in `dbswitch.conf`. This function could not be implemented under the new model, but two new functions, `ACL_LDAPSessionAllocate()` and `ACL_LDAPSessionFree()`, have been added to the Access Control API in ES 4.0. These are described below.

### 2. `ACL_LDAPSessionAllocate()`

This is a new function in ES 4.0, intended to provide the same functionality previously obtained from `ACL_LDAPDatabaseHandle()`. It allocates an LDAP connection to the specified LDAP database, returning a (LDAP *) handle for the connection, which can be used in calls to LDAP SDK functions. The caller is responsible for calling `ACL_LDAPSessionFree()` to return the connection to the pool of LDAP connections managed by the server. Upon a successful return, the returned LDAP connection is bound to the binddn specified in `dbswitch.conf`, if any, or anonymously bound otherwise. The caller may rebind the connection, if desired.

> Syntax:

> `#include <aclapi.h>`

> `NSAPI_PUBLIC`
> `int ACL_LDAPSessionAllocate(NSErr_t *errp, const char *dbname,`
> `LDAP **ld, const char **basedn)`

> Parameters:

> This function has the following parameters:

> `errp`

> > Pointer to the header for a list of error frames.

> `dbname`

> > Name of the LDAP database. If this argument is NULL, the default database is used.

> `ld`

> > Pointer to the returned connection handle to the LDAP server. If you are performing LDAP operations through LDAP API function calls, you need to pass this handle as an argument to the functions you call. This parameter must not be NULL.

> `basedn`

> > Pointer to the returned distinguished name (DN) of the root object in the LDAP directory (for example, o=Ace Industry,c=US). Note that unlike `ACL_LDAPDatabaseHandle()`, the returned value is a (`const char *`), which need not be freed by the caller, and which is valid until `ACL_LDAPSessionFree()` is called. This parameter may be NULL if the base DN is not needed.

> Returns:

> LAS_EVAL_TRUE if successful, or LAS_EVAL_FAIL if an error occurs.

> Example:

> See `lasemail.c`.

### 3. `ACL_LDAPSessionFree()`

This function is used to free an LDAP connection obtained from `ACL_LDAPSessionAllocate()` back to the LDAP connection pool from which it was allocated. Since LDAP connections are shared among all threads in the server, it is important to free a connection when there is no immediate use for it.

> Syntax:

> `#include <aclapi.h>```

> `void ACL_LDAPSessionFree(LDAP *ld)`

> Parameters:

> `ld`

> > This is the handle for the LDAP connection that was previously returned by `ACL_LDAPSessionAllocate()`.

> Returns:

> No value is returned.

> Example:

> See `lasemail.c`.

### 4. Handling of LAS_EVAL_FAIL

When an LAS plugin returns LAS_EVAL_FAIL in ES 4.0, this is taken to be indicative of a server configuration error, and "Server Error" is the response given to the client. It may be necessary to return LAS_EVAL_FALSE instead of LAS_EVAL_FAIL in some cases, to achieve the desired behavior.