## NMSecretAgent

NMSecretAgent

## Synopsis

    #define             NM_SECRET_AGENT_ERROR
    #define             NM_TYPE_SECRET_AGENT_ERROR
    GQuark              nm_secret_agent_error_quark         (void);
    enum                NMSecretAgentError;
    enum                NMSecretAgentGetSecretsFlags;
    #define             NM_SECRET_AGENT_IDENTIFIER
    #define             NM_SECRET_AGENT_AUTO_REGISTER
    #define             NM_SECRET_AGENT_REGISTRATION_RESULT
                        NMSecretAgent;
    void                (*NMSecretAgentGetSecretsFunc)      (NMSecretAgent *agent,
                                                             NMConnection *connection,
                                                             GHashTable *secrets,
                                                             GError *error,
                                                             gpointer user_data);
    void                (*NMSecretAgentSaveSecretsFunc)     (NMSecretAgent *agent,
                                                             NMConnection *connection,
                                                             GError *error,
                                                             gpointer user_data);
    void                (*NMSecretAgentDeleteSecretsFunc)   (NMSecretAgent *agent,
                                                             NMConnection *connection,
                                                             GError *error,
                                                             gpointer user_data);
                        NMSecretAgentClass;
    GType               nm_secret_agent_get_type            (void);
    gboolean            nm_secret_agent_register            (NMSecretAgent *self);
    gboolean            nm_secret_agent_unregister          (NMSecretAgent *self);
    void                nm_secret_agent_get_secrets         (NMSecretAgent *self,
                                                             NMConnection *connection,
                                                             const char *setting_name,
                                                             const char **hints,
                                                             NMSecretAgentGetSecretsFlags flags,
                                                             NMSecretAgentGetSecretsFunc callback,
                                                             gpointer callback_data);
    void                nm_secret_agent_save_secrets        (NMSecretAgent *self,
                                                             NMConnection *connection,
                                                             NMSecretAgentSaveSecretsFunc callback,
                                                             gpointer callback_data);
    void                nm_secret_agent_delete_secrets      (NMSecretAgent *self,
                                                             NMConnection *connection,
                                                             NMSecretAgentDeleteSecretsFunc callback,
                                                             gpointer callback_data);

## Object Hierarchy

      GObject
       +----NMSecretAgent

## Properties

      "auto-register"            gboolean              : Read / Write / Construct
      "identifier"               gchar*                : Read / Write / Construct Only

## Signals

      "registration-result"                            : Run First

## Description

## Details

### NM_SECRET_AGENT_ERROR

    #define NM_SECRET_AGENT_ERROR         (nm_secret_agent_error_quark ())

### NM_TYPE_SECRET_AGENT_ERROR

    #define NM_TYPE_SECRET_AGENT_ERROR    (nm_secret_agent_error_get_type ())

### nm_secret_agent_error_quark ()

    GQuark              nm_secret_agent_error_quark         (void);

### enum NMSecretAgentError

    typedef enum {
    	NM_SECRET_AGENT_ERROR_NOT_AUTHORIZED = 0,
    	NM_SECRET_AGENT_ERROR_INVALID_CONNECTION,
    	NM_SECRET_AGENT_ERROR_USER_CANCELED,
    	NM_SECRET_AGENT_ERROR_AGENT_CANCELED,
    	NM_SECRET_AGENT_ERROR_INTERNAL_ERROR,
    	NM_SECRET_AGENT_ERROR_NO_SECRETS,
    } NMSecretAgentError;

### enum NMSecretAgentGetSecretsFlags

    typedef enum {
    	NM_SECRET_AGENT_GET_SECRETS_FLAG_NONE = 0x0,
    	NM_SECRET_AGENT_GET_SECRETS_FLAG_ALLOW_INTERACTION = 0x1,
    	NM_SECRET_AGENT_GET_SECRETS_FLAG_REQUEST_NEW = 0x2
    } NMSecretAgentGetSecretsFlags;

NMSecretAgentGetSecretsFlags values modify the behavior of a GetSecrets request.

`NM_SECRET_AGENT_GET_SECRETS_FLAG_NONE` | no special behavior; by default no user interaction is allowed and requests for secrets are fulfilled from persistent storage, or if no secrets are available an error is returned.
`NM_SECRET_AGENT_GET_SECRETS_FLAG_ALLOW_INTERACTION` | allows the request to interact with the user, possibly prompting via UI for secrets if any are required, or if none are found in persistent storage.
`NM_SECRET_AGENT_GET_SECRETS_FLAG_REQUEST_NEW` | explicitly prompt for new secrets from the user. This flag signals that NetworkManager thinks any existing secrets are invalid or wrong. This flag implies that interaction is allowed.

