doc/manual/html/p11-kit-Modules.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>Modules</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="reference.html" title="API Reference">
  10 <link rel="next" href="p11-kit-URIs.html" title="URIs">
  11 <meta name="generator" content="GTK-Doc V1.19 (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="reference.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="p11-kit-URIs.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-Modules.synopsis" class="shortcut">Top</a>
  25                    |
  26                   <a href="#p11-kit-Modules.description" class="shortcut">Description</a>
  27 </td></tr>
  28 </table>
  29 <div class="refentry">
  30 <a name="p11-kit-Modules"></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-Modules.top_of_page"></a>Modules</span></h2>
  34 <p>Modules — Module loading and initializing</p>
  35 </td>
  36 <td valign="top" align="right"></td>
  37 </tr></table></div>
  38 <div class="refsynopsisdiv">
  39 <a name="p11-kit-Modules.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-Modules.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-Modules.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-Modules.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-Modules.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-Modules.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-Modules.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-Modules.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-Modules.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-Modules.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 </pre>
  52 </div>
  53 <div class="refsect1">
  54 <a name="p11-kit-Modules.description"></a><h2>Description</h2>
  55 <p>
  56 PKCS#11 modules are used by crypto libraries and applications to access
  57 crypto objects (like keys and certificates) and to perform crypto operations.
  58 </p>
  59 <p>
  60 In order for applications to behave consistently with regard to the user's
  61 installed PKCS#11 modules, each module must be registered so that applications
  62 or libraries know that they should load it.
  63 </p>
  64 <p>
  65 The functions here provide support for initializing registered modules. The
  66 <a class="link" href="p11-kit-Modules.html#p11-kit-initialize-registered" title="p11_kit_initialize_registered ()"><code class="function">p11_kit_initialize_registered()</code></a> function should be used to load and initialize
  67 the registered modules. When done, the <a class="link" href="p11-kit-Modules.html#p11-kit-finalize-registered" title="p11_kit_finalize_registered ()"><code class="function">p11_kit_finalize_registered()</code></a> function
  68 should be used to release those modules and associated resources.
  69 </p>
  70 <p>
  71 In addition <a class="link" href="p11-kit-Modules.html#p11-kit-registered-option" title="p11_kit_registered_option ()"><code class="function">p11_kit_registered_option()</code></a> can be used to access other parts
  72 of the module configuration.
  73 </p>
  74 <p>
  75 When multiple consumers of a module (such as libraries or applications) are
  76 in the same process, coordination of the initialization and finalization
  77 of PKCS#11 modules is required. The functions here automatically provide
  78 initialization reference counting to make this work.
  79 </p>
  80 <p>
  81 If a consumer wishes to load an arbitrary PKCS#11 module that's not
  82 registered, that module should be initialized with <a class="link" href="p11-kit-Modules.html#p11-kit-initialize-module" title="p11_kit_initialize_module ()"><code class="function">p11_kit_initialize_module()</code></a>
  83 and finalized with <a class="link" href="p11-kit-Modules.html#p11-kit-finalize-module" title="p11_kit_finalize_module ()"><code class="function">p11_kit_finalize_module()</code></a>. The module's own
  84 <code class="code">C_Initialize</code> and <code class="code">C_Finalize</code> methods should not
  85 be called directly.
  86 </p>
  87 <p>
  88 Modules are represented by a pointer to their <code class="code">CK_FUNCTION_LIST</code>
  89 entry points. This means that callers can load modules elsewhere, using
  90 <code class="function">dlopen()</code> for example, and then still use these methods on them.
  91 </p>
  92 </div>
  93 <div class="refsect1">
  94 <a name="p11-kit-Modules.details"></a><h2>Details</h2>
  95 <div class="refsect2">
  96 <a name="p11-kit-initialize-registered"></a><h3>p11_kit_initialize_registered ()</h3>
  97 <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>
  98 <p>
  99 Initialize all the registered PKCS#11 modules.
 100 </p>
 101 <p>
 102 If this is the first time this function is called multiple times
 103 consecutively within a single process, then it merely increments an
 104 initialization reference count for each of these modules.
 105 </p>
 106 <p>
 107 Use <a class="link" href="p11-kit-Modules.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
 108 the caller is done with them.
 109 </p>
 110 <p>
 111 If this function fails, then an error message will be available via the
 112 <a class="link" href="p11-kit-Future.html#p11-kit-message" title="p11_kit_message ()"><code class="function">p11_kit_message()</code></a> function.
 113 </p>
 114 <div class="variablelist"><table border="0" class="variablelist">
 115 <colgroup>
 116 <col align="left" valign="top">
 117 <col>
 118 </colgroup>
 119 <tbody><tr>
 120 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 121 <td>CKR_OK if the initialization succeeded, or an error code.</td>
 122 </tr></tbody>
 123 </table></div>
 124 </div>
 125 <hr>
 126 <div class="refsect2">
 127 <a name="p11-kit-finalize-registered"></a><h3>p11_kit_finalize_registered ()</h3>
 128 <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>
 129 <p>
 130 Finalize all the registered PKCS#11 modules. These should have been
 131 initialized with <a class="link" href="p11-kit-Modules.html#p11-kit-initialize-registered" title="p11_kit_initialize_registered ()"><code class="function">p11_kit_initialize_registered()</code></a>.
 132 </p>
 133 <p>
 134 If <a class="link" href="p11-kit-Modules.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
 135 process, then this function must be called the same number of times before
 136 actual finalization will occur.
 137 </p>
 138 <p>
 139 If this function fails, then an error message will be available via the
 140 <a class="link" href="p11-kit-Future.html#p11-kit-message" title="p11_kit_message ()"><code class="function">p11_kit_message()</code></a> function.
 141 </p>
 142 <div class="variablelist"><table border="0" class="variablelist">
 143 <colgroup>
 144 <col align="left" valign="top">
 145 <col>
 146 </colgroup>
 147 <tbody><tr>
 148 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 149 <td>CKR_OK if the finalization succeeded, or an error code.</td>
 150 </tr></tbody>
 151 </table></div>
 152 </div>
 153 <hr>
 154 <div class="refsect2">
 155 <a name="p11-kit-registered-modules"></a><h3>p11_kit_registered_modules ()</h3>
 156 <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>
 157 <p>
 158 Get a list of all the registered PKCS#11 modules. This list will be valid
 159 once the <a class="link" href="p11-kit-Modules.html#p11-kit-initialize-registered" title="p11_kit_initialize_registered ()"><code class="function">p11_kit_initialize_registered()</code></a> function has been called.
 160 </p>
 161 <p>
 162 The returned value is a <code class="code">NULL</code> terminated array of
 163 <code class="code">CK_FUNCTION_LIST_PTR</code> pointers.
 164 </p>
 165 <div class="variablelist"><table border="0" class="variablelist">
 166 <colgroup>
 167 <col align="left" valign="top">
 168 <col>
 169 </colgroup>
 170 <tbody><tr>
 171 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 172 <td>A list of all the registered modules. Use the <code class="function">free()</code> function to
 173 free the list.</td>
 174 </tr></tbody>
 175 </table></div>
 176 </div>
 177 <hr>
 178 <div class="refsect2">
 179 <a name="p11-kit-registered-module-to-name"></a><h3>p11_kit_registered_module_to_name ()</h3>
 180 <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>
 181 <p>
 182 Get the name of a registered PKCS#11 module.
 183 </p>
 184 <p>
 185 You can use <a class="link" href="p11-kit-Modules.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
 186 modules. This name is specified by the registered module configuration.
 187 </p>
 188 <div class="variablelist"><table border="0" class="variablelist">
 189 <colgroup>
 190 <col align="left" valign="top">
 191 <col>
 192 </colgroup>
 193 <tbody>
 194 <tr>
 195 <td><p><span class="term"><em class="parameter"><code>module</code></em> :</span></p></td>
 196 <td>pointer to a registered module</td>
 197 </tr>
 198 <tr>
 199 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 200 <td>A newly allocated string containing the module name, or
 201 <code class="code">NULL</code> if no such registered module exists. Use <code class="function">free()</code> to
 202 free this string.</td>
 203 </tr>
 204 </tbody>
 205 </table></div>
 206 </div>
 207 <hr>
 208 <div class="refsect2">
 209 <a name="p11-kit-registered-name-to-module"></a><h3>p11_kit_registered_name_to_module ()</h3>
 210 <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>
 211 <p>
 212 Lookup a registered PKCS#11 module by its name. This name is specified by
 213 the registered module configuration.
 214 </p>
 215 <div class="variablelist"><table border="0" class="variablelist">
 216 <colgroup>
 217 <col align="left" valign="top">
 218 <col>
 219 </colgroup>
 220 <tbody>
 221 <tr>
 222 <td><p><span class="term"><em class="parameter"><code>name</code></em> :</span></p></td>
 223 <td>name of a registered module</td>
 224 </tr>
 225 <tr>
 226 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 227 <td>a pointer to a PKCS#11 module, or <code class="code">NULL</code> if this name was
 228 not found.</td>
 229 </tr>
 230 </tbody>
 231 </table></div>
 232 </div>
 233 <hr>
 234 <div class="refsect2">
 235 <a name="p11-kit-registered-option"></a><h3>p11_kit_registered_option ()</h3>
 236 <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>,
 237                                                          <em class="parameter"><code>const <span class="type">char</span> *field</code></em>);</pre>
 238 <p>
 239 Lookup a configured option for a registered PKCS#11 module. If a
 240 <code class="code">NULL</code> module argument is specified, then this will lookup
 241 the configuration option in the global config file.
 242 </p>
 243 <div class="variablelist"><table border="0" class="variablelist">
 244 <colgroup>
 245 <col align="left" valign="top">
 246 <col>
 247 </colgroup>
 248 <tbody>
 249 <tr>
 250 <td><p><span class="term"><em class="parameter"><code>module</code></em> :</span></p></td>
 251 <td>a pointer to a registered module</td>
 252 </tr>
 253 <tr>
 254 <td><p><span class="term"><em class="parameter"><code>field</code></em> :</span></p></td>
 255 <td>the name of the option to lookup.</td>
 256 </tr>
 257 <tr>
 258 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 259 <td>A newly allocated string containing the option value, or
 260 <code class="code">NULL</code> if the registered module or the option were not found.
 261 Use <code class="function">free()</code> to free the returned string.</td>
 262 </tr>
 263 </tbody>
 264 </table></div>
 265 </div>
 266 <hr>
 267 <div class="refsect2">
 268 <a name="p11-kit-initialize-module"></a><h3>p11_kit_initialize_module ()</h3>
 269 <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>
 270 <p>
 271 Initialize an arbitrary PKCS#11 module. Normally using the
 272 <a class="link" href="p11-kit-Modules.html#p11-kit-initialize-registered" title="p11_kit_initialize_registered ()"><code class="function">p11_kit_initialize_registered()</code></a> is preferred.
 273 </p>
 274 <p>
 275 Using this function to initialize modules allows coordination between
 276 multiple users of the same module in a single process. It should be called
 277 on modules that have been loaded (with <code class="function">dlopen()</code> for example) but not yet
 278 initialized. The caller should not yet have called the module's
 279 <code class="code">C_Initialize</code> method. This function will call
 280 <code class="code">C_Initialize</code> as necessary.
 281 </p>
 282 <p>
 283 Subsequent calls to this function for the same module will result in an
 284 initialization count being incremented for the module. It is safe (although
 285 usually unnecessary) to use this function on registered modules.
 286 </p>
 287 <p>
 288 The module must be finalized with <a class="link" href="p11-kit-Modules.html#p11-kit-finalize-module" title="p11_kit_finalize_module ()"><code class="function">p11_kit_finalize_module()</code></a> instead of
 289 calling its <code class="code">C_Finalize</code> method directly.
 290 </p>
 291 <p>
 292 This function does not accept a <code class="code">CK_C_INITIALIZE_ARGS</code> argument.
 293 Custom initialization arguments cannot be supported when multiple consumers
 294 load the same module.
 295 </p>
 296 <p>
 297 If this function fails, then an error message will be available via the
 298 <a class="link" href="p11-kit-Future.html#p11-kit-message" title="p11_kit_message ()"><code class="function">p11_kit_message()</code></a> function.
 299 </p>
 300 <div class="variablelist"><table border="0" class="variablelist">
 301 <colgroup>
 302 <col align="left" valign="top">
 303 <col>
 304 </colgroup>
 305 <tbody>
 306 <tr>
 307 <td><p><span class="term"><em class="parameter"><code>module</code></em> :</span></p></td>
 308 <td>loaded module to initialize.</td>
 309 </tr>
 310 <tr>
 311 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 312 <td>CKR_OK if the initialization was successful.</td>
 313 </tr>
 314 </tbody>
 315 </table></div>
 316 </div>
 317 <hr>
 318 <div class="refsect2">
 319 <a name="p11-kit-load-initialize-module"></a><h3>p11_kit_load_initialize_module ()</h3>
 320 <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>,
 321                                                          <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>
 322 <p>
 323 Load an arbitrary PKCS#11 module from a dynamic library file, and
 324 initialize it. Normally using the <a class="link" href="p11-kit-Modules.html#p11-kit-initialize-registered" title="p11_kit_initialize_registered ()"><code class="function">p11_kit_initialize_registered()</code></a> function
 325 is preferred.
 326 </p>
 327 <p>
 328 Using this function to load and initialize modules allows coordination between
 329 multiple users of the same module in a single process. The caller should not
 330 call the module's <code class="code">C_Initialize</code> method. This function will call
 331 <code class="code">C_Initialize</code> as necessary.
 332 </p>
 333 <p>
 334 If a module has already been loaded, then use of this function is unnecesasry.
 335 Instead use the <a class="link" href="p11-kit-Modules.html#p11-kit-initialize-module" title="p11_kit_initialize_module ()"><code class="function">p11_kit_initialize_module()</code></a> function to initialize it.
 336 </p>
 337 <p>
 338 Subsequent calls to this function for the same module will result in an
 339 initialization count being incremented for the module. It is safe (although
 340 usually unnecessary) to use this function on registered modules.
 341 </p>
 342 <p>
 343 The module must be finalized with <a class="link" href="p11-kit-Modules.html#p11-kit-finalize-module" title="p11_kit_finalize_module ()"><code class="function">p11_kit_finalize_module()</code></a> instead of
 344 calling its <code class="code">C_Finalize</code> method directly.
 345 </p>
 346 <p>
 347 This function does not accept a <code class="code">CK_C_INITIALIZE_ARGS</code> argument.
 348 Custom initialization arguments cannot be supported when multiple consumers
 349 load the same module.
 350 </p>
 351 <p>
 352 If this function fails, then an error message will be available via the
 353 <a class="link" href="p11-kit-Future.html#p11-kit-message" title="p11_kit_message ()"><code class="function">p11_kit_message()</code></a> function.
 354 </p>
 355 <div class="variablelist"><table border="0" class="variablelist">
 356 <colgroup>
 357 <col align="left" valign="top">
 358 <col>
 359 </colgroup>
 360 <tbody>
 361 <tr>
 362 <td><p><span class="term"><em class="parameter"><code>module_path</code></em> :</span></p></td>
 363 <td>full file path of module library</td>
 364 </tr>
 365 <tr>
 366 <td><p><span class="term"><em class="parameter"><code>module</code></em> :</span></p></td>
 367 <td>location to place loaded module pointer</td>
 368 </tr>
 369 <tr>
 370 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 371 <td>CKR_OK if the initialization was successful.</td>
 372 </tr>
 373 </tbody>
 374 </table></div>
 375 </div>
 376 <hr>
 377 <div class="refsect2">
 378 <a name="p11-kit-finalize-module"></a><h3>p11_kit_finalize_module ()</h3>
 379 <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>
 380 <p>
 381 Finalize an arbitrary PKCS#11 module. The module must have been initialized
 382 using <a class="link" href="p11-kit-Modules.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
 383 <a class="link" href="p11-kit-Modules.html#p11-kit-finalize-registered" title="p11_kit_finalize_registered ()"><code class="function">p11_kit_finalize_registered()</code></a> instead of this function.
 384 </p>
 385 <p>
 386 Using this function to finalize modules allows coordination between
 387 multiple users of the same module in a single process. The caller should
 388 call the module's <code class="code">C_Finalize</code> method. This function will call
 389 <code class="code">C_Finalize</code> as necessary.
 390 </p>
 391 <p>
 392 If the module was initialized more than once, then this function will
 393 decrement an initialization count for the module. When the count reaches zero
 394 the module will be truly finalized. It is safe (although usually unnecessary)
 395 to use this function on registered modules if (and only if) they were
 396 initialized using <a class="link" href="p11-kit-Modules.html#p11-kit-initialize-module" title="p11_kit_initialize_module ()"><code class="function">p11_kit_initialize_module()</code></a> for some reason.
 397 </p>
 398 <p>
 399 If this function fails, then an error message will be available via the
 400 <a class="link" href="p11-kit-Future.html#p11-kit-message" title="p11_kit_message ()"><code class="function">p11_kit_message()</code></a> function.
 401 </p>
 402 <div class="variablelist"><table border="0" class="variablelist">
 403 <colgroup>
 404 <col align="left" valign="top">
 405 <col>
 406 </colgroup>
 407 <tbody>
 408 <tr>
 409 <td><p><span class="term"><em class="parameter"><code>module</code></em> :</span></p></td>
 410 <td>loaded module to finalize.</td>
 411 </tr>
 412 <tr>
 413 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 414 <td>CKR_OK if the finalization was successful.</td>
 415 </tr>
 416 </tbody>
 417 </table></div>
 418 </div>
 419 </div>
 420 </div>
 421 <div class="footer">
 422 <hr>
 423           Generated by GTK-Doc V1.19</div>
 424 </body>
 425 </html>