← 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-find.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-find.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-find">
5
 
<refmeta>
6
 
<refentrytitle role="top_of_page" id="gnome-keyring-gnome-keyring-find.top_of_page">Search Functionality</refentrytitle>
7
 
<manvolnum>3</manvolnum>
8
 
<refmiscinfo>GNOME-KEYRING Library</refmiscinfo>
9
 
</refmeta>
10
 
 
11
 
<refnamediv>
12
 
<refname>Search Functionality</refname>
13
 
<refpurpose>Find Keyring Items</refpurpose>
14
 
</refnamediv>
15
 
 
16
 
<refsynopsisdiv id="gnome-keyring-gnome-keyring-find.synopsis" role="synopsis">
17
 
<title role="synopsis.title">Synopsis</title>
18
 
 
19
 
<synopsis>
20
 
                    <link linkend="GnomeKeyringFound">GnomeKeyringFound</link>;
21
 
<link linkend="void">void</link>                <link linkend="gnome-keyring-found-free">gnome_keyring_found_free</link>            (<link linkend="GnomeKeyringFound">GnomeKeyringFound</link> *found);
22
 
<link linkend="void">void</link>                <link linkend="gnome-keyring-found-list-free">gnome_keyring_found_list_free</link>       (<link linkend="GList">GList</link> *found_list);
23
 
<link linkend="gpointer">gpointer</link>            <link linkend="gnome-keyring-find-items">gnome_keyring_find_items</link>            (<link linkend="GnomeKeyringItemType">GnomeKeyringItemType</link> type,
24
 
                                                         <link linkend="GnomeKeyringAttributeList">GnomeKeyringAttributeList</link> *attributes,
25
 
                                                         <link linkend="GnomeKeyringOperationGetListCallback">GnomeKeyringOperationGetListCallback</link> callback,
26
 
                                                         <link linkend="gpointer">gpointer</link> data,
27
 
                                                         <link linkend="GDestroyNotify">GDestroyNotify</link> destroy_data);
28
 
<link linkend="gpointer">gpointer</link>            <link linkend="gnome-keyring-find-itemsv">gnome_keyring_find_itemsv</link>           (<link linkend="GnomeKeyringItemType">GnomeKeyringItemType</link> type,
29
 
                                                         <link linkend="GnomeKeyringOperationGetListCallback">GnomeKeyringOperationGetListCallback</link> callback,
30
 
                                                         <link linkend="gpointer">gpointer</link> data,
31
 
                                                         <link linkend="GDestroyNotify">GDestroyNotify</link> destroy_data,
32
 
                                                         ...);
33
 
<link linkend="GnomeKeyringResult">GnomeKeyringResult</link>  <link linkend="gnome-keyring-find-items-sync">gnome_keyring_find_items_sync</link>       (<link linkend="GnomeKeyringItemType">GnomeKeyringItemType</link> type,
34
 
                                                         <link linkend="GnomeKeyringAttributeList">GnomeKeyringAttributeList</link> *attributes,
35
 
                                                         <link linkend="GList">GList</link> **found);
36
 
<link linkend="GnomeKeyringResult">GnomeKeyringResult</link>  <link linkend="gnome-keyring-find-itemsv-sync">gnome_keyring_find_itemsv_sync</link>      (<link linkend="GnomeKeyringItemType">GnomeKeyringItemType</link> type,
37
 
                                                         <link linkend="GList">GList</link> **found,
38
 
                                                         ...);
39
 
</synopsis>
40
 
</refsynopsisdiv>
41
 
 
42
 
 
43
 
 
44
 
 
45
 
 
46
 
 
47
 
 
48
 
 
49
 
 
50
 
<refsect1 id="gnome-keyring-gnome-keyring-find.description" role="desc">
51
 
<title role="desc.title">Description</title>
52
 
<para>
53
 
A find operation searches through all keyrings for items that match the 
54
 
