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