← Back to branch summary

~ubuntu-branches/ubuntu/natty/gnome-keyring/natty

« back to all changes in this revision

Viewing changes to docs/reference/gnome-keyring/xml/gnome-keyring-password.xml

  • Committer: Bazaar Package Importer
  • Author(s): Sebastien Bacher
  • Date: 2010-02-16 19:00:06 UTC
  • mfrom: (1.1.58 upstream)
  • Revision ID: james.westby@ubuntu.com-20100216190006-cqpnic4zxlkmmi0o
Tags: 2.29.90git20100218-0ubuntu1
Updated to a git snapshot version

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/reference/gnome-keyring/xml/gnome-keyring-password.xml
1
 
<?xml version="1.0"?>
2
 
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" 
3
 
               "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
4
 
<refentry id="gnome-keyring-gnome-keyring-password">
5
 
<refmeta>
6
 
<refentrytitle role="top_of_page" id="gnome-keyring-gnome-keyring-password.top_of_page">Simple Password Storage</refentrytitle>
7
 
<manvolnum>3</manvolnum>
8
 
<refmiscinfo>GNOME-KEYRING Library</refmiscinfo>
9
 
</refmeta>
10
 
 
11
 
<refnamediv>
12
 
<refname>Simple Password Storage</refname>
13
 
<refpurpose>Store and lookup passwords with a set of attributes.</refpurpose>
14
 
</refnamediv>
15
 
 
16
 
<refsynopsisdiv id="gnome-keyring-gnome-keyring-password.synopsis" role="synopsis">
17
 
<title role="synopsis.title">Synopsis</title>
18
 
 
19
 
<synopsis>
20
 
                    <link linkend="GnomeKeyringPasswordSchema">GnomeKeyringPasswordSchema</link>;
21
 
extern              const GnomeKeyringPasswordSchema* <link linkend="GNOME-KEYRING-NETWORK-PASSWORD--CAPS">GNOME_KEYRING_NETWORK_PASSWORD</link>;
22
 
#define             <link linkend="GNOME-KEYRING-DEFAULT--CAPS">GNOME_KEYRING_DEFAULT</link>
23
 
#define             <link linkend="GNOME-KEYRING-SESSION--CAPS">GNOME_KEYRING_SESSION</link>
24
 
<link linkend="gpointer">gpointer</link>            <link linkend="gnome-keyring-store-password">gnome_keyring_store_password</link>        (const <link linkend="GnomeKeyringPasswordSchema">GnomeKeyringPasswordSchema</link> *schema,
25
 
                                                         const <link linkend="gchar">gchar</link> *keyring,
26
 
                                                         const <link linkend="gchar">gchar</link> *display_name,
27
 
                                                         const <link linkend="gchar">gchar</link> *password,
28
 
                                                         <link linkend="GnomeKeyringOperationDoneCallback">GnomeKeyringOperationDoneCallback</link> callback,
29
 
                                                         <link linkend="gpointer">gpointer</link> data,
30
 
                                                         <link linkend="GDestroyNotify">GDestroyNotify</link> destroy_data,
31
 
                                                         ...);
32
 
<link linkend="GnomeKeyringResult">GnomeKeyringResult</link>  <link linkend="gnome-keyring-store-password-sync">gnome_keyring_store_password_sync</link>   (const <link linkend="GnomeKeyringPasswordSchema">GnomeKeyringPasswordSchema</link> *schema,
33
 
                                                         const <link linkend="gchar">gchar</link> *keyring,
34
 
                                                         const <link linkend="gchar">gchar</link> *display_name,
35
 
                                                         const <link linkend="gchar">gchar</link> *password,
36
 
                                                         ...);
37
 
<link linkend="gpointer">gpointer</link>            <link linkend="gnome-keyring-find-password">gnome_keyring_find_password</link>         (const <link linkend="GnomeKeyringPasswordSchema">GnomeKeyringPasswordSchema</link> *schema,
38
 
                                                         <link linkend="GnomeKeyringOperationGetStringCallback">GnomeKeyringOperationGetStringCallback</link> callback,
39
 
                                                         <link linkend="gpointer">gpointer</link> data,
40
 
                                                         <link linkend="GDestroyNotify">GDestroyNotify</link> destroy_data,
41
 
                                                         ...);