attributes. The user may have been prompted to unlock necessary keyrings, and 
55
 
user will have been prompted for access to the items if needed.
56
 
</para>
57
 
<para>
58
 
A find operation may return multiple or zero results.</para>
59
 
<para>
60
 
</para>
61
 
</refsect1>
62
 
 
63
 
<refsect1 id="gnome-keyring-gnome-keyring-find.details" role="details">
64
 
<title role="details.title">Details</title>
65
 
<refsect2 id="GnomeKeyringFound" role="struct">
66
 
<title>GnomeKeyringFound</title>
67
 
<indexterm zone="GnomeKeyringFound"><primary sortas="GnomeKeyringFound">GnomeKeyringFound</primary></indexterm><programlisting>typedef struct {
68
 
        char *keyring;
69
 
        guint item_id;
70
 
        GnomeKeyringAttributeList *attributes;
71
 
        char *secret;
72
 
} GnomeKeyringFound;
73
 
</programlisting>
74
 
<para>
75
 
</para></refsect2>
76
 
<refsect2 id="gnome-keyring-found-free" role="function">
77
 
<title>gnome_keyring_found_free ()</title>
78
 
<indexterm zone="gnome-keyring-found-free"><primary sortas="gnome_keyring_found_free">gnome_keyring_found_free</primary></indexterm><programlisting><link linkend="void">void</link>                gnome_keyring_found_free            (<link linkend="GnomeKeyringFound">GnomeKeyringFound</link> *found);</programlisting>
79
 
<para>
80
 
Free the memory used by a <link linkend="GnomeKeyringFound"><type>GnomeKeyringFound</type></link> item.
81
 
</para>
82
 
<para>
83
 
You usually want to use <link linkend="gnome-keyring-found-list-free"><function>gnome_keyring_found_list_free()</function></link> on the list of
84
 
results.</para>
85
 
<para>
86
 
</para><variablelist role="params">
87
 
<varlistentry><term><parameter>found</parameter>&#160;:</term>
88
 
<listitem><simpara> a <link linkend="GnomeKeyringFound"><type>GnomeKeyringFound</type></link>
89
 
</simpara></listitem></varlistentry>
90
 
</variablelist></refsect2>
91
 
<refsect2 id="gnome-keyring-found-list-free" role="function">
92
 
<title>gnome_keyring_found_list_free ()</title>
93
 
<indexterm zone="gnome-keyring-found-list-free"><primary sortas="gnome_keyring_found_list_free">gnome_keyring_found_list_free</primary></indexterm><programlisting><link linkend="void">void</link>                gnome_keyring_found_list_free       (<link linkend="GList">GList</link> *found_list);</programlisting>
94
 
<para>
95
 
Free the memory used by the <link linkend="GnomeKeyringFound"><type>GnomeKeyringFound</type></link> items in <parameter>found_list</parameter>.</para>
96
 
<para>
97
 
</para><variablelist role="params">
98
 
<varlistentry><term><parameter>found_list</parameter>&#160;:</term>
99
 
<listitem><simpara> a <link linkend="GList"><type>GList</type></link> of <link linkend="GnomeKeyringFound"><type>GnomeKeyringFound</type></link>
100
 
</simpara></listitem></varlistentry>
101
 
</variablelist></refsect2>
102
 
<refsect2 id="gnome-keyring-find-items" role="function">
103
 
<title>gnome_keyring_find_items ()</title>
104
 
<indexterm zone="gnome-keyring-find-items"><primary sortas="gnome_keyring_find_items">gnome_keyring_find_items</primary></indexterm><programlisting><link linkend="gpointer">gpointer</link>            gnome_keyring_find_items            (<link linkend="GnomeKeyringItemType">GnomeKeyringItemType</link> type,
105
 
                                                         <link linkend="GnomeKeyringAttributeList">GnomeKeyringAttributeList</link> *attributes,
106
 
                                                         <link linkend="GnomeKeyringOperationGetListCallback">GnomeKeyringOperationGetListCallback</link> callback,
107
 
                                                         <link linkend="gpointer">gpointer</link> data,
108
 
                                                         <link linkend="GDestroyNotify">GDestroyNotify</link> destroy_data);</programlisting>
