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-object">
6
<refentrytitle role="top_of_page" id="gp11-gp11-object.top_of_page">GP11Object</refentrytitle>
7
<manvolnum>3</manvolnum>
8
<refmiscinfo>GP11 Library</refmiscinfo>
12
<refname>GP11Object</refname>
13
<refpurpose>Represents a PKCS11 object such as a key or certificate.</refpurpose>
16
<refsynopsisdiv id="gp11-gp11-object.synopsis" role="synopsis">
17
<title role="synopsis.title">Synopsis</title>
18
<anchor id="GP11Object"/>
20
<link linkend="GP11Object-struct">GP11Object</link>;
21
<link linkend="GP11Object">GP11Object</link>* <link linkend="gp11-object-from-handle">gp11_object_from_handle</link> (<link linkend="GP11Slot">GP11Slot</link> *slot,
22
<link linkend="CK-OBJECT-HANDLE--CAPS">CK_OBJECT_HANDLE</link> handle);
23
<link linkend="GList">GList</link>* <link linkend="gp11-objects-from-handle-array">gp11_objects_from_handle_array</link> (<link linkend="GP11Slot">GP11Slot</link> *slot,
24
<link linkend="CK-OBJECT-HANDLE-PTR--CAPS">CK_OBJECT_HANDLE_PTR</link> handles,
25
<link linkend="CK-ULONG--CAPS">CK_ULONG</link> n_handles);
26
<link linkend="gboolean">gboolean</link> <link linkend="gp11-object-equal">gp11_object_equal</link> (<link linkend="gconstpointer">gconstpointer</link> object1,
27
<link linkend="gconstpointer">gconstpointer</link> object2);
28
<link linkend="guint">guint</link> <link linkend="gp11-object-hash">gp11_object_hash</link> (<link linkend="gconstpointer">gconstpointer</link> object);
29
<link linkend="GP11Module">GP11Module</link>* <link linkend="gp11-object-get-module">gp11_object_get_module</link> (<link linkend="GP11Object">GP11Object</link> *self);
30
<link linkend="GP11Slot">GP11Slot</link>* <link linkend="gp11-object-get-slot">gp11_object_get_slot</link> (<link linkend="GP11Object">GP11Object</link> *self);
31
<link linkend="CK-OBJECT-HANDLE--CAPS">CK_OBJECT_HANDLE</link> <link linkend="gp11-object-get-handle">gp11_object_get_handle</link> (<link linkend="GP11Object">GP11Object</link> *self);
32
<link linkend="GP11Session">GP11Session</link>* <link linkend="gp11-object-get-session">gp11_object_get_session</link> (<link linkend="GP11Object">GP11Object</link> *self);
33
<link linkend="void">void</link> <link linkend="gp11-object-set-session">gp11_object_set_session</link> (<link linkend="GP11Object">GP11Object</link> *self,
34
<link linkend="GP11Session">GP11Session</link> *session);
35
<link linkend="gboolean">gboolean</link> <link linkend="gp11-object-destroy">gp11_object_destroy</link> (<link linkend="GP11Object">GP11Object</link> *self,
36
<link linkend="GError">GError</link> **err);
37
<link linkend="gboolean">gboolean</link> <link linkend="gp11-object-destroy-full">gp11_object_destroy_full</link> (<link linkend="GP11Object">GP11Object</link> *self,
38
<link linkend="GCancellable">GCancellable</link> *cancellable,
39
<link linkend="GError">GError</link> **err);
40
<link linkend="void">void</link> <link linkend="gp11-object-destroy-async">gp11_object_destroy_async</link> (<link linkend="GP11Object">GP11Object</link> *self,
41
<link linkend="GCancellable">GCancellable</link> *cancellable,
42
<link linkend="GAsyncReadyCallback">GAsyncReadyCallback</link> callback,
43
<link linkend="gpointer">gpointer</link> user_data);
44
<link linkend="gboolean">gboolean</link> <link linkend="gp11-object-destroy-finish">gp11_object_destroy_finish</link> (<link linkend="GP11Object">GP11Object</link> *self,
45
<link linkend="GAsyncResult">GAsyncResult</link> *result,
46
<link linkend="GError">GError</link> **err);
47
<link linkend="gboolean">gboolean</link> <link linkend="gp11-object-set">gp11_object_set</link> (<link linkend="GP11Object">GP11Object</link> *self,
48
<link linkend="GError">GError</link> **err,
50
<link linkend="void">void</link> <link linkend="gp11-object-set-async">gp11_object_set_async</link> (<link linkend="GP11Object">GP11Object</link> *self,
51
<link linkend="GP11Attributes">GP11Attributes</link> *attrs,
52
<link linkend="GCancellable">GCancellable</link> *cancellable,
53
<link linkend="GAsyncReadyCallback">GAsyncReadyCallback</link> callback,
54
<link linkend="gpointer">gpointer</link> user_data);
55
<link linkend="gboolean">gboolean</link> <link linkend="gp11-object-set-finish">gp11_object_set_finish</link> (<link linkend="GP11Object">GP11Object</link> *self,
56
<link linkend="GAsyncResult">GAsyncResult</link> *result,
57
<link linkend="GError">GError</link> **err);
58
<link linkend="GP11Attributes">GP11Attributes</link>* <link linkend="gp11-object-get">gp11_object_get</link> (<link linkend="GP11Object">GP11Object</link> *self,
59
<link linkend="GError">GError</link> **err,
61
<link linkend="void">void</link> <link linkend="gp11-object-get-async">gp11_object_get_async</link> (<link linkend="GP11Object">GP11Object</link> *self,
62
<link linkend="GP11Attributes">GP11Attributes</link> *attrs,
63
<link linkend="GCancellable">GCancellable</link> *cancellable,
64
<link linkend="GAsyncReadyCallback">GAsyncReadyCallback</link> callback,
65
<link linkend="gpointer">gpointer</link> user_data);
66
<link linkend="GP11Attributes">GP11Attributes</link>* <link linkend="gp11-object-get-finish">gp11_object_get_finish</link> (<link linkend="GP11Object">GP11Object</link> *self,
67
<link linkend="GAsyncResult">GAsyncResult</link> *result,
68
<link linkend="GError">GError</link> **err);
69
<link linkend="gpointer">gpointer</link> <link linkend="gp11-object-get-data">gp11_object_get_data</link> (<link linkend="GP11Object">GP11Object</link> *self,
70
<link linkend="gulong">gulong</link> attr_type,
71
<link linkend="gsize">gsize</link> *n_data,
72
<link linkend="GError">GError</link> **err);
73
<link linkend="gpointer">gpointer</link> <link linkend="gp11-object-get-data-full">gp11_object_get_data_full</link> (<link linkend="GP11Object">GP11Object</link> *self,
74
<link linkend="gulong">gulong</link> attr_type,
75
<link linkend="GP11Allocator">GP11Allocator</link> allocator,
76
<link linkend="GCancellable">GCancellable</link> *cancellable,
77
<link linkend="gsize">gsize</link> *n_data,
78
<link linkend="GError">GError</link> **err);
79
<link linkend="void">void</link> <link linkend="gp11-object-get-data-async">gp11_object_get_data_async</link> (<link linkend="GP11Object">GP11Object</link> *self,
80
<link linkend="gulong">gulong</link> attr_type,
81
<link linkend="GP11Allocator">GP11Allocator</link> allocator,
82
<link linkend="GCancellable">GCancellable</link> *cancellable,
83
<link linkend="GAsyncReadyCallback">GAsyncReadyCallback</link> callback,
84
<link linkend="gpointer">gpointer</link> user_data);
85
<link linkend="gpointer">gpointer</link> <link linkend="gp11-object-get-data-finish">gp11_object_get_data_finish</link> (<link linkend="GP11Object">GP11Object</link> *self,
86
<link linkend="GAsyncResult">GAsyncResult</link> *result,
87
<link linkend="gsize">gsize</link> *n_data,
88
<link linkend="GError">GError</link> **err);
92
<refsect1 id="gp11-gp11-object.object-hierarchy" role="object_hierarchy">
93
<title role="object_hierarchy.title">Object Hierarchy</title>
95
<link linkend="GObject">GObject</link>
104
<refsect1 id="gp11-gp11-object.properties" role="properties">
105
<title role="properties.title">Properties</title>
107
"<link linkend="GP11Object--handle">handle</link>" <link linkend="gulong">gulong</link> : Read / Write / Construct Only
108
"<link linkend="GP11Object--module">module</link>" <link linkend="GP11Module">GP11Module</link>* : Read / Write / Construct Only
109
"<link linkend="GP11Object--session">session</link>" <link linkend="GP11Session">GP11Session</link>* : Read / Write
110
"<link linkend="GP11Object--slot">slot</link>" <link linkend="GP11Slot">GP11Slot</link>* : Read / Write / Construct Only
116
<refsect1 id="gp11-gp11-object.description" role="desc">
117
<title role="desc.title">Description</title>
119
A GP11Object holds a handle to a PKCS11 object such as a key or certificate. Token objects
120
are stored on the token persistently. Others are transient and are called session objects.</para>
125
<refsect1 id="gp11-gp11-object.details" role="details">
126
<title role="details.title">Details</title>
127
<refsect2 id="GP11Object-struct" role="struct">
128
<title>GP11Object</title>
129
<indexterm zone="GP11Object-struct"><primary sortas="GP11Object">GP11Object</primary></indexterm><programlisting>typedef struct _GP11Object GP11Object;</programlisting>
131
Represents a PKCS11 object handle such as a key or certifiacte.</para>
134
<refsect2 id="gp11-object-from-handle" role="function">
135
<title>gp11_object_from_handle ()</title>
136
<indexterm zone="gp11-object-from-handle"><primary sortas="gp11_object_from_handle">gp11_object_from_handle</primary></indexterm><programlisting><link linkend="GP11Object">GP11Object</link>* gp11_object_from_handle (<link linkend="GP11Slot">GP11Slot</link> *slot,
137
<link linkend="CK-OBJECT-HANDLE--CAPS">CK_OBJECT_HANDLE</link> handle);</programlisting>
139
Initialize a GP11Object from a raw PKCS<link linkend="11--CAPS"><type>11</type></link> handle. Normally you would use
140
<link linkend="gp11-session-create-object"><function>gp11_session_create_object()</function></link> or <link linkend="gp11-session-find-objects"><function>gp11_session_find_objects()</function></link> to access objects.</para>
142
</para><variablelist role="params">
143
<varlistentry><term><parameter>slot</parameter> :</term>
144
<listitem><simpara> The slot on which this object is present.
145
</simpara></listitem></varlistentry>
146
<varlistentry><term><parameter>handle</parameter> :</term>
147
<listitem><simpara> The raw handle of the object.
148
</simpara></listitem></varlistentry>
149
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> The new GP11Object. You should use <link linkend="g-object-unref"><function>g_object_unref()</function></link> when done with this object.
150
</simpara></listitem></varlistentry>
151
</variablelist></refsect2>
152
<refsect2 id="gp11-objects-from-handle-array" role="function">
153
<title>gp11_objects_from_handle_array ()</title>
154
<indexterm zone="gp11-objects-from-handle-array"><primary sortas="gp11_objects_from_handle_array">gp11_objects_from_handle_array</primary></indexterm><programlisting><link linkend="GList">GList</link>* gp11_objects_from_handle_array (<link linkend="GP11Slot">GP11Slot</link> *slot,
155
<link linkend="CK-OBJECT-HANDLE-PTR--CAPS">CK_OBJECT_HANDLE_PTR</link> handles,
156
<link linkend="CK-ULONG--CAPS">CK_ULONG</link> n_handles);</programlisting>
158
Initialize a list of GP11Object from raw PKCS<link linkend="11--CAPS"><type>11</type></link> handles. The handles argument must contain
159
contiguous CK_OBJECT_HANDLE handles in an array.</para>
161
</para><variablelist role="params">
162
<varlistentry><term><parameter>slot</parameter> :</term>
163
<listitem><simpara> The slot on which these objects are present.
164
</simpara></listitem></varlistentry>
165
<varlistentry><term><parameter>handles</parameter> :</term>
166
<listitem><simpara> The raw object handles.
167
</simpara></listitem></varlistentry>
168
<varlistentry><term><parameter>n_handles</parameter> :</term>
169
<listitem><simpara> The number of raw object handles.
170
</simpara></listitem></varlistentry>
171
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> The list of GP11Object. You should use <link linkend="gp11-list-unref-free"><function>gp11_list_unref_free()</function></link> when done with
173
</simpara></listitem></varlistentry>
174
</variablelist></refsect2>
175
<refsect2 id="gp11-object-equal" role="function">
176
<title>gp11_object_equal ()</title>
177
<indexterm zone="gp11-object-equal"><primary sortas="gp11_object_equal">gp11_object_equal</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> gp11_object_equal (<link linkend="gconstpointer">gconstpointer</link> object1,
178
<link linkend="gconstpointer">gconstpointer</link> object2);</programlisting>
180
Checks equality of two objects. Two GP11Object objects can point to the same
181
underlying PKCS<link linkend="11--CAPS"><type>11</type></link> object.</para>
183
</para><variablelist role="params">
184
<varlistentry><term><parameter>object1</parameter> :</term>
185
<listitem><simpara> A pointer to the first GP11Object
186
</simpara></listitem></varlistentry>
187
<varlistentry><term><parameter>object2</parameter> :</term>
188
<listitem><simpara> A pointer to the second GP11Object
189
</simpara></listitem></varlistentry>
190
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> TRUE if object1 and object2 are equal. FALSE if either is not a GP11Object.
191
</simpara></listitem></varlistentry>
192
</variablelist></refsect2>
193
<refsect2 id="gp11-object-hash" role="function">
194
<title>gp11_object_hash ()</title>
195
<indexterm zone="gp11-object-hash"><primary sortas="gp11_object_hash">gp11_object_hash</primary></indexterm><programlisting><link linkend="guint">guint</link> gp11_object_hash (<link linkend="gconstpointer">gconstpointer</link> object);</programlisting>
197
Create a hash value for the GP11Object.
200
This function is intended for easily hashing a GP11Object to add to
201
a GHashTable or similar data structure.</para>
203
</para><variablelist role="params">
204
<varlistentry><term><parameter>object</parameter> :</term>
205
<listitem><simpara> A pointer to a GP11Object
206
</simpara></listitem></varlistentry>
207
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> An integer that can be used as a hash value, or 0 if invalid.
208
</simpara></listitem></varlistentry>
209
</variablelist></refsect2>
210
<refsect2 id="gp11-object-get-module" role="function">
211
<title>gp11_object_get_module ()</title>
212
<indexterm zone="gp11-object-get-module"><primary sortas="gp11_object_get_module">gp11_object_get_module</primary></indexterm><programlisting><link linkend="GP11Module">GP11Module</link>* gp11_object_get_module (<link linkend="GP11Object">GP11Object</link> *self);</programlisting>
214
Get the PKCS<link linkend="11--CAPS"><type>11</type></link> module to which this object belongs.</para>
216
</para><variablelist role="params">
217
<varlistentry><term><parameter>self</parameter> :</term>
218
<listitem><simpara> The object.
219
</simpara></listitem></varlistentry>
220
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> The module, which should be unreffed after use.
221
</simpara></listitem></varlistentry>
222
</variablelist></refsect2>
223
<refsect2 id="gp11-object-get-slot" role="function">
224
<title>gp11_object_get_slot ()</title>
225
<indexterm zone="gp11-object-get-slot"><primary sortas="gp11_object_get_slot">gp11_object_get_slot</primary></indexterm><programlisting><link linkend="GP11Slot">GP11Slot</link>* gp11_object_get_slot (<link linkend="GP11Object">GP11Object</link> *self);</programlisting>
227
Get the PKCS<link linkend="11--CAPS"><type>11</type></link> slot to which this object belongs.</para>
229
</para><variablelist role="params">
230
<varlistentry><term><parameter>self</parameter> :</term>
231
<listitem><simpara> The object.
232
</simpara></listitem></varlistentry>
233
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> The slot, which should be unreffed after use.
234
</simpara></listitem></varlistentry>
235
</variablelist></refsect2>
236
<refsect2 id="gp11-object-get-handle" role="function">
237
<title>gp11_object_get_handle ()</title>
238
<indexterm zone="gp11-object-get-handle"><primary sortas="gp11_object_get_handle">gp11_object_get_handle</primary></indexterm><programlisting><link linkend="CK-OBJECT-HANDLE--CAPS">CK_OBJECT_HANDLE</link> gp11_object_get_handle (<link linkend="GP11Object">GP11Object</link> *self);</programlisting>
240
Get the raw PKCS<link linkend="11--CAPS"><type>11</type></link> handle of a GP11Object.</para>
242
</para><variablelist role="params">
243
<varlistentry><term><parameter>self</parameter> :</term>
244
<listitem><simpara> The object.
245
</simpara></listitem></varlistentry>
246
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> The raw object handle.
247
</simpara></listitem></varlistentry>
248
</variablelist></refsect2>
249
<refsect2 id="gp11-object-get-session" role="function">
250
<title>gp11_object_get_session ()</title>
251
<indexterm zone="gp11-object-get-session"><primary sortas="gp11_object_get_session">gp11_object_get_session</primary></indexterm><programlisting><link linkend="GP11Session">GP11Session</link>* gp11_object_get_session (<link linkend="GP11Object">GP11Object</link> *self);</programlisting>
253
Get the PKCS<link linkend="11--CAPS"><type>11</type></link> session assigned to make calls on when operating
257
This will only return a session if it was set explitly on this
258
object. By default an object will open and close sessions
259
appropriate for its calls.</para>
261
</para><variablelist role="params">
262
<varlistentry><term><parameter>self</parameter> :</term>
263
<listitem><simpara> The object
264
</simpara></listitem></varlistentry>
265
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> The assigned session, which must be unreffed after use.
266
</simpara></listitem></varlistentry>
267
</variablelist></refsect2>
268
<refsect2 id="gp11-object-set-session" role="function">
269
<title>gp11_object_set_session ()</title>
270
<indexterm zone="gp11-object-set-session"><primary sortas="gp11_object_set_session">gp11_object_set_session</primary></indexterm><programlisting><link linkend="void">void</link> gp11_object_set_session (<link linkend="GP11Object">GP11Object</link> *self,
271
<link linkend="GP11Session">GP11Session</link> *session);</programlisting>
273
Set the PKCS<link linkend="11--CAPS"><type>11</type></link> session assigned to make calls on when operating
277
It isn't always necessary to assign a session to an object.
278
By default an object will open and close sessions appropriate for
282
If you assign a read-only session, then calls on this object
283
that modify the state of the object will probably fail.</para>
285
</para><variablelist role="params">
286
<varlistentry><term><parameter>self</parameter> :</term>
287
<listitem><simpara> The object
288
</simpara></listitem></varlistentry>
289
<varlistentry><term><parameter>session</parameter> :</term>
290
<listitem><simpara> The assigned session
291
</simpara></listitem></varlistentry>
292
</variablelist></refsect2>
293
<refsect2 id="gp11-object-destroy" role="function">
294
<title>gp11_object_destroy ()</title>
295
<indexterm zone="gp11-object-destroy"><primary sortas="gp11_object_destroy">gp11_object_destroy</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> gp11_object_destroy (<link linkend="GP11Object">GP11Object</link> *self,
296
<link linkend="GError">GError</link> **err);</programlisting>
298
Destroy a PKCS<link linkend="11--CAPS"><type>11</type></link> object, deleting it from storage or the session.
299
This call may block for an indefinite period.</para>
301
</para><variablelist role="params">
302
<varlistentry><term><parameter>self</parameter> :</term>
303
<listitem><simpara> The object to destroy.
304
</simpara></listitem></varlistentry>
305
<varlistentry><term><parameter>err</parameter> :</term>
306
<listitem><simpara> A location to return an error.
307
</simpara></listitem></varlistentry>
308
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> Whether the call was successful or not.
309
</simpara></listitem></varlistentry>
310
</variablelist></refsect2>
311
<refsect2 id="gp11-object-destroy-full" role="function">
312
<title>gp11_object_destroy_full ()</title>
313
<indexterm zone="gp11-object-destroy-full"><primary sortas="gp11_object_destroy_full">gp11_object_destroy_full</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> gp11_object_destroy_full (<link linkend="GP11Object">GP11Object</link> *self,
314
<link linkend="GCancellable">GCancellable</link> *cancellable,
315
<link linkend="GError">GError</link> **err);</programlisting>
317
Destroy a PKCS<link linkend="11--CAPS"><type>11</type></link> object, deleting it from storage or the session.
318
This call may block for an indefinite period.</para>
320
</para><variablelist role="params">
321
<varlistentry><term><parameter>self</parameter> :</term>
322
<listitem><simpara> The object to destroy.
323
</simpara></listitem></varlistentry>
324
<varlistentry><term><parameter>cancellable</parameter> :</term>
325
<listitem><simpara> Optional cancellable object, or NULL to ignore.
326
</simpara></listitem></varlistentry>
327
<varlistentry><term><parameter>err</parameter> :</term>
328
<listitem><simpara> A location to return an error.
329
</simpara></listitem></varlistentry>
330
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> Whether the call was successful or not.
331
</simpara></listitem></varlistentry>
332
</variablelist></refsect2>
333
<refsect2 id="gp11-object-destroy-async" role="function">
334
<title>gp11_object_destroy_async ()</title>
335
<indexterm zone="gp11-object-destroy-async"><primary sortas="gp11_object_destroy_async">gp11_object_destroy_async</primary></indexterm><programlisting><link linkend="void">void</link> gp11_object_destroy_async (<link linkend="GP11Object">GP11Object</link> *self,
336
<link linkend="GCancellable">GCancellable</link> *cancellable,
337
<link linkend="GAsyncReadyCallback">GAsyncReadyCallback</link> callback,
338
<link linkend="gpointer">gpointer</link> user_data);</programlisting>
340
Destroy a PKCS<link linkend="11--CAPS"><type>11</type></link> object, deleting it from storage or the session.
341
This call will return immediately and complete asynchronously.</para>
343
</para><variablelist role="params">
344
<varlistentry><term><parameter>self</parameter> :</term>
345
<listitem><simpara> The object to destroy.
346
</simpara></listitem></varlistentry>
347
<varlistentry><term><parameter>cancellable</parameter> :</term>
348
<listitem><simpara> Optional cancellable object, or NULL to ignore.
349
</simpara></listitem></varlistentry>
350
<varlistentry><term><parameter>callback</parameter> :</term>
351
<listitem><simpara> Callback which is called when operation completes.
352
</simpara></listitem></varlistentry>
353
<varlistentry><term><parameter>user_data</parameter> :</term>
354
<listitem><simpara> Data to pass to the callback.
355
</simpara></listitem></varlistentry>
356
</variablelist></refsect2>
357
<refsect2 id="gp11-object-destroy-finish" role="function">
358
<title>gp11_object_destroy_finish ()</title>
359
<indexterm zone="gp11-object-destroy-finish"><primary sortas="gp11_object_destroy_finish">gp11_object_destroy_finish</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> gp11_object_destroy_finish (<link linkend="GP11Object">GP11Object</link> *self,
360
<link linkend="GAsyncResult">GAsyncResult</link> *result,
361
<link linkend="GError">GError</link> **err);</programlisting>
363
Get the status of the operation to destroy a PKCS<link linkend="11--CAPS"><type>11</type></link> object, begun with
364
<link linkend="gp11-object-destroy-async"><function>gp11_object_destroy_async()</function></link>.</para>
366
</para><variablelist role="params">
367
<varlistentry><term><parameter>self</parameter> :</term>
368
<listitem><simpara> The object being destroyed.
369
</simpara></listitem></varlistentry>
370
<varlistentry><term><parameter>result</parameter> :</term>
371
<listitem><simpara> The result of the destory operation passed to the callback.
372
</simpara></listitem></varlistentry>
373
<varlistentry><term><parameter>err</parameter> :</term>
374
<listitem><simpara> A location to store an error.
375
</simpara></listitem></varlistentry>
376
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> Whether the object was destroyed successfully or not.
377
</simpara></listitem></varlistentry>
378
</variablelist></refsect2>
379
<refsect2 id="gp11-object-set" role="function">
380
<title>gp11_object_set ()</title>
381
<indexterm zone="gp11-object-set"><primary sortas="gp11_object_set">gp11_object_set</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> gp11_object_set (<link linkend="GP11Object">GP11Object</link> *self,
382
<link linkend="GError">GError</link> **err,
383
...);</programlisting>
385
Set PKCS<link linkend="11--CAPS"><type>11</type></link> attributes on an object.
386
This call may block for an indefinite period.
389
The arguments must be triples of: attribute type, data type, value
392
<para>The variable argument list should contain:
396
<listitem><para>The gulong attribute type (ie: CKA_LABEL). </para></listitem>
400
<listitem><para>The attribute data type (one of GP11_BOOLEAN, GP11_ULONG,
401
GP11_STRING, GP11_DATE) orthe raw attribute value length.</para></listitem>
405
<listitem><para>The attribute value, either a gboolean, gulong, gchar*, GDate* or
406
a pointer to a raw attribute value.</para></listitem>
409
The variable argument list should be terminated with GP11_INVALID.</para></para>
411
</para><variablelist role="params">
412
<varlistentry><term><parameter>self</parameter> :</term>
413
<listitem><simpara> The object to set attributes on.
414
</simpara></listitem></varlistentry>
415
<varlistentry><term><parameter>err</parameter> :</term>
416
<listitem><simpara> A location to return an error.
417
</simpara></listitem></varlistentry>
418
<varlistentry><term><parameter>...</parameter> :</term>
419
<listitem><simpara> The attributes to set.
420
</simpara></listitem></varlistentry>
421
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> Whether the call was successful or not.
422
</simpara></listitem></varlistentry>
423
</variablelist></refsect2>
424
<refsect2 id="gp11-object-set-async" role="function">
425
<title>gp11_object_set_async ()</title>
426
<indexterm zone="gp11-object-set-async"><primary sortas="gp11_object_set_async">gp11_object_set_async</primary></indexterm><programlisting><link linkend="void">void</link> gp11_object_set_async (<link linkend="GP11Object">GP11Object</link> *self,
427
<link linkend="GP11Attributes">GP11Attributes</link> *attrs,
428
<link linkend="GCancellable">GCancellable</link> *cancellable,
429
<link linkend="GAsyncReadyCallback">GAsyncReadyCallback</link> callback,
430
<link linkend="gpointer">gpointer</link> user_data);</programlisting>
432
Set PKCS<link linkend="11--CAPS"><type>11</type></link> attributes on an object. This call will return
433
immediately and completes asynchronously.</para>
435
</para><variablelist role="params">
436
<varlistentry><term><parameter>self</parameter> :</term>
437
<listitem><simpara> The object to set attributes on.
438
</simpara></listitem></varlistentry>
439
<varlistentry><term><parameter>attrs</parameter> :</term>
440
<listitem><simpara> The attributes to set on the object.
441
</simpara></listitem></varlistentry>
442
<varlistentry><term><parameter>cancellable</parameter> :</term>
443
<listitem><simpara> Optional cancellable object, or NULL to ignore.
444
</simpara></listitem></varlistentry>
445
<varlistentry><term><parameter>callback</parameter> :</term>
446
<listitem><simpara> Callback which is called when operation completes.
447
</simpara></listitem></varlistentry>
448
<varlistentry><term><parameter>user_data</parameter> :</term>
449
<listitem><simpara> Data to pass to the callback.
450
</simpara></listitem></varlistentry>
451
</variablelist></refsect2>
452
<refsect2 id="gp11-object-set-finish" role="function">
453
<title>gp11_object_set_finish ()</title>
454
<indexterm zone="gp11-object-set-finish"><primary sortas="gp11_object_set_finish">gp11_object_set_finish</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> gp11_object_set_finish (<link linkend="GP11Object">GP11Object</link> *self,
455
<link linkend="GAsyncResult">GAsyncResult</link> *result,
456
<link linkend="GError">GError</link> **err);</programlisting>
458
Get the status of the operation to set attributes on a PKCS<link linkend="11--CAPS"><type>11</type></link> object,
459
begun with <link linkend="gp11-object-set-async"><function>gp11_object_set_async()</function></link>.</para>
461
</para><variablelist role="params">
462
<varlistentry><term><parameter>self</parameter> :</term>
463
<listitem><simpara> The object to set attributes on.
464
</simpara></listitem></varlistentry>
465
<varlistentry><term><parameter>result</parameter> :</term>
466
<listitem><simpara> The result of the destory operation passed to the callback.
467
</simpara></listitem></varlistentry>
468
<varlistentry><term><parameter>err</parameter> :</term>
469
<listitem><simpara> A location to store an error.
470
</simpara></listitem></varlistentry>
471
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> Whether the attributes were successfully set on the object or not.
472
</simpara></listitem></varlistentry>
473
</variablelist></refsect2>
474
<refsect2 id="gp11-object-get" role="function">
475
<title>gp11_object_get ()</title>
476
<indexterm zone="gp11-object-get"><primary sortas="gp11_object_get">gp11_object_get</primary></indexterm><programlisting><link linkend="GP11Attributes">GP11Attributes</link>* gp11_object_get (<link linkend="GP11Object">GP11Object</link> *self,
477
<link linkend="GError">GError</link> **err,
478
...);</programlisting>
480
Get the specified attributes from the object. This call may
481
block for an indefinite period.</para>
483
</para><variablelist role="params">
484
<varlistentry><term><parameter>self</parameter> :</term>
485
<listitem><simpara> The object to get attributes from.
486
</simpara></listitem></varlistentry>
487
<varlistentry><term><parameter>err</parameter> :</term>
488
<listitem><simpara> A location to store an error.
489
</simpara></listitem></varlistentry>
490
<varlistentry><term><parameter>...</parameter> :</term>
491
<listitem><simpara> The attribute types to get.
492
</simpara></listitem></varlistentry>
493
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> The resulting PKCS<link linkend="11--CAPS"><type>11</type></link> attributes, or NULL if an error occurred.
494
The result must be unreffed when you're finished with it.
495
</simpara></listitem></varlistentry>
496
</variablelist></refsect2>
497
<refsect2 id="gp11-object-get-async" role="function">
498
<title>gp11_object_get_async ()</title>
499
<indexterm zone="gp11-object-get-async"><primary sortas="gp11_object_get_async">gp11_object_get_async</primary></indexterm><programlisting><link linkend="void">void</link> gp11_object_get_async (<link linkend="GP11Object">GP11Object</link> *self,
500
<link linkend="GP11Attributes">GP11Attributes</link> *attrs,
501
<link linkend="GCancellable">GCancellable</link> *cancellable,
502
<link linkend="GAsyncReadyCallback">GAsyncReadyCallback</link> callback,
503
<link linkend="gpointer">gpointer</link> user_data);</programlisting>
505
Get the specified attributes from the object. The attributes will be cleared
506
of their current values, and new attributes will be stored. The attributes
507
should not be accessed in any way except for referencing and unreferencing
508
them until <link linkend="gp11-object-get-finish"><function>gp11_object_get_finish()</function></link> is called.
511
This call returns immediately and completes asynchronously.</para>
513
</para><variablelist role="params">
514
<varlistentry><term><parameter>self</parameter> :</term>
515
<listitem><simpara> The object to get attributes from.
516
</simpara></listitem></varlistentry>
517
<varlistentry><term><parameter>attrs</parameter> :</term>
518
<listitem><simpara> The attributes to get, initialized with their types.
519
</simpara></listitem></varlistentry>
520
<varlistentry><term><parameter>cancellable</parameter> :</term>
521
<listitem><simpara> Optional cancellation object, or NULL.
522
</simpara></listitem></varlistentry>
523
<varlistentry><term><parameter>callback</parameter> :</term>
524
<listitem><simpara> A callback which is called when the operation completes.
525
</simpara></listitem></varlistentry>
526
<varlistentry><term><parameter>user_data</parameter> :</term>
527
<listitem><simpara> Data to be passed to the callback.
528
</simpara></listitem></varlistentry>
529
</variablelist></refsect2>
530
<refsect2 id="gp11-object-get-finish" role="function">
531
<title>gp11_object_get_finish ()</title>
532
<indexterm zone="gp11-object-get-finish"><primary sortas="gp11_object_get_finish">gp11_object_get_finish</primary></indexterm><programlisting><link linkend="GP11Attributes">GP11Attributes</link>* gp11_object_get_finish (<link linkend="GP11Object">GP11Object</link> *self,
533
<link linkend="GAsyncResult">GAsyncResult</link> *result,
534
<link linkend="GError">GError</link> **err);</programlisting>
536
Get the result of a get operation and return specified attributes from
540
No extra references are added to the returned attributes pointer.</para>
542
</para><variablelist role="params">
543
<varlistentry><term><parameter>self</parameter> :</term>
544
<listitem><simpara> The object to get attributes from.
545
</simpara></listitem></varlistentry>
546
<varlistentry><term><parameter>result</parameter> :</term>
547
<listitem><simpara> The result passed to the callback.
548
</simpara></listitem></varlistentry>
549
<varlistentry><term><parameter>err</parameter> :</term>
550
<listitem><simpara> A location to store an error.
551
</simpara></listitem></varlistentry>
552
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> The filled in attributes structure if successful or
553
NULL if not successful.
554
</simpara></listitem></varlistentry>
555
</variablelist></refsect2>
556
<refsect2 id="gp11-object-get-data" role="function">
557
<title>gp11_object_get_data ()</title>
558
<indexterm zone="gp11-object-get-data"><primary sortas="gp11_object_get_data">gp11_object_get_data</primary></indexterm><programlisting><link linkend="gpointer">gpointer</link> gp11_object_get_data (<link linkend="GP11Object">GP11Object</link> *self,
559
<link linkend="gulong">gulong</link> attr_type,
560
<link linkend="gsize">gsize</link> *n_data,
561
<link linkend="GError">GError</link> **err);</programlisting>
563
Get the data for the specified attribute from the object. For convenience
564
the returned data has a null terminator.
567
This call may block for an indefinite period.</para>
569
</para><variablelist role="params">
570
<varlistentry><term><parameter>self</parameter> :</term>
571
<listitem><simpara> The object to get attribute data from.
572
</simpara></listitem></varlistentry>
573
<varlistentry><term><parameter>attr_type</parameter> :</term>
574
<listitem><simpara> The attribute to get data for.
575
</simpara></listitem></varlistentry>
576
<varlistentry><term><parameter>n_data</parameter> :</term>
577
<listitem><simpara> The length of the resulting data.
578
</simpara></listitem></varlistentry>
579
<varlistentry><term><parameter>err</parameter> :</term>
580
<listitem><simpara> A location to store an error.
581
</simpara></listitem></varlistentry>
582
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> The resulting PKCS<link linkend="11--CAPS"><type>11</type></link> attribute data, or NULL if an error occurred.
583
</simpara></listitem></varlistentry>
584
</variablelist></refsect2>
585
<refsect2 id="gp11-object-get-data-full" role="function">
586
<title>gp11_object_get_data_full ()</title>
587
<indexterm zone="gp11-object-get-data-full"><primary sortas="gp11_object_get_data_full">gp11_object_get_data_full</primary></indexterm><programlisting><link linkend="gpointer">gpointer</link> gp11_object_get_data_full (<link linkend="GP11Object">GP11Object</link> *self,
588
<link linkend="gulong">gulong</link> attr_type,
589
<link linkend="GP11Allocator">GP11Allocator</link> allocator,
590
<link linkend="GCancellable">GCancellable</link> *cancellable,
591
<link linkend="gsize">gsize</link> *n_data,
592
<link linkend="GError">GError</link> **err);</programlisting>
594
Get the data for the specified attribute from the object. For convenience
595
the returned data has an extra null terminator, not included in the returned length.
598
This call may block for an indefinite period.</para>
600
</para><variablelist role="params">
601
<varlistentry><term><parameter>self</parameter> :</term>
602
<listitem><simpara> The object to get attribute data from.
603
</simpara></listitem></varlistentry>
604
<varlistentry><term><parameter>attr_type</parameter> :</term>
605
<listitem><simpara> The attribute to get data for.
606
</simpara></listitem></varlistentry>
607
<varlistentry><term><parameter>allocator</parameter> :</term>
608
<listitem><simpara> An allocator with which to allocate memory for the data, or NULL for default.
609
</simpara></listitem></varlistentry>
610
<varlistentry><term><parameter>cancellable</parameter> :</term>
611
<listitem><simpara> Optional cancellation object, or NULL.
612
</simpara></listitem></varlistentry>
613
<varlistentry><term><parameter>n_data</parameter> :</term>
614
<listitem><simpara> The length of the resulting data.
615
</simpara></listitem></varlistentry>
616
<varlistentry><term><parameter>err</parameter> :</term>
617
<listitem><simpara> A location to store an error.
618
</simpara></listitem></varlistentry>
619
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> The resulting PKCS<link linkend="11--CAPS"><type>11</type></link> attribute data, or NULL if an error occurred.
620
</simpara></listitem></varlistentry>
621
</variablelist></refsect2>
622
<refsect2 id="gp11-object-get-data-async" role="function">
623
<title>gp11_object_get_data_async ()</title>
624
<indexterm zone="gp11-object-get-data-async"><primary sortas="gp11_object_get_data_async">gp11_object_get_data_async</primary></indexterm><programlisting><link linkend="void">void</link> gp11_object_get_data_async (<link linkend="GP11Object">GP11Object</link> *self,
625
<link linkend="gulong">gulong</link> attr_type,
626
<link linkend="GP11Allocator">GP11Allocator</link> allocator,
627
<link linkend="GCancellable">GCancellable</link> *cancellable,
628
<link linkend="GAsyncReadyCallback">GAsyncReadyCallback</link> callback,
629
<link linkend="gpointer">gpointer</link> user_data);</programlisting>
631
Get the data for the specified attribute from the object.
634
This call will return immediately and complete asynchronously.</para>
636
</para><variablelist role="params">
637
<varlistentry><term><parameter>self</parameter> :</term>
638
<listitem><simpara> The object to get attribute data from.
639
</simpara></listitem></varlistentry>
640
<varlistentry><term><parameter>attr_type</parameter> :</term>
641
<listitem><simpara> The attribute to get data for.
642
</simpara></listitem></varlistentry>
643
<varlistentry><term><parameter>allocator</parameter> :</term>
644
<listitem><simpara> An allocator with which to allocate memory for the data, or NULL for default.
645
</simpara></listitem></varlistentry>
646
<varlistentry><term><parameter>cancellable</parameter> :</term>
647
<listitem><simpara> Optional cancellation object, or NULL.
648
</simpara></listitem></varlistentry>
649
<varlistentry><term><parameter>callback</parameter> :</term>
650
<listitem><simpara> Called when the operation completes.
651
</simpara></listitem></varlistentry>
652
<varlistentry><term><parameter>user_data</parameter> :</term>
653
<listitem><simpara> Data to be passed to the callback.
654
</simpara></listitem></varlistentry>
655
</variablelist></refsect2>
656
<refsect2 id="gp11-object-get-data-finish" role="function">
657
<title>gp11_object_get_data_finish ()</title>
658
<indexterm zone="gp11-object-get-data-finish"><primary sortas="gp11_object_get_data_finish">gp11_object_get_data_finish</primary></indexterm><programlisting><link linkend="gpointer">gpointer</link> gp11_object_get_data_finish (<link linkend="GP11Object">GP11Object</link> *self,
659
<link linkend="GAsyncResult">GAsyncResult</link> *result,
660
<link linkend="gsize">gsize</link> *n_data,
661
<link linkend="GError">GError</link> **err);</programlisting>
663
Get the result of an operation to get attribute data from
664
an object. For convenience the returned data has an extra null terminator,
665
not included in the returned length.</para>
667
</para><variablelist role="params">
668
<varlistentry><term><parameter>self</parameter> :</term>
669
<listitem><simpara> The object to get an attribute from.
670
</simpara></listitem></varlistentry>
671
<varlistentry><term><parameter>result</parameter> :</term>
672
<listitem><simpara> The result passed to the callback.
673
</simpara></listitem></varlistentry>
674
<varlistentry><term><parameter>n_data</parameter> :</term>
675
<listitem><simpara> The length of the resulting data.
676
</simpara></listitem></varlistentry>
677
<varlistentry><term><parameter>err</parameter> :</term>
678
<listitem><simpara> A location to store an error.
679
</simpara></listitem></varlistentry>
680
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> The PKCS<link linkend="11--CAPS"><type>11</type></link> attribute data or NULL if an error occurred.
681
</simpara></listitem></varlistentry>
682
</variablelist></refsect2>
685
<refsect1 id="gp11-gp11-object.property-details" role="property_details">
686
<title role="property_details.title">Property Details</title>
687
<refsect2 id="GP11Object--handle" role="property"><title>The <literal>"handle"</literal> property</title>
688
<indexterm zone="GP11Object--handle"><primary sortas="GP11Object:handle">GP11Object:handle</primary></indexterm><programlisting> "handle" <link linkend="gulong">gulong</link> : Read / Write / Construct Only</programlisting>
690
The raw PKCS11 handle for this object.</para>
693
<refsect2 id="GP11Object--module" role="property"><title>The <literal>"module"</literal> property</title>
694
<indexterm zone="GP11Object--module"><primary sortas="GP11Object:module">GP11Object:module</primary></indexterm><programlisting> "module" <link linkend="GP11Module">GP11Module</link>* : Read / Write / Construct Only</programlisting>
696
The GP11Module that this object belongs to.</para>
699
<refsect2 id="GP11Object--session" role="property"><title>The <literal>"session"</literal> property</title>
700
<indexterm zone="GP11Object--session"><primary sortas="GP11Object:session">GP11Object:session</primary></indexterm><programlisting> "session" <link linkend="GP11Session">GP11Session</link>* : Read / Write</programlisting>
702
The PKCS11 session to make calls on when this object needs to
703
perform operations on itself.
706
If this is NULL then a new session is opened for each operation,
707
such as <link linkend="gp11-object-get"><function>gp11_object_get()</function></link>, <link linkend="gp11-object-set"><function>gp11_object_set()</function></link> or <link linkend="gp11-object-destroy"><function>gp11_object_destroy()</function></link>.</para>
710
<refsect2 id="GP11Object--slot" role="property"><title>The <literal>"slot"</literal> property</title>
711
<indexterm zone="GP11Object--slot"><primary sortas="GP11Object:slot">GP11Object:slot</primary></indexterm><programlisting> "slot" <link linkend="GP11Slot">GP11Slot</link>* : Read / Write / Construct Only</programlisting>
713
The GP11Slot that this object belongs to.
716
If this is a token object then it will be stored on the token in this slot.
717
If this is a session object, then it belongs to a session opened on this slot.</para>