constr_TYPE.h 10 KB
Newer Older
1 2
/*
 * Copyright (c) 2003-2017 Lev Walkin <vlm@lionet.info>. All rights reserved.
Lev Walkin's avatar
Lev Walkin committed
3 4
 * Redistribution and modifications are permitted subject to BSD license.
 */
Lev Walkin's avatar
Lev Walkin committed
5 6 7 8 9 10
/*
 * This file contains the declaration structure called "ASN.1 Type Definition",
 * which holds all information necessary for encoding and decoding routines.
 * This structure even contains pointer to these encoding and decoding routines
 * for each defined ASN.1 type.
 */
Lev Walkin's avatar
Lev Walkin committed
11 12
#ifndef	_CONSTR_TYPE_H_
#define	_CONSTR_TYPE_H_
Lev Walkin's avatar
Lev Walkin committed
13

14 15 16
#include <ber_tlv_length.h>
#include <ber_tlv_tag.h>

Lev Walkin's avatar
Lev Walkin committed
17 18 19 20
#ifdef __cplusplus
extern "C" {
#endif

21 22 23 24 25 26 27 28 29
struct asn_TYPE_descriptor_s;	/* Forward declaration */
struct asn_TYPE_member_s;	/* Forward declaration */

/*
 * This type provides the context information for various ASN.1 routines,
 * primarily ones doing decoding. A member _asn_ctx of this type must be
 * included into certain target language's structures, such as compound types.
 */
typedef struct asn_struct_ctx_s {
Lev Walkin's avatar
Lev Walkin committed
30 31 32
	short phase;		/* Decoding phase */
	short step;		/* Elementary step of a phase */
	int context;		/* Other context information */
33
	void *ptr;		/* Decoder-specific stuff (stack elements) */
Lev Walkin's avatar
Lev Walkin committed
34
	ber_tlv_len_t left;	/* Number of bytes left, -1 for indefinite */
35 36
} asn_struct_ctx_t;

Lev Walkin's avatar
Lev Walkin committed
37 38 39 40
#include <ber_decoder.h>	/* Basic Encoding Rules decoder */
#include <der_encoder.h>	/* Distinguished Encoding Rules encoder */
#include <xer_decoder.h>	/* Decoder of XER (XML, text) */
#include <xer_encoder.h>	/* Encoder into XER (XML, text) */
Lev Walkin's avatar
Lev Walkin committed
41
#include <per_decoder.h>	/* Packet Encoding Rules decoder */
Lev Walkin's avatar
Lev Walkin committed
42
#include <per_encoder.h>	/* Packet Encoding Rules encoder */
43
#include <constraints.h>	/* Subtype constraints support */
44
#include <asn_random_fill.h>	/* Random structures support */
45 46

#ifdef  ASN_DISABLE_OER_SUPPORT
47 48
typedef void (oer_type_decoder_f)(void);
typedef void (oer_type_encoder_f)(void);
Lev Walkin's avatar
Lev Walkin committed
49
typedef void asn_oer_constraints_t;
50
#else
Lev Walkin's avatar
Lev Walkin committed
51 52
#include <oer_decoder.h>	/* Octet Encoding Rules encoder */
#include <oer_encoder.h>	/* Octet Encoding Rules encoder */
53
#endif
Lev Walkin's avatar
Lev Walkin committed
54 55 56

/*
 * Free the structure according to its specification.
57 58
 * Use one of ASN_STRUCT_{FREE,RESET,CONTENTS_ONLY} macros instead.
 * Do not use directly.
Lev Walkin's avatar
Lev Walkin committed
59
 */
60 61 62 63 64
enum asn_struct_free_method {
    ASFM_FREE_EVERYTHING,   /* free(struct_ptr) and underlying members */
    ASFM_FREE_UNDERLYING,   /* free underlying members */
    ASFM_FREE_UNDERLYING_AND_RESET   /* FREE_UNDERLYING + memset(0) */
};
Lev Walkin's avatar
Lev Walkin committed
65
typedef void (asn_struct_free_f)(
66
		const struct asn_TYPE_descriptor_s *type_descriptor,
67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94
		void *struct_ptr, enum asn_struct_free_method);

/*
 * Free the structure including freeing the memory pointed to by ptr itself.
 */
#define ASN_STRUCT_FREE(asn_DEF, ptr) \
    (asn_DEF).op->free_struct(&(asn_DEF), (ptr), ASFM_FREE_EVERYTHING)

/*
 * Free the memory used by the members of the structure without freeing the
 * the structure pointer itself.
 * ZERO-OUT the structure to the safe clean state.
 * (Retaining the pointer may be useful in case the structure is allocated
 *  statically or arranged on the stack, yet its elements are dynamic.)
 */
#define ASN_STRUCT_RESET(asn_DEF, ptr) \
    (asn_DEF).op->free_struct(&(asn_DEF), (ptr), ASFM_FREE_UNDERLYING_AND_RESET)

/*
 * Free memory used by the members of the structure without freeing
 * the structure pointer itself.
 * (Retaining the pointer may be useful in case the structure is allocated
 *  statically or arranged on the stack, yet its elements are dynamic.)
 * AVOID using it in the application code;
 * Use a safer ASN_STRUCT_RESET() instead.
 */
#define ASN_STRUCT_FREE_CONTENTS_ONLY(asn_DEF, ptr) \
    (asn_DEF).op->free_struct(&(asn_DEF), (ptr), ASFM_FREE_UNDERLYING)
Lev Walkin's avatar
Lev Walkin committed
95 96 97 98

/*
 * Print the structure according to its specification.
 */
99 100 101 102 103
typedef int(asn_struct_print_f)(
    const struct asn_TYPE_descriptor_s *type_descriptor,
    const void *struct_ptr,
    int level, /* Indentation level */
    asn_app_consume_bytes_f *callback, void *app_key);
Lev Walkin's avatar
Lev Walkin committed
104

105 106 107 108 109 110 111 112 113 114 115
/*
 * Compare two structs between each other.
 * Returns <0 if struct_A is "smaller" than struct_B, >0 if "greater",
 * and =0 if "equal to", for some type-specific, stable definition of
 * "smaller", "greater" and "equal to".
 */
typedef int (asn_struct_compare_f)(
		const struct asn_TYPE_descriptor_s *type_descriptor,
		const void *struct_A,
		const void *struct_B);

Lev Walkin's avatar
Lev Walkin committed
116 117 118 119 120 121 122
/*
 * Return the outmost tag of the type.
 * If the type is untagged CHOICE, the dynamic operation is performed.
 * NOTE: This function pointer type is only useful internally.
 * Do not use it in your application.
 */
typedef ber_tlv_tag_t (asn_outmost_tag_f)(
123
		const struct asn_TYPE_descriptor_s *type_descriptor,
Lev Walkin's avatar
Lev Walkin committed
124
		const void *struct_ptr, int tag_mode, ber_tlv_tag_t tag);
Lev Walkin's avatar
Lev Walkin committed
125
/* The instance of the above function type; used internally. */
126
asn_outmost_tag_f asn_TYPE_outmost_tag;
Lev Walkin's avatar
Lev Walkin committed
127

128 129 130 131
/*
 * Fetch the desired type of the Open Type based on the
 * Information Object Set driven constraints.
 */
132
typedef struct asn_type_selector_result_s {
133
    const struct asn_TYPE_descriptor_s *type_descriptor; /* Type encoded. */
134 135 136
    unsigned presence_index; /* Associated choice variant. */
} asn_type_selector_result_t;
typedef asn_type_selector_result_t(asn_type_selector_f)(
137 138 139
    const struct asn_TYPE_descriptor_s *parent_type_descriptor,
    const void *parent_structure_ptr);

Lev Walkin's avatar
Lev Walkin committed
140
/*
141 142
 * Generalized functions for dealing with the speciic type.
 * May be directly invoked by applications.
Lev Walkin's avatar
Lev Walkin committed
143
 */
144
typedef struct asn_TYPE_operation_s {
145 146 147 148 149 150 151 152 153 154 155
    asn_struct_free_f *free_struct;     /* Free the structure */
    asn_struct_print_f *print_struct;   /* Human readable output */
    asn_struct_compare_f *compare_struct; /* Compare two structures */
    ber_type_decoder_f *ber_decoder;      /* Generic BER decoder */
    der_type_encoder_f *der_encoder;      /* Canonical DER encoder */
    xer_type_decoder_f *xer_decoder;      /* Generic XER decoder */
    xer_type_encoder_f *xer_encoder;      /* [Canonical] XER encoder */
    oer_type_decoder_f *oer_decoder;      /* Generic OER decoder */
    oer_type_encoder_f *oer_encoder;      /* Canonical OER encoder */
    per_type_decoder_f *uper_decoder;     /* Unaligned PER decoder */
    per_type_encoder_f *uper_encoder;     /* Unaligned PER encoder */
156 157
    per_type_decoder_f *aper_decoder;     /* Aligned PER decoder */
    per_type_encoder_f *aper_encoder;     /* Aligned PER encoder */
158 159
    asn_random_fill_f *random_fill;       /* Initialize with a random value */
    asn_outmost_tag_f *outmost_tag;       /* <optional, internal> */
160 161
} asn_TYPE_operation_t;

162 163 164 165 166 167 168 169 170
/*
 * A constraints tuple specifying both the OER and PER constraints.
 */
typedef struct asn_encoding_constraints_s {
    const struct asn_oer_constraints_s *oer_constraints;
    const struct asn_per_constraints_s *per_constraints;
    asn_constr_check_f *general_constraints;
} asn_encoding_constraints_t;

171 172 173 174
/*
 * The definitive description of the destination language's structure.
 */
typedef struct asn_TYPE_descriptor_s {
175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209
    const char *name;       /* A name of the ASN.1 type. "" in some cases. */
    const char *xml_tag;    /* Name used in XML tag */

    /*
     * Generalized functions for dealing with the specific type.
     * May be directly invoked by applications.
     */
    asn_TYPE_operation_t *op;

    /***********************************************************************
     * Internally useful members. Not to be used by applications directly. *
     **********************************************************************/

    /*
     * Tags that are expected to occur.
     */
    const ber_tlv_tag_t *tags;      /* Effective tags sequence for this type */
    unsigned tags_count;            /* Number of tags which are expected */
    const ber_tlv_tag_t *all_tags;  /* Every tag for BER/containment */
    unsigned all_tags_count;        /* Number of tags */

    /* OER, PER, and general constraints */
    asn_encoding_constraints_t encoding_constraints;

    /*
     * An ASN.1 production type members (members of SEQUENCE, SET, CHOICE).
     */
    struct asn_TYPE_member_s *elements;
    unsigned elements_count;

    /*
     * Additional information describing the type, used by appropriate
     * functions above.
     */
    const void *specifics;
210
} asn_TYPE_descriptor_t;
Lev Walkin's avatar
Lev Walkin committed
211

Lev Walkin's avatar
Lev Walkin committed
212
/*
213 214
 * This type describes an element of the constructed type,
 * i.e. SEQUENCE, SET, CHOICE, etc.
Lev Walkin's avatar
Lev Walkin committed
215
 */
216
  enum asn_TYPE_flags_e {
217 218 219 220
    ATF_NOFLAGS,
    ATF_POINTER = 0x01,   /* Represented by the pointer */
    ATF_OPEN_TYPE = 0x02, /* Open Type */
    ATF_ANY_TYPE = 0x04   /* ANY type (deprecated!) */
221
  };
222
typedef struct asn_TYPE_member_s {
Lev Walkin's avatar
Lev Walkin committed
223 224 225 226 227 228
    enum asn_TYPE_flags_e flags; /* Element's presentation flags */
    unsigned optional;      /* Following optional members, including current */
    unsigned memb_offset;   /* Offset of the element */
    ber_tlv_tag_t tag;      /* Outmost (most immediate) tag */
    int tag_mode;           /* IMPLICIT/no/EXPLICIT tag at current level */
    asn_TYPE_descriptor_t *type;            /* Member type descriptor */
229
    asn_type_selector_f *type_selector;     /* IoS runtime type selector */
230
    asn_encoding_constraints_t encoding_constraints;
231
    int (*default_value_cmp)(const void *sptr); /* Compare DEFAULT <value> */
232
    int (*default_value_set)(void **sptr);      /* Set DEFAULT <value> */
Lev Walkin's avatar
Lev Walkin committed
233
    const char *name; /* ASN.1 identifier of the element */
234
} asn_TYPE_member_t;
Lev Walkin's avatar
Lev Walkin committed
235

Lev Walkin's avatar
Lev Walkin committed
236 237 238
/*
 * BER tag to element number mapping.
 */
239
typedef struct asn_TYPE_tag2member_s {
Lev Walkin's avatar
Lev Walkin committed
240 241
    ber_tlv_tag_t el_tag;   /* Outmost tag of the member */
    unsigned el_no;         /* Index of the associated member, base 0 */
Lev Walkin's avatar
Lev Walkin committed
242 243
    int toff_first;         /* First occurence of the el_tag, relative */
    int toff_last;          /* Last occurence of the el_tag, relative */
244
} asn_TYPE_tag2member_t;
Lev Walkin's avatar
Lev Walkin committed
245

Lev Walkin's avatar
Lev Walkin committed
246
/*
Lev Walkin's avatar
Lev Walkin committed
247 248
 * This function prints out the contents of the target language's structure
 * (struct_ptr) into the file pointer (stream) in human readable form.
Lev Walkin's avatar
Lev Walkin committed
249 250 251
 * RETURN VALUES:
 * 	 0: The structure is printed.
 * 	-1: Problem dumping the structure.
Lev Walkin's avatar
Lev Walkin committed
252
 * (See also xer_fprint() in xer_encoder.h)
Lev Walkin's avatar
Lev Walkin committed
253
 */
Lev Walkin's avatar
Lev Walkin committed
254 255 256
int asn_fprint(FILE *stream, /* Destination stream descriptor */
               const asn_TYPE_descriptor_t *td, /* ASN.1 type descriptor */
               const void *struct_ptr);         /* Structure to be printed */
Lev Walkin's avatar
Lev Walkin committed
257

Lev Walkin's avatar
Lev Walkin committed
258 259 260 261
#ifdef __cplusplus
}
#endif

Lev Walkin's avatar
Lev Walkin committed
262
#endif	/* _CONSTR_TYPE_H_ */