>From cb64d1fd38bb11e85b8acacb7594146c3637d0f3 Mon Sep 17 00:00:00 2001 From: Nathan Kinder <nkinder@xxxxxxxxxx> Date: Wed, 9 Dec 2009 08:27:29 -0800 Subject: [PATCH] Document SLAPI DN related functions. This patch adds Doxygen comment blocks for the DN related functions in slapi-plugin.h. --- ldap/servers/slapd/slapi-plugin.h | 921 ++++++++++++++++++++++++++++++++++++- 1 files changed, 913 insertions(+), 8 deletions(-) diff --git a/ldap/servers/slapd/slapi-plugin.h b/ldap/servers/slapd/slapi-plugin.h index 09f18e7..f3c15c4 100644 --- a/ldap/servers/slapd/slapi-plugin.h +++ b/ldap/servers/slapd/slapi-plugin.h @@ -1706,7 +1706,7 @@ int slapi_entry_merge_values_sv( Slapi_Entry *e, const char *type, Slapi_Value * * \param type Attribute type which will receive the replaced values * \param vals \c NULL terminated array of #Slapi_Value valyes that should replace * the existing values of the attribute. - * \return \c 0 when successfull; any other value returned signals failure. + * \return \c 0 when successful; any other value returned signals failure. * \warning This function makes a copy of \c vals. The \c vals parameter * can be \c NULL. */ @@ -1723,7 +1723,7 @@ int slapi_entry_attr_replace_sv( Slapi_Entry *e, const char *type, Slapi_Value * * \param e Entry to which you want to add a value. * \param type Attribute to which you want to add a value. * \param value The #Slapi_Value data value you want to add to the entry. - * \return \c 0 when successfull; any other value returned signals failure. + * \return \c 0 when successful; any other value returned signals failure. * \warning This function makes a copy of \c value. The \c value parameter * can be \c NULL. */ @@ -1740,7 +1740,7 @@ int slapi_entry_add_value(Slapi_Entry *e, const char *type, const Slapi_Value *v * \param e Entry to which you want to add a string value. * \param type Attribute to which you want to add a string value. * \param value String value you want to add. - * \return \c 0 when successfull; any other value returned signals failure. + * \return \c 0 when successful; any other value returned signals failure. * \warning This function makes a copy of \c value. The \c value parameter * can be \c NULL. */ @@ -1752,7 +1752,7 @@ int slapi_entry_add_string(Slapi_Entry *e, const char *type, const char *value); * \param e Entry from which you want the string deleted. * \param type Attribute type from which you want the string deleted. * \param value Value of string to delete. - * \return \c 0 when successfull; any other value returned signals failure. + * \return \c 0 when successful; any other value returned signals failure. */ int slapi_entry_delete_string(Slapi_Entry *e, const char *type, const char *value); @@ -1873,95 +1873,1000 @@ void slapi_entry_vattrcache_watermark_invalidate(Slapi_Entry *e); void slapi_entrycache_vattrcache_watermark_invalidate(); -/* TODO - Pickup Doxygen work here */ /* * Slapi_DN routines */ +/** + * Creates a new \c Slapi_DN structure. + * + * This function will allocate the necessary memory for a \c Slapi_DN + * and initialize both the DN and normalized DN values to \c NULL. + * + * \return A pointer to the newly allocated, and still empty, + * \c Slapi_DN structure. + * \see slapi_sdn_free() + * \see slapi_sdn_copy() + * \see slapi_sdn_done() + */ Slapi_DN *slapi_sdn_new( void ); + +/** + * Creates a new \c Slapi_DN structure and intializes it's DN to a requested value. + * + * The DN of the new structure will point to a copy of the string pointed to by \c dn. + * The DN value is passed in to the parameter by value. + * + * \param dn The DN value to be set in the new \c Slapi_DN structure. + * \return A pointer to the newly allocated \c Slapi_DN structure with + * a DN value set to the content of \c dn. + * \warning The \c dn value is copied by the function itself. The caller + * is still responsible for the memory used by \c dn. + * \see slapi_sdn_new_dn_byref() + * \see slapi_sdn_new_dn_passin() + * \see slapi_sdn_free() + * \see slapi_sdn_copy() + * \see slapi_sdn_done() + */ Slapi_DN *slapi_sdn_new_dn_byval(const char *dn); + +/** + * Creates a new \c Slapi_DN structure and intializes it's normalized DN to a requested value. + * + * The normalized DN of the new structure will point to a copy of the string pointed to by + * \c ndn. The normalized DN value is passed in to the parameter by value. + * + * \param ndn The normalized DN value to be set in the new \c Slapi_DN structure. + * \return A pointer to the newly allocated \c Slapi_DN structure with + * the normalized DN value set to the content of \c ndn. + * \warning The \c ndn value is copied by the function itself. The caller + * is still responsible for the memory used by \c ndn. + * \see slapi_sdn_new_ndn_byref() + * \see slapi_sdn_free() + * \see slapi_sdn_copy() + * \see slapi_sdn_done() + */ Slapi_DN *slapi_sdn_new_ndn_byval(const char *ndn); + +/** + * Creates a new \c Slapi_DN structure and intializes it's DN to a requested value. + * + * The DN of the new structure will point to the same string pointed to by \c dn. + * The DN value is passed in to the parameter by reference. + * + * \param dn The DN value to be set in the new \c Slapi_DN structure. + * \return A pointer to the newly allocated \c Slapi_DN structure with + * a DN value set to the content of \c dn. + * \warning The caller is still responsible for the memory used by \c dn. This + * memory should not be freed until the returned \c Slapi_DN has been + * disposed of or reinitialized. + * \see slapi_sdn_new_dn_byval() + * \see slapi_sdn_new_dn_passin() + * \see slapi_sdn_free() + * \see slapi_sdn_copy() + * \see slapi_sdn_done() + */ Slapi_DN *slapi_sdn_new_dn_byref(const char *dn); + +/** + * Creates a new \c Slapi_DN structure and intializes it's normalized DN to a requested value. + * + * The normalized DN of the new structure will point to the same string pointed to by \c ndn. + * The normalized DN value is passed in to the parameter by reference. + * + * \param ndn The normalized DN value to be set in the new \c Slapi_DN structure. + * \return A pointer to the newly allocated \c Slapi_DN structure with + * the normalized DN value set to the content of \c ndn. + * \warning The caller is still responsible for the memory used by \c ndn. This + * memory should not be freed until the returned \c Slapi_DN has been + * disposed of or reinitialized. + * \see slapi_sdn_new_ndn_byval() + * \see slapi_sdn_free() + * \see slapi_sdn_copy() + * \see slapi_sdn_done() + */ Slapi_DN *slapi_sdn_new_ndn_byref(const char *ndn); + +/** + * Creates a new \c Slapi_DN structure and intializes it's DN to a requested value. + * + * The DN of the new structure will point to the same string pointed to by \c dn. + * Ownership of the memory pointed to by \c dn is tranferred to the Slapi_DN. + * + * \param dn The DN value to be set in the new \c Slapi_DN structure. + * \return A pointer to the newly allocated \c Slapi_DN structure with + * a DN value set to the content of \c dn. + * \warning The caller is no longer responsible for the memory used by \c dn. + * This memory should not be freed directly. It will be freed when + * the \c Slapi_DN is properly disposed of. + * \see slapi_sdn_new_dn_byval() + * \see slapi_sdn_new_dn_byref() + * \see slapi_sdn_free() + * \see slapi_sdn_copy() + * \see slapi_sdn_done() + */ Slapi_DN *slapi_sdn_new_dn_passin(const char *dn); + +/** + * Sets a DN value in a \c Slapi_DN structure. + * + * The DN of the structure will point to a copy of the string pointed to by + * \c dn. The DN value is passed in to the parameter by value. + * + * \param sdn The target \c Slapi_DN structure. + * \param dn The DN value to be set in \c sdn. + * \return A pointer to the \c Slapi_DN structure containing the new DN value. + * \warning The \c dn value is copied by the function itself. The caller + * is still responsible for the memory used by \c dn. + * \see slapi_sdn_set_dn_byref() + * \see slapi_sdn_set_dn_passin() + */ Slapi_DN *slapi_sdn_set_dn_byval(Slapi_DN *sdn, const char *dn); + +/** + * Sets a DN value in a \c Slapi_DN structure. + * + * The DN of the structure will point to the same string pointed to by \c dn. + * The DN value is passed in to the parameter by reference. + * + * \param sdn The target \c Slapi_DN structure. + * \param dn The DN value to be set in \c sdn. + * \return A pointer to the \c Slapi_DN structure containing the new DN value. + * \warning The caller is still responsible for the memory used by \c dn. This + * memory should not be freed until the returned \c Slapi_DN has been + * disposed of or reinitialized. + * \see slapi_sdn_set_dn_byval() + * \see slapi_sdn_set_dn_passin() + */ Slapi_DN *slapi_sdn_set_dn_byref(Slapi_DN *sdn, const char *dn); + +/** + * Sets a DN value in a \c Slapi_DN structure. + * + * The DN of the structure will point to the same string pointed to by \c dn. + * Ownership of the memory pointed to by \c dn is tranferred to the Slapi_DN. + * + * \param sdn The target \c Slapi_DN structure. + * \param dn The DN value to be set in \c sdn. + * \return A pointer to the \c Slapi_DN structure containing the new DN value. + * \warning The caller is no longer responsible for the memory used by \c dn. + * This memory should not be freed directly. It will be freed when + * the \c Slapi_DN is properly disposed of. + * \see slapi_sdn_set_dn_byval() + * \see slapi_sdn_set_dn_byref() + */ Slapi_DN *slapi_sdn_set_dn_passin(Slapi_DN *sdn, const char *dn); + +/** + * Sets a normalized DN value in a \c Slapi_DN structure. + * + * The normalized DN of the structure will point to a copy of the string + * pointed to by \c ndn. The normalized DN value is passed in to the parameter + * by value. + * + * \param sdn The target \c Slapi_DN structure. + * \param ndn The normalized DN value to be set in \c sdn. + * \return A pointer to the \c Slapi_DN structure containing the new normalized DN value. + * \warning The \c ndn value is copied by the function itself. The caller + * is still responsible for the memory used by \c ndn. + * \see slapi_sdn_set_ndn_byref() + */ Slapi_DN *slapi_sdn_set_ndn_byval(Slapi_DN *sdn, const char *ndn); + +/** + * Sets a normalized DN value in a \c Slapi_DN structure. + * + * The normalized DN of the structure will point to the same string pointed to + * by \c ndn. The normalized DN value is passed in to the parameter by reference. + * + * \param sdn The target \c Slapi_DN structure. + * \param ndn The normalized DN value to be set in \c sdn. + * \return A pointer to the \c Slapi_DN structure containing the new normalized DN value. + * \warning The caller is still responsible for the memory used by \c ndn. This + * memory should not be freed until the returned \c Slapi_DN has been + * disposed of or reinitialized. + * \see slapi_sdn_set_ndn_byval() + */ Slapi_DN *slapi_sdn_set_ndn_byref(Slapi_DN *sdn, const char *ndn); + +/** + * Clears the contents of a Slapi_DN structure. + * + * Both the DN and the normalized DN are freed if the \c Slapi_DN structure + * owns the memory. Both pointers are then set to \c NULL. + * + * \param sdn Pointer to the \c Slapi_DN to clear. + * \see slapi_sdn_free() + */ void slapi_sdn_done(Slapi_DN *sdn); + +/** + * Frees a \c Slapi_DN structure. + * + * Both the DN and the normalized DN are freed if the \c Slapi_DN structure + * owns the memory. The \c Slapi_DN structure itself is then freed. + * + * \param sdn Pointer to the pointer of the \c Slapi_DN structure to be freed. + * \see slapi_sdn_done() + * \see slapi_sdn_new() + */ void slapi_sdn_free(Slapi_DN **sdn); + +/** + * Retrieves the DN value of a \c Slapi_DN structure. + * + * \param sdn The \c Slapi_DN strucure containing the DN value. + * \return A pointer to the DN value if one is set. + * \return A pointer to the normalized DN value if one is set and no + * DN value is set. + * \return \c NULL if no DN or normalized DN value is set. + * \warning The pointer returned is the actual value from the structure, not a copy. + * \see slapi_sdn_get_ndn() + */ const char * slapi_sdn_get_dn(const Slapi_DN *sdn); + +/** + * Retrieves the normalized DN value of a \c Slapi_DN structure. + * + * If the structure does not contain a normalized DN yet, it will normalize + * the DN and set it in the structure. + * + * \param sdn The \c Slapi_DN strucure containing the normalized DN value. + * \return The normalized DN value. + * \return \c NULL if no DN or normalized DN value is set. + * \warning The pointer returned is the actual value from the structure, not a copy. + * \see slapi_sdn_get_dn() + */ const char * slapi_sdn_get_ndn(const Slapi_DN *sdn); + +/** + * Fills in an existing \c Slapi_DN structure with the parent DN of the passed in \c Slapi_DN. + * + * \param sdn Pointer to the \c Slapi_DN structure containing the DN whose parent is desired. + * \param sdn_parent Pointer to the \c Slapi_DN structure where the parent DN is returned. + * The existing contents (if any) will be cleared before the new DN value is set. + * \warning A \c Slapi_DN structure for \c sdn_parent must be allocated before calling this function. + * \see slapi_sdn_get_backend_parent() + */ void slapi_sdn_get_parent(const Slapi_DN *sdn,Slapi_DN *sdn_parent); + +/** + * Fills in an existing \c Slapi_DN structure with the parent DN of an entry within a specific backend. + * + * The parent DN is returned in \c sdn_parent, unless \c sdn is empty or is a suffix of the backend + * itself. In this case, \c sdn_parent is empty. + * + * \param sdn Pointer to the \c Slapi_DN structure containing the DN whose parent is desired. + * \param sdn_parent Pointer to the \c Slapi_DN structure where the parent DN is returned. + * The existing contents (if any) will be cleared before the new DN value is set. + * \param backend Backend to search for the parent of \c sdn. + * \warning A \c Slapi_DN structure for \c sdn_parent must be allocated before calling this function. + * \see slapi_sdn_get_parent() + */ void slapi_sdn_get_backend_parent(const Slapi_DN *sdn,Slapi_DN *sdn_parent,const Slapi_Backend *backend); + +/** + * Duplicates a \c Slapi_DN structure. + * + * \param sdn Pointer to the \c Slapi_DN structure to duplicate. + * \return A pointer to a duplicate of \c sdn. + * \see slapi_sdn_copy() + * \see slapi_sdn_new() + * \see slapi_sdn_free() + */ Slapi_DN * slapi_sdn_dup(const Slapi_DN *sdn); + +/** + * Copies the contents of a \c Slapi_DN to another \c existing Slapi_DN. + * + * \param from A pointer to the \c Slapi_DN structure to copy from. + * \param to A pointer to the \c Slapi_DN structure to copy to. + * \warning You must allocate \c to before calling this function. + * \see slapi_sdn_dup() + */ void slapi_sdn_copy(const Slapi_DN *from, Slapi_DN *to); + +/** + * Compares two \c Slapi_DN structures. + * + * Performs a case-sensitive comparison of two \c Slapi_DN structures. + * + * \param sdn1 A pointer to the first \c Slapi_DN structure to compare. + * \param sdn2 A pointer to the second \c Slapi_DN structure to compare. + * \return \c 0 if \c sdn1 is equal to \c sdn2. + * \return \c -1 if \c sdn1 is \c NULL. + * \return \c 1 if \c sdn2 is \c NULL and \c sdn1 is not \c NULL. + */ int slapi_sdn_compare( const Slapi_DN *sdn1, const Slapi_DN *sdn2 ); + +/** + * Checks if a DN or normalized DN is set in a \c Slapi_DN. + * + * \param sdn A pointer to the \c Slapi_DN structure to check. + * \return \c 1 if there is no DN or normalized DN set in \c sdn. + * \return \c 0 if \c sdn is not empty. + * \see slapi_sdn_done() + */ int slapi_sdn_isempty( const Slapi_DN *sdn); + +/** + * Checks whether a \c Slapi_DN structure contains a suffix of another \c Slapi_DN structure. + * + * \param sdn A pointer to the \c Slapi_DN structure to check. + * \param suffixsdn A pointer to the \c Slapi_DN structure of the suffix. + * \return \c 1 if the DN in \c suffixsdn is a suffix of \c sdn. + * \return \c 0 if the DN in \c suffixsdn is not a suffix of \c sdn. + * \see slapi_sdn_isparent() + * \see slapi_sdn_isgrandparent() + */ int slapi_sdn_issuffix(const Slapi_DN *sdn, const Slapi_DN *suffixsdn); + +/** + * Checks whether a DN is the parent of a given DN. + * + * \param parent A pointer to the \c Slapi_DN structure containing the DN + * which claims to be the parent of the DN in \c child. + * \param child A pointer to the Slapi_DN structure containing the DN of the + * supposed child of the DN in the structure pointed to by \c parent. + * \return \c 1 if the DN in \c parent is the parent of the DN in \c child. + * \return \c 0 if the DN in \c parent is not the parent of the DN in \c child. + * \see slapi_sdn_isgrandparent() + * \see slapi_sdn_issuffix() + * \see slapi_sdn_get_parent() + */ int slapi_sdn_isparent( const Slapi_DN *parent, const Slapi_DN *child ); + +/** + * Checks whether a DN is the grandparent of a given DN. + * + * \param parent A pointer to the \c Slapi_DN structure containing the DN + * which claims to be the grandparent of the DN in \c child. + * \param child A pointer to the Slapi_DN structure containing the DN of the + * supposed grandchild of the DN in the structure pointed to by \c parent. + * \return \c 1 if the DN in \c parent is the grandparent of the DN in \c child. + * \return \c 0 if the DN in \c parent is not the grandparent of the DN in \c child. + * \see slapi_sdn_isparent() + * \see slapi_sdn_issuffix() + * \see slapi_sdn_get_parent() + */ int slapi_sdn_isgrandparent( const Slapi_DN *parent, const Slapi_DN *child ); + +/** + * Gets the length of the normalized DN of a Slapi_DN structure. + * + * This function normalizes \c sdn if it has not already been normalized. + * + * \param sdn A pointer to the \c Slapi_DN structure containing the DN value. + * \return The length of the normalized DN. + */ int slapi_sdn_get_ndn_len(const Slapi_DN *sdn); + +/** + * Checks if a DN is within a specified scope under a specified base DN. + * + * \param dn A pointer to the \c Slapi_DN structure to test. + * \param base The base DN against which \c dn is going to be tested. + * \param scope The scope tested. Valid scopes are: + * \arg \c LDAP_SCOPE_BASE + * \arg \c LDAP_SCOPE_ONELEVEL + * \arg \c LDAP_SCOPE_SUBTREE + * \return non-zero if \c dn matches the scoping criteria given by \c base and \c scope. + * \see slapi_sdn_compare() + * \see slapi_sdn_isparent() + * \see slapi_sdn_issuffix() + */ int slapi_sdn_scope_test( const Slapi_DN *dn, const Slapi_DN *base, int scope ); + +/** + * Retreives the RDN from a given DN. + * + * This function takes the DN stored in the \c Slapi_DN structure pointed to + * by \c sdn and fills in it's RDN within the \c Slapi_RDN structure pointed + * to by \c rdn. + * + * \param sdn A pointer to the \c Slapi_DN structure containing the DN. + * \param rdn A pointer to the \c Slapi_RDN structure where the RDN is filled in. + * \warning The caller must allocate \c rdn before calling this function. + * \see slapi_sdn_get_dn() + * \see slapi_sdn_set_rdn() + * \see slapi_sdn_add_rdn() + * \see slapi_sdn_is_rdn_component() + */ void slapi_sdn_get_rdn(const Slapi_DN *sdn,Slapi_RDN *rdn); + +/** + * Sets a new RDN for a given DN. + * + * This function changes the RDN of \c sdn by adding the value from + * \c rdn to the parent DN of \c sdn. + * + * \param sdn The DN that you want to rename. + * \param rdn The new RDN. + * \return A pointer to the \c Slapi_DN structure that has been renamed. + * \see slapi_sdn_get_rdn() + */ Slapi_DN *slapi_sdn_set_rdn(Slapi_DN *sdn, const Slapi_RDN *rdn); + +/** + * Sets a new parent for a given DN. + * + * This function keeps the RDN of the original DN and adds it to the + * specified parent DN. + * + * \param sdn The \c Slapi_DN structure containing the DN whose parent you want to change. + * \param parentdn The \c Slapi_DN structure containing the new parent DN. + * \return A pointer to the \c Slapi_DN structure that contains the new DN. + * \see slapi_sdn_isparent() + * \see slapi_sdn_get_parent() + */ Slapi_DN *slapi_sdn_set_parent(Slapi_DN *sdn, const Slapi_DN *parentdn); -int slapi_sdn_is_rdn_component(const Slapi_DN *rdn, const Slapi_Attr *a, const Slapi_Value *v); + +/** + * Builds a new DN out of a new RDN and the DN of the new parent. + * + * The new DN is worked out by adding the new RDN in \c newrdn to a + * parent DN. The parent will be the value in \c newsuperiordn if different + * from \c NULL, and will otherwise be taken from \c dn_olddn by removing + * the old RDN (the parent of the entry will still be the same as the new DN). + * + * \param dn_olddn The old DN value. + * \param newrdn The new RDN value. + * \param newsuperiordn If not \c NULL, will be the DN of the future superior + * entry of the new DN, which will be worked out by adding the value + * in \c newrdn in front of the content of this parameter. + * \return The new DN for the entry whose previous DN was \c dn_olddn. + */ char * slapi_moddn_get_newdn(Slapi_DN *dn_olddn, char *newrdn, char *newsuperiordn); /* * Slapi_RDN functions */ +/** + * Creates a new \c Slapi_RDN structure. + * + * Allocates the necessary memory and initializes both the + * RDN value and the array of split RDNs to \c NULL. + * + * \return A pointer to the newly allocated, and still empty, \c Slapi_RDN structure. + * \warning You must free the returned \c Slapi_RDN structure by calling \c slapi_rdn_free() + * when you are finished using it. + * \see slapi_rdn_init() + * \see slapi_rdn_done() + * \see slapi_rdn_free() + */ Slapi_RDN *slapi_rdn_new( void ); + +/** + * Creates a new \c Slapi_RDN structure and initializes it from a string. + * + * \param dn The DN value whose RDN will be used to initialize the new + * \c Slapi_RDN structure. + * \return A pointer to the newly allocated and initialized \c Slapi_RDN structure. + * \warning You must free the returned \c Slapi_RDN structure by calling \c slapi_rdn_free() + * when you are finished using it. + * \see slapi_rdn_new_sdn() + * \see slapi_rdn_new_rdn() + * \see slapi_rdn_free() + */ Slapi_RDN *slapi_rdn_new_dn(const char *dn); + +/** + * Creates a new \c Slapi_RDN structure and initializes it from a \c Slapi_DN. + * + * \param sdn The \c Slapi_DN structure whose RDN will be used to initialize + * the new \c Slapi_RDN structure. + * \return A pointer to the newly allocated and initialized \c Slapi_RDN structure. + * \warning You must free the returned \c Slapi_RDN structure by calling \c slapi_rdn_free() + * when you are finished using it. + * \see slapi_rdn_new_dn() + * \see slapi_rdn_new_rdn() + * \see slapi_rdn_free() + */ Slapi_RDN *slapi_rdn_new_sdn(const Slapi_DN *sdn); + +/** + * Creates a new \c Slapi_RDN structure and initializes it from a \c Slapi_RDN. + * + * \param fromrdn The \c Slapi_RDN structure whose RDN will be used to initialize + * the new \c Slapi_RDN structure. + * \return A pointer to the newly allocated and initialized \c Slapi_RDN structure. + * \warning You must free the returned \c Slapi_RDN structure by calling \c slapi_rdn_free() + * when you are finished using it. + * \see slapi_rdn_new_dn() + * \see slapi_rdn_new_sdn() + * \see slapi_rdn_free() + */ Slapi_RDN *slapi_rdn_new_rdn(const Slapi_RDN *fromrdn); + +/** + * Clears out a \c Slapi_RDN structure. + * + * Sets both the RDN value and the array of split RDNs to \c NULL. + * + * \param rdn The \c Slapi_RDN structure to be initialized. + * \warning The previous contents of \c rdn are not freed. It is + * up to the caller to do this first if necessary. + * \see slapi_rdn_new() + * \see slapi_rdn_free() + * \see slapi_rdn_done() + */ void slapi_rdn_init(Slapi_RDN *rdn); + +/** + * Initializes a \c Slapi_RDN structure from a string. + * + * \param rdn The \c Slapi_RDN structure to be initialized. + * \param dn The DN value whose RDN will be used to initialize \c rdn. + * \warning The previous contents of \c rdn are not freed. It is + * up to the caller to do this first if necessary. + * \see slapi_rdn_done() + * \see slapi_rdn_init_sdn() + * \see slapi_rdn_init_rdn() + */ void slapi_rdn_init_dn(Slapi_RDN *rdn,const char *dn); + +/** + * Initializes a \c Slapi_RDN structure from a \c Slapi_DN. + * + * \param rdn The \c Slapi_RDN structure to be initialized. + * \param sdn The \c Slapi_DN whose RDN will be used to initialize \c rdn. + * \warning The previous contents of \c rdn are not freed. It is + * up to the caller to do this first if necessary. + * \see slapi_rdn_done() + * \see slapi_rdn_init_dn() + * \see slapi_rdn_init_rdn() + */ void slapi_rdn_init_sdn(Slapi_RDN *rdn,const Slapi_DN *sdn); + +/** + * Initializes a \c Slapi_RDN structure from another \c Slapi_RDN. + * + * \param rdn The \c Slapi_RDN structure to be initialized. + * \param fromrdn The \c Slapi_RDN structure that will be used to + * initialize \c rdn. + * \warning The previous contents of \c rdn are not freed. It is + * up to the caller to do this first if necessary. + * \see slapi_rdn_done() + * \see slapi_rdn_init_dn() + * \see slapi_rdn_init_sdn() + */ void slapi_rdn_init_rdn(Slapi_RDN *rdn,const Slapi_RDN *fromrdn); + +/** + * Sets the RDN value in a \c Slapi_RDN structure from a string. + * + * The previous contents of the \c rdn are freed before + * the new RDN is set. + * + * \param rdn The target \c Slapi_RDN structure. + * \param dn The DN value whose RDN will be set in \c rdn. + * \see slapi_rdn_set_sdn() + * \see slapi_rdn_set_rdn() + */ void slapi_rdn_set_dn(Slapi_RDN *rdn,const char *dn); + +/** + * Sets the RDN value in a \c Slapi_RDN structure from a \c Slapi_DN. + * + * The previous contents of the \c rdn are freed before + * the new RDN is set. + * + * \param rdn The target \c Slapi_RDN structure. + * \param sdn The \c Slapi_DN value whose RDN will be set in \c rdn. + * \see slapi_rdn_set_dn() + * \see slapi_rdn_set_rdn() + */ void slapi_rdn_set_sdn(Slapi_RDN *rdn,const Slapi_DN *sdn); + +/** + * Sets the RDN value in a \c Slapi_RDN structure from a \c Slapi_RDN. + * + * The previous contents of the \c rdn are freed before + * the new RDN is set. + * + * \param rdn The target \c Slapi_RDN structure. + * \param fromrdn The \c Slapi_RDN value whose RDN will be set in \c rdn. + * \see slapi_rdn_set_dn() + * \see slapi_rdn_set_sdn() + */ void slapi_rdn_set_rdn(Slapi_RDN *rdn,const Slapi_RDN *fromrdn); + +/** + * Frees a \c Slapi_RDN structure and it's contents from memory. + * + * \param rdn A pointer to a pointer of the \c Slapi_RDN strucure to be freed. + * \see slapi_rdn_new() + * \see slapi_rdn_done() + */ void slapi_rdn_free(Slapi_RDN **rdn); + +/** + * Frees and clears the contents of a \c Slapi_RDN structure from memory. + * + * Both the RDN value and the array of split RDNs are freed. Those pointers + * are then set to \c NULL. + * + * \param rdn A pointer to the \c Slapi_RDN strucure to clear. + * \see slapi_rdn_free() + * \see slapi_rdn_init() + */ void slapi_rdn_done(Slapi_RDN *rdn); + +/** + * Gets the first RDN stored in a \c Slapi_RDN structure. + * + * The type and the value of the first RDN are retrieved. + * + * \param rdn The \c Slapi_RDN structure containing the RDN value(s). + * \param type Address to return a pointer to the type of the first RDN. If + * this is \c NULL at the return of the function, it means that \c rdn + * is empty. + * \param value Address to return a pointer to the value of the first RDN. + * If this is \c NULL at the return of the function, it means that + * \c rdn is empty. + * \return \c -1 if \c rdn is empty. + * \return \c 1 if the operation is successful. + * \warning Do not free the returned type or value. + * \see slapi_rdn_get_next() + * \see slapi_rdn_get_rdn() + */ int slapi_rdn_get_first(Slapi_RDN *rdn, char **type, char **value); + +/** + * Gets the next RDN stored in a \c Slapi_RDN structure. + * + * The type/value pair for the RDN at the position following that indicated + * by \c index will be retrieved. + * + * \param rdn The \c Slapi_RDN structure containing the RDN value(s). + * \param index Indicates the position that precedes that of the desired RDN. + * For example, pass 1 if you would like the second RDN. + * \param type Address to return a pointer to the type of the next RDN. If + * this is \c NULL at the return of the function, it means that \c rdn + * is empty. + * \param value Address to return a pointer to the value of the next RDN. + * If this is \c NULL at the return of the function, it means that + * \c rdn is empty. + * \return \c -1 if no RDN exists at the index position. + * \return The position (\c index + \c 1) of the retrieved RDN if the operation is successful. + * \see slapi_rdn_get_first() + * \see slapi_rdn_get_rdn() + */ int slapi_rdn_get_next(Slapi_RDN *rdn, int index, char **type, char **value); + +/** + * Finds a RDN in a \c Slapi_RDN structure and returns it's index. + * + * The \c Slapi_RDN structure will be searched for a RDN matching + * the given type and value. + * + * \param rdn The \c Slapi_RDN structure containing the RDN value(s). + * \param type Type (\c cn, \c o, \c ou, etc.) of the RDN that is searched for. + * \param value Value of the RDN that is searched for. + * \param length Gives the length of the value that should be taken into + * account for the string comparisons when searching for the RDN. + * \return The index of the RDN that matches \c type and \c value. + * \return \c -1 if no RDN stored in \c rdn matches \c type and \c value. + * \see slapi_rdn_get_index_attr() + * \see slapi_rdn_contains() + */ int slapi_rdn_get_index(Slapi_RDN *rdn, const char *type, const char *value,size_t length); + +/** + * Finds a RDN for a given type in a \c Slapi_RDN structure and returns it's index. + * + * \param rdn The \c Slapi_RDN structure containing the RDN value(s). + * \param type Type (\c cn, \c o, \c ou, etc.) of the RDN that is searched for. + * \param value Address to return a pointer to the value of the next RDN. + * If this is \c NULL at the return of the function, it means that + * no matching RDN exist in \c rdn. + * \return The index of the RDN that matches \c type. + * \return \c -1 if no RDN stored in \c rdn matches \c type. + * \see slapi_rdn_get_index() + */ int slapi_rdn_get_index_attr(Slapi_RDN *rdn, const char *type, char **value); + +/** + * Checks if a RDN exists in a \c Slapi_RDN structure. + * + * \param rdn The \c Slapi_RDN structure containing the RDN value(s). + * \param type Type (\c cn, \c o, \c ou, etc.) of the RDN that is searched for. + * \param value Value of the RDN that is searched for. + * \param length Gives the length of the value that should be taken into + * account for the string comparisons when searching for the RDN. + * \return \c 1 if \c rdn contains a RDN that matches \c type and \c value. + * \return \c 0 if no RDN stored in \c rdn matches \c type and \c value. + * \see slapi_rdn_get_index() + * \see slapi_rdn_contains_attr() + */ int slapi_rdn_contains(Slapi_RDN *rdn, const char *type, const char *value,size_t length); + +/** + * Checks if a RDN for a given type exists in a \c Slapi_RDN structure. + * + * \param rdn The \c Slapi_RDN structure containing the RDN value(s). + * \param type Type (\c cn, \c o, \c ou, etc.) of the RDN that is searched for. + * \param value Address to return a pointer to the value of the next RDN. + * If this is \c NULL at the return of the function, it means that + * no matching RDN exist in \c rdn. + * \return \c 1 if \c rdn contains a RDN that matches \c type. + * \return \c 0 if no RDN stored in \c rdn matches \c type. + * \see slapi_rdn_get_index_attr() + * \see slapi_rdn_contains() + */ int slapi_rdn_contains_attr(Slapi_RDN *rdn, const char *type, char **value); + +/** + * Adds a new RDN to a \c Slapi_RDN structure. + * + * A new type/value pair will be added to an existing RDN, or the type/value + * pair will be set as the new RDN if \c rdn is empty. This function resets the + * FLAG_RDNS flags, which means that the RDN array with-in the \c Slapi_RDN + * structure is no longer current with the new RDN. + * + * \param rdn The target \c Slapi_RDN structure. + * \param type The type (\c cn, \c o, \c ou, etc.) of the RDN to be added. + * This parameter cannot be \c NULL. + * \param value The value of the RDN to be added. This parameter cannot + * be \c NULL. + * \return Always returns 1. + * \see slapi_rdn_get_num_components() + */ int slapi_rdn_add(Slapi_RDN *rdn, const char *type, const char *value); + +/** + * Removes a RDN from a \c Slapi_RDN structure at a given position. + * + * \param rdn The target \c Slapi_RDN structure. + * \param atindex The index of the RDN type/value pair to remove. + * \return \c 1 if the RDN is removed from \c rdn. + * \return \c 0 if no RDN is removed because either \c rdn is empty + * or \c atindex goes beyond the number of RDNs present. + * \see slapi_rdn_remove() + * \see slapi_rdn_remove_attr() + */ int slapi_rdn_remove_index(Slapi_RDN *rdn, int atindex); + +/** + * Removes a RDN from a \c Slapi_RDN structure matching a given type/value pair. + * + * \param rdn The target \c Slapi_RDN structure. + * \param type The type (\c cn, \c o, \c ou, etc.) of the RDN to be removed. + * \param value The value of the RDN to be removed. + * \param length Gives the length of the value that should be taken into + * account for the string comparisons when searching for the RDN. + * \return \c 1 if the RDN is removed from \c rdn. + * \return \c 0 if no RDN is removed. + * \see slapi_rdn_remove_attr() + * \see slapi_rdn_remove_index() + */ int slapi_rdn_remove(Slapi_RDN *rdn, const char *type, const char *value, size_t length); + +/** + * Removes a RDN from a \c Slapi_RDN structure matching a given type. + * + * \param rdn The target \c Slapi_RDN structure. + * \param type The type (\c cn, \c o, \c ou, etc.) of the RDN to be removed. + * \return \c 1 if the RDN is removed from \c rdn. + * \return \c 0 if no RDN is removed. + * \see slapi_rdn_remove() + * \see slapi_rdn_remove_index() + */ int slapi_rdn_remove_attr(Slapi_RDN *rdn, const char *type); + +/** + * Checks whether a RDN value is stored in a \c Slapi_RDN structure. + * + * \param rdn The target \c Slapi_RDN structure. + * \return \c 1 if there is no RDN value present. + * \return \c 0 if rdn contains a value. + * \see slapi_rdn_init() + * \see slapi_rdn_done() + * \see slapi_rdn_free() + */ int slapi_rdn_isempty(const Slapi_RDN *rdn); + +/** + * Gets the number of RDN type/value pairs present in a \c Slapi_RDN structure. + * + * \param rdn The target \c Slapi_RDN structure. + * \return The number of RDN type/value pairs present in \c rdn. + * \see slapi_rdn_add() + */ int slapi_rdn_get_num_components(Slapi_RDN *rdn); + +/** + * Compares two \c Slapi_RDN structures. + * + * For RDNs to be considered equal, the order of their components + * do not have to be the same. + * + * \param rdn1 The first RDN to compare. + * \param rdn2 The second RDN to compare. + * \return \c 0 if \c rdn1 and \c rdn2 have the same RDN components. + * \return \c -1 if they do not have the same components. + */ int slapi_rdn_compare(Slapi_RDN *rdn1, Slapi_RDN *rdn2); + +/** + * Gets the RDN from a \c Slapi_RDN structure. + * + * \param rdn The \c Slapi_RDN structure holding the RDN value. + * \return The RDN value. + * \warning Do not free the returned RDN value. + */ const char *slapi_rdn_get_rdn(const Slapi_RDN *rdn); + +/** + * Gets the normalized RDN from a \c Slapi_RDN structure + * + * \param rdn The \c Slapi_RDN structure holding the RDN value. + * \return The normalized RDN value. + * \deprecated This function is not inmplemented. Do not use it. + */ const char *slapi_rdn_get_nrdn(const Slapi_RDN *rdn); + +/** + * Adds a RDN from a \c Slapi_RDN structure to a DN in a \c Slapi_DN structure. + * + * The RDN in the \c Slapi_RDN structure will be appended to the DN + * value in \c sdn. + * + * \param sdn \c Slapi_DN structure containing the value to which + * a new RDN is to be added. + * \param rdn \c Slapi_RDN structure containing the RDN value + * that is to be added to the DN value. + * \return The \c Slapi_DN structure with the new DN. + * \see slapi_sdn_set_rdn() + */ Slapi_DN *slapi_sdn_add_rdn(Slapi_DN *sdn, const Slapi_RDN *rdn); /* * utility routines for dealing with DNs */ +/** + * Normalizes a DN. + * + * \param dn The DN to normalize. + * \return The normalized DN. + * \deprecated Use slapi_sdn_get_ndn() instead. + */ char *slapi_dn_normalize( char *dn ); + +/** + * Normalizes a portion of a DN value. + * + * \param dn The DN value to normalize. + * \param end Pointer to the end of what will be normalized from the DN + * value in \c dn. If this parameter is \c NULL, the DN value + * will be wholly normalized. + * \return A pointer to the end of the DN that has been normalized. + * \warning This function does not null-terminate the string. Use this + * function only if you know what you are doing. + */ char *slapi_dn_normalize_to_end( char *dn, char *end ); + +/** + * Converts a DN to lowercase. + * + * \param dn The DN to convert. + * \return A pointer to the converted DN. + * \deprecated Use slapi_sdn_get_ndn() instead to normalize the case, + * or use slapi_sdn_compare() to compare regardless of case. + */ char *slapi_dn_ignore_case( char *dn ); + +/** + * Converts a DN to canonical format and converts all characters to lowercase. + * + * \param dn DN that you want to normalize and convert to lowercase. + * \return The normalized and converted DN. + * \note The \c dn parameter is converted in place. + */ char *slapi_dn_normalize_case( char *dn ); + +/** + * Get a copy of the parent DN of a DN. + * + * \param pb A parameter block with the backend set. + * \param dn The DN whose parent is desired. + * \return A pointer to the parent DN of \c dn. + * \return \c NULL if the DN is a suffix of the backend. + * \warning The caller must free the returned DN when finished with it. + * \deprecated Use slapi_sdn_get_backend_parent() instead. + */ char *slapi_dn_beparent( Slapi_PBlock *pb, const char *dn ); + +/** + * Finds the parent DN of a DN within the same string. + * + * \param dn The DN whose parent DN is desired. + * \return A pointer to the parent DN within \c dn. + */ const char *slapi_dn_find_parent( const char *dn ); + +/** + * Gets the parent DN of a given DN. + * + * \param dn The DN whose parent is desired. + * \return A pointer to the parent DN of \c dn. + * \warning The caller must free the returned DN when finished with it. + * \deprecated Use slapi_sdn_get_parent() instead. + */ char *slapi_dn_parent( const char *dn ); + +/** + * Checks if a DN belongs to a suffix. + * + * \param dn The DN to check. + * \param suffix The suffix to check. + * \return \c 1 if \c dn belongs to \c suffix + * \return \c 0 if \c dn does not belong to \c suffix. + * \warning Both \c dn and \c suffix must be normalized before calling this function. + * \deprecated Use slapi_sdn_issuffix() instead. + */ int slapi_dn_issuffix( const char *dn, const char *suffix ); + +/** + * Checks if a DN is the parent of another DN. + * + * \param parentdn The DN of the supposed parent. + * \param childdn The DN of the supposed child. + * \return non-zero if \c parentdn is the parent of \c childdn. + * \return \c 0 if \c parentdn is not the paret of \c childdn. + * \deprecated Use slapi_sdn_isparent() instead. + */ int slapi_dn_isparent( const char *parentdn, const char *childdn ); + +/** + * Determines is a DN is the root DN. + * + * \param dn The DN to check + * \return \c 1 if the DN is the root DN. + * \return \c 0 if the DN is not the root DN. + * \warning You must normalize \c dn before calling this function. + */ int slapi_dn_isroot( const char *dn ); + +/** + * Checks if a DN is the backend suffix. + * + * \param pb A parameter block with the backend set. + * \param dn The DN to check. + * \return \c 1 if \c dn is the backend suffix. + * \return \c 0 if \c dn is not the backend suffix. + * \deprecated slapi_be_issuffix() + */ int slapi_dn_isbesuffix( Slapi_PBlock *pb, const char *dn ); + +/** + * Converts the second RDN type value to the berval value. + * + * Returns the new RDN value as a berval value in \c bv. This function + * can be used for creating the RDN as an attribute value since it returns + * the value of the RDN in the berval structure. + * + * \param rdn Second RDN value. + * \param type Address of a pointer to receive the attribute type + * of the second RDN. + * \param bv A pointer to the berval structure to receive the value. + */ int slapi_rdn2typeval( char *rdn, char **type, struct berval *bv ); + +/** + * Adds a RDN to a DN. + * + * \param dn The DN to add the RDN to. + * \param rdn the new RDN to add to the DN. + * \return A pointer to the new DN. + * \warning The caller must free the returnd DN when finished with it. + * \deprecated Use slapi_sdn_add_rdn() instead. + */ char *slapi_dn_plus_rdn(const char *dn, const char *rdn); +/* TODO - Pickup Doxygen work here */ /* * thread safe random functions */ @@ -3655,7 +4560,7 @@ char **slapi_str2charray_ext( char *str, char *brkstr, int allow_dups ); * * \param type Attribute type to add to the default config entry * \param value Attribute value to add to the default config entry - * \return 0 if the operation was successful + * \return \c 0 if the operation was successful * \return non-0 if the operation was not successful */ int slapi_set_plugin_default_config(const char *type, Slapi_Value *value); @@ -3666,7 +4571,7 @@ int slapi_set_plugin_default_config(const char *type, Slapi_Value *value); * * \param type Attribute type to get from the default config entry * \param valueset Valueset holding the attribute values - * \return 0 if the operation was successful + * \return \c 0 if the operation was successful * \return non-0 if the operation was not successful * \warning Caller is responsible to free attrs by slapi_ch_array_free * */ -- 1.6.2.5
-- 389-devel mailing list 389-devel@xxxxxxxxxx https://www.redhat.com/mailman/listinfo/fedora-directory-devel
