asn1c_defs/all-defs/asn_application.h

   1 /*-\r
   2  * Copyright (c) 2004-2017 Lev Walkin <vlm@lionet.info>. All rights reserved.\r
   3  * Redistribution and modifications are permitted subject to BSD license.\r
   4  */\r
   5 /*\r
   6  * Application-level ASN.1 callbacks.\r
   7  */\r
   8 #ifndef ASN_APPLICATION_H\r
   9 #define ASN_APPLICATION_H\r
  10 \r
  11 #include "asn_system.h"         /* for platform-dependent types */\r
  12 #include "asn_codecs.h"         /* for ASN.1 codecs specifics */\r
  13 \r
  14 #ifdef __cplusplus\r
  15 extern "C" {\r
  16 #endif\r
  17 \r
  18 /*\r
  19  * A selection of ASN.1 Transfer Syntaxes to use with generalized\r
  20  * encoders and decoders declared further in this .h file.\r
  21  */\r
  22 enum asn_transfer_syntax {\r
  23     /* Avoid appearance of a default transfer syntax. */\r
  24     ATS_INVALID = 0,\r
  25     /* Plaintext output (not conforming to any standard), for debugging. */\r
  26     ATS_NONSTANDARD_PLAINTEXT,\r
  27     /* Returns a randomly generated structure. */\r
  28     ATS_RANDOM,\r
  29     /*\r
  30      * X.690:\r
  31      * BER: Basic Encoding Rules.\r
  32      * DER: Distinguished Encoding Rules.\r
  33      * CER: Canonical Encoding Rules.\r
  34      * DER and CER are more strict variants of BER.\r
  35      */\r
  36     ATS_BER,\r
  37     ATS_DER,\r
  38     ATS_CER, /* Only decoding is supported */\r
  39     /*\r
  40      * X.696:\r
  41      * OER: Octet Encoding Rules.\r
  42      * CANONICAL-OER is a more strict variant of BASIC-OER.\r
  43      */\r
  44     ATS_BASIC_OER,\r
  45     ATS_CANONICAL_OER,\r
  46     /*\r
  47      * X.691:\r
  48      * PER: Packed Encoding Rules.\r
  49      * CANONICAL-PER is a more strict variant of BASIC-PER.\r
  50      * NOTE: Produces or consumes a complete encoding (X.691 (08/2015) #11.1).\r
  51      */\r
  52     ATS_UNALIGNED_BASIC_PER,\r
  53     ATS_UNALIGNED_CANONICAL_PER,\r
  54     ATS_ALIGNED_BASIC_PER,\r
  55     ATS_ALIGNED_CANONICAL_PER,\r
  56     /*\r
  57      * X.693:\r
  58      * XER: XML Encoding Rules.\r
  59      * CANONICAL-XER is a more strict variant of BASIC-XER.\r
  60      */\r
  61     ATS_BASIC_XER,\r
  62     ATS_CANONICAL_XER\r
  63 };\r
  64 \r
  65 /*\r
  66  * A generic encoder for any supported transfer syntax.\r
  67  * RETURN VALUES:\r
  68  * The (.encoded) field of the return value is REDEFINED to mean the following:\r
  69  * >=0: The computed size of the encoded data. Can exceed the (buffer_size).\r
  70  *  -1: Error encoding the structure. See the error code in (errno):\r
  71  *      EINVAL: Incorrect parameters to the function, such as NULLs.\r
  72  *      ENOENT: Encoding transfer syntax is not defined (for this type).\r
  73  *      EBADF:  The structure has invalid form or content constraint failed.\r
  74  *      The (.failed_type) and (.structure_ptr) MIGHT be set to the appropriate\r
  75  *      values at the place of failure, if at all possible.\r
  76  * WARNING: The (.encoded) field of the return value can exceed the buffer_size.\r
  77  * This is similar to snprintf(3) contract which might return values\r
  78  * greater than the buffer size.\r
  79  */\r
  80 asn_enc_rval_t asn_encode_to_buffer(\r
  81     const asn_codec_ctx_t *opt_codec_parameters, /* See asn_codecs.h */\r
  82     enum asn_transfer_syntax,\r
  83     const struct asn_TYPE_descriptor_s *type_to_encode,\r
  84     const void *structure_to_encode, void *buffer, size_t buffer_size);\r
  85 \r
  86 /*\r
  87  * A variant of asn_encode_to_buffer() with automatically allocated buffer.\r
  88  * RETURN VALUES:\r
  89  * On success, returns a newly allocated (.buffer) containing the whole message.\r
  90  * The message size is returned in (.result.encoded).\r
  91  * On failure:\r
  92  *  (.buffer) is NULL,\r
  93  *  (.result.encoded) as in asn_encode_to_buffer(),\r
  94  *  The errno codes as in asn_encode_to_buffer(), plus the following:\r
  95  *      ENOMEM: Memory allocation failed due to system or internal limits.\r
  96  * The user is responsible for freeing the (.buffer).\r
  97  */\r
  98 typedef struct asn_encode_to_new_buffer_result_s {\r
  99     void *buffer;   /* NULL if failed to encode. */\r
 100     asn_enc_rval_t result;\r
 101 } asn_encode_to_new_buffer_result_t;\r
 102 asn_encode_to_new_buffer_result_t asn_encode_to_new_buffer(\r
 103     const asn_codec_ctx_t *opt_codec_parameters, /* See asn_codecs.h */\r
 104     enum asn_transfer_syntax,\r
 105     const struct asn_TYPE_descriptor_s *type_to_encode,\r
 106     const void *structure_to_encode);\r
 107 \r
 108 \r
 109 /*\r
 110  * Generic type of an application-defined callback to return various\r
 111  * types of data to the application.\r
 112  * EXPECTED RETURN VALUES:\r
 113  *  -1: Failed to consume bytes. Abort the mission.\r
 114  * Non-negative return values indicate success, and ignored.\r
 115  */\r
 116 typedef int(asn_app_consume_bytes_f)(const void *buffer, size_t size,\r
 117                                      void *application_specific_key);\r
 118 \r
 119 \r
 120 /*\r
 121  * A generic encoder for any supported transfer syntax.\r
 122  * Returns the comprehensive encoding result descriptor (see asn_codecs.h).\r
 123  * RETURN VALUES:\r
 124  * The negative (.encoded) field of the return values is accompanied with the\r
 125  * following error codes (errno):\r
 126  *      EINVAL: Incorrect parameters to the function, such as NULLs.\r
 127  *      ENOENT: Encoding transfer syntax is not defined (for this type).\r
 128  *      EBADF:  The structure has invalid form or content constraint failed.\r
 129  *      EIO:    The (callback) has returned negative value during encoding.\r
 130  */\r
 131 asn_enc_rval_t asn_encode(\r
 132     const asn_codec_ctx_t *opt_codec_parameters, /* See asn_codecs.h */\r
 133     enum asn_transfer_syntax,\r
 134     const struct asn_TYPE_descriptor_s *type_to_encode,\r
 135     const void *structure_to_encode,\r
 136     asn_app_consume_bytes_f *callback, void *callback_key);\r
 137 \r
 138 \r
 139 /*\r
 140  * A generic decoder for any supported transfer syntax.\r
 141  */\r
 142 asn_dec_rval_t asn_decode(\r
 143     const asn_codec_ctx_t *opt_codec_parameters, enum asn_transfer_syntax,\r
 144     const struct asn_TYPE_descriptor_s *type_to_decode,\r
 145     void **structure_ptr, /* Pointer to a target structure's pointer */\r
 146     const void *buffer,   /* Data to be decoded */\r
 147     size_t size           /* Size of that buffer */\r
 148 );\r
 149 \r
 150 \r
 151 /*\r
 152  * A callback of this type is called whenever constraint validation fails\r
 153  * on some ASN.1 type. See "constraints.h" for more details on constraint\r
 154  * validation.\r
 155  * This callback specifies a descriptor of the ASN.1 type which failed\r
 156  * the constraint check, as well as human readable message on what\r
 157  * particular constraint has failed.\r
 158  */\r
 159 typedef void (asn_app_constraint_failed_f)(void *application_specific_key,\r
 160         const struct asn_TYPE_descriptor_s *type_descriptor_which_failed,\r
 161         const void *structure_which_failed_ptr,\r
 162         const char *error_message_format, ...) CC_PRINTFLIKE(4, 5);\r
 163 \r
 164 \r
 165 #ifdef __cplusplus\r
 166 }\r
 167 #endif\r
 168 \r
 169 #include "constr_TYPE.h"        /* for asn_TYPE_descriptor_t */\r
 170 \r
 171 #endif  /* ASN_APPLICATION_H */\r