| -funnamed-unions |
Enable unnamed unions in the definitions of target language's
structures. |
@@ -789,7 +793,7 @@ be possible to compile everything with the single instruction:
cc -o rectangle *.c # It could be that simple4.1
+ HREF="#foot411">4.1
@@ -836,22 +840,27 @@ There are several generic functions available:
-- check_constraints
-- Check that the contents of the target structure
-are semantically valid and constrained to appropriate implicit or
-explicit subtype constraints. Please refer to Section sub:Validating-the-target.
-
- ber_decoder
- This is the generic restartable4.2 BER decoder (Basic Encoding Rules). This decoder would create
+ HREF="#foot238">4.2 BER decoder (Basic Encoding Rules). This decoder would create
and/or fill the target structure for you. Please refer to Section
[Decoding-BER].
- der_encoder
- This is the generic DER encoder (Distinguished Encoding
-Rules). This decoder will take the target structure and encode it
+Rules). This encoder will take the target structure and encode it
into a series of bytes. Please refer to Section [Encoding-DER].
+- xer_encoder
+- This is the generic XER encoder (XML Encoding Rules).
+This encoder will take the target structure and represent it as an
+XML (text) document. Please refer to Section [Encoding-XER].
+
+- check_constraints
+- Check that the contents of the target structure
+are semantically valid and constrained to appropriate implicit or
+explicit subtype constraints. Please refer to Section sub:Validating-the-target.
+
- print_struct
- This function convert the contents of the passed target
structure into human readable form. This form is not formal and cannot
@@ -863,6 +872,11 @@ for debugging or quick-n-dirty printing. Please refer to Section [Freeing-the-target].
+check_constraints Check that the contents of the target structure
+are semantically valid and constrained to appropriate implicit or
+explicit subtype constraints. Please refer to Section sub:Validating-the-target.
+
+
Each of the above function takes the type descriptor (asn1_DEF_...)
and the target structure (rect, in the above example). The
target structure is typically created by the generic BER decoder or
@@ -1015,12 +1029,13 @@ Encoding DER
-The Distinguished Encoding Rules is the variant of BER encoding rules
-which is oriented on representing the structures with length known
-beforehand. This is probably exactly how you want to encode: either
-after a BER decoding or after a manual fill-up, the target structure
-contains the data which size is implicitly known before encoding.
-The DER encoding is used, for example, to encode X.509 certificates.
+The Distinguished Encoding Rules is the canonical variant of
+BER encoding rules. The DER is best suited to encode the structures
+where all the lengths are known beforehand. This is probably exactly
+how you want to encode: either after a BER decoding or after a manual
+fill-up, the target structure contains the data which size is implicitly
+known before encoding. The DER encoding is used, for example, to encode
+X.509 certificates.
As with BER decoder, the DER encoder may be invoked either directly
@@ -1051,21 +1066,21 @@ write_stream(const void *buffer, size_t size, void
*/
ssize_t
simple_serializer(FILE *ostream, Rectangle_t *rect) {
- der_enc_rval_t rval; /* Return value */
+ asn_enc_rval_t er; /* Encoder return value */
- rval = der_encode(&asn1_DEF_Rect, rect,
+ er = der_encode(&asn1_DEF_Rect, rect,
write_stream, ostream);
- if(rval.encoded == -1) {
+ if(er.encoded == -1) {
/*
- * Failure to encode the rectangle data.
+ * Failed to encode the rectangle data.
*/
fprintf(stderr, ''Cannot encode %s: %s\n'',
- rval.failed_type->name,
+ er.failed_type->name,
strerror(errno));
return -1;
} else {
/* Return the number of bytes */
- return rval.encoded;
+ return er.encoded;
}
}
@@ -1083,7 +1098,7 @@ DER encoder will essentially do the same thing (i.e., encode the data)
but no callbacks will be invoked (so the data goes nowhere). It may
prove useful to determine the size of the structure's encoding before
actually doing the encoding4.3.
+ HREF="#foot314">4.3.
Please look into der_encoder.h for the precise definition of der_encode()
@@ -1091,7 +1106,51 @@ and related types.
-
+
+Encoding XER
+
+
+
+The XER stands for XML Encoding Rules, where XML, in turn, is eXtensible
+Markup Language, a text-based format for information exchange. The
+encoder routine API comes in two flavors: stdio-based and callback-based.
+With the callback-based encoder, the encoding process is very similar
+to the DER one, described in Section sub:Encoding-DER. The
+following example uses the definition of write_stream() from up there.
+
+
+
+
+/*
+ * This procedure generates the XML document
+ * by invoking the XER encoder.
+ * NOTE: Do not copy this code verbatim!
+ * If the stdio output is necessary,
+ * use the xer_fprint() procedure instead.
+ * See Section sub:Printing-the-target.
+ */
+int
+print_as_XML(FILE *ostream, Rectangle_t *rect) {
+ asn_enc_rval_t er; /* Encoder return value */
+
+ er = xer_encode(&asn1_DEF_Rect, rect,
+ XER_F_BASIC, /* BASIC-XER or CANONICAL-XER */
+ write_stream, ostream);
+
+ return (er.encoded == -1) ? -1 : 0;
+}
+
+
+Please look into xer_encoder.h for the precise definition of xer_encode()
+and related types.
+
+
+See Section [Printing-the-target] for the example of stdio-based
+XML encoder and other pretty-printing suggestions.
+
+
+
+
Validating the target structure
@@ -1119,7 +1178,7 @@ and related types.
-
+
Printing the target structure
@@ -1138,8 +1197,23 @@ Please look into constr_TYPE.h for the precise definition of asn_fprint()
and related types.
+Another practical alternative to this custom format printing would
+be to invoke XER encoder. The default BASIC-XER encoder performs reasonable
+formatting for the output to be useful and human readable. To invoke
+the XER decoder in a manner similar to asn_fprint(), use the xer_fprint()
+call:
-
+
+
+
+xer_fprint(stdout, &asn1_DEF_Rectangle, rect);
+
+
+See Section sub:Encoding-XER for XML-related details.
+
+
+
+
Freeing the target structure
@@ -1224,7 +1298,7 @@ ISBN:0-12-6333361-0.
not a definitive factor.
-... this... this2.2
-fnative-types compiler option is used to produce basic C int
types instead of infinite width INTEGER_t structures. See Table 1.
@@ -1236,32 +1310,32 @@ types instead of infinite width INTEGER_t structures. See Table
text (XML) based.
-...asn1c...asn1c3.1
The 1 symbol in asn1c is a digit, not an ''ell'' letter.
-... specification... specification3.2
This is probably not what you want to try out right now -
read through the rest of this chapter to find out about -P
and -R options.
-...that simple...that simple4.1
Provided that you've also created a .c file with the int main()
routine.
-...restartable...restartable4.2
Restartable means that if the decoder encounters the end of the buffer,
it will fail, but may later be invoked again with the rest of the
buffer to continue decoding.
-... encoding... encoding4.3
It is actually faster too: the encoder might skip over some computations
which aren't important for the size determination.
@@ -1270,7 +1344,7 @@ which aren't important for the size determination.
Lev Walkin
-2004-09-17
+2004-09-26