Section Contents

 

 

Session Management
[Invoking Directory Operations]


Functions

DS_Status DS_Session_New (const char *address, int force_tls, DS_Session **session_p)
 Create an unbound directory session.
DS_Status DS_BindAnonymousSync (DS_Session *session, DS_CommonArgs *common_args, DS_Indication **indication_p)
 Perform an anonymous synchronous directory bind.
DS_Status DS_BindSync_Anonymous (const char *address, DS_Session **session_p)
 Perform an anonymous synchronous directory bind.
DS_Status DS_BindSimpleSync (DS_Session *session, const DS_DN *dn, const char *password, DS_CommonArgs *common_args, DS_Indication **indication_p)
 Perform a synchronous directory bind using simple credentials.
DS_Status DS_BindSync_Simple (const char *address, const DS_DN *dn, const char *password, DS_Session **session_p)
 Perform a synchronous directory bind using simple credentials.
DS_Status DS_BindStrongSync (DS_Session *session, const DS_DN *dsa_dn, const DS_DN *dn, const char *password, DS_CommonArgs *common_args, DS_Indication **indication_p)
 Perform a synchronous directory bind using strong credentials.
DS_Status DS_BindSync_Strong (const char *address, const DS_DN *dsa_dn, const DS_DN *dn, const char *password, DS_Session **session_p)
 Perform a synchronous directory bind using strong credentials.
DS_Status DS_BindSASLSync (DS_Session *session, const char *mechanism, const char *userid, const char *secret, DS_CommonArgs *common_args, DS_Indication **indication_p)
 Perform a synchronous directory bind using SASL.
DS_Status DS_BindSync_SASL (const char *address, const char *mechanism, const char *userid, const char *secret, DS_Session **session_p)
 Perform a synchronous directory bind using SASL.
void DS_UnbindSync (DS_Session **session_p)
 Perform a synchronous directory unbind.
DS_Status DS_AllowUnknownAttrs (DS_Session *session, int allow_unknown)
 Turn on or off the flag that allows unknown attributes to be read over LDAP.
DS_Status DS_GetAllowUnknownAttrs (DS_Session *session, int *allow_unknown_p)
 Get the values of the flag that allows unknown attributes to be read over LDAP.

Detailed Description

Methods used to create, authenticate, and delete a directory session.

The normal procedure is to create a session using DS_Session_New(), then bind using DS_BindAnonymousSync(), DS_BindSimpleSync(), DS_BindSASLSync() or DS_BindStrongSync(), perform other operations against the directory server, and then finally unbind and delete the session with DS_UnbindSync().

Function Documentation

DS_Status DS_Session_New ( const char *  address,
int  force_tls,
DS_Session **  session_p 
)

Create an unbound directory session.

If address is a presentation address (RFC 1278 format) then a DAP session will be created. If address is an LDAP URL (RFC 2255 format) or an LDAPS URL then an LDAPv3 session will be created.

Parameters:
address [in] Address of directory server.
force_tls [in] Set to 1 to force plain LDAP connections to use TLS (ignored for DAP connections and LDAPS connections).
session_p [out] Pointer to receive session pointer (on success).
Returns:
DSAPI function status code.
Since:
DSAPI_VERSION 2026

DS_Status DS_BindAnonymousSync ( DS_Session *  session,
DS_CommonArgs *  common_args,
DS_Indication **  indication_p 
)

Perform an anonymous synchronous directory bind.

Perform an anonymous bind on a directory session created by DS_Session_New(). Optionally, pass in any common arguments - a common use for this is to request password policy information.

Returns an indication of the bind success or failure.

Parameters:
session [in] Pointer to the directory session
common_args [in] Common arguments to directory operations
indication_p [out] Return result/error
Returns:
DSAPI function status code.
Since:
DSAPI_VERSION 2026

DS_Status DS_BindSync_Anonymous ( const char *  address,
DS_Session **  session_p 
)

Perform an anonymous synchronous directory bind.

If address is a presentation address (RFC 1278 format) then a DAP session will be created. If address is an LDAP URL (RFC 2255 format) or an LDAPS URL then an LDAPv3 session will be created.

Parameters:
address [in] Address of directory server.
session_p [out] Pointer to receive session pointer (on success).
Returns:
DSAPI function status code.
Deprecated:
Use DS_BindAnonymousSync() instead.
Examples:
anonymous.c, async.c, and read.c.

DS_Status DS_BindSimpleSync ( DS_Session *  session,
const DS_DN *  dn,
const char *  password,
DS_CommonArgs *  common_args,
DS_Indication **  indication_p 
)

Perform a synchronous directory bind using simple credentials.

Perform a simple bind on a directory session created by DS_Session_New(). Optionally, pass in any common arguments - a common use for this is to request password policy information.

Parameters:
session [in] Pointer to the directory session
dn [in] DN of user to connect as (NULL signifies anonymous)
password [in] Password of user to connects as (NULL signifies none)
common_args [in] Common arguments to directory operations
indication_p [out] Return result/error
Returns:
DSAPI function status code.
Since:
DSAPI_VERSION 2026

DS_Status DS_BindSync_Simple ( const char *  address,
const DS_DN *  dn,
const char *  password,
DS_Session **  session_p 
)

Perform a synchronous directory bind using simple credentials.

If address is a presentation address (RFC 1278 format) then a DAP session will be created. If address is an LDAP URL (RFC 2255 format) or an LDAPS URL then an LDAPv3 session will be created.

