GcrSystemPrompt

## GcrSystemPrompt GcrSystemPrompt — a system modal prompt |

## Synopsis

    struct              GcrSystemPrompt;
    struct              GcrSystemPromptClass;
    #define             GCR_SYSTEM_PROMPT_ERROR
    enum                GcrSystemPromptError;
    GcrPrompt *         gcr_system_prompt_open              (gint timeout_seconds,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                gcr_system_prompt_open_async        (gint timeout_seconds,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    GcrPrompt *         gcr_system_prompt_open_finish       (GAsyncResult *result,
                                                             GError **error);
    GcrPrompt *         gcr_system_prompt_open_for_prompter (const gchar *prompter_name,
                                                             gint timeout_seconds,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                gcr_system_prompt_open_for_prompter_async
                                                            (const gchar *prompter_name,
                                                             gint timeout_seconds,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    GcrSecretExchange * gcr_system_prompt_get_secret_exchange
                                                            (GcrSystemPrompt *self);
    gboolean            gcr_system_prompt_close             (GcrSystemPrompt *self,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                gcr_system_prompt_close_async       (GcrSystemPrompt *self,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            gcr_system_prompt_close_finish      (GcrSystemPrompt *self,
                                                             GAsyncResult *result,
                                                             GError **error);

## Object Hierarchy

      GObject
       +----GcrSystemPrompt

## Implemented Interfaces

GcrSystemPrompt implements GcrPrompt, GInitable and GAsyncInitable.

## Properties

      "bus-name"                 gchar*                : Read / Write / Construct Only
      "secret-exchange"          GcrSecretExchange*    : Read / Write
      "timeout-seconds"          gint                  : Write / Construct Only

## Description

A GcrPrompt implementation which calls to the system prompter to display prompts in a system modal fashion.

Since the system prompter usually only displays one prompt at a time, you may have to wait for the prompt to be displayed. Use `gcr_system_prompt_open()` or a related function to open a prompt. Since this can take a long time, you should always check that the prompt is still needed after it is opened. A previous prompt may have already provided the information needed and you may no longer need to prompt.

Use `gcr_system_prompt_close()` to close the prompt when you're done with it.

## Details

### struct GcrSystemPrompt

    struct GcrSystemPrompt;

A GcrPrompt which shows a system prompt. This is usually a system modal dialog.

### struct GcrSystemPromptClass

    struct GcrSystemPromptClass {
    	GObjectClass parent_class;
    };

The class for GcrSystemPrompt.

GObjectClass `parent_class`; | parent class

### GCR_SYSTEM_PROMPT_ERROR

    #define GCR_SYSTEM_PROMPT_ERROR              (gcr_system_prompt_error_get_domain ())

The domain for errors returned from GcrSystemPrompt methods.

### enum GcrSystemPromptError

    typedef enum {
    	GCR_SYSTEM_PROMPT_IN_PROGRESS = 1,
    } GcrSystemPromptError;

No error returned by the GcrSystemPrompt is suitable for display or to the user.

If the system prompter can only show one prompt at a time, and there is already a prompt being displayed, and the timeout waiting to open the prompt expires, then `GCR_SYSTEM_PROMPT_IN_PROGRESS` is returned.

`GCR_SYSTEM_PROMPT_IN_PROGRESS` | another prompt is already in progress

### gcr_system_prompt_open ()

    GcrPrompt *         gcr_system_prompt_open              (gint timeout_seconds,
                                                             GCancellable *cancellable,
                                                             GError **error);

Opens a system prompt with the default prompter.

Most system prompters only allow showing one prompt at a time, and if another prompt is shown then this method will block for up to `timeout_seconds` seconds. If `timeout_seconds` is equal to -1, then this will block indefinitely until the prompt can be opened. If `timeout_seconds` expires, then this function will fail with a `GCR_SYSTEM_PROMPT_IN_PROGRESS` error.

`timeout_seconds` : | the number of seconds to wait to access the prompt, or -1
`cancellable` : | optional cancellation object
`error` : | location to place error on failure
Returns : | the prompt, or `NULL` if prompt could not be opened. [transfer full][type Gcr.SystemPrompt]

### gcr_system_prompt_open_async ()

    void                gcr_system_prompt_open_async        (gint timeout_seconds,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Asynchronously open a system prompt with the default system prompter.

Most system prompters only allow showing one prompt at a time, and if another prompt is shown then this method will block for up to `timeout_seconds` seconds. If `timeout_seconds` is equal to -1, then this will block indefinitely until the prompt can be opened. If `timeout_seconds` expires, then this operation will fail with a `GCR_SYSTEM_PROMPT_IN_PROGRESS` error.

`timeout_seconds` : | the number of seconds to wait to access the prompt, or -1
`cancellable` : | optional cancellation object
`callback` : | called when the operation completes
`user_data` : | data to pass the callback

### gcr_system_prompt_open_finish ()

    GcrPrompt *         gcr_system_prompt_open_finish       (GAsyncResult *result,
                                                             GError **error);

Complete an operation to asynchronously open a system prompt.

`result` : | the asynchronous result
`error` : | location to place an error on failure
Returns : | the prompt, or `NULL` if prompt could not be opened. [transfer full][type Gcr.SystemPrompt]

### gcr_system_prompt_open_for_prompter ()

    GcrPrompt *         gcr_system_prompt_open_for_prompter (const gchar *prompter_name,
                                                             gint timeout_seconds,
                                                             GCancellable *cancellable,
                                                             GError **error);

Opens a system prompt. If prompter_name is `NULL`, then the default system prompter is used.

Most system prompters only allow showing one prompt at a time, and if another prompt is shown then this method will block for up to `timeout_seconds` seconds. If `timeout_seconds` is equal to -1, then this will block indefinitely until the prompt can be opened. If `timeout_seconds` expires, then this function will fail with a `GCR_SYSTEM_PROMPT_IN_PROGRESS` error.

`prompter_name` : | the prompter dbus name. [allow-none]
`timeout_seconds` : | the number of seconds to wait to access the prompt, or -1
`cancellable` : | optional cancellation object
`error` : | location to place error on failure
Returns : | the prompt, or `NULL` if prompt could not be opened. [transfer full][type Gcr.SystemPrompt]

### gcr_system_prompt_open_for_prompter_async ()

    void                gcr_system_prompt_open_for_prompter_async
                                                            (const gchar *prompter_name,
                                                             gint timeout_seconds,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Opens a system prompt asynchronously. If prompter_name is `NULL`, then the default system prompter is used.

Most system prompters only allow showing one prompt at a time, and if another prompt is shown then this method will block for up to `timeout_seconds` seconds. If `timeout_seconds` is equal to -1, then this will block indefinitely until the prompt can be opened. If `timeout_seconds` expires, then this operation will fail with a `GCR_SYSTEM_PROMPT_IN_PROGRESS` error.

`prompter_name` : | the prompter dbus name. [allow-none]
`timeout_seconds` : | the number of seconds to wait to access the prompt, or -1
`cancellable` : | optional cancellation object
`callback` : | called when the operation completes
`user_data` : | data to pass the callback

### gcr_system_prompt_get_secret_exchange ()

    GcrSecretExchange * gcr_system_prompt_get_secret_exchange
                                                            (GcrSystemPrompt *self);

Get the current GcrSecretExchange used to transfer secrets in this prompt.

`self` : | a prompter
Returns : | the secret exchange. [transfer none]

### gcr_system_prompt_close ()

    gboolean            gcr_system_prompt_close             (GcrSystemPrompt *self,
                                                             GCancellable *cancellable,
                                                             GError **error);

Close this prompt. After calling this function, no further prompts will succeed on this object. The prompt object is not unreferenced by this function, and you must unreference it once done.

This call may block, use the `gcr_system_prompt_close_async()` to perform this action indefinitely.

Whether or not this function returns `TRUE`, the system prompt object is still closed and may not be further used.

`self` : | the prompt
`cancellable` : | an optional cancellation object
`error` : | location to place an error on failure
Returns : | whether close was cleanly completed

### gcr_system_prompt_close_async ()

    void                gcr_system_prompt_close_async       (GcrSystemPrompt *self,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Close this prompt asynchronously. After calling this function, no further methods may be called on this object. The prompt object is not unreferenced by this function, and you must unreference it once done.

This call returns immediately and completes asynchronously.

`self` : | the prompt
`cancellable` : | an optional cancellation object
`callback` : | called when the operation completes
`user_data` : | data to pass to the callback

### gcr_system_prompt_close_finish ()

    gboolean            gcr_system_prompt_close_finish      (GcrSystemPrompt *self,
                                                             GAsyncResult *result,
                                                             GError **error);

Complete operation to close this prompt.

Whether or not this function returns `TRUE`, the system prompt object is still closed and may not be further used.

`self` : | the prompt
`result` : | asynchronous operation result
`error` : | location to place an error on failure
Returns : | whether close was cleanly completed

## Property Details

### The `"bus-name"` property

      "bus-name"                 gchar*                : Read / Write / Construct Only

The DBus bus name of the prompter to use for prompting, or `NULL` for the default prompter.

Default value: NULL

### The `"secret-exchange"` property

      "secret-exchange"          GcrSecretExchange*    : Read / Write

The GcrSecretExchange to use when transferring passwords. A default secret exchange will be used if this is not set.

### The `"timeout-seconds"` property

      "timeout-seconds"          gint                  : Write / Construct Only

The timeout in seconds to wait when opening the prompt.

Allowed values: >= -1

Default value: -1