libnm-glib Reference Manual | ||||
---|---|---|---|---|
Top | Description | Object Hierarchy | Properties | Signals |
Synopsis
#define NM_SECRET_AGENT_ERROR GQuark nm_secret_agent_error_quark (void
); enum NMSecretAgentError; enum NMSecretAgentCapabilities; enum NMSecretAgentGetSecretsFlags; #define NM_SECRET_AGENT_IDENTIFIER #define NM_SECRET_AGENT_AUTO_REGISTER #define NM_SECRET_AGENT_REGISTERED #define NM_SECRET_AGENT_CAPABILITIES #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; gboolean nm_secret_agent_register (NMSecretAgent *self
); gboolean nm_secret_agent_unregister (NMSecretAgent *self
); gboolean nm_secret_agent_get_registered (NMSecretAgent *self
); void nm_secret_agent_get_secrets (NMSecretAgent *self
,NMConnection *connection
,const char *setting_name
,const char **hints
,NMSecretAgentGetSecretsFlags flags
,NMSecretAgentGetSecretsFunc callback
,gpointer user_data
); void nm_secret_agent_save_secrets (NMSecretAgent *self
,NMConnection *connection
,NMSecretAgentSaveSecretsFunc callback
,gpointer user_data
); void nm_secret_agent_delete_secrets (NMSecretAgent *self
,NMConnection *connection
,NMSecretAgentDeleteSecretsFunc callback
,gpointer user_data
);
Properties
"auto-register" gboolean : Read / Write / Construct "capabilities" NMSecretAgentCapabilities : Read / Write / Construct "identifier" gchar* : Read / Write / Construct Only "registered" gboolean : Read
Details
enum NMSecretAgentError
typedef enum { NM_SECRET_AGENT_ERROR_NOT_AUTHORIZED = 0, /*< nick=NotAuthorized >*/ NM_SECRET_AGENT_ERROR_INVALID_CONNECTION, /*< nick=InvalidConnection >*/ NM_SECRET_AGENT_ERROR_USER_CANCELED, /*< nick=UserCanceled >*/ NM_SECRET_AGENT_ERROR_AGENT_CANCELED, /*< nick=AgentCanceled >*/ NM_SECRET_AGENT_ERROR_INTERNAL_ERROR, /*< nick=InternalError >*/ NM_SECRET_AGENT_ERROR_NO_SECRETS, /*< nick=NoSecrets >*/ } NMSecretAgentError;
NMSecretAgentError values are passed by secret agents back to NetworkManager when they encounter problems retrieving secrets on behalf of NM.
the caller (ie, NetworkManager) is not authorized to make this request | |
the connection for which secrets were requested could not be found | |
the request was canceled by the user | |
the agent canceled the request because it was requested to do so by NetworkManager | |
some internal error in the agent caused the request to fail | |
the agent cannot find any secrets for this connection |
enum NMSecretAgentCapabilities
typedef enum { NM_SECRET_AGENT_CAPABILITY_NONE = 0x0, NM_SECRET_AGENT_CAPABILITY_VPN_HINTS = 0x1, /* boundary value */ NM_SECRET_AGENT_CAPABILITY_LAST = NM_SECRET_AGENT_CAPABILITY_VPN_HINTS } NMSecretAgentCapabilities;
NMSecretAgentCapabilities indicate various capabilities of the agent.
the agent supports no special capabilities | |
the agent supports sending hints given
by the NMSecretAgentClass::get_secrets() class method to VPN plugin
authentication dialogs.
|
|
bounds checking value; should not be used. |
Since 0.9.10
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, NM_SECRET_AGENT_GET_SECRETS_FLAG_USER_REQUESTED = 0x4 } NMSecretAgentGetSecretsFlags;
NMSecretAgentGetSecretsFlags values modify the behavior of a GetSecrets request.
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. | |
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. | |
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. | |
set if the request was initiated by user-requested action via the D-Bus interface, as opposed to automatically initiated by NetworkManager in response to (for example) scan results or carrier changes. |
NM_SECRET_AGENT_REGISTRATION_RESULT
#define NM_SECRET_AGENT_REGISTRATION_RESULT "registration-result"
NMSecretAgentGetSecretsFunc ()
void (*NMSecretAgentGetSecretsFunc) (NMSecretAgent *agent
,NMConnection *connection
,GHashTable *secrets
,GError *error
,gpointer user_data
);
Called as a result of a request by NM to retrieve secrets. When the NMSecretAgent subclass has finished retrieving secrets and is ready to return them, or to return an error, this function should be called with those secrets or the error.
To easily create the hash table to return the Wi-Fi PSK, you could do something like this:
Example 1. Creating a secrets hash
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
NMConnection *secrets; NMSettingWirelessSecurity *s_wsec; GHashTable *secrets_hash; secrets = nm_connection_new (); s_wsec = (NMSettingWirelessSecurity *) nm_setting_wireless_security_new (); g_object_set (G_OBJECT (s_wsec), NM_SETTING_WIRELESS_SECURITY_PSK, "my really cool PSK", NULL); nm_connection_add_setting (secrets, NM_SETTING (s_wsec)); secrets_hash = nm_connection_to_hash (secrets, NM_SETTING_HASH_FLAG_ALL); (call the NMSecretAgentGetSecretsFunc with secrets_hash) g_object_unref (secrets); g_hash_table_unref (secrets_hash); |
|
the secret agent object |
|
the connection for which secrets were requested,
note that this object will be unrefed after the callback has returned, use
g_object_ref() /g_object_unref() if you want to use this object after the callback
has returned. [transfer none]
|
|
the GHashTable containing
the requested secrets in the same format as an NMConnection hash (as
created by nm_connection_to_hash() for example). Each key in secrets
should be the name of a NMSetting object (like "802-11-wireless-security")
and each value should be a GHashTable. The sub-hashes map string:GValue
where the string is the setting property name (like "psk") and the value
is the secret. [element-type utf8 GLib.HashTable]
|
|
if the secrets request failed, give a descriptive error here |
|
caller-specific data to be passed to the function |
NMSecretAgentSaveSecretsFunc ()
void (*NMSecretAgentSaveSecretsFunc) (NMSecretAgent *agent
,NMConnection *connection
,GError *error
,gpointer user_data
);
Called as a result of a request by NM to save secrets. When the NMSecretAgent subclass has finished saving the secrets, this function should be called.
|
the secret agent object |
|
the connection for which secrets were to be saved,
note that this object will be unrefed after the callback has returned, use
g_object_ref() /g_object_unref() if you want to use this object after the callback
has returned. [transfer none]
|
|
if the saving secrets failed, give a descriptive error here |
|
caller-specific data to be passed to the function |
NMSecretAgentDeleteSecretsFunc ()
void (*NMSecretAgentDeleteSecretsFunc) (NMSecretAgent *agent
,NMConnection *connection
,GError *error
,gpointer user_data
);
Called as a result of a request by NM to delete secrets. When the NMSecretAgent subclass has finished deleting the secrets, this function should be called.
|
the secret agent object |
|
the connection for which secrets were to be deleted,
note that this object will be unrefed after the callback has returned, use
g_object_ref() /g_object_unref() if you want to use this object after the callback
has returned. [transfer none]
|
|
if the deleting secrets failed, give a descriptive error here |
|
caller-specific data to be passed to the function |
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 'self', 'callback', * and 'user_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 *self, NMConnection *connection, const char *connection_path, const char *setting_name, const char **hints, NMSecretAgentGetSecretsFlags flags, NMSecretAgentGetSecretsFunc callback, gpointer user_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 *self, 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 'self', 'callback', and 'user_data' * of course). */ void (*save_secrets) (NMSecretAgent *self, NMConnection *connection, const char *connection_path, NMSecretAgentSaveSecretsFunc callback, gpointer user_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 'self', 'callback', and 'user_data' * of course). */ void (*delete_secrets) (NMSecretAgent *self, NMConnection *connection, const char *connection_path, NMSecretAgentDeleteSecretsFunc callback, gpointer user_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_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.
|
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.
|
a NMSecretAgent |
Returns : |
a new TRUE if unregistration was successful, FALSE if it was not. |
nm_secret_agent_get_registered ()
gboolean nm_secret_agent_get_registered (NMSecretAgent *self
);
|
a NMSecretAgent |
Returns : |
a TRUE if the agent is registered, FALSE if it is 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 user_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.
Virtual: get_secrets
|
a NMSecretAgent |
|
the NMConnection for which we're asked secrets |
|
the name of the secret setting |
|
hints to the agent. [array zero-terminated=1] |
|
flags that modify the behavior of the request |
|
a callback, to be invoked when the operation is done. [scope async] |
|
caller-specific data to be passed to callback . [closure]
|
nm_secret_agent_save_secrets ()
void nm_secret_agent_save_secrets (NMSecretAgent *self
,NMConnection *connection
,NMSecretAgentSaveSecretsFunc callback
,gpointer user_data
);
Asyncronously ensure that all secrets inside connection
are stored to disk.
Virtual: save_secrets
|
a NMSecretAgent |
|
a NMConnection |
|
a callback, to be invoked when the operation is done. [scope async] |
|
caller-specific data to be passed to callback . [closure]
|
nm_secret_agent_delete_secrets ()
void nm_secret_agent_delete_secrets (NMSecretAgent *self
,NMConnection *connection
,NMSecretAgentDeleteSecretsFunc callback
,gpointer user_data
);
Asynchronously ask the agent to delete all saved secrets belonging to
connection
.
Virtual: delete_secrets
|
a NMSecretAgent |
|
a NMConnection |
|
a callback, to be invoked when the operation is done. [scope async] |
|
caller-specific data to be passed to callback . [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 "capabilities"
property
"capabilities" NMSecretAgentCapabilities : Read / Write / Construct
A bitfield of NMSecretAgentCapabilities
.
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.
|
the agent that received the signal |
|
the error, if any, that occured while registering |
|
user data set when the signal handler was connected. |