### NM_SECRET_AGENT_IDENTIFIER

    #define NM_SECRET_AGENT_IDENTIFIER          "identifier"

### NM_SECRET_AGENT_AUTO_REGISTER

    #define NM_SECRET_AGENT_AUTO_REGISTER       "auto-register"

### NM_SECRET_AGENT_REGISTRATION_RESULT

    #define NM_SECRET_AGENT_REGISTRATION_RESULT "registration-result"

### NMSecretAgent

    typedef struct _NMSecretAgent NMSecretAgent;

### NMSecretAgentGetSecretsFunc ()

    void                (*NMSecretAgentGetSecretsFunc)      (NMSecretAgent *agent,
                                                             NMConnection *connection,
                                                             GHashTable *secrets,
                                                             GError *error,
                                                             gpointer user_data);

### NMSecretAgentSaveSecretsFunc ()

    void                (*NMSecretAgentSaveSecretsFunc)     (NMSecretAgent *agent,
                                                             NMConnection *connection,
                                                             GError *error,
                                                             gpointer user_data);

### NMSecretAgentDeleteSecretsFunc ()

    void                (*NMSecretAgentDeleteSecretsFunc)   (NMSecretAgent *agent,
                                                             NMConnection *connection,
                                                             GError *error,
                                                             gpointer user_data);

### NMSecretAgentClass

    typedef struct {
    	GObjectClass parent;

    	/* Virtual methods for subclasses */

    	/* Called when the subclass should retrieve and return secrets.  Subclass
    	 * must copy or reference any arguments it may require after returning from
    	 * this method, as the arguments will freed (except for 'agent', 'callback',
    	 * and 'callback_data' of course).  If the request is canceled, the callback
    	 * should still be called, but with the NM_SECRET_AGENT_ERROR_AGENT_CANCELED
    	 * error.
    	 */
    	void (*get_secrets) (NMSecretAgent *agent,
    	                     NMConnection *connection,
    	                     const char *connection_path,
    	                     const char *setting_name,
    	                     const char **hints,
    	                     NMSecretAgentGetSecretsFlags flags,
    	                     NMSecretAgentGetSecretsFunc callback,
    	                     gpointer callback_data);

    	/* Called when the subclass should cancel an outstanding request to
    	 * get secrets for a given connection.  Canceling the request MUST
    	 * call the callback that was passed along with the initial get_secrets
    	 * call, sending the NM_SECRET_AGENT_ERROR/NM_SECRET_AGENT_ERROR_AGENT_CANCELED
    	 * error to that callback.
    	 */
    	void (*cancel_get_secrets) (NMSecretAgent *agent,
    	                            const char *connection_path,
    	                            const char *setting_name);

    	/* Called when the subclass should save the secrets contained in the
    	 * connection to backing storage.  Subclass must copy or reference any
    	 * arguments it may require after returning from this method, as the
    	 * arguments will freed (except for 'agent', 'callback', and 'callback_data'
    	 * of course).
    	 */
    	void (*save_secrets) (NMSecretAgent *agent,
    	                      NMConnection *connection,
    	                      const char *connection_path,
    	                      NMSecretAgentSaveSecretsFunc callback,
    	                      gpointer callback_data);

    	/* Called when the subclass should delete the secrets contained in the
    	 * connection from backing storage.  Subclass must copy or reference any
    	 * arguments it may require after returning from this method, as the
    	 * arguments will freed (except for 'agent', 'callback', and 'callback_data'
    	 * of course).
    	 */
    	void (*delete_secrets) (NMSecretAgent *agent,
    	                        NMConnection *connection,
    	                        const char *connection_path,
    	                        NMSecretAgentDeleteSecretsFunc callback,
    	                        gpointer callback_data);

    	/* Signals */
    	void (*registration_result) (NMSecretAgent *agent, GError *error);

    	/* Padding for future expansion */
    	void (*_reserved1) (void);
    	void (*_reserved2) (void);
    	void (*_reserved3) (void);
    	void (*_reserved4) (void);
    	void (*_reserved5) (void);
    	void (*_reserved6) (void);
    } NMSecretAgentClass;