42
 
<link linkend="GnomeKeyringResult">GnomeKeyringResult</link>  <link linkend="gnome-keyring-find-password-sync">gnome_keyring_find_password_sync</link>    (const <link linkend="GnomeKeyringPasswordSchema">GnomeKeyringPasswordSchema</link> *schema,
43
 
                                                         <link linkend="gchar">gchar</link> **password,
44
 
                                                         ...);
45
 
<link linkend="gpointer">gpointer</link>            <link linkend="gnome-keyring-delete-password">gnome_keyring_delete_password</link>       (const <link linkend="GnomeKeyringPasswordSchema">GnomeKeyringPasswordSchema</link> *schema,
46
 
                                                         <link linkend="GnomeKeyringOperationDoneCallback">GnomeKeyringOperationDoneCallback</link> callback,
47
 
                                                         <link linkend="gpointer">gpointer</link> data,
48
 
                                                         <link linkend="GDestroyNotify">GDestroyNotify</link> destroy_data,
49
 
                                                         ...);
50
 
<link linkend="GnomeKeyringResult">GnomeKeyringResult</link>  <link linkend="gnome-keyring-delete-password-sync">gnome_keyring_delete_password_sync</link>  (const <link linkend="GnomeKeyringPasswordSchema">GnomeKeyringPasswordSchema</link> *schema,
51
 
                                                         ...);
52
 
<link linkend="void">void</link>                <link linkend="gnome-keyring-free-password">gnome_keyring_free_password</link>         (<link linkend="gchar">gchar</link> *password);
53
 
</synopsis>
54
 
</refsynopsisdiv>
55
 
 
56
 
 
57
 
 
58
 
 
59
 
 
60
 
 
61
 
 
62
 
 
63
 
 
64
 
<refsect1 id="gnome-keyring-gnome-keyring-password.description" role="desc">
65
 
<title role="desc.title">Description</title>
66
 
<para>
67
 
This is a simple API for storing passwords and retrieving passwords in the keyring.
68
 
</para>
69
 
<para>
70
 
Each password is associated with a set of attributes. Attribute values can be either 
71
 
strings or unsigned integers.
72
 
 
73
 
The names and types of allowed attributes for a given password are defined with a 
74
 
schema. Certain schemas are predefined such as <link linkend="GNOME-KEYRING-NETWORK-PASSWORD--CAPS"><literal>GNOME_KEYRING_NETWORK_PASSWORD</literal></link>. 
75
 
Additional schemas can be defined via the <link linkend="GnomeKeyringPasswordSchema"><literal>GnomeKeyringPasswordSchema</literal></link> structure.
76
 
</para>
77
 
<para>
78
 
Each function accepts a variable list of attributes names and their values. 
79
 
Include a <link linkend="NULL--CAPS"><literal>NULL</literal></link> to terminate the list of attributes.
80
 
</para>
81
 
<para>
82
 
<example>
83
 
<title>Passing attributes to the functions</title>
84
 
<programlisting>
85
 
  res = gnome_keyring_delete_password_sync (GNOME_KEYRING_NETWORK_PASSWORD,
86
 
                                            "user", "me",        // A string attribute
87
 
                                            "server, "example.gnome.org", 
88
 
                                            "port", "8080",      // An integer attribute
89
 
                                            NULL);
90
 
</programlisting></example></para>
91
 
<para>
92
 
</para>
93
 
</refsect1>
94
 
 
95
 
<refsect1 id="gnome-keyring-gnome-keyring-password.details" role="details">
96
 
<title role="details.title">Details</title>
97
 
<refsect2 id="GnomeKeyringPasswordSchema" role="struct">
98
 
<title>GnomeKeyringPasswordSchema</title>
99
 
