e2sim/ASN1c/asn_application.h

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