## EUserPrompter EUserPrompter — Manages user prompts over DBus |

## Functions

EUserPrompter * | e_user_prompter_new ()
void | e_user_prompter_prompt ()
gint | e_user_prompter_prompt_finish ()
gint | e_user_prompter_prompt_sync ()
void | e_user_prompter_extension_prompt ()
gint | e_user_prompter_extension_prompt_finish ()
gint | e_user_prompter_extension_prompt_sync ()

## Types and Values

struct | EUserPrompter

## Object Hierarchy

        GObject
        ╰── EUserPrompter

## Includes

    #include <libebackend/libebackend.h>

## Description

Use this to initiate a user prompt from an EBackend descendant.

## Functions

### e_user_prompter_new ()

    EUserPrompter *
    e_user_prompter_new (void);

Creates a new instance of EUserPrompter.

#### Returns

a new instance of EUserPrompter

Since: 3.8

### e_user_prompter_prompt ()

    void
    e_user_prompter_prompt (EUserPrompter *prompter,
                            const gchar *type,
                            const gchar *title,
                            const gchar *primary_text,
                            const gchar *secondary_text,
                            gboolean use_markup,
                            GList *button_captions,
                            GCancellable *cancellable,
                            GAsyncReadyCallback callback,
                            gpointer user_data);

Asynchronously prompt a user for a decision.

The `type` can be one of "info", "warning", "question" or "error", to include an icon in the message prompt; anything else results in no icon in the message.

If `button_captions` is `NULL` or empty list, then only one button is shown in the prompt, a "Dismiss" button.

When the operation is finished, `callback` will be called. You can then call `e_user_prompter_prompt_finish()` to get the result of the operation.

#### Parameters

prompter | an EUserPrompter |
type | type of the prompt; can be `NULL`. | [nullable]
title | window title of the prompt; can be `NULL`. | [nullable]
primary_text | primary text of the prompt; can be `NULL`. | [nullable]
secondary_text | secondary text of the prompt; can be `NULL`. | [nullable]
use_markup | whether both texts are with markup |
button_captions | captions of buttons to use in the message; can be `NULL`. | [nullable][element-type utf8]
cancellable | optional GCancellable object, or `NULL` |
callback | a GAsyncReadyCallback to call when the request is satisfied |
user_data | data to pass to the callback function |

Since: 3.8

### e_user_prompter_prompt_finish ()

    gint
    e_user_prompter_prompt_finish (EUserPrompter *prompter,
                                   GAsyncResult *result,
                                   GError **error);

Finishes the operation started with `e_user_prompter_prompt()`.

If an error occurred, the function sets `error` and returns -1.

#### Parameters

prompter | an EUserPrompter |
result | a GAsyncResult |
error | return location for a GError, or `NULL` |

#### Returns

0-based index of a button being used by a user as a response, corresponding to 'button_captions' from `e_user_prompter_prompt()` call.

Since: 3.8

### e_user_prompter_prompt_sync ()

    gint
    e_user_prompter_prompt_sync (EUserPrompter *prompter,
                                 const gchar *type,
                                 const gchar *title,
                                 const gchar *primary_text,
                                 const gchar *secondary_text,
                                 gboolean use_markup,
                                 GList *button_captions,
                                 GCancellable *cancellable,
                                 GError **error);

Prompts a user for a decision.

The `type` can be one of "info", "warning", "question" or "error", to include an icon in the message prompt; anything else results in no icon in the message.

If `button_captions` is `NULL` or empty list, then only one button is shown in the prompt, a "Dismiss" button.

If an error occurred, the function sets `error` and returns -1.

#### Parameters

prompter | an EUserPrompter |
type | type of the prompt; can be `NULL`. | [nullable]
title | window title of the prompt; can be `NULL`. | [nullable]
primary_text | primary text of the prompt; can be `NULL`. | [nullable]
secondary_text | secondary text of the prompt; can be `NULL`. | [nullable]
use_markup | whether both texts are with markup |
button_captions | captions of buttons to use in the message; can be `NULL`. | [nullable][element-type utf8]
cancellable | optional GCancellable object, or `NULL` |
error | return location for a GError, or `NULL` |

