Latest update.

doc/man3/OSSL_SERIALIZER_CTX.pod

@@ -0,0 +1,94 @@
+=pod
+
+=head1 NAME
+
+OSSL_SERIALIZER_CTX,
+OSSL_SERIALIZER_CTX_new,
+OSSL_SERIALIZER_CTX_get_serializer,
+OSSL_SERIALIZER_settable_ctx_params,
+OSSL_SERIALIZER_CTX_set_params,
+OSSL_SERIALIZER_CTX_free
+- Serializer context routines
+
+=head1 SYNOPSIS
+
+ #include <openssl/serializer.h>
+
+ typedef struct ossl_serializer_ctx_st OSSL_SERIALIZER_CTX;
+
+ OSSL_SERIALIZER_CTX *OSSL_SERIALIZER_CTX_new(OSSL_SERIALIZER *ser);
+ const OSSL_SERIALIZER *
+ OSSL_SERIALIZER_CTX_get_serializer(OSSL_SERIALIZER_CTX *ctx);
+ const OSSL_PARAM *OSSL_SERIALIZER_settable_ctx_params(OSSL_SERIALIZER *ser);
+ int OSSL_SERIALIZER_CTX_set_params(OSSL_SERIALIZER_CTX *ctx,
+                                    const OSSL_PARAM params[]);
+ void OSSL_SERIALIZER_CTX_free(OSSL_SERIALIZER_CTX *ctx);
+
+=head1 DESCRIPTION
+
+B<OSSL_SERIALIZER_CTX> is a context with which B<OSSL_SERIALIZER>
+operations are performed.  The context typically holds values, both
+internal and supplied by the application, which are useful for the
+implementations supplied by providers.
+
+OSSL_SERIALIZER_CTX_new() creates a B<OSSL_SERIALIZER_CTX> associated
+with the serializer I<ser>.  NULL is a valid I<ser>, the context will
+be created anyway, it's just not very useful.  This is intentional, to
+distinguish between errors in allocating the context or assigning it
+values on one hand, and the lack of serializer support on the other.
+
+=begin comment
+
+The above distinction makes it possible for other routines to sense if
+they need to report an error or fall back on other methods to
+serialize.
+
+=end comment
+
+OSSL_SERIALIZER_CTX_get_serializer() gets the serializer method
+currently associated with the context I<ctx>.
+
+OSSL_SERIALIZER_settable_ctx_params() returns an L<OSSL_PARAM(3)>
+array of parameter descriptors.
+
+OSSL_SERIALIZER_CTX_set_params() attempts to set parameters specified
+with an L<OSSL_PARAM(3)> array I<params>.  Parameters that the
+implementation doesn't recognise should be ignored.
+
+OSSL_SERIALIZER_CTX_free() frees the given context I<ctx>.
+
+=head1 RETURN VALUES
+
+OSSL_SERIALIZER_CTX_new() returns a pointer to a
+B<OSSL_SERIALIZER_CTX>, or NULL if the context structure couldn't be
+allocated.
+
+OSSL_SERIALIZER_CTX_get_serializer() returns a pointer to the
+serializer method associated with I<ctx>.  NULL is a valid return
+value and signifies that there is no associated serializer method.
+
+OSSL_SERIALIZER_settable_ctx_params() returns an L<OSSL_PARAM(3)>
+array, or NULL if none is available.
+
+OSSL_SERIALIZER_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.
+
+=head1 SEE ALSO
+
+L<provider(7)>, L<OSSL_SERIALIZER(3)>
+
+=head1 HISTORY
+
+The functions described here were added in OpenSSL 3.0.
+
+=head1 COPYRIGHT
+
+Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the Apache License 2.0 (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
+L<https://www.openssl.org/source/license.html>.
+
+=cut