>From 145928b645e57b853415908bfb7e4247cbb47c02 Mon Sep 17 00:00:00 2001 From: Nathan Kinder <nkinder@xxxxxxxxxx> Date: Tue, 12 Jan 2010 16:03:52 -0800 Subject: [PATCH] Add Doxygen comments for SLAPI attr, value, and valueset functions. This adds Doxygen comment blocks to the public header file for the attr, value, and valueset related fucntions and defines. --- ldap/servers/slapd/slapi-plugin.h | 1089 ++++++++++++++++++++++++++++++++++++- 1 files changed, 1085 insertions(+), 4 deletions(-) diff --git a/ldap/servers/slapd/slapi-plugin.h b/ldap/servers/slapd/slapi-plugin.h index 42b5710..d35c12c 100644 --- a/ldap/servers/slapd/slapi-plugin.h +++ b/ldap/servers/slapd/slapi-plugin.h @@ -102,13 +102,71 @@ NSPR_API(PRUint32) PR_fprintf(struct PRFileDesc* fd, const char *fmt, ...) * * Note that the flag values 0x0010, 0x0020, 0x4000, and 0x8000 are reserved. */ +/** + * Flag indicating that an attribtue is single-valued. + * + * \see slapi_attr_flag_is_set() + * \see slapi_attr_set_flags() + */ #define SLAPI_ATTR_FLAG_SINGLE 0x0001 /* single-valued attribute */ + +/** + * Flag indicating than an attribute is operational. + * + * \see slapi_attr_flag_is_set() + * \see slapi_attr_set_flags() + */ #define SLAPI_ATTR_FLAG_OPATTR 0x0002 /* operational attribute */ + +/** + * Flag indicating than an attribute is read-only. + * + * \see slapi_attr_flag_is_set() + * \see slapi_attr_set_flags() + */ #define SLAPI_ATTR_FLAG_READONLY 0x0004 /* read from shipped config file */ + +/** + * Flag indicating than an attribute is read-only. + * + * This is an alias for #SLAPI_ATTR_FLAG_READONLY. + * \see slapi_attr_flag_is_set() + * \see slapi_attr_set_flags() + */ #define SLAPI_ATTR_FLAG_STD_ATTR SLAPI_ATTR_FLAG_READONLY /* alias for read only */ + +/** + * Flag indicating than an attribute is obsolete. + * + * \see slapi_attr_flag_is_set() + * \see slapi_attr_set_flags() + */ #define SLAPI_ATTR_FLAG_OBSOLETE 0x0040 /* an outdated definition */ + +/** + * Flag indicating that an attribute is collective. + * + * \warning Collective attributes are not supported, so this + * flag has no effect. + * \see slapi_attr_flag_is_set() + * \see slapi_attr_set_flags() + */ #define SLAPI_ATTR_FLAG_COLLECTIVE 0x0080 /* collective (not supported) */ + +/** + * Flag indicating that an attribute is not modifiable over LDAP. + * + * \see slapi_attr_flag_is_set() + * \see slapi_attr_set_flags() + */ #define SLAPI_ATTR_FLAG_NOUSERMOD 0x0100 /* can't be modified over LDAP */ + +/** + * Flag to indicate that the attribute value is normalized. + * + * \see slapi_value_set_flags() + * \see slapi_values_set_flags() + */ #define SLAPI_ATTR_FLAG_NORMALIZED 0x0200 /* the attr value is normalized */ /* operation flags */ @@ -2866,110 +2924,1133 @@ int slapi_rdn2typeval( char *rdn, char **type, struct berval *bv ); char *slapi_dn_plus_rdn(const char *dn, const char *rdn); -/* TODO - Pickup Doxygen work here */ /* * thread safe random functions */ +/** + * Generate a pseudo-random integer with optional seed. + * + * \param seed A seed to use when generating the pseudo random number. + * \return A pseudo random number. + * \see slapi_rand() + * \see slapi_rand_array() + */ int slapi_rand_r(unsigned int * seed); + +/* Generate a pseudo-random integer in an array. + * + * \param randx The array you want filled with the random number. + * \param len The length of the array you want filled with the random number. + * \see slapi_rand() + * \see slapi_rand_r() + */ void slapi_rand_array(void *randx, size_t len); + +/** + * Generate a pseudo-random integer. + * + * \return A pseudo random number. + * \see slapi_rand_r() + * \see slapi_rand_array() + */ int slapi_rand(); /* * attribute routines */ +/** + * Create a new empty attribute. + * + * \return A pointer to the newly created attribute. + * \warning You must free the returned attribute using slapi_attr_free(). + * \see slapi_attr_init() + * \see slapi_attr_dup() + * \see slapi_attr_free() + */ Slapi_Attr *slapi_attr_new( void ); + +/** + * Initializes an attribute with an attribute type. + * + * \param a The attribute to initialize. + * \param type The attribute type to set. + * \return A pointer to the initialized attribute. + */ Slapi_Attr *slapi_attr_init(Slapi_Attr *a, const char *type); + +/** + * Frees an attribute from memory. + * + * \param a Address of a pointer to the attribute to be freed. + * \see slapi_attr_init() + * \see slapi_attr_dup() + * \see slapi_attr_new() + */ void slapi_attr_free( Slapi_Attr **a ); + +/** + * Make a copy of an attribute. + * + * \param attr The attribute to be duplicated. + * \return The newly created copy of the attribute. + * \warning You must free the returned attribute using slapi_attr_free(). + * \see slapi_attr_new() + * \see slapi_attr_init() + * \see slapi_attr_free() + */ Slapi_Attr *slapi_attr_dup(const Slapi_Attr *attr); + +/** + * Adds a value to an attribute. + * + * \param a The attribute that will contain the values. + * \param v Value to be added to the attribute. + * \return Always returns 0. + * \see slapi_attr_first_value() + * \see slapi_attr_next_value() + * \see slapi_attr_get_numvalues() + * \see slapi_attr_value_cmp() + * \see slapi_attr_value_find() + */ int slapi_attr_add_value(Slapi_Attr *a, const Slapi_Value *v); + +/** + * Find syntax plugin associated with an attribute type. + * + * \param type Type of attribute for which you want to get the plugin. + * \param pi Address to receive a pointer to the plugin structure. + * \return \c 0 if successful. + * \return \c -1 if the plugin is not found. + * \see slapi_attr_get_type() + * \see slapi_attr_type_cmp() + * \see slapi_attr_types_equivalent() + * \see slapi_attr_basetype() + */ int slapi_attr_type2plugin( const char *type, void **pi ); + +/** + * Get the name of the attribute type from a specified attribute. + * + * \param attr Attribute for which you want to get the type. + * \param type Address to receive a pointer to the attribute type. + * \return Always returns \c 0. + * \warning Do not free the returned attribute type. The type is a part + * if the actual attribute data, not a copy. + * \see slapi_attr_type2plugin() + * \see slapi_attr_type_cmp() + * \see slapi_attr_types_equivalent() + * \see slapi_attr_basetype() + */ int slapi_attr_get_type( Slapi_Attr *attr, char **type ); + +/** + * Get the attribute type OID of a particular attribute. + * + * \param attr Attribute that contains the desired OID. + * \param oidp Address to receive a pointer to a copy of the + * attribute type OID. + * \return \c 0 if the attribute type is found. + * \return \c -1 if the attribute type is not found. + * \warning The returned OID should be freed by calling the + * slapi_ch_free_string() function. + * \see slapi_attr_get_syntax_oid_copy() + */ int slapi_attr_get_oid_copy( const Slapi_Attr *attr, char **oidp ); + +/* + * Get the syntax OID of a particular attribute. + * + * \param a Attribute that contains the desired OID. + * \param oidp Address to receive a pointer to a copy of the + * syntax OID. + * \return \c 0 if the syntax OID is found. + * \return \c -1 if the syntax OID is not found. + * \warning The returned OID should be freed by calling the + * slapi_ch_free_string() function. + * \see slapi_attr_get_oid_copy() + */ int slapi_attr_get_syntax_oid_copy( const Slapi_Attr *a, char **oidp ); + +/** + * Get the flags associated with a particular attribute. + * + * Valid flags are: + * \arg #SLAPI_ATTR_FLAG_SINGLE + * \arg #SLAPI_ATTR_FLAG_OPATTR + * \arg #SLAPI_ATTR_FLAG_READONLY + * \arg #SLAPI_ATTR_FLAG_OBSOLETE + * \arg #SLAPI_ATTR_FLAG_COLLECTIVE + * \arg #SLAPI_ATTR_FLAG_NOUSERMOD + * \arg #SLAPI_ATTR_FLAG_NORMALIZED + * + * \param attr Attribute for which you want to get the flags. + * \param flags Address of an integer that you want to reveive the flags. + * \return \c Always returns 0. + * \see slapi_attr_flag_is_set() + */ int slapi_attr_get_flags( const Slapi_Attr *attr, unsigned long *flags ); + +/** + * Checks if certain flags are set for a particular attribute. + * + * Valid flags are: + * \arg #SLAPI_ATTR_FLAG_SINGLE + * \arg #SLAPI_ATTR_FLAG_OPATTR + * \arg #SLAPI_ATTR_FLAG_READONLY + * \arg #SLAPI_ATTR_FLAG_OBSOLETE + * \arg #SLAPI_ATTR_FLAG_COLLECTIVE + * \arg #SLAPI_ATTR_FLAG_NOUSERMOD + * \arg #SLAPI_ATTR_FLAG_NORMALIZED + * + * \param attr Attribute that you want to check. + * \param flag Flags to check in the attribute. + * \return \c 1 if the specified flags are set. + * \return \c 0 if the specified flags are not set. + * \see slapi_attr_get_flags() + */ int slapi_attr_flag_is_set( const Slapi_Attr *attr, unsigned long flag ); + +/** + * Comare two values for a given attribute. + * + * \param attr Attribute used to determine how these values are compared; for + * example, the syntax of the attribute may perform case-insensitive + * comparisons. + * \param v1 Pointer to the \c berval structure containing the first value + * that you want to compare. + * \param v2 Pointer to the \c berval structure containing the second value + * that you want to compare. + * \return \c 0 if the values are equal. + * \return \c -1 if the values are not equal. + * \see slapi_attr_add_value() + * \see slapi_attr_first_value() + * \see slapi_attr_next_value() + * \see slapi_attr_get_numvalues() + * \see slapi_attr_value_find() + */ int slapi_attr_value_cmp( const Slapi_Attr *attr, const struct berval *v1, const struct berval *v2 ); + +/** + * Determine if an attribute contains a given value. + * + * \param a Attribute that you want to check. + * \param v Pointer to the \c berval structure containing the value for + * which you want to search. + * \return \c 0 if the attribute contains the specified value. + * \return \c 01 if the attribute does not contain the specified value. + * \see slapi_attr_add_value() + * \see slapi_attr_first_value() + * \see slapi_attr_next_value() + * \see slapi_attr_get_numvalues() + * \see slapi_attr_value_cmp() + */ int slapi_attr_value_find( const Slapi_Attr *a, const struct berval *v ); +/** + * Compare two attribute types. + * + * \param t1 Name of the first attribute type to compare. + * \param t2 Name of the second attribute type to compare. + * \param opt One of the following options: + * \arg #SLAPI_TYPE_CMP_EXACT + * \arg #SLAPI_TYPE_CMP_BASE + * \arg #SLAPI_TYPE_CMP_SUBTYPE + * \return \c 0 if the type names are equal. + * \return A non-zero value if the type names are not equal. + * \see slapi_attr_type2plugin() + * \see slapi_attr_get_type() + * \see slapi_attr_types_equivalent() + * \see slapi_attr_basetype() + */ int slapi_attr_type_cmp( const char *t1, const char *t2, int opt ); + /* Mode of operation (opt) values for slapi_attr_type_cmp() */ +/** + * Compare the types as-is. + * + * \see slapi_attr_type_cmp() + */ #define SLAPI_TYPE_CMP_EXACT 0 + +/** + * Compare only the base names of the types. + * + * \see slapi_attr_type_cmp() + */ #define SLAPI_TYPE_CMP_BASE 1 + +/** + * Ignore any subtypes in the second type that are not in the first subtype. + * + * \see slapi_attr_type_cmp() + */ #define SLAPI_TYPE_CMP_SUBTYPE 2 +/** + * Compare two attribute names to determine if they represent the same value. + * + * \param t1 Pointer to the first attribute you want to compare. + * \param t2 Pointer to the second attribute you want to compare. + * \return \c 1 if \c t1 and \c t2 represent the same attribute. + * \return \c 0 if \c t1 and \c t2 do not represent the same attribute. + * \see slapi_attr_type_cmp() + * \see slapi_attr_get_type() + * \see slapi_attr_basetype() + */ int slapi_attr_types_equivalent(const char *t1, const char *t2); + +/** + * Get the base type of an attribute. + * + * For example, if given \c cn;lang-jp, returns \c cn. + * + * \param type Attribute type from which you want to get the base type. + * \param buf Buffer to hold the returned base type. + * \param bufsiz Size of the buffer. + * \return \c NULL if the base type fits in the buffer. + * \return A pointer to a newly allocated base type if the buffer is + * too small to hold it. + * \warning If a base type is returned, if should be freed by calling + * slapi_ch_free_string(). + * \see slapi_attr_get_type() + * \see slapi_attr_type_cmp() + * \see slapi_attr_types_equivalent() + */ char *slapi_attr_basetype( const char *type, char *buf, size_t bufsiz ); + +/** + * Get the first value of an attribute. + * + * This is part of a set of functions to enumerate over a + * \c Slapi_Attr structure. + * + * \param a Attribute containing the desired value. + * \param v Holds the first value of the attribute. + * \return \c 0, which is the index of the first value. + * \return \c -1 if \c NULL or if the value is not found. + * \warning Do not free the returned value. It is a part + * of the attribute structure and not a copy. + * \see slapi_attr_next_value() + * \see slapi_attr_get_num_values() + */ int slapi_attr_first_value( Slapi_Attr *a, Slapi_Value **v ); + +/** + * Get the next value of an attribute. + * + * The value of an attribute associated with an index is placed into + * a value. This is pare of a set of functions to enumerate over a + * \c Slapi_Attr structure. + * + * \param a Attribute containing the desired value. + * \param hint Index of the value to be returned. + * \param v Holds the value of the attribute. + * \return \c hint plus \c 1 if the value is found. + * \return \c -1 if \c NULL or if a value at \c hint is not found. + * \warning Do not free the returned value. It is a part + * of the attribute structure and not a copy. + * \see slapi_attr_first_value() + * \see slapi_attr_get_num_values() + */ int slapi_attr_next_value( Slapi_Attr *a, int hint, Slapi_Value **v ); + +/** + * Get the number of values present in an attribute. + * + * Counts the number of values in an attribute and places that + * count in an integer. + * + * \param a Attribute containing the values to be counted. + * \param numValues Integer to hold the counted values. + * \see slapi_attr_first_value() + * \see slapi_attr_next_value() + */ int slapi_attr_get_numvalues( const Slapi_Attr *a, int *numValues); + +/** + * Copy existing values contained in an attribute into a valueset. + * + * \param a Attribute containing the values to be placed into + * a valueset. + * \param vs Receives the values from the attribute. + * \return Always returns \c 0. + * \warning Free the returned valueset with slapi_valueset_free() + * when finished using it. + * \see slapi_entry_add_valueset() + * \see slapi_valueset_new() + * \see slapi_valueset_free() + * \see slapi_valueset_init() + * \see slapi_valueset_done() + * \see slapi_valueset_add_value() + * \see slapi_valueset_first_value() + * \see slapi_valueset_next_value() + * \see slapi_valueset_count() + */ int slapi_attr_get_valueset(const Slapi_Attr *a, Slapi_ValueSet **vs); -/* Make the valuset in Slapi_Attr be *vs--not a copy */ + +/** + * Sets the valueset in an attribute. + * + * Intializes a valueset in a \c Slapi_Attr structure from a specified + * \c Slapi_ValueSet structure. The valueset in the \c Slapi_Attr + * will be \c vs, not a copy. + * + * \param a The attribute to set the valueset in. + * \param vs The valueset that you want to set in the attribute. + * \return Always returns \c 0. + * \warning Do not free \c vs. Ownership of \c vs is tranferred to + * the attribute. + * \see slapi_valueset_set_valueset() + */ int slapi_attr_set_valueset(Slapi_Attr *a, const Slapi_ValueSet *vs); + +/** + * Set the attribute type of an attribute. + * + * \param a The attribute whose type you want to set. + * \param type The attribute type you want to set. + * \return \c 0 if the type was set. + * \return \c -1 if the type was not set. + * \warning The passed in type is copied, so ownership of \c type + * remains with the caller. + * \see slapi_attr_get_type() + */ int slapi_attr_set_type(Slapi_Attr *a, const char *type); + +/** + * Copy the values from an attribute into a berval array. + * + * \param a Attribute that contains the desired values. + * \param vals Pointer to an array of berval structure pointers to + * hold the desired values. + * \return \c 0 if values are found. + * \return \c -1 if \c NULL. + * \warning You should free the array using ber_bvecfree() from the + * Mozilla LDAP C SDK. + */ int slapi_attr_get_bervals_copy( Slapi_Attr *a, struct berval ***vals ); + +/** + * Normalize an attribute type. + * + * The attribute type will be looked up in the defined syntaxes to + * get the normalized form. If it is not found, the passed in type + * will be normalized. + * + * \param s The attribute type that you want to normalize. + * \return A normalized copy of the passed in attribute type. + * \warning You should free the returned string using slapi_ch_free_string(). + * \see slapi_ch_free_string() + */ char * slapi_attr_syntax_normalize( const char *s ); -void slapi_valueset_set_valueset(Slapi_ValueSet *vs1, const Slapi_ValueSet *vs2); -void slapi_valueset_set_from_smod(Slapi_ValueSet *vs, Slapi_Mod *smod); /* * value routines */ +/** + * Create a new empty \c Slapi_Value structure. + * + * \return A pointer to the newly allocated \c Slapi_Value structure. + * \warning If space can not be allocated, the \c ns-slapd program terminates. + * \warning When you are no longer using the value, free it from memory + * by calling slapi_value_free() + * \see slapi_value_free() + * \see slapi_value_dup() + * \see slapi_value_new_berval() + * \see slapi_value_new_string() + * \see slapi_value_new_string_passin() + */ Slapi_Value *slapi_value_new( void ); + +/** + * Create a new \c Slapi_value structure and initialize it's value. + * + * \param bval Pointer to the \c berval structure used to initialize + * the newly allocated \c Slapi_value. + * \return A pointer to the newly allocated and initialized value. + * \warning The passed in \c berval structure will be copied. Ownership + * of \c bval remains with the caller. + * \warning If space can not be allocated, the \c ns-slapd program terminates. + * \warning When you are no longer using the value, free it from memory + * by calling slapi_value_free() + * \see slapi_value_free() + * \see slapi_value_new() + * \see slapi_value_new_string() + * \see slapi_value_new_string_passin() + * \see slapi_value_dup() + */ Slapi_Value *slapi_value_new_berval(const struct berval *bval); + +/** + * Duplicate a \c Slapi_Value structure. + * + * \param v The value to duplicate. + * \return A pointer to the copy of the value. + * \warning If space can not be allocated, the \c ns-slapd program terminates. + * \warning When you are no longer using the value, free it from memory + * by calling slapi_value_free() + * \warning This function is identical to slapi_value_dup(). + * \see slapi_value_dup() + * \see slapi_value_free() + */ Slapi_Value *slapi_value_new_value(const Slapi_Value *v); + +/** + * Create a new \c Slapi_value structure and initialize it's value. + * + * \param s A \c NULL terminated string used to initialize + * the newly allocated \c Slapi_value. + * \return A pointer to the newly allocated and initialized value. + * \warning The passed in string will be copied. Ownership of \c s + * remains with the caller. + * \warning If space can not be allocated, the \c ns-slapd program terminates. + * \warning When you are no longer using the value, free it from memory + * by calling slapi_value_free() + * \see slapi_value_free() + * \see slapi_value_new() + * \see slapi_value_new_berval() + \see slapi_value_new_string_passin() + * \see slapi_value_dup() + */ Slapi_Value *slapi_value_new_string(const char *s); + +/** + * Create a new \c Slapi_value structure and initialize it's value. + * + * \param s A \c NULL terminated string used to initialize + * the newly allocated \c Slapi_value. + * \return A pointer to the newly allocated and initialized value. + * \warning The passed in string will be used directly as the value. + * It will not be copied. Ownership of \c s is transferred + * to the new \c Slapi_Value structure, so it should not be + * freed by the caller. + * \warning If space can not be allocated, the \c ns-slapd program terminates. + * \warning When you are no longer using the value, free it from memory + * by calling slapi_value_free() + * \see slapi_value_free() + * \see slapi_value_new() + * \see slapi_value_new_berval() + * \see slapi_value_new_string() + * \see slapi_value_dup() + */ Slapi_Value *slapi_value_new_string_passin(char *s); + +/** + * Initialize a \c Slapi_Value structure. + * + * All fields of the passed in \c Slapi_Value will be reset to zero. + * + * \param v The value to initialize. + * \return A pointer to the initialized value. + * \warning The passed in value must not be \c NULL. + * \see slapi_value_init_berval() + * \see slapi_value_init_string() + * \see slapi_value_init_string_passin() + */ Slapi_Value *slapi_value_init(Slapi_Value *v); + +/** + * Initialize a \c Slapi_Value structure from the value contained in a \c berval structure. + * + * \param v The value to initialize. + * \param bval The \c berval structure to be used to intialize the value. + * \return A pointer to the initialized value. + * \warning The passed in \c Slapi_Value must not be \c NULL. + * \warning The content of the \c berval structure is duplicated. It is up + * to the caller to manage the memory used by the \c berval. + * \see slapi_value_init() + * \see slapi_value_init_string() + * \see slapi_value_init_string_passin() + */ Slapi_Value *slapi_value_init_berval(Slapi_Value *v, struct berval *bval); + +/** + * Initialize a \c Slapi_Value with a copy of the value contained in a string. + * + * \param v The value to initialize. + * \param s The null-terminated string to be used to initialize the value. + * \return A pointer to the initialized value. + * \warning The passed in \c Slapi_Value must not be \c NULL. + * \warning The passed in string is duplicated. It is up to the caller to + * manage the memory used by the passed in string. + * \see slapi_value_init() + * \see slapi_value_init_berval() + * \see slapi_value_init_string_passin() + */ Slapi_Value *slapi_value_init_string(Slapi_Value *v,const char *s); + +/* Initialize a \c Slapi_Value with the value contained in a string. + * + * \param v The value to initialize. + * \param s The null-terminated string to be used to initialize the value. + * \return A pointer to the initialized value. + * \warning The passed in \c Slapi_Value must not be \c NULL. + * \warning The passed in string is not duplicated. Responsibility for the + * memory used by the string is handed over to the \c Slapi_Value + * structure. + * \warning The passed in string must not be freed. It will be freed when + * the \c Slapi_Value structure is freed by calling \c slapi_value_free(). + * \see slapi_value_free() + * \see slapi_value_init() + * \see slapi_value_init_berval() + * \see slapi_value_init_string() + */ Slapi_Value *slapi_value_init_string_passin(Slapi_Value *v, char *s); + +/** + * Duplicate a \c Slapi_Value structure. + * + * \param v The value to duplicate. + * \return A pointer to the copy of the value. + * \warning If space can not be allocated, the \c ns-slapd program terminates. + * \warning When you are no longer using the value, free it from memory + * by calling slapi_value_free() + * \warning This function is identical to slapi_value_new_value(). + * \see slapi_value_new_value() + * \see slapi_value_free() + */ Slapi_Value *slapi_value_dup(const Slapi_Value *v); + +/** + * Sets the flags in a \c Slapi_Value structure. + * + * Valid flags are: + * \arg #SLAPI_ATTR_FLAG_NORMALIZED + * + * \param v Pointer to the \c Slapi_Value structure for which to + * set the flags. + * \param flags The flags you want to set. + * \warning The flags support bit-wise operations. + * \see slapi_values_set_flags() + * \see slapi_value_get_flags() + */ void slapi_value_set_flags(Slapi_Value *v, unsigned long flags); + +/** + * Sets the flags in an array of \c Slapi_Value structures. + * + * Valid flags are: + * \arg #SLAPI_ATTR_FLAG_NORMALIZED + * + * \param vs Pointer to the \c Slapi_Value array for which you + * want to set the flags. + * \param flags The flags you want to set. + * \warning The flags support bit-wise operations. + * \see slapi_value_set_flags() + * \see slapi_value_get_flags() + */ void slapi_values_set_flags(Slapi_Value **vs, unsigned long flags); + +/** + * Retrieves the flags from a \c Slapi_Value structure. + * + * \param v Pointer to the \c Slapi_Value structure from which the + * flags are to be retrieved. + * \return The flags that are set in the value. + * \see slapi_value_set_flags() + * \see slapi_values_set_flags() + */ unsigned long slapi_value_get_flags(Slapi_Value *v); + +/** + * Frees a \c Slapi_Value structure from memory. + * + * The contents of the value will be freed along with the \c Slapi_Value + * structure itself. The pointer will also be set to \c NULL. + * + * \param value Address of the pointer to the \c Slapi_Value structure + * you wish to free. + * \see slapi_value_new() + */ void slapi_value_free(Slapi_Value **value); + +/** + * Gets the \c berval structure of the value. + * + * \param value Pointer to the \c Slapi_Value of which you wish + * to get the \c berval. + * \return A pointer to the \c berval structure contained in the + * \c Slapi_Value. + * \warning The returned pointer point to the actual \c berval structure + * inside of the value, not a copy. + * \warning You should not free the returned \c berval structure unless + * you plan to replace it by calling \c slapi_value_set_berval(). + * \see slapi_value_set_berval() + */ const struct berval *slapi_value_get_berval( const Slapi_Value *value ); + +/** + * Sets the value of a \c Slapi_Value structure from a \c berval structure. + * + * The value is duplicated from the passed in \c berval structure. + * + * \param value Pointer to the \c Slapi_Value structure in which to + * set the value. + * \param bval Pointer to the \c berval value to be copied. + * \return Pointer to the \c Slapi_Value structure passed in as \c value. + * \return NULL if the passed in value was \c NULL. + * \warning If the pointer to the \c Slapi_Value structure is \c NULL, + * nothing is done, and the function returns \c NULL. + * \warning If the \c Slapi_Value structure already contains a value, it + * is freed from memory before the new one is set. + * \warning When you are no longer using the \c Slapi_Value structure, you + * should free it from memory by valling \c slapi_value_free(). + * \see slapi_value_free() + * \see slapi_value_get_berval() + */ Slapi_Value *slapi_value_set_berval( Slapi_Value *value, const struct berval *bval ); + +/** + * Sets the value of a \c Slapi_Value structure from another \c Slapi_Value structure. + * + * The value is duplicated from the supplied \c Slapi_value structure. + * + * \param value Pointer to the \c Slapi_Value structure in which to set + * the value. + * \param vfrom Pointer to the \c Slapi_Value structure from which to + * get the value. + * \return Pointer to the \c Slapi_Value structure passed as the \c value paramter. + * \return \c NULL if the \c value parameter was \c NULL. + * \warning The \c vfrom parameter must not be \c NULL. + * \warning If the pointer to the \c Slapi_Value structure is \c NULL, + * nothing is done, and the function returns \c NULL. + * \warning If the \c Slapi_Value structure already contains a value, it + * is freed from memory before the new one is set. + * \warning When you are no longer using the \c Slapi_Value structure, you + * should free it from memory by valling \c slapi_value_free(). + * \see slapi_value_free() + */ Slapi_Value *slapi_value_set_value( Slapi_Value *value, const Slapi_Value *vfrom); + +/** + * Sets the value of a \c Slapi_Value structure. + * + * The value is a duplicate of the data pointed to by \c val and the + * length \c len. + * + * \param value Pointer to the \c Slapi_Value structure in which to set + * the value. + * \param val Pointer to the value. + * \param len Length of the value. + * \return Pointer to the \c Slapi_Value structure with the value set. + * \return \c NULL if the supplied \c Slapi_Value is \c NULL. + * \warning If the pointer to the \c Slapi_Value structure is \c NULL, + * nothing is done, and the function returns \c NULL. + * \warning If the \c Slapi_Value structure already contains a value, it + * is freed from memory before the new one is set. + * \warning When you are no longer using the \c Slapi_Value structure, you + * should free it from memory by valling \c slapi_value_free(). + * \see slapi_value_free() + */ Slapi_Value *slapi_value_set( Slapi_Value *value, void *val, unsigned long len); + +/** + * Sets the value of a \c Slapi_Value structure from a string. + * + * The value is duplicated from a supplied string. + * + * \param value Pointer to the \c Slapi_Value structure in which to set + * the value. + * \param strVal The string containing the value to set. + * \return \c 0 if the value is set. + * \return \c -1 if the pointer to the \c Slapi_Value is \c NULL. + * \warning If the pointer to the \c Slapi_Value structure is \c NULL, + * nothing is done, and the function returns \c -1. + * \warning If the \c Slapi_Value structure already contains a value, it + * is freed from memory before the new one is set. + * \warning When you are no longer using the \c Slapi_Value structure, you + * should free it from memory by valling \c slapi_value_free(). + * \see slapi_value_free() + * \see slapi_value_set_string_passin() + */ int slapi_value_set_string(Slapi_Value *value, const char *strVal); + +/** + * Sets the value of a \c Slapi_Value structure from a string. + * + * The supplied string is used as the value within the \c Slapi_Value + * structure. + * + * \param value Pointer to the \c Slapi_Value structure in which to set + * the value. + * \param strVal The string containing the value to set. + * \return \c 0 if the value is set. + * \return \c -1 if the pointer to the \c Slapi_Value is \c NULL. + * \warning Do not free the passed in string pointer to by \c strVal. + * Responsibility for the memory used by the string is handed + * over to the \c Slapi_Value structure. + * \warning When you are no longer using the \c Slapi_Value structure, you + * should free it from memory by valling \c slapi_value_free(). + * \see slapi_value_free() + * \see slapi_value_set_string() + */ int slapi_value_set_string_passin(Slapi_Value *value, char *strVal); + +/** + * Sets the value of a \c Slapi_Value structure from an integer. + * + * \param value Pointer to the \c Slapi_Value structure in which to set + * the value. + * \param intVal The integer containing the value to set. + * \return \c 0 if the value is set. + * \return \c -1 if the pointer to the \c Slapi_Value is \c NULL. + * \warning If the pointer to the \c Slapi_Value structure is \c NULL, + * nothing is done, and the function returns \c -1. + * \warning If the \c Slapi_Value structure already contains a value, it + * is freed from memory before the new one is set. + * \warning When you are no longer using the \c Slapi_Value structure, you + * should free it from memory by valling \c slapi_value_free(). + * \see slapi_value_free() + */ int slapi_value_set_int(Slapi_Value *value, int intVal); + +/** + * Retrieves the value of a \c Slapi_Value structure as a string. + * + * \param value Pointer to the value you wish to get as a string. + * \return A string containing the value. + * \return \c NULL if there is no value. + * \warning The returned string is the actual value, not a copy. You + * should not free the returned string unless you plan to + * replace it by calling slapi_value_set_string(). + * \see slapi_value_set_string() + */ const char*slapi_value_get_string(const Slapi_Value *value); + +/** + * Retrieves the value of a \c Slapi_Value structure as an integer. + * + * \param value Pointer to the value you wish to get as an integer. + * \return An integer that corresponds to the value stored in the + * \c Slapi_Value structure. + * \return \c 0 if there is no value. + * \see slapi_value_get_uint() + * \see slapi_value_get_long() + * \see slapi_value_get_ulong() + * \see slapi_value_get_longlong() + * \see slapi_value_get_ulonglong() + */ int slapi_value_get_int(const Slapi_Value *value); + +/** + * Retrieves the value of a \c Slapi_Value structure as an unsigned integer. + * + * \param value Pointer to the value you wish to get as an unsigned integer. + * \return An unsigned integer that corresponds to the value stored in + * the \c Slapi_Value structure. + * \return \c 0 if there is no value. + * \see slapi_value_get_int() + * \see slapi_value_get_long() + * \see slapi_value_get_ulong() + * \see slapi_value_get_longlong() + * \see slapi_value_get_ulonglong() + */ unsigned int slapi_value_get_uint(const Slapi_Value *value); + +/** + * Retrieves the value of a \c Slapi_Value structure as a long integer. + * + * \param value Pointer to the value you wish to get as a long integer. + * \return A long integer that corresponds to the value stored in the + * \c Slapi_Value structure. + * \return \c 0 if there is no value. + * \see slapi_value_get_int() + * \see slapi_value_get_uint() + * \see slapi_value_get_ulong() + * \see slapi_value_get_longlong() + * \see slapi_value_get_ulonglong() + */ long slapi_value_get_long(const Slapi_Value *value); + +/** + * Retrieves the value of a \c Slapi_Value structure as an unsigned long integer. + * + * \param value Pointer to the value you wish to get as an unsigned long integer. + * \return An unsigned long integer that corresponds to the value stored in the + * \c Slapi_Value structure. + * \return \c 0 if there is no value. + * \see slapi_value_get_int() + * \see slapi_value_get_uint() + * \see slapi_value_get_long() + * \see slapi_value_get_longlong() + * \see slapi_value_get_ulonglong() + */ unsigned long slapi_value_get_ulong(const Slapi_Value *value); + +/** + * Retrieves the value of a \c Slapi_Value structure as a long long integer. + * + * \param value Pointer to the value you wish to get as a long long integer. + * \return A long long integer that corresponds to the value stored in the + * \c Slapi_Value structure. + * \return \c 0 if there is no value. + * \see slapi_value_get_int() + * \see slapi_value_get_uint() + * \see slapi_value_get_long() + * \see slapi_value_get_ulong() + * \see slapi_value_get_ulonglong() + */ long long slapi_value_get_longlong(const Slapi_Value *value); + +/** + * Retrieves the value of a \c Slapi_Value structure as an unsigned long long integer. + * + * \param value Pointer to the value you wish to get as an unsigned long long integer. + * \return An unsigned long long integer that corresponds to the value stored in the + * \c Slapi_Value structure. + * \return \c 0 if there is no value. + * \see slapi_value_get_int() + * \see slapi_value_get_uint() + * \see slapi_value_get_long() + * \see slapi_value_get_ulong() + * \see slapi_value_get_longlong() + */ unsigned long long slapi_value_get_ulonglong(const Slapi_Value *value); + +/** + * Gets the length of a value contained in a \c Slapi_Value structure. + * + * \param value Pointer to the value of which you wish to get the length. + * \return The length of the value. + * \return \c 0 if there is no value. + */ size_t slapi_value_get_length(const Slapi_Value *value); + +/** + * Compares two \c Slapi_Value structures + * + * The matching rule associated with the supplied attribute \c a is used + * to compare the two values. + * + * \param a A pointer to an attribute used to determine how the + * two values will be compared. + * \param v1 Pointer to the \c Slapi_Value structure containing the first + * value to compare. + * \param v2 Pointer to the \c Slapi_Value structure containing the second + * value to compare. + * \return \c 0 if the two values are equal. + * \return \c -1 if \c v1 is smaller than \c v2. + * \return \c 1 if \c v1 is greater than \c v2. + */ int slapi_value_compare(const Slapi_Attr *a,const Slapi_Value *v1,const Slapi_Value *v2); /* * Valueset functions. */ + +/** + * Flag that indicates that the value should be used by reference. + * + * \see slapi_valueset_add_value_ext() + */ #define SLAPI_VALUE_FLAG_PASSIN 0x1 #define SLAPI_VALUE_FLAG_IGNOREERROR 0x2 #define SLAPI_VALUE_FLAG_PRESERVECSNSET 0x4 #define SLAPI_VALUE_FLAG_USENEWVALUE 0x8 /* see valueset_remove_valuearray */ +/** + * Creates an empty \c Slapi_ValueSet structure. + * + * \return Pointer to the newly allocated \c Slapi_ValueSet structure. + * \warning If no space can be allocated (for example, if no more virtual + * memory exists), the \c ns-slapd program terminates. + * \warning When you are no longer using the valueset, you should free it + * from memory by calling \c slapi_valueset_free(). + * \see slapi_valueset_free() + */ Slapi_ValueSet *slapi_valueset_new( void ); + +/** + * Free a \c Slapi_ValueSet structure from memory. + * + * Call this function when you are done working with the structure. + * All members of the valueset will be freed as well if they are not + * \c NULL. + * + * \param vs Pointer to the \c Slapi_ValueSet to free. + * \see slapi_valueset_done() + */ void slapi_valueset_free(Slapi_ValueSet *vs); + +/** + * Initializes a \c Slapi_ValueSet structure. + * + * All values inside of the structure will be cleared (set to \c 0). + * The values will not be freed by this function. To free the values + * first, call \c slapi_valueset_done(). + * + * \param vs Pointer to the \c Slapi_ValueSet to initialize. + * \warning When you are no longer using the \c Slapi_ValueSet structure, + * you should free it from memory by calling \c slapi_valueset_free(). + * \see slapi_valueset_done() + * \see slapi_valueset_free() + */ void slapi_valueset_init(Slapi_ValueSet *vs); + +/** + * Frees the values contained in a \c Slapi_ValueSet structure. + * + * \param vs Pointer to the \c Slapi_ValueSet structure from which + * you want to free its values. + * \warning Use this function when you are no longer using the values + * but you want to re-use the \c Slapi_ValueSet structure for + * a new set of values. + * \see slapi_valueset_init() + */ void slapi_valueset_done(Slapi_ValueSet *vs); + +/** + * Adds a value to a \c Slapi_ValueSet structure. + * + * \param vs Pointer to the \c Slapi_ValueSet structure to which to + * add the value. + * \param addval Pointer to the \c Slapi_Value structure to add to + * the \c Slapi_ValueSet. + * \warning The value is duplicated from the \c Slapi_Value structure, + * which can be freed frmo memory without altering the + * \c Slapi_ValueSet structure. + * \warning This function does not verify if the value is already present + * in the \c Slapi_ValueSet structure. You can manually check + * this using \c slapi_valueset_first_value() and + * \c slapi_valueset_next_value(). + * \see slapi_valueset_first_value() + * \see slapi_valueset_next_value() + */ void slapi_valueset_add_value(Slapi_ValueSet *vs, const Slapi_Value *addval); + +/** + * Adds a value to a \c Slapi_ValueSet structure with optional flags. + * + * This function is similar to \c slapi_valueset_add_value(), but it + * allows optional flags to be specified to allow the new value to be + * used by reference. + * + * \param vs Pointer to the \c Slapi_ValueSet structure to which to + * add the value. + * \param addval Pointer to the \c Slapi_Value structure to add to + * the \c Slapi_ValueSet. + * \param flags If #SLAPI_VALUE_FLAG_PASSIN bit is set in the flags, + * the function will take over the ownership of the new value + * to be added without duplicating it. + * \warning This function does not verify if the value is already present + * in the \c Slapi_ValueSet structure. You can manually check + * this using \c slapi_valueset_first_value() and + * \c slapi_valueset_next_value(). + * \see slapi_valueset_add_value() + * \see slapi_valueset_first_value() + * \see slapi_valueset_next_value() + */ void slapi_valueset_add_value_ext(Slapi_ValueSet *vs, Slapi_Value *addval, unsigned long flags); + +/** + * Gets the first value in a \c Slapi_ValueSet structure. + * + * This function can be used with \c slapi_valueset_next_value() to + * iterate through all values in a \c Slapi_ValueSet structure. + * + * \param vs Pointer to the \c Slapi_ValueSet structure from which + * you wish to get the value. + * \param v Address of the pointer to the \c Slapi_Value structure + * for the returned value. + * \return The index of the value in the Slapi_ValueSet structure. + * \return \c -1 if there was no value. + * \warning This function gives a pointer to the actual value within + * the \c Slapi_ValueSet structure. You should not free it + * from memory. + * \warning You will need to pass this index to slapi_valueset_next_value() + * if you wish to iterate through all values in the valueset. + * \see slapi_valueset_next_value(). + */ int slapi_valueset_first_value( Slapi_ValueSet *vs, Slapi_Value **v ); + +/** + * Gets the next value in a \c Slapi_ValueSet structure. + * + * This is part of a pair of iterator functions. It should be + * called after first calling \c slapi_valueset_first_value(). + * + * \param vs Pointer to the \c Slapi_ValueSet structure from which + * you wish to get the value. + * \param index Value returned by the previous call to \c slapi_valueset_first_value() + * or \c slapi_valueset_next_value(). + * \param v Address of the pointer to the \c Slapi_Value structure + * for the returned value. + * \return The index of the value in the Slapi_ValueSet structure. + * \return \c -1 if there was no value. + * \warning This function gives a pointer to the actual value within + * the \c Slapi_ValueSet structure. You should not free it + * from memory. + * \warning You will need to pass this index to slapi_valueset_next_value() + * if you wish to iterate through all values in the valueset. + * \see slapi_valueset_first_value() + */ int slapi_valueset_next_value( Slapi_ValueSet *vs, int index, Slapi_Value **v); + +/** + * Returns the number of values contained in a \c Slapi_ValueSet structure. + * + * \param vs Pointer to the \c Slapi_ValueSet structure of which + * you wish to get the count. + * \return The number of values contained in the \c Slapi_ValueSet structure. + */ int slapi_valueset_count( const Slapi_ValueSet *vs); + +/** + * Initializes a \c Slapi_ValueSet with copies of the values of a \c Slapi_Mod structure. + * + * \param vs Pointer to the \c Slapi_ValueSet structure into which + * you wish to copy the values. + * \param smod Pointer to the \c Slapi_Mod structure from which you + * want to copy the values. + * \warning This function does not verify that the \c Slapi_ValueSet + * structure already contains values, so it is your responsibility + * to verify that there are no values prior to calling this function. + * If you do not verify this, the allocated memory space will leak. + * You can free existing values by calling slapi_valueset_done(). + * \see slapi_valueset_done() + */ void slapi_valueset_set_from_smod(Slapi_ValueSet *vs, Slapi_Mod *smod); + +/** + * Initializes a \c Slapi_ValueSet with copies of the values of another \c Slapi_ValueSet. + * + * \param vs1 Pointer to the \c Slapi_ValueSet structure into which + * you wish to copy the values. + * \param vs2 Pointer to the \c Slapi_ValueSet structure from which + * you want to copy the values. + * \warning This function does not verify that the \c Slapi_ValueSet + * structure already contains values, so it is your responsibility + * to verify that there are no values prior to calling this function. + * If you do not verify this, the allocated memory space will leak. + * You can free existing values by calling slapi_valueset_done(). + * \see slapi_valueset_done() + */ void slapi_valueset_set_valueset(Slapi_ValueSet *vs1, const Slapi_ValueSet *vs2); + +/** + * Finds a requested value in a valueset. + * + * The syntax of a supplied attribute will be used to compare the values. + * This function can be used to check for duplicate values in a valueset. + * + * \param a Pointer to the attribute. This is used to determine the + * syntax of the values and how to match them. + * \param vs Pointer to the \c Slapi_ValueSet structure from which + * you wish to find the value. + * \param v Pointer to the \c Slapi_Value structure containing the + * value that you wish to find. + * \return Pointer to the value in the valueset if the value was found. + * \return \c NULL if the value was not found. + * \warning The returned pointer points to the actual value in the + * \c Slapi_ValueSet structure. It should not be freed. + */ Slapi_Value *slapi_valueset_find(const Slapi_Attr *a, const Slapi_ValueSet *vs, const Slapi_Value *v); +/* TODO - Pickup Doxygen work here */ /* * operation routines */ -- 1.6.2.5
-- 389-devel mailing list 389-devel@xxxxxxxxxxxxxxxxxxxxxxx https://admin.fedoraproject.org/mailman/listinfo/389-devel