109
 
<para>
110
 
Searches through all keyrings for items that match the <parameter>attributes</parameter>. The matches
111
 
are for exact equality. 
112
 
</para>
113
 
<para>
114
 
A <link linkend="GList"><literal>GList</literal></link> of GnomeKeyringFound structures are passed to the <parameter>callback</parameter>. The 
115
 
list and structures are freed after the callback returns.
116
 
</para>
117
 
<para>
118
 
The user may have been prompted to unlock necessary keyrings, and user will 
119
 
have been prompted for access to the items if needed. 
120
 
</para>
121
 
<para>
122
 
For a synchronous version of this function see <link linkend="gnome-keyring-find-items-sync"><function>gnome_keyring_find_items_sync()</function></link>.</para>
123
 
<para>
124
 
</para><variablelist role="params">
125
 
<varlistentry><term><parameter>type</parameter>&#160;:</term>
126
 
<listitem><simpara> The type of items to find. 
127
 
</simpara></listitem></varlistentry>
128
 
<varlistentry><term><parameter>attributes</parameter>&#160;:</term>
129
 
<listitem><simpara> A list of attributes to search for. This cannot be an empty list.
130
 
</simpara></listitem></varlistentry>
131
 
<varlistentry><term><parameter>callback</parameter>&#160;:</term>
132
 
<listitem><simpara> A callback which will be called when the request completes or fails.
133
 
</simpara></listitem></varlistentry>
134
 
<varlistentry><term><parameter>data</parameter>&#160;:</term>
135
 
<listitem><simpara> A pointer to arbitrary data that will be passed to the <parameter>callback</parameter>.
136
 
</simpara></listitem></varlistentry>
137
 
<varlistentry><term><parameter>destroy_data</parameter>&#160;:</term>
138
 
<listitem><simpara> A function to free <parameter>data</parameter> when it's no longer needed.
139
 
</simpara></listitem></varlistentry>
140
 
<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>.
141
 
</simpara></listitem></varlistentry>
142
 
</variablelist></refsect2>
143
 
<refsect2 id="gnome-keyring-find-itemsv" role="function">
144
 
<title>gnome_keyring_find_itemsv ()</title>
145
 
<indexterm zone="gnome-keyring-find-itemsv"><primary sortas="gnome_keyring_find_itemsv">gnome_keyring_find_itemsv</primary></indexterm><programlisting><link linkend="gpointer">gpointer</link>            gnome_keyring_find_itemsv           (<link linkend="GnomeKeyringItemType">GnomeKeyringItemType</link> type,
146
 
                                                         <link linkend="GnomeKeyringOperationGetListCallback">GnomeKeyringOperationGetListCallback</link> callback,
147
 
                                                         <link linkend="gpointer">gpointer</link> data,
148
 
                                                         <link linkend="GDestroyNotify">GDestroyNotify</link> destroy_data,
149
 
                                                         ...);</programlisting>
150
 
<para>
151
 
Searches through all keyrings for items that match the specified attributes. 
152
 
The matches are for exact equality.
153
 
</para>
154
 
<para>
155
 
The variable argument list should contain a) The attribute name as a null 
156
 
terminated string, followed by b) The attribute type, either 
157
 
<link linkend="GNOME-KEYRING-ATTRIBUTE-TYPE-STRING--CAPS"><literal>GNOME_KEYRING_ATTRIBUTE_TYPE_STRING</literal></link> or <link linkend="GNOME-KEYRING-ATTRIBUTE-TYPE-UINT32--CAPS"><literal>GNOME_KEYRING_ATTRIBUTE_TYPE_UINT32</literal></link>
158
 
