Don't walk past the end of ldb values.
[tprouty/samba.git] / source / lib / ldb / include / ldb.h
index 41d23b5d1030b9b51d460fd97ce846e7038ea721..5dbf99e5bf9aa2aaf88ae34ba9b25089b2b2e1f7 100644 (file)
@@ -203,7 +203,7 @@ struct ldb_debug_ops {
 */
 struct ldb_utf8_fns {
        void *context;
-       char *(*casefold)(void *context, void *mem_ctx, const char *s);
+       char *(*casefold)(void *context, TALLOC_CTX *mem_ctx, const char *s);
 };
 
 /**
@@ -280,8 +280,8 @@ struct ldb_parse_tree {
        } u;
 };
 
-struct ldb_parse_tree *ldb_parse_tree(void *mem_ctx, const char *s);
-char *ldb_filter_from_tree(void *mem_ctx, struct ldb_parse_tree *tree);
+struct ldb_parse_tree *ldb_parse_tree(TALLOC_CTX *mem_ctx, const char *s);
+char *ldb_filter_from_tree(TALLOC_CTX *mem_ctx, struct ldb_parse_tree *tree);
 
 /**
    Encode a binary blob
@@ -290,14 +290,14 @@ char *ldb_filter_from_tree(void *mem_ctx, struct ldb_parse_tree *tree);
    2254 (Section 4). This function also escapes any non-printable
    characters.
 
-   \param ctx the memory context to allocate the return string in.
+   \param mem_ctx the memory context to allocate the return string in.
    \param val the (potentially) binary data to be encoded
 
    \return the encoded data as a null terminated string
 
    \sa <a href="http://www.ietf.org/rfc/rfc2252.txt">RFC 2252</a>.
 */
-char *ldb_binary_encode(void *ctx, struct ldb_val val);
+char *ldb_binary_encode(TALLOC_CTX *mem_ctx, struct ldb_val val);
 
 /**
    Encode a string
@@ -313,13 +313,13 @@ char *ldb_binary_encode(void *ctx, struct ldb_val val);
 
    \sa <a href="http://www.ietf.org/rfc/rfc2252.txt">RFC 2252</a>.
 */
-char *ldb_binary_encode_string(void *mem_ctx, const char *string);
+char *ldb_binary_encode_string(TALLOC_CTX *mem_ctx, const char *string);
 
 /*
   functions for controlling attribute handling
 */
-typedef int (*ldb_attr_handler_t)(struct ldb_context *, void *mem_ctx, const struct ldb_val *, struct ldb_val *);
-typedef int (*ldb_attr_comparison_t)(struct ldb_context *, void *mem_ctx, const struct ldb_val *, const struct ldb_val *);
+typedef int (*ldb_attr_handler_t)(struct ldb_context *, TALLOC_CTX *mem_ctx, const struct ldb_val *, struct ldb_val *);
+typedef int (*ldb_attr_comparison_t)(struct ldb_context *, TALLOC_CTX *mem_ctx, const struct ldb_val *, const struct ldb_val *);
 
 /*
   attribute handler structure
@@ -358,9 +358,9 @@ const struct ldb_schema_attribute *ldb_schema_attribute_by_name(struct ldb_conte
 #define LDB_ATTR_FLAG_ALLOCATED    (1<<1) 
 
 /**
-   The attribute is constructed from other attributes
+   The attribute is supplied by the application and should not be removed
 */
-#define LDB_ATTR_FLAG_CONSTRUCTED  (1<<1
+#define LDB_ATTR_FLAG_FIXED        (1<<2
 
 /**
   LDAP attribute syntax for a DN
@@ -705,7 +705,7 @@ struct ldb_handle {
 struct ldb_search {
        struct ldb_dn *base;
        enum ldb_scope scope;
-       const struct ldb_parse_tree *tree;
+       struct ldb_parse_tree *tree;
        const char * const *attrs;
        struct ldb_result *res;
 };
@@ -735,12 +735,14 @@ struct ldb_register_partition {
        struct ldb_dn *dn;
 };
 
+enum ldb_sequence_type {
+       LDB_SEQ_HIGHEST_SEQ,
+       LDB_SEQ_HIGHEST_TIMESTAMP,
+       LDB_SEQ_NEXT
+};
+
 struct ldb_sequence_number {
-       enum ldb_sequence_type {
-               LDB_SEQ_HIGHEST_SEQ,
-               LDB_SEQ_HIGHEST_TIMESTAMP,
-               LDB_SEQ_NEXT
-       } type;
+       enum ldb_sequence_type type;
        uint64_t seq_num;
        uint32_t flags;
 };
@@ -780,6 +782,9 @@ int ldb_set_timeout(struct ldb_context *ldb, struct ldb_request *req, int timeou
 int ldb_set_timeout_from_prev_req(struct ldb_context *ldb, struct ldb_request *oldreq, struct ldb_request *newreq);
 void ldb_set_create_perms(struct ldb_context *ldb, unsigned int perms);
 void ldb_set_modules_dir(struct ldb_context *ldb, const char *path);
+struct event_context;
+void ldb_set_event_context(struct ldb_context *ldb, struct event_context *ev);
+struct event_context * ldb_get_event_context(struct ldb_context *ldb);
 
 /**
   Initialise ldbs' global information
@@ -801,7 +806,7 @@ int ldb_global_init(void);
   \return pointer to ldb_context that should be free'd (using talloc_free())
   at the end of the program.
 */
-struct ldb_context *ldb_init(void *mem_ctx);
+struct ldb_context *ldb_init(TALLOC_CTX *mem_ctx, struct event_context *ev_ctx);
 
 /**
    Connect to a database.
@@ -884,14 +889,14 @@ int ldb_search_default_callback(struct ldb_context *ldb, void *context, struct l
   \param attrs the search attributes for the query (pass NULL if none required)
   \param controls an array of controls
   \param context the callback function context
-  \param the callback function to handle the async replies
+  \param callback the callback function to handle the async replies
 
   \return result code (LDB_SUCCESS on success, or a failure code)
 */
 
 int ldb_build_search_req(struct ldb_request **ret_req,
                        struct ldb_context *ldb,
-                       void *mem_ctx,
+                       TALLOC_CTX *mem_ctx,
                        struct ldb_dn *base,
                        enum ldb_scope scope,
                        const char *expression,
@@ -909,14 +914,14 @@ int ldb_build_search_req(struct ldb_request **ret_req,
   \param message contains the entry to be added 
   \param controls an array of controls
   \param context the callback function context
-  \param the callback function to handle the async replies
+  \param callback the callback function to handle the async replies
 
   \return result code (LDB_SUCCESS on success, or a failure code)
 */
 
 int ldb_build_add_req(struct ldb_request **ret_req,
                        struct ldb_context *ldb,
-                       void *mem_ctx,
+                       TALLOC_CTX *mem_ctx,
                        const struct ldb_message *message,
                        struct ldb_control **controls,
                        void *context,
@@ -931,14 +936,14 @@ int ldb_build_add_req(struct ldb_request **ret_req,
   \param message contains the entry to be modified
   \param controls an array of controls
   \param context the callback function context
-  \param the callback function to handle the async replies
+  \param callback the callback function to handle the async replies
 
   \return result code (LDB_SUCCESS on success, or a failure code)
 */
 
 int ldb_build_mod_req(struct ldb_request **ret_req,
                        struct ldb_context *ldb,
-                       void *mem_ctx,
+                       TALLOC_CTX *mem_ctx,
                        const struct ldb_message *message,
                        struct ldb_control **controls,
                        void *context,
@@ -953,14 +958,14 @@ int ldb_build_mod_req(struct ldb_request **ret_req,
   \param dn the DN to be deleted
   \param controls an array of controls
   \param context the callback function context
-  \param the callback function to handle the async replies
+  \param callback the callback function to handle the async replies
 
   \return result code (LDB_SUCCESS on success, or a failure code)
 */
 
 int ldb_build_del_req(struct ldb_request **ret_req,
                        struct ldb_context *ldb,
-                       void *mem_ctx,
+                       TALLOC_CTX *mem_ctx,
                        struct ldb_dn *dn,
                        struct ldb_control **controls,
                        void *context,
@@ -976,14 +981,14 @@ int ldb_build_del_req(struct ldb_request **ret_req,
   \param newdn the new DN
   \param controls an array of controls
   \param context the callback function context
-  \param the callback function to handle the async replies
+  \param callback the callback function to handle the async replies
 
   \return result code (LDB_SUCCESS on success, or a failure code)
 */
 
 int ldb_build_rename_req(struct ldb_request **ret_req,
                        struct ldb_context *ldb,
-                       void *mem_ctx,
+                       TALLOC_CTX *mem_ctx,
                        struct ldb_dn *olddn,
                        struct ldb_dn *newdn,
                        struct ldb_control **controls,
@@ -995,7 +1000,7 @@ int ldb_build_rename_req(struct ldb_request **ret_req,
 
   \param req the request struct where to add the control
   \param oid the object identifier of the control as string
-  \param ciritical whether the control should be critical or not
+  \param critical whether the control should be critical or not
   \param data a talloc pointer to the control specific data
 
   \return result code (LDB_SUCCESS on success, or a failure code)
@@ -1135,13 +1140,13 @@ int ldb_extended_default_callback(struct ldb_context *ldb, void *context, struct
   it needs to be NULL or a valid talloc pointer! talloc_get_type() will be used on it  
   \param controls an array of controls
   \param context the callback function context
-  \param the callback function to handle the async replies
+  \param callback the callback function to handle the async replies
 
   \return result code (LDB_SUCCESS on success, or a failure code)
 */
 int ldb_build_extended_req(struct ldb_request **ret_req,
                           struct ldb_context *ldb,
-                          void *mem_ctx,
+                          TALLOC_CTX *mem_ctx,
                           const char *oid,
                           void *data,/* NULL or a valid talloc pointer! talloc_get_type() will be used on it */
                           struct ldb_control **controls,
@@ -1211,11 +1216,11 @@ void ldb_set_utf8_default(struct ldb_context *ldb);
    \note The default function is not yet UTF8 aware. Provide your own
          set of functions through ldb_set_utf8_fns()
 */
-char *ldb_casefold(struct ldb_context *ldb, void *mem_ctx, const char *s);
+char *ldb_casefold(struct ldb_context *ldb, TALLOC_CTX *mem_ctx, const char *s);
 
 /**
    Check the attribute name is valid according to rfc2251
-   \param s tthe string to check
+   \param s the string to check
 
    \return 1 if the name is ok
 */
@@ -1224,6 +1229,7 @@ int ldb_valid_attr_name(const char *s);
 /*
   ldif manipulation functions
 */
+
 /**
    Write an LDIF message
 
@@ -1355,7 +1361,7 @@ int ldb_ldif_write_file(struct ldb_context *ldb, FILE *f, const struct ldb_ldif
 
    \note The caller is responsible for freeing the result
 */
-char *ldb_base64_encode(void *mem_ctx, const char *buf, int len);
+char *ldb_base64_encode(TALLOC_CTX *mem_ctx, const char *buf, int len);
 
 /**
    Base64 decode a buffer
@@ -1373,15 +1379,16 @@ int ldb_base64_decode(char *s);
 
 /* The following definitions come from lib/ldb/common/ldb_dn.c  */
 
-struct ldb_dn *ldb_dn_new(void *mem_ctx, struct ldb_context *ldb, const char *dn);
-struct ldb_dn *ldb_dn_new_fmt(void *mem_ctx, struct ldb_context *ldb, const char *new_fmt, ...) PRINTF_ATTRIBUTE(3,4);
+struct ldb_dn *ldb_dn_new(TALLOC_CTX *mem_ctx, struct ldb_context *ldb, const char *dn);
+struct ldb_dn *ldb_dn_new_fmt(TALLOC_CTX *mem_ctx, struct ldb_context *ldb, const char *new_fmt, ...) PRINTF_ATTRIBUTE(3,4);
+struct ldb_dn *ldb_dn_from_ldb_val(void *mem_ctx, struct ldb_context *ldb, const struct ldb_val *strdn);
 bool ldb_dn_validate(struct ldb_dn *dn);
 
-char *ldb_dn_escape_value(void *mem_ctx, struct ldb_val value);
+char *ldb_dn_escape_value(TALLOC_CTX *mem_ctx, struct ldb_val value);
 const char *ldb_dn_get_linearized(struct ldb_dn *dn);
 const char *ldb_dn_get_casefold(struct ldb_dn *dn);
-char *ldb_dn_alloc_linearized(void *mem_ctx, struct ldb_dn *dn);
-char *ldb_dn_alloc_casefold(void *mem_ctx, struct ldb_dn *dn);
+char *ldb_dn_alloc_linearized(TALLOC_CTX *mem_ctx, struct ldb_dn *dn);
+char *ldb_dn_alloc_casefold(TALLOC_CTX *mem_ctx, struct ldb_dn *dn);
 
 int ldb_dn_compare_base(struct ldb_dn *base, struct ldb_dn *dn);
 int ldb_dn_compare(struct ldb_dn *edn0, struct ldb_dn *edn1);
@@ -1393,10 +1400,10 @@ bool ldb_dn_add_child_fmt(struct ldb_dn *dn, const char *child_fmt, ...) PRINTF_
 bool ldb_dn_remove_base_components(struct ldb_dn *dn, unsigned int num);
 bool ldb_dn_remove_child_components(struct ldb_dn *dn, unsigned int num);
 
-struct ldb_dn *ldb_dn_copy(void *mem_ctx, struct ldb_dn *dn);
-struct ldb_dn *ldb_dn_get_parent(void *mem_ctx, struct ldb_dn *dn);
-char *ldb_dn_canonical_string(void *mem_ctx, struct ldb_dn *dn);
-char *ldb_dn_canonical_ex_string(void *mem_ctx, struct ldb_dn *dn);
+struct ldb_dn *ldb_dn_copy(TALLOC_CTX *mem_ctx, struct ldb_dn *dn);
+struct ldb_dn *ldb_dn_get_parent(TALLOC_CTX *mem_ctx, struct ldb_dn *dn);
+char *ldb_dn_canonical_string(TALLOC_CTX *mem_ctx, struct ldb_dn *dn);
+char *ldb_dn_canonical_ex_string(TALLOC_CTX *mem_ctx, struct ldb_dn *dn);
 int ldb_dn_get_comp_num(struct ldb_dn *dn);
 const char *ldb_dn_get_component_name(struct ldb_dn *dn, unsigned int num);
 const struct ldb_val *ldb_dn_get_component_val(struct ldb_dn *dn, unsigned int num);
@@ -1416,8 +1423,8 @@ bool ldb_dn_is_null(struct ldb_dn *dn);
    This function compares to attribute names. Note that this is a
    case-insensitive comparison.
 
-   \param attr1 the first attribute name to compare
-   \param attr2 the second attribute name to compare
+   \param a the first attribute name to compare
+   \param b the second attribute name to compare
 
    \return 0 if the attribute names are the same, or only differ in
    case; non-zero if there are any differences
@@ -1427,7 +1434,7 @@ bool ldb_dn_is_null(struct ldb_dn *dn);
   return 0 for match
 */
 #define ldb_attr_cmp(a, b) strcasecmp(a, b)
-char *ldb_attr_casefold(void *mem_ctx, const char *s);
+char *ldb_attr_casefold(TALLOC_CTX *mem_ctx, const char *s);
 int ldb_attr_dn(const char *attr);
 
 /**
@@ -1437,7 +1444,7 @@ int ldb_attr_dn(const char *attr);
    to get the top level context, however the ldb context (from
    ldb_init()) may be a better choice
 */
-struct ldb_message *ldb_msg_new(void *mem_ctx);
+struct ldb_message *ldb_msg_new(TALLOC_CTX *mem_ctx);
 
 /**
    Find an element within an message
@@ -1531,15 +1538,15 @@ const char *ldb_msg_find_attr_as_string(const struct ldb_message *msg,
                                        const char *default_value);
 
 struct ldb_dn *ldb_msg_find_attr_as_dn(struct ldb_context *ldb,
-                                      void *mem_ctx,
+                                      TALLOC_CTX *mem_ctx,
                                       const struct ldb_message *msg,
                                       const char *attr_name);
 
 void ldb_msg_sort_elements(struct ldb_message *msg);
 
-struct ldb_message *ldb_msg_copy_shallow(void *mem_ctx, 
+struct ldb_message *ldb_msg_copy_shallow(TALLOC_CTX *mem_ctx, 
                                         const struct ldb_message *msg);
-struct ldb_message *ldb_msg_copy(void *mem_ctx, 
+struct ldb_message *ldb_msg_copy(TALLOC_CTX *mem_ctx, 
                                 const struct ldb_message *msg);
 
 struct ldb_message *ldb_msg_canonicalize(struct ldb_context *ldb, 
@@ -1560,6 +1567,7 @@ int ldb_msg_check_string_attribute(const struct ldb_message *msg,
    This function performs basic sanity / integrity checks on an
    ldb_message.
 
+   \param ldb context in which to perform the checks
    \param msg the message to check
 
    \return LDB_SUCCESS if the message is OK, or a non-zero error code
@@ -1581,7 +1589,7 @@ int ldb_msg_sanity_check(struct ldb_context *ldb,
 
    \return the duplicated ldb_val structure.
 */
-struct ldb_val ldb_val_dup(void *mem_ctx, const struct ldb_val *v);
+struct ldb_val ldb_val_dup(TALLOC_CTX *mem_ctx, const struct ldb_val *v);
 
 /**
   this allows the user to set a debug function for error reporting
@@ -1607,8 +1615,8 @@ int ldb_set_debug_stderr(struct ldb_context *ldb);
 int ldb_set_opaque(struct ldb_context *ldb, const char *name, void *value);
 void *ldb_get_opaque(struct ldb_context *ldb, const char *name);
 
-const char **ldb_attr_list_copy(void *mem_ctx, const char * const *attrs);
-const char **ldb_attr_list_copy_add(void *mem_ctx, const char * const *attrs, const char *new_attr);
+const char **ldb_attr_list_copy(TALLOC_CTX *mem_ctx, const char * const *attrs);
+const char **ldb_attr_list_copy_add(TALLOC_CTX *mem_ctx, const char * const *attrs, const char *new_attr);
 int ldb_attr_in_list(const char * const *attrs, const char *attr);
 
 
@@ -1632,7 +1640,7 @@ void ldb_msg_remove_attr(struct ldb_message *msg, const char *attr);
    \return the formatted string, or NULL if the time structure could
    not be converted
 */
-char *ldb_timestring(void *mem_ctx, time_t t);
+char *ldb_timestring(TALLOC_CTX *mem_ctx, time_t t);
 
 /**
    Convert a string to a time structure
@@ -1658,7 +1666,7 @@ time_t ldb_string_to_time(const char *s);
    \return the formatted string, or NULL if the time structure could
    not be converted
 */
-char *ldb_timestring_utc(void *mem_ctx, time_t t);
+char *ldb_timestring_utc(TALLOC_CTX *mem_ctx, time_t t);
 
 /**
    Convert a string to a time structure
@@ -1685,6 +1693,6 @@ void ldb_qsort (void *const pbase, size_t total_elems, size_t size, void *opaque
 
    \return array of ldb_control elements
 */
-struct ldb_control **ldb_parse_control_strings(struct ldb_context *ldb, void *mem_ctx, const char **control_strings);
+struct ldb_control **ldb_parse_control_strings(struct ldb_context *ldb, TALLOC_CTX *mem_ctx, const char **control_strings);
 
 #endif