Release 9.2
Part Number A96577-01
 Home |
 Book List |
 Contents |
 Index |
 Master Index |
 Feedback |
| Oracle Internet Directory Application Developer's Guide Release 9.2 Part Number A96577-01 |
|
This chapter introduces the Oracle Internet Directory C API and provides examples of how to use it. It contains these topics:
The Oracle Internet Directory SDK C API is based on:
You can use the Oracle Internet Directory API Release 9.2 in the following modes:
The API uses TCP/IP to connect to an LDAP server. When it does this, it uses, by default, an unencrypted channel. To use the SSL mode, you must use the Oracle SSL call interface. You determine which mode you are using by the presence or absence of the SSL calls in the API usage. You can easily switch between SSL and non-SSL modes.
| See Also:
"Sample C API Usage" for more details on how to use the two modes |
This section contains these topics:
Oracle SSL extensions to the LDAP API are based on standard SSL protocol. The SSL extensions provide encryption and decryption of data over the wire, and authentication.
There are three modes of authentication:
The type of authentication is indicated by a parameter in the SSL interface call.
There is only one call required to enable SSL:
int ldap_init_SSL(Sockbuf *sb, text *sslwallet, text *sslwalletpasswd, int sslauthmode)
The ldap_init_SSL call performs the necessary handshake between client and server using the standard SSL protocol. If the call is successful, all subsequent communication happens over a secure connection.
To use the SSL feature, both the server and the client may require wallets, depending on which authentication mode is being used. Release 9.2 of the API supports only Oracle Wallet. You can create wallets using Oracle Wallet Manager.
This section contains these topics:
This section lists all the calls available in the LDAP C API found in RFC 1823.
| See Also:
The following URL: http://www.ietf.org/rfc/rfc1823.txt for a more detailed explanation of these calls |
This section contains these topics:
ldap_init() initializes a session with an LDAP server. The server is not actually contacted until an operation is performed that requires it, allowing various options to be set after initialization.
LDAP *ldap_init ( const char *hostname, int portno) ;
ldap_init() and ldap_open() both return a "session handle," a pointer to an opaque structure that MUST be passed to subsequent calls pertaining to the session. These routines return NULL if the session cannot be initialized in which case the operating system error reporting mechanism can be checked to see why the call failed.
Note that if you connect to an LDAPv2 server, one of the LDAP bind calls described later SHOULD be completed before other operations can be performed on the session. LDAPv3 does not require that a bind operation be completed before other operations can be performed.
The calling program can set various attributes of the session by calling the routines described in the next section.
The LDAP session handle returned by ldap_init() is a pointer to an opaque data type representing an LDAP session. In RFC 1823 this data type was a structure exposed to the caller, and various fields in the structure could be set to control aspects of the session, such as size and time limits on searches.
In the interest of insulating callers from inevitable changes to this structure, these aspects of the session are now accessed through a pair of accessor functions, described in this section.
ldap_get_option() is used to access the current value of various session-wide parameters. ldap_set_option() is used to set the value of these parameters. Note that some options are READ-ONLY and cannot be set; it is an error to call ldap_set_option() and attempt to set a READ-ONLY option.
Note that if automatic referral following is enabled (the default), any connections created during the course of following referrals will inherit the options associated with the session that sent the original request that caused the referrals to be returned.
int ldap_get_option ( LDAP *ld, int option, void *outvalue) ; int ldap_set_option (
LDAP *ld, int option, const void *invalue) ;
#define LDAP_OPT_ON ((void *)1) #define LDAP_OPT_OFF ((void *)0)
| Parameters | Description |
|---|---|
|
ld |
The session handle. If this is NULL, a set of global defaults is accessed. New LDAP session handles created with ldap_init() or ldap_open() inherit their characteristics from these global defaults. |
|
option |
The name of the option being accessed or set. This parameter SHOULD be one of the constants listed and described in Table 3-4. After the constant the actual hexadecimal value of the constant is listed in parentheses. |
|
outvalue |
The address of a place to put the value of the option. The actual type of this parameter depends on the setting of the option parameter. For outvalues of type char ** and LDAPControl **, a copy of the data that is associated with the LDAP session ld is returned; callers should dispose of the memory by calling ldap_memfree() or ldap_controls_free(), depending on the type of data returned. |
|
invalue |
A pointer to the value the option is to be given. The actual type of this parameter depends on the setting of the option parameter. The data associated with invalue is copied by the API implementation to allow callers of the API to dispose of or otherwise change their copy of the data after a successful call to ldap_set_option(). If a value passed for invalue is invalid or cannot be accepted by the implementation, ldap_set_option() should return -1 to indicate an error. |
| Constant | Type for invalue parameter | Type for outvalue parameter | Description |
|---|---|---|---|
|
LDAP_OPT_API_INFO (0x00) |
not applicable (option is READ-ONLY) |
LDAPAPIInfo * |
Used to retrieve some basic information about the LDAP API implementation at execution time. Applications need to be able to determine information about the particular API implementation they are using both at compile time and during execution. This option is READ-ONLY and cannot be set. |
|
LDAP_OPT_DEREF (0x02) |
int * |
int * |
Determines how aliases are handled during search. It SHOULD have one of the following values: LDAP_DEREF_NEVER (0x00), LDAP_DEREF SEARCHING (0x01), LDAP_DEREF_FINDING (0x02), or LDAP_DEREF_ALWAYS (0x03). The LDAP_DEREF_SEARCHING value means aliases are dereferenced during the search but not when locating the base object of the search. The LDAP_DEREF_FINDING value means aliases are dereferenced when locating the base object but not during the search. The default value for this option is LDAP_DEREF_NEVER. |
|
LDAP_OPT_SIZELIMIT (0x03) |
int * |
int * |
A limit on the number of entries to return from a search. A value of LDAP_NO_LIMIT (0) means no limit. The default value for this option is LDAP_NO_LIMIT. |
|
LDAP_OPT_TIMELIMIT (0x04) |
int * |
int * |
A limit on the number of seconds to spend on a search. A value of LDAP_NO_LIMIT (0) means no limit. This value is passed to the server in the search request only; it does not affect how long the C LDAP API implementation itself will wait locally for search results. The timeout parameter passed to ldap_search_ext_s() or ldap_result() -- both of which are described later in this document -- can be used to specify both a local and server side time limit. The default value for this option is LDAP_NO_LIMIT. |
|
LDAP_OPT_REFERRALS (0x08) |
void * (LDAP_OPT_ON or LDAP_OPT_OFF) |
int * |
Determines whether the LDAP library automatically follows referrals returned by LDAP servers or not. It MAY be set to one of the constants LDAP_OPT_ON or LDAP_OPT_OFF; any non- NULL pointer value passed to ldap_set_option() enables this option. When reading the current setting using ldap_get_option(), a zero value means OFF and any nonzero value means ON. By default, this option is ON. |
|
LDAP_OPT_RESTART (0x09) |
void * (LDAP_OPT_ON or LDAP_OPT_OFF) |
int * |
Determines whether LDAP I/O operations are automatically restarted if they stop prematurely. It MAY be set to one of the constants LDAP_OPT_ON or LDAP_OPT_OFF; any non-NULL pointer value passed to ldap_set_option() enables this option. When reading the current setting using ldap_get_option(), a zero value means OFF and any nonzero value means ON. This option is useful if an LDAP I/O operation can be interrupted prematurely, for example by a timer going off, or other interrupt. By default, this option is OFF. |
|
LDAP_OPT_PROTOCOL_VERSION (0x11) |
int * |
int * |
This option indicates the version of the LDAP protocol used when communicating with the primary LDAP server. It SHOULD be one of the constants LDAP_VERSION2 (2) or LDAP_VERSION3 (3). If no version is set the default is LDAP_VERSION2 (2). |
|
LDAP_OPT_SERVER_CONTROLS (0x12) |
LDAPControl ** |
LDAPControl *** |
A default list of LDAP server controls to be sent with each request. See Also: "Working With Controls" |
|
LDAP_OPT_CLIENT_CONTROLS (0x13) |
LDAPControl ** |
LDAPControl *** |
A default list of client controls that affect the LDAP session. See Also: "Working With Controls" |
|
LDAP_OPT_API_FEATURE_INFO (0x15) |
not applicable (option is READ-ONLY) |
LDAPAPIFeatureInfo * |
Used to retrieve version information about LDAP API extended features at execution time. Applications need to be able to determine information about the particular API implementation they are using both at compile time and during execution. This option is READ-ONLY and cannot be set. |
|
LDAP_OPT_HOST_NAME (0x30) |
char * |
char ** |
The host name (or list of hosts) for the primary LDAP server. See the definition of the hostname parameter to ldap_init() for the allowed syntax. |
|
LDAP_OPT_ERROR_NUMBER (0x31) |
int * |
int * |
The code of the most recent LDAP error that occurred for this session. |
|
LDAP_OPT_ERROR_STRING (0x32) |
char * |
char ** |
The message returned with the most recent LDAP error that occurred for this session. |
|
LDAP_OPT_MATCHED_DN (0x33) |
char * |
char ** |
The matched DN value returned with the most recent LDAP error that occurred for this session. |
Both ldap_get_option() and ldap_set_option() return 0 if successful and -1 if an error occurs. If -1 is returned by either function, a specific error code MAY be retrieved by calling ldap_get_option() with an option value of LDAP_OPT_ERROR_NUMBER. Note that there is no way to retrieve a more specific error code if a call to ldap_get_option() with an option value of LDAP_OPT_ERROR_NUMBER fails.
When a call to ldap_get_option() succeeds, the API implementation MUST NOT change the state of the LDAP session handle or the state of the underlying implementation in a way that affects the behavior of future LDAP API calls. When a call to ldap_get_option() fails, the only session handle change permitted is setting the LDAP error code (as returned by the LDAP_OPT_ERROR_NUMBER option).
When a call to ldap_set_option() fails, it MUST NOT change the state of the LDAP session handle or the state of the underlying implementation in a way that affects the behavior of future LDAP API calls.
Standards track documents that extend this specification and specify new options SHOULD use values for option macros that are between 0x1000 and 0x3FFF inclusive. Private and experimental extensions SHOULD use values for the option macros that are between 0x4000 and 0x7FFF inclusive. All values less than 0x1000 and greater than 0x7FFF that are not defined in this document are reserved and SHOULD NOT be used. The following macro MUST be defined by C LDAP API implementations to aid extension implementors:
#define LDAP_OPT_PRIVATE_EXTENSION_BASE 0x4000 /* to 0x7FFF inclusive */
LDAPv3 operations can be extended through the use of controls. Controls can be sent to a server or returned to the client with any LDAP message. These controls are referred to as server controls.
The LDAP API also supports a client-side extension mechanism through the use of client controls. These controls affect the behavior of the LDAP API only and are never sent to a server. A common data structure is used to represent both types of controls:
typedef struct ldapcontrol { char *ldctl_oid; struct berval ldctl_value; char ldctl_iscritical;} LDAPControl;
The fields in the ldapcontrol structure have the following meanings:
Some LDAP API calls allocate an ldapcontrol structure or a NULL-terminated array of ldapcontrol structures. The following routines can be used to dispose of a single control or an array of controls:
void ldap_control_free( LDAPControl *ctrl ); void ldap_controls_free( LDAPControl **ctrls );
If the ctrl or ctrls parameter is NULL, these calls do nothing.
A set of controls that affect the entire session can be set using the ldap_set_option() function described in "ldap_set_option". A list of controls can also be passed directly to some LDAP API calls such as ldap_search_ext(), in which case any controls set for the session through the use of ldap_set_option() are ignored. Control lists are represented as a NULL-terminated array of pointers to ldapcontrol structures.
Server controls are defined by LDAPv3 protocol extension documents; for example, a control has been proposed to support server-side sorting of search results.
One client control is defined in this document (described in the following section). Other client controls MAY be defined in future revisions of this document or in documents that extend this API.
As described previously in "LDAP Session Handle Options", applications can enable and disable automatic chasing of referrals on a session-wide basic by using the ldap_set_option() function with the LDAP_OPT_REFERRALS option. It is also useful to govern automatic referral chasing on per-request basis. A client control with an OID of 1.2.840.113556.1.4.616 exists to provide this functionality.
/* OID for referrals client control */ #define LDAP_CONTROL_REFERRALS "1.2.840.113556.1.4.616" /* Flags for referrals client control value */ #define LDAP_CHASE_SUBORDINATE_REFERRALS 0x00000020U #define LDAP_CHASE_EXTERNAL_REFERRALS 0x00000040U
To create a referrals client control, the ldctl_oid field of an LDAPControl structure MUST be set to LDAP_CONTROL_REFERRALS ("1.2.840.113556.1.4.616") and the ldctl_value field MUST be set to a 4-octet value that contains a set of flags. The ldctl_value.bv_len field MUST always be set to 4. The ldctl_value.bv_val field MUST point to a 4-octet integer flags value. This flags value can be set to zero to disable automatic chasing of referrals and LDAPv3 references altogether. Alternatively, the flags value can be set to the value LDAP_CHASE_SUBORDINATE_REFERRALS (0x00000020U) to indicate that only LDAPv3 search continuation references are to be automatically chased by the API implementation, to the value LDAP_CHASE_EXTERNAL_REFERRALS (0x00000040U) to indicate that only LDAPv3 referrals are to be automatically chased, or the logical OR of the two flag values (0x00000060U) to indicate that both referrals and references are to be automatically chased.
The following functions are used to authenticate an LDAP client to an LDAP directory server.
The ldap_sasl_bind() and ldap_sasl_bind_s() functions can be used to do general and extensible authentication over LDAP through the use of the Simple Authentication Security Layer. The routines both take the dn to bind as, the method to use, as a dotted-string representation of an object identifier identifying the method, and a struct berval holding the credentials. The special constant value LDAP_SASL_SIMPLE (NULL) can be passed to request simple authentication, or the simplified routines ldap_simple_bind() or ldap_simple_bind_s() can be used.
int ldap_sasl_bind ( LDAP *ld, const char *dn, const char *mechanism, const struct berval *cred, LDAPControl **serverctrls, LDAPControl **clientctrls, int *msgidp
);
int ldap_sasl_bind_s( LDAP *ld, const char *dn, const char *mechanism, const struct berval *cred, LDAPControl **serverctrls, LDAPControl **clientctrls, struct berval **servercredp);
int ldap_simple_bind( LDAP *ld, const char *dn, const char *passwd);
int ldap_simple_bind_s( LDAP *ld, const char *dn, const char *passwd);
The use of the following routines is deprecated and more complete descriptions can be found in RFC 1823:
int ldap_bind( LDAP *ld, const char *dn, const char *cred, int method );
int ldap_bind_s( LDAP *ld, const char *dn, const char *cred, int method );
int ldap_kerberos_bind( LDAP *ld, const char *dn );
int ldap_kerberos_bind_s( LDAP *ld, const char *dn );
Additional parameters for the deprecated routines are not described. Interested readers are referred to RFC 1823.
The ldap_sasl_bind() function initiates an asynchronous bind operation and returns the constant LDAP_SUCCESS if the request was successfully sent, or another LDAP error code if not. If successful, ldap_sasl_bind() places the message id of the request in *msgidp. A subsequent call to ldap_result(), described in "ldap_result", can be used to obtain the result of the bind.
The ldap_simple_bind() function initiates a simple asynchronous bind operation and returns the message id of the operation initiated. A subsequent call to ldap_result(), described in , can be used to obtain the result of the bind. In case of error, ldap_simple_bind() will return -1, setting the session error parameters in the LDAP structure appropriately.
The synchronous ldap_sasl_bind_s() and ldap_simple_bind_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.
Note that if an LDAPv2 server is contacted, no other operations over the connection can be attempted before a bind call has successfully completed.
Subsequent bind calls can be used to re-authenticate over the same connection, and multistep SASL sequences can be accomplished through a sequence of calls to ldap_sasl_bind() or ldap_sasl_bind_s().
| See Also:
"Handling Errors and Parsing Results" for more information about possible errors and how to interpret them. |
The following functions are used to unbind from the directory, close open connections, and dispose of the session handle.
int ldap_unbind_ext( LDAP *ld, LDAPControl **serverctrls, LDAPControl **clientctrls ); int ldap_unbind( LDAP *ld ); int ldap_unbind_s( LDAP *ld );
| Parameter | Description |
|---|---|
|
ld |
The session handle |
|
serverctrls |
List of LDAP server controls |
|
clientctrls |
List of client controls |
The ldap_unbind_ext(), ldap_unbind() and ldap_unbind_s() all work synchronously in the sense that they send an unbind request to the server, close all open connections associated with the LDAP session handle, and dispose of all resources associated with the session handle before returning. Note, however, that there is no server response to an LDAP unbind operation. All three of the unbind functions return LDAP_SUCCESS (or another LDAP error code if the request cannot be sent to the LDAP server). After a call to one of the unbind functions, the session handle ld is invalid and it is illegal to make any further LDAP API calls using ld.
The ldap_unbind() and ldap_unbind_s() functions behave identically. The ldap_unbind_ext() function allows server and client controls to be included explicitly, but note that since there is no server response to an unbind request there is no way to receive a response to a server control sent with an unbind request.
These functions are used to search the LDAP directory, returning a requested set of attributes for each entry matched.
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, const char *base, int scope, const char *filter, char **attrs, int attrsonly, struct timeval *timeout, LDAPMessage **res
);
The ldap_search_ext() function initiates an asynchronous search operation and returns the constant LDAP_SUCCESS if the request was successfully sent, or another LDAP error code if not. If successful, ldap_search_ext() places the message id of the request in *msgidp. A subsequent call to ldap_result(), described in "ldap_result", can be used to obtain the results from the search. These results can be parsed using the result parsing routines described in detail later.
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(), described in "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. Entries returned from the search (if any) are contained in the res parameter. This parameter is opaque to the caller. Entries, attributes, values, and so on, can be extracted by calling the parsing routines described in this section. The results contained in res SHOULD be freed when no longer in use by calling ldap_msgfree(), described later.
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 expires, the API implementation will send an abandon operation to stop the search operation.
| See Also:
"Handling Errors and Parsing Results" for more information about possible errors and how to interpret them. |
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. attrs 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. attrs contains the list of attributes to return for each child entry.
These routines are used to compare a given attribute value assertion against an LDAP entry.
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);
The ldap_compare_ext() function initiates an asynchronous compare operation and returns the constant LDAP_SUCCESS if the request was successfully sent, or another LDAP error code if not. If successful, ldap_compare_ext() places the message id of the request in *msgidp. A subsequent call to ldap_result(), described in "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(), described in "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 constant LDAP_SUCCESS if the operation was successful, or another LDAP error code if it was not.
The ldap_compare_ext() and ldap_compare_ext_s() functions support LDAPv3 server controls and client controls.
| See Also:
"Handling Errors and Parsing Results" for more information about possible errors and how to interpret them. |
These routines are used to modify an existing LDAP entry.
typedef struct ldapmod { int mod_op; char *mod_type; union mod_vals_u {
char **modv_strvals; struct berval **modv_bvals; } mod_vals;} LDAPMod;
#define mod_values mod_vals.modv_strvals #define mod_bvalues mod_vals.modv_bvalsint 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);
The fields in the LDAPMod structure have the following meanings:
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 can 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. If successful, ldap_modify_ext() places the message id of the request in *msgidp. A subsequent call to ldap_result(), described in "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(), described in "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.
The ldap_modify_ext() and ldap_modify_ext_s() functions support LDAPv3 server controls and client controls.
| See Also:
"Handling Errors and Parsing Results" for more information about possible errors and how to interpret them. |
These routines are used to change the name of an entry.
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);
The use of the following routines is deprecated and more complete descriptions can be found in RFC 1823:
int ldap_modrdn ( LDAP *ld, const char *dn, const char *newrdn); int ldap_modrdn_s (
LDAP *ld, const char *dn, const char *newrdn); int ldap_modrdn2 (
LDAP *ld, const char *dn, const char *newrdn, int deleteoldrdn); int ldap_modrdn2_s (
LDAP *ld, const char *dn, const char *newrdn, int deleteoldrdn);
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. If successful, ldap_rename() places the DN message id of the request in *msgidp. A subsequent call to ldap_result(), described in "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.
The ldap_rename() and ldap_rename_s() functions both support LDAPv3 server controls and client controls.
| See Also:
"Handling Errors and Parsing Results" for more information about possible errors and how to interpret them. |
These functions are used to add entries to the LDAP directory.
int ldap_add_ext ( LDAP *ld, const char *dn, LDAPMod **attrs, LDAPControl **serverctrls, LDAPControl **clientctrls, int *msgidp); int ldap_add_ext_s (
LDAP *ld, const char *dn, LDAPMod **attrs, LDAPControl **serverctrls, LDAPControl **clientctrls); int ldap_add (
LDAP *ld, const char *dn, LDAPMod **attrs); int ldap_add_s (
LDAP *ld, const char *dn, LDAPMod **attrs);
Note that the parent of the entry being added must already exist or the parent must be empty--that is, equal to the root DN--for an add to succeed.
The ldap_add_ext() function initiates an asynchronous add operation and returns the constant LDAP_SUCCESS if the request was successfully sent, or another LDAP error code if not. If successful, ldap_add_ext() places the message id of the request in *msgidp. A subsequent call to ldap_result(), described in "ldap_result", can be used to obtain the result of the add.
Similar to ldap_add_ext(), the ldap_add() function initiates an asynchronous add operation and returns the message id of the operation initiated. As for ldap_add_ext(), a subsequent call to ldap_result(), described in "ldap_result", can be used to obtain the result of the add. In case of error, ldap_add() will return -1, setting the session error parameters in the LDAP structure appropriately.
The synchronous ldap_add_ext_s() and ldap_add_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.
The ldap_add_ext() and ldap_add_ext_s() functions support LDAPv3 server controls and client controls.
| See Also:
"Handling Errors and Parsing Results" for more information about possible errors and how to interpret them. |
These functions are used to delete a leaf entry from the LDAP directory.
int ldap_delete_ext ( LDAP *ld, const char *dn, LDAPControl **serverctrls, LDAPControl **clientctrls, int *msgidp); int ldap_delete_ext_s ( LDAP *ld,
const char *dn, LDAPControl **serverctrls, LDAPControl **clientctrls);
int ldap_delete
( LDAP *ld, const char *dn); int ldap_delete_s (
LDAP *ld, const char *dn);
Note that the entry to delete must be a leaf entry--that is, it must have no children). Deletion of entire subtrees in a single operation is not supported by LDAP.
The ldap_delete_ext() function initiates an asynchronous delete operation and returns the constant LDAP_SUCCESS if the request was successfully sent, or another LDAP error code if not. If successful, ldap_delete_ext() places the message id of the request in *msgidp. A subsequent call to ldap_result(), described in "ldap_result", can be used to obtain the result of the delete.
Similar to ldap_delete_ext(), the ldap_delete() function initiates an asynchronous delete operation and returns the message id of the operation initiated. As for ldap_delete_ext(), a subsequent call to ldap_result(), described in "ldap_result", can be used to obtain the result of the delete. In case of error, ldap_delete() will return -1, setting the session error parameters in the LDAP structure appropriately.
The synchronous ldap_delete_ext_s() and ldap_delete_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.
The ldap_delete_ext() and ldap_delete_ext_s() functions support LDAPv3 server controls and client controls.
| See Also:
"Handling Errors and Parsing Results" for more information about possible errors and how to interpret them. |
These routines allow extended LDAP operations to be passed to the server, providing a general protocol extensibility mechanism.
int ldap_extended_operation ( LDAP *ld, const char *requestoid, const struct berval *requestdata, LDAPControl **serverctrls, LDAPControl **clientctrls, int *msgidp); int ldap_extended_operation_s (
LDAP *ld, const char *requestoid, const struct berval *requestdata, LDAPControl **serverctrls, LDAPControl **clientctrls, char **retoidp, struct berval **retdatap);