<indexterm zone="GnomeKeyringPasswordSchema"><primary sortas="GnomeKeyringPasswordSchema">GnomeKeyringPasswordSchema</primary></indexterm><programlisting>typedef struct {
100
 
        GnomeKeyringItemType item_type;
101
 
        struct {
102
 
                const gchar* name;
103
 
                GnomeKeyringAttributeType type;
104
 
        } attributes[32];
105
 
} GnomeKeyringPasswordSchema;
106
 
</programlisting>
107
 
<para>
108
 
Describes a password schema. Often you'll want to use a predefined schema such 
109
 
as <link linkend="GNOME-KEYRING-NETWORK-PASSWORD--CAPS"><literal>GNOME_KEYRING_NETWORK_PASSWORD</literal></link>.
110
 
</para>
111
 
<para>
112
 
<para>
113
 
The last attribute name in a schema must be <link linkend="NULL--CAPS"><literal>NULL</literal></link>.
114
 
</para>
115
 
<para>
116
 
<programlisting>
117
 
  GnomeKeyringPasswordSchema my_schema = {
118
 
      GNOME_KEYRING_ITEM_GENERIC_SECRET,
119
 
      { 
120
 
           { "string-attr", GNOME_KEYRING_ATTRIBUTE_TYPE_STRING },
121
 
           { "uint-attr", GNOME_KEYRING_ATTRIBUTE_TYPE_UINT32 },
122
 
           { NULL, 0 }
123
 
      }
124
 
  };
125
 
</programlisting>
126
 
</para></para>
127
 
<para>
128
 
</para></refsect2>
129
 
<refsect2 id="GNOME-KEYRING-NETWORK-PASSWORD--CAPS" role="variable">
130
 
<title>GNOME_KEYRING_NETWORK_PASSWORD</title>
131
 
<indexterm zone="GNOME-KEYRING-NETWORK-PASSWORD--CAPS"><primary sortas="GNOME_KEYRING_NETWORK_PASSWORD">GNOME_KEYRING_NETWORK_PASSWORD</primary></indexterm><programlisting>extern const GnomeKeyringPasswordSchema* GNOME_KEYRING_NETWORK_PASSWORD; 
132
 
</programlisting>
133
 
<para>
134
 
<para>
135
 
A predefined schema for network paswsords. It contains the following attributes:
136
 
</para>
137
 
<itemizedlist>
138
 
<listitem>user: A string for the user login.</listitem>
139
 
<listitem>server: The server being connected to.</listitem>
140
 
<listitem>protocol: The protocol used to access the server, such as 'http' or 'smb'</listitem>
141
 
<listitem>domain: A realm or domain, such as a Windows login domain.</listitem>
142
 
<listitem>port: The network port to used to connect to the server.</listitem>
143
 
</itemizedlist></para>
144
 
<para>
145
 
</para></refsect2>
146
 
<refsect2 id="GNOME-KEYRING-DEFAULT--CAPS" role="macro">
147
 
<title>GNOME_KEYRING_DEFAULT</title>
148
 
<indexterm zone="GNOME-KEYRING-DEFAULT--CAPS"><primary sortas="GNOME_KEYRING_DEFAULT">GNOME_KEYRING_DEFAULT</primary></indexterm><programlisting>#define GNOME_KEYRING_DEFAULT   NULL
149
 
</programlisting>
150
 
<para>
151
 
<para>
152
 
The default keyring.
153
 
</para></para>
154
 
<para>
155
 
</para></refsect2>
156
 
<refsect2 id="GNOME-KEYRING-SESSION--CAPS" role="macro">
157
 
<title>GNOME_KEYRING_SESSION</title>
158
 
<indexterm zone="GNOME-KEYRING-SESSION--CAPS"><primary sortas="GNOME_KEYRING_SESSION">GNOME_KEYRING_SESSION</primary></indexterm><programlisting>#define GNOME_KEYRING_SESSION   "session"
159
 
</programlisting>
160
 
<para>
161
 
<para>
162
 
A keyring only stored in memory.
163
 
</para></para>
164
 
<para>
165
 
</para></refsect2>
166
 
<refsect2 id="gnome-keyring-store-password" role="function" condition="since:2.22">
167
 
<title>gnome_keyring_store_password ()</title>
168
 
