e2sim/asn1c/asn_application.h

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