Parameters:
address [in] Address of directory server
dn [in] DN of user to connect as (NULL signifies anonymous)
password [in] Password of user to connects as (NULL signifies none)
session_p [out] Pointer to receive session pointer (on success)
Returns:
DSAPI function status code.
Deprecated:
Use DS_BindSimpleSync() instead.
Examples:
add.c, delete.c, modify.c, and simple.c.

DS_Status DS_BindStrongSync ( DS_Session *  session,
const DS_DN *  dsa_dn,
const DS_DN *  dn,
const char *  password,
DS_CommonArgs *  common_args,
DS_Indication **  indication_p 
)

Perform a synchronous directory bind using strong credentials.

Perform a strong bind on a directory session created by DS_Session_New(). Optionally, pass in any common arguments - a common use for this is to request password policy information.

If dn is not NULL, an identity must exist with the same subject name. If dn is NULL, a default identity will be used.

Parameters:
session [in] Pointer to the directory session
dsa_dn [in] DN of DSA to bind to
dn [in] DN of user to connect as (can be NULL)
password [in] Password used to decrypt the user's identity
common_args [in] Common arguments to directory operations
indication_p [out] Return result/error
Returns:
DSAPI function status code.
Since:
DSAPI_VERSION 2026

DS_Status DS_BindSync_Strong ( const char *  address,
const DS_DN *  dsa_dn,
const DS_DN *  dn,
const char *  password,
DS_Session **  session_p 
)

Perform a synchronous directory bind using strong credentials.

If address is a presentation address (RFC 1278 format) then a DAP session will be created. If address is an LDAP URL (RFC 2255 format) or an LDAPS URL then an LDAPv3 session will be created.

If dn is not NULL, an identity must exist with the same subject name. If dn is NULL, a default identity will be used.

Parameters:
address [in] Address of directory server
dsa_dn [in] DN of DSA to bind to
dn [in] DN of user to connect as (can be NULL)
password [in] Password used to decrypt the user's identity
session_p [out] Pointer to receive session pointer (on success)
Returns:
DSAPI function status code.
Since:
DSAPI_VERSION 2000
Deprecated:
Use DS_BindStrongSync() instead.

DS_Status DS_BindSASLSync ( DS_Session *  session,
const char *  mechanism,
const char *  userid,
const char *  secret,
DS_CommonArgs *  common_args,
DS_Indication **  indication_p 
)

Perform a synchronous directory bind using SASL.

Perform a SASL bind on a directory session created by DS_Session_New(). Optionally, pass in any common arguments - a common use for this is to request password policy information.

Currently SASL is not supported for DAP sessions.

Parameters:
session [in] Pointer to the directory session
mechanism [in] SASL mechanism to use (e.g. "DIGEST-MD5"), or NULL to allow the mechanism to be negotiated
userid [in] SASL userid to authenticate with (e.g. "user@example.com")
secret [in] SASL secret, or NULL if one is not required for the selected mechanism
common_args [in] Common arguments to directory operations
indication_p [out] Return result/error
Returns:
DSAPI function status code.
Since:
DSAPI_VERSION 2026

DS_Status DS_BindSync_SASL ( const char *  address,
const char *  mechanism,
const char *  userid,
const char *  secret,
DS_Session **  session_p 
)

Perform a synchronous directory bind using SASL.

If address is an LDAP URL (RFC 2255 format) or an LDAPS URL then an LDAPv3 session will be created. Currently SASL is not supported for DAP sessions.

Parameters:
address [in] Address of directory server
mechanism [in] SASL mechanism to use (e.g. "DIGEST-MD5"), or NULL to allow the mechanism to be negotiated
userid [in] SASL userid to authenticate with (e.g. "user@example.com")
secret [in] SASL secret, or NULL if one is not required for the selected mechanism
session_p [out] Pointer to receive session pointer (on success)
Returns:
DSAPI function status code.
Since:
DSAPI_VERSION 2022
Deprecated:
Use DS_BindSASLSync() instead.

void DS_UnbindSync ( DS_Session **  session_p  ) 

Perform a synchronous directory unbind.

Parameters:
session_p [in] Pointer to an open directory session (contents are freed)
Examples:
add.c, anonymous.c, async.c, delete.c, modify.c, read.c, and simple.c.

DS_Status DS_AllowUnknownAttrs ( DS_Session *  session,
int  allow_unknown 
)

Turn on or off the flag that allows unknown attributes to be read over LDAP.

Parameters:
session [in] DS_Session to modify
allow_unknown [in] Allow unknown attributes? (1 to allow, 0 to disallow)
Return values:
DS_E_NOERROR Success
DS_E_BADPARAM If session was NULL or allow_unknown was something other than 1 or 0.
Since:
DSAPI_VERSION 2018
By default, LDAP operations which return unknown attribute types (according to the local schema) will result in DS_E_BADATTRTYPE errors.

The "allow_unknown" flag may be used to override this behaviour: if set, then any such attributes will be returned as "unknown attributes", and will have a syntax of "octetstring".

Unknown attributes may be written to LDIF files, or used in subsequent LDAP operations to write data to the directory.

Unknown attributes will never be returned from a DAP session, and may not be written to a directory server over DAP.

DS_Status DS_GetAllowUnknownAttrs ( DS_Session *  session,
int *  allow_unknown_p 
)

Get the values of the flag that allows unknown attributes to be read over LDAP.

Parameters:
session [in] DS_Session to modify
allow_unknown_p [out] Variable to write result to
Return values:
DS_E_NOERROR Value was read successfully
DS_E_NOBADPARAM If session was NULL or allow_unknown_p was NULL
Since:
DSAPI_VERSION 2018

Copyright © 2008 Isode privacy   feedback Subscribe to our rss newsfeed