### nm_secret_agent_get_type ()

    GType               nm_secret_agent_get_type            (void);

### nm_secret_agent_register ()

    gboolean            nm_secret_agent_register            (NMSecretAgent *self);

Registers the NMSecretAgent with the NetworkManager secret manager, indicating to NetworkManager that the agent is able to provide and save secrets for connections on behalf of its user. Registration is an asynchronous operation and its success or failure is indicated via the 'registration-result' signal.

`self` : | a NMSecretAgent
Returns : | a new `TRUE` if registration was successfully requested (this does not mean registration itself was successful), `FALSE` if registration was not successfully requested.

### nm_secret_agent_unregister ()

    gboolean            nm_secret_agent_unregister          (NMSecretAgent *self);

Unregisters the NMSecretAgent with the NetworkManager secret manager, indicating to NetworkManager that the agent is will no longer provide or store secrets on behalf of this user.

`self` : | a NMSecretAgent
Returns : | a new `TRUE` if unregistration was successful, `FALSE` if it was not.

### nm_secret_agent_get_secrets ()

    void                nm_secret_agent_get_secrets         (NMSecretAgent *self,
                                                             NMConnection *connection,
                                                             const char *setting_name,
                                                             const char **hints,
                                                             NMSecretAgentGetSecretsFlags flags,
                                                             NMSecretAgentGetSecretsFunc callback,
                                                             gpointer callback_data);

Asyncronously retrieve secrets belonging to `connection` for the setting `setting_name`. `flags` indicate specific behavior that the secret agent should use when performing the request, for example returning only existing secrets without user interaction, or requesting entirely new secrets from the user.

VFunc: get_secrets

`self` : | a NMSecretAgent
`connection` : | the NMConnection for which we're asked secrets
`setting_name` : | the name of the secret setting
`hints` : | hints to the agent. [array zero-terminated=1]
`flags` : | flags that modify the behavior of the request
`callback` : | a callback, invoked when the operation is done. [scope async]
`callback_data` : | . [closure]

### nm_secret_agent_save_secrets ()

    void                nm_secret_agent_save_secrets        (NMSecretAgent *self,
                                                             NMConnection *connection,
                                                             NMSecretAgentSaveSecretsFunc callback,
                                                             gpointer callback_data);

Asyncronously ensure that all secrets inside `connection` are stored to disk.

VFunc: save_secrets

`self` : | a NMSecretAgent
`connection` : | a NMConnection
`callback` : | a callback, invoked when the operation is done. [scope async]
`callback_data` : | . [closure]

### nm_secret_agent_delete_secrets ()

    void                nm_secret_agent_delete_secrets      (NMSecretAgent *self,
                                                             NMConnection *connection,
                                                             NMSecretAgentDeleteSecretsFunc callback,
                                                             gpointer callback_data);

Asynchronously ask the agent to delete all saved secrets belonging to `connection`.

VFunc: delete_secrets

`self` : | a NMSecretAgent
`connection` : | a NMConnection
`callback` : | a callback, invoked when the operation is done. [scope async]
`callback_data` : | . [closure]

## Property Details

### The `"auto-register"` property

      "auto-register"            gboolean              : Read / Write / Construct

If TRUE, the agent will attempt to automatically register itself after it is created (via an idle handler) and to re-register itself if NetworkManager restarts. If FALSE, the agent does not automatically register with NetworkManager, and `nm_secret_agent_register()` must be called. If 'auto-register' is TRUE, calling `nm_secret_agent_unregister()` will suppress auto-registration until `nm_secret_agent_register()` is called, which re-enables auto-registration.

Default value: TRUE

### The `"identifier"` property

      "identifier"               gchar*                : Read / Write / Construct Only

Identifies this agent; only one agent in each user session may use the same identifier. Identifier formatting follows the same rules as D-Bus bus names with the exception that the ':' character is not allowed. The valid set of characters is "[A-Z][a-z][0-9]_-." and the identifier is limited in length to 255 characters with a minimum of 3 characters. An example valid identifier is 'org.gnome.nm-applet' (without quotes).

Default value: NULL

## Signal Details

### The `"registration-result"` signal

    void                user_function                      (NMSecretAgent *agent,
                                                            gpointer       error,
                                                            gpointer       user_data)      : Run First

Indicates the result of a registration request; if `error` is NULL the request was successful.

`agent` : | the agent that received the signal
`error` : | the error, if any, that occured while registering
`user_data` : | user data set when the signal handler was connected.