and then the c) attribute value, either a character string, or 32-bit 
159
 
unsigned int. The list should be terminated with a NULL. 
160
 
</para>
161
 
<para>
162
 
A <link linkend="GList"><literal>GList</literal></link> of GnomeKeyringFound structures are passed to the <parameter>callback</parameter>. The 
163
 
list and structures are freed after the callback returns.
164
 
</para>
165
 
<para>
166
 
The user may have been prompted to unlock necessary keyrings, and user will 
167
 
have been prompted for access to the items if needed. 
168
 
</para>
169
 
<para>
170
 
For a synchronous version of this function see <link linkend="gnome-keyring-find-itemsv-sync"><function>gnome_keyring_find_itemsv_sync()</function></link>.</para>
171
 
<para>
172
 
</para><variablelist role="params">
173
 
<varlistentry><term><parameter>type</parameter>&#160;:</term>
174
 
<listitem><simpara> The type of items to find. 
175
 
</simpara></listitem></varlistentry>
176
 
<varlistentry><term><parameter>callback</parameter>&#160;:</term>
177
 
<listitem><simpara> A callback which will be called when the request completes or fails.
178
 
</simpara></listitem></varlistentry>
179
 
<varlistentry><term><parameter>data</parameter>&#160;:</term>
180
 
<listitem><simpara> A pointer to arbitrary data that will be passed to the <parameter>callback</parameter>.
181
 
</simpara></listitem></varlistentry>
182
 
<varlistentry><term><parameter>destroy_data</parameter>&#160;:</term>
183
 
<listitem><simpara> A function to free <parameter>data</parameter> when it's no longer needed.
184
 
</simpara></listitem></varlistentry>
185
 
<varlistentry><term><parameter>...</parameter>&#160;:</term>
186
 
<listitem><simpara>
187
 
</simpara></listitem></varlistentry>
188
 
<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>.
189
 
</simpara></listitem></varlistentry>
190
 
</variablelist></refsect2>
191
 
<refsect2 id="gnome-keyring-find-items-sync" role="function">
192
 
<title>gnome_keyring_find_items_sync ()</title>
193
 
<indexterm zone="gnome-keyring-find-items-sync"><primary sortas="gnome_keyring_find_items_sync">gnome_keyring_find_items_sync</primary></indexterm><programlisting><link linkend="GnomeKeyringResult">GnomeKeyringResult</link>  gnome_keyring_find_items_sync       (<link linkend="GnomeKeyringItemType">GnomeKeyringItemType</link> type,
194
 
                                                         <link linkend="GnomeKeyringAttributeList">GnomeKeyringAttributeList</link> *attributes,
195
 
                                                         <link linkend="GList">GList</link> **found);</programlisting>
196
 
<para>
197
 
Searches through all keyrings for items that match the <parameter>attributes</parameter> and <parameter>type</parameter>. 
198
 
The matches are for exact equality. 
199
 
</para>
200
 
<para>
201
 
A <link linkend="GList"><literal>GList</literal></link> of GnomeKeyringFound structures is returned in <parameter>found</parameter>. The list may 
202
 
have zero items if nothing matched the criteria. The list should be freed 
203
 
using <link linkend="gnome-keyring-found-list-free"><function>gnome_keyring_found_list_free()</function></link>.
204
 
</para>
205
 
<para>
206
 
The user may have been prompted to unlock necessary keyrings, and user will 
207
 
have been prompted for access to the items if needed. 
208
 
</para>
209
 
<para>
210
 
For an asynchronous version of this function see <link linkend="gnome-keyring-find-items"><function>gnome_keyring_find_items()</function></link>.</para>
211
 
<para>
212
 
</para><variablelist role="params">
213
 
<varlistentry><term><parameter>type</parameter>&#160;:</term>
214
 
<listitem><simpara> The type of items to find. 
215
 
</simpara></listitem></varlistentry>
216
 
