This section lists the compiler directives and provides a thorough description of their function. The compiler directives on this page are grouped into two categories: standard directives (ASN1.*) and OSS directives (OSS.*).
Specifies the name of a function in your application that is used to check a user-defined constraint.
By default, the name of the constraining function is typereference_fn.
In the following example, the application function isContrOdd() is used to check if the type OddInteger is odd. If no constraining function name is provided, by default, the name of the constraining function is OddInteger_fn.
We stand with Ukraine
--<ASN1.ConstraintFunction Module.OddInteger isConstrOdd>--
Module DEFINITIONS ::= BEGIN
OddInteger ::= INTEGER (CONSTRAINED BY {-- odd --} )
END
This directive can be used only with types that have a CONSTRAINED BY clause.
The ASN1.ConstraintFunction directive must be placed before the user-defined type it references.
User-defined constraint-checking functions are generated only when the -userConstraints compiler option is enabled. Note that TOED does not support user-defined constraints.
Changes the C-representation of a specific CHOICE, SEQUENCE, or SET component to the open type structure. The BER and DER decoders will not decode the component; its undecoded form is left in the "encoded" field of the structure.
By default, all components of CHOICE, SET, or SEQUENCE are decoded with their containing type.
In the following example, the defined type, Type_setComponent_encodable, can be later used in decoding setComponent. This type has a separate PDU tag generated for it.
| ASN.1 | .h |
|---|---|
--<ASN1.DeferDecoding Module.Type.setComponent>--
Module DEFINITIONS ::= BEGIN
Type ::= SET {
setComponent INTEGER,
b BOOLEAN
}
END
|
#define Type_PDU 1
#define Type_setComponent_encodable_PDU 2
typedef struct Type {
OpenType setComponent; /* Type_setComponent_encodable type */
ossBoolean b;
} Type;
typedef int Type_setComponent_encodable;
|
The ASN1.DeferDecoding directive:
Sets a special representation for an INTEGER whose size is not supported by the operating system.
absoluteReference refers to INTEGER types represented using the HugeInteger representation. The HugeInteger representation consists of a structure that contains a pointer to a CHARACTER STRING and a length field.
By default, INTEGER types are represented as machine dependent 16-bit, 32-bit, or 64-bit numbers.
struct {
unsigned short length;
unsigned char *value;
} integerType;
The INTEGER is stored in binary format in the series of octets referenced by the above value field.
| ASN.1 | .h |
|---|---|
--<ASN1.HugeInteger LengthModule.LengthData.lengthOfSolarSystem>--
LengthModule DEFINITIONS ::= BEGIN
LengthData ::= SEQUENCE {
lengthOfSolarSystem INTEGER,
units ENUMERATED {mm(0), cm(1), m(2), km(3), lightyears(4)} DEFAULT mm
}
END
|
typedef struct LengthData {
unsigned char bit_mask;
# define units_present 0x80
struct _struct1 {
unsigned short length;
unsigned char *value;
} lengthOfSolarSystem;
enum _enum1 {
mm = 0,
cm = 1,
m = 2,
km = 3,
lightyears = 4
} units; /* units_present not set in bit_mask implies value is mm */
} LengthData;
|
The ASN1.HugeInteger directive requires a parameter and it cannot be applied to all integers.
Provides an alias to a name from an ASN.1 module indicated by absoluteReference that can be used in the generated code.
absoluteReference specifies a name for: a module, type reference, value reference, object class reference, object reference, object set reference, identifier or field name, element of a SET or SEQUENCE, anonymous component of a SET or SEQUENCE, or an identifier in a named bit or number list.
By default, the name used in the generated data structures is derived from the ASN.1 input file.
In the following notation, the MTN nickname is used for the type MyTypeName, which is an element of MySequence within MyModule.
--<ASN1.Nickname MyModule.MySequence.MyTypeName MTN>--
The following example illustrates how to name types and identifiers:
| ASN.1 | .h |
|---|---|
--<ASN1.Nickname Module.UserData Monkey>--
--<ASN1.Nickname Module.UserData.* Gorilla>--
--<ASN1.Nickname Module.UserData.*.1 Gibbon>--
--<ASN1.Nickname Module.UserData.*.fvalue Mandrill>--
Module DEFINITIONS ::= BEGIN
UserData ::= SET OF SEQUENCE {
key INTEGER,
fvalue OCTET STRING OPTIONAL
}
END
|
typedef struct Monkey {
struct Monkey *next;
struct Gorilla {
unsigned char bit_mask;
# define Mandrill_present 0x80
int Gibbon;
struct {
unsigned int length;
unsigned char *value;
} Mandrill; /* optional; set in bit_mask Mandrill_present if present */
} value;
} *Monkey;
|
"*" refers to the SEQUENCE type and "1" refers to the first element in the SEQUENCE (the key). In ASN.1:1990 you can omit identifiers for elements of a SEQUENCE, SET, or CHOICE, therefore you can use the number notation to give a name to every component of these constructs. Note that identifiers are mandatory in ASN.1:2021.
The following example shows how to name an item in a NamedNumberList:
| ASN.1 | .h |
|---|---|
--<ASN1.Nickname Module.E.enum1 " new_enum1">--
--<ASN1.Nickname Module.B.bit1 " new_bit1">--
--<ASN1.Nickname Module.I.int1 " new_int1">--
Module DEFINITIONS ::= BEGIN
E ::= ENUMERATED {enum1(1), enum2(2)}
B ::= BIT STRING {bit1(4), bit2(8)}
I ::= INTEGER {int1(10), int2(8)}
END
|
typedef enum E {
new_enum1 = 1,
enum2 = 2
} E;
typedef struct B {
unsigned int length; /* number of significant bits */
unsigned char *value;
} B;
#define new_bit1 0x08
#define new_bit1_byte 0
#define bit2 0x80
#define bit2_byte 1
typedef int I;
#define new_int1 10
#define int2 8
|
To rename a type defined with the TYPE NOTATION macro, place the ASN1.Nickname directive after the module where this type is defined.
Instructs the compiler to treat one or more ASN.1 types as Protocol Data Units (PDUs).
By default, unreferenced types (user defined types that are not referenced by any other type) are considered PDUs by the compiler, and they can be encoded and decoded as complete units.
In the following example, MyType is treated as a PDU, even if it is referenced in another type definition. Note that the types in the directive must be specified using the absolute reference notation.
--<ASN1.PDU Module.MyType>--
Module DEFINITIONS ::= BEGIN
AnotherTypeRef ::= MyType
MyType ::= SET {
b BOOLEAN
}
END
Enables you to select the representation (binary, decimal, or mixed) for ASN.1 values of type REAL. This directive can be applied to particular REAL types, or can specify a default for all REAL types.
Use decimal to represent REAL as a CHARACTER STRING with the following format: "[-]nnnnn.nnnnn[E[-]nnnnn]".
Use mixed to represent REAL as a struct with both possible representations.
By default, the REAL type is represented as C double (binary).
The list of affected types is specified using the absolute reference notation. If no type is specified, the ASN1.RealRepresentation directive sets the default representation for REAL types locally, on the module level, or globally, depending on its position.
| ASN.1 | .h |
|---|---|
--<ASN1.RealRepresentation mixed Module.MyType.a1.b2>--
Module DEFINITIONS ::= BEGIN
MyType ::= SEQUENCE {
a1 SET { b1 INTEGER, b2 REAL},
a2 REAL
}
END
|
typedef struct MyType {
struct {
int b1;
double b2;
} a1;
double a2;
} MyType;
|
Instructs the ASN.1 compiler to ignore ASN.1 items. The compiler does not generate code in the .h or .c file for this type. This directive is useful when you want to omit certain parts of an ASN.1 specification without modifying the original ASN.1 source.
absoluteReference can refer to: types, values, members of a CHOICE (except empty CHOICE types), OPTIONAL or DEFAULT fields in a SEQUENCE or a SET, information object class, information object that is not included in an information object set, information object set.
By default, all parts of the ASN.1 input are included in the compiler-generated files.
In the following example, after compiling the syntax, the compiler generates in the header file an empty structure S with an arbitrary placeholder:
| ASN.1 | .h |
|---|---|
--<ASN1.Remove Mod.Int>--
--<ASN1.Remove Mod.S.a>--
--<ASN1.Remove Mod.i>--
Mod DEFINITIONS ::= BEGIN
S ::= SET { a SET OF SET OF SEQUENCE { b Int }OPTIONAL
}
Int ::= INTEGER
i Int ::= 10
END
|
#define S_PDU 1
typedef struct S {
char placeholder;
} S;
|
Similar to the following example, if errors related to missing references occur and the -genDirectives or the -keepNames command-line option is specified, the OSS ASN.1 compiler automatically generates the ASN1.Remove directives in the .rmv file. The generated .rmv file can be passed on the command line (before any compiler option) to enable the compiler to automatically remove the types:
--<ASN1.Remove Mod.bit, Mod.Int>--
--<ASN1.Remove Mod.Set.a.b.c.d.*.e>--
Mod DEFINITIONS ::= BEGIN
Int ::= INTEGER
A ::= SEQUENCE {a Int OPTIONAL, b BIT STRING}
a A ::= { a 1, b bit}
bit BIT STRING ::= '0'B
C ::= CHOICE { a Int }
Set ::= SET {
a SET {
b SET {
c SET {
d SET OF SET {
e INTEGER OPTIONAL
}
}
}
}
}
s Set ::= { a { b { c { d { {e 3}, {e 4}, {e 5} } } } } }
END
Additionaly, you can prevent the ASN1.Remove directive from being automatically generated in the .rmv file. To do so, you must correct the ASN.1 specification manually until it compiles correctly.
The example above generates the following Remove directives in the .rmv file:
If you assign automatic tags when you remove components, the encodings are still compatible with applications that do not use the ASN1.Remove directive. To make sure an encoded value has not been modified, for encoding rules that depend on the number of possible components (PER, for example), removed components are counted when encoding.
When an ASN.1 item is marked for removal, any references to the item must also be removed.
Other directives applied to ASN.1 items marked for removal have no effect.
The ASN1.Remove applied to fields of a parameterized type removes the fields from each instance of the parameterized type. It is not recommended to apply ASN1.Remove to parameterized types.
Types referenced only by items marked for removal may become PDUs when the references are removed.
Enables you to specify the year of the ASN.1 standard used in a particular ASN.1 module. This directive is useful for applications that use several versions of ASN.1 source.
By default, before detecting a particular type of notation, the compiler uses neutral mode. After the compiler detects notation particular to a version, it switches out of neutral mode and enforces conformance to that standard.
When ASN1.Version conflicts with the compiler option -1990 | -2021, the most recent version is used.
Enables you to select from the input ASN.1 schema a subset of types that can be used in your application. In other words, the ASN1.WorkingSet directive enables you to specify, using one directive, all PDUs (the types of the messages to encode and decode). Values, information objects, etc. defined in the working set are also represented in the compiler generated code.
The ASN1.WorkingSet directive replaces the default compiler behavior of assigning PDUs for non-referenced types. You can access certain parts of the ASN.1 specification that are not included in the working set by referencing them from the parts in the working set.
WSName is a working set name required for consistency between the ASN.1/C product and the ASN.1/C++ and ASN.1/Java products; otherwise it is ignored.
absoluteReference refers to a module name, type reference, value reference, object class reference, object reference, or object set reference. If absoluteReference is a module name, this directive has the same effect as the OSS.ROOT directive.
By default, the ASN.1 compiler chooses a working set by examining the type of compiler directives that are present.
In the following example, Type1, Type2 and Type4 are directly available to the application as PDUs. Type3 is not available as PDU.
--<ASN1.WorkingSet WSName Module2, Module3.Type4>--
Module2 DEFINITIONS ::= BEGIN
Type1 ::= SET { typeComponent INTEGER, b BOOLEAN
}
Type2 ::= INTEGER
END
Module3 DEFINITIONS ::= BEGIN
Type3 ::= SET { aComponent INTEGER, b BOOLEAN }
Type4 ::= IA5String
END
You can extend a set by adding more than one module. For example, both module1 and module14 are included in commonSet:
--<ASN1.WorkingSet commonSet module1>-- --<ASN1.WorkingSet commonSet module14>--
The ASN1.WorkingSet directive does not affect pairs of cross referencing types. In the following example, when using a working set, neither Foo nor Bar will become a PDU:
Foo ::= SEQUENCE OF Bar
Bar ::= SEQUENCE {a INTEGER, b Foo}
A component of a SET, SEQUENCE, CHOICE, SET OF, or SEQUENCE OF cannot be added to a working set by itself.
By default, the ASN.1 compiler computes the working set by considering four types of directives, in the following order of precedence:
Based on the presence and absence of these directives in the input, the ASN.1 compiler assumes one of the following four modes of operation:
The following table illustrates how the above four modes are used by the ASN.1 compiler (x = present, blank = absent):
| Directive Type | Types of Directives Present in Input | |||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| OSS.ROOT | x | x | x | x | x | x | x | x | ||||||||
| Other OSS.* directive | x | x | x | x | x | x | x | x | ||||||||
| ASN1.WorkingSet | x | x | x | x | x | x | x | x | ||||||||
| Other ASN1.* directive | x | x | x | x | x | x | x | x | ||||||||
| ASN.1 Compiler Mode | dws | rd | rd | rd | r | r | ws | ws | ws | ws | ws | ws | ws | ws | ws | ws |
Instructs the compiler to represent SET OF, SEQUENCE OF, and OBJECT IDENTIFIER types as arrays of values with a count field.
By default, SET OF, and SEQUENCE OF types are represented as single linked lists, and OBJECT IDENTIFIERs are represented in structures with CHARACTER STRING pointers and length fields.
absoluteReference can be used to affect a particular instance of a type.
asn1Type can take the values of: SET OF, SEQUENCE OF, or OBJECT IDENTIFIER.
When used locally, the OSS.ARRAY directive does not accept operands and affects only the type placed next to it.
The following example shows both the local and global use of the OSS.ARRAY directive.
BooleanArray, RealArray, and IntArray are represented as arrays by three different OSS.ARRAY directives. RealLinkedList defaults to the linked list representation because no OSS.ARRAY directive is applied to it:
--<OSS.ARRAY SET OF>--
--<OSS.ARRAY ArraySample.RealArray>--
ArraySample DEFINITIONS ::= BEGIN
IntArray ::= SEQUENCE SIZE (5) --<ARRAY>-- OF INTEGER
RealArray ::= SEQUENCE SIZE (5) OF REAL
RealLinkedList ::= SEQUENCE SIZE (5) OF REAL
BooleanArray ::= SET SIZE (5) OF BOOLEAN
END
The OSS.ARRAY directive is not supported when the -helperNames option is specified.
Specifies the version of the ASN.1 standard for the input files.
By default, before detecting a particular type of notation, the compiler uses neutral mode. After the compiler detects notation particular to a version, it switches out of neutral mode and enforces conformance to that standard.
The following example shows how to allow unnamed elements to be used in a SEQUENCE:
--<OSS.ASN1VER MyModule.NoNames 1990>--
MyModule DEFINITIONS ::= BEGIN
NoNames ::= SEQUENCE {
BOOLEAN,
BOOLEAN,
INTEGER
}
END
Enables representation of ASN.1 UTF8String types in C as unbounded arrays of two-byte characters, the same as the default representation of the ASN.1 BMPString types.
absoluteReference refers to an item in the ASN.1 syntax that is declared as a UTF8String. If used without arguments, this directive can only operate as a local directive.
By default, the ASN.1 UTF8String type is represented as a NULL terminating CHARACTER STRING.
In the following example, TwoByteGlobal and TwoByteLocal are set to the BMPString representation.
Note that the length fields in TwoByteLocal and TwoByteGlobal specify the number of characters in the string and not the number of bytes.
| ASN.1 | .h |
|---|---|
--<OSS.BMPSTRING Module.TwoByteGlobal>--
Module DEFINITIONS ::= BEGIN
Nullterm ::= UTF8String
TwoByteLocal ::= UTF8String --<BMPSTRING>--
TwoByteGlobal ::= UTF8String
END
|
typedef unsigned char *Nullterm;
typedef struct TwoByteLocal {
unsigned int length;
unsigned short *value;
} TwoByteLocal;
typedef struct TwoByteGlobal {
unsigned int length;
unsigned short *value;
} TwoByteGlobal;
|
The BMPString and UniversalString representations of UTF8String are incompatible with the OSS.OBJHANDLE (or the OSS.NOCOPY) directive.
With the BMPString and UniversalString representations, character data is automatically converted to UTF-8 format before encoding. Also, it is converted from UTF-8 format after decoding.
No attempt is made at run time to ensure that the generated C variable contains a valid UTF-8 converted CHARACTER STRING. Data octets are passed to the encoder unchanged. Also, when decoding, unmodified data octets are used to fill the C variable. Before you call the encoder, you must make sure the UTF-8 data is valid and then, you must interpret the UTF-8 data received from the decoder.
Instructs the ASN.1 compiler to place a user-defined comment at the beginning of the .c and .h files generated by the compiler.
commentText is the comment that appears at the beginning of the generated files.
By default, no user-defined comment is generated.
For the following input:
--<OSS.COMMENT "!ALERT! PDU should be encrypted before sending.">--
The compiler generates the following header file with comments:
/***************************************************/
/* !ALERT! PDU should be encrypted before sending.*/
/***************************************************/
...
Comments from ASN.1 files are transferred by the compiler to the header file as well.
OSS.COMMENT can be specified only globally, and can occur only once in the ASN.1 input. If two or more OSS.COMMENT statements are found, the last one encountered is used and the rest will be ignored.
Controls the transfer of ASN.1 comments to the generated header file. Using this directive, you can enable comment transfer for certain sections of your ASN.1 source and disable it for other sections.
By default, ASN.1 comments are transferred to the generated header file.
This directive affects all lines of ASN.1 source that follow it until another OSS.CommentPreservation directive is encountered.
The OSS.CommentPreservation OFF is included as the first directive of any:
The OSS.DataCallback compiler directive associates a field of a SEQUENCE or SET type, an alternative of a CHOICE type, or an element of a SEQUENCE OF or a SET OF type with your callback function. This directive is useful when using partial decoding.
When specified globally (either in an ASN.1 file before the module definition or in a separate directives file), the OSS.DataCallback directive takes an absolute reference to a field.
FunctionName is the user-defined name for the callback function.
When specified locally, the OSS.DataCallback directive must be placed next to the field definition. For example:
age INTEGER(1..100) --<DataCallback "FunctionName">--,
It's possible for a named type to appear more than once in a PDU. When an OSS.DataCallback directive is applied to such a field, the decoder will call the same callback function for each occurrence. The callback, however, cannot differentiate a call for one field from a call for the other since they are both associated with the same function. To discern the difference, consider the OSS.InfoCallback directive.
Specify the representations for the ASN.1 REAL type.
By default, REAL is represented as a double.
OSS.MIXED sets the following representation:
enum MixedReal_kind {BINARY, DECIMAL};
typedef struct {
enum MixedReal_kind kind;
union {
double base2;
char *base10;
} u;
} MixedReal;
By constraining the base of the REAL type to 2, the binary representation is represented as a double by default. By constraining the base to 10, the decimal representation is represented as null-terminated char* by default.
| ASN.1 | .h |
|---|---|
--<OSS.DECIMAL>--
Module DEFINITIONS ::= BEGIN
Decimal ::= REAL (WITH COMPONENTS {..., base (10)})
Binary ::= REAL (WITH COMPONENTS {..., base (2)})
BinaryAlso ::= REAL
Mixed ::= REAL --<MIXED>--
END
|
typedef char *Decimal; typedef char *Binary; typedef char *BinaryAlso; typedef MixedReal Mixed; |
The global directive --<OSS.DECIMAL>-- overrides the default representation of the base 2 constraint. However, it does not take precedence over the local --<MIXED>-- directive.
| ASN.1 | .h |
|---|---|
--<OSS.DECIMAL>--
Module DEFINITIONS ::= BEGIN
Decimal ::= REAL (WITH COMPONENTS {..., base (10)})
DecimalAlso ::= REAL (WITH COMPONENTS {..., base (2)})
DecimalToo ::= REAL
Mixed ::= REAL --<MIXED>--
END |
typedef char *Decimal; typedef char *DecimalAlso; typedef char *DecimalToo; typedef MixedReal Mixed; |
OSS.DECIMAL sets the representation as a null-terminated CHARACTER STRING with the following format:
"[-]nnnnn.nnnnn[E[-]nnnnn]".
Note that the string pointer can point to the OSS_PLUS_INFINITY, OSS_MINUS_INFINITY , and OSS_NOT_A_NUMBER variables.
double is provided as the default representation. However, the ASN.1 standard implies that values encoded in base 10 must be represented in a format suitable for base 10 and values encoded in base 2 must be represented in a format suitable for base 2. This is done to avoid losing precision in conversions to and from their floating point representation.
To ensure that no precision is lost, you can constrain the type REAL to base 2 or base 10. To ensure that the C representation can encode and decode without conversion, you can use the MIXED directive.
The -helperNames option overrides the OSS.MIXED directive.
Instructs the compiler to generate only encoder or decoder routines, when using the Time-Optimized Encoder/Decoder. The OSS.DECODEONLY and OSS.ENCODEONLY directives can be applied to a named PDU type. These directives have no effect when the type is not used as a PDU (for example, if it is the type of a SEQUENCE or SET field). The compiler issues a warning in this case.
The OSS.DECODEONLY and OSS.ENCODEONLY directives have been deprecated, use the OSS.NODECODE | OSS.NOENCODE directive instead.
By default, when the -toed option is specified, the compiler generates both encoder and decoder routines.
When you use the Space-Optimized Encoder and Decoder, this directive has no effect because the information generated in the control table is used for encoding and decoding.
Enables you to specify names for generated #defined components within CHOICE, SEQUENCE, or SET structures.
absoluteReference refers to a particular field in a CHOICE, SEQUENCE, or a SET. It is mandatory.
userDefinedName specifies the name to be assigned. It is mandatory.
By default, the compiler generates names for #defined components.
| ASN.1 | .h |
|---|---|
--<OSS.DefineName Module.Type.field1 myName>--
Module DEFINITIONS ::= BEGIN
Type ::= CHOICE {
field1 BOOLEAN,
field2 REAL
}
END
|
typedef struct Type {
unsigned short choice;
# define myName_chosen 1
# define field2_chosen 2
union {
ossBoolean field1; /* to choose, set choice to myName_chosen */
double field2; /* to choose, set choice to field2_chosen */
} u;
} Type;
|
Instructs the compiler to use the definite or indefinite length form when encoding PDUs.
By default, the compiler uses the definite length form. Applying these directives to non-PDU types has no effect.
In the following example, ByteStream is encoded using the indefinite length form because no other directives are applied to it. DataPacket is encoded using the definite length form because the local OSS.DEFINITE directive is present:
--<OSS.INDEFINITE>--
Module DEFINITIONS ::= BEGIN
ByteStream ::= OCTET STRING
DataPacket ::= SEQUENCE {name IA5String, id INTEGER } --<DEFINITE>--
END
These directives do not affect the generated header file.
Except for the Time-Optimized BER encoder and the Lean BER encoder, all provided decoders (Space-Optimized/Lean/Time-Optimized) support the indefinite length form of encoding.
Instructs the compiler to represent SET OF and SEQUENCE OF types as doubly-linked lists of values.
By default, SET OF and SEQUENCE OF types are represented as singly-linked lists of values.
In the following example, IndDL and StrDL are represented as doubly-linked lists:
| ASN.1 | .h |
|---|---|
--<OSS.DLINKED SET OF>--
Sample1 DEFINITIONS EXPLICIT TAGS ::= BEGIN
IntDL ::= [1] SET SIZE (5) OF INTEGER
IntAR ::= [2] SET SIZE (15) --<ARRAY>-- OF INTEGER
StrDL ::= [3] SET OF IA5String
END
|
typedef struct IntDL {
struct IntDL *next;
struct IntDL *prev;
int value;
} *IntDL;
typedef struct IntAR {
unsigned short count;
int value[15];
} IntAR;
typedef struct StrDL {
struct StrDL *next;
struct StrDL *prev;
char *value;
} *StrDL;
|
The -helperNames option overrides the OSS.DLINKED directive.
Instructs the compiler to represent SET OF and SEQUENCE OF types as doubly-linked-plus lists of nodes. Doubly-linked-plus representations are similar to doubly-linked representations, except for the extra structure for keeping pointers to the head and tail nodes, as well as the number of nodes in the list.
By default, when the -helperNames option is specified or implied, SET OF and SEQUENCE OF types with elements whose types are structured or pointered, are represented as a doubly-linked-plus list of values. SET OF and SEQUENCE OF types with elements whose types are not structured and not pointered (INTEGER without HUGE, REAL with DOUBLE, BOOLEAN, NULL, and ENUMERATED, for example) are represented as unbounded structures.
The OSS.HelperListAPI directive overrides the OSS.DLINKED-PLUS directive and uses instead the DLINKED-PLUS representation.
Instructs the compiler to generate a separate DTD (XML Data Type Definition) with the filename (NewName.dtd) specified by you, for any particular PDU referenced by absoluteReference.
By default, no DTDs are produced by the ASN.1 compiler.
In the following example, two separate DTD files, StringType.dtd and AnotherNameForInt.dtd, are produced for their PDUs.
--<OSS.DTD XModule.StringType>--
--<OSS.DTD XModule.IntType "AnotherNameForInt.dtd">--
XModule DEFINITIONS ::= BEGIN
StringType ::= UTF8String
IntType ::= INTEGER
studentName ::= <StringType>John H. Doe</StringType>
studentAge ::= <IntType>23</IntType>
END
When the -dtd option is specified, a data type definition for each PDU in the input is generated in a separate file whose name is derived from the PDU name.
To make the XER output produced by ossEncode() editable in an XML tool that is not specific to ASN.1, you can use data type definitions.
To enable the ossEncode() function to generate a reference to your DTD in the XER encoding, use the ossSetXmlDTD() API function.
Enables support for DER (Distinguished Encoding Rules) applications that encode encrypted signatures.
By default, all components within a CHOICE, SEQUENCE, or SET are represented using their normal form and no typedef is generated.
In the following example, a separate PDU tag is generated for the type marked with the OSS.ENCODABLE directive. Data is represented as open type and a typedef is created for the associated OCTET STRING:
| ASN.1 | .h |
|---|---|
A DEFINITIONS ::= BEGIN
A ::= SEQUENCE {
id [0] INTEGER,
data [1] OCTET STRING --<ENCODABLE>--
}
END
|
#define A_PDU 1
#define A_data_encodable_PDU 2
typedef struct A {
int id;
OpenType data; /* A_data_encodable type */
} A;
typedef struct A_data_encodable {
unsigned int length;
unsigned char *value;
} A_data_encodable;
|
OpenType is defined as follows in the asn1hdr.h file:
typedef struct {
int pduNum;
long length; /* length of encoded */
void *encoded;
void *decoded;
#ifdef OSS_OPENTYPE_HAS_USERFIELD
void *userField;
#endif
} OpenType;
The userField can carry any type of information. This field is generated only when the -extendOpenType compiler option is specified and is ignored by the encoder/decoder.
When applied to a component of a CHOICE, SEQUENCE, or a SET, it compels the compiler to represent the component as open type. The type that would normally have been generated as a field in the struct is generated as a typedef and can be encoded independently of the CHOICE, SEQUENCE, or SET in which it was embedded.
The OSS.ENCODABLE directive is not supported for tagged types. For tagged types, you can use the ASN1.DeferDecoding directive.
This directive is not supported by PER, OER, XER or E-XER.
Instructs the compiler to encode BOOLEAN types as numeric values of 0 and 1 instead of "true" and "false", when GLOBAL-DEFAULTS MODIFIED-ENCODINGS encoding instructions are present. This is especially useful for reducing the size of the encoded XML documents and for exchanging information with decoders that understand only numeric BOOLEAN values.
In the following example, the value p0 is encoded as <Presence>0</Presence> and not as <Presence>absent</Presence>:
--<OSS.ExerNumericBoolean Test.Presence>--
Test DEFINITIONS XER INSTRUCTIONS AUTOMATIC TAGS ::= BEGIN
Presence ::= BOOLEAN
p0 Presence ::= FALSE
ENCODING-CONTROL XER
GLOBAL-DEFAULTS MODIFIED-ENCODINGS
TEXT Presence:false AS "absent"
TEXT Presence:true AS "present"
END
Enables or disables decoder support for the rules of extensibility. At compile time, disables an internal flag associated with SEQUENCE, SET and BIT STRING types.
When decoding a PDU, consider the following rules of extensibility:
The EXTENSIBLE directive functions the same as the ASN.1 formal extension marker (...).
You can use either the directive or the extension marker, but not both.
Affects how unknown values of extensible CHOICE types with a final XER USE-TYPE encoding instruction are decoded. Unknown values are values that contain the xsi:type attribute with an unrecognized value.
By default, data described above is decoded as data matching the first alternative, and all unknown elements or attributes are ignored. In the presence of the OSS.ExtensibleUseType directive, the decoder treats such data as unknown extension rather than a value of the first CHOICE alternative.
Test DEFINITIONS XER INSTRUCTIONS AUTOMATIC TAGS ::= BEGIN
T ::= [USE-TYPE] CHOICE {
base SEQUENCE {i INTEGER},
e1 SEQUENCE {i INTEGER, b BOOLEAN},
...
} --<ExtensibleUseType>--
ENCODING-CONTROL XER
GLOBAL-DEFAULTS MODIFIED-ENCODINGS
GLOBAL-DEFAULTS CONTROL-NAMESPACE
"http://www.w3.org/2001/XMLSchema-instance" PREFIX "xsi"
END
The following example shows different scenarios of decoding the XML document:
<T xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="e4">
<i>1</i>
<j>2</j>
</T>
Without ExtensibleUseType, unknown content is skipped:
value T ::= base : {
i 1
With ExtensibleUseType and without -relaySafe, the XML subtree is skipped:
value T ::= <unknown>
The decoded value contains the following data:
choice == 0
With ExtensibleUseType and -relaySafe, the XML subtree is relayed:
value T ::= <unknown>
The decoded value contains the following data:
choice == ossUnknownAlt_chosen
u.ossUnknownAlt contains
<T xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:type="e4">
<i>1</i>
<j>2</j>
</T>
If the input ASN.1 schema is compiled with the -relaySafe option, the XML sub-element that corresponds to an unknown extension is preserved in the special unknown alternative field and can be safely relayed to other parties.
In the absence of the -relaySafe option, the XML sub-element is skipped and the presence of the decoded CHOICE type indicates the use of an unknown alternative.
The directive is useful when dealing with unknown elements and attributes from the USE-TYPE content model on a low level. The decoder skips them by default, therefore if you need to analyze such data, use the relaySafe option. Also, to access the encoded XML data, apply the OSS.ExtensibleUseType directive to the CHOICE type.
Instructs the compiler to code a nested structure either using a typedef defined outside the structure or inline within the structure.
absoluteReference is mandatory and must refer to a CHOICE, SEQUENCE, SEQUENCE OF, SET, or SET OF type that is affected by these directives.
By default, for identical nested structures, the compiler generates a shared independent typedef. Unique nested structures, by default, are coded inline in the header file.
In the following example, Type1 has an inline nested structure, Type2 and Type3 have typedef structures:
| ASN.1 | .h |
|---|---|
--<OSS.ExtractType Mod.Type1.nested>--
Mod DEFINITIONS ::= BEGIN
Type1 ::= SET {
nested SET OF INTEGER
}
END
|
typedef struct _setof1 {
struct _setof1 *next;
int value;
} *_setof1;
typedef struct Type1 {
struct _setof1 *nested;
} Type1;
|
--<OSS.InlineType Mod.Type1.1>--
Mod DEFINITIONS ::= BEGIN
Type1 ::= SET {SET OF INTEGER}
Type2 ::= SET {SET OF INTEGER}
Type3 ::= SET {SET OF INTEGER}
END
|
typedef struct Type1 {
struct _setof1 {
struct _setof1 *next;
int value;
} *setOf;
} Type1;
typedef struct _setof2 {
struct _setof2 *next;
int value;
} *_setof2;
typedef struct Type2 {
struct _setof2 *setOf;
} Type2;
typedef struct Type3 {
struct _setof2 *setOf;
} Type3;
|
Instructs the ASN.1 compiler to use the specified newName for a value, field in a structure, or user-defined type.
newName must be a valid C variable name (the compiler modifies other derived names if they conflict with the specified one).
By default, names are derived from the ASN.1 definition.
| ASN.1 | .h |
|---|---|
--<OSS.FIELDNAME MyMo.Item.available inStock>--
--<OSS.TYPENAME MyMo.Name Title>--
MyMo DEFINITIONS ::= BEGIN
Name ::= IA5String
Item ::= SEQUENCE {
available BOOLEAN,
count INTEGER
}
END
|
typedef char *Title;
typedef struct Item {
ossBoolean inStock;
int count;
} Item;
|
Specifies the C data type used to represent the ASN.1 REAL type.
By default, the ASN.1 REAL type is represented using the C double data type.
In the following example, the OSS.FLOAT directive is used, therefore the local OSS.DOUBLE directive overrides the global default set:
| ASN.1 | .h |
|---|---|
--<OSS.FLOAT>--
--<OSS.DOUBLE Module.DataFolder.b>--
Module DEFINITIONS ::= BEGIN
DataFolder ::= SEQUENCE {
a REAL --<DOUBLE>--,
b REAL,
c REAL
}
END
|
typedef struct DataFolder {
double a;
double b;
float c;
} DataFolder;
|
When the -helperNames option is specified, the OSS.FLOAT directive is not supported.
Specifies a name for a function that verifies the user-defined constraints.
By default, the name of the C function (that the encoder and decoder calls before encoding and after decoding a user-constrained value) is derived from the name of the type or identifier with which the constraint is associated. For example:
Y ::= INTEGER (CONSTRAINED BY { -- Must be a power of 2 -- })
For the above syntax, the default constraint-checking function name is:
Y_fn
| ASN.1 | .h |
|---|---|
--<OSS.FUNCNAME Module.DataCard.c "checkForPowerOf2">--
Module DEFINITIONS ::= BEGIN
DataCard ::= SEQUENCE {
a BOOLEAN,
b BOOLEAN,
c INTEGER (CONSTRAINED BY { -- Must be a power of 2 --})
}
END
|
typedef struct DataCard {
ossBoolean a;
ossBoolean b;
int c; /* Must be a power of 2 */
} DataCard;
/* checkForPowerOf2 is user-defined constraint function for ASN.1 item * Module.DataCard.c */
extern int DLL_ENTRY checkForPowerOf2(struct ossGlobal *, int *, void **);
|
User-defined constraint-checking functions are only generated when the -userConstraints compiler option is specified.
User-defined constraints are not supported by the TOED.
Enables you to specify a name for the header file generated for a particular ASN.1 module. This directive is used with the split-headers mode of the ASN.1 compiler.
By default, the names of these header files are derived from their module references.
--<OSS.HeaderName MyModule "myInteger.h">--
MyModule DEFINITIONS ::= BEGIN
A ::= INTEGER
END
Controls the generation of helper list APIs when the -helperNames option is specified, and affects types with the DLINKED-PLUS representation.
In the the following example, the ASN.1 specification is compiled with -helperNames option. The helper list API functions are generated only for Quest_answers:
| ASN.1 | .h |
|---|---|
--<OSS.DLINKED-PLUS M.Quest.answers>--
--<OSS.HelperListAPI M.Quest.answers>--
M DEFINITIONS AUTOMATIC TAGS ::= BEGIN
Quest ::= SEQUENCE {
questions SEQUENCE OF IA5String,
answers SEQUENCE OF BOOLEAN
}
END
|
typedef struct Quest {
struct Quest_questions *questions;
struct Quest_answers *answers;
} Quest;
...
typedef struct Quest_answers {
struct Quest_answers_node *head;
struct Quest_answers_node *tail;
unsigned int count;
} Quest_answers;
typedef struct Quest_answers_node {
struct Quest_answers_node *next;
struct Quest_answers_node *prev;
ossBoolean value;
} Quest_answers_node;
/* ************************************************** */
/* Helper List API functions for 'Quest_answers' list */
/* ************************************************** */
/* creates an empty list */
struct Quest_answers * DLL_ENTRY oss_Quest_answers(OssGlobal *_world);
...
/* unlinks and frees node of list */
ossBoolean DLL_ENTRY oss_Quest_answers_unlink(OssGlobal *_world, struct Quest_answers * _list, Quest_answers_node * _node);
|
The -helperListAPI | -noHelperListAPI compiler options override these directives.
Instructs the ASN.1 compiler whether to generate helper macros for the referenced types, when the -helperNames compiler option is specified.
| ASN.1 | .h |
|---|---|
--<OSS.HelperMacro>--
--<OSS.NoHelperMacro M.Item.size>--
M DEFINITIONS AUTOMATIC TAGS ::= BEGIN
Size ::= SEQUENCE {
length INTEGER,
width INTEGER,
height INTEGER
}
Item ::= SEQUENCE {
color IA5String,
size Size
}
END
|
typedef struct Size {
int length;
int width;
int height;
} Size;
...
typedef struct Item {
char *color;
Size size;
} Item;
/* allocates memory for Item_PDU */
#define oss_Item_new_pdu(world) (Item *)ossGetInitializedMemory(world, sizeof(Item))
/* gets "color" field value */
#define oss_Item_color_get(inp) (inp)->color
/* sets "color" field value */
#define oss_Item_color_set(outp, color_) (outp)->color = (color_)
/* allocates memory for a string of given length */
#define oss_Item_color_new(world, length_) oss__CharStr_new(world, length_)
/* allocates memory and returns a copy of an input string */
#define oss_Item_color_copy(world, value_) oss__CharStr_copy(world, value_)
|
The -helperMacros | -noHelperMacros compiler options override these directives.
Replaces the default INTEGER representation to accommodate large INTEGERs.
| ASN.1 | .h |
|---|---|
HugeInt DEFINITIONS ::= BEGIN
A ::= INTEGER --<HUGE>--
END
|
typedef struct A {
unsigned short length;
unsigned char *value;
} A;
|
When specified globally, the absoluteReference operand should refer to an ASN.1 INTEGER type that will be represented using the HugeInteger representation. Also, when OSS.HUGE is applied globally with no parameters, it applies to all integers in the schema.
When specified locally, the OSS.HUGE directive takes no operands and affects the type that it is placed next to.
When an INTEGER type marked with an OSS.HUGE directive is constrained to be non-negative, the type value will be treated as an unsigned number rather than as a two's complement binary integer. For the BER/DER encoder, this ensures that the unsigned HUGE INTEGER values are encoded correctly by pre-pending an additional 0 octet when the high order bit of the value is 1.
Value constraints applied to INTEGER types with the OSS.HUGE directive cannot exceed 64bit. Otherwise, the ASN.1 compiler issues error messages.
Specifies the name of one or more configuration files that you can add to the ASN.1 input. This is useful when defining different sets of compiler directives that can be included or excluded, depending on the application.
By default, no configuration files are inserted into the ASN.1 input.
In the following example, directives from file1.cfg and file2.cgf are inserted at the location of the OSS.INCLUDES directive:
--<OSS.INCLUDES "file1.cfg", "file2.cfg" >-- Sample1 DEFINITIONS EXPLICIT TAGS ::= BEGIN ...
This directive can be specified only globally and must have at least one configuration filename as operand. The configuration file must contain global directives.
Directives obtained by specifying the OSS.INCLUDES directive can be used only on a single ASN.1 module definition and override any conflicting directives in the asn1dflt file.
This directive is provided for those cases where an OSS.DataCallback directive is applied to a type which occurs in multiple locations in a message.
For this definition:
M DEFINITIONS AUTOMATIC TAGS ::= BEGIN
PackageInfo ::= SEQUENCE {
from Address,
to Address,
posted DATE
}
Address ::= SEQUENCE {
zipcode INTEGER( 0..99999 ),
addressline VisibleString( SIZE (1..64) )
}
END
a directive like this
--<OSS.DataCallback M.Address.zipcode "myZipcode">--
would cause myZipcode() to be called for both PackageInfo.from.zipcode and PackageInfo.to.zipcode, but myZipcode() wouldn't be able to differentiate the two fields. OSS.InfoCallback offers a way. By employing:
--<OSS.InfoCallback M.PackageInfo.from "fromAddress">--
you instruct the compiler to generate a prototype for the fromAddress() callback function. This function, which you provide, is called by the decoder twice, once before starting the partial decoding of the from field and again after finishing its decoding.
Enables you to specify the data formatter function for encoding ASN.1 types using the JSON Encoding Rules (JER). The function that you provide is called each time the JER encoder adds the encoding of the type affected by this directive to the output buffer; instead of generating the JSON encoding for the type, the encoder passes its C value to the user-defined function and expects the encoded value to be returned.
parameterAbsoluteReference specifies an additional ASN.1 type to be used as a parameter of the encoding function; the encoder submits the last instance of the parameter type found in the input PDU value to the user-provided function each time it is called.
yourJEREncodeFunctionName has the following prototype:
int DLL_ENTRY yourJEREncodeFunctionName( struct ossGlobal *world, yourType *in, [yourParameter *param,] OssBuf *out, OssSafeMallocp safemalloc);
When the OSS.JEREncodeFunction directive is applied to an ASN.1 type, the values of this type are not encoded according to the ITU-T X.697/ISO 8825-xx standard; instead, each value is provided to the formatter function for encoding according to custom application requirements.
Also, you can provide an optional C value for the function parameter (NULL is provided when no parameter values are found in the input PDU when calling the JER encoding function). The function must populate the length and value fields of the OssBuf *out structure and return success (one of the values OSS_FORMAT_OK_STATIC or OSS_FORMAT_OK) or an error code (any positive integer).
OSS_FORMAT_OK_STATIC instructs the encoder not to free the memory referenced by the value field of the OssBuf (it is assumed that this memory is not allocated on the heap).
OSS_FORMAT_OK instructs the encoder to free the memory. The JER encoding function can dynamically allocate the output memory only by calling the safemalloc function.
Note that the OSS.JEREncodeFunction directive is available only when the -soed or -toed compiler option is specified.
Changes the default representation for the count and length fields of the structures generated by the ASN.1 compiler.
The OSS.LENGTHSIZE directive does not take an absolute reference, but has a global effect.
By default, when no size constraints are specified, the count and length fields are either short (for the OBJECT IDENTIFIER type) or int (for all other types). When a size constraint is present, these fields use the smallest representation that can accommodate all the required values.
In the following example, the short data type for the length field is used instead of (the default) int:
| ASN.1 | .h |
|---|---|
--<OSS.LENGTHSIZE SHORT>--
Module DEFINITIONS ::= BEGIN
A ::= OCTET STRING
END
|
typedef struct A {
unsigned short length;
unsigned char *value;
} A;
|
Size constraints override the OSS.LENGTHSIZE directive.
In some cases, the operand LONG has the same effect as the operand INT.
OSS.LENGTHSIZE is not supported when the -helperNames option is specified.
Instructs the compiler to represent SET OF, SEQUENCE OF, or OBJECT IDENTIFIER types as singly-linked lists of values. For SET OF and SEQUENCE OF, this directive is useful when their default representation is modified by other directives.
| ASN.1 | .h |
|---|---|
--<OSS.DLINKED SET OF>--
--<OSS.LINKED Module.InfoCards>--
Module DEFINITIONS ::= BEGIN
DataCards ::= SET OF INTEGER
InfoCards ::= SET SIZE (18) OF IA5String
END
|
typedef struct DataCards {
struct DataCards *next;
struct DataCards *prev;
int value;
} *DataCards;
typedef struct InfoCards {
struct InfoCards *next;
char *value;
} *InfoCards;
|
The -helperNames compiler option overrides the OSS.LINKED directive.
Identifies types or components for which constraint checking should be disabled. The directive disables all constraint checking for the type, including checking of the default permitted alphabet for CHARACTER STRING types. For ENUMERATED types, it disables the subtype constraints, but it does not disable checking for valid enumerators.
By default, constraint checking is enabled.
For the following example, if -constraint is not specified, all constraints for the type S are disabled. If -userConstraints is specified, constraint checking of user-constraints is enabled.
--<OSS.NoConstrain Module.S>--
Module DEFINITIONS ::= BEGIN
S ::= INTEGER (1..10 | 300) (CONSTRAINED BY { })
END
In the following example, PrintableString abc is passed at run time without issuing a constraint violation error. Although the OSS.NoConstrain directive is not explicitly applied to the ShortABCs type, constraint checking for this type is disabled because the type is composed of types marked with OSS.NoConstrain.
--<OSS.NoConstrain Mod.ABConly>--
--<OSS.NoConstrain Mod.ShortString>--
--<OSS.PDU>--
Mod DEFINITIONS ::= BEGIN
ABConly ::= PrintableString (FROM ("A" | "B" | "C"))
abc ABConly ::= "The wrong string"
ShortString ::= PrintableString (SIZE(1 | 3 ))
shStr ShortString ::= "The long string"
ShortABCs ::= PrintableString (ABConly INTERSECTION ShortString)
shABC ShortABCs ::= "ABCDD"
END
For the following example, although the -constraint option is specified, the automatic encoding and decoding is not performed at run time:
--<OSS.NoConstrain ContConstr.O>--
ContConstr DEFINITIONS::= BEGIN
O ::= OCTET STRING (CONTAINING INTEGER)
END
The OSS.NoConstrain directive cannot be specified locally. Also, it has no effect if -constraint is explicitly specified, except in the following situations:
If -userConstraints is used with OSS.NoConstrain, all constraints except for user-constraints are disabled for the specified type or field.
Informs the ASN.1 compiler to treat items marked with the ASN.1 DEFAULT tag as items marked with the OPTIONAL tag.
Types marked with the DEFAULT tag use the specified default value when absent from the encoding.
When specified globally without absoluteReference , the OSS.NODEFAULTVALUE directive affects all types marked with the DEFAULT keyword.
| ASN.1 | .h |
|---|---|
--<OSS.NODEFAULTVALUE Module.DataCard.a>--
Module DEFINITIONS ::= BEGIN
DataCard ::= SEQUENCE {
a [0] BOOLEAN DEFAULT TRUE,
b [1] BOOLEAN DEFAULT TRUE,
c [2] BOOLEAN
}
END
|
typedef struct DataCard {
unsigned char bit_mask;
# define a_present 0x80
# define b_present 0x40
ossBoolean a; /* optional; set in bit_mask a_present if present */
ossBoolean b; /* b_present not set in bit_mask implies value is
* TRUE */
ossBoolean c;
} DataCard;
|
Instructs the compiler to not generate decoder or encoder routines for the operand of the directive when using the Time-Optimized Encoder/Decoder.
The OSS.NOENCODE and OSS.NODECODE compiler directives reduce the amount of generated code. The directives can be applied either to a named PDU type or to a SEQUENCE or SET field or a CHOICE alternative, as follows:
NOTES:
The following restriction applies to the compact version: the OSS.NODECODE directive must be applied either to all fields of an extension group or to none of the fields of an extension group.
By default, when the -toed option is specified, the compiler generates both encoder and decoder routines.
When you use the Space-Optimized Encoder and Decoder, the OSS.NOENCODE and OSS.NODECODE directives have no effect.
Generates a predefined structure OpenType as the C representation for the ASN.1 open type, where the decoded value is represented as the untyped pointer.
By default, in the C representation for an ASN.1 open type, the decoded value is represented as a union of PDU type alternatives.
Instruct the compiler to represent CHARACTER STRING, GeneralizedTime, and UTCTime types in the target language as null-terminated variable length strings.
asn1Type provides the names of the ASN.1 built-in CHARACTER STRING types. The argument cannot be used for time types.
By default, string types (GeneralString, GraphicString, IA5String, NumericString, PrintableString, TeletexString, UTF8String, VideotexString, and VisibleString) and TIME type are represented as null-terminated strings. Also, multi-octet strings like BMPString and UniversalString typically contain embedded NULLs. The OSS.NULLTERM directive has no effect on these types.
| ASN.1 | .h |
|---|---|
--<OSS.NULLTERM PrintableString>--
NameDefault ::= PrintableString
|
typedef char *NameDefault; |
--<OSS.NULLTERM Sample1.TimeNULL>--
TimeDefault ::= GeneralizedTime
TimeNULL ::= GeneralizedTime
|
typedef GeneralizedTime TimeDefault; typedef char *TimeNULL; |
If the -helperNames option is not specified, time types (GeneralizedTime and UTCTime) by default, are represented as structures of INTEGERs.
If -helperNamesis specified, time types are represented as NULLTERM. The OSS.NULLTERM directive changes the representation to a string.
When NULLTERM is specified and a size constraint subtype is not present, the POINTER directive is used implicitly.
When using the null-terminated representation, you must ensure that the CHARACTER STRING does not contain embedded null characters that will affect the encoding and decoding.
Allows the compiler to represent OBJECT IDENTIFIER types as structures with lengths in octets and addresses of arrays of characters containing the BER-encoded contents of the OBJECT IDENTIFIER. In other words, OBJECT IDENTIFIER types can be represented having node values that exceed the maximum INTEGER representation on a given machine. The encoded value is derived according to the ITU-T Rec.X.690 (2021) document (clause 8.19).
length specifies the size [2 to 32,767] in octets of the CHARACTER STRING containing the BER-encoded contents of the OBJECT IDENTIFIER.
ENCODED allows the string to contain the OBJECT IDENTIFIER value of arbitrary length.
By default, OBJECT IDENTIFIER types are represented as structures with CHARACTER STRING pointers and length fields, giving the size of the CHARACTER STRING in bytes.
The following example demonstrates the local and global use of the OSS.OBJECTID and OSS.ENCODED directives. The default representation is the same as the ENCODED representation:
| ASN.1 | .h |
|---|---|
--<OSS.OBJECTID ENCODED>--
Module DEFINITIONS ::= BEGIN
ObjectIDRep ::= [1] OBJECT IDENTIFIER --<OBJECTID 82>--
EncodedRep ::= [2] OBJECT IDENTIFIER --<ENCODED>--
UnboundedRep ::= [3] OBJECT IDENTIFIER --<UNBOUNDED>--
DefaultRep ::= [4] OBJECT IDENTIFIER
END
|
typedef struct ObjectID {
unsigned short length;
unsigned char *value;
} ObjectID;
typedef struct ObjectIDRep {
unsigned short length;
unsigned char value[82];
} ObjectIDRep;
typedef ObjectID EncodedRep;
typedef struct UnboundedRep {
unsigned short count;
unsigned short *value;
} UnboundedRep;
typedef ObjectID DefaultRep;
|
The OSS.ENCODED directive can only be used locally and is equivalent to the OSS.OBJECTID ENCODED directive.
The -helperNames option overrides the OSS.OBJECTID directive representation.
Enable you to encode portions of a PDU from a file or, when the file memory manager is used, to decode portions of a PDU to a file. When the default memory manager is used, the OSS.OBJHANDLE (OSS.NOCOPY) directive instructs the decoder to use a pointer to the encoded data during decoding instead of making a copy of the encoded data.
OSS.OBJHANDLE and OSS.NOCOPY are synonym directives. Both can be used on OCTET STRING, BIT STRING, restricted CHARACTER STRING types, or types with the ASN1.DeferDecoding directive applied, to specify special handling at run time.
Note that OSS.OBJHANDLE is permitted only on restricted CHARACTER STRING types with a single byte per character, BIT STRING, OCTET STRING, ANY, ANY DEFINED BY, and open types.
In the following example, the .h file contains code that informs the encoder and decoder about the special handling of the type labeled SpecialHandling:
| ASN.1 | .h |
|---|---|
--<OSS.OBJHANDLE Module.SpecialHandling>--
Module DEFINITIONS ::= BEGIN
NoSpecialHandling ::= IA5String
SpecialHandling ::= IA5String
END
|
typedef char *NoSpecialHandling;
typedef struct SpecialHandling {
unsigned int length;
char *value;
} SpecialHandling;
|
OSS.OBJHANDLE has no effect during run time if PER encoding is used. If other encoding rules are used (BER and DER, for example), the OSS.OBJHANDLE directive is fully implemented. For example, ossDecode() and ossCpyValue() do not allocate regular memory for fields of a PDU marked with the OSS.OBJHANDLE directive. Similarly, ossFreePDU() does not de-allocate memory for such fields.
Instructs the compiler to limit the representation of a restricted CHARACTER STRING to one character.
asn1Type refers to a CHARACTER STRING type.
By default, CHARACTER STRING types can have an indefinite length or a length specified by a subtype constraint.
| ASN.1 | .h |
|---|---|
--<OSS.ONECHAR UniversalString>--
--<OSS.ONECHAR Module.SingleCharBMP>--
Module DEFINITIONS ::= BEGIN
SingleCharUTF ::= UTF8String --<ONECHAR>--
SingleCharUni ::= UniversalString
SingleCharBMP ::= BMPString
RegularBMP ::= BMPString
END
|
typedef unsigned char SingleCharUTF;
typedef int SingleCharUni;
typedef unsigned short SingleCharBMP;
typedef struct RegularBMP {
unsigned int length;
unsigned short *value;
} RegularBMP;
|
This directive is especially useful for generating initialized C values for special characters, such as those in the ASN1-CHARACTER-MODULE, as defined in ISO/IEC 8824-1:1994.
The -helperNames option overrides the OSS.ONECHAR directive.
Indicates that character string, BIT STRING, and OCTET STRING types should be represented in the target language as fixed-length padded strings when the SizeConstraint subtype or the NamedBitList for the BIT STRING type, is used. The character string types are blank-padded and BIT STRING types are zero-padded. In other words, all strings specified with the OSS.PADDED directive are the same size; short character strings and BIT STRINGs can have trailing spaces or zeros, respectively.
By default, character string types are represented as NULLTERM strings. BIT STRING and OCTET STRING types are represented as UNBOUNDED strings when the SizeConstraint subtype or NamedBitList is present.
In the following example, UnPaddedStr is one character larger than PaddedStr because of the NULL terminated-character.
| ASN.1 | .h |
|---|---|
--<OSS.PADDED Module.PaddedBitStr>--
Module DEFINITIONS ::= BEGIN
PaddedBitStr ::= BIT STRING (SIZE (10))
UnboundedBitStr ::= BIT STRING (SIZE (10))
END
|
typedef unsigned short PaddedBitStr;
typedef struct UnboundedBitStr {
unsigned short length; /* number of significant bits */
unsigned char *value;
} UnboundedBitStr;
|
The OSS.PADDED directive is not supported when the -helperNames option is specified.
Indicate whether an ASN.1 type can be sent or received as a protocol data unit. By default, all unreferenced types (defined types that are not referenced by any other type) are considered PDUs by the compiler and can be encoded or decoded as complete units.
When specified globally, these directives can take an absolute reference that specifies which component of the ASN.1 syntax is intended. If specified globally without an absolute reference, the OSS.PDU and OSS.NOPDU directives set a default for all types within their scope.
When specified locally, these directives do not take any arguments and only affect the type they are placed next to.
The following ASN.1 notation demonstrates the local and global use of the OSS.PDU directive.
--<OSS.PDU Module.NameString>--
Module DEFINITIONS ::= BEGIN
MiddleAgeClubCard ::= SEQUENCE {
name NameString,
phoneNumber PhoneString,
age AgeInt
}
NameString ::= IA5String (SIZE (40))
PhoneString ::= NumericString (SIZE (15)) --<PDU>--
AgeInt ::= INTEGER (45..54)
END
After passing the above notation through the ASN.1 compiler, the following is generated:
#define MiddleAgeClubCard_PDU 1
#define NameString_PDU 2
#define PhoneString_PDU 3
typedef char NameString[41];
typedef char PhoneString[16];
typedef unsigned short AgeInt;
typedef struct MiddleAgeClubCard {
NameString name;
PhoneString phoneNumber;
AgeInt age;
} MiddleAgeClubCard;
The #defines shown above mark which types are PDUs. Notice how AgeInt is not marked to be a PDU, since it is referenced in the SEQUENCE MiddleAgeClubCard and doesn't have a PDU directive applied to it.
The OSS.PDU and ASN1.PDU directives only affect types contained in root modules. To treat all input modules as root modules, either specify the -root compiler option (when compiling your ASN.1 syntax) or include the global OSS.ROOT directive in your ASN.1 specification.
The OSS.NOPOINTER specifies that memory must be allocated inline for an ASN.1 type.
The OSS.POINTER specifies that a pointer to the type must be created without inline allocation for the type.
By default, all C CHARACTER STRING data types without a size constraint use the OSS.POINTER representation. Other types use inline allocation.
| ASN.1 | .h |
|---|---|
--<OSS.POINTER>--
--<OSS.NOPOINTER MyModule.IntNoPoint >--
MyModule DEFINITIONS ::= BEGIN
IntNoPoint ::= INTEGER
IntPoint ::= INTEGER
END
|
typedef int IntNoPoint; typedef int *IntPoint; |
The OSS.POINTER directive affects the following simple types: BOOLEAN, INTEGER without OSS.HUGE directive, NULL, and REAL.
The -helperNames option overrides the OSS.NOPOINTER directive.
Instructs the ASN.1 compiler to generate header files for non-PDU types which typically are ignored. All types that are referenced by the type selected will also have data structures generated for them.
In the following example, without the -root option, the definitions in the non-root module Mod1 would not be generated. When using the OSS.Preserve directive, the following code is generated:
| ASN.1 | .h |
|---|---|
--<OSS.Preserve Mod1.ShortString>--
Mod1 DEFINITIONS ::= BEGIN
CompanyName ::= ShortString
ShortString ::= PrintableString
END
Mod2 DEFINITIONS ::= BEGIN
Name ::= IA5String
Age ::= INTEGER
END
|
#define Name_PDU 2 #define Age_PDU 3 typedef char *ShortString; typedef char *Name; typedef int Age; |
This directive is useful in the split-headers mode as it enables you to put selected type definitions in a particular module header file.
Enables you to specify your own data formatter function for printing values of primitive types. This function is called during ossPrintPDU(), ossPrintPER(), etc.
The data formatter function must have the following prototype:
void DLL_ENTRY myPrintFunctionName (struct ossGlobal * handle, char * toPrint);
toPrint is a string that represents the ASN.1 value.
By default, a generic internal data format and display utility is used.
| ASN.1 primitive type | String format |
|---|---|
| INTEGER | ENUMERATED | decimal number |
| OCTET STRING BIT STRING |
'xx...xx'H
'xx...xx'B |
| REAL | {mantissa, base, exponent} |
| restricted CHARACTER STRING | quoted string |
| UTC/GeneralizedTime | quoted string |
| OID-IRI/RELATIVE-OID-IRI | quoted string |
The OSS.PrintFunctionName directive can be used with one of the following OSS API function names to convert OCTET STRING type values to ASCII, IP address, TBCD, BCD, or a special time stamp format:
--<OSS.PrintFunctionName MyModule.Seq.name "ossPrintOctetAsASCII">--
--<OSS.PrintFunctionName MyModule.Seq.ip "ossPrintOctetAsIPAddress">--
--<OSS.PrintFunctionName MyModule.Seq.tbcd "ossPrintOctetAsTBCDString">--
--<OSS.PrintFunctionName MyModule.Seq.bcd "ossPrintOctetAsBCDString">--
--<OSS.PrintFunctionName MyModule.Seq.time "ossPrintOctetAsTimeStamp">--
MyModule DEFINITIONS ::= BEGIN
Seq ::= SEQUENCE {
name OCTET STRING,
ip OCTET STRING,
tbcd OCTET STRING,
bcd OCTET STRING,
time OCTET STRING
}
END
The OSS ASN.1 Tools includes the following commonly used replacement print functions: ossPrintOctetAsIPAddress(), ossPrintOctetAsASCII(), ossPrintOctetAsTBCDString(), ossPrintOctetAsBCDString(), and ossPrintOctetAsTimeStamp().
Identifies ASN.1 modules that are used as root modules. In a root module, all unreferenced types are considered PDUs. In addition, the scope of non-root modules is to supply external references to root modules.
By default, the last ASN.1 input file specified on the command line contains the root module.
--<OSS.ROOT DirectorySystemProtocol{joint-iso-ccitt ds(5) modules(1) dsp(12)}>--
OSS.ROOT takes one or more operands to identify ASN.1 modules. The operand can be a module reference ( moduleName), or a module reference followed by a built-in objectIdentifier value.
If no operands are provided, all input modules are considered root modules.
Instructs the compiler whether to generate a sample application containing code for PDU types and values identified by it.
The pdus or values parameters are used to apply the directive to all PDUs or values.
count:number specifies the default number of items created by the compiler for sample values of SEQUENCE OF and SET OF types. If count:number is not specified, the number of items is 1.
selection refers to a CHOICE alternative. By default, the compiler selects the first CHOICE alternative for the values in the sample code. If there are several such directives assigned to different alternatives of the same CHOICE type, the compiler creates as many sample values as specified.
The compiler generates sample code for all values, except for those defined in Module2:
--<OSS.ROOT>--
--<OSS.SampleCode values>--
--<OSS.NoSampleCode Module2>--
Module1 DEFINITIONS ::= BEGIN
A ::= OCTET STRING
value1 A ::= '00'H
END
Module2 DEFINITIONS ::= BEGIN
B ::= INTEGER
value2 B ::= 1
END
In the following example, the compiler generates a sequence of three sample values for a CHOICE:
--<OSS.SampleCode pdus Module>--
--<OSS.SampleCode selection Module.S.b>--
Module DEFINITIONS ::= BEGIN
S ::= CHOICE {
a IA5String,
b SEQUENCE --<SampleCode count:3>-- OF INTEGER
}
END
The compiler creates the sample application containing test code for the following value:
samplevalue1-S S ::= b : { 0, 0, 0 }
Compared to the -sampleCode command-line option, the OSS.SampleCode directive provides more control over the sample code that is created.
You can use the OSS.SampleCode directive more than once in the ASN.1 input.
The OSS.NoSampleCode directive can be used to exclude PDUs or values from the sample application.
Applying OSS.SampleCode results in the same sample code as when using the -sampleCode command-line option.
The -noSampleCode | -sampleCode options override the OSS.SampleCode | OSS.NoSampleCode directives.
Instructs the E-XER decoder to preserve the wildcard body in the decoded value as it was in the original XML document. Applies to types with the XER ANY-ELEMENT encoding instruction.
--<OSS.SelfCompleteWildcard M.Root.w>--
M DEFINITIONS XER INSTRUCTIONS ::= BEGIN
Root ::= SEQUENCE {
w [ANY-ELEMENT] UTF8String (CONSTRAINED BY {}) }
ENCODING-CONTROL XER
GLOBAL-DEFAULTS MODIFIED-ENCODINGS
NAMESPACE ALL AS "urn:Root" PREFIX "r"
END
For the following XML document:
<Root xmlns="urn:Root"> <n1:wildcard xmlns:n1="urn:n1" xmlns:n2="urn:n2" n1:at1="1" n2:at2="2"/> </Root>
n1:wildcard is an element wildcard, the decoder produces:
<n1:wildcard xmlns:n1="urn:n1" xmlns:n2="urn:n2" n1:at1="1" n2:at2="2"/>
Without the SelfCompleteWildcard directive:
<n1:wildcard xmlns:n2="urn:n2" xmlns:n1="urn:n1" xmlns="urn:Root" n2:at2="2" n1:at1="1"/>
When decoding from plain memory with the SOED and when using LED, the wildcard contents are directly copied to the output C value. When decoding from files and sockets with the SOED, the decoder can reconstruct the outermost tag of a wildcard, performing whitespace normalization within it and declaring all namespaces before all attributes. In either case, the following applies:
When the wildcard contents are normalized according to the W3C Canonical XML specification, the decoded wildcard value matches the original XML value. This enables you to validate the digital signature of a wildcard after decoding.
The directive is also useful to increase the E-XER decoding speed of wildcards when knowing that they are self-complete and that they do not use namespace or entity declarations from an outer XML document.
Determine the representation of INTEGER types.
By default, if no subtype constraints are present, the OSS.INT directive is implied.
| Directive | Representation | Notes |
|---|---|---|
| OSS.SHORT | 16 bit | |
| OSS.INT | 32 bit | 16 bit on older OS |
| OSS.LONG | 32 bit | |
| OSS.LONGLONG | 64 bit | 32 bit on platform that do not support 64 bit INTEGERs |
In the following example, LONG_LONG is defined in the file asn1hdr.h and is C compiler-specific representation of a 64-bit INTEGER:
| ASN.1 | .h |
|---|---|
--<OSS.SHORT>--
--<OSS.INT Module.GlobalINTInt>--
Module DEFINITIONS ::= BEGIN
GlobalDefaultInt ::= INTEGER
GlobalINTInt ::= INTEGER
LONGInt ::= INTEGER --<LONG>--
LONGLONGInt ::= INTEGER --<LONGLONG>--
END
|
typedef short GlobalDefaultInt; typedef int GlobalINTInt; typedef long LONGInt; typedef LONG_LONG LONGLONGInt; |
When constraints are applied to INTEGER types, the compiler chooses the smallest representation that can carry all the required values, thus ignoring such directives, except when a directive is specified with an absoluteReference or locally (inline).
Instructs the compiler to omit certain letters from long names to reduce their size to 31 characters in the header file. This directive accommodates maximum name length requirements that exist on certain C compilers. The OSS ASN.1 compiler ensures that all shortened names are unique by adding _# suffixes, when necessary.
By default, shortenToLength is 31 and must be 16 or greater.
| ASN.1 | .h |
|---|---|
--<OSS.SHORTENNAMES>--
Mod DEFINITIONS ::= BEGIN
WeWereTryingToThinkOfaNameButWeCouldNotFindaSuitableOne ::= INTEGER
NormalName ::= BOOLEAN
END
|
typedef int WWTTTONBWCNFSOn; typedef ossBoolean NormalName; |
Instructs the compiler to represent GeneralizedTime or UTCTime types as structures and not as strings.
This directive has three forms. When specified globally, the absoluteReference operand should refer to a specific ASN.1 GeneralizedTime or UTCTime type that you want to represent as a structure.
--<OSS.TIMESTRUCT absoluteReference>--
Alternatively, you can use the asn1Type argument to provide the name of an ASN.1 built-in type (GeneralizedTime or UTCTime) whose default representation should be set to the structure. If the asn1Type argument is absent, both the GeneralizedTime and UTCTime types will be represented as a structure.
--<OSS.TIMESTRUCT [asn1Type]>--
When specified locally, the TIMESTRUCT directive takes no operands and affects only the type that it is placed next to.
--<TIMESTRUCT>--
| ASN.1 | With -helperNames |
|---|---|
--<OSS.TIMESTRUCT Mod.Utc>--
Mod DEFINITIONS ::= BEGIN
Utc ::= UTCTime
Gen ::= GeneralizedTime
END
|
#define Utc_PDU 1 #define Gen_PDU 2 typedef UTCTime Utc; typedef char *Gen; |
The -helperNames and -lean options override the OSS.TIMESTRUCT directive.
Instructs the ASN.1 compiler to generate a separate XML stylesheet with your filename for any particular PDU. This directive gives you more control over the default XML stylesheets generated by the ASN.1 compiler.
When absoluteReference is not specified, a stylesheet is generated for every PDU in the input syntax.
For the following syntax, two separate stylesheet files (StringType.xsl and AnotherNameForInt.xsl) are generated. They contain default style information for their respective PDUs.
--<OSS.Stylesheet XModule.StringType>--
--<OSS.Stylesheet XModule.IntType "AnotherNameForInt.xsl">--
XModule DEFINITIONS ::= BEGIN
StringType ::= UTF8String
IntType ::= INTEGER
studentName ::= <StringType>John H. Doe</StringType>
studentAge ::= <IntType>23</IntType>
END
When the -xsl option is specified, a stylesheet for each PDU is generated into a separate file whose name is derived from that of the PDU.
Stylesheets can be used to make the XER output of the ossEncode() function more visually appealing when viewed in a web browser.
This directive is a deprecated internal directive that is generated into the .spl file when the -splitHeaders or -splitForSharing option is used.
Disables printing of specific informatory and warning messages. This is useful when compiling abstract syntaxes that contain specifications which are not fully compliant with the ASN.1 standard.
messageID specifies which message needs to be suppressed. The messageID can be either the full message identifier (A0178W) or just the numeric part of the message number (178).
By default, informatory and warning messages suppressed when -noRelaxedMode is turned on.
In the following example, message A0178W warns that the first digit of a number in a module definition should be non-zero:
--<OSS.SUPPRESS A0178W>--
Sample DEFINITIONS ::= BEGIN
Age ::= INTEGER
legalAge Age ::= 021
END
Note that the OSS.SUPPRESS directive does not affect the C-representation. The following warning message is not generated for the above syntax:
"filename.asn", line 4
(Sample): A0178W: The first digit should not be zero unless the number is a single digit.
legalAge Age ::= 021
Enables you to increase the decoding speed of certain large PDUs by skipping extra trailing elements in SET OF or SEQUENCE OF types.
absoluteReference refers to SET OF or SEQUENCE OF types for which all elements with an index greater than maxLimit are ignored.
maxLimit is an integer number between 1 and 16384.
In the following example, by using the generated control-table/code-file, the decoder will only process 3000 elements of type Records. This type of truncation is useful when the information you need should not be at the end of the list of elements or will not be included in a large list of elements:
--<OSS.Truncate Mod.Records 3000>--
Mod DEFINITIONS ::= BEGIN
Records ::= SEQUENCE OF Employee
Employee ::= SEQUENCE {
name IA5String,
position IA5String,
salary REAL
}
END
Instructs the compiler to represent CHARACTER STRING types, BIT STRING types, and OCTET STRING types as length/pointer pairs and SET OF and SEQUENCE OF types as count/pointer pairs.
By default, CHARACTER STRING types (GeneralString, GraphicString, IA5String, NumericString, PrintableString, TeletexString, UTF8String, VideotexString, VisibleString) are represented as null-terminated strings.
For BIT STRING types, the default representation is the UNBOUNDED representation when the SizeConstraint subtype is specified and a NamedBitList is present.
For OCTET STRING types, the default representation is the VARYING representation when the SizeConstraint subtype is specified.
For SET OF and SEQUENCE OF types, the default is the LINKED representation.
| ASN.1 | .h |
|---|---|
--<OSS.UNBOUNDED Module.SeqOfIntU>--
--<OSS.UNBOUNDED IA5String>--
Module DEFINITIONS ::= BEGIN
SeqOfInt ::= SEQUENCE OF INTEGER
SeqOfIntU ::= SEQUENCE OF INTEGER
Ia5Str ::= IA5String --<NULLTERM>--
Ia5StrU ::= IA5String
UTF8Str ::= UTF8String
UTF8StrU ::= UTF8String --<UNBOUNDED>--
OctetStrU ::= OCTET STRING
END
|
typedef struct SeqOfInt {
struct SeqOfInt *next;
int value;
} *SeqOfInt;
typedef struct SeqOfIntU {
unsigned int count;
int *value;
} SeqOfIntU;
typedef char *Ia5Str;
typedef struct Ia5StrU {
unsigned int length;
char *value;
} Ia5StrU;
typedef char *UTF8Str;
typedef struct UTF8StrU {
unsigned int length;
char *value;
} UTF8StrU;
typedef struct OctetStrU {
unsigned int length;
unsigned char *value;
} OctetStrU;
|
The local --<NULLTERM>-- directive overrides the global default set by the --<OSS.UNBOUNDED IA5String>-- directive.
The default representation for the OCTET STRING type is UNBOUNDED.
When a SizeConstraint subtype is specified, the count or length field of the UNBOUNDED representation is either short, int, or long, depending on which is the smallest to fit the largest value. When the SizeConstraint subtype is absent, the count or length field is always int.
Instructs the compiler to represent UTF8String types as unbounded arrays of four-byte characters (UCS-4), the same as the representation of the UniversalString.
By default, UTF8String types are represented as NULL terminating CHARACTER STRINGs
| ASN.1 | .h |
|---|---|
--<OSS.UNIVERSALSTRING Module.FourByteGlobal>--
Module DEFINITIONS ::= BEGIN
Nullterm ::= UTF8String
FourByte ::= UTF8String
TwoByte ::= UTF8String --<BMPSTRING>--
END
|
typedef char *Nullterm;
typedef struct TwoByte {
unsigned int length;
unsigned short *value;
} TwoByte;
typedef struct FourByte {
unsigned int length;
int *value;
} FourByte;
|
Enables you to reduce the size of the ASN.1 compiler-generated header file by eliminating similar C typedefs. This is useful for multiple instances of parameterized and constrained types which do not satisfy all the requirements for typesharing.
absoluteReference1 refers to the component of the ASN.1 specification that will be substituted.
absoluteReference2 refers to the component that will be used in the substitution.
| ASN.1 | With OSS.UseThis | Without OSS.UseThis |
|---|---|---|
--<OSS.UseThis Module.S1.a Module.S2>--
Module DEFINITIONS ::= BEGIN
S1 ::= SET {
a SET OF INTEGER
}
S2 ::= SET OF INTEGER
END
|
typedef struct S2 {
struct S2 *next;
int value;
} *S2;
typedef struct S1 {
struct S2 *a;
} S1;
|
typedef struct _setof1 {
struct _setof1 *next;
int value;
} *_setof1;
typedef struct S1 {
struct _setof1 *a;
} S1;
typedef struct S2 {
struct S2 *next;
int value;
} *S2;
|
With the OSS.UseThis directive, you can substitute only ASN.1 types. Fields are not allowed.
Enables the compiler to generate a user field defined locally that can be used only for a particular application. User fields can appear in ASN.1 SEQUENCE or SET types and must be either marked as OPTIONAL or DEFAULT. These fields make it easier to handle compiler-generated C data structures. The OSS.USERFIELD directive instructs the encoder to skip the field and the decoder to perceive an error upon receipt of a value which appears in the same context and has the same tag as the user field.
By default, no user field is generated.
For the following example, the encoder and decoder ignores the controlGroup field:
| ASN.1 | .h |
|---|---|
--<OSS.USERFIELD Module.DataCard.controlGroup>--
Module DEFINITIONS ::= BEGIN
DataCard ::= SEQUENCE {
controlGroup BOOLEAN DEFAULT FALSE,
ame PrintableString,
numberOfCars INTEGER (1..5)
}
END
|
typedef struct DataCard {
unsigned char bit_mask;
# define controlGroup_present 0x80
ossBoolean controlGroup; /* user field */
char *ame;
unsigned short numberOfCars;
} DataCard;
|
The compiler cannot generate bit masks for optional user fields.
The compiler subjects user fields to the same ASN.1 restrictions as non-user fields. For example, an OPTIONAL element of a SET or SEQUENCE must have a tag that is different from the element which follows it, regardless of whether either of these elements is a user field.
Specifies whether a C variable should be generated and initialized in the .c file for each ASN.1 value.
| ASN.1 | C |
|---|---|
--<OSS.NOVALUE Module.ID>--
Module DEFINITIONS ::= BEGIN
Name ::= IA5String
ID ::= INTEGER
myName Name ::= "John"
myID ID ::= 12345
END
|
Name myName = "John"; |
Specifies the length-prefixed variable-length string representation for CHARACTER STRING types with a size constraint, BIT STRING types with a named bit list, and OCTET STRING types.
| ASN.1 | .h |
|---|---|
--<OSS.VARYING MyMo.VaryingStr>--
MyMo DEFINITIONS ::= BEGIN
DefaultStr ::= VisibleString (SIZE(10))
VaryingStr ::= VisibleString (SIZE(10))
END |
typedef char DefaultStr[11];
typedef struct VaryingStr {
unsigned short length;
char value[10];
} VaryingStr;
|
The -helperNames option overrides the OSS.VARYING directive.
Enables you to specify the data formatter function for encoding ASN.1 types using XML Encoding Rules. The function that you provide is called each time the XER Encoder adds the encoding of the type affected by this directive to the output buffer; instead of generating the XER encoding for the type, the encoder passes its C value to the user-defined function and expects the encoded value to be returned.
parameterAbsoluteReference specifies an additional ASN.1 type to be used as a parameter of the encoding function; the encoder submits the last instance of the parameter type found in the input PDU value to the user-provided function each time it is called.
yourXEREncodeFunctionName has the following prototype:
int DLL_ENTRY
yourXEREncodeFunctionName(
struct ossGlobal *world,
yourType *in,
[yourParameter *param,]
OssBuf *out,
OssSafeMallocp safemalloc);
When the OSS.XEREncodeFunction directive is applied to an ASN.1 type, the values of this type are not encoded according to the ITU-T X.693/ISO 8825-4 standard; instead, each value is provided to the formatter function for encoding according to custom application requirements.
Also, you can provide an optional C value for the function parameter (NULL is provided when no parameter values are found in the input PDU when calling the XER encoding function). The function must populate the length and value fields of the OssBuf *out structure and return success (one of the values OSS_FORMAT_OK_STATIC or OSS_FORMAT_OK) or an error code (any positive integer).
OSS_FORMAT_OK_STATIC instructs the encoder not to free the memory referenced by the value field of the OssBuf (it is assumed that this memory is not allocated on the heap).
OSS_FORMAT_OK instructs the encoder to free the memory. The XER encoding function can dynamically allocate the output memory only by calling the safemalloc function.
This documentation applies to the OSS® ASN.1 Tools for C release 11.3 and later.
Copyright © 2024 OSS Nokalva, Inc. All rights reserved.
No part of this publication may be reproduced, stored in a retrieval system, or transmitted in any form or by any means electronic, mechanical, photocopying, recording or otherwise, without the prior permission of OSS Nokalva, Inc.
Every distributed copy of the OSS® ASN.1 Tools for C is associated with a specific license and related unique license number. That license determines, among other things, what functions of the OSS ASN.1 Tools for C are available to you.