#### Returns

0-based index of a button being used by a user as a response, corresponding to `button_captions` list.

Since: 3.8

### e_user_prompter_extension_prompt ()

    void
    e_user_prompter_extension_prompt (EUserPrompter *prompter,
                                      const gchar *dialog_name,
                                      const ENamedParameters *in_parameters,
                                      GCancellable *cancellable,
                                      GAsyncReadyCallback callback,
                                      gpointer user_data);

Asynchronously prompt a user for a decision on an extension-provided dialog. The caller usually provides an extension for EUserPrompterServer, a descendant of EUserPrompterServerExtension, which registers itself as a dialog provider. The extension defines `dialog_name` , same as meaning of `in_parameters` ; only the extension and the caller know about meaning of these.

When the operation is finished, `callback` will be called. You can then call `e_user_prompter_extension_prompt_finish()` to get the result of the operation. If there is no extension providing given dialog name, the operation finishes with a G_IO_ERROR, G_IO_ERROR_NOT_FOUND GError.

#### Parameters

prompter | an EUserPrompter |
dialog_name | name of a dialog to invoke |
in_parameters | optional parameters to pass to extension; can be `NULL`. | [nullable]
cancellable | optional GCancellable object, or `NULL` |
callback | a GAsyncReadyCallback to call when the request is satisfied |
user_data | data to pass to the callback function |

Since: 3.8

### e_user_prompter_extension_prompt_finish ()

    gint
    e_user_prompter_extension_prompt_finish
                                   (EUserPrompter *prompter,
                                    GAsyncResult *result,
                                    ENamedParameters *out_values,
                                    GError **error);

Finishes the operation started with `e_user_prompter_extension_prompt()`. Caller can provide `out_values` to get additional values provided by the extension. In case the caller is not interested in additional values, it can pass `NULL` `out_values` . The `out_values` will be cleared first, then any values will be added there. Only the caller and the extension know about meaning of the result code and additional values.

If an error occurred, the function sets `error` and returns -1. If there is no extension providing given dialog name, the operation finishes with a G_IO_ERROR, G_IO_ERROR_NOT_FOUND `error` .

#### Parameters

prompter | an EUserPrompter |
result | a GAsyncResult |
out_values | Where to store values from the extension, or `NULL`. | [nullable]
error | return location for a GError, or `NULL` |

#### Returns

Result code of the prompt, as defined by the extension, or -1 on error.

Since: 3.8

### e_user_prompter_extension_prompt_sync ()

    gint
    e_user_prompter_extension_prompt_sync (EUserPrompter *prompter,
                                           const gchar *dialog_name,
                                           const ENamedParameters *in_parameters,
                                           ENamedParameters *out_values,
                                           GCancellable *cancellable,
                                           GError **error);

Synchronously prompt a user for a decision on an extension-provided dialog. The caller usually provides an extension for EUserPrompterServer, a descendant of EUserPrompterServerExtension, which registers itself as a dialog provider. The extension defines `dialog_name` , same as meaning of `in_parameters` ; only the extension and the caller know about meaning of these.

Caller can provide `out_values` to get additional values provided by the extension. In case the caller is not interested in additional values, it can pass `NULL` `out_values` . The `out_values` will be cleared first, then any values will be added there. Only the caller and the extension know about meaning of the result code and additional values.

If an error occurred, the function sets `error` and returns -1. If there is no extension providing given dialog name, the operation finishes with a G_IO_ERROR, G_IO_ERROR_NOT_FOUND `error` .

#### Parameters

prompter | an EUserPrompter |
dialog_name | name of a dialog to invoke |
in_parameters | optional parameters to pass to extension; can be `NULL`. | [nullable]
out_values | Where to store values from the extension, or `NULL`. | [nullable]
cancellable | optional GCancellable object, or `NULL` |
error | return location for a GError, or `NULL` |

#### Returns

Result code of the prompt, as defined by the extension, or -1 on error.

Since: 3.8

## Types and Values

### struct EUserPrompter

    struct EUserPrompter;

Contains only private data that should be read and manipulated using the functions below.

Since: 3.8