<varlistentry><term><parameter>attributes</parameter>&#160;:</term>
217
 
<listitem><simpara> A list of attributes to search for. This cannot be an empty list.
218
 
</simpara></listitem></varlistentry>
219
 
<varlistentry><term><parameter>found</parameter>&#160;:</term>
220
 
<listitem><simpara> The location to return a list of <link linkend="GnomeKeyringFound"><type>GnomeKeyringFound</type></link> pointers.
221
 
</simpara></listitem></varlistentry>
222
 
<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 
223
 
an error result otherwise. 
224
 
</simpara></listitem></varlistentry>
225
 
</variablelist></refsect2>
226
 
<refsect2 id="gnome-keyring-find-itemsv-sync" role="function">
227
 
<title>gnome_keyring_find_itemsv_sync ()</title>
228
 
<indexterm zone="gnome-keyring-find-itemsv-sync"><primary sortas="gnome_keyring_find_itemsv_sync">gnome_keyring_find_itemsv_sync</primary></indexterm><programlisting><link linkend="GnomeKeyringResult">GnomeKeyringResult</link>  gnome_keyring_find_itemsv_sync      (<link linkend="GnomeKeyringItemType">GnomeKeyringItemType</link> type,
229
 
                                                         <link linkend="GList">GList</link> **found,
230
 
                                                         ...);</programlisting>
231
 
<para>
232
 
Searches through all keyrings for items that match the <parameter>attributes</parameter> and <parameter>type</parameter>. 
233
 
The matches are for exact equality. 
234
 
</para>
235
 
<para>
236
 
The variable argument list should contain a) The attribute name as a null 
237
 
terminated string, followed by b) The attribute type, either 
238
 
<link linkend="GNOME-KEYRING-ATTRIBUTE-TYPE-STRING--CAPS"><literal>GNOME_KEYRING_ATTRIBUTE_TYPE_STRING</literal></link> or <link linkend="GNOME-KEYRING-ATTRIBUTE-TYPE-UINT32--CAPS"><literal>GNOME_KEYRING_ATTRIBUTE_TYPE_UINT32</literal></link>
239
 
and then the c) attribute value, either a character string, or 32-bit 
240
 
unsigned int. The list should be terminated with a NULL. 
241
 
</para>
242
 
<para>
243
 
A <link linkend="GList"><literal>GList</literal></link> of GnomeKeyringFound structures is returned in <parameter>found</parameter>. The list may 
244
 
have zero items if nothing matched the criteria. The list should be freed 
245
 
using <link linkend="gnome-keyring-found-list-free"><function>gnome_keyring_found_list_free()</function></link>.
246
 
</para>
247
 
<para>
248
 
The user may have been prompted to unlock necessary keyrings, and user will 
249
 
have been prompted for access to the items if needed. 
250
 
</para>
251
 
<para>
252
 
For an asynchronous version of this function see <link linkend="gnome-keyring-find-items"><function>gnome_keyring_find_items()</function></link>.</para>
253
 
<para>
254
 
</para><variablelist role="params">
255
 
<varlistentry><term><parameter>type</parameter>&#160;:</term>
256
 
<listitem><simpara> The type of items to find. 
257
 
</simpara></listitem></varlistentry>
258
 
<varlistentry><term><parameter>found</parameter>&#160;:</term>
259
 
<listitem><simpara> The location to return a list of <link linkend="GnomeKeyringFound"><type>GnomeKeyringFound</type></link> pointers.
260
 
</simpara></listitem></varlistentry>
261
 
<varlistentry><term><parameter>...</parameter>&#160;:</term>
262
 
<listitem><simpara>
263
 
</simpara></listitem></varlistentry>
264
 
<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 
265
 
an error result otherwise. 
266
 
</simpara></listitem></varlistentry>
267
 
</variablelist></refsect2>
268
 
 
269
 
</refsect1>
270
 
 
271
 
 
272
 
 
273
 
 
274
 
</refentry>