 |
OpenVMS Utility Routines Manual
12.8 Closing the Session
The following functions are used to unbind from the directory, close
the connection, and dispose of the session handle.
int ldap_unbind( LDAP *ld );
int ldap_unbind_s( LDAP *ld );
|
Parameter is as follows:
The
ldap_unbind()
and
ldap_unbind_s()
functions both work synchronously, unbinding from the directory,
closing the connection, and freeing up the ld structure before
returning. There is no server response to an unbind operation. The
ldap_unbind()
function returns LDAP_SUCCESS (or another LDAP error code if the
request cannot be sent to the LDAP server). After a call to
ldap_unbind()
or
ldap_unbind_s()
, the session handle ld is invalid and it is illegal to make any
further LDAP API calls using ld.
12.9 Searching
The following functions are used to search the LDAP directory,
returning a requested set of attributes for each entry matched. There
are five variations.
int ldap_search_ext(
LDAP *ld,
const char *base,
int scope,
const char *filter,
char **attrs,
int attrsonly,
LDAPControl **serverctrls,
LDAPControl **clientctrls,
struct timeval *timeout,
int sizelimit,
int *msgidp
);
int ldap_search_ext_s(
LDAP *ld,
const char *base,
int scope,
const char *filter,
char **attrs,
int attrsonly,
LDAPControl **serverctrls,
LDAPControl **clientctrls,
struct timeval *timeout,
int sizelimit,
LDAPMessage **res
);
int ldap_search(
LDAP *ld,
const char *base,
int scope,
const char *filter,
char **attrs,
int attrsonly
);
int ldap_search_s(
LDAP *ld,
const char *base,
int scope,
const char *filter,
char **attrs,
int attrsonly,
LDAPMessage **res
);
int ldap_search_st(
LDAP *ld,
char *base,
int scope,
char *filter,
char **attrs,
int attrsonly,
struct timeval *timeout,
LDAPMessage **res
);
|
Parameters are as follows:
|
ld
|
The session handle.
|
|
base
|
The dn of the entry at which to start the search.
|
|
scope
|
One of LDAP_SCOPE_BASE (0x00), LDAP_SCOPE_ONELEVEL (0x01), or
LDAP_SCOPE_SUBTREE (0x02), indicating the scope of the search.
|
|
filter
|
A character string representing the search filter. The value NULL can
be passed to indicate that the filter (objectclass=*) that matches all
entries should be used.
|
|
attrs
|
A NULL-terminated array of strings indicating which attributes to
return for each matching entry. Passing NULL for this parameter causes
all available user attributes to be retrieved. The special constant
string LDAP_NO_ATTRS (1.1) can be used as the only element in the array
to indicate that no attribute types should be returned by the server.
The special constant string LDAP_ALL_USER_ATTRS (*), can be used in the
attrs array along with the names of some operational attributes to
indicate that all user attributes plus the listed operational
attributes should be returned.
|
|
attrsonly
|
A boolean value that should be either zero if both attribute types and
values are to be returned or non-zero if only types are wanted.
|
|
timeout
|
For the
ldap_search_st()
function, this specifies the local search timeout value (if it is NULL,
the timeout is infinite). For the
ldap_search_ext()
and
ldap_search_ext_s()
functions, this specifies both the local search timeout value and the
operation time limit that is sent to the server within the search
request. For the
ldap_search_ext()
and
ldap_search_ext_s()
functions, passing a NULL value for timeout causes the global default
timeout stored in the LDAP session handle to be used (set using
ldap_set_option()
with the LDAP_OPT_TIMELIMIT parameter).
|
|
sizelimit
|
For the
ldap_search_ext()
and
ldap_search_ext_s()
calls, this is a limit on the number of entries to return from the
search. A value of LDAP_NO_LIMIT (0) means no limit.
|
|
res
|
For the synchronous calls, this is a result parameter which will
contain the results of the search upon completion of the call.
|
|
serverctrls
|
List of LDAP server controls.
|
|
clientctrls
|
List of client controls.
|
|
msgidp
|
This result parameter will be set to the message id of the request if
the
ldap_search_ext()
call succeeds.
|
There are three options in the session handle ld that potentially
affect how the search is performed. They are as follows:
|
LDAP_OPT_SIZELIMIT
|
A limit on the number of entries to return from the search. A value of
LDAP_NO_LIMIT (0) means no limit. Note that the value from the session
handle is ignored when using the
ldap_search_ext()
or
ldap_search_ext_s()
functions.
|
|
LDAP_OPT_TIMELIMIT
|
A limit on the number of seconds to spend on the search. A value of
LDAP_NO_LIMIT (0) means no limit. Note that the value from the session
handle is ignored when using the
ldap_search_ext()
or
ldap_search_ext_s()
functions.
|
|
LDAP_OPT_DEREF
|
One of LDAP_DEREF_NEVER(0x00), LDAP_DEREF_SEARCHING(0x01),
LDAP_DEREF_FINDING (0x02), or LDAP_DEREF_ALWAYS (0x03), specifying how
aliases should be handled during the search. The LDAP_DEREF_SEARCHING
value means aliases should be dereferenced during the search but not
when locating the base object of the search. The LDAP_DEREF_FINDING
value means aliases should be dereferenced when locating the base
object but not during the search.
|
The
ldap_search_ext()
function initiates an asynchronous search operation and returns either
the constant LDAP_SUCCESS if the request was successfully sent or
another LDAP error code if not. See Section 12.18 for more information
about possible errors and how to interpret them. If successful,
ldap_search_ext()
places the message id of the request in *msgidp. A subsequent call to
ldap_result()
can be used to obtain the results from the search. These results can be
parsed using the result parsing functions described in Section 12.18.
Similar to
ldap_search_ext()
, the
ldap_search()
function initiates an asynchronous search operation and returns the
message id of the operation initiated. As for
ldap_search_ext()
, a subsequent call to
ldap_result()
can be used to obtain the result of the bind. In case of error,
ldap_search()
will return -1, setting the session error parameters in the LDAP
structure appropriately.
The synchronous
ldap_search_ext_s()
,
ldap_search_s()
, and
ldap_search_st()
functions all return the result of the operation, either the constant
LDAP_SUCCESS if the operation was successful or another LDAP error code
if it was not. See Section 12.18 for more information about possible
errors and how to interpret them. Entries returned from the search (if
any) are contained in the res parameter. This parameter is opaque to
the caller. Entries, attributes, and values should be extracted by
calling the parsing functions. The results contained in res should be
freed when no longer in use by calling
ldap_msgfree()
.
The
ldap_search_ext()
and
ldap_search_ext_s()
functions support LDAPv3 server controls, client controls, and allow
varying size and time limits to be easily specified for each search
operation. The
ldap_search_st()
function is identical to
ldap_search_s()
except that it takes an additional parameter specifying a local timeout
for the search. The local search timeout is used to limit the amount of
time the API implementation will wait for a search to complete. After
the local search timeout the search operation will return LDAP_TIMEOUT
if the search result has not been removed.
12.9.1 Reading and Listing the Children of an Entry
LDAP does not support a read operation directly. Instead, this
operation is emulated by a search with base set to the DN of the entry
to read, scope set to LDAP_SCOPE_BASE, and filter set to
"(objectclass=*)" or NULL. The attrs parameter contains the list of
attributes to return.
LDAP does not support a list operation directly. Instead, this
operation is emulated by a search with base set to the DN of the entry
to list, scope set to LDAP_SCOPE_ONELEVEL, and filter set to
"(objectclass=*)" or NULL. The attrs parameter contains the list of
attributes to return for each child entry.
12.10 Comparing a Value Against an Entry
The following functions are used to compare a given attribute value
assertion against an LDAP entry. There are four variations.
int ldap_compare_ext(
LDAP *ld,
const char *dn,
const char *attr,
const struct berval *bvalue
LDAPControl **serverctrls,
LDAPControl **clientctrls,
int *msgidp
);
int ldap_compare_ext_s(
LDAP *ld,
const char *dn,
const char *attr,
const struct berval *bvalue,
LDAPControl **serverctrls,
LDAPControl **clientctrls
);
int ldap_compare(
LDAP *ld,
const char *dn,
const char *attr,
const char *value
);
int ldap_compare_s(
LDAP *ld,
const char *dn,
const char *attr,
const char *value
);
|
Parameters are as follows:
|
ld
|
The session handle.
|
|
dn
|
The name of the entry to compare against.
|
|
attr
|
The attribute to compare against.
|
|
bvalue
|
The attribute value to compare against those found in the given entry.
This parameter is used in the extended functions and is a pointer to a
struct berval so it is possible to compare binary values.
|
|
value
|
A string attribute value to compare against, used by the
ldap_compare()
and
ldap_compare_s()
functions. Use
ldap_compare_ext()
or
ldap_compare_ext_s()
if you need to compare binary values.
|
|
serverctrls
|
List of LDAP server controls.
|
|
clientctrls
|
List of client controls.
|
|
msgidp
|
This result parameter will be set to the message id of the request if
the
ldap_compare_ext()
call succeeds. The
ldap_compare_ext()
function initiates an asynchronous compare operation and returns either
the constant LDAP_SUCCESS if the request was successfully sent, or
another LDAP error code if not. See Section 12.18 for more information
about possible errors and how to interpret them. If successful,
ldap_compare_ext()
places the message id of the request in *msgidp. A subsequent call to
ldap_result()
can be used to obtain the result of the compare.
|
Similar to
ldap_compare_ext()
, the
ldap_compare()
function initiates an asynchronous compare operation and returns the
message id of the operation initiated. As for
ldap_compare_ext()
, a subsequent call to
ldap_result()
can be used to obtain the result of the bind. In case of error,
ldap_compare()
will return -1, setting the session error parameters in the LDAP
structure appropriately.
The synchronous
ldap_compare_ext_s()
and
ldap_compare_s()
functions both return the result of the operation, either the constants
LDAP_COMPARE_TRUE or LDAP_COMPARE_FALSE if the operation was
successful, or another LDAP error code if it was not. See Section 12.18
for more information about possible errors and how to interpret them.
The
ldap_compare_ext()
and
ldap_compare_ext_s()
functions support LDAPv3 server controls and client controls.
12.11 Modifying an Entry
The following functions are used to modify an existing LDAP entry.
There are four variations.
typedef struct ldapmod {
int mod_op;
char *mod_type;
union {
char **modv_strvals;
struct berval **modv_bvals;
} mod_vals;
} LDAPMod;
#define mod_values mod_vals.modv_strvals
#define mod_bvalues mod_vals.modv_bvals
int ldap_modify_ext(
LDAP *ld,
const char *dn,
LDAPMod **mods,
LDAPControl **serverctrls,
LDAPControl **clientctrls,
int *msgidp
);
int ldap_modify_ext_s(
LDAP *ld,
const char *dn,
LDAPMod **mods,
LDAPControl **serverctrls,
LDAPControl **clientctrls
);
int ldap_modify(
LDAP *ld,
const char *dn,
LDAPMod **mods
);
int ldap_modify_s(
LDAP *ld,
const char *dn,
LDAPMod **mods
);
|
Parameters are as follows:
|
ld
|
The session handle.
|
|
dn
|
The name of the entry to modify.
|
|
mods
|
A NULL-terminated array of modifications to make to the entry.
|
|
serverctrls
|
List of LDAP server controls.
|
|
clientctrls
|
List of client controls.
|
|
msgidp
|
This result parameter will be set to the message id of the request if
the
ldap_modify_ext()
call succeeds.
|
The fields in the LDAPMod structure have the following meanings:
|
mod_op
|
The modification operation to perform. It should be one of
LDAP_MOD_ADD(0x00), LDAP_MOD_DELETE (0x01), or LDAP_MOD_REPLACE(0x02).
This field also indicates the type of values included in the mod_vals
union. It is logically ORed with LDAP_MOD_BVALUES (0x80) to select the
mod_bvalues form. Otherwise, the mod_values form is used.
|
|
mod_type
|
The type of the attribute to modify.
|
|
mod_vals
|
The values (if any) to add, delete, or replace. Only one of the
mod_values or mod_bvalues variants should be used, selected by ORing
the mod_op field with the constant LDAP_MOD_BVALUES. The mod_values
field is a NULL-terminated array of zero-terminated strings and
mod_bvalues is a NULL- terminated array of berval structures that can
be used to pass binary values such as images.
|
For LDAP_MOD_ADD modifications, the given values are added to the
entry, creating the attribute if necessary.
For LDAP_MOD_DELETE modifications, the given values are deleted from
the entry, removing the attribute if no values remain. If the entire
attribute is to be deleted, the mod_vals field should be set to NULL.
For LDAP_MOD_REPLACE modifications, the attribute will have the listed
values after the modification, having been created if necessary, or
removed if the mod_vals field is NULL. All modifications are performed
in the order in which they are listed.
The
ldap_modify_ext()
function initiates an asynchronous modify operation and returns the
constant LDAP_SUCCESS if the request was successfully sent, or another
LDAP error code if not. See Section 12.18 for more information about
possible errors and how to interpret them. If successful,
ldap_modify_ext()
places the message id of the request in *msgidp. A subsequent call to
ldap_result()
can be used to obtain the result of the modify.
Similar to
ldap_modify_ext()
, the
ldap_modify()
function initiates an asynchronous modify operation and returns the
message id of the operation initiated. As for
ldap_modify_ext()
, a subsequent call to
ldap_result()
can be used to obtain the result of the modify. In case of error,
ldap_modify()
will return -1, setting the session error parameters in the LDAP
structure appropriately.
The synchronous
ldap_modify_ext_s()
and
ldap_modify_s()
functions both return the result of the operation, either the constant
LDAP_SUCCESS if the operation was successful, or another LDAP error
code if it was not.
See Section 12.18 for more information about possible errors and how to
interpret them.
The
ldap_modify_ext()
and
ldap_modify_ext_s()
functions support LDAPv3 server controls and client controls.
12.12 Modifying the Name of an Entry
In LDAP Version 2, the
ldap_modrdn()
and
ldap_modrdn_s()
functions were used to change the name of an LDAP entry. They could
only be used to change the least significant component of a name (the
RDN or relative distinguished name). LDAPv3 provides the Modify DN
protocol operation that allows more general name change access. The
ldap_rename()
and
ldap_rename_s()
functions are used to change the name of an entry, and the use of the
ldap_modrdn()
and
ldap_modrdn_s()
functions is deprecated.
int ldap_rename(
LDAP *ld,
const char *dn,
const char *newrdn,
const char *newparent,
int deleteoldrdn,
LDAPControl **serverctrls,
LDAPControl **clientctrls,
int *msgidp
);
int ldap_rename_s(
LDAP *ld,
const char *dn,
const char *newrdn,
const char *newparent,
int deleteoldrdn,
LDAPControl **serverctrls,
LDAPControl **clientctrls
);
|
Use of the following functions is deprecated.
int ldap_modrdn(
LDAP *ld,
char *dn,
char *newrdn,
int deleteoldrdn
);
int ldap_modrdn_s(
LDAP *ld,
char *dn,
char *newrdn,
int deleteoldrdn
);
|
Parameters are as follows:
|
ld
|
The session handle.
|
|
dn
|
The name of the entry whose DN is to be changed.
|
|
newrdn
|
The new RDN to give the entry.
|
|
newparent
|
The new parent, or superior entry. If this parameter is NULL, only the
RDN of the entry is changed. The root DN may be specified by passing a
zero length string, "". The newparent parameter should always be NULL
when using Version 2 of the LDAP protocol; otherwise the server's
behavior is undefined.
|
|
deleteoldrdn
|
This parameter only has meaning on the rename functions if newrdn is
different than the old RDN. It is a boolean value. If it is non-zero,
it indicates that the old RDN value(s) should be removed. If it is
zero, it indicates that the old RDN value(s) should be retained as
non-distinguished values of the entry.
|
|
serverctrls
|
List of LDAP server controls.
|
|
clientctrls
|
List of client controls.
|
|
msgidp
|
This result parameter will be set to the message id of the request if
the
ldap_rename()
call succeeds.
|
The
ldap_rename()
function initiates an asynchronous modify DN operation and returns the
constant LDAP_SUCCESS if the request was successfully sent, or another
LDAP error code if not. See Section 12.18 for more information about
possible errors and how to interpret them. If successful,
ldap_rename()
places the DN message id of the request in *msgidp. A subsequent call to
ldap_result()
can be used to obtain the result of the rename.
The synchronous
ldap_rename_s()
returns the result of the operation, either the constant LDAP_SUCCESS
if the operation was successful, or another LDAP error code if it was
not. See Section 12.18 for more information about possible errors and
how to interpret them.
The
ldap_rename()
and
ldap_rename_s()
functions both support LDAPv3 server controls and client controls.
|
