PolicyKit: Branch 'master'
David Zeuthen
david at kemper.freedesktop.org
Tue Oct 30 14:48:38 PDT 2007
doc/polkit-docs.xml | 33 ++++++++-------------------------
polkit-dbus/polkit-dbus.c | 32 ++++++++++++++++++++++++++++++++
polkit-grant/polkit-grant.c | 36 +++++++++++++++++++++++++++++-------
3 files changed, 69 insertions(+), 32 deletions(-)
New commits:
commit d2a37b5730eef2ffc5108f65c409991da7a8fa01
Author: David Zeuthen <davidz at redhat.com>
Date: Tue Oct 30 17:46:41 2007 -0400
rearrange the docs so all API is in one section
Also specificy, per function and class, if it's not in libpolkit.
diff --git a/doc/polkit-docs.xml b/doc/polkit-docs.xml
index 2564aee..98a92d3 100644
--- a/doc/polkit-docs.xml
+++ b/doc/polkit-docs.xml
@@ -73,7 +73,13 @@
<partintro>
<para>
This part presents the class and function reference for the
- core PolicyKit library, <literal>libpolkit</literal>.
+ core PolicyKit
+ libraries, <literal>libpolkit</literal>, <literal>libpolkit-grant</literal>
+ and <literal>libpolkit-dbus</literal>. Note that unless
+ explictly stated, a function belongs
+ to <literal>libpolkit</literal>. The split is arranged such
+ that mechanisms checking for authorizations only need to link
+ with <literal>libpolkit</literal>.
</para>
</partintro>
<xi:include href="xml/polkit-types.xml"/>
@@ -84,6 +90,7 @@
<xi:include href="xml/polkit-seat.xml"/>
<xi:include href="xml/polkit-session.xml"/>
<xi:include href="xml/polkit-caller.xml"/>
+ <xi:include href="xml/polkit-dbus.xml"/>
<xi:include href="xml/polkit-context.xml"/>
<xi:include href="xml/polkit-config.xml"/>
<xi:include href="xml/polkit-policy-file.xml"/>
@@ -93,30 +100,6 @@
<xi:include href="xml/polkit-authorization.xml"/>
<xi:include href="xml/polkit-authorization-constraint.xml"/>
<xi:include href="xml/polkit-authorization-db.xml"/>
- </reference>
-
- <reference id="ref-convenience">
- <title>Convenience API Reference</title>
- <partintro>
- <para>
- This part presents the class and function reference for the
- convenience library <literal>libpolkit-dbus</literal>.
- </para>
- </partintro>
- <xi:include href="xml/polkit-dbus.xml"/>
- </reference>
-
- <reference id="ref-granting">
- <title>Authorization and privilege granting API Reference</title>
- <partintro>
- <para>
- This part presents the class and function reference for the
- PolicyKit granting library, libpolkit-grant. This library is
- targetted at desktop developers writing authentication dialogs
- that users can use to obtain privileges to do specific
- actions.
- </para>
- </partintro>
<xi:include href="xml/polkit-grant.xml"/>
</reference>
diff --git a/polkit-dbus/polkit-dbus.c b/polkit-dbus/polkit-dbus.c
index 087ea1f..76ae4e6 100644
--- a/polkit-dbus/polkit-dbus.c
+++ b/polkit-dbus/polkit-dbus.c
@@ -39,6 +39,8 @@
* roundtrips, to use the high-level #PolKitTracker class rather than
* the low-level functions polkit_caller_new_from_dbus_name() and
* polkit_caller_new_from_pid().
+ *
+ * These functions are in <literal>libpolkit-dbus</literal>.
**/
#ifdef HAVE_CONFIG_H
@@ -76,6 +78,8 @@
* of blocking IO so it is best avoided if your process already
* tracks/caches all the information. If you pass in @uid as a
* non-negative number, a round trip can be saved.
+ *
+ * This function is in <literal>libpolkit-dbus</literal>.
*
* Returns: the new object or #NULL if an error occured (in which case
* @error will be set)
@@ -301,6 +305,8 @@ out:
* the ConsoleKit daemon for information. Note that this will do a lot
* of blocking IO so it is best avoided if your process already
* tracks/caches all the information.
+ *
+ * This function is in <literal>libpolkit-dbus</literal>.
*
* Returns: the new object or #NULL if an error occured (in which case
* @error will be set)
@@ -364,6 +370,8 @@ out:
* information. Note that this will do a lot of blocking IO so it is
* best avoided if your process already tracks/caches all the
* information. You can use the #PolKitTracker class for this.
+ *
+ * This function is in <literal>libpolkit-dbus</literal>.
*
* Returns: the new object or #NULL if an error occured (in which case
* @error will be set)
@@ -572,6 +580,8 @@ out:
* blocking IO so it is best avoided if your process already
* tracks/caches all the information. You can use the #PolKitTracker
* class for this.
+ *
+ * This function is in <literal>libpolkit-dbus</literal>.
*
* Returns: the new object or #NULL if an error occured (in which case
* @error will be set)
@@ -868,6 +878,8 @@ out:
* error occurred (then error will be set) or if the entity the
* authorization refers to has gone out of scope.
*
+ * This function is in <literal>libpolkit-dbus</literal>.
+ *
* Since: 0.7
*/
polkit_bool_t
@@ -939,6 +951,8 @@ polkit_is_authorization_relevant (DBusConnection *con, PolKitAuthorization *auth
* The careful reader will notice that, during the testing session, we
* did a quick VT switch away from the session (and back) which is
* reflected in the output.
+ *
+ * These functions are in <literal>libpolkit-dbus</literal>.
**/
struct _PolKitTracker {
int refcount;
@@ -988,6 +1002,8 @@ _pid_start_time_equal (gconstpointer a, gconstpointer b)
* polkit_tracker_new:
*
* Creates a new #PolKitTracker object.
+ *
+ * This function is in <literal>libpolkit-dbus</literal>.
*
* Returns: the new object
*
@@ -1015,6 +1031,8 @@ polkit_tracker_new (void)
* @pk_tracker: the tracker object
*
* Increase reference count.
+ *
+ * This function is in <literal>libpolkit-dbus</literal>.
*
* Returns: the object
*
@@ -1036,6 +1054,8 @@ polkit_tracker_ref (PolKitTracker *pk_tracker)
* the object is freed. Before freeing, reference counts on embedded
* objects are decresed by one.
*
+ * This function is in <literal>libpolkit-dbus</literal>.
+ *
* Since: 0.7
**/
void
@@ -1060,6 +1080,8 @@ polkit_tracker_unref (PolKitTracker *pk_tracker)
* when it needs to fetch information from the system message bus and
* ConsoleKit services. This is used for priming the cache.
*
+ * This function is in <literal>libpolkit-dbus</literal>.
+ *
* Since: 0.7
*/
void
@@ -1075,6 +1097,8 @@ polkit_tracker_set_system_bus_connection (PolKitTracker *pk_tracker, DBusConnect
*
* Initialize the tracker.
*
+ * This function is in <literal>libpolkit-dbus</literal>.
+ *
* Since: 0.7
*/
void
@@ -1178,6 +1202,8 @@ _remove_caller_by_dbus_name (PolKitTracker *pk_tracker, const char *dbus_name)
* system message bus (just NameOwnerChanged will do) and all signals
* from the ConsoleKit service into this function.
*
+ * This function is in <literal>libpolkit-dbus</literal>.
+ *
* Returns: #TRUE only if there was a change in the ConsoleKit database.
*
* Since: 0.7
@@ -1317,6 +1343,8 @@ out:
* polkit_caller_unref() on the object when done with it. Returns
* #NULL if an error occured (in which case error will be set).
*
+ * This function is in <literal>libpolkit-dbus</literal>.
+ *
* Since: 0.7
*/
PolKitCaller *
@@ -1365,6 +1393,8 @@ polkit_tracker_get_caller_from_dbus_name (PolKitTracker *pk_tracker, const char
* polkit_caller_unref() on the object when done with it. Returns
* #NULL if an error occured (in which case error will be set).
*
+ * This function is in <literal>libpolkit-dbus</literal>.
+ *
* Since: 0.7
*/
PolKitCaller *
@@ -1439,6 +1469,8 @@ polkit_tracker_get_caller_from_pid (PolKitTracker *pk_tracker, pid_t pid, DBusEr
* error occurred (then error will be set) or if the entity the
* authorization refers to has gone out of scope.
*
+ * This function is in <literal>libpolkit-dbus</literal>.
+ *
* Since: 0.7
*/
polkit_bool_t
diff --git a/polkit-grant/polkit-grant.c b/polkit-grant/polkit-grant.c
index f28052c..0e7a43d 100644
--- a/polkit-grant/polkit-grant.c
+++ b/polkit-grant/polkit-grant.c
@@ -40,21 +40,27 @@
/**
* SECTION:polkit-grant
- * @title: PolKitGrant
- * @short_description: A class used for obtain privileges through
+ * @title: Authorizations and Authentication
+ * @short_description: Obtain authorizations through
* authentication.
*
- * These functions are used to obtain privileges for a user that is
- * able to successfully authenticate. It is only useful for people
+ * These functions are used to obtain authorizations for a user that
+ * is able to successfully authenticate. It is only useful for people
* writing user interfaces that interfaces with the end user.
+ *
+ * All of these functions are in the
+ * <literal>libpolkit-grant</literal> library.
**/
/**
* PolKitGrant:
*
- * Objects of this class are used to obtain privileges for a user that
- * is able to successfully authenticate. It is only useful for people
- * writing user interfaces that interfaces with the end user.
+ * Objects of this class are used to obtain authorizations for a user
+ * that is able to successfully authenticate. It is only useful for
+ * people writing user interfaces that interfaces with the end user.
+ *
+ * All of these functions are in the
+ * <literal>libpolkit-grant</literal> library.
**/
struct _PolKitGrant
{
@@ -90,6 +96,8 @@ struct _PolKitGrant
*
* Creates a #PolKitGrant object.
*
+ * This function is in <literal>libpolkit-grant</literal>.
+ *
* Returns: the new object or #NULL if the authorization backend
* doesn't support obtaining authorizations through authentication.
**/
@@ -112,6 +120,8 @@ polkit_grant_new (void)
*
* Increase reference count.
*
+ * This function is in <literal>libpolkit-grant</literal>.
+ *
* Returns: the object.
**/
PolKitGrant *
@@ -130,6 +140,8 @@ polkit_grant_ref (PolKitGrant *polkit_grant)
* Decreases the reference count of the object. If it becomes zero,
* the object is freed. Before freeing, reference counts on embedded
* objects are decresed by one.
+ *
+ * This function is in <literal>libpolkit-grant</literal>.
**/
void
polkit_grant_unref (PolKitGrant *polkit_grant)
@@ -181,6 +193,8 @@ polkit_grant_unref (PolKitGrant *polkit_grant)
* @user_data: User data that will be passed to the callback functions.
*
* Set callback functions used for authentication.
+ *
+ * This function is in <literal>libpolkit-grant</literal>.
**/
void
polkit_grant_set_functions (PolKitGrant *polkit_grant,
@@ -232,6 +246,8 @@ polkit_grant_set_functions (PolKitGrant *polkit_grant,
* Method that the application must call when a child process
* registered with the supplied function of type
* #PolKitGrantAddChildWatch terminates.
+ *
+ * This function is in <literal>libpolkit-grant</literal>.
**/
void
polkit_grant_child_func (PolKitGrant *polkit_grant, pid_t pid, int exit_code)
@@ -264,6 +280,8 @@ polkit_grant_child_func (PolKitGrant *polkit_grant, pid_t pid, int exit_code)
* Method that the application must call when there is data to read
* from a file descriptor registered with the supplied function of
* type #PolKitGrantAddIOWatch.
+ *
+ * This function is in <literal>libpolkit-grant</literal>.
**/
void
polkit_grant_io_func (PolKitGrant *polkit_grant, int fd)
@@ -402,6 +420,8 @@ polkit_grant_io_func (PolKitGrant *polkit_grant, int fd)
* @polkit_grant: the object
*
* Cancel an authentication in progress
+ *
+ * This function is in <literal>libpolkit-grant</literal>.
**/
void
polkit_grant_cancel_auth (PolKitGrant *polkit_grant)
@@ -440,6 +460,8 @@ polkit_grant_cancel_auth (PolKitGrant *polkit_grant)
* The caller of this method must iterate the mainloop context in
* order for authentication to make progress.
*
+ * This function is in <literal>libpolkit-grant</literal>.
+ *
* Returns: #TRUE only if authentication have been initiated.
**/
polkit_bool_t
More information about the hal-commit
mailing list