doc/man3/OSSL_SERIALIZER_CTX.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 OSSL_SERIALIZER_CTX,
   6 OSSL_SERIALIZER_CTX_new,
   7 OSSL_SERIALIZER_CTX_get_serializer,
   8 OSSL_SERIALIZER_settable_ctx_params,
   9 OSSL_SERIALIZER_CTX_set_params,
  10 OSSL_SERIALIZER_CTX_free
  11 - Serializer context routines
  12
  13 =head1 SYNOPSIS
  14
  15  #include <openssl/serializer.h>
  16
  17  typedef struct ossl_serializer_ctx_st OSSL_SERIALIZER_CTX;
  18
  19  OSSL_SERIALIZER_CTX *OSSL_SERIALIZER_CTX_new(OSSL_SERIALIZER *ser);
  20  const OSSL_SERIALIZER *
  21  OSSL_SERIALIZER_CTX_get_serializer(OSSL_SERIALIZER_CTX *ctx);
  22  const OSSL_PARAM *OSSL_SERIALIZER_settable_ctx_params(OSSL_SERIALIZER *ser);
  23  int OSSL_SERIALIZER_CTX_set_params(OSSL_SERIALIZER_CTX *ctx,
  24                                     const OSSL_PARAM params[]);
  25  void OSSL_SERIALIZER_CTX_free(OSSL_SERIALIZER_CTX *ctx);
  26
  27 =head1 DESCRIPTION
  28
  29 B<OSSL_SERIALIZER_CTX> is a context with which B<OSSL_SERIALIZER>
  30 operations are performed.  The context typically holds values, both
  31 internal and supplied by the application, which are useful for the
  32 implementations supplied by providers.
  33
  34 OSSL_SERIALIZER_CTX_new() creates a B<OSSL_SERIALIZER_CTX> associated
  35 with the serializer I<ser>.  NULL is a valid I<ser>, the context will
  36 be created anyway, it's just not very useful.  This is intentional, to
  37 distinguish between errors in allocating the context or assigning it
  38 values on one hand, and the lack of serializer support on the other.
  39
  40 =begin comment
  41
  42 The above distinction makes it possible for other routines to sense if
  43 they need to report an error or fall back on other methods to
  44 serialize.
  45
  46 =end comment
  47
  48 OSSL_SERIALIZER_CTX_get_serializer() gets the serializer method
  49 currently associated with the context I<ctx>.
  50
  51 OSSL_SERIALIZER_settable_ctx_params() returns an L<OSSL_PARAM(3)>
  52 array of parameter descriptors.
  53
  54 OSSL_SERIALIZER_CTX_set_params() attempts to set parameters specified
  55 with an L<OSSL_PARAM(3)> array I<params>.  Parameters that the
  56 implementation doesn't recognise should be ignored.
  57
  58 OSSL_SERIALIZER_CTX_free() frees the given context I<ctx>.
  59
  60 =head1 RETURN VALUES
  61
  62 OSSL_SERIALIZER_CTX_new() returns a pointer to a
  63 B<OSSL_SERIALIZER_CTX>, or NULL if the context structure couldn't be
  64 allocated.
  65
  66 OSSL_SERIALIZER_CTX_get_serializer() returns a pointer to the
  67 serializer method associated with I<ctx>.  NULL is a valid return
  68 value and signifies that there is no associated serializer method.
  69
  70 OSSL_SERIALIZER_settable_ctx_params() returns an L<OSSL_PARAM(3)>
  71 array, or NULL if none is available.
  72
  73 OSSL_SERIALIZER_CTX_set_params() returns 1 if all recognised
  74 parameters were valid, or 0 if one of them was invalid or caused some
  75 other failure in the implementation.
  76
  77 =head1 SEE ALSO
  78
  79 L<provider(7)>, L<OSSL_SERIALIZER(3)>
  80
  81 =head1 HISTORY
  82
  83 The functions described here were added in OpenSSL 3.0.
  84
  85 =head1 COPYRIGHT
  86
  87 Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.
  88
  89 Licensed under the Apache License 2.0 (the "License").  You may not use
  90 this file except in compliance with the License.  You can obtain a copy
  91 in the file LICENSE in the source distribution or at
  92 L<https://www.openssl.org/source/license.html>.
  93
  94 =cut