Introduce cynara_admin_list_policies() admin function

Introduce new administrative API function: cynara_admin_list_policies()
New function allows listing with filter policies from a single bucket.

New admin define CYNARA_ADMIN_ANY is also introduced. It is a wildcard
for policy listing and removal. It can be used as client, user or privilege
name and matches any policy (even CYNARA_ADMIN_WILDCARD).

Change-Id: I9d014ebc8018e3fa6ad897c4de768471e672ac40

diff --git a/src/include/cynara-admin-types.h b/src/include/cynara-admin-types.h
index 8dd3c66..5978c80 100644 (file)
--- a/src/include/cynara-admin-types.h
+++ b/src/include/cynara-admin-types.h
@@ -63,6 +63,17 @@ struct cynara_admin_policy {
  */
 #define CYNARA_ADMIN_DEFAULT_BUCKET ""
 
+/**
+ * \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)
+ * * 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.
+ */
+#define CYNARA_ADMIN_ANY "#"
+
 #ifdef __cplusplus
 }
 #endif

diff --git a/src/include/cynara-admin.h b/src/include/cynara-admin.h
index 3b737d8..595ad6a 100644 (file)
--- a/src/include/cynara-admin.h
+++ b/src/include/cynara-admin.h
@@ -85,7 +85,7 @@ int cynara_admin_initialize(struct cynara_admin **pp_cynara_admin);
  * This API releases inner library structures and destroys cynara_admin structure.
  *
  * \par Sync (or) Async:
- * This is a Synchronous API.
+ * This is a synchronous API.
  *
  * \par Important notes:
  * No invocations of cynara-admin library API functions are allowed after call to
@@ -132,7 +132,7 @@ int cynara_admin_finish(struct cynara_admin *p_cynara_admin);
  * However, considered buckets must exist before referring to them in policies.
  *
  * \par Sync (or) Async:
- * This is a Synchronous API.
+ * This is a synchronous API.
  *
  * \par Important notes:
  * When plugin API will be specified, there will be more valid types to pass as result.
@@ -171,7 +171,7 @@ int cynara_admin_set_policies(struct cynara_admin *p_cynara_admin,
  * CYNARA_ADMIN_DELETE, a bucket is removed with all policies that were kept in it.
  *
  * \par Sync (or) Async:
- * This is a Synchronous API.
+ * This is a synchronous API.
  *
  * \par Important notes:
  * When plugin API will be specified, there will be more valid types to pass as operation / default
@@ -245,6 +245,63 @@ int cynara_admin_check(struct cynara_admin *p_cynara_admin,
                        const char *client, const char *user, const char *privilege,
                        int *result, char **result_extra);
 
+/**
+ * \par Description:
+ * Lists filtered cynara policies from single bucket.
+ *
+ * \par Purpose:
+ * This API should be used to list policies from single bucket.
+ *
+ * \par Typical use case:
+ * List 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 tripple {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}
+ * 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,
+ * 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"}
+ *
+ * Matching policies are returned as NULL terminated array of pointers to cynara_admin_policy
+ * structures.
+ *
+ * If any of: 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 and *policies points to newly created
+ * array of pointers to struct cynara_admin_policy. It is responsibility of caller to release:
+ * * all non-NULL const char* pointers in all cynara_admin_policy structures;
+ * * all pointers to cynara_admin_policy structures kept in *policies array;
+ * * *policies array itself.
+ * All allocation made by cynara admin library are done with malloc(3) function and must be released
+ * with free(3) function.
+ *
+ * \par Sync (or) Async:
+ * This is a synchronous API.
+ *
+ * \param[in] p_cynara_admin cynara admin structure.
+ * \param[in] bucket name.
+ * \param[in] client filter for client name.
+ * \param[in] user filter for user name.
+ * \param[in] privilege filter for privilege.
+ * \param[out] policies placeholder for NULL terminated array of pointers to policy structures.
+ *
+ * \return CYNARA_API_SUCCESS on success, or error code otherwise.
+ *
+ * \brief Lists policies from single bucket in cynara database.
+ */
+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);
 #ifdef __cplusplus
 }
 #endif