doc/man3/OSSL_ENCODER_CTX.pod

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