<indexterm zone="gnome-keyring-store-password" role="2.22"><primary sortas="gnome_keyring_store_password">gnome_keyring_store_password</primary></indexterm><programlisting><link linkend="gpointer">gpointer</link>            gnome_keyring_store_password        (const <link linkend="GnomeKeyringPasswordSchema">GnomeKeyringPasswordSchema</link> *schema,
169
 
                                                         const <link linkend="gchar">gchar</link> *keyring,
170
 
                                                         const <link linkend="gchar">gchar</link> *display_name,
171
 
                                                         const <link linkend="gchar">gchar</link> *password,
172
 
                                                         <link linkend="GnomeKeyringOperationDoneCallback">GnomeKeyringOperationDoneCallback</link> callback,
173
 
                                                         <link linkend="gpointer">gpointer</link> data,
174
 
                                                         <link linkend="GDestroyNotify">GDestroyNotify</link> destroy_data,
175
 
                                                         ...);</programlisting>
176
 
<para>
177
 
Store a password associated with a given set of attributes.
178
 
</para>
179
 
<para>
180
 
Attributes which identify this password must be passed as additional 
181
 
arguments. Attributes passed must be defined in the schema.
182
 
</para>
183
 
<para>
184
 
If a password exists in the keyring that already has all the same arguments,
185
 
then the password will be updated. 
186
 
</para>
187
 
<para>
188
 
Another more complex way to create a keyring item is using <link linkend="gnome-keyring-item-create"><function>gnome_keyring_item_create()</function></link>.</para>
189
 
<para>
190
 
</para><variablelist role="params">
191
 
<varlistentry><term><parameter>schema</parameter>&#160;:</term>
192
 
<listitem><simpara> The password schema.
193
 
</simpara></listitem></varlistentry>
194
 
<varlistentry><term><parameter>keyring</parameter>&#160;:</term>
195
 
<listitem><simpara> The keyring to store the password in. Specify <link linkend="NULL--CAPS"><literal>NULL</literal></link> for the default keyring. 
196
 
          Use <link linkend="GNOME-KEYRING-SESSION--CAPS"><literal>GNOME_KEYRING_SESSION</literal></link> to store the password in memory only.
197
 
</simpara></listitem></varlistentry>
198
 
<varlistentry><term><parameter>display_name</parameter>&#160;:</term>
199
 
<listitem><simpara> A human readable description of what the password is for.
200
 
</simpara></listitem></varlistentry>
201
 
<varlistentry><term><parameter>password</parameter>&#160;:</term>
202
 
<listitem><simpara> The password to store.
203
 
</simpara></listitem></varlistentry>
204
 
<varlistentry><term><parameter>callback</parameter>&#160;:</term>
205
 
<listitem><simpara> A callback which will be called when the request completes or fails.
206
 
</simpara></listitem></varlistentry>
207
 
<varlistentry><term><parameter>data</parameter>&#160;:</term>
208
 
<listitem><simpara> A pointer to arbitrary data that will be passed to the <parameter>callback</parameter>.
209
 
</simpara></listitem></varlistentry>
210
 
<varlistentry><term><parameter>destroy_data</parameter>&#160;:</term>
211
 
<listitem><simpara> A function to free <parameter>data</parameter> when it's no longer needed.
212
 
</simpara></listitem></varlistentry>
213
 
<varlistentry><term><parameter>...</parameter>&#160;:</term>
214
 
<listitem><simpara> The variable argument list should contain pairs of a) The attribute name as a null 
215
 
      terminated string, followed by b) attribute value, either a character string, 
216
 
      or 32-bit unsigned int, as defined in the password <parameter>schema</parameter>. The list of attribtues
217
 
      should be terminated with a <link linkend="NULL--CAPS"><literal>NULL</literal></link>. 
218
 
</simpara></listitem></varlistentry>
219
 
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> The asychronous request, which can be passed to <link linkend="gnome-keyring-cancel-request"><function>gnome_keyring_cancel_request()</function></link>.
220
 
</simpara></listitem></varlistentry>
221
 
</variablelist><para role="since">Since 2.22</para></refsect2>
222
 
