doc/manual/html/p11-kit-Deprecated.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <html>
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
   5 <title>Deprecated</title>
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
   7 <link rel="home" href="index.html" title="p11-kit">
   8 <link rel="up" href="reference.html" title="API Reference">
   9 <link rel="prev" href="p11-kit-Future.html" title="Future">
  10 <link rel="next" href="devel.html" title="Building, Packaging, and Contributing to p11-kit">
  11 <meta name="generator" content="GTK-Doc V1.18 (XML mode)">
  12 <link rel="stylesheet" href="style.css" type="text/css">
  13 </head>
  14 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  15 <table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2">
  16 <tr valign="middle">
  17 <td><a accesskey="p" href="p11-kit-Future.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
  18 <td><a accesskey="u" href="reference.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
  19 <td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
  20 <th width="100%" align="center">p11-kit</th>
  21 <td><a accesskey="n" href="devel.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
  22 </tr>
  23 <tr><td colspan="5" class="shortcuts">
  24 <a href="#p11-kit-Deprecated.synopsis" class="shortcut">Top</a>
  25                    |
  26                   <a href="#p11-kit-Deprecated.description" class="shortcut">Description</a>
  27 </td></tr>
  28 </table>
  29 <div class="refentry">
  30 <a name="p11-kit-Deprecated"></a><div class="titlepage"></div>
  31 <div class="refnamediv"><table width="100%"><tr>
  32 <td valign="top">
  33 <h2><span class="refentrytitle"><a name="p11-kit-Deprecated.top_of_page"></a>Deprecated</span></h2>
  34 <p>Deprecated — Deprecated functions</p>
  35 </td>
  36 <td valign="top" align="right"></td>
  37 </tr></table></div>
  38 <div class="refsynopsisdiv">
  39 <a name="p11-kit-Deprecated.synopsis"></a><h2>Synopsis</h2>
  40 <pre class="synopsis"><a href="http://developer.gnome.org/gck/stable/pkcs11-links.html#CK-RV:CAPS"><span class="returnvalue">CK_RV</span></a>               <a class="link" href="p11-kit-Deprecated.html#p11-kit-initialize-registered" title="p11_kit_initialize_registered ()">p11_kit_initialize_registered</a>       (<em class="parameter"><code><span class="type">void</span></code></em>);
  41 <a href="http://developer.gnome.org/gck/stable/pkcs11-links.html#CK-RV:CAPS"><span class="returnvalue">CK_RV</span></a>               <a class="link" href="p11-kit-Deprecated.html#p11-kit-finalize-registered" title="p11_kit_finalize_registered ()">p11_kit_finalize_registered</a>         (<em class="parameter"><code><span class="type">void</span></code></em>);
  42 <a href="http://developer.gnome.org/gck/stable/pkcs11-links.html#CK-FUNCTION-LIST-PTR:CAPS"><span class="returnvalue">CK_FUNCTION_LIST_PTR</span></a> * <a class="link" href="p11-kit-Deprecated.html#p11-kit-registered-modules" title="p11_kit_registered_modules ()">p11_kit_registered_modules</a>       (<em class="parameter"><code><span class="type">void</span></code></em>);
  43 <span class="returnvalue">char</span> *              <a class="link" href="p11-kit-Deprecated.html#p11-kit-registered-module-to-name" title="p11_kit_registered_module_to_name ()">p11_kit_registered_module_to_name</a>   (<em class="parameter"><code><a href="http://developer.gnome.org/gck/stable/pkcs11-links.html#CK-FUNCTION-LIST-PTR:CAPS"><span class="type">CK_FUNCTION_LIST_PTR</span></a> module</code></em>);
  44 <a href="http://developer.gnome.org/gck/stable/pkcs11-links.html#CK-FUNCTION-LIST-PTR:CAPS"><span class="returnvalue">CK_FUNCTION_LIST_PTR</span></a> <a class="link" href="p11-kit-Deprecated.html#p11-kit-registered-name-to-module" title="p11_kit_registered_name_to_module ()">p11_kit_registered_name_to_module</a>  (<em class="parameter"><code>const <span class="type">char</span> *name</code></em>);
  45 <span class="returnvalue">char</span> *              <a class="link" href="p11-kit-Deprecated.html#p11-kit-registered-option" title="p11_kit_registered_option ()">p11_kit_registered_option</a>           (<em class="parameter"><code><a href="http://developer.gnome.org/gck/stable/pkcs11-links.html#CK-FUNCTION-LIST-PTR:CAPS"><span class="type">CK_FUNCTION_LIST_PTR</span></a> module</code></em>,
  46                                                          <em class="parameter"><code>const <span class="type">char</span> *field</code></em>);
  47 <a href="http://developer.gnome.org/gck/stable/pkcs11-links.html#CK-RV:CAPS"><span class="returnvalue">CK_RV</span></a>               <a class="link" href="p11-kit-Deprecated.html#p11-kit-initialize-module" title="p11_kit_initialize_module ()">p11_kit_initialize_module</a>           (<em class="parameter"><code><a href="http://developer.gnome.org/gck/stable/pkcs11-links.html#CK-FUNCTION-LIST-PTR:CAPS"><span class="type">CK_FUNCTION_LIST_PTR</span></a> module</code></em>);
  48 <a href="http://developer.gnome.org/gck/stable/pkcs11-links.html#CK-RV:CAPS"><span class="returnvalue">CK_RV</span></a>               <a class="link" href="p11-kit-Deprecated.html#p11-kit-load-initialize-module" title="p11_kit_load_initialize_module ()">p11_kit_load_initialize_module</a>      (<em class="parameter"><code>const <span class="type">char</span> *module_path</code></em>,
  49                                                          <em class="parameter"><code><a href="http://developer.gnome.org/gck/stable/pkcs11-links.html#CK-FUNCTION-LIST-PTR:CAPS"><span class="type">CK_FUNCTION_LIST_PTR</span></a> *module</code></em>);
  50 <a href="http://developer.gnome.org/gck/stable/pkcs11-links.html#CK-RV:CAPS"><span class="returnvalue">CK_RV</span></a>               <a class="link" href="p11-kit-Deprecated.html#p11-kit-finalize-module" title="p11_kit_finalize_module ()">p11_kit_finalize_module</a>             (<em class="parameter"><code><a href="http://developer.gnome.org/gck/stable/pkcs11-links.html#CK-FUNCTION-LIST-PTR:CAPS"><span class="type">CK_FUNCTION_LIST_PTR</span></a> module</code></em>);
  51 #define             <a class="link" href="p11-kit-Deprecated.html#P11-KIT-DEPRECATED-FOR:CAPS" title="P11_KIT_DEPRECATED_FOR()">P11_KIT_DEPRECATED_FOR</a>              (f)
  52 </pre>
  53 </div>
  54 <div class="refsect1">
  55 <a name="p11-kit-Deprecated.description"></a><h2>Description</h2>
  56 <p>
  57 These functions have been deprecated from p11-kit and are not recommended for
  58 general usage. In large part they were deprecated because they did not adequately
  59 insulate multiple callers of a PKCS#11 module from another, and could not
  60 support the 'managed' mode needed to do this.
  61 </p>
  62 </div>
  63 <div class="refsect1">
  64 <a name="p11-kit-Deprecated.details"></a><h2>Details</h2>
  65 <div class="refsect2">
  66 <a name="p11-kit-initialize-registered"></a><h3>p11_kit_initialize_registered ()</h3>
  67 <pre class="programlisting"><a href="http://developer.gnome.org/gck/stable/pkcs11-links.html#CK-RV:CAPS"><span class="returnvalue">CK_RV</span></a>               p11_kit_initialize_registered       (<em class="parameter"><code><span class="type">void</span></code></em>);</pre>
  68 <div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;">
  69 <h3 class="title">Warning</h3>
  70 <p><code class="literal">p11_kit_initialize_registered</code> is deprecated and should not be used in newly-written code. Since: 0.19.0: Use <a class="link" href="p11-kit-Modules.html#p11-kit-modules-load" title="p11_kit_modules_load ()"><code class="function">p11_kit_modules_load()</code></a> instead.</p>
  71 </div>
  72 <p>
  73 Initialize all the registered PKCS#11 modules.
  74 </p>
  75 <p>
  76 If this is the first time this function is called multiple times
  77 consecutively within a single process, then it merely increments an
  78 initialization reference count for each of these modules.
  79 </p>
  80 <p>
  81 Use <a class="link" href="p11-kit-Deprecated.html#p11-kit-finalize-registered" title="p11_kit_finalize_registered ()"><code class="function">p11_kit_finalize_registered()</code></a> to finalize these registered modules once
  82 the caller is done with them.
  83 </p>
  84 <p>
  85 If this function fails, then an error message will be available via the
  86 <a class="link" href="p11-kit-Utilities.html#p11-kit-message" title="p11_kit_message ()"><code class="function">p11_kit_message()</code></a> function.
  87 </p>
  88 <div class="variablelist"><table border="0" class="variablelist">
  89 <colgroup>
  90 <col align="left" valign="top">
  91 <col>
  92 </colgroup>
  93 <tbody><tr>
  94 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
  95 <td>CKR_OK if the initialization succeeded, or an error code.</td>
  96 </tr></tbody>
  97 </table></div>
  98 </div>
  99 <hr>
 100 <div class="refsect2">
 101 <a name="p11-kit-finalize-registered"></a><h3>p11_kit_finalize_registered ()</h3>
 102 <pre class="programlisting"><a href="http://developer.gnome.org/gck/stable/pkcs11-links.html#CK-RV:CAPS"><span class="returnvalue">CK_RV</span></a>               p11_kit_finalize_registered         (<em class="parameter"><code><span class="type">void</span></code></em>);</pre>
 103 <div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;">
 104 <h3 class="title">Warning</h3>
 105 <p><code class="literal">p11_kit_finalize_registered</code> is deprecated and should not be used in newly-written code. Since 0.19.0: Use <a class="link" href="p11-kit-Modules.html#p11-kit-modules-release" title="p11_kit_modules_release ()"><code class="function">p11_kit_modules_release()</code></a> instead.</p>
 106 </div>
 107 <p>
 108 Finalize all the registered PKCS#11 modules. These should have been
 109 initialized with <a class="link" href="p11-kit-Deprecated.html#p11-kit-initialize-registered" title="p11_kit_initialize_registered ()"><code class="function">p11_kit_initialize_registered()</code></a>.
 110 </p>
 111 <p>
 112 If <a class="link" href="p11-kit-Deprecated.html#p11-kit-initialize-registered" title="p11_kit_initialize_registered ()"><code class="function">p11_kit_initialize_registered()</code></a> has been called more than once in this
 113 process, then this function must be called the same number of times before
 114 actual finalization will occur.
 115 </p>
 116 <p>
 117 If this function fails, then an error message will be available via the
 118 <a class="link" href="p11-kit-Utilities.html#p11-kit-message" title="p11_kit_message ()"><code class="function">p11_kit_message()</code></a> function.
 119 </p>
 120 <div class="variablelist"><table border="0" class="variablelist">
 121 <colgroup>
 122 <col align="left" valign="top">
 123 <col>
 124 </colgroup>
 125 <tbody><tr>
 126 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 127 <td>CKR_OK if the finalization succeeded, or an error code.</td>
 128 </tr></tbody>
 129 </table></div>
 130 </div>
 131 <hr>
 132 <div class="refsect2">
 133 <a name="p11-kit-registered-modules"></a><h3>p11_kit_registered_modules ()</h3>
 134 <pre class="programlisting"><a href="http://developer.gnome.org/gck/stable/pkcs11-links.html#CK-FUNCTION-LIST-PTR:CAPS"><span class="returnvalue">CK_FUNCTION_LIST_PTR</span></a> * p11_kit_registered_modules       (<em class="parameter"><code><span class="type">void</span></code></em>);</pre>
 135 <div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;">
 136 <h3 class="title">Warning</h3>
 137 <p><code class="literal">p11_kit_registered_modules</code> is deprecated and should not be used in newly-written code. Since 0.19.0: Use <a class="link" href="p11-kit-Modules.html#p11-kit-modules-load" title="p11_kit_modules_load ()"><code class="function">p11_kit_modules_load()</code></a> instead.</p>
 138 </div>
 139 <p>
 140 Get a list of all the registered PKCS#11 modules. This list will be valid
 141 once the <a class="link" href="p11-kit-Deprecated.html#p11-kit-initialize-registered" title="p11_kit_initialize_registered ()"><code class="function">p11_kit_initialize_registered()</code></a> function has been called.
 142 </p>
 143 <p>
 144 The returned value is a <code class="code">NULL</code> terminated array of
 145 <code class="code">CK_FUNCTION_LIST_PTR</code> pointers.
 146 </p>
 147 <p>
 148 The returned modules are unmanaged.
 149 </p>
 150 <div class="variablelist"><table border="0" class="variablelist">
 151 <colgroup>
 152 <col align="left" valign="top">
 153 <col>
 154 </colgroup>
 155 <tbody><tr>
 156 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 157 <td>A list of all the registered modules. Use the <code class="function">free()</code> function to
 158 free the list.</td>
 159 </tr></tbody>
 160 </table></div>
 161 </div>
 162 <hr>
 163 <div class="refsect2">
 164 <a name="p11-kit-registered-module-to-name"></a><h3>p11_kit_registered_module_to_name ()</h3>
 165 <pre class="programlisting"><span class="returnvalue">char</span> *              p11_kit_registered_module_to_name   (<em class="parameter"><code><a href="http://developer.gnome.org/gck/stable/pkcs11-links.html#CK-FUNCTION-LIST-PTR:CAPS"><span class="type">CK_FUNCTION_LIST_PTR</span></a> module</code></em>);</pre>
 166 <div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;">
 167 <h3 class="title">Warning</h3>
 168 <p><code class="literal">p11_kit_registered_module_to_name</code> is deprecated and should not be used in newly-written code. Since 0.19.0: Use <a class="link" href="p11-kit-Modules.html#p11-kit-module-get-name" title="p11_kit_module_get_name ()"><code class="function">p11_kit_module_get_name()</code></a> instead.</p>
 169 </div>
 170 <p>
 171 Get the name of a registered PKCS#11 module.
 172 </p>
 173 <p>
 174 You can use <a class="link" href="p11-kit-Deprecated.html#p11-kit-registered-modules" title="p11_kit_registered_modules ()"><code class="function">p11_kit_registered_modules()</code></a> to get a list of all the registered
 175 modules. This name is specified by the registered module configuration.
 176 </p>
 177 <div class="variablelist"><table border="0" class="variablelist">
 178 <colgroup>
 179 <col align="left" valign="top">
 180 <col>
 181 </colgroup>
 182 <tbody>
 183 <tr>
 184 <td><p><span class="term"><em class="parameter"><code>module</code></em> :</span></p></td>
 185 <td>pointer to a registered module</td>
 186 </tr>
 187 <tr>
 188 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 189 <td>A newly allocated string containing the module name, or
 190 <code class="code">NULL</code> if no such registered module exists. Use <code class="function">free()</code> to
 191 free this string.</td>
 192 </tr>
 193 </tbody>
 194 </table></div>
 195 </div>
 196 <hr>
 197 <div class="refsect2">
 198 <a name="p11-kit-registered-name-to-module"></a><h3>p11_kit_registered_name_to_module ()</h3>
 199 <pre class="programlisting"><a href="http://developer.gnome.org/gck/stable/pkcs11-links.html#CK-FUNCTION-LIST-PTR:CAPS"><span class="returnvalue">CK_FUNCTION_LIST_PTR</span></a> p11_kit_registered_name_to_module  (<em class="parameter"><code>const <span class="type">char</span> *name</code></em>);</pre>
 200 <div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;">
 201 <h3 class="title">Warning</h3>
 202 <p><code class="literal">p11_kit_registered_name_to_module</code> is deprecated and should not be used in newly-written code. Since 0.19.0: Use <a class="link" href="p11-kit-Modules.html#p11-kit-module-for-name" title="p11_kit_module_for_name ()"><code class="function">p11_kit_module_for_name()</code></a> instead.</p>
 203 </div>
 204 <p>
 205 Lookup a registered PKCS#11 module by its name. This name is specified by
 206 the registered module configuration.
 207 </p>
 208 <div class="variablelist"><table border="0" class="variablelist">
 209 <colgroup>
 210 <col align="left" valign="top">
 211 <col>
 212 </colgroup>
 213 <tbody>
 214 <tr>
 215 <td><p><span class="term"><em class="parameter"><code>name</code></em> :</span></p></td>
 216 <td>name of a registered module</td>
 217 </tr>
 218 <tr>
 219 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 220 <td>a pointer to a PKCS#11 module, or <code class="code">NULL</code> if this name was
 221 not found.</td>
 222 </tr>
 223 </tbody>
 224 </table></div>
 225 </div>
 226 <hr>
 227 <div class="refsect2">
 228 <a name="p11-kit-registered-option"></a><h3>p11_kit_registered_option ()</h3>
 229 <pre class="programlisting"><span class="returnvalue">char</span> *              p11_kit_registered_option           (<em class="parameter"><code><a href="http://developer.gnome.org/gck/stable/pkcs11-links.html#CK-FUNCTION-LIST-PTR:CAPS"><span class="type">CK_FUNCTION_LIST_PTR</span></a> module</code></em>,
 230                                                          <em class="parameter"><code>const <span class="type">char</span> *field</code></em>);</pre>
 231 <div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;">
 232 <h3 class="title">Warning</h3>
 233 <p><code class="literal">p11_kit_registered_option</code> is deprecated and should not be used in newly-written code. Since 0.19.0: Use <a class="link" href="p11-kit-Modules.html#p11-kit-config-option" title="p11_kit_config_option ()"><code class="function">p11_kit_config_option()</code></a> instead.</p>
 234 </div>
 235 <p>
 236 Lookup a configured option for a registered PKCS#11 module. If a
 237 <code class="code">NULL</code> module argument is specified, then this will lookup
 238 the configuration option in the global config file.
 239 </p>
 240 <div class="variablelist"><table border="0" class="variablelist">
 241 <colgroup>
 242 <col align="left" valign="top">
 243 <col>
 244 </colgroup>
 245 <tbody>
 246 <tr>
 247 <td><p><span class="term"><em class="parameter"><code>module</code></em> :</span></p></td>
 248 <td>a pointer to a registered module</td>
 249 </tr>
 250 <tr>
 251 <td><p><span class="term"><em class="parameter"><code>field</code></em> :</span></p></td>
 252 <td>the name of the option to lookup.</td>
 253 </tr>
 254 <tr>
 255 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 256 <td>A newly allocated string containing the option value, or
 257 <code class="code">NULL</code> if the registered module or the option were not found.
 258 Use <code class="function">free()</code> to free the returned string.</td>
 259 </tr>
 260 </tbody>
 261 </table></div>
 262 </div>
 263 <hr>
 264 <div class="refsect2">
 265 <a name="p11-kit-initialize-module"></a><h3>p11_kit_initialize_module ()</h3>
 266 <pre class="programlisting"><a href="http://developer.gnome.org/gck/stable/pkcs11-links.html#CK-RV:CAPS"><span class="returnvalue">CK_RV</span></a>               p11_kit_initialize_module           (<em class="parameter"><code><a href="http://developer.gnome.org/gck/stable/pkcs11-links.html#CK-FUNCTION-LIST-PTR:CAPS"><span class="type">CK_FUNCTION_LIST_PTR</span></a> module</code></em>);</pre>
 267 <div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;">
 268 <h3 class="title">Warning</h3>
 269 <p><code class="literal">p11_kit_initialize_module</code> is deprecated and should not be used in newly-written code. Since 0.19.0: Use <a class="link" href="p11-kit-Modules.html#p11-kit-module-initialize" title="p11_kit_module_initialize ()"><code class="function">p11_kit_module_initialize()</code></a> instead.</p>
 270 </div>
 271 <p>
 272 Initialize an arbitrary PKCS#11 module. Normally using the
 273 <a class="link" href="p11-kit-Deprecated.html#p11-kit-initialize-registered" title="p11_kit_initialize_registered ()"><code class="function">p11_kit_initialize_registered()</code></a> is preferred.
 274 </p>
 275 <p>
 276 Using this function to initialize modules allows coordination between
 277 multiple users of the same module in a single process. It should be called
 278 on modules that have been loaded (with <code class="function">dlopen()</code> for example) but not yet
 279 initialized. The caller should not yet have called the module's
 280 <code class="code">C_Initialize</code> method. This function will call
 281 <code class="code">C_Initialize</code> as necessary.
 282 </p>
 283 <p>
 284 Subsequent calls to this function for the same module will result in an
 285 initialization count being incremented for the module. It is safe (although
 286 usually unnecessary) to use this function on registered modules.
 287 </p>
 288 <p>
 289 The module must be finalized with <a class="link" href="p11-kit-Deprecated.html#p11-kit-finalize-module" title="p11_kit_finalize_module ()"><code class="function">p11_kit_finalize_module()</code></a> instead of
 290 calling its <code class="code">C_Finalize</code> method directly.
 291 </p>
 292 <p>
 293 This function does not accept a <code class="code">CK_C_INITIALIZE_ARGS</code> argument.
 294 Custom initialization arguments cannot be supported when multiple consumers
 295 load the same module.
 296 </p>
 297 <p>
 298 If this function fails, then an error message will be available via the
 299 <a class="link" href="p11-kit-Utilities.html#p11-kit-message" title="p11_kit_message ()"><code class="function">p11_kit_message()</code></a> function.
 300 </p>
 301 <div class="variablelist"><table border="0" class="variablelist">
 302 <colgroup>
 303 <col align="left" valign="top">
 304 <col>
 305 </colgroup>
 306 <tbody>
 307 <tr>
 308 <td><p><span class="term"><em class="parameter"><code>module</code></em> :</span></p></td>
 309 <td>loaded module to initialize.</td>
 310 </tr>
 311 <tr>
 312 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 313 <td>CKR_OK if the initialization was successful.</td>
 314 </tr>
 315 </tbody>
 316 </table></div>
 317 </div>
 318 <hr>
 319 <div class="refsect2">
 320 <a name="p11-kit-load-initialize-module"></a><h3>p11_kit_load_initialize_module ()</h3>
 321 <pre class="programlisting"><a href="http://developer.gnome.org/gck/stable/pkcs11-links.html#CK-RV:CAPS"><span class="returnvalue">CK_RV</span></a>               p11_kit_load_initialize_module      (<em class="parameter"><code>const <span class="type">char</span> *module_path</code></em>,
 322                                                          <em class="parameter"><code><a href="http://developer.gnome.org/gck/stable/pkcs11-links.html#CK-FUNCTION-LIST-PTR:CAPS"><span class="type">CK_FUNCTION_LIST_PTR</span></a> *module</code></em>);</pre>
 323 <div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;">
 324 <h3 class="title">Warning</h3>
 325 <p><code class="literal">p11_kit_load_initialize_module</code> is deprecated and should not be used in newly-written code. Since 0.19.0: Use <a class="link" href="p11-kit-Modules.html#p11-kit-module-load" title="p11_kit_module_load ()"><code class="function">p11_kit_module_load()</code></a> instead.</p>
 326 </div>
 327 <p>
 328 Load an arbitrary PKCS#11 module from a dynamic library file, and
 329 initialize it. Normally using the <a class="link" href="p11-kit-Deprecated.html#p11-kit-initialize-registered" title="p11_kit_initialize_registered ()"><code class="function">p11_kit_initialize_registered()</code></a> function
 330 is preferred.
 331 </p>
 332 <p>
 333 Using this function to load and initialize modules allows coordination between
 334 multiple users of the same module in a single process. The caller should not
 335 call the module's <code class="code">C_Initialize</code> method. This function will call
 336 <code class="code">C_Initialize</code> as necessary.
 337 </p>
 338 <p>
 339 If a module has already been loaded, then use of this function is unnecesasry.
 340 Instead use the <a class="link" href="p11-kit-Deprecated.html#p11-kit-initialize-module" title="p11_kit_initialize_module ()"><code class="function">p11_kit_initialize_module()</code></a> function to initialize it.
 341 </p>
 342 <p>
 343 Subsequent calls to this function for the same module will result in an
 344 initialization count being incremented for the module. It is safe (although
 345 usually unnecessary) to use this function on registered modules.
 346 </p>
 347 <p>
 348 The module must be finalized with <a class="link" href="p11-kit-Deprecated.html#p11-kit-finalize-module" title="p11_kit_finalize_module ()"><code class="function">p11_kit_finalize_module()</code></a> instead of
 349 calling its <code class="code">C_Finalize</code> method directly.
 350 </p>
 351 <p>
 352 This function does not accept a <code class="code">CK_C_INITIALIZE_ARGS</code> argument.
 353 Custom initialization arguments cannot be supported when multiple consumers
 354 load the same module.
 355 </p>
 356 <p>
 357 If this function fails, then an error message will be available via the
 358 <a class="link" href="p11-kit-Utilities.html#p11-kit-message" title="p11_kit_message ()"><code class="function">p11_kit_message()</code></a> function.
 359 </p>
 360 <div class="variablelist"><table border="0" class="variablelist">
 361 <colgroup>
 362 <col align="left" valign="top">
 363 <col>
 364 </colgroup>
 365 <tbody>
 366 <tr>
 367 <td><p><span class="term"><em class="parameter"><code>module_path</code></em> :</span></p></td>
 368 <td>full file path of module library</td>
 369 </tr>
 370 <tr>
 371 <td><p><span class="term"><em class="parameter"><code>module</code></em> :</span></p></td>
 372 <td>location to place loaded module pointer</td>
 373 </tr>
 374 <tr>
 375 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 376 <td>CKR_OK if the initialization was successful.</td>
 377 </tr>
 378 </tbody>
 379 </table></div>
 380 </div>
 381 <hr>
 382 <div class="refsect2">
 383 <a name="p11-kit-finalize-module"></a><h3>p11_kit_finalize_module ()</h3>
 384 <pre class="programlisting"><a href="http://developer.gnome.org/gck/stable/pkcs11-links.html#CK-RV:CAPS"><span class="returnvalue">CK_RV</span></a>               p11_kit_finalize_module             (<em class="parameter"><code><a href="http://developer.gnome.org/gck/stable/pkcs11-links.html#CK-FUNCTION-LIST-PTR:CAPS"><span class="type">CK_FUNCTION_LIST_PTR</span></a> module</code></em>);</pre>
 385 <div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;">
 386 <h3 class="title">Warning</h3>
 387 <p><code class="literal">p11_kit_finalize_module</code> is deprecated and should not be used in newly-written code. Since 0.19.0: Use <a class="link" href="p11-kit-Modules.html#p11-kit-module-finalize" title="p11_kit_module_finalize ()"><code class="function">p11_kit_module_finalize()</code></a> and
 388         <a class="link" href="p11-kit-Modules.html#p11-kit-module-release" title="p11_kit_module_release ()"><code class="function">p11_kit_module_release()</code></a> instead.</p>
 389 </div>
 390 <p>
 391 Finalize an arbitrary PKCS#11 module. The module must have been initialized
 392 using <a class="link" href="p11-kit-Deprecated.html#p11-kit-initialize-module" title="p11_kit_initialize_module ()"><code class="function">p11_kit_initialize_module()</code></a>. In most cases callers will want to use
 393 <a class="link" href="p11-kit-Deprecated.html#p11-kit-finalize-registered" title="p11_kit_finalize_registered ()"><code class="function">p11_kit_finalize_registered()</code></a> instead of this function.
 394 </p>
 395 <p>
 396 Using this function to finalize modules allows coordination between
 397 multiple users of the same module in a single process. The caller should not
 398 call the module's <code class="code">C_Finalize</code> method. This function will call
 399 <code class="code">C_Finalize</code> as necessary.
 400 </p>
 401 <p>
 402 If the module was initialized more than once, then this function will
 403 decrement an initialization count for the module. When the count reaches zero
 404 the module will be truly finalized. It is safe (although usually unnecessary)
 405 to use this function on registered modules if (and only if) they were
 406 initialized using <a class="link" href="p11-kit-Deprecated.html#p11-kit-initialize-module" title="p11_kit_initialize_module ()"><code class="function">p11_kit_initialize_module()</code></a> for some reason.
 407 </p>
 408 <p>
 409 If this function fails, then an error message will be available via the
 410 <a class="link" href="p11-kit-Utilities.html#p11-kit-message" title="p11_kit_message ()"><code class="function">p11_kit_message()</code></a> function.
 411 </p>
 412 <div class="variablelist"><table border="0" class="variablelist">
 413 <colgroup>
 414 <col align="left" valign="top">
 415 <col>
 416 </colgroup>
 417 <tbody>
 418 <tr>
 419 <td><p><span class="term"><em class="parameter"><code>module</code></em> :</span></p></td>
 420 <td>loaded module to finalize.</td>
 421 </tr>
 422 <tr>
 423 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 424 <td>CKR_OK if the finalization was successful.</td>
 425 </tr>
 426 </tbody>
 427 </table></div>
 428 </div>
 429 <hr>
 430 <div class="refsect2">
 431 <a name="P11-KIT-DEPRECATED-FOR:CAPS"></a><h3>P11_KIT_DEPRECATED_FOR()</h3>
 432 <pre class="programlisting">#define P11_KIT_DEPRECATED_FOR(f) __attribute__((deprecated("Use " #f " instead")))
 433 </pre>
 434 </div>
 435 </div>
 436 </div>
 437 <div class="footer">
 438 <hr>
 439           Generated by GTK-Doc V1.18</div>
 440 </body>
 441 </html>