Commit a2974bda authored by David Zeuthen's avatar David Zeuthen
Browse files

document the API

Now I only need to implement it...
parent 96e73f52
......@@ -64,7 +64,15 @@
PolicyKit library.
</para>
</partintro>
<xi:include href="xml/libpolkit.xml"/>
<title>
<xi:include href="xml/libpolkit.xml"/>
</title>
<xi:include href="xml/libpolkit-context.xml"/>
<xi:include href="xml/libpolkit-privilege.xml"/>
<xi:include href="xml/libpolkit-resource.xml"/>
<xi:include href="xml/libpolkit-seat.xml"/>
<xi:include href="xml/libpolkit-session.xml"/>
<xi:include href="xml/libpolkit-caller.xml"/>
</reference>
<index>
......
......@@ -23,6 +23,13 @@
*
**************************************************************************/
/**
* SECTION:libpolkit-caller
* @short_description: Callers on the system message bus.
*
* This class is used to represent a caller in another process connected to the system message bus.
**/
#ifdef HAVE_CONFIG_H
# include <config.h>
#endif
......@@ -39,77 +46,188 @@
#include <glib.h>
#include "libpolkit-caller.h"
struct PolKitCaller_s
/**
* PolKitCaller:
*
* Objects of this class are used to record information about a caller
* on the system bus.
**/
struct PolKitCaller
{
};
/**
* libpolkit_caller_new:
*
* Creates a new #PolKitCaller object.
*
* Returns: the new object
**/
PolKitCaller *
libpolkit_caller_new (void)
{
return NULL;
}
/**
* libpolkit_caller_ref:
* @caller: The caller object
*
* Increase reference count.
*
* Returns: the object
**/
PolKitCaller *
libpolkit_caller_ref (PolKitCaller *caller)
{
return caller;
}
/**
* libpolkit_caller_set_dbus_name:
* @caller: The caller object
* @dbus_name: unique system bus connection name
*
* Set the callers unique system bus connection name.
**/
void
libpolkit_caller_set_dbus_name (PolKitCaller *caller, const char *dbus_name)
{
}
/**
* libpolkit_caller_set_uid:
* @caller: The caller object
* @uid: UNIX user id
*
* Set the callers UNIX user id.
**/
void
libpolkit_caller_set_uid (PolKitCaller *caller, uid_t uid)
{
}
/**
* libpolkit_caller_set_pid:
* @caller: The caller object
* @pid: UNIX process id
*
* Set the callers UNIX process id.
**/
void
libpolkit_caller_set_pid (PolKitCaller *caller, pid_t pid)
{
}
/**
* libpolkit_caller_set_selinux_context:
* @caller: The caller object
* @selinux_context: SELinux security context
*
* Set the callers SELinux security context.
**/
void
libpolkit_caller_set_selinux_context (PolKitCaller *caller, const char *selinux_context)
{
}
/**
* libpolkit_caller_set_ck_session:
* @caller: The caller object
* @session: a session object
*
* Set the callers session. The reference count on the given object
* will be increased by one. If an existing session object was set
* already, the reference count on that one will be decreased by one.
**/
void
libpolkit_caller_set_ck_session (PolKitCaller *caller, PolKitSession *session)
{
}
/**
* libpolkit_caller_get_dbus_name:
* @caller: The caller object
* @out_dbus_name: Returns the unique system bus connection name. The caller shall not free this string.
*
* Get the callers unique system bus connection name.
*
* Returns: TRUE iff the value is returned
**/
gboolean
libpolkit_caller_get_dbus_name (PolKitCaller *caller, char **out_dbus_name)
{
return FALSE;
}
/**
* libpolkit_caller_get_uid:
* @caller: The caller object
* @out_uid: Returns the UNIX user id
*
* Get the callers UNIX user id.
*
* Returns: TRUE iff the value is returned
**/
gboolean
libpolkit_caller_get_uid (PolKitCaller *caller, uid_t *out_uid)
{
return FALSE;
}
/**
* libpolkit_caller_get_pid:
* @caller: The caller object
* @out_pid: Returns the UNIX process id
*
* Get the callers UNIX process id.
*
* Returns: TRUE iff the value is returned
**/
gboolean
libpolkit_caller_get_pid (PolKitCaller *caller, uid_t *out_pid)
{
return FALSE;
}
/**
* libpolkit_caller_get_selinux_context:
* @caller: The caller object
* @out_selinux_context: Returns the SELinux security context. The caller shall not free this string.
*
* Get the callers SELinux security context.
*
* Returns: TRUE iff the value is returned
**/
gboolean
libpolkit_caller_get_selinux_context (PolKitCaller *caller, char *out_selinux_context)
{
return FALSE;
}
/**
* libpolkit_caller_get_ck_session:
* @caller: The caller object
* @out_session: Returns the session object. Caller shall not unref it.
*
* Get the callers session.
*
* Returns: TRUE iff the value is returned
**/
gboolean
libpolkit_caller_get_ck_session (PolKitCaller *caller, PolKitSession **out_session)
{
return FALSE;
}
/**
* libpolkit_caller_unref:
* @caller: The caller object
*
* 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.
**/
void
libpolkit_caller_unref (PolKitCaller *caller)
{
......
......@@ -33,22 +33,22 @@
#include <libpolkit/libpolkit-session.h>
struct PolKitCaller_s;
typedef struct PolKitCaller_s PolKitCaller;
struct PolKitCaller;
typedef struct PolKitCaller PolKitCaller;
PolKitCaller *libpolkit_caller_new (void);
PolKitCaller *libpolkit_caller_ref (PolKitCaller *caller);
void libpolkit_caller_set_dbus_name (PolKitCaller *caller, const char *dbus_name);
void libpolkit_caller_set_uid (PolKitCaller *caller, uid_t uid);
void libpolkit_caller_set_pid (PolKitCaller *caller, pid_t pid);
void libpolkit_caller_set_selinux_context (PolKitCaller *caller, const char *selinux_context);
void libpolkit_caller_unref (PolKitCaller *caller);
void libpolkit_caller_set_dbus_name (PolKitCaller *caller, const char *dbus_name);
void libpolkit_caller_set_uid (PolKitCaller *caller, uid_t uid);
void libpolkit_caller_set_pid (PolKitCaller *caller, pid_t pid);
void libpolkit_caller_set_selinux_context (PolKitCaller *caller, const char *selinux_context);
void libpolkit_caller_set_ck_session (PolKitCaller *caller, PolKitSession *session);
gboolean libpolkit_caller_get_dbus_name (PolKitCaller *caller, char **out_dbus_name);
gboolean libpolkit_caller_get_uid (PolKitCaller *caller, uid_t *out_uid);
gboolean libpolkit_caller_get_pid (PolKitCaller *caller, uid_t *out_pid);
gboolean libpolkit_caller_get_selinux_context (PolKitCaller *caller, char *out_selinux_context);
gboolean libpolkit_caller_get_dbus_name (PolKitCaller *caller, char **out_dbus_name);
gboolean libpolkit_caller_get_uid (PolKitCaller *caller, uid_t *out_uid);
gboolean libpolkit_caller_get_pid (PolKitCaller *caller, uid_t *out_pid);
gboolean libpolkit_caller_get_selinux_context (PolKitCaller *caller, char *out_selinux_context);
gboolean libpolkit_caller_get_ck_session (PolKitCaller *caller, PolKitSession **out_session);
void libpolkit_caller_unref (PolKitCaller *caller);
#endif /* LIBPOLKIT_H */
......
......@@ -39,22 +39,60 @@
#include <glib.h>
#include "libpolkit-context.h"
struct PolKitContext_s
/**
* SECTION:libpolkit-context
* @short_description: Context.
*
* This class is used to represent the interface to PolicyKit.
**/
/**
* PolKitContext:
*
* Context object for users of PolicyKit.
**/
struct PolKitContext
{
};
/**
* libpolkit_context_new:
*
* Create a new context.
*
* Returns: the new context object
**/
PolKitContext *
libpolkit_context_new (void)
{
return FALSE;
}
/**
* libpolkit_context_ref:
* @pk_context: the context object
*
* Increase reference count.
*
* Returns: the object
**/
PolKitContext *
libpolkit_context_ref (PolKitContext *pk_context)
{
return pk_context;
}
/**
* libpolkit_context_set_config_changed:
* @pk_context: the context object
* @cb: the callback to invoke
* @user_data: user data to pass to the callback
*
* Register the callback function for when configuration changes.
* Mechanisms should use this callback to e.g. reconfigure all
* permissions / acl's they have set in response to policy decisions
* made from information provided by PolicyKit.
**/
void
libpolkit_context_set_config_changed (PolKitContext *pk_context,
PolKitContextConfigChangedCB cb,
......@@ -62,6 +100,14 @@ libpolkit_context_set_config_changed (PolKitContext *pk_context,
{
}
/**
* libpolkit_context_unref:
* @pk_context: the context object
*
* 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.
**/
void
libpolkit_context_unref (PolKitContext *pk_context)
{
......
......@@ -31,19 +31,15 @@
#include <sys/types.h>
#include <glib.h>
struct PolKitContext_s;
typedef struct PolKitContext_s PolKitContext;
struct PolKitContext;
typedef struct PolKitContext PolKitContext;
/**
* PolKitContextConfigChangedCB:
* @pk_context: PolicyKit context
* @user_data: user data
*
* Called when configuration changes. Mechanisms should listen on this
* signal and e.g. reconfigure all permissions / acl's they have set
* in response to policy decisions made from information provided by
* PolicyKit.
* See libpolkit_context_set_config_changed() for details.
*/
typedef void (*PolKitContextConfigChangedCB) (PolKitContext *pk_context,
gpointer user_data);
......
......@@ -39,33 +39,85 @@
#include <glib.h>
#include "libpolkit-privilege.h"
struct PolKitPrivilege_s
/**
* SECTION:libpolkit-privilege
* @short_description: Privileges.
*
* This class is used to represent a privilege. TODO: describe what a privilege really is.
**/
/**
* PolKitPrivilege:
*
* Objects of this class are used to record information about a
* privilege.
**/
struct PolKitPrivilege
{
};
/**
* libpolkit_privilege_new:
*
* Create a new #PolKitPrivilege object.
*
* Returns: the new object
**/
PolKitPrivilege *
libpolkit_privilege_new (void)
{
return NULL;
}
/**
* libpolkit_privilege_ref:
* @privilege: the privilege object
*
* Increase reference count.
*
* Returns: the object
**/
PolKitPrivilege *
libpolkit_privilege_ref (PolKitPrivilege *privilege)
{
return privilege;
}
/**
* libpolkit_privilege_set_privilege_id:
* @privilege: the privilege object
* @privilege_id: privilege identifier
*
* Set the privilege identifier
**/
void
libpolkit_privilege_set_privilege_id (PolKitPrivilege *privilege, const char *privilege_id)
{
}
/**
* libpolkit_privilege_get_privilege_id:
* @privilege: the privilege object
* @out_privilege_id: Returns the privilege identifier. The caller shall not free this string.
*
* Get the privilege identifier.
*
* Returns: TRUE iff the value was returned.
**/
gboolean
libpolkit_privilege_get_privilege_id (PolKitPrivilege *privilege, char **out_privilege_id)
{
return FALSE;
}
/**
* libpolkit_privilege_unref:
* @privilege: the privilege object
*
* 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.
**/
void
libpolkit_privilege_unref (PolKitPrivilege *privilege)
{
......
......@@ -31,14 +31,14 @@
#include <sys/types.h>
#include <glib.h>
struct PolKitPrivilege_s;
typedef struct PolKitPrivilege_s PolKitPrivilege;
struct PolKitPrivilege;
typedef struct PolKitPrivilege PolKitPrivilege;
PolKitPrivilege *libpolkit_privilege_new (void);
PolKitPrivilege *libpolkit_privilege_ref (PolKitPrivilege *privilege);
void libpolkit_privilege_unref (PolKitPrivilege *privilege);
void libpolkit_privilege_set_privilege_id (PolKitPrivilege *privilege, const char *privilege_id);
gboolean libpolkit_privilege_get_privilege_id (PolKitPrivilege *privilege, char **out_privilege_id);
void libpolkit_privilege_unref (PolKitPrivilege *privilege);
#endif /* LIBPOLKIT_PRIVILEGE_H */
......
......@@ -39,44 +39,112 @@
#include <glib.h>
#include "libpolkit-resource.h"
struct PolKitResource_s
/**
* SECTION:libpolkit-resource
* @short_description: Resources.
*
* This class is used to represent a resource. TODO: describe what a resource really is.
**/
/**
* PolKitResource:
*
* Objects of this class are used to record information about a
* resource. TODO: describe what a resource really is.
**/
struct PolKitResource
{
};
/**
* libpolkit_resource_new:
*
* Create a new #PolKitResource object.
*
* Returns: the new object
**/
PolKitResource *
libpolkit_resource_new (void)
{
return NULL;
}
/**
* libpolkit_resource_ref:
* @resource: the resource object
*
* Increase reference count
*
* Returns: the object
**/
PolKitResource *
libpolkit_resource_ref (PolKitResource *resource)
{
return resource;
}
/**
* libpolkit_resource_set_resource_type:
* @resource: the resource object
* @resource_type: type of resource
*
* Set the type of the resource. TODO: link to wtf this is.
**/
void
libpolkit_resource_set_resource_type (PolKitResource *resource, const char *resource_type)
{
}
/**
* libpolkit_resource_set_resource_id:
* @resource: the resource object
* @resource_id: identifier of resource
*
* set the identifier of the resource. TODO: link to wtf this is.
**/
void
libpolkit_resource_set_resource_id (PolKitResource *resource, const char *resource_id)
{
}
/**
* libpolkit_resource_get_resource_type:
* @resource: the resource object
* @out_resource_type: Returns the resource type. The caller shall not free this string.
*
* Get the type of the resource.
*
* Returns: TRUE iff the value was returned.
**/
gboolean
libpolkit_resource_get_resource_type (PolKitResource *resource, char **out_resource_type)
{
return FALSE;
}
/**
* libpolkit_resource_get_resource_id:
* @resource: the resource object
* @out_resource_id: Returns the resource identifier. The caller shall not free this string.
*
* Get the identifier of the resource
*
* Returns: TRUE iff the value was returned.
**/
gboolean
libpolkit_resource_get_resource_id (PolKitResource *resource, char **out_resource_id)
{
return FALSE;
}
/**
* libpolkit_resource_unref:
* @resource: the resource object
*
* 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.
**/
void
libpolkit_resource_unref (PolKitResource *resource)
{
......
......@@ -31,16 +31,16 @@
#include <sys/types.h>
#include <glib.h>
struct PolKitResource_s;
typedef struct PolKitResource_s PolKitResource;
struct PolKitResource;
typedef struct PolKitResource PolKitResource;
PolKitResource *libpolkit_resource_new (void);
PolKitResource *libpolkit_resource_ref (PolKitResource *resource);
void libpolkit_resource_unref (PolKitResource *resource);
void libpolkit_resource_set_resource_type (PolKitResource *resource, const char *resource_type);
void libpolkit_resource_set_resource_id (PolKitResource *resource, const char *resource_id);
gboolean libpolkit_resource_get_resource_type (PolKitResource *resource, char **out_resource_type);
gboolean libpolkit_resource_get_resource_id (PolKitResource *resource, char **out_resource_id);
void libpolkit_resource_unref (PolKitResource *resource);
#endif /* LIBPOLKIT_RESOURCE_H */
......
......@@ -39,33 +39,85 @@
#include <glib.h>
#include "libpolkit-seat.h"
struct PolKitSeat_s
/**
* SECTION:libpolkit-seat
* @short_description: Seats.
*
* This class is used to represent a seat. TODO: describe seat.
**/
/**
* PolKitSeat:
*
* Objects of this class are used to record information about a
* seat.
**/
struct PolKitSeat
{
};
/**
* libpolkit_seat_new:
*
* Creates a new #PolKitSeat object.
*
* Returns: the new object
**/
PolKitSeat *
libpolkit_seat_new (void)
{
return NULL;
}
/**
* libpolkit_seat_ref:
* @seat: the seat object
*
* Increase reference count.
*
* Returns: the object