<refsect2 id="gnome-keyring-store-password-sync" role="function" condition="since:2.22">
223
 
<title>gnome_keyring_store_password_sync ()</title>
224
 
<indexterm zone="gnome-keyring-store-password-sync" role="2.22"><primary sortas="gnome_keyring_store_password_sync">gnome_keyring_store_password_sync</primary></indexterm><programlisting><link linkend="GnomeKeyringResult">GnomeKeyringResult</link>  gnome_keyring_store_password_sync   (const <link linkend="GnomeKeyringPasswordSchema">GnomeKeyringPasswordSchema</link> *schema,
225
 
                                                         const <link linkend="gchar">gchar</link> *keyring,
226
 
                                                         const <link linkend="gchar">gchar</link> *display_name,
227
 
                                                         const <link linkend="gchar">gchar</link> *password,
228
 
                                                         ...);</programlisting>
229
 
<para>
230
 
Store a password associated with a given set of attributes.
231
 
</para>
232
 
<para>
233
 
Attributes which identify this password must be passed as additional 
234
 
arguments. Attributes passed must be defined in the schema.
235
 
</para>
236
 
<para>
237
 
This function may block for an unspecified period. If your application must
238
 
remain responsive to the user, then use <link linkend="gnome-keyring-store-password"><function>gnome_keyring_store_password()</function></link>. 
239
 
</para>
240
 
<para>
241
 
If a password exists in the keyring that already has all the same arguments,
242
 
then the password will be updated. 
243
 
</para>
244
 
<para>
245
 
Another more complex way to create a keyring item is using 
246
 
<link linkend="gnome-keyring-item-create-sync"><function>gnome_keyring_item_create_sync()</function></link>.</para>
247
 
<para>
248
 
</para><variablelist role="params">
249
 
<varlistentry><term><parameter>schema</parameter>&#160;:</term>
250
 
<listitem><simpara> The password schema.
251
 
</simpara></listitem></varlistentry>
252
 
<varlistentry><term><parameter>keyring</parameter>&#160;:</term>
253
 
<listitem><simpara> The keyring to store the password in. Specify <link linkend="NULL--CAPS"><literal>NULL</literal></link> for the default keyring. 
254
 
          Use <link linkend="GNOME-KEYRING-SESSION--CAPS"><literal>GNOME_KEYRING_SESSION</literal></link> to store the password in memory only.
255
 
</simpara></listitem></varlistentry>
256
 
<varlistentry><term><parameter>display_name</parameter>&#160;:</term>
257
 
<listitem><simpara> A human readable description of what the password is for.
258
 
</simpara></listitem></varlistentry>
259
 
<varlistentry><term><parameter>password</parameter>&#160;:</term>
260
 
<listitem><simpara> The password to store.
261
 
</simpara></listitem></varlistentry>
262
 
<varlistentry><term><parameter>...</parameter>&#160;:</term>
263
 
<listitem><simpara> The variable argument list should contain pairs of a) The attribute name as a null 
264
 
      terminated string, followed by b) attribute value, either a character string, 
265
 
      or 32-bit unsigned int, as defined in the password <parameter>schema</parameter>. The list of attribtues
266
 
      should be terminated with a <link linkend="NULL--CAPS"><literal>NULL</literal></link>. 
267
 
</simpara></listitem></varlistentry>
268
 
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="GNOME-KEYRING-RESULT-OK--CAPS"><literal>GNOME_KEYRING_RESULT_OK</literal></link> if the operation was succcessful or 
269
 
an error result otherwise. 
270
 
</simpara></listitem></varlistentry>
271
 
</variablelist><para role="since">Since 2.22</para></refsect2>
272
 
<refsect2 id="gnome-keyring-find-password" role="function" condition="since:2.22">
273
 
<title>gnome_keyring_find_password ()</title>
274
 
