NAME
mavros-output \- output of the MAVROS ASN.1 compiler
SYNOPSIS
#include "asn1.h"
#include ".h"
asn1 XXXXXX_cod(area,type_scope,type_number,argument_list)
asn1 area;
int type_scope;
int type_number;
asn1 XXXXXX_dec(area,area_limit,argument_list)
asn1 area, area_limit;
XXXXXX_free(argument_list)
asn1_uint32 XXXXXX_len(type_number,argument_list)
int type_number;
char \(**XXXXXX_out(area, argument_list)
char \(**area;
char \(**XXXXXX_in(area, area_limit, argument_list)
char \(**area, \(**area_limit;
int XXXXXX_olen(argument_list)
void XXXXXX_cpy(target_argument_list,source_argument_list)
int XXXXXX_cmp(argument_list_1,argument_list_2)
asn1_uint32 XXXXXX_hash(h,argument_list)
asn1_uint32 h;
int XXXXXX_stp(argument_list)
DESCRIPTION
For every data type, MAVROS will generate four 'C' procedures for the
basic coding and decoding functions, a subtype verification routine, plus
optionally text coding and decoding routines, copying, comparison and hashing
routines.
The list of procedures above mentions the data types:
- asn1
which is defined in the header file
asn1.h
as an
unsigned char *.
- asn1_uint32
which is defined in the header file
asn1.h
as a 32 bits long unsigned integer.
In all these declarations, the string
XXXXXX
will indeed be replaced by
the actual name of the data-type, as declared in the MAVROS input.
The four basic coding routines perform the following functions:
- XXXXXX_cod:
Encodes the data type in ASN-1, in the area beginning at
area.
Returns
the address of the first byte following the ASN-1 encoding: this address can
be used as
area
argument of another call when encoding a
Sequence
or a
Set.
The arguments
type-scope
and
type-number
are used to build
the ASN-1 flag; if one sets these values to -1 and 0 respectively, the coding
routine will use the default tag of the data-type. The other allowed values
for the type scope are:
0: UNIVERSAL
1: APPLICATION
2: CONTEXT
-
These values should only be used by ASN.1 experts, as using an unexpected
ASN.1 tag may result in decoding errors at the other end of the connection.
The ASN.1 basic encoding rules allow several possible codings for the "length"
fields in the type-length-value notation. The high order bits of the
type number argument can be used to pass coding directives, by "oring" the
actual type number with one of the following predefined values:
ASN1_LEN_DEF, ASN1_LEN_UDEF,
ASN1_X509_MODE, ASN1_DER_MODE, ASN1_CER_MODE
ASN1_LENGTH_0, ASN1_LENGTH_1, ASN1_LENGTH_2,
ASN1_LENGTH_3, ASN1_LENGTH_4
-
The
ASN1_LEN_DEF
flag will mandate the use of "defined" length encoding, always using exactly
the number of bits necessary to encode the length field. The
ASN1_LEN_UDEF
flag, on the contrary, will mandate the use of the "undefined" length
encoding for structured elements, i.e. replacing the "length" field by an
octet indicating that "the length of the length" is null, and terminating the
structure by an "end of component" mark. The flags
ASN1_X509_MODE
and
ASN1_DER_MODE
are equivalent; they result in a unique "distinguished encoding" of the value,
using defined length fields and ordering the components of sets by ascending
tag values. This is suitable when a unique encoding is required, e.g. if the
data shall be digitally signed according to the X.509 specifications. The
"canonical encoding rules" which can be obtained with the
ASN1_CER_MODE
flag also define a unique encoding, with different rules that X.509: the set
elements are also ordered, but undefined length are used and the long strings
are represented as sequences of 1024 octets elements. The
ASN1_LENGTH_0
mode can be used to check that the length will always be encoded on exactly
one octet for elements smaller than 128 bytes, and that undefined length
notations will be used for longer elements. The other types constrain the use
of a "length of length" notation, followed by at least 1, 2, 3 or 4 octets
respectively. For example, the call:
.DS
area_end = XXXXXX_cod(area, 1, ASN1_LEN_DEF|1, argument_list);
.DE
will encode a value of type XXXXXX using the ASN.1 tag \[ APPLICATION 1\],
without ever using the ``undefined'' coding for length fields.
- XXXXXX_dec:
Decode the data-type from the ASN-1 encoded area beginning at
area.
Returns the address of the first byte following the ASN-1 representation of
the data-type: this address can be used as
area
argument of another call
when decoding a
Sequence
or a
Set.
The argument
area_limit
gives the limit of the buffer to be decoded; it is used by syntax checking
routines during the decoding procedure. If an error occurs, the decoding
routine returns a null pointer; the location of the byte which was being
decoded can be found in the global variable
asn1_wrongbyte,
and an error code in the global variable
asn1_diagnostic.
The diagnostic code can be transformed into a text string by the routine
asn1_errdec.
These variables are declared in the header file
asn1.h.
- XXXXXX_free:
During the decoding of an ASN-1 type, memory may have been allocated to hold
some variable length components. Calling the
XXXXXX_free
routine with
exactly the same arguments as
XXXXXX_dec:
will free all these memory
allocations.
- XXXXXX_len:
One must pass to the coding routine a pointer to an area of sufficient size
to hold all the encoded information. The routine
XXXXXX_len
, called with
exactly the same arguments as
XXXXXX_cod
will return a closed
overevaluation
of the size of the ASN-1 encoding.
They will not necessarily return
an exact evaluation, as this would involve too much
processing: for example, for encoding an integer, MAVROS will reserve four
bytes, even if the coding will use from 1 to 4 bytes depending on the actual
value.
The type number is passed as an argument,
as encoding the type tag may need a variable number of bytes.
- XXXXXX_stp:
The ASN.1 specification of a type may include a number of
"subtype constraints"
such as specification of string or table sizes, ranges for
INTEGERs, sets of acceptable values, allowed characters in strings. These
constraints are not checked at decoding time. The function
XXXXXX_stp
will return a non null value if the constraints are met, a null value
otherwise.
All these routines include in their argument list the list of arguments
which was passed in the MAVROS declaration, whith the following precisions:
-
When declared in
VAR
mode, all the arguments are passed
by address.
-
When declared in
VALUE
mode, all the arguments are passed
by value.
-
If not qualified, the arguments are passed
by address
to the decoding
routine
XXXXXX_dec
and
by value
to all the other routines.
When the
-a
argument is present, MAVROS will generate text coding
and decoding routines, which will take the same
C
arguments
as the ASN.1 coding and decoding routines, but will generate
a null terminated text string of the form:
orname = <
C= "FR";
ADMD= "ATLAS";
PRMD= "INRIA";
PersonalName = <
Surname= "Huitema";
GivenName= "Christian">>
For each data type, MAVROS will generate three routines:
- XXXXXX_out:
Produce a text encoding of the arguments, in the null terminated character
string
area
, and returns a pointer to the first available byte.
The argument list has the same value as that of the ASN.1 coding routine.
- XXXXXX_in:
Parse the null terminated
area
and set the result in the argument list,
which has the same format as that of the ASN.1 decoding routines. The
argument
area_limit
points to the end of the encoding buffer, and
is used for syntax checking. In case of error, the routine returns a null
pointer; the global variable
asn1_wrong_input_char
holds the location
of the character where the error was decoded, and the global variable
asn1_input_diagnostic
holds the error code, which can be transformed
in a text string by the routine
asn1_errdec
.
- XXXXXX_olen:
Plays the same role as
XXXXXX_len
, for the textual syntax.
The length returned by "XXXXXX_olen" does not include the "null character"
delimiter of the string. The memory allocated to encode the component
XXXXXX
with the text syntax should be sized to
"XXXXXX_olen(x) + 1".
There is no specific memory deallocation routine for the text syntax. The
routine
XXXXXX_free
should be used to release the memory allocated
during the decoding, when the data are not anymore needed. It should
also be used after an error detection.
If the
-c
argument is present, MAVROS will generate copying, comparison and hashing
routines:
- "XXXXXX_cpy(target_argument_list,source_argument_list)"
is the copying routine. The
target
arguments are those of the decoding routine. The
source
arguments are those of the
coding
routines. Using the copying routine
is equivalent to calling
XXXXXX_cod
with the source arguments,
and then
XXXXXX_dec
with the target arguments.
The copying routine performs memory allocation, so that the resulting
copy can be used even after
freeing
the initial data. It can be
freed, if no longer needed, by calling
XXXXXX_free.
- "XXXXXX_cmp(argument_list_1,argument_list_2)"
is a comparison routine. Both
argument_list_1
and
argument_list_2
correspond to the arguments of the coding routine. The comparison returns a
null integer if the values match, a non null integer otherwise. When the type
XXXXXX support order comparison, the routines will return a positive value
if the first term is larger than the second. In all other cases, it will
return a negative argument. The comparison function is type dependant; for
example, two "set of" structures may be found equal even if their components
are not in the same order.
- "XXXXXX_hash(h,argument_list)"
takes arguments similar to those of the coding routine and returns a
hash code
of the value, combined with the initial argument
h.
The hash function is type dependant, so that if two arguments
matches they will be assigned the same code.
"SEE ALSO"
mavcod (9x),
mavros (9x),
mavros-input (9x),
asn1_oid(9x),
asn1_utctime(9x),
asn1_malloc(9x)
C. Huitema,
"General Presentation of the MAVROS Compiler" ,INRIA, 1990
WARNINGS
Application programmers may be tempted to use the
XXXXXX_free
routines
to free the input of coding functions, e.g. after formatting a message.
This may not yeld the expected results, except if the data have been
produced by a decoding or a copying procedure: MAVROS uses
its own memory allocation procedures, described in the
asn1_malloc
manual.
MAVROS may decide to encode some procedures by using
macros
rather
than actual procedures. When one needs a real function, e.g. to
insert it in a table of functions, this can be prevented by declaring the
type in the list of exported variables, in the MAVROS input.