← Back to branch summary

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

« back to all changes in this revision

Viewing changes to docs/reference/gp11/xml/gp11-module.xml

  • Committer: Bazaar Package Importer
  • Author(s): Sebastien Bacher
  • Date: 2010-03-10 21:37:48 UTC
  • mfrom: (1.1.59 upstream)
  • Revision ID: james.westby@ubuntu.com-20100310213748-imimrnfxu32ih4t3
Tags: 2.29.92-0ubuntu1
* New upstream version:
  - Fix various problems with not storing secret value properly.
  - Return no results when a search includes a bad collection identifier.
  - Don't raise error if ssh client disconnects early.
  - Allow running in a test environment.
  - Fix error when setting default keyring to NULL.
  - Autostart gnome-keyring-daemon in LXDE as well.
  - Rework the startup again, to use a singleton crontrolled via dbus, to help
    when no process was started by pam.
  - Display password and confirm prompts when creating keyring.
  - Allow specifying CKA_ID when creating collection.
  - Give translatable label to created login keyring.
  - When no default keyring set, use login keyring.
  - Fix problem initializing socket path in rpc module.
  - Fix endless loop in reading data.
  - Potential fix or sporadic crash.
  - Solaris build fixes.
  - Updated translations.
* debian/patches/05_git_no_read_looping.patch:
  - the change is in the new version

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/reference/gp11/xml/gp11-module.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="gp11-gp11-module">
5
 
<refmeta>
6
 
<refentrytitle role="top_of_page" id="gp11-gp11-module.top_of_page">GP11Module</refentrytitle>
7
 
<manvolnum>3</manvolnum>
8
 
<refmiscinfo>GP11 Library</refmiscinfo>
9
 
</refmeta>
10
 
 
11
 
<refnamediv>
12
 
<refname>GP11Module</refname>
13
 
<refpurpose>A loaded and initialized PKCS<link linkend="11--CAPS"><type>11</type></link> module.</refpurpose>
14
 
</refnamediv>
15
 
 
16
 
<refsynopsisdiv id="gp11-gp11-module.synopsis" role="synopsis">
17
 
<title role="synopsis.title">Synopsis</title>
18
 
<anchor id="GP11Module"/>
19
 
<synopsis>
20
 
                    <link linkend="GP11Module-struct">GP11Module</link>;
21
 
<link linkend="GP11Module">GP11Module</link>*         <link linkend="gp11-module-new">gp11_module_new</link>                     (<link linkend="CK-FUNCTION-LIST-PTR--CAPS">CK_FUNCTION_LIST_PTR</link> funcs);
22
 
<link linkend="GP11Module">GP11Module</link>*         <link linkend="gp11-module-initialize">gp11_module_initialize</link>              (const <link linkend="gchar">gchar</link> *path,
23
 
                                                         <link linkend="gpointer">gpointer</link> reserved,
24
 
                                                         <link linkend="GError">GError</link> **err);
25
 
<link linkend="gboolean">gboolean</link>            <link linkend="gp11-module-equal">gp11_module_equal</link>                   (<link linkend="gconstpointer">gconstpointer</link> module1,
26
 
                                                         <link linkend="gconstpointer">gconstpointer</link> module2);
27
 
<link linkend="guint">guint</link>               <link linkend="gp11-module-hash">gp11_module_hash</link>                    (<link linkend="gconstpointer">gconstpointer</link> module);
28
 
const <link linkend="gchar">gchar</link>*        <link linkend="gp11-module-get-path">gp11_module_get_path</link>                (<link linkend="GP11Module">GP11Module</link> *self);
29
 
<link linkend="CK-FUNCTION-LIST-PTR--CAPS">CK_FUNCTION_LIST_PTR</link>  <link linkend="gp11-module-get-functions">gp11_module_get_functions</link>         (<link linkend="GP11Module">GP11Module</link> *self);
30
 
<link linkend="GP11ModuleInfo">GP11ModuleInfo</link>*     <link linkend="gp11-module-get-info">gp11_module_get_info</link>                (<link linkend="GP11Module">GP11Module</link> *self);
31
 
<link linkend="GList">GList</link>*              <link linkend="gp11-module-get-slots">gp11_module_get_slots</link>               (<link linkend="GP11Module">GP11Module</link> *self,
32
 
                                                         <link linkend="gboolean">gboolean</link> token_present);
33
 
<link linkend="gboolean">gboolean</link>            <link linkend="gp11-module-get-pool-sessions">gp11_module_get_pool_sessions</link>       (<link linkend="GP11Module">GP11Module</link> *self);
34
 
<link linkend="void">void</link>                <link linkend="gp11-module-set-pool-sessions">gp11_module_set_pool_sessions</link>       (<link linkend="GP11Module">GP11Module</link> *self,
35
 
                                                         <link linkend="gboolean">gboolean</link> pool);
36
 
<link linkend="gint">gint</link>                <link linkend="gp11-module-get-auto-authenticate">gp11_module_get_auto_authenticate</link>   (<link linkend="GP11Module">GP11Module</link> *self);
37
 
<link linkend="void">void</link>                <link linkend="gp11-module-set-auto-authenticate">gp11_module_set_auto_authenticate</link>   (<link linkend="GP11Module">GP11Module</link> *self,
38
 
                                                         <link linkend="gint">gint</link> auto_authenticate);
39
 
<link linkend="gboolean">gboolean</link>            <link linkend="gp11-module-enumerate-objects">gp11_module_enumerate_objects</link>       (<link linkend="GP11Module">GP11Module</link> *self,
40
 
                                                         <link linkend="GP11ObjectForeachFunc">GP11ObjectForeachFunc</link> func,
41
 
                                                         <link linkend="gpointer">gpointer</link> user_data,
42
 
                                                         ...);
43
 
<link linkend="gboolean">gboolean</link>            (<link linkend="GP11ObjectForeachFunc">*GP11ObjectForeachFunc</link>)            (<link linkend="GP11Object">GP11Object</link> *object,
44
 
                                                         <link linkend="gpointer">gpointer</link> user_data);
45
 
                    <link linkend="GP11ModuleInfo">GP11ModuleInfo</link>;
46
 
<link linkend="void">void</link>                <link linkend="gp11-module-info-free">gp11_module_info_free</link>               (<link linkend="GP11ModuleInfo">GP11ModuleInfo</link> *module_info);
47
 
</synopsis>
48
 
</refsynopsisdiv>
49
 
 
50
 
<refsect1 id="gp11-gp11-module.object-hierarchy" role="object_hierarchy">
51
 
<title role="object_hierarchy.title">Object Hierarchy</title>
52
 
<synopsis>
53
 
  <link linkend="GObject">GObject</link>
54
 
   +----GP11Module
55
 
</synopsis>
56
 
</refsect1>
57
 
 
58
 
 
59
 
 
60
 
 
61
 
 
62
 
<refsect1 id="gp11-gp11-module.properties" role="properties">
63
 
<title role="properties.title">Properties</title>
64
 
<synopsis>
65
 
  &quot;<link linkend="GP11Module--auto-authenticate">auto-authenticate</link>&quot;        <link linkend="gint">gint</link>                  : Read / Write
66
 
  &quot;<link linkend="GP11Module--functions">functions</link>&quot;                <link linkend="gpointer">gpointer</link>              : Read / Write / Construct Only
67
 
  &quot;<link linkend="GP11Module--path">path</link>&quot;                     <link linkend="gchar">gchar</link>*                : Read / Write / Construct Only
68
 
  &quot;<link linkend="GP11Module--pool-sessions">pool-sessions</link>&quot;            <link linkend="gboolean">gboolean</link>              : Read / Write
69
 
</synopsis>
70
 
</refsect1>
71
 
 
72
 
<refsect1 id="gp11-gp11-module.signals" role="signal_proto">
73
 
<title role="signal_proto.title">Signals</title>
74
 
<synopsis>
75
 
  &quot;<link linkend="GP11Module-authenticate-object">authenticate-object</link>&quot;                            : Run Last
76
 
  &quot;<link linkend="GP11Module-authenticate-slot">authenticate-slot</link>&quot;                              : Run Last
77
 
</synopsis>
78
 
</refsect1>
79
 
 
80
 
 
81
 
<refsect1 id="gp11-gp11-module.description" role="desc">
82
 
<title role="desc.title">Description</title>
83
 
<para>
84
 
A GP11Module object holds a loaded PKCS<link linkend="11--CAPS"><type>11</type></link> module. A PKCS<link linkend="11--CAPS"><type>11</type></link> module is a shared library. 
85
 
</para>
86
 
<para>
87
 
You can load and initialize a PKCS<link linkend="11--CAPS"><type>11</type></link> module with the <link linkend="gp11-module-initialize"><function>gp11_module_initialize()</function></link> call. If you already
88
 
have a loaded and initialized module that you'd like to use with the various GP11 functions, then 
89
 
you can use <link linkend="gp11-module-new"><function>gp11_module_new()</function></link>.</para>
90
 
<para>
91
 
</para>
92
 
</refsect1>
93
 
 
94
 
<refsect1 id="gp11-gp11-module.details" role="details">
95
 
<title role="details.title">Details</title>
96
 
<refsect2 id="GP11Module-struct" role="struct">
97
 
<title>GP11Module</title>
98
 
<indexterm zone="GP11Module-struct"><primary sortas="GP11Module">GP11Module</primary></indexterm><programlisting>typedef struct _GP11Module GP11Module;</programlisting>
99
 
<para>
100
 
Holds a loaded and initialized PKCS<link linkend="11--CAPS"><type>11</type></link> module.</para>
101
 
<para>
102
 
</para></refsect2>
103
 
<refsect2 id="gp11-module-new" role="function">
104
 
<title>gp11_module_new ()</title>
105
 
<indexterm zone="gp11-module-new"><primary sortas="gp11_module_new">gp11_module_new</primary></indexterm><programlisting><link linkend="GP11Module">GP11Module</link>*         gp11_module_new                     (<link linkend="CK-FUNCTION-LIST-PTR--CAPS">CK_FUNCTION_LIST_PTR</link> funcs);</programlisting>
106
 
<para>
107
 
Create a GP11Module representing a PKCS<link linkend="11--CAPS"><type>11</type></link> module. It is assumed that 
108
 
this the module is already initialized. In addition it will not be 
109
 
finalized when complete.</para>
110
 
<para>
111
 
</para><variablelist role="params">
112
 
<varlistentry><term><parameter>funcs</parameter>&#160;:</term>
113
 
<listitem><simpara> Initialized PKCS<link linkend="11--CAPS"><type>11</type></link> function list pointer
114
 
</simpara></listitem></varlistentry>
115
 
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> The new PKCS<link linkend="11--CAPS"><type>11</type></link> module.
116
 
</simpara></listitem></varlistentry>
117
 
</variablelist></refsect2>
118
 
<refsect2 id="gp11-module-initialize" role="function">
119
 
<title>gp11_module_initialize ()</title>
120
 
<indexterm zone="gp11-module-initialize"><primary sortas="gp11_module_initialize">gp11_module_initialize</primary></indexterm><programlisting><link linkend="GP11Module">GP11Module</link>*         gp11_module_initialize              (const <link linkend="gchar">gchar</link> *path,
121
 
                                                         <link linkend="gpointer">gpointer</link> reserved,
122
 
                                                         <link linkend="GError">GError</link> **err);</programlisting>
123
 
<para>
124
 
Load and initialize a PKCS<link linkend="11--CAPS"><type>11</type></link> module represented by a GP11Module object.</para>
125
 
<para>
126
 
</para><variablelist role="params">
127
 
<varlistentry><term><parameter>path</parameter>&#160;:</term>
128
 
<listitem><simpara> The file system path to the PKCS<link linkend="11--CAPS"><type>11</type></link> module to load.
129
 
</simpara></listitem></varlistentry>
130
 
<varlistentry><term><parameter>reserved</parameter>&#160;:</term>
131
 
<listitem><simpara> Extra arguments for the PKCS<link linkend="11--CAPS"><type>11</type></link> module, should usually be NULL.
132
 
</simpara></listitem></varlistentry>
133
 
<varlistentry><term><parameter>err</parameter>&#160;:</term>
134
 
<listitem><simpara> A location to store an error resulting from a failed load.
135
 
</simpara></listitem></varlistentry>
136
 
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> The loaded PKCS<link linkend="11--CAPS"><type>11</type></link> module or NULL if failed.
137
 
</simpara></listitem></varlistentry>
138
 
</variablelist></refsect2>
139
 
<refsect2 id="gp11-module-equal" role="function">
140
 
<title>gp11_module_equal ()</title>
141
 
<indexterm zone="gp11-module-equal"><primary sortas="gp11_module_equal">gp11_module_equal</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            gp11_module_equal                   (<link linkend="gconstpointer">gconstpointer</link> module1,
142
 
                                                         <link linkend="gconstpointer">gconstpointer</link> module2);</programlisting>
143
 
<para>
144
 
Checks equality of two modules. Two GP11Module objects can point to the same 
145
 
underlying PKCS<link linkend="11--CAPS"><type>11</type></link> module.</para>
146
 
<para>
147
 
</para><variablelist role="params">
148
 
<varlistentry><term><parameter>module1</parameter>&#160;:</term>
149
 
<listitem><simpara> A pointer to the first GP11Module
150
 
</simpara></listitem></varlistentry>
151
 
<varlistentry><term><parameter>module2</parameter>&#160;:</term>
152
 
<listitem><simpara> A pointer to the second GP11Module
153
 
</simpara></listitem></varlistentry>
154
 
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> TRUE if module1 and module2 are equal. FALSE if either is not a GP11Module.
155
 
</simpara></listitem></varlistentry>
156
 
</variablelist></refsect2>
157
 
<refsect2 id="gp11-module-hash" role="function">
158
 
<title>gp11_module_hash ()</title>
159
 
<indexterm zone="gp11-module-hash"><primary sortas="gp11_module_hash">gp11_module_hash</primary></indexterm><programlisting><link linkend="guint">guint</link>               gp11_module_hash                    (<link linkend="gconstpointer">gconstpointer</link> module);</programlisting>
160
 
<para>
161
 
Create a hash value for the GP11Module. 
162
 
</para>
163
 
<para>
164
 
This function is intended for easily hashing a GP11Module to add to 
165
 
a GHashTable or similar data structure.</para>
166
 
<para>
167
 
</para><variablelist role="params">
168
 
<varlistentry><term><parameter>module</parameter>&#160;:</term>
169
 
<listitem><simpara> A pointer to a GP11Module
170
 
</simpara></listitem></varlistentry>
171
 
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> An integer that can be used as a hash value, or 0 if invalid.
172
 
</simpara></listitem></varlistentry>
173
 
</variablelist></refsect2>
174
 
<refsect2 id="gp11-module-get-path" role="function">
175
 
<title>gp11_module_get_path ()</title>
176
 
<indexterm zone="gp11-module-get-path"><primary sortas="gp11_module_get_path">gp11_module_get_path</primary></indexterm><programlisting>const <link linkend="gchar">gchar</link>*        gp11_module_get_path                (<link linkend="GP11Module">GP11Module</link> *self);</programlisting>
177
 
<para>
178
 
Get the file path of this module. This may not be an absolute path, and 
179
 
usually reflects the path passed to <link linkend="gp11-module-initialize"><function>gp11_module_initialize()</function></link>.</para>
180
 
<para>
181
 
</para><variablelist role="params">
182
 
<varlistentry><term><parameter>self</parameter>&#160;:</term>
183
 
<listitem><simpara> The module for which to get the path.
184
 
</simpara></listitem></varlistentry>
185
 
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> The path, do not modify or free this value. 
186
 
</simpara></listitem></varlistentry>
187
 
</variablelist></refsect2>
188
 
<refsect2 id="gp11-module-get-functions" role="function">
189
 
<title>gp11_module_get_functions ()</title>
190
 
<indexterm zone="gp11-module-get-functions"><primary sortas="gp11_module_get_functions">gp11_module_get_functions</primary></indexterm><programlisting><link linkend="CK-FUNCTION-LIST-PTR--CAPS">CK_FUNCTION_LIST_PTR</link>  gp11_module_get_functions         (<link linkend="GP11Module">GP11Module</link> *self);</programlisting>
191
 
<para>
192
 
Get the PKCS<link linkend="11--CAPS"><type>11</type></link> function list for the module.</para>
193
 
<para>
194
 
</para><variablelist role="params">
195
 
<varlistentry><term><parameter>self</parameter>&#160;:</term>
196
 
<listitem><simpara> The module for which to get the function list.
197
 
</simpara></listitem></varlistentry>
198
 
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> The function list, do not modify this structure. 
199
 
</simpara></listitem></varlistentry>
200
 
</variablelist></refsect2>
201
 
<refsect2 id="gp11-module-get-info" role="function">
202
 
<title>gp11_module_get_info ()</title>
203
 
<indexterm zone="gp11-module-get-info"><primary sortas="gp11_module_get_info">gp11_module_get_info</primary></indexterm><programlisting><link linkend="GP11ModuleInfo">GP11ModuleInfo</link>*     gp11_module_get_info                (<link linkend="GP11Module">GP11Module</link> *self);</programlisting>
204
 
<para>
205
 
Get the info about a PKCS<link linkend="11--CAPS"><type>11</type></link> module.</para>
206
 
<para>
207
 
</para><variablelist role="params">
208
 
<varlistentry><term><parameter>self</parameter>&#160;:</term>
209
 
<listitem><simpara> The module to get info for.
210
 
</simpara></listitem></varlistentry>
211
 
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> The module info. Release this with <link linkend="gp11-module-info-free"><function>gp11_module_info_free()</function></link>.
212
 
</simpara></listitem></varlistentry>
213
 
</variablelist></refsect2>
214
 
<refsect2 id="gp11-module-get-slots" role="function">
215
 
<title>gp11_module_get_slots ()</title>
216
 
<indexterm zone="gp11-module-get-slots"><primary sortas="gp11_module_get_slots">gp11_module_get_slots</primary></indexterm><programlisting><link linkend="GList">GList</link>*              gp11_module_get_slots               (<link linkend="GP11Module">GP11Module</link> *self,
217
 
                                                         <link linkend="gboolean">gboolean</link> token_present);</programlisting>
218
 
<para>
219
 
Get the GP11Slot objects for a given module.</para>
220
 
<para>
221
 
</para><variablelist role="params">
222
 
<varlistentry><term><parameter>self</parameter>&#160;:</term>
223
 
<listitem><simpara> The module for which to get the slots.
224
 
</simpara></listitem></varlistentry>
225
 
<varlistentry><term><parameter>token_present</parameter>&#160;:</term>
226
 
<listitem><simpara> Whether to limit only to slots with a token present.
227
 
</simpara></listitem></varlistentry>
228
 
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> The possibly empty list of slots. Release this with <link linkend="gp11-list-unref-free"><function>gp11_list_unref_free()</function></link>.
229
 
</simpara></listitem></varlistentry>
230
 
</variablelist></refsect2>
231
 
<refsect2 id="gp11-module-get-pool-sessions" role="function">
232
 
<title>gp11_module_get_pool_sessions ()</title>
233
 
<indexterm zone="gp11-module-get-pool-sessions"><primary sortas="gp11_module_get_pool_sessions">gp11_module_get_pool_sessions</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            gp11_module_get_pool_sessions       (<link linkend="GP11Module">GP11Module</link> *self);</programlisting>
234
 
<para>
235
 
Get the reuse sessions setting. When this is set, sessions
236
 
will be pooled and reused if their flags match when 
237
 
<link linkend="gp11-slot-open-session"><function>gp11_slot_open_session()</function></link> is called.</para>
238
 
<para>
239
 
</para><variablelist role="params">
240
 
<varlistentry><term><parameter>self</parameter>&#160;:</term>
241
 
<listitem><simpara> The module to get setting from.
242
 
</simpara></listitem></varlistentry>
243
 
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> Whether reusing sessions or not.
244
 
</simpara></listitem></varlistentry>
245
 
</variablelist></refsect2>
246
 
<refsect2 id="gp11-module-set-pool-sessions" role="function">
247
 
<title>gp11_module_set_pool_sessions ()</title>
248
 
<indexterm zone="gp11-module-set-pool-sessions"><primary sortas="gp11_module_set_pool_sessions">gp11_module_set_pool_sessions</primary></indexterm><programlisting><link linkend="void">void</link>                gp11_module_set_pool_sessions       (<link linkend="GP11Module">GP11Module</link> *self,
249
 
                                                         <link linkend="gboolean">gboolean</link> pool);</programlisting>
250
 
<para>
251
 
When this is set, sessions will be pooled and reused
252
 
if their flags match when <link linkend="gp11-slot-open-session"><function>gp11_slot_open_session()</function></link> is called.</para>
253
 
<para>
254
 
</para><variablelist role="params">
255
 
<varlistentry><term><parameter>self</parameter>&#160;:</term>
256
 
<listitem><simpara> The module to set the setting on.
257
 
</simpara></listitem></varlistentry>
258
 
<varlistentry><term><parameter>pool</parameter>&#160;:</term>
259
 
<listitem><simpara> Whether to reuse sessions or not.
260
 
</simpara></listitem></varlistentry>
261
 
</variablelist></refsect2>
262
 
<refsect2 id="gp11-module-get-auto-authenticate" role="function">
263
 
<title>gp11_module_get_auto_authenticate ()</title>
264
 
<indexterm zone="gp11-module-get-auto-authenticate"><primary sortas="gp11_module_get_auto_authenticate">gp11_module_get_auto_authenticate</primary></indexterm><programlisting><link linkend="gint">gint</link>                gp11_module_get_auto_authenticate   (<link linkend="GP11Module">GP11Module</link> *self);</programlisting>
265
 
<para>
266
 
Get the auto login setting. When this is set, this slot 
267
 
will emit the 'authenticate-slot' signal when a session
268
 
requires authentication, and the 'authenticate-object'
269
 
signal when an object requires authintication.</para>
270
 
<para>
271
 
</para><variablelist role="params">
272
 
<varlistentry><term><parameter>self</parameter>&#160;:</term>
273
 
<listitem><simpara> The module to get setting from.
274
 
</simpara></listitem></varlistentry>
275
 
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> Whether auto login or not.
276
 
</simpara></listitem></varlistentry>
277
 
</variablelist></refsect2>
278
 
<refsect2 id="gp11-module-set-auto-authenticate" role="function">
279
 
<title>gp11_module_set_auto_authenticate ()</title>
280
 
<indexterm zone="gp11-module-set-auto-authenticate"><primary sortas="gp11_module_set_auto_authenticate">gp11_module_set_auto_authenticate</primary></indexterm><programlisting><link linkend="void">void</link>                gp11_module_set_auto_authenticate   (<link linkend="GP11Module">GP11Module</link> *self,
281
 
                                                         <link linkend="gint">gint</link> auto_authenticate);</programlisting>
282
 
<para>
283
 
When this is set, this slot 
284
 
will emit the 'authenticate-slot' signal when a session
285
 
requires authentication, and the 'authenticate-object'
286
 
signal when an object requires authintication.</para>
287
 
<para>
288
 
</para><variablelist role="params">
289
 
<varlistentry><term><parameter>self</parameter>&#160;:</term>
290
 
<listitem><simpara> The module to set the setting on.
291
 
</simpara></listitem></varlistentry>
292
 
<varlistentry><term><parameter>auto_authenticate</parameter>&#160;:</term>
293
 
<listitem><simpara> Whether auto login or not.
294
 
</simpara></listitem></varlistentry>
295
 
</variablelist></refsect2>
296
 
<refsect2 id="gp11-module-enumerate-objects" role="function">
297
 
<title>gp11_module_enumerate_objects ()</title>
298
 
<indexterm zone="gp11-module-enumerate-objects"><primary sortas="gp11_module_enumerate_objects">gp11_module_enumerate_objects</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            gp11_module_enumerate_objects       (<link linkend="GP11Module">GP11Module</link> *self,
299
 
                                                         <link linkend="GP11ObjectForeachFunc">GP11ObjectForeachFunc</link> func,
300
 
                                                         <link linkend="gpointer">gpointer</link> user_data,
301
 
                                                         ...);</programlisting>
302
 
<para>
303
 
Call a function for every matching object on the module. This call may 
304
 
block for an indefinite period.
305
 
</para>
306
 
<para>
307
 
<para>The variable argument list should contain:
308
 
        <variablelist>
309
 
        <varlistentry>
310
 
                        <term>a)</term>
311
 
                        <listitem><para>The gulong attribute type (ie: CKA_LABEL). </para></listitem>
312
 
                </varlistentry>
313
 
                <varlistentry>
314
 
                        <term>b)</term>
315
 
                        <listitem><para>The attribute data type (one of GP11_BOOLEAN, GP11_ULONG, 
316
 
                                GP11_STRING, GP11_DATE) orthe raw attribute value length.</para></listitem>
317
 
                </varlistentry>
318
 
                <varlistentry>
319
 
                        <term>c)</term>
320
 
                        <listitem><para>The attribute value, either a gboolean, gulong, gchar*, GDate* or 
321
 
                                a pointer to a raw attribute value.</para></listitem>
322
 
                </varlistentry>
323
 
        </variablelist>
324
 
The variable argument list should be terminated with GP11_INVALID.</para>
325
 
</para>
326
 
<para>
327
 
This function will open a session per slot. It's recommended that you 
328
 
set the 'reuse-sessions' property on each slot if you'll be calling 
329
 
it a lot.
330
 
</para>
331
 
<para>
332
 
You can access the session in which the object was found, by using the 
333
 
<link linkend="gp11-object-get-session"><function>gp11_object_get_session()</function></link> function on the resulting objects.
334
 
</para>
335
 
<para>
336
 
This function skips tokens that are not initialize, and makes a best effort to 
337
 
find objects on valid tokens. 
338
 
</para>
339
 
<para>
340
 
The function can return FALSE to stop the enumeration.</para>
341
 
<para>
342
 
</para><variablelist role="params">
343
 
<varlistentry><term><parameter>self</parameter>&#160;:</term>
344
 
<listitem><simpara> The module to enumerate objects.
345
 
</simpara></listitem></varlistentry>
346
 
<varlistentry><term><parameter>func</parameter>&#160;:</term>
347
 
<listitem><simpara> Function to call for each object.
348
 
</simpara></listitem></varlistentry>
349
 
<varlistentry><term><parameter>user_data</parameter>&#160;:</term>
350
 
<listitem><simpara> Data to pass to the function.
351
 
</simpara></listitem></varlistentry>
352
 
<varlistentry><term><parameter>...</parameter>&#160;:</term>
353
 
<listitem><simpara> The arguments must be triples of: attribute type, data type, value.
354
 
</simpara></listitem></varlistentry>
355
 
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> If FALSE then an error prevented all matching objects from being enumerated.
356
 
</simpara></listitem></varlistentry>
357
 
</variablelist></refsect2>
358
 
<refsect2 id="GP11ObjectForeachFunc" role="function">
359
 
<title>GP11ObjectForeachFunc ()</title>
360
 
<indexterm zone="GP11ObjectForeachFunc"><primary sortas="GP11ObjectForeachFunc">GP11ObjectForeachFunc</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            (*GP11ObjectForeachFunc)            (<link linkend="GP11Object">GP11Object</link> *object,
361
 
                                                         <link linkend="gpointer">gpointer</link> user_data);</programlisting>
362
 
<para>
363
 
This function is passed to <link linkend="gp11-module-enumerate-objects"><function>gp11_module_enumerate_objects()</function></link> or a similar function.
364
 
It is called once for each object matched. 
365
 
</para>
366
 
<para>
367
 
The GP11Session through which the object is accessible can be retrieved by calling
368
 
<link linkend="gp11-object-get-session"><function>gp11_object_get_session()</function></link> on object.</para>
369
 
<para>
370
 
</para><variablelist role="params">
371
 
<varlistentry><term><parameter>object</parameter>&#160;:</term>
372
 
<listitem><simpara> The enumerated object.
373
 
</simpara></listitem></varlistentry>
374
 
<varlistentry><term><parameter>user_data</parameter>&#160;:</term>
375
 
<listitem><simpara> Data passed to enumerate function.
376
 
</simpara></listitem></varlistentry>
377
 
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> TRUE to continue enumerating, FALSE to stop.
378
 
</simpara></listitem></varlistentry>
379
 
</variablelist></refsect2>
380
 
<refsect2 id="GP11ModuleInfo" role="struct">
381
 
<title>GP11ModuleInfo</title>
382
 
<indexterm zone="GP11ModuleInfo"><primary sortas="GP11ModuleInfo">GP11ModuleInfo</primary></indexterm><programlisting>typedef struct {
383
 
        guint8 pkcs11_version_major;
384
 
        guint8 pkcs11_version_minor;
385
 
        
386
 
        gchar *manufacturer_id;
387
 
        gulong flags;
388
 
        
389
 
        gchar *library_description;
390
 
        guint8 library_version_major;
391
 
        guint8 library_version_minor;
392
 
} GP11ModuleInfo;
393
 
</programlisting>
394
 
<para>
395
 
Holds information about the PKCS&num;11 module. 
396
 
</para>
397
 
<para>
398
 
This structure corresponds to CK_MODULE_INFO in the PKCS<link linkend="11--CAPS"><type>11</type></link> standard. The 
399
 
strings are NULL terminated for easier use. 
400
 
</para>
401
 
<para>
402
 
Use <link linkend="gp11-module-info-free"><function>gp11_module_info_free()</function></link> to release this structure when done with it.</para>
403
 
<para>
404
 
</para><variablelist role="struct">
405
 
<varlistentry>
406
 
<term><link linkend="guint8">guint8</link>&#160;<structfield>pkcs11_version_major</structfield>;</term>
407
 
<listitem><simpara> The major version of the module.
408
 
</simpara></listitem>
409
 
</varlistentry>
410
 
<varlistentry>
411
 
<term><link linkend="guint8">guint8</link>&#160;<structfield>pkcs11_version_minor</structfield>;</term>
412
 
<listitem><simpara> The minor version of the module.
413
 
</simpara></listitem>
414
 
</varlistentry>
415
 
<varlistentry>
416
 
<term><link linkend="gchar">gchar</link>&#160;*<structfield>manufacturer_id</structfield>;</term>
417
 
<listitem><simpara> The module manufacturer.
418
 
</simpara></listitem>
419
 
</varlistentry>
420
 
<varlistentry>
421
 
<term><link linkend="gulong">gulong</link>&#160;<structfield>flags</structfield>;</term>
422
 
<listitem><simpara> The module PKCS&num;11 flags.
423
 
</simpara></listitem>
424
 
</varlistentry>
425
 
<varlistentry>
426
 
<term><link linkend="gchar">gchar</link>&#160;*<structfield>library_description</structfield>;</term>
427
 
<listitem><simpara> The module description.
428
 
</simpara></listitem>
429
 
</varlistentry>
430
 
<varlistentry>
431
 
<term><link linkend="guint8">guint8</link>&#160;<structfield>library_version_major</structfield>;</term>
432
 
<listitem><simpara> The major version of the library.
433
 
</simpara></listitem>
434
 
</varlistentry>
435
 
<varlistentry>
436
 
<term><link linkend="guint8">guint8</link>&#160;<structfield>library_version_minor</structfield>;</term>
437
 
<listitem><simpara> The minor version of the library.
438
 
</simpara></listitem>
439
 
</varlistentry>
440
 
</variablelist></refsect2>
441
 
<refsect2 id="gp11-module-info-free" role="function">
442
 
<title>gp11_module_info_free ()</title>
443
 
<indexterm zone="gp11-module-info-free"><primary sortas="gp11_module_info_free">gp11_module_info_free</primary></indexterm><programlisting><link linkend="void">void</link>                gp11_module_info_free               (<link linkend="GP11ModuleInfo">GP11ModuleInfo</link> *module_info);</programlisting>
444
 
<para>
445
 
Free a GP11ModuleInfo structure.</para>
446
 
<para>
447
 
</para><variablelist role="params">
448
 
<varlistentry><term><parameter>module_info</parameter>&#160;:</term>
449
 
<listitem><simpara> The module info to free, or NULL.
450
 
</simpara></listitem></varlistentry>
451
 
</variablelist></refsect2>
452
 
 
453
 
</refsect1>
454
 
<refsect1 id="gp11-gp11-module.property-details" role="property_details">
455
 
<title role="property_details.title">Property Details</title>
456
 
<refsect2 id="GP11Module--auto-authenticate" role="property"><title>The <literal>&quot;auto-authenticate&quot;</literal> property</title>
457
 
<indexterm zone="GP11Module--auto-authenticate"><primary sortas="GP11Module:auto-authenticate">GP11Module:auto-authenticate</primary></indexterm><programlisting>  &quot;auto-authenticate&quot;        <link linkend="gint">gint</link>                  : Read / Write</programlisting>
458
 
<para>
459
 
Whether or not to automatically authenticate token objects that need
460
 
a C_Login call before they can be used.
461
 
</para>
462
 
<para>
463
 
The <link linkend="GP11Module-authenticate-object"><type>"authenticate-object"</type></link> signal will be fired when an
464
 
object needs to be authenticated.</para>
465
 
<para>
466
 
</para><para>Allowed values: &gt;= 0</para>
467
 
<para>Default value: 0</para>
468
 
</refsect2>
469
 
<refsect2 id="GP11Module--functions" role="property"><title>The <literal>&quot;functions&quot;</literal> property</title>
470
 
<indexterm zone="GP11Module--functions"><primary sortas="GP11Module:functions">GP11Module:functions</primary></indexterm><programlisting>  &quot;functions&quot;                <link linkend="gpointer">gpointer</link>              : Read / Write / Construct Only</programlisting>
471
 
<para>
472
 
The raw PKCS&num;11 function list for the module.
473
 
</para>
474
 
<para>
475
 
This points to a CK_FUNCTION_LIST structure.</para>
476
 
<para>
477
 
</para></refsect2>
478
 
<refsect2 id="GP11Module--path" role="property"><title>The <literal>&quot;path&quot;</literal> property</title>
479
 
<indexterm zone="GP11Module--path"><primary sortas="GP11Module:path">GP11Module:path</primary></indexterm><programlisting>  &quot;path&quot;                     <link linkend="gchar">gchar</link>*                : Read / Write / Construct Only</programlisting>
480
 
<para>
481
 
The PKCS&num;11 module file path. 
482
 
</para>
483
 
<para>
484
 
This may be set to NULL if this object was created from an already
485
 
initialized module via the <link linkend="gp11-module-new"><function>gp11_module_new()</function></link> function.</para>
486
 
<para>
487
 
</para><para>Default value: NULL</para>
488
 
</refsect2>
489
 
<refsect2 id="GP11Module--pool-sessions" role="property"><title>The <literal>&quot;pool-sessions&quot;</literal> property</title>
490
 
<indexterm zone="GP11Module--pool-sessions"><primary sortas="GP11Module:pool-sessions">GP11Module:pool-sessions</primary></indexterm><programlisting>  &quot;pool-sessions&quot;            <link linkend="gboolean">gboolean</link>              : Read / Write</programlisting>
491
 
<para>
492
 
Whether or not to pool PKCS&num;11 sessions. When this is set, sessions
493
 
will be pooled and reused if their flags match when <link linkend="gp11-slot-open-session"><function>gp11_slot_open_session()</function></link> 
494
 
is called.</para>
495
 
<para>
496
 
</para><para>Default value: FALSE</para>
497
 
</refsect2>
498
 
 
499
 
</refsect1>
500
 
 
501
 
<refsect1 id="gp11-gp11-module.signal-details" role="signals">
502
 
<title role="signals.title">Signal Details</title>
503
 
<refsect2 id="GP11Module-authenticate-object" role="signal"><title>The <literal>&quot;authenticate-object&quot;</literal> signal</title>
504
 
<indexterm zone="GP11Module-authenticate-object"><primary sortas="GP11Module::authenticate-object">GP11Module::authenticate-object</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            user_function                      (<link linkend="GP11Module">GP11Module</link> *module,
505
 
                                                        <link linkend="GP11Object">GP11Object</link> *object,
506
 
                                                        <link linkend="gchar">gchar</link>      *label,
507
 
                                                        <link linkend="gpointer">gpointer</link>    password,
508
 
                                                        <link linkend="gpointer">gpointer</link>    user_data)      : Run Last</programlisting>
509
 
<para>
510
 
This signal is emitted when a password is needed to authenticate a PKCS&num;11
511
 
object like a key. If the module prompts for passwords itself, then this signal will
512
 
not be emitted.</para>
513
 
<para>
514
 
</para><variablelist role="params">
515
 
<varlistentry><term><parameter>module</parameter>&#160;:</term>
516
 
<listitem><simpara> The module.
517
 
</simpara></listitem></varlistentry>
518
 
<varlistentry><term><parameter>object</parameter>&#160;:</term>
519
 
<listitem><simpara> The object to be authenticated.
520
 
</simpara></listitem></varlistentry>
521
 
<varlistentry><term><parameter>label</parameter>&#160;:</term>
522
 
<listitem><simpara> A displayable label which describes the object.
523
 
</simpara></listitem></varlistentry>
524
 
<varlistentry><term><parameter>password</parameter>&#160;:</term>
525
 
<listitem><simpara> A gchar** where a password should be returned.
526
 
</simpara></listitem></varlistentry>
527
 
<varlistentry><term><parameter>user_data</parameter>&#160;:</term>
528
 
<listitem><simpara>user data set when the signal handler was connected.</simpara></listitem></varlistentry>
529
 
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> FALSE if the user cancelled, TRUE if we should proceed.
530
 
</simpara></listitem></varlistentry>
531
 
</variablelist></refsect2><refsect2 id="GP11Module-authenticate-slot" role="signal"><title>The <literal>&quot;authenticate-slot&quot;</literal> signal</title>
532
 
<indexterm zone="GP11Module-authenticate-slot"><primary sortas="GP11Module::authenticate-slot">GP11Module::authenticate-slot</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            user_function                      (<link linkend="GP11Module">GP11Module</link> *module,
533
 
                                                        <link linkend="GP11Slot">GP11Slot</link>   *slot,
534
 
                                                        <link linkend="gchar">gchar</link>      *string,
535
 
                                                        <link linkend="gpointer">gpointer</link>    password,
536
 
                                                        <link linkend="gpointer">gpointer</link>    user_data)      : Run Last</programlisting>
537
 
<para>
538
 
This signal is emitted when a password is needed to authenticate a PKCS&num;11 
539
 
slot. If the module prompts for passwords itself, then this signal will 
540
 
not be emitted.</para>
541
 
<para>
542
 
</para><variablelist role="params">
543
 
<varlistentry><term><parameter>module</parameter>&#160;:</term>
544
 
<listitem><simpara> The module
545
 
</simpara></listitem></varlistentry>
546
 
<varlistentry><term><parameter>slot</parameter>&#160;:</term>
547
 
<listitem><simpara> The slot to be authenticated.
548
 
</simpara></listitem></varlistentry>
549
 
<varlistentry><term><parameter>string</parameter>&#160;:</term>
550
 
<listitem><simpara> A displayable label which describes the object.
551
 
</simpara></listitem></varlistentry>
552
 
<varlistentry><term><parameter>password</parameter>&#160;:</term>
553
 
<listitem><simpara> A gchar** where a password should be returned. 
554
 
</simpara></listitem></varlistentry>
555
 
<varlistentry><term><parameter>user_data</parameter>&#160;:</term>
556
 
<listitem><simpara>user data set when the signal handler was connected.</simpara></listitem></varlistentry>
557
 
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> FALSE if the user cancelled, TRUE if we should proceed.
558
 
</simpara></listitem></varlistentry>
559
 
</variablelist></refsect2>
560
 
</refsect1>
561
 
 
562
 
 
563
 
 
564
 
</refentry>