<indexterm zone="gnome-keyring-find-password" role="2.22"><primary sortas="gnome_keyring_find_password">gnome_keyring_find_password</primary></indexterm><programlisting><link linkend="gpointer">gpointer</link>            gnome_keyring_find_password         (const <link linkend="GnomeKeyringPasswordSchema">GnomeKeyringPasswordSchema</link> *schema,
275
 
                                                         <link linkend="GnomeKeyringOperationGetStringCallback">GnomeKeyringOperationGetStringCallback</link> callback,
276
 
                                                         <link linkend="gpointer">gpointer</link> data,
277
 
                                                         <link linkend="GDestroyNotify">GDestroyNotify</link> destroy_data,
278
 
                                                         ...);</programlisting>
279
 
<para>
280
 
Find a password that matches a given set of attributes.
281
 
</para>
282
 
<para>
283
 
Attributes which identify this password must be passed as additional 
284
 
arguments. Attributes passed must be defined in the schema.
285
 
</para>
286
 
<para>
287
 
The string that is passed to <parameter>callback</parameter> is automatically freed when the 
288
 
function returns.
289
 
</para>
290
 
<para>
291
 
Another more complex way to find items in the keyrings is using 
292
 
<link linkend="gnome-keyring-find-items"><function>gnome_keyring_find_items()</function></link>.</para>
293
 
<para>
294
 
</para><variablelist role="params">
295
 
<varlistentry><term><parameter>schema</parameter>&#160;:</term>
296
 
<listitem><simpara> The password schema.
297
 
</simpara></listitem></varlistentry>
298
 
<varlistentry><term><parameter>callback</parameter>&#160;:</term>
299
 
<listitem><simpara> A callback which will be called when the request completes or fails.
300
 
</simpara></listitem></varlistentry>
301
 
<varlistentry><term><parameter>data</parameter>&#160;:</term>
302
 
<listitem><simpara> A pointer to arbitrary data that will be passed to the <parameter>callback</parameter>.
303
 
</simpara></listitem></varlistentry>
304
 
<varlistentry><term><parameter>destroy_data</parameter>&#160;:</term>
305
 
<listitem><simpara> A function to free <parameter>data</parameter> when it's no longer needed.
306
 
</simpara></listitem></varlistentry>
307
 
<varlistentry><term><parameter>...</parameter>&#160;:</term>
308
 
<listitem><simpara> The variable argument list should contain pairs of a) The attribute name as a null 
309
 
      terminated string, followed by b) attribute value, either a character string, 
310
 
      or 32-bit unsigned int, as defined in the password <parameter>schema</parameter>. The list of attribtues
311
 
      should be terminated with a <link linkend="NULL--CAPS"><literal>NULL</literal></link>. 
312
 
</simpara></listitem></varlistentry>
313
 
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> The asychronous request, which can be passed to <link linkend="gnome-keyring-cancel-request"><function>gnome_keyring_cancel_request()</function></link>.
314
 
</simpara></listitem></varlistentry>
315
 
</variablelist><para role="since">Since 2.22</para></refsect2>
316
 
<refsect2 id="gnome-keyring-find-password-sync" role="function" condition="since:2.22">
317
 
<title>gnome_keyring_find_password_sync ()</title>
318
 
<indexterm zone="gnome-keyring-find-password-sync" role="2.22"><primary sortas="gnome_keyring_find_password_sync">gnome_keyring_find_password_sync</primary></indexterm><programlisting><link linkend="GnomeKeyringResult">GnomeKeyringResult</link>  gnome_keyring_find_password_sync    (const <link linkend="GnomeKeyringPasswordSchema">GnomeKeyringPasswordSchema</link> *schema,
319
 
                                                         <link linkend="gchar">gchar</link> **password,
320
 
                                                         ...);</programlisting>
321
 
<para>
322
 
Find a password that matches a given set of attributes.
323
 
</para>
324
 
<para>
325
 
Attributes which identify this password must be passed as additional 
326
 
arguments. Attributes passed must be defined in the schema.
327
 
</para>
328
 
<para>
329
 
This function may block for an unspecified period. If your application must
330
 
remain responsive to the user, then use <link linkend="gnome-keyring-find-password"><function>gnome_keyring_find_password()</function></link>. 
331
 
</para>
332
 
<para>
333
 
Another more complex way to find items in the keyrings is using 
334
 
