From: Gary Lockyer Date: Mon, 6 Oct 2025 03:04:41 +0000 (+1300) Subject: s4:dsdb:audit_log clean up doc comments X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=568740313ed162f083bc8254e967f59651a89bf3;p=thirdparty%2Fsamba.git s4:dsdb:audit_log clean up doc comments Signed-off-by: Gary Lockyer Reviewed-by: Douglas Bagnall --- diff --git a/source4/dsdb/samdb/ldb_modules/audit_log.c b/source4/dsdb/samdb/ldb_modules/audit_log.c index 92570e2f4ec..c944a84b360 100644 --- a/source4/dsdb/samdb/ldb_modules/audit_log.c +++ b/source4/dsdb/samdb/ldb_modules/audit_log.c @@ -102,6 +102,8 @@ struct audit_private { * Does the message contain a change to one of the password attributes? The * password attributes are defined in DSDB_PASSWORD_ATTRIBUTES * + * @param[in] message the ldb_message to examine + * * @return true if the message contains a password attribute * */ @@ -143,6 +145,8 @@ static bool has_password_changed(const struct ldb_message *message) * database -- a message setting an attribute to its current * value will still be logged as a change. * + * @param[in] message the ldb_message to examine + * * @return true if the message contains authentication information */ static bool has_authentication_information_changed( @@ -169,8 +173,8 @@ static bool has_authentication_information_changed( * This routine assumes that the request contains password attributes and that the * password ACL checks have been performed by acl.c * - * @param request the ldb_request to inspect - * @param reply the ldb_reply, will contain the password controls + * @param[in] request the ldb_request to inspect + * @param[in] reply the ldb_reply, will contain the password controls * * @return The windows event code. */ @@ -209,8 +213,8 @@ static enum event_id_type get_password_windows_event_id( * routine assumes that the request contains password attributes and that the * password ACL checks have been performed by acl.c * - * @param request the ldb_request to inspect - * @param reply the ldb_reply, will contain the password controls + * @param[in] request the ldb_request to inspect + * @param[in] reply the ldb_reply, will contain the password controls * * @return "Change" if the password is being changed. * "Reset" if the password is being reset. @@ -249,12 +253,12 @@ static const char *get_password_action( * * Generate a JSON object detailing an ldb operation. * - * @param module the ldb module - * @param request the request - * @param reply the result of the operation. + * @param[in] module the ldb module + * @param[in] request the request + * @param[in] reply the result of the operation. * * @return the generated JSON object, should be freed with json_free. - * + * in the event of an error it will return json_empty_object * */ static struct json_object operation_json( @@ -393,12 +397,12 @@ failure: * * Generate a JSON object detailing a replicated update * - * @param module the ldb module - * @param request the request - * @paran reply the result of the operation + * @param[in] module the ldb module + * @param[in] request the request + * @param[in] reply the result of the operation * * @return the generated JSON object, should be freed with json_free. - * NULL if there was an error generating the message. + * in the event of an error it will return json_empty_object * */ static struct json_object replicated_update_json( @@ -511,12 +515,13 @@ failure: * * Generate a JSON object detailing a password change. * - * @param module the ldb module - * @param request the request - * @param reply the result/response - * @param status the status code returned for the underlying ldb operation. + * @param[in] module the ldb module + * @param[in] request the request + * @param[in] reply the result/response + * @param[in] auth_info_changed was authentication information changed? * - * @return the generated JSON object. + * @return the generated JSON object, should be freed with json_free. + * in the event of an error it will return json_empty_object * */ static struct json_object password_change_json( @@ -639,12 +644,12 @@ failure: * Create a JSON object detailing a transaction transaction life cycle events, * i.e. begin, commit, roll back * - * @param action a one word description of the event/action - * @param transaction_id the GUID identifying the current transaction. - * @param status the status code returned by the operation - * @param duration the duration of the operation. + * @param action[in] a one word description of the event/action + * @param transaction_id[in] the GUID identifying the current transaction. + * @param duration[in] the duration of the operation. * - * @return a JSON object detailing the event + * @return the generated JSON object, should be freed with json_free. + * in the event of an error it will return json_empty_object */ static struct json_object transaction_json( const char *action, @@ -717,10 +722,14 @@ failure: * * Generate a JSON object containing details of a commit failure. * - * @param action the commit action, "commit" or "prepare" - * @param status the status code returned by commit - * @param reason any extra failure information/reason available - * @param transaction_id the GUID identifying the current transaction. + * @param action[in] the commit action, "commit" or "prepare" + * @param duration[in] the duration of the operation. + * @param status[in] the status code returned by commit + * @param reason[in] any extra failure information/reason available + * @param transaction_id[in] the GUID identifying the current transaction. + * + * @return the generated JSON object, should be freed with json_free. + * in the event of an error it will return json_empty_object */ static struct json_object commit_failure_json( const char *action, @@ -805,11 +814,12 @@ failure: * * Generate a human readable log line detailing a password change. * - * @param mem_ctx The talloc context that will own the generated log line. - * @param module the ldb module - * @param request the request - * @param reply the result/response - * @param status the status code returned for the underlying ldb operation. + * @param[in] mem_ctx the talloc context that will own the + * generated log line. + * @param[in] module the ldb module + * @param[in] request the request + * @param[in] reply the result/response + * @param[in] auth_info_changed was authentication information changed? * * @return the generated log line. */ @@ -865,11 +875,13 @@ static char *password_change_human_readable( * Base64 values are enclosed in {} * Truncated values are indicated by three trailing dots "..." * - * @param ldb The ldb_context - * @param buffer The attributes will be appended to the buffer. - * assumed to have been allocated via talloc. - * @param operation The operation type - * @param message the message to process + * @param[in] ldb the ldb_context + * @param[out] buffer the attributes will be appended to the buffer. + * assumed to have been allocated via talloc. + * @param[in] operation the operation type + * @param[in] message the message to process + * + * @return a pointer to buffer * */ static char *log_attributes( @@ -962,10 +974,10 @@ static char *log_attributes( * * Generate a human readable log entry detailing an ldb operation. * - * @param mem_ctx The talloc context owning the returned string. - * @param module the ldb module - * @param request the request - * @param reply the result of the operation + * @param[in] mem_ctx the talloc context owning the returned string. + * @param[in] module the ldb module + * @param[in] request the request + * @param[in] reply the result of the operation * * @return the log entry. * @@ -1041,10 +1053,10 @@ static char *operation_human_readable( * * Generate a human readable log entry detailing a replicated update operation * - * @param mem_ctx The talloc context owning the returned string. - * @param module the ldb module - * @param request the request - * @param reply the result of the operation. + * @param[in] mem_ctx the talloc context owning the returned string. + * @param[in] module the ldb module + * @param[in] request the request + * @param[in] reply the result of the operation. * * @return the log entry. * @@ -1103,9 +1115,9 @@ static char *replicated_update_human_readable( * Create a human readable log entry detailing a transaction event. * i.e. begin, commit, roll back * - * @param mem_ctx The talloc context owning the returned string. - * @param action a one word description of the event/action - * @param duration the duration of the transaction. + * @param[in] mem_ctx the talloc context owning the returned string. + * @param[in] action a one word description of the event/action + * @param[in] duration the duration of the transaction. * * @return the log entry */ @@ -1137,10 +1149,11 @@ static char *transaction_human_readable( * * Generate generate a human readable log entry detailing a commit failure. * - * @param mem_ctx The talloc context owning the returned string. - * @param action the commit action, "prepare" or "commit" - * @param status the status code returned by commit - * @param reason any extra failure information/reason available + * @param[in] mem_ctx the talloc context owning the returned string. + * @param[in] action the commit action, "prepare" or "commit" + * @param[in] duration the duration of the transaction. + * @param[in] status the status code returned by commit + * @param[in] reason any extra failure information/reason available * * @return the log entry */ @@ -1177,10 +1190,9 @@ static char *commit_failure_human_readable( * Log the details of an ldb operation in JSON and or human readable format * and send over the message bus. * - * @param module the ldb_module - * @param request the operation request. - * @param reply the operation result. - * @param the status code returned for the operation. + * @param[in] module the ldb_module + * @param[in] request the operation request. + * @param[in] reply the operation result. * */ static void log_standard_operation( @@ -1309,9 +1321,9 @@ static void log_standard_operation( * Log the details of a replicated update in JSON and or human readable * format and send over the message bus. * - * @param module the ldb_module + * @param module the ldb_module * @param request the operation request - * @param reply the result of the operation. + * @param reply the result of the operation. * */ static void log_replicated_operation( @@ -1366,9 +1378,9 @@ static void log_replicated_operation( * Log the details of an ldb operation in JSON and or human readable format * and send over the message bus. * - * @param module the ldb_module - * @param request the operation request - * @part reply the result of the operation + * @param[in] module the ldb_module + * @param[in] request the operation request + * @param[in] reply the result of the operation * */ static void log_operation( @@ -1395,9 +1407,9 @@ static void log_operation( * Log the details of a transaction event in JSON and or human readable format * and send over the message bus. * - * @param module the ldb_module - * @param action the transaction event i.e. begin, commit, roll back. - * @param log_level the logging level + * @param[in] module the ldb_module + * @param[in] action the transaction event i.e. begin, commit, roll back. + * @param[in] log_level the logging level * */ static void log_transaction( @@ -1453,9 +1465,9 @@ static void log_transaction( * Log the details of a commit failure in JSON and or human readable * format and send over the message bus. * - * @param module the ldb_module - * @param action the commit action "prepare" or "commit" - * @param status the ldb status code returned by prepare commit. + * @param[in] module the ldb_module + * @param[in] action the commit action "prepare" or "commit" + * @param[in] status the ldb status code returned by prepare commit. * */ static void log_commit_failure( @@ -1531,8 +1543,8 @@ struct audit_callback_context { * the operations, a callback needs to be registered to process the results * of the LDB operations. * - * @param req the ldb request - * @param res the result of the operation + * @param[in] req the ldb request + * @param[in] res the result of the operation * * @return the LDB_STATUS */ @@ -1588,8 +1600,8 @@ static int audit_callback(struct ldb_request *req, struct ldb_reply *ares) * Add the current transaction identifier in the module private data, * to the request as a control. * - * @param module - * @param req the request. + * @param[in] module the ldb_module + * @param[in] req the request. * * @return an LDB_STATUS code, LDB_SUCCESS if successful. */ @@ -1624,8 +1636,8 @@ static int add_transaction_id( * * Log the details of an add operation. * - * @param module the ldb_module - * @param req the ldb_request + * @param[in] module the ldb_module + * @param[in] req the ldb_request * * @return ldb status code */ @@ -1675,8 +1687,8 @@ static int log_add( * * Log the details of an delete operation. * - * @param module the ldb_module - * @param req the ldb_request + * @param[in] module the ldb_module + * @param[in] req the ldb_request * * @return ldb status code */ @@ -1725,8 +1737,8 @@ static int log_delete( * * Log the details of a modify operation. * - * @param module the ldb_module - * @param req the ldb_request + * @param[in] module the ldb_module + * @param[in] req the ldb_request * * @return ldb status code */ @@ -1777,8 +1789,8 @@ static int log_modify( * process a transaction start, as we don't currently log transaction starts * just generate the new transaction_id. * - * @param module the ldb_module - * @param req the ldb_request + * @param[in] module the ldb_module + * @param[in] req the ldb_request * * @return ldb status code */ @@ -1805,8 +1817,8 @@ static int log_start_transaction(struct ldb_module *module) * Log the details of a prepare commit, currently only details of * failures are logged. * - * @param module the ldb_module - * @param req the ldb_request + * @param[in] module the ldb_module + * @param[in] req the ldb_request * * @return ldb status code */ @@ -1829,8 +1841,8 @@ static int log_prepare_commit(struct ldb_module *module) * process a transaction end, as we don't currently log transaction ends * just clear transaction_id. * - * @param module the ldb_module - * @param req the ldb_request + * @param[in] module the ldb_module + * @param[in] req the ldb_request * * @return ldb status code */ @@ -1863,8 +1875,8 @@ static int log_end_transaction(struct ldb_module *module) * * Log details of a transaction roll back. * - * @param module the ldb_module - * @param req the ldb_request + * @param[in] module the ldb_module + * @param[in] req the ldb_request * * @return ldb status code */ @@ -1884,8 +1896,8 @@ static int log_del_transaction(struct ldb_module *module) * * Log the details of an extended operation. * - * @param module the ldb_module - * @param req the ldb_request + * @param[in] module the ldb_module + * @param[in] req the ldb_request * * @return ldb status code */