doc/crypto/BIO_meth_new.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 BIO_meth_new, BIO_meth_free, BIO_meth_get_write, BIO_meth_set_write,
   6 BIO_meth_get_read, BIO_meth_set_read, BIO_meth_get_puts, BIO_meth_set_puts,
   7 BIO_meth_get_gets, BIO_meth_set_gets, BIO_meth_get_ctrl, BIO_meth_set_ctrl,
   8 BIO_meth_get_create, BIO_meth_set_create, BIO_meth_get_destroy,
   9 BIO_meth_set_destroy, BIO_meth_get_callback_ctrl,
  10 BIO_meth_set_callback_ctrl  - Routines to build up BIO methods
  11
  12 =head1 SYNOPSIS
  13
  14  #include <openssl/bio.h>
  15
  16  BIO_METHOD *BIO_meth_new(int type, const char *name);
  17  void BIO_meth_free(BIO_METHOD *biom);
  18  int (*BIO_meth_get_write(BIO_METHOD *biom)) (BIO *, const char *, int);
  19  int BIO_meth_set_write(BIO_METHOD *biom,
  20                         int (*write) (BIO *, const char *, int));
  21  int (*BIO_meth_get_read(BIO_METHOD *biom)) (BIO *, char *, int);
  22  int BIO_meth_set_read(BIO_METHOD *biom,
  23                        int (*read) (BIO *, char *, int));
  24  int (*BIO_meth_get_puts(BIO_METHOD *biom)) (BIO *, const char *);
  25  int BIO_meth_set_puts(BIO_METHOD *biom,
  26                        int (*puts) (BIO *, const char *));
  27  int (*BIO_meth_get_gets(BIO_METHOD *biom)) (BIO *, char *, int);
  28  int BIO_meth_set_gets(BIO_METHOD *biom,
  29                        int (*gets) (BIO *, char *, int));
  30  long (*BIO_meth_get_ctrl(BIO_METHOD *biom)) (BIO *, int, long, void *);
  31  int BIO_meth_set_ctrl(BIO_METHOD *biom,
  32                        long (*ctrl) (BIO *, int, long, void *));
  33  int (*BIO_meth_get_create(BIO_METHOD *bion)) (BIO *);
  34  int BIO_meth_set_create(BIO_METHOD *biom, int (*create) (BIO *));
  35  int (*BIO_meth_get_destroy(BIO_METHOD *biom)) (BIO *);
  36  int BIO_meth_set_destroy(BIO_METHOD *biom, int (*destroy) (BIO *));
  37  long (*BIO_meth_get_callback_ctrl(BIO_METHOD *biom))
  38                                   (BIO *, int, bio_info_cb *);
  39  int BIO_meth_set_callback_ctrl(BIO_METHOD *biom,
  40                                 long (*callback_ctrl) (BIO *, int,
  41                                                       bio_info_cb *));
  42
  43 =head1 DESCRIPTION
  44
  45 The B<BIO_METHOD> type is a structure used for the implementation of new BIO
  46 types. It provides a set of of functions used by OpenSSL for the implementation
  47 of the various BIO capabilities. See the L<bio> page for more information.
  48
  49 BIO_meth_new() creates a new B<BIO_METHOD> structure. It should be given a
  50 unique integer B<type> and a string that represents its B<name>. The set of
  51 standard OpenSSL provided BIO types is provided in B<bio.h>. Some examples
  52 include B<BIO_TYPE_BUFFER> and B<BIO_TYPE_CIPHER>. Filter BIOs should have a
  53 type which have the "filter" bit set (B<BIO_TYPE_FILTER>). Source/sink BIOs
  54 should have the "source/sink" bit set (B<BIO_TYPE_SOURCE_SINK>). File descriptor
  55 based BIOs (e.g. socket, fd, connect, accept etc) should additionally have the
  56 "descriptor" bit set (B<BIO_TYPE_DESCRIPTOR>). See the L<BIO_find_type> page for
  57 more information.
  58
  59 BIO_meth_free() destroys a B<BIO_METHOD> structure and frees up any memory
  60 associated with it.
  61
  62 BIO_meth_get_write() and BIO_meth_set_write() get and set the function used for
  63 writing arbitrary length data to the BIO respectively. This function will be
  64 called in response to the application calling BIO_write(). The parameters for
  65 the function have the same meaning as for BIO_write().
  66
  67 BIO_meth_get_read() and BIO_meth_set_read() get and set the function used for
  68 reading arbitrary length data from the BIO respectively. This function will be
  69 called in response to the application calling BIO_read(). The parameters for the
  70 function have the same meaning as for BIO_read().
  71
  72 BIO_meth_get_puts() and BIO_meth_set_puts() get and set the function used for
  73 writing a NULL terminated string to the BIO respectively. This function will be
  74 called in response to the application calling BIO_puts(). The parameters for
  75 the function have the same meaning as for BIO_puts().
  76
  77 BIO_meth_get_gets() and BIO_meth_set_gets() get and set the function typically
  78 used for reading a line of data from the BIO respectively (see the L<BIO_gets(3)>
  79 page for more information). This function will be called in response to the
  80 application calling BIO_gets(). The parameters for the function have the same
  81 meaning as for BIO_gets().
  82
  83 BIO_meth_get_ctrl() and BIO_meth_set_ctrl() get and set the function used for
  84 processing ctrl messages in the BIO respectively. See the L<BIO_ctrl> page for
  85 more information. This function will be called in response to the application
  86 calling BIO_ctrl(). The parameters for the function have the same meaning as for
  87 BIO_ctrl().
  88
  89 BIO_meth_get_create() and BIO_meth_set_create() get and set the function used
  90 for creating a new instance of the BIO respectively. This function will be
  91 called in response to the application calling BIO_new() and passing
  92 in a pointer to the current BIO_METHOD. The BIO_new() function will allocate the
  93 memory for the new BIO, and a pointer to this newly allocated structure will
  94 be passed as a parameter to the function.
  95
  96 BIO_meth_get_destroy() and BIO_meth_set_destroy() get and set the function used
  97 for destroying an instance of a BIO respectively. This function will be
  98 called in response to the application calling BIO_free(). A pointer to the BIO
  99 to be destroyed is passed as a parameter. The destroy function should be used
 100 for BIO specific clean up. The memory for the BIO itself should not be freed by
 101 this function.
 102
 103 BIO_meth_get_callback_ctrl() and BIO_meth_set_callback_ctrl() get and set the
 104 function used for processing callback ctrl messages in the BIO respectively. See
 105 the L<BIO_callback_ctrl(3)> page for more information. This function will be called
 106 in response to the application calling BIO_callback_ctrl(). The parameters for
 107 the function have the same meaning as for BIO_callback_ctrl().
 108
 109 =head1 SEE ALSO
 110
 111 L<bio>, L<BIO_find_type>, L<BIO_ctrl>, L<BIO_read>, L<BIO_new>
 112
 113 =head1 HISTORY
 114
 115 The functions described here were added in OpenSSL version 1.1.0.
 116
 117 =head1 COPYRIGHT
 118
 119 Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
 120
 121 Licensed under the OpenSSL license (the "License").  You may not use
 122 this file except in compliance with the License.  You can obtain a copy
 123 in the file LICENSE in the source distribution or at
 124 L<https://www.openssl.org/source/license.html>.
 125
 126 =cut