 |
 |
 |
PolicyKit Reference Manual |  |
|---|---|---|---|---|
| Top | Description | Object Hierarchy | Signals | ||||
Synopsis
PolkitAgentSession; PolkitAgentSession * polkit_agent_session_new (PolkitIdentity *identity, const gchar *cookie); void polkit_agent_session_initiate (PolkitAgentSession *session); void polkit_agent_session_response (PolkitAgentSession *session, const gchar *response); void polkit_agent_session_cancel (PolkitAgentSession *session);
Description
The PolkitAgentSession class is an abstraction used for interacting with the native authentication system (for example PAM) for obtaining authorizations. This class is typically used together with instances that are derived from the PolkitAgentListener abstract base class.
To perform the actual authentication, PolkitAgentSession uses a trusted suid helper.
The authentication conversation is done through a pipe. This is transparent; the user
only need to handle the
"request",
"show-info",
"show-error" and
"completed"
signals and invoke polkit_agent_session_response() in response to requests.
If the user successfully authenticates, the authentication helper will invoke
a method on the PolicyKit daemon (see polkit_authority_authentication_agent_response_sync())
with the given cookie. Upon receiving a positive response from the PolicyKit daemon (via
the authentication helper), the "completed" signal will be emitted
with the gained_authorization paramter set to TRUE.
If the user is unable to authenticate, the "completed" signal will
be emitted with the gained_authorization paramter set to FALSE.
Details
PolkitAgentSession
typedef struct _PolkitAgentSession PolkitAgentSession;
The PolkitAgentSession struct should not be accessed directly.
polkit_agent_session_new ()
PolkitAgentSession * polkit_agent_session_new (PolkitIdentity *identity, const gchar *cookie);
Creates a new authentication session.
The caller should connect to the
"request",
"show-info",
"show-error" and
"completed"
signals and then call polkit_agent_session_initiate() to initiate the authentication session.
|
The identity to authenticate. |
|
The cookie obtained from the PolicyKit daemon |
Returns : |
A PolkitAgentSession. Free with g_object_unref().
|
polkit_agent_session_initiate ()
void polkit_agent_session_initiate (PolkitAgentSession *session);
Initiates the authentication session.
Use polkit_agent_session_cancel() to cancel the session.
|
A PolkitAgentSession. |
polkit_agent_session_response ()
void polkit_agent_session_response (PolkitAgentSession *session, const gchar *response);
Function for providing response to requests received via the "request" signal.
|
A PolkitAgentSession. |
|
Response from the user, typically a password. |
polkit_agent_session_cancel ()
void polkit_agent_session_cancel (PolkitAgentSession *session);
Cancels an authentication session. This will make session emit the "completed"
signal.
|
A PolkitAgentSession. |
Signal Details
The "completed" signal
void user_function (PolkitAgentSession *session, gboolean gained_authorization, gpointer user_data) : Run Last
Emitted when the authentication session has been completed or
cancelled. The gained_authorization parameter is TRUE only if
the user successfully authenticated.
Upon receiving this signal, the user should free session using g_object_unref().
|
A PolkitAgentSession. |
|
TRUE only if the authorization was successfully obtained.
|
|
user data set when the signal handler was connected. |
The "request" signal
void user_function (PolkitAgentSession *session, gchar *request, gboolean echo_on, gpointer user_data) : Run Last
Emitted when the user is requested to answer a question.
When the response has been collected from the user, call polkit_agent_session_response().
|
A PolkitAgentSession. |
|
The request to show the user, e.g. "name: " or "password: ". |
|
TRUE if the response to the request SHOULD be echoed on the
screen, FALSE if the response MUST NOT be echoed to the screen.
|
|
user data set when the signal handler was connected. |
The "show-error" signal
void user_function (PolkitAgentSession *session, gchar *text, gpointer user_data) : Run Last
Emitted when there is information related to an error condition to be displayed to the user.
|
A PolkitAgentSession. |
|
An error string to display to the user. |
|
user data set when the signal handler was connected. |
The "show-info" signal
void user_function (PolkitAgentSession *session, gchar *text, gpointer user_data) : Run Last
Emitted when there is information to be displayed to the user.
|
A PolkitAgentSession. |
|
A string to display to the user. |
|
user data set when the signal handler was connected. |