| Current Path : /usr/opt/openssl11/share/doc/openssl/html/man3/ |
FreeBSD hs32.drive.ne.jp 9.1-RELEASE FreeBSD 9.1-RELEASE #1: Wed Jan 14 12:18:08 JST 2015 root@hs32.drive.ne.jp:/sys/amd64/compile/hs32 amd64 |
| Current File : //usr/opt/openssl11/share/doc/openssl/html/man3/OSSL_STORE_LOADER_set_ctrl.html |
<?xml version="1.0" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>OSSL_STORE_LOADER</title>
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
<link rev="made" href="mailto:root@hsxx.drive.ne.jp" />
</head>
<body style="background-color: white">
<!-- INDEX BEGIN -->
<div name="index">
<p><a name="__index__"></a></p>
<ul>
<li><a href="#name">NAME</a></li>
<li><a href="#synopsis">SYNOPSIS</a></li>
<li><a href="#description">DESCRIPTION</a></li>
<ul>
<li><a href="#types">Types</a></li>
<li><a href="#functions">Functions</a></li>
</ul>
<li><a href="#notes">NOTES</a></li>
<li><a href="#return_values">RETURN VALUES</a></li>
<li><a href="#see_also">SEE ALSO</a></li>
<li><a href="#history">HISTORY</a></li>
<li><a href="#copyright">COPYRIGHT</a></li>
</ul>
<hr name="index" />
</div>
<!-- INDEX END -->
<p>
</p>
<hr />
<h1><a name="name">NAME</a></h1>
<p>OSSL_STORE_LOADER, OSSL_STORE_LOADER_CTX, OSSL_STORE_LOADER_new,
OSSL_STORE_LOADER_get0_engine, OSSL_STORE_LOADER_get0_scheme,
OSSL_STORE_LOADER_set_open, OSSL_STORE_LOADER_set_ctrl,
OSSL_STORE_LOADER_set_expect, OSSL_STORE_LOADER_set_find,
OSSL_STORE_LOADER_set_load, OSSL_STORE_LOADER_set_eof,
OSSL_STORE_LOADER_set_error, OSSL_STORE_LOADER_set_close,
OSSL_STORE_LOADER_free, OSSL_STORE_register_loader,
OSSL_STORE_unregister_loader, OSSL_STORE_open_fn, OSSL_STORE_ctrl_fn,
OSSL_STORE_expect_fn, OSSL_STORE_find_fn,
OSSL_STORE_load_fn, OSSL_STORE_eof_fn, OSSL_STORE_error_fn,
OSSL_STORE_close_fn - Types and functions to manipulate, register and
unregister STORE loaders for different URI schemes</p>
<p>
</p>
<hr />
<h1><a name="synopsis">SYNOPSIS</a></h1>
<pre>
#include <openssl/store.h></pre>
<pre>
typedef struct ossl_store_loader_st OSSL_STORE_LOADER;</pre>
<pre>
OSSL_STORE_LOADER *OSSL_STORE_LOADER_new(ENGINE *e, const char *scheme);
const ENGINE *OSSL_STORE_LOADER_get0_engine(const OSSL_STORE_LOADER
*store_loader);
const char *OSSL_STORE_LOADER_get0_scheme(const OSSL_STORE_LOADER
*store_loader);</pre>
<pre>
/* struct ossl_store_loader_ctx_st is defined differently by each loader */
typedef struct ossl_store_loader_ctx_st OSSL_STORE_LOADER_CTX;</pre>
<pre>
typedef OSSL_STORE_LOADER_CTX *(*OSSL_STORE_open_fn)(const char *uri,
const UI_METHOD *ui_method,
void *ui_data);
int OSSL_STORE_LOADER_set_open(OSSL_STORE_LOADER *store_loader,
OSSL_STORE_open_fn store_open_function);
typedef int (*OSSL_STORE_ctrl_fn)(OSSL_STORE_LOADER_CTX *ctx, int cmd,
va_list args);
int OSSL_STORE_LOADER_set_ctrl(OSSL_STORE_LOADER *store_loader,
OSSL_STORE_ctrl_fn store_ctrl_function);
typedef int (*OSSL_STORE_expect_fn)(OSSL_STORE_LOADER_CTX *ctx, int expected);
int OSSL_STORE_LOADER_set_expect(OSSL_STORE_LOADER *loader,
OSSL_STORE_expect_fn expect_function);
typedef int (*OSSL_STORE_find_fn)(OSSL_STORE_LOADER_CTX *ctx,
OSSL_STORE_SEARCH *criteria);
int OSSL_STORE_LOADER_set_find(OSSL_STORE_LOADER *loader,
OSSL_STORE_find_fn find_function);
typedef OSSL_STORE_INFO *(*OSSL_STORE_load_fn)(OSSL_STORE_LOADER_CTX *ctx,
UI_METHOD *ui_method,
void *ui_data);
int OSSL_STORE_LOADER_set_load(OSSL_STORE_LOADER *store_loader,
OSSL_STORE_load_fn store_load_function);
typedef int (*OSSL_STORE_eof_fn)(OSSL_STORE_LOADER_CTX *ctx);
int OSSL_STORE_LOADER_set_eof(OSSL_STORE_LOADER *store_loader,
OSSL_STORE_eof_fn store_eof_function);
typedef int (*OSSL_STORE_error_fn)(OSSL_STORE_LOADER_CTX *ctx);
int OSSL_STORE_LOADER_set_error(OSSL_STORE_LOADER *store_loader,
OSSL_STORE_error_fn store_error_function);
typedef int (*OSSL_STORE_close_fn)(OSSL_STORE_LOADER_CTX *ctx);
int OSSL_STORE_LOADER_set_close(OSSL_STORE_LOADER *store_loader,
OSSL_STORE_close_fn store_close_function);
void OSSL_STORE_LOADER_free(OSSL_STORE_LOADER *store_loader);</pre>
<pre>
int OSSL_STORE_register_loader(OSSL_STORE_LOADER *loader);
OSSL_STORE_LOADER *OSSL_STORE_unregister_loader(const char *scheme);</pre>
<p>
</p>
<hr />
<h1><a name="description">DESCRIPTION</a></h1>
<p>These functions help applications and engines to create loaders for
schemes they support.</p>
<p>
</p>
<h2><a name="types">Types</a></h2>
<p><strong>OSSL_STORE_LOADER</strong> is the type to hold a loader.
It contains a scheme and the functions needed to implement
<code>OSSL_STORE_open()</code>, <code>OSSL_STORE_load()</code>, <code>OSSL_STORE_eof()</code>, <code>OSSL_STORE_error()</code> and
<code>OSSL_STORE_close()</code> for this scheme.</p>
<p><strong>OSSL_STORE_LOADER_CTX</strong> is a type template, to be defined by each loader
using <strong>struct ossl_store_loader_ctx_st { ... }</strong>.</p>
<p><strong>OSSL_STORE_open_fn</strong>, <strong>OSSL_STORE_ctrl_fn</strong>, <strong>OSSL_STORE_expect_fn</strong>,
<strong>OSSL_STORE_find_fn</strong>, <strong>OSSL_STORE_load_fn</strong>, <strong>OSSL_STORE_eof_fn</strong>,
and <strong>OSSL_STORE_close_fn</strong>
are the function pointer types used within a STORE loader.
The functions pointed at define the functionality of the given loader.</p>
<dl>
<dt><strong><a name="ossl_store_open_fn" class="item"><strong>OSSL_STORE_open_fn</strong></a></strong></dt>
<dd>
<p>This function takes a URI and is expected to interpret it in the best
manner possible according to the scheme the loader implements, it also
takes a <strong>UI_METHOD</strong> and associated data, to be used any time
something needs to be prompted for.
Furthermore, this function is expected to initialize what needs to be
initialized, to create a private data store (<strong>OSSL_STORE_LOADER_CTX</strong>, see
above), and to return it.
If something goes wrong, this function is expected to return NULL.</p>
</dd>
<dt><strong><a name="ossl_store_ctrl_fn" class="item"><strong>OSSL_STORE_ctrl_fn</strong></a></strong></dt>
<dd>
<p>This function takes a <strong>OSSL_STORE_LOADER_CTX</strong> pointer, a command number
<strong>cmd</strong> and a <strong>va_list</strong> <strong>args</strong> and is used to manipulate loader
specific parameters.</p>
<p>Loader specific command numbers must begin at <strong>OSSL_STORE_C_CUSTOM_START</strong>.
Any number below that is reserved for future globally known command
numbers.</p>
<p>This function is expected to return 1 on success, 0 on error.</p>
</dd>
<dt><strong><a name="ossl_store_expect_fn" class="item"><strong>OSSL_STORE_expect_fn</strong></a></strong></dt>
<dd>
<p>This function takes a <strong>OSSL_STORE_LOADER_CTX</strong> pointer and a <strong>OSSL_STORE_INFO</strong>
identity <strong>expected</strong>, and is used to tell the loader what object type is
expected.
<strong>expected</strong> may be zero to signify that no specific object type is expected.</p>
<p>This function is expected to return 1 on success, 0 on error.</p>
</dd>
<dt><strong><a name="ossl_store_find_fn" class="item"><strong>OSSL_STORE_find_fn</strong></a></strong></dt>
<dd>
<p>This function takes a <strong>OSSL_STORE_LOADER_CTX</strong> pointer and a
<strong>OSSL_STORE_SEARCH</strong> search criterion, and is used to tell the loader what
to search for.</p>
<p>When called with the loader context being <strong>NULL</strong>, this function is expected
to return 1 if the loader supports the criterion, otherwise 0.</p>
<p>When called with the loader context being something other than <strong>NULL</strong>, this
function is expected to return 1 on success, 0 on error.</p>
</dd>
<dt><strong><a name="ossl_store_load_fn" class="item"><strong>OSSL_STORE_load_fn</strong></a></strong></dt>
<dd>
<p>This function takes a <strong>OSSL_STORE_LOADER_CTX</strong> pointer and a <strong>UI_METHOD</strong>
with associated data.
It's expected to load the next available data, mold it into a data
structure that can be wrapped in a <strong>OSSL_STORE_INFO</strong> using one of the
<em>OSSL_STORE_INFO(3)</em> functions.
If no more data is available or an error occurs, this function is
expected to return NULL.
The <strong>OSSL_STORE_eof_fn</strong> and <strong>OSSL_STORE_error_fn</strong> functions must indicate if
it was in fact the end of data or if an error occurred.</p>
<p>Note that this function retrieves <em>one</em> data item only.</p>
</dd>
<dt><strong><a name="ossl_store_eof_fn" class="item"><strong>OSSL_STORE_eof_fn</strong></a></strong></dt>
<dd>
<p>This function takes a <strong>OSSL_STORE_LOADER_CTX</strong> pointer and is expected to
return 1 to indicate that the end of available data has been reached.
It is otherwise expected to return 0.</p>
</dd>
<dt><strong><a name="ossl_store_error_fn" class="item"><strong>OSSL_STORE_error_fn</strong></a></strong></dt>
<dd>
<p>This function takes a <strong>OSSL_STORE_LOADER_CTX</strong> pointer and is expected to
return 1 to indicate that an error occurred in a previous call to the
<strong>OSSL_STORE_load_fn</strong> function.
It is otherwise expected to return 0.</p>
</dd>
<dt><strong><a name="ossl_store_close_fn" class="item"><strong>OSSL_STORE_close_fn</strong></a></strong></dt>
<dd>
<p>This function takes a <strong>OSSL_STORE_LOADER_CTX</strong> pointer and is expected to
close or shut down what needs to be closed, and finally free the
contents of the <strong>OSSL_STORE_LOADER_CTX</strong> pointer.
It returns 1 on success and 0 on error.</p>
</dd>
</dl>
<p>
</p>
<h2><a name="functions">Functions</a></h2>
<p><code>OSSL_STORE_LOADER_new()</code> creates a new <strong>OSSL_STORE_LOADER</strong>.
It takes an <strong>ENGINE</strong> <strong>e</strong> and a string <strong>scheme</strong>.
<strong>scheme</strong> must <em>always</em> be set.
Both <strong>e</strong> and <strong>scheme</strong> are used as is and must therefore be alive as
long as the created loader is.</p>
<p>OSSL_STORE_LOADER_get0_engine() returns the engine of the <strong>store_loader</strong>.
OSSL_STORE_LOADER_get0_scheme() returns the scheme of the <strong>store_loader</strong>.</p>
<p><code>OSSL_STORE_LOADER_set_open()</code> sets the opener function for the
<strong>store_loader</strong>.</p>
<p><code>OSSL_STORE_LOADER_set_ctrl()</code> sets the control function for the
<strong>store_loader</strong>.</p>
<p><code>OSSL_STORE_LOADER_set_expect()</code> sets the expect function for the
<strong>store_loader</strong>.</p>
<p><code>OSSL_STORE_LOADER_set_load()</code> sets the loader function for the
<strong>store_loader</strong>.</p>
<p><code>OSSL_STORE_LOADER_set_eof()</code> sets the end of file checker function for the
<strong>store_loader</strong>.</p>
<p><code>OSSL_STORE_LOADER_set_close()</code> sets the closing function for the
<strong>store_loader</strong>.</p>
<p><code>OSSL_STORE_LOADER_free()</code> frees the given <strong>store_loader</strong>.</p>
<p><code>OSSL_STORE_register_loader()</code> register the given <strong>store_loader</strong> and thereby
makes it available for use with <code>OSSL_STORE_open()</code>, <code>OSSL_STORE_load()</code>,
<code>OSSL_STORE_eof()</code> and <code>OSSL_STORE_close()</code>.</p>
<p><code>OSSL_STORE_unregister_loader()</code> unregister the store loader for the given
<strong>scheme</strong>.</p>
<p>
</p>
<hr />
<h1><a name="notes">NOTES</a></h1>
<p>The <strong>file:</strong> scheme has built in support.</p>
<p>
</p>
<hr />
<h1><a name="return_values">RETURN VALUES</a></h1>
<p>The functions with the types <strong>OSSL_STORE_open_fn</strong>, <strong>OSSL_STORE_ctrl_fn</strong>,
<strong>OSSL_STORE_expect_fn</strong>,
<strong>OSSL_STORE_load_fn</strong>, <strong>OSSL_STORE_eof_fn</strong> and <strong>OSSL_STORE_close_fn</strong> have the
same return values as <code>OSSL_STORE_open()</code>, <code>OSSL_STORE_ctrl()</code>, <code>OSSL_STORE_expect()</code>,
<code>OSSL_STORE_load()</code>, <code>OSSL_STORE_eof()</code> and <code>OSSL_STORE_close()</code>, respectively.</p>
<p><code>OSSL_STORE_LOADER_new()</code> returns a pointer to a <strong>OSSL_STORE_LOADER</strong> on success,
or <strong>NULL</strong> on failure.</p>
<p><code>OSSL_STORE_LOADER_set_open()</code>, <code>OSSL_STORE_LOADER_set_ctrl()</code>,
<code>OSSL_STORE_LOADER_set_load()</code>, <code>OSSL_STORE_LOADER_set_eof()</code> and
<code>OSSL_STORE_LOADER_set_close()</code> return 1 on success, or 0 on failure.</p>
<p><code>OSSL_STORE_register_loader()</code> returns 1 on success, or 0 on failure.</p>
<p><code>OSSL_STORE_unregister_loader()</code> returns the unregistered loader on success,
or <strong>NULL</strong> on failure.</p>
<p>
</p>
<hr />
<h1><a name="see_also">SEE ALSO</a></h1>
<p><em>ossl_store(7)</em>, <em>OSSL_STORE_open(3)</em></p>
<p>
</p>
<hr />
<h1><a name="history">HISTORY</a></h1>
<p><code>OSSL_STORE_LOADER()</code>, <code>OSSL_STORE_LOADER_CTX()</code>, <code>OSSL_STORE_LOADER_new()</code>,
OSSL_STORE_LOADER_set0_scheme(), <code>OSSL_STORE_LOADER_set_open()</code>,
<code>OSSL_STORE_LOADER_set_ctrl()</code>, <code>OSSL_STORE_LOADER_set_load()</code>,
<code>OSSL_STORE_LOADER_set_eof()</code>, <code>OSSL_STORE_LOADER_set_close()</code>,
<code>OSSL_STORE_LOADER_free()</code>, <code>OSSL_STORE_register_loader()</code>,
<code>OSSL_STORE_unregister_loader()</code>, <a href="#ossl_store_open_fn"><code>OSSL_STORE_open_fn()</code></a>, <a href="#ossl_store_ctrl_fn"><code>OSSL_STORE_ctrl_fn()</code></a>,
<a href="#ossl_store_load_fn"><code>OSSL_STORE_load_fn()</code></a>, <a href="#ossl_store_eof_fn"><code>OSSL_STORE_eof_fn()</code></a> and <a href="#ossl_store_close_fn"><code>OSSL_STORE_close_fn()</code></a>
were added in OpenSSL 1.1.1.</p>
<p>
</p>
<hr />
<h1><a name="copyright">COPYRIGHT</a></h1>
<p>Copyright 2016-2019 The OpenSSL Project Authors. All Rights Reserved.</p>
<p>Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
<a href="https://www.openssl.org/source/license.html">https://www.openssl.org/source/license.html</a>.</p>
</body>
</html>