<link linkend="gnome-keyring-find-items-sync"><function>gnome_keyring_find_items_sync()</function></link>.</para>
335
 
<para>
336
 
</para><variablelist role="params">
337
 
<varlistentry><term><parameter>schema</parameter>&#160;:</term>
338
 
<listitem><simpara> The password schema.
339
 
</simpara></listitem></varlistentry>
340
 
<varlistentry><term><parameter>password</parameter>&#160;:</term>
341
 
<listitem><simpara> An address to store password that was found. The password must 
342
 
           be freed with <link linkend="gnome-keyring-free-password"><function>gnome_keyring_free_password()</function></link>.
343
 
</simpara></listitem></varlistentry>
344
 
<varlistentry><term><parameter>...</parameter>&#160;:</term>
345
 
<listitem><simpara> The variable argument list should contain pairs of a) The attribute name as a null 
346
 
      terminated string, followed by b) attribute value, either a character string, 
347
 
      or 32-bit unsigned int, as defined in the password <parameter>schema</parameter>. The list of attribtues
348
 
      should be terminated with a <link linkend="NULL--CAPS"><literal>NULL</literal></link>. 
349
 
</simpara></listitem></varlistentry>
350
 
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="GNOME-KEYRING-RESULT-OK--CAPS"><literal>GNOME_KEYRING_RESULT_OK</literal></link> if the operation was succcessful or 
351
 
an error result otherwise. 
352
 
</simpara></listitem></varlistentry>
353
 
</variablelist><para role="since">Since 2.22</para></refsect2>
354
 
<refsect2 id="gnome-keyring-delete-password" role="function" condition="since:2.22">
355
 
<title>gnome_keyring_delete_password ()</title>
356
 
<indexterm zone="gnome-keyring-delete-password" role="2.22"><primary sortas="gnome_keyring_delete_password">gnome_keyring_delete_password</primary></indexterm><programlisting><link linkend="gpointer">gpointer</link>            gnome_keyring_delete_password       (const <link linkend="GnomeKeyringPasswordSchema">GnomeKeyringPasswordSchema</link> *schema,
357
 
                                                         <link linkend="GnomeKeyringOperationDoneCallback">GnomeKeyringOperationDoneCallback</link> callback,
358
 
                                                         <link linkend="gpointer">gpointer</link> data,
359
 
                                                         <link linkend="GDestroyNotify">GDestroyNotify</link> destroy_data,
360
 
                                                         ...);</programlisting>
361
 
<para>
362
 
Delete a password that matches a given set of attributes.
363
 
</para>
364
 
<para>
365
 
Attributes which identify this password must be passed as additional 
366
 
arguments. Attributes passed must be defined in the schema.
367
 
</para>
368
 
<para>
369
 
Another more complex way to find items in the keyrings is using 
370
 
<link linkend="gnome-keyring-item-delete"><function>gnome_keyring_item_delete()</function></link>.</para>
371
 
<para>
372
 
</para><variablelist role="params">
373
 
<varlistentry><term><parameter>schema</parameter>&#160;:</term>
374
 
<listitem><simpara> The password schema.
375
 
</simpara></listitem></varlistentry>
376
 
<varlistentry><term><parameter>callback</parameter>&#160;:</term>
377
 
<listitem><simpara> A callback which will be called when the request completes or fails.
378
 
</simpara></listitem></varlistentry>
379
 
<varlistentry><term><parameter>data</parameter>&#160;:</term>
380
 
<listitem><simpara> A pointer to arbitrary data that will be passed to the <parameter>callback</parameter>.
381
 
</simpara></listitem></varlistentry>
382
 
<varlistentry><term><parameter>destroy_data</parameter>&#160;:</term>
383
 
<listitem><simpara> A function to free <parameter>data</parameter> when it's no longer needed.
384
 
</simpara></listitem></varlistentry>
385
 
<varlistentry><term><parameter>...</parameter>&#160;:</term>
386
 
<listitem><simpara> The variable argument list should contain pairs of a) The attribute name as a null 
387
 
      terminated string, followed by b) attribute value, either a character string, 
