Introduce new admin API function cynara_admin_erase()

cynara_admin_erase() can be used to erase multiple policies matching
given filter key (client, user, privilege). Erasing starts in given
bucket and then can step into nested buckets if recursive flag is
enabled.
Filter key can use CYNARA_ADMIN_ANY to match any value of client,
user or privilege.

Change-Id: Ib2eb55e864828b4b073a177bc6fea468ec3911c8

diff --git a/src/include/cynara-admin-types.h b/src/include/cynara-admin-types.h
index 5978c80..b83c81d 100644 (file)
--- a/src/include/cynara-admin-types.h
+++ b/src/include/cynara-admin-types.h
@@ -67,7 +67,7 @@ struct cynara_admin_policy {
  * \name Any
  * definition of ANY, that can replace client, user or privilege name.
  * ANY matches any string (including WILDCARD) during:
- * * policy removal (setPolicies with CYNARA_ADMIN_DELETE)
+ * * policy removal with cynara_admin_erase() function
  * * listing policies from a single bucket.
  * Using ANY as default policy for bucket or as policy type of inserted policy record
  * is forbidden and will cause CYNARA_API_INVALID_PARAM error.

diff --git a/src/include/cynara-admin.h b/src/include/cynara-admin.h
index 595ad6a..bb1b8d1 100644 (file)
--- a/src/include/cynara-admin.h
+++ b/src/include/cynara-admin.h
@@ -257,16 +257,16 @@ int cynara_admin_check(struct cynara_admin *p_cynara_admin,
  *
  * \par Method of function operation:
  * Policies are arranged into buckets. Every bucket contains set of policies. Each of policies are
- * identified with tripple {client, user, privilege}. Function lists all policies from single bucket
+ * identified with triple {client, user, privilege}. Function lists all policies from single bucket
  * with matching client, user and privilege names.
  *
  * CYNARA_ADMIN_ANY can be used to match any client, user or privilege, e.g.
  *
- * List with paramaters: {client = CYNARA_ADMIN_ANY, user = "alice", privilege = CYNARA_ADMIN_ANY}
+ * List with parameters: {client = CYNARA_ADMIN_ANY, user = "alice", privilege = CYNARA_ADMIN_ANY}
  * will match all policies related to "alice", so will match {"app1", "alice", "gps"} and
  * {CYNARA_ADMIN_WILDCARD, "alice", "sms"}, but won't match {"app3", CYNARA_ADMIN_WILDCARD, "call"}.
  *
- * List with paramaters: {client = "calculator", user = CYNARA_ADMIN_WILDCARD,
+ * List with parameters: {client = "calculator", user = CYNARA_ADMIN_WILDCARD,
  * privilege = CYNARA_ADMIN_ANY} will match {"calculator", CYNARA_ADMIN_WILDCARD, "sms"} but won't
  * match {CYNARA_ADMIN_WILDCARD, CYNARA_ADMIN_WILDCARD, "sms"} nor {"calculator", "bob", "sms"}
  *
@@ -302,6 +302,62 @@ int cynara_admin_check(struct cynara_admin *p_cynara_admin,
 int cynara_admin_list_policies(struct cynara_admin *p_cynara_admin, const char *bucket,
                                const char *client, const char *user, const char *privilege,
                                struct cynara_admin_policy ***policies);
+
+/**
+ * \par Description:
+ * Erase policies matching filter from cynara database.
+ *
+ * \par Purpose:
+ * This API should be used to erase multiple policies with some common key part,
+ * e.g. all policies related to given user.
+ *
+ * \par Typical use case:
+ * Erase all policies matching defined filter.
+ *
+ * \par Method of function operation:
+ * Policies are arranged into buckets. Every bucket contains set of policies. Each of policies are
+ * identified with triple {client, user, privilege}. Function erases all policies with matching
+ * client, user and privilege names.
+ *
+ * There are two modes:
+ * * non-recursive (recursive parameter set to 0) - when policies are erased only from single bucket
+ * * recursive (recursive parameter set to 1) when policies are removed from given start_bucket and
+ * all nested buckets.
+ *
+ * CYNARA_ADMIN_ANY can be used to match any client, user or privilege, e.g.
+ *
+ * Erase with parameters: {client = CYNARA_ADMIN_ANY, user = "alice", privilege = CYNARA_ADMIN_ANY}
+ * will match all policies related to "alice", so will match {"app1", "alice", "gps"} and
+ * {CYNARA_ADMIN_WILDCARD, "alice", "sms"}, but won't match {"app3", CYNARA_ADMIN_WILDCARD, "call"}.
+ *
+ * Erase with parameters: {client = "calculator", user = CYNARA_ADMIN_WILDCARD,
+ * privilege = CYNARA_ADMIN_ANY} will match {"calculator", CYNARA_ADMIN_WILDCARD, "sms"} but won't
+ * match {CYNARA_ADMIN_WILDCARD, CYNARA_ADMIN_WILDCARD, "sms"} nor {"calculator", "bob", "sms"}
+ *
+ * If any of: start_bucket, client, user, privilege, policies is NULL then CYNARA_API_INVALID_PARAM
+ * is returned.
+ * If there is no bucket with given name CYNARA_API_BUCKET_NOT_FOUND is returned.
+ *
+ * In case of successful call CYNARA_API_SUCCESS is returned.
+ *
+ * \par Sync (or) Async:
+ * This is a synchronous API.
+ *
+ * \param[in] p_cynara_admin cynara admin structure.
+ * \param[in] start_bucket name of bucket where erase would start.
+ * \param[in] recursive FALSE (== 0) : erase is not recursive (single bucket erase);
+ *                      TRUE  (!= 0) : erase follows all policies leading to nested buckets
+ * \param[in] client filter for client name.
+ * \param[in] user filter for user name.
+ * \param[in] privilege filter for privilege.
+ *
+ * \return CYNARA_API_SUCCESS on success, or error code otherwise.
+ *
+ * \brief Erase policies matching filter from cynara database.
+ */
+int cynara_admin_erase(struct cynara_admin *p_cynara_admin,
+                       const char *start_bucket, int recursive,
+                       const char *client, const char *user, const char *privilege);
 #ifdef __cplusplus
 }
 #endif