PolkitAgentSession: polkit Reference Manual

## 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

char * | 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”                   char *

The cookie obtained from the PolicyKit daemon

Owner: PolkitAgentSession

Flags: Read / Write / Construct Only

Default value: NULL

### The `“identity”` property

      “identity”                 PolkitIdentity *

The identity to authenticate.

Owner: PolkitAgentSession

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,
                   char               *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,
                   char               *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,
                   char               *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