Standard preamble:
========================================================================
..
.... Set up some character translations and predefined strings. \*(-- will
give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
double quote, and \*(R" will give a right double quote. \*(C+ will
give a nicer C++. Capital omega is used to do unbreakable dashes and
therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
nothing in troff, for use with C<>.
.tr \(*W- . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\}
Escape single quotes in literal strings from groff's Unicode transform.
If the F register is >0, we'll generate index entries on stderr for
titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
entries marked with X<> in POD. Of course, you'll have to process the
output yourself in some meaningful fashion.
Avoid warning from groff about undefined register 'F'.
.. .nr rF 0 . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] .\} . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents . \" corrections for vroff . \" for low resolution devices (crt and lpr) \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} ========================================================================
Title "OSSL_DECODER_CTX 3ossl"
way too many mistakes in technical documents.
The chains may be limited by specifying an input type, which is considered a starting point. This is both considered by OSSL_DECODER_CTX_add_extra(), which will stop adding one more decoder implementations when it has already added those that take the specified input type, and functions like \fBOSSL_DECODER_from_bio\|(3), which will only start the decoding process with the decoder implementations that take that input type. For example, if the input type is set to \*(C`DER\*(C', a \s-1PEM\s0 to \s-1DER\s0 decoder will be ignored.
The input type can also be \s-1NULL,\s0 which means that the caller doesn't know what type of input they have. In this case, OSSL_DECODER_from_bio() will simply try with one decoder implementation after the other, and thereby discover what kind of input the caller gave it.
For every decoding done, even an intermediary one, a constructor provided by the caller is called to attempt to construct an appropriate type / structure that the caller knows how to handle from the current decoding result. The constructor is set with OSSL_DECODER_CTX_set_construct().
\fB\s-1OSSL_DECODER_INSTANCE\s0 is an opaque structure that contains data about the decoder that was just used, and that may be useful for the constructor. There are some functions to extract data from this type, described further down.
\fBOSSL_DECODER_settable_ctx_params() returns an \s-1OSSL_PARAM\s0\|(3) array of parameter descriptors.
\fBOSSL_DECODER_CTX_set_params() attempts to set parameters specified with an \s-1OSSL_PARAM\s0\|(3) array params. These parameters are passed to all decoders that have been added to the ctx so far. Parameters that an implementation doesn't recognise should be ignored by it.
\fBOSSL_DECODER_CTX_free() frees the given context ctx.
\fBOSSL_DECODER_CTX_add_decoder() populates the \s-1OSSL_DECODER_CTX\s0 ctx with a decoder, to be used to attempt to decode some encoded input.
\fBOSSL_DECODER_CTX_add_extra() finds decoders that generate input for already added decoders, and adds them as well. This is used to build decoder chains.
\fBOSSL_DECODER_CTX_set_input_type() sets the starting input type. This limits the decoder chains to be considered, as explained in the general description above.
\fBOSSL_DECODER_CTX_set_input_structure() sets the name of the structure that the input is expected to have. This may be used to determines what decoder implementations may be used. \s-1NULL\s0 is a valid input structure, when it's not relevant, or when the decoder implementations are expected to figure it out.
\fBOSSL_DECODER_CTX_get_num_decoders() gets the number of decoders currently added to the context ctx.
\fBOSSL_DECODER_CTX_set_construct() sets the constructor construct.
\fBOSSL_DECODER_CTX_set_construct_data() sets the constructor data that is passed to the constructor every time it's called.
\fBOSSL_DECODER_CTX_set_cleanup() sets the constructor data cleanup function. This is called by OSSL_DECODER_CTX_free\|(3).
\fBOSSL_DECODER_CTX_get_construct(), OSSL_DECODER_CTX_get_construct_data() and \fBOSSL_DECODER_CTX_get_cleanup() return the values that have been set by \fBOSSL_DECODER_CTX_set_construct(), OSSL_DECODER_CTX_set_construct_data() and \fBOSSL_DECODER_CTX_set_cleanup() respectively.
\fBOSSL_DECODER_export() is a fallback function for constructors that cannot use the data they get directly for diverse reasons. It takes the same decode instance decoder_inst that the constructor got and an object \fIreference, unpacks the object which it refers to, and exports it by creating an \s-1OSSL_PARAM\s0\|(3) array that it then passes to export_cb, along with export_arg.
The constructor is expected to return 1 when the data it receives can be constructed, otherwise 0.
These utility functions may be used by a constructor:
\fBOSSL_DECODER_INSTANCE_get_decoder() can be used to get the decoder implementation from a decoder instance decoder_inst.
\fBOSSL_DECODER_INSTANCE_get_decoder_ctx() can be used to get the decoder implementation's provider context from a decoder instance decoder_inst.
\fBOSSL_DECODER_INSTANCE_get_input_type() can be used to get the decoder implementation's input type from a decoder instance decoder_inst.
\fBOSSL_DECODER_INSTANCE_get_input_structure() can be used to get the input structure for the decoder implementation from a decoder instance \fIdecoder_inst. This may be \s-1NULL.\s0
\fBOSSL_DECODER_settable_ctx_params() returns an \s-1OSSL_PARAM\s0\|(3) array, or \s-1NULL\s0 if none is available.
\fBOSSL_DECODER_CTX_set_params() returns 1 if all recognised parameters were valid, or 0 if one of them was invalid or caused some other failure in the implementation.
\fBOSSL_DECODER_CTX_add_decoder(), OSSL_DECODER_CTX_add_extra(), \fBOSSL_DECODER_CTX_set_construct(), OSSL_DECODER_CTX_set_construct_data() and \fBOSSL_DECODER_CTX_set_cleanup() return 1 on success, or 0 on failure.
\fBOSSL_DECODER_CTX_get_construct(), OSSL_DECODER_CTX_get_construct_data() and \fBOSSL_DECODER_CTX_get_cleanup() return the current pointers to the constructor, the constructor data and the cleanup functions, respectively.
\fBOSSL_DECODER_CTX_num_decoders() returns the current number of decoders. It returns 0 if ctx is \s-1NULL.\s0
\fBOSSL_DECODER_export() returns 1 on success, or 0 on failure.
\fBOSSL_DECODER_INSTANCE_decoder() returns an \s-1OSSL_DECODER\s0 pointer on success, or \s-1NULL\s0 on failure.
\fBOSSL_DECODER_INSTANCE_decoder_ctx() returns a provider context pointer on success, or \s-1NULL\s0 on failure.
Licensed under the Apache License 2.0 (the \*(L"License\*(R"). You may not use this file except in compliance with the License. You can obtain a copy in the file \s-1LICENSE\s0 in the source distribution or at <https://www.openssl.org/source/license.html>.