prompt: libuser Reference Manual

prompt

prompt — Sample prompter functions for use with the libuser library.

Functions

gboolean	lu_prompt_console ()
gboolean	lu_prompt_console_quiet ()

Types and Values

struct

lu_prompt

Includes

#include <libuser/prompt.h>

Description

prompt.h declares two predefined prompter functions which applications can use instead of providing their own. These should suffice for most command-line applications. Authors of graphical applications are encouraged to supply graphical implementations.

Functions

lu_prompt_console ()

gboolean
lu_prompt_console (struct lu_prompt *prompts,
                   int count,
                   gpointer callback_data,
                   struct lu_error **error);

Prompts the user using a text console.

Parameters

prompts	An array of lu_prompt structures.
count	The number of elements in the `prompts` array.
callback_data	Ignored.
error	The location to store error information in the event of an error.

Returns

A gboolean indicating success or failure.

lu_prompt_console_quiet ()

gboolean
lu_prompt_console_quiet (struct lu_prompt *prompts,
                         int count,
                         gpointer callback_data,
                         struct lu_error **error);

Prompts the user using a text console. Unlike lu_prompt_console(), this function will not prompt users for a question for which the calling application or module supplies a default, and will simply return the default.

Parameters

prompts	An array of lu_prompt structures.
count	The number of elements in the `prompts` array.
callback_data	Ignored.
error	The location to store error information in the event of an error.

Returns

A gboolean indicating success or failure.

Types and Values

struct lu_prompt

struct lu_prompt {
	const char *key;
	const char *prompt;
	const char *domain;
	gboolean visible;
	const char *default_value;
	char *value;
	void (*free_value) (void *);
};

The type of data passed to a prompter function. The library uses these when it needs to prompt the user for information.

Members

const char *`key`;	An invariant string of the form "module/name", which describes the information being prompted for. The calling application may use this value as an index into a hash table used to cache answers to particular queries.
const char *`prompt`;	The text of a prompt to display. This may be translated for the current locale by a module.
const char *`domain`;	The text domain which contains this prompt's translations. This may be the default libuser domain, or a module-specific text domain which the module which provided this prompt bound for gettext when it was loaded.
gboolean `visible`;	Whether or not the user's response should be echoed to the screen (in a console app) or visible in an entry field (in a GUI app).
const char *`default_value`;	A default value, given as a string. This will only contain a value if the string is visible, but the reverse won't necessarily be true (default_value -> visible).
char *`value`;	The user's response. This is set by the prompter function.
`free_value` ()	A function which can free the user's response. This is set by the prompter function. If NULL, the response will not be freed, ever.