Commit d2a37b57 authored by David Zeuthen's avatar David Zeuthen

rearrange the docs so all API is in one section

Also specificy, per function and class, if it's not in libpolkit.
parent 4a157d2c
......@@ -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>
......
......@@ -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
......
......@@ -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
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment