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-slot">
6
<refentrytitle role="top_of_page" id="gp11-gp11-slot.top_of_page">GP11Slot</refentrytitle>
7
<manvolnum>3</manvolnum>
8
<refmiscinfo>GP11 Library</refmiscinfo>
12
<refname>GP11Slot</refname>
13
<refpurpose>Represents a PKCS11 slot that can contain a token.</refpurpose>
16
<refsynopsisdiv id="gp11-gp11-slot.synopsis" role="synopsis">
17
<title role="synopsis.title">Synopsis</title>
18
<anchor id="GP11Slot"/>
20
<link linkend="GP11MechanismInfo">GP11MechanismInfo</link>;
21
<link linkend="void">void</link> <link linkend="gp11-mechanism-info-free">gp11_mechanism_info_free</link> (<link linkend="GP11MechanismInfo">GP11MechanismInfo</link> *mech_info);
22
typedef <link linkend="GP11Mechanisms">GP11Mechanisms</link>;
23
#define <link linkend="gp11-mechanisms-length">gp11_mechanisms_length</link> (a)
24
#define <link linkend="gp11-mechanisms-at">gp11_mechanisms_at</link> (a, i)
25
#define <link linkend="gp11-mechanisms-free">gp11_mechanisms_free</link> (a)
26
<link linkend="gboolean">gboolean</link> <link linkend="gp11-mechanisms-check">gp11_mechanisms_check</link> (<link linkend="GP11Mechanisms">GP11Mechanisms</link> *mechanisms,
28
<link linkend="GP11Slot-struct">GP11Slot</link>;
29
<link linkend="gboolean">gboolean</link> <link linkend="gp11-slot-equal">gp11_slot_equal</link> (<link linkend="gconstpointer">gconstpointer</link> slot1,
30
<link linkend="gconstpointer">gconstpointer</link> slot2);
31
<link linkend="guint">guint</link> <link linkend="gp11-slot-hash">gp11_slot_hash</link> (<link linkend="gconstpointer">gconstpointer</link> slot);
32
<link linkend="GP11Module">GP11Module</link>* <link linkend="gp11-slot-get-module">gp11_slot_get_module</link> (<link linkend="GP11Slot">GP11Slot</link> *self);
33
<link linkend="CK-SLOT-ID--CAPS">CK_SLOT_ID</link> <link linkend="gp11-slot-get-handle">gp11_slot_get_handle</link> (<link linkend="GP11Slot">GP11Slot</link> *self);
34
<link linkend="GP11SlotInfo">GP11SlotInfo</link>* <link linkend="gp11-slot-get-info">gp11_slot_get_info</link> (<link linkend="GP11Slot">GP11Slot</link> *self);
35
<link linkend="GP11TokenInfo">GP11TokenInfo</link>* <link linkend="gp11-slot-get-token-info">gp11_slot_get_token_info</link> (<link linkend="GP11Slot">GP11Slot</link> *self);
36
<link linkend="GP11Mechanisms">GP11Mechanisms</link>* <link linkend="gp11-slot-get-mechanisms">gp11_slot_get_mechanisms</link> (<link linkend="GP11Slot">GP11Slot</link> *self);
37
<link linkend="GP11MechanismInfo">GP11MechanismInfo</link>* <link linkend="gp11-slot-get-mechanism-info">gp11_slot_get_mechanism_info</link> (<link linkend="GP11Slot">GP11Slot</link> *self,
38
<link linkend="gulong">gulong</link> mech_type);
39
<link linkend="gboolean">gboolean</link> <link linkend="gp11-slot-has-flags">gp11_slot_has_flags</link> (<link linkend="GP11Slot">GP11Slot</link> *self,
40
<link linkend="gulong">gulong</link> flags);
41
<link linkend="GP11Session">GP11Session</link>* <link linkend="gp11-slot-open-session">gp11_slot_open_session</link> (<link linkend="GP11Slot">GP11Slot</link> *self,
42
<link linkend="gulong">gulong</link> flags,
43
<link linkend="GError">GError</link> **err);
44
<link linkend="GP11Session">GP11Session</link>* <link linkend="gp11-slot-open-session-full">gp11_slot_open_session_full</link> (<link linkend="GP11Slot">GP11Slot</link> *self,
45
<link linkend="gulong">gulong</link> flags,
46
<link linkend="gpointer">gpointer</link> app_data,
47
<link linkend="CK-NOTIFY--CAPS">CK_NOTIFY</link> notify,
48
<link linkend="GCancellable">GCancellable</link> *cancellable,
49
<link linkend="GError">GError</link> **err);
50
<link linkend="void">void</link> <link linkend="gp11-slot-open-session-async">gp11_slot_open_session_async</link> (<link linkend="GP11Slot">GP11Slot</link> *self,
51
<link linkend="gulong">gulong</link> flags,
52
<link linkend="gpointer">gpointer</link> app_data,
53
<link linkend="CK-NOTIFY--CAPS">CK_NOTIFY</link> notify,
54
<link linkend="GCancellable">GCancellable</link> *cancellable,
55
<link linkend="GAsyncReadyCallback">GAsyncReadyCallback</link> callback,
56
<link linkend="gpointer">gpointer</link> user_data);
57
<link linkend="GP11Session">GP11Session</link>* <link linkend="gp11-slot-open-session-finish">gp11_slot_open_session_finish</link> (<link linkend="GP11Slot">GP11Slot</link> *self,
58
<link linkend="GAsyncResult">GAsyncResult</link> *result,
59
<link linkend="GError">GError</link> **err);
60
<link linkend="GP11SlotInfo">GP11SlotInfo</link>;
61
<link linkend="void">void</link> <link linkend="gp11-slot-info-free">gp11_slot_info_free</link> (<link linkend="GP11SlotInfo">GP11SlotInfo</link> *slot_info);
62
<link linkend="GP11TokenInfo">GP11TokenInfo</link>;
63
<link linkend="void">void</link> <link linkend="gp11-token-info-free">gp11_token_info_free</link> (<link linkend="GP11TokenInfo">GP11TokenInfo</link> *token_info);
67
<refsect1 id="gp11-gp11-slot.object-hierarchy" role="object_hierarchy">
68
<title role="object_hierarchy.title">Object Hierarchy</title>
70
<link linkend="GObject">GObject</link>
79
<refsect1 id="gp11-gp11-slot.properties" role="properties">
80
<title role="properties.title">Properties</title>
82
"<link linkend="GP11Slot--handle">handle</link>" <link linkend="gulong">gulong</link> : Read / Write / Construct Only
83
"<link linkend="GP11Slot--module">module</link>" <link linkend="GP11Module">GP11Module</link>* : Read / Write / Construct Only
89
<refsect1 id="gp11-gp11-slot.description" role="desc">
90
<title role="desc.title">Description</title>
92
A PKCS11 slot can contain a token. As an example, a slot might be a card reader, and the token
93
the card. If the PKCS11 module is not a hardware driver, often the slot and token are equivalent.</para>
98
<refsect1 id="gp11-gp11-slot.details" role="details">
99
<title role="details.title">Details</title>
100
<refsect2 id="GP11MechanismInfo" role="struct">
101
<title>GP11MechanismInfo</title>
102
<indexterm zone="GP11MechanismInfo"><primary sortas="GP11MechanismInfo">GP11MechanismInfo</primary></indexterm><programlisting>typedef struct {
109
Represents information about a PKCS11 mechanism.
112
This is analogous to a CK_MECHANISM_INFO structure.
115
When you're done with this structure it should be released with
116
<link linkend="gp11-mechanism-info-free"><function>gp11_mechanism_info_free()</function></link>.</para>
118
</para><variablelist role="struct">
120
<term><link linkend="gulong">gulong</link> <structfield>min_key_size</structfield>;</term>
121
<listitem><simpara> The minimum key size that can be used with this mechanism.
122
</simpara></listitem>
125
<term><link linkend="gulong">gulong</link> <structfield>max_key_size</structfield>;</term>
126
<listitem><simpara> The maximum key size that can be used with this mechanism.
127
</simpara></listitem>
130
<term><link linkend="gulong">gulong</link> <structfield>flags</structfield>;</term>
131
<listitem><simpara> Various PKCS11 flags that apply to this mechanism.
132
</simpara></listitem>
134
</variablelist></refsect2>
135
<refsect2 id="gp11-mechanism-info-free" role="function">
136
<title>gp11_mechanism_info_free ()</title>
137
<indexterm zone="gp11-mechanism-info-free"><primary sortas="gp11_mechanism_info_free">gp11_mechanism_info_free</primary></indexterm><programlisting><link linkend="void">void</link> gp11_mechanism_info_free (<link linkend="GP11MechanismInfo">GP11MechanismInfo</link> *mech_info);</programlisting>
139
Free the GP11MechanismInfo and associated resources.</para>
141
</para><variablelist role="params">
142
<varlistentry><term><parameter>mech_info</parameter> :</term>
143
<listitem><simpara> The mechanism info to free, or NULL.
144
</simpara></listitem></varlistentry>
145
</variablelist></refsect2>
146
<refsect2 id="GP11Mechanisms" role="typedef">
147
<title>GP11Mechanisms</title>
148
<indexterm zone="GP11Mechanisms"><primary sortas="GP11Mechanisms">GP11Mechanisms</primary></indexterm><programlisting>typedef GArray GP11Mechanisms;
151
A set of GP11MechanismInfo structures.</para>
154
<refsect2 id="gp11-mechanisms-length" role="macro">
155
<title>gp11_mechanisms_length()</title>
156
<indexterm zone="gp11-mechanisms-length"><primary sortas="gp11_mechanisms_length">gp11_mechanisms_length</primary></indexterm><programlisting>#define gp11_mechanisms_length(a) ((a)->len)
159
Get the number of GP11MechanismInfo in the set.</para>
161
</para><variablelist role="params">
162
<varlistentry><term><parameter>a</parameter> :</term>
163
<listitem><simpara> A GP11Mechanisms set.
164
</simpara></listitem></varlistentry>
165
</variablelist></refsect2>
166
<refsect2 id="gp11-mechanisms-at" role="macro">
167
<title>gp11_mechanisms_at()</title>
168
<indexterm zone="gp11-mechanisms-at"><primary sortas="gp11_mechanisms_at">gp11_mechanisms_at</primary></indexterm><programlisting>#define gp11_mechanisms_at(a, i) (g_array_index(a, CK_MECHANISM_TYPE, i))
171
Get a specific GP11MechanismInfo in a the set.</para>
173
</para><variablelist role="params">
174
<varlistentry><term><parameter>a</parameter> :</term>
175
<listitem><simpara> A GP11Mechanisms set.
176
</simpara></listitem></varlistentry>
177
<varlistentry><term><parameter>i</parameter> :</term>
178
<listitem><simpara> The index of a GP11MechanismInfo.
179
</simpara></listitem></varlistentry>
180
</variablelist></refsect2>
181
<refsect2 id="gp11-mechanisms-free" role="macro">
182
<title>gp11_mechanisms_free()</title>
183
<indexterm zone="gp11-mechanisms-free"><primary sortas="gp11_mechanisms_free">gp11_mechanisms_free</primary></indexterm><programlisting>#define gp11_mechanisms_free(a) (g_array_free(a, TRUE))
186
Free a GP11Mechanisms set.</para>
188
</para><variablelist role="params">
189
<varlistentry><term><parameter>a</parameter> :</term>
190
<listitem><simpara> A GP11Mechanisms set.
191
</simpara></listitem></varlistentry>
192
</variablelist></refsect2>
193
<refsect2 id="gp11-mechanisms-check" role="function">
194
<title>gp11_mechanisms_check ()</title>
195
<indexterm zone="gp11-mechanisms-check"><primary sortas="gp11_mechanisms_check">gp11_mechanisms_check</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> gp11_mechanisms_check (<link linkend="GP11Mechanisms">GP11Mechanisms</link> *mechanisms,
196
...);</programlisting>
198
Check whether all the mechanism types are in the list.
201
The arguments should be a list of CKM_XXX mechanism types. The last argument
202
should be GP11_INVALID.</para>
204
</para><variablelist role="params">
205
<varlistentry><term><parameter>mechanisms</parameter> :</term>
206
<listitem><simpara> A list of mechanisms, perhaps retrieved from <link linkend="gp11-slot-get-mechanisms"><function>gp11_slot_get_mechanisms()</function></link>.
207
</simpara></listitem></varlistentry>
208
<varlistentry><term><parameter>...</parameter> :</term>
209
<listitem><simpara> A list of mechanism types followed by GP11_INVALID.
210
</simpara></listitem></varlistentry>
211
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> Whether the mechanism is in the list or not.
212
</simpara></listitem></varlistentry>
213
</variablelist></refsect2>
214
<refsect2 id="GP11Slot-struct" role="struct">
215
<title>GP11Slot</title>
216
<indexterm zone="GP11Slot-struct"><primary sortas="GP11Slot">GP11Slot</primary></indexterm><programlisting>typedef struct _GP11Slot GP11Slot;</programlisting>
218
Represents a PKCS11 slot.</para>
221
<refsect2 id="gp11-slot-equal" role="function">
222
<title>gp11_slot_equal ()</title>
223
<indexterm zone="gp11-slot-equal"><primary sortas="gp11_slot_equal">gp11_slot_equal</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> gp11_slot_equal (<link linkend="gconstpointer">gconstpointer</link> slot1,
224
<link linkend="gconstpointer">gconstpointer</link> slot2);</programlisting>
226
Checks equality of two slots. Two GP11Slot objects can point to the same
227
underlying PKCS<link linkend="11--CAPS"><type>11</type></link> slot.</para>
229
</para><variablelist role="params">
230
<varlistentry><term><parameter>slot1</parameter> :</term>
231
<listitem><simpara> A pointer to the first GP11Slot
232
</simpara></listitem></varlistentry>
233
<varlistentry><term><parameter>slot2</parameter> :</term>
234
<listitem><simpara> A pointer to the second GP11Slot
235
</simpara></listitem></varlistentry>
236
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> TRUE if slot1 and slot2 are equal. FALSE if either is not a GP11Slot.
237
</simpara></listitem></varlistentry>
238
</variablelist></refsect2>
239
<refsect2 id="gp11-slot-hash" role="function">
240
<title>gp11_slot_hash ()</title>
241
<indexterm zone="gp11-slot-hash"><primary sortas="gp11_slot_hash">gp11_slot_hash</primary></indexterm><programlisting><link linkend="guint">guint</link> gp11_slot_hash (<link linkend="gconstpointer">gconstpointer</link> slot);</programlisting>
243
Create a hash value for the GP11Slot.
246
This function is intended for easily hashing a GP11Slot to add to
247
a GHashTable or similar data structure.</para>
249
</para><variablelist role="params">
250
<varlistentry><term><parameter>slot</parameter> :</term>
251
<listitem><simpara> A pointer to a GP11Slot
252
</simpara></listitem></varlistentry>
253
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> An integer that can be used as a hash value, or 0 if invalid.
254
</simpara></listitem></varlistentry>
255
</variablelist></refsect2>
256
<refsect2 id="gp11-slot-get-module" role="function">
257
<title>gp11_slot_get_module ()</title>
258
<indexterm zone="gp11-slot-get-module"><primary sortas="gp11_slot_get_module">gp11_slot_get_module</primary></indexterm><programlisting><link linkend="GP11Module">GP11Module</link>* gp11_slot_get_module (<link linkend="GP11Slot">GP11Slot</link> *self);</programlisting>
260
Get the module that this slot is on.</para>
262
</para><variablelist role="params">
263
<varlistentry><term><parameter>self</parameter> :</term>
264
<listitem><simpara> The slot to get the module for.
265
</simpara></listitem></varlistentry>
266
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> The module, you must unreference this after you're done with it.
267
</simpara></listitem></varlistentry>
268
</variablelist></refsect2>
269
<refsect2 id="gp11-slot-get-handle" role="function">
270
<title>gp11_slot_get_handle ()</title>
271
<indexterm zone="gp11-slot-get-handle"><primary sortas="gp11_slot_get_handle">gp11_slot_get_handle</primary></indexterm><programlisting><link linkend="CK-SLOT-ID--CAPS">CK_SLOT_ID</link> gp11_slot_get_handle (<link linkend="GP11Slot">GP11Slot</link> *self);</programlisting>
273
Get the raw PKCS<link linkend="11--CAPS"><type>11</type></link> handle of a slot.</para>
275
</para><variablelist role="params">
276
<varlistentry><term><parameter>self</parameter> :</term>
277
<listitem><simpara> The slot to get the handle of.
278
</simpara></listitem></varlistentry>
279
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> The raw handle.
280
</simpara></listitem></varlistentry>
281
</variablelist></refsect2>
282
<refsect2 id="gp11-slot-get-info" role="function">
283
<title>gp11_slot_get_info ()</title>
284
<indexterm zone="gp11-slot-get-info"><primary sortas="gp11_slot_get_info">gp11_slot_get_info</primary></indexterm><programlisting><link linkend="GP11SlotInfo">GP11SlotInfo</link>* gp11_slot_get_info (<link linkend="GP11Slot">GP11Slot</link> *self);</programlisting>
286
Get the information for this slot.</para>
288
</para><variablelist role="params">
289
<varlistentry><term><parameter>self</parameter> :</term>
290
<listitem><simpara> The slot to get info for.
291
</simpara></listitem></varlistentry>
292
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> The slot information. When done, use <link linkend="gp11-slot-info-free"><function>gp11_slot_info_free()</function></link>
294
</simpara></listitem></varlistentry>
295
</variablelist></refsect2>
296
<refsect2 id="gp11-slot-get-token-info" role="function">
297
<title>gp11_slot_get_token_info ()</title>
298
<indexterm zone="gp11-slot-get-token-info"><primary sortas="gp11_slot_get_token_info">gp11_slot_get_token_info</primary></indexterm><programlisting><link linkend="GP11TokenInfo">GP11TokenInfo</link>* gp11_slot_get_token_info (<link linkend="GP11Slot">GP11Slot</link> *self);</programlisting>
300
Get the token information for this slot.</para>
302
</para><variablelist role="params">
303
<varlistentry><term><parameter>self</parameter> :</term>
304
<listitem><simpara> The slot to get info for.
305
</simpara></listitem></varlistentry>
306
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> The token information. When done, use <link linkend="gp11-token-info-free"><function>gp11_token_info_free()</function></link>
308
</simpara></listitem></varlistentry>
309
</variablelist></refsect2>
310
<refsect2 id="gp11-slot-get-mechanisms" role="function">
311
<title>gp11_slot_get_mechanisms ()</title>
312
<indexterm zone="gp11-slot-get-mechanisms"><primary sortas="gp11_slot_get_mechanisms">gp11_slot_get_mechanisms</primary></indexterm><programlisting><link linkend="GP11Mechanisms">GP11Mechanisms</link>* gp11_slot_get_mechanisms (<link linkend="GP11Slot">GP11Slot</link> *self);</programlisting>
314
Get the available mechanisms for this slot.</para>
316
</para><variablelist role="params">
317
<varlistentry><term><parameter>self</parameter> :</term>
318
<listitem><simpara> The slot to get mechanisms for.
319
</simpara></listitem></varlistentry>
320
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> A list of the mechanisms for this slot. Use
321
<link linkend="gp11-mechanisms-free"><function>gp11_mechanisms_free()</function></link> when done with this.
322
</simpara></listitem></varlistentry>
323
</variablelist></refsect2>
324
<refsect2 id="gp11-slot-get-mechanism-info" role="function">
325
<title>gp11_slot_get_mechanism_info ()</title>
326
<indexterm zone="gp11-slot-get-mechanism-info"><primary sortas="gp11_slot_get_mechanism_info">gp11_slot_get_mechanism_info</primary></indexterm><programlisting><link linkend="GP11MechanismInfo">GP11MechanismInfo</link>* gp11_slot_get_mechanism_info (<link linkend="GP11Slot">GP11Slot</link> *self,
327
<link linkend="gulong">gulong</link> mech_type);</programlisting>
329
Get information for the specified mechanism.</para>
331
</para><variablelist role="params">
332
<varlistentry><term><parameter>self</parameter> :</term>
333
<listitem><simpara> The slot to get mechanism info from.
334
</simpara></listitem></varlistentry>
335
<varlistentry><term><parameter>mech_type</parameter> :</term>
336
<listitem><simpara> The mechanisms type to get info for.
337
</simpara></listitem></varlistentry>
338
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> The mechanism information, or NULL if failed. Use
339
<link linkend="gp11-mechanism-info-free"><function>gp11_mechanism_info_free()</function></link> when done with it.
340
</simpara></listitem></varlistentry>
341
</variablelist></refsect2>
342
<refsect2 id="gp11-slot-has-flags" role="function">
343
<title>gp11_slot_has_flags ()</title>
344
<indexterm zone="gp11-slot-has-flags"><primary sortas="gp11_slot_has_flags">gp11_slot_has_flags</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> gp11_slot_has_flags (<link linkend="GP11Slot">GP11Slot</link> *self,
345
<link linkend="gulong">gulong</link> flags);</programlisting>
347
Check if the PKCS11 slot has the given flags.</para>
349
</para><variablelist role="params">
350
<varlistentry><term><parameter>self</parameter> :</term>
351
<listitem><simpara> The GP11Slot object.
352
</simpara></listitem></varlistentry>
353
<varlistentry><term><parameter>flags</parameter> :</term>
354
<listitem><simpara> The flags to check.
355
</simpara></listitem></varlistentry>
356
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> Whether one or more flags exist.
357
</simpara></listitem></varlistentry>
358
</variablelist></refsect2>
359
<refsect2 id="gp11-slot-open-session" role="function">
360
<title>gp11_slot_open_session ()</title>
361
<indexterm zone="gp11-slot-open-session"><primary sortas="gp11_slot_open_session">gp11_slot_open_session</primary></indexterm><programlisting><link linkend="GP11Session">GP11Session</link>* gp11_slot_open_session (<link linkend="GP11Slot">GP11Slot</link> *self,
362
<link linkend="gulong">gulong</link> flags,
363
<link linkend="GError">GError</link> **err);</programlisting>
365
Open a session on the slot. If the 'auto reuse' setting is set,
366
then this may be a recycled session with the same flags.
369
This call may block for an indefinite period.</para>
371
</para><variablelist role="params">
372
<varlistentry><term><parameter>self</parameter> :</term>
373
<listitem><simpara> The slot ot open a session on.
374
</simpara></listitem></varlistentry>
375
<varlistentry><term><parameter>flags</parameter> :</term>
376
<listitem><simpara> The flags to open a session with.
377
</simpara></listitem></varlistentry>
378
<varlistentry><term><parameter>err</parameter> :</term>
379
<listitem><simpara> A location to return an error, or NULL.
380
</simpara></listitem></varlistentry>
381
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> A new session or NULL if an error occurs.
382
</simpara></listitem></varlistentry>
383
</variablelist></refsect2>
384
<refsect2 id="gp11-slot-open-session-full" role="function">
385
<title>gp11_slot_open_session_full ()</title>
386
<indexterm zone="gp11-slot-open-session-full"><primary sortas="gp11_slot_open_session_full">gp11_slot_open_session_full</primary></indexterm><programlisting><link linkend="GP11Session">GP11Session</link>* gp11_slot_open_session_full (<link linkend="GP11Slot">GP11Slot</link> *self,
387
<link linkend="gulong">gulong</link> flags,
388
<link linkend="gpointer">gpointer</link> app_data,
389
<link linkend="CK-NOTIFY--CAPS">CK_NOTIFY</link> notify,
390
<link linkend="GCancellable">GCancellable</link> *cancellable,
391
<link linkend="GError">GError</link> **err);</programlisting>
393
Open a session on the slot. If the 'auto reuse' setting is set,
394
then this may be a recycled session with the same flags.
397
This call may block for an indefinite period.</para>
399
</para><variablelist role="params">
400
<varlistentry><term><parameter>self</parameter> :</term>
401
<listitem><simpara> The slot to open a session on.
402
</simpara></listitem></varlistentry>
403
<varlistentry><term><parameter>flags</parameter> :</term>
404
<listitem><simpara> The flags to open a session with.
405
</simpara></listitem></varlistentry>
406
<varlistentry><term><parameter>app_data</parameter> :</term>
407
<listitem><simpara> Application data for notification callback.
408
</simpara></listitem></varlistentry>
409
<varlistentry><term><parameter>notify</parameter> :</term>
410
<listitem><simpara> PKCS<link linkend="11--CAPS"><type>11</type></link> notification callback.
411
</simpara></listitem></varlistentry>
412
<varlistentry><term><parameter>cancellable</parameter> :</term>
413
<listitem><simpara> Optional cancellation object, or NULL.
414
</simpara></listitem></varlistentry>
415
<varlistentry><term><parameter>err</parameter> :</term>
416
<listitem><simpara> A location to return an error, or NULL.
417
</simpara></listitem></varlistentry>
418
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> A new session or NULL if an error occurs.
419
</simpara></listitem></varlistentry>
420
</variablelist></refsect2>
421
<refsect2 id="gp11-slot-open-session-async" role="function">
422
<title>gp11_slot_open_session_async ()</title>
423
<indexterm zone="gp11-slot-open-session-async"><primary sortas="gp11_slot_open_session_async">gp11_slot_open_session_async</primary></indexterm><programlisting><link linkend="void">void</link> gp11_slot_open_session_async (<link linkend="GP11Slot">GP11Slot</link> *self,
424
<link linkend="gulong">gulong</link> flags,
425
<link linkend="gpointer">gpointer</link> app_data,
426
<link linkend="CK-NOTIFY--CAPS">CK_NOTIFY</link> notify,
427
<link linkend="GCancellable">GCancellable</link> *cancellable,
428
<link linkend="GAsyncReadyCallback">GAsyncReadyCallback</link> callback,
429
<link linkend="gpointer">gpointer</link> user_data);</programlisting>
431
Open a session on the slot. If the 'auto reuse' setting is set,
432
then this may be a recycled session with the same flags.
435
This call will return immediately and complete asynchronously.</para>
437
</para><variablelist role="params">
438
<varlistentry><term><parameter>self</parameter> :</term>
439
<listitem><simpara> The slot to open a session on.
440
</simpara></listitem></varlistentry>
441
<varlistentry><term><parameter>flags</parameter> :</term>
442
<listitem><simpara> The flags to open a session with.
443
</simpara></listitem></varlistentry>
444
<varlistentry><term><parameter>app_data</parameter> :</term>
445
<listitem><simpara> Application data for notification callback.
446
</simpara></listitem></varlistentry>
447
<varlistentry><term><parameter>notify</parameter> :</term>
448
<listitem><simpara> PKCS<link linkend="11--CAPS"><type>11</type></link> notification callback.
449
</simpara></listitem></varlistentry>
450
<varlistentry><term><parameter>cancellable</parameter> :</term>
451
<listitem><simpara> Optional cancellation object, or NULL.
452
</simpara></listitem></varlistentry>
453
<varlistentry><term><parameter>callback</parameter> :</term>
454
<listitem><simpara> Called when the operation completes.
455
</simpara></listitem></varlistentry>
456
<varlistentry><term><parameter>user_data</parameter> :</term>
457
<listitem><simpara> Data to pass to the callback.
458
</simpara></listitem></varlistentry>
459
</variablelist></refsect2>
460
<refsect2 id="gp11-slot-open-session-finish" role="function">
461
<title>gp11_slot_open_session_finish ()</title>
462
<indexterm zone="gp11-slot-open-session-finish"><primary sortas="gp11_slot_open_session_finish">gp11_slot_open_session_finish</primary></indexterm><programlisting><link linkend="GP11Session">GP11Session</link>* gp11_slot_open_session_finish (<link linkend="GP11Slot">GP11Slot</link> *self,
463
<link linkend="GAsyncResult">GAsyncResult</link> *result,
464
<link linkend="GError">GError</link> **err);</programlisting>
466
Get the result of an open session operation. If the 'auto reuse' setting is set,
467
then this may be a recycled session with the same flags.</para>
469
</para><variablelist role="params">
470
<varlistentry><term><parameter>self</parameter> :</term>
471
<listitem><simpara> The slot to open a session on.
472
</simpara></listitem></varlistentry>
473
<varlistentry><term><parameter>result</parameter> :</term>
474
<listitem><simpara> The result passed to the callback.
475
</simpara></listitem></varlistentry>
476
<varlistentry><term><parameter>err</parameter> :</term>
477
<listitem><simpara> A location to return an error or NULL.
478
</simpara></listitem></varlistentry>
479
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> The new session or NULL if an error occurs.
480
</simpara></listitem></varlistentry>
481
</variablelist></refsect2>
482
<refsect2 id="GP11SlotInfo" role="struct">
483
<title>GP11SlotInfo</title>
484
<indexterm zone="GP11SlotInfo"><primary sortas="GP11SlotInfo">GP11SlotInfo</primary></indexterm><programlisting>typedef struct {
485
gchar *slot_description;
486
gchar *manufacturer_id;
488
guint8 hardware_version_major;
489
guint8 hardware_version_minor;
490
guint8 firmware_version_major;
491
guint8 firmware_version_minor;
495
Represents information about a PKCS11 slot.
498
This is analogous to a CK_SLOT_INFO structure, but the
499
strings are far more usable.
502
When you're done with this structure it should be released with
503
<link linkend="gp11-slot-info-free"><function>gp11_slot_info_free()</function></link>.</para>
505
</para><variablelist role="struct">
507
<term><link linkend="gchar">gchar</link> *<structfield>slot_description</structfield>;</term>
508
<listitem><simpara> Description of the slot.
509
</simpara></listitem>
512
<term><link linkend="gchar">gchar</link> *<structfield>manufacturer_id</structfield>;</term>
513
<listitem><simpara> The manufacturer of this slot.
514
</simpara></listitem>
517
<term><link linkend="gulong">gulong</link> <structfield>flags</structfield>;</term>
518
<listitem><simpara> Various PKCS11 flags that apply to this slot.
519
</simpara></listitem>
522
<term><link linkend="guint8">guint8</link> <structfield>hardware_version_major</structfield>;</term>
523
<listitem><simpara> The major version of the hardware.
524
</simpara></listitem>
527
<term><link linkend="guint8">guint8</link> <structfield>hardware_version_minor</structfield>;</term>
528
<listitem><simpara> The minor version of the hardware.
529
</simpara></listitem>
532
<term><link linkend="guint8">guint8</link> <structfield>firmware_version_major</structfield>;</term>
533
<listitem><simpara> The major version of the firmware.
534
</simpara></listitem>
537
<term><link linkend="guint8">guint8</link> <structfield>firmware_version_minor</structfield>;</term>
538
<listitem><simpara> The minor version of the firmware.
539
</simpara></listitem>
541
</variablelist></refsect2>
542
<refsect2 id="gp11-slot-info-free" role="function">
543
<title>gp11_slot_info_free ()</title>
544
<indexterm zone="gp11-slot-info-free"><primary sortas="gp11_slot_info_free">gp11_slot_info_free</primary></indexterm><programlisting><link linkend="void">void</link> gp11_slot_info_free (<link linkend="GP11SlotInfo">GP11SlotInfo</link> *slot_info);</programlisting>
546
Free the GP11SlotInfo and associated resources.</para>
548
</para><variablelist role="params">
549
<varlistentry><term><parameter>slot_info</parameter> :</term>
550
<listitem><simpara> The slot info to free, or NULL.
551
</simpara></listitem></varlistentry>
552
</variablelist></refsect2>
553
<refsect2 id="GP11TokenInfo" role="struct">
554
<title>GP11TokenInfo</title>
555
<indexterm zone="GP11TokenInfo"><primary sortas="GP11TokenInfo">GP11TokenInfo</primary></indexterm><programlisting>typedef struct {
557
gchar *manufacturer_id;
559
gchar *serial_number;
561
glong max_session_count;
563
glong max_rw_session_count;
564
glong rw_session_count;
567
glong total_public_memory;
568
glong free_public_memory;
569
glong total_private_memory;
570
glong free_private_memory;
571
guint8 hardware_version_major;
572
guint8 hardware_version_minor;
573
guint8 firmware_version_major;
574
guint8 firmware_version_minor;
579
Represents information about a PKCS11 token.
582
This is analogous to a CK_TOKEN_INFO structure, but the
583
strings are far more usable.
586
When you're done with this structure it should be released with
587
<link linkend="gp11-token-info-free"><function>gp11_token_info_free()</function></link>.</para>
589
</para><variablelist role="struct">
591
<term><link linkend="gchar">gchar</link> *<structfield>label</structfield>;</term>
592
<listitem><simpara> The displayable token label.
593
</simpara></listitem>
596
<term><link linkend="gchar">gchar</link> *<structfield>manufacturer_id</structfield>;</term>
597
<listitem><simpara> The manufacturer of this slot.
598
</simpara></listitem>
601
<term><link linkend="gchar">gchar</link> *<structfield>model</structfield>;</term>
602
<listitem><simpara> The token model number as a string.
603
</simpara></listitem>
606
<term><link linkend="gchar">gchar</link> *<structfield>serial_number</structfield>;</term>
607
<listitem><simpara> The token serial number as a string.
608
</simpara></listitem>
611
<term><link linkend="gulong">gulong</link> <structfield>flags</structfield>;</term>
612
<listitem><simpara> Various PKCS11 flags that apply to this token.
613
</simpara></listitem>
616
<term><link linkend="glong">glong</link> <structfield>max_session_count</structfield>;</term>
617
<listitem><simpara> The maximum number of sessions allowed on this token.
618
</simpara></listitem>
621
<term><link linkend="glong">glong</link> <structfield>session_count</structfield>;</term>
622
<listitem><simpara> The number of sessions open on this token.
623
</simpara></listitem>
626
<term><link linkend="glong">glong</link> <structfield>max_rw_session_count</structfield>;</term>
627
<listitem><simpara> The maximum number of read/write sessions allowed on this token.
628
</simpara></listitem>
631
<term><link linkend="glong">glong</link> <structfield>rw_session_count</structfield>;</term>
632
<listitem><simpara> The number of sessions open on this token.
633
</simpara></listitem>
636
<term><link linkend="glong">glong</link> <structfield>max_pin_len</structfield>;</term>
637
<listitem><simpara> The maximum length of a PIN for locking this token.
638
</simpara></listitem>
641
<term><link linkend="glong">glong</link> <structfield>min_pin_len</structfield>;</term>
642
<listitem><simpara> The minimum length of a PIN for locking this token.
643
</simpara></listitem>
646
<term><link linkend="glong">glong</link> <structfield>total_public_memory</structfield>;</term>
647
<listitem><simpara> The total amount of memory on this token for storing public objects.
648
</simpara></listitem>
651
<term><link linkend="glong">glong</link> <structfield>free_public_memory</structfield>;</term>
652
<listitem><simpara> The available amount of memory on this token for storing public objects.
653
</simpara></listitem>
656
<term><link linkend="glong">glong</link> <structfield>total_private_memory</structfield>;</term>
657
<listitem><simpara> The total amount of memory on this token for storing private objects.
658
</simpara></listitem>
661
<term><link linkend="glong">glong</link> <structfield>free_private_memory</structfield>;</term>
662
<listitem><simpara> The available amount of memory on this token for storing private objects.
663
</simpara></listitem>
666
<term><link linkend="guint8">guint8</link> <structfield>hardware_version_major</structfield>;</term>
667
<listitem><simpara> The major version of the hardware.
668
</simpara></listitem>
671
<term><link linkend="guint8">guint8</link> <structfield>hardware_version_minor</structfield>;</term>
672
<listitem><simpara> The minor version of the hardware.
673
</simpara></listitem>
676
<term><link linkend="guint8">guint8</link> <structfield>firmware_version_major</structfield>;</term>
677
<listitem><simpara> The major version of the firmware.
678
</simpara></listitem>
681
<term><link linkend="guint8">guint8</link> <structfield>firmware_version_minor</structfield>;</term>
682
<listitem><simpara> The minor version of the firmware.
683
</simpara></listitem>
686
<term><link linkend="gint64">gint64</link> <structfield>utc_time</structfield>;</term>
687
<listitem><simpara> If the token has a hardware clock, this is set to the number of seconds since the epoch.
688
</simpara></listitem>
690
</variablelist></refsect2>
691
<refsect2 id="gp11-token-info-free" role="function">
692
<title>gp11_token_info_free ()</title>
693
<indexterm zone="gp11-token-info-free"><primary sortas="gp11_token_info_free">gp11_token_info_free</primary></indexterm><programlisting><link linkend="void">void</link> gp11_token_info_free (<link linkend="GP11TokenInfo">GP11TokenInfo</link> *token_info);</programlisting>
695
Free the GP11TokenInfo and associated resources.</para>
697
</para><variablelist role="params">
698
<varlistentry><term><parameter>token_info</parameter> :</term>
699
<listitem><simpara> The token info to free, or NULL.
700
</simpara></listitem></varlistentry>
701
</variablelist></refsect2>
704
<refsect1 id="gp11-gp11-slot.property-details" role="property_details">
705
<title role="property_details.title">Property Details</title>
706
<refsect2 id="GP11Slot--handle" role="property"><title>The <literal>"handle"</literal> property</title>
707
<indexterm zone="GP11Slot--handle"><primary sortas="GP11Slot:handle">GP11Slot:handle</primary></indexterm><programlisting> "handle" <link linkend="gulong">gulong</link> : Read / Write / Construct Only</programlisting>
709
The raw CK_SLOT_ID handle of this slot.</para>
712
<refsect2 id="GP11Slot--module" role="property"><title>The <literal>"module"</literal> property</title>
713
<indexterm zone="GP11Slot--module"><primary sortas="GP11Slot:module">GP11Slot:module</primary></indexterm><programlisting> "module" <link linkend="GP11Module">GP11Module</link>* : Read / Write / Construct Only</programlisting>
715
The PKCS11 object that this slot is a part of.</para>