PolkitAgentSession

PolkitAgentSession — Authentication Session

Stability Level

Unstable, unless otherwise indicated

Functions

PolkitAgentSession * polkit_agent_session_new ()
void polkit_agent_session_initiate ()
void polkit_agent_session_response ()
void polkit_agent_session_cancel ()

Properties

gchar * cookie Read / Write / Construct Only
PolkitIdentity * identity Read / Write / Construct Only

Signals

void completed Run Last
void request Run Last
void show-error Run Last
void show-info Run Last

Types and Values

  PolkitAgentSession

Object Hierarchy

    GObject
    ╰── PolkitAgentSession

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.

Functions

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.

Parameters

identity

The identity to authenticate.

  

cookie

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. Before calling this method, make sure to connect to the various signals. The signals will be emitted in the thread-default main loop that this method is invoked from.

Use polkit_agent_session_cancel() to cancel the session.

Parameters

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.

Parameters

session

A PolkitAgentSession.

  

response

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.

Parameters

session

A PolkitAgentSession.

  

Types and Values

PolkitAgentSession

typedef struct _PolkitAgentSession PolkitAgentSession;

The PolkitAgentSession struct should not be accessed directly.

Property Details

The “cookie” property

  “cookie”                   gchar *

The cookie obtained from the PolicyKit daemon

Flags: Read / Write / Construct Only

Default value: NULL

The “identity” property

  “identity”                 PolkitIdentity *

The identity to authenticate.

Flags: Read / Write / Construct Only

Signal Details

The “completed” signal

void
user_function (PolkitAgentSession *session,
               gboolean            gained_authorization,
               gpointer            user_data)

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().

Parameters

session

A PolkitAgentSession.

  

gained_authorization

TRUE only if the authorization was successfully obtained.

  

user_data

user data set when the signal handler was connected.

  

Flags: Run Last

The “request” signal

void
user_function (PolkitAgentSession *session,
               gchar              *request,
               gboolean            echo_on,
               gpointer            user_data)

Emitted when the user is requested to answer a question.

When the response has been collected from the user, call polkit_agent_session_response().

Parameters

session

A PolkitAgentSession.

  

request

The request to show the user, e.g. "name: " or "password: ".

  

echo_on

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

user data set when the signal handler was connected.

  

Flags: Run Last

The “show-error” signal

void
user_function (PolkitAgentSession *session,
               gchar              *text,
               gpointer            user_data)

Emitted when there is information related to an error condition to be displayed to the user.

Parameters

session

A PolkitAgentSession.

  

text

An error string to display to the user.

  

user_data

user data set when the signal handler was connected.

  

Flags: Run Last

The “show-info” signal

void
user_function (PolkitAgentSession *session,
               gchar              *text,
               gpointer            user_data)

Emitted when there is information to be displayed to the user.

Parameters

session

A PolkitAgentSession.

  

text

A string to display to the user.

  

user_data

user data set when the signal handler was connected.

  

Flags: Run Last

Generated by GTK-Doc V1.28