388
 
      or 32-bit unsigned int, as defined in the password <parameter>schema</parameter>. The list of attribtues
389
 
      should be terminated with a <link linkend="NULL--CAPS"><literal>NULL</literal></link>. 
390
 
</simpara></listitem></varlistentry>
391
 
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> The asychronous request, which can be passed to <link linkend="gnome-keyring-cancel-request"><function>gnome_keyring_cancel_request()</function></link>.
392
 
</simpara></listitem></varlistentry>
393
 
</variablelist><para role="since">Since 2.22</para></refsect2>
394
 
<refsect2 id="gnome-keyring-delete-password-sync" role="function" condition="since:2.22">
395
 
<title>gnome_keyring_delete_password_sync ()</title>
396
 
<indexterm zone="gnome-keyring-delete-password-sync" role="2.22"><primary sortas="gnome_keyring_delete_password_sync">gnome_keyring_delete_password_sync</primary></indexterm><programlisting><link linkend="GnomeKeyringResult">GnomeKeyringResult</link>  gnome_keyring_delete_password_sync  (const <link linkend="GnomeKeyringPasswordSchema">GnomeKeyringPasswordSchema</link> *schema,
397
 
                                                         ...);</programlisting>
398
 
<para>
399
 
Delete a password that matches a given set of attributes.
400
 
</para>
401
 
<para>
402
 
Attributes which identify this password must be passed as additional 
403
 
arguments. Attributes passed must be defined in the schema.
404
 
</para>
405
 
<para>
406
 
This function may block for an unspecified period. If your application must
407
 
remain responsive to the user, then use <link linkend="gnome-keyring-delete-password"><function>gnome_keyring_delete_password()</function></link>. 
408
 
</para>
409
 
<para>
410
 
Another more complex way to find items in the keyrings is using 
411
 
<link linkend="gnome-keyring-item-delete-sync"><function>gnome_keyring_item_delete_sync()</function></link>.</para>
412
 
<para>
413
 
</para><variablelist role="params">
414
 
<varlistentry><term><parameter>schema</parameter>&#160;:</term>
415
 
<listitem><simpara> The password schema.
416
 
</simpara></listitem></varlistentry>
417
 
<varlistentry><term><parameter>...</parameter>&#160;:</term>
418
 
<listitem><simpara> The variable argument list should contain pairs of a) The attribute name as a null 
419
 
      terminated string, followed by b) attribute value, either a character string, 
420
 
      or 32-bit unsigned int, as defined in the password <parameter>schema</parameter>. The list of attribtues
421
 
      should be terminated with a <link linkend="NULL--CAPS"><literal>NULL</literal></link>. 
422
 
</simpara></listitem></varlistentry>
423
 
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="GNOME-KEYRING-RESULT-OK--CAPS"><literal>GNOME_KEYRING_RESULT_OK</literal></link> if the operation was succcessful or 
424
 
an error result otherwise. 
425
 
</simpara></listitem></varlistentry>
426
 
</variablelist><para role="since">Since 2.22</para></refsect2>
427
 
<refsect2 id="gnome-keyring-free-password" role="function">
428
 
<title>gnome_keyring_free_password ()</title>
429
 
<indexterm zone="gnome-keyring-free-password"><primary sortas="gnome_keyring_free_password">gnome_keyring_free_password</primary></indexterm><programlisting><link linkend="void">void</link>                gnome_keyring_free_password         (<link linkend="gchar">gchar</link> *password);</programlisting>
430
 
<para>
431
 
Clears the memory used by password by filling with '\0' and frees the memory
432
 
after doing this. You should use this function instead of <link linkend="g-free"><function>g_free()</function></link> for
433
 
secret information.</para>
434
 
<para>
435
 
</para><variablelist role="params">
436
 
<varlistentry><term><parameter>password</parameter>&#160;:</term>
437
 
<listitem><simpara> the password to be freed
438
 
</simpara></listitem></varlistentry>
439
 
</variablelist></refsect2>
440
 
 
441
 
</refsect1>
442
 
 
443
 
 
444
 
 
445
 
 
446
 
</refentry>