This section lists the compiler directives and provides a thorough description of their function.
Does not allow the compiler to automatically decode a particular component within SET, SEQUENCE, or CHOICE, and SET OF or SEQUENCE OF elements when its containing type is marked for decoding.
The component referred to by the absolute reference is represented as the Oss.Asn1.DeferredComponent runtime library generic class type. The class type includes the Encoded property, which allows access to the encoded deferred component, and the Decoded property, which allows access to the decoded deferred component.
The Oss.Asn1.DeferredComponent class can store a component either in the encoded form as a byte array or in the decoded form as an object of the Oss.Asn1.BasePdu runtime library class.
| ASN.1 | C# |
|---|---|
--<ASN1.DeferDecoding Module.Type.f1d>--
Module DEFINITIONS ::= BEGIN
Type ::= SET {
f1d INTEGER,
f2 BOOLEAN
}
END
|
/// <summary>
/// Represents schema type 'Type' (SET)
/// </summary>
[System.Serializable]
public partial class Type : Oss.Asn1.BasePdu
{
/// <summary>Field 'f1d'</summary>
public Oss.Asn1.DeferredComponent<TypeF1dEncodable> F1d { get; set; }
/// <summary>Field 'f2'</summary>
public bool F2 { get; set; }
...
}
|
The representation shown above in bold is generated only when the DeferDecoding directive is set. The TypeF1dEncodable type parameter is the representation generated for the f1d component type to store the component in decoded form as an object of the Oss.Asn1.BasePdu class.
The ASN1.DeferDecoding directive is supported for BER and DER. Do not use it with any other encoding rules.
The IgnoreDeferredDecoding property of Oss.Asn1.BaseDecoderOptions allows you to store all deferred components in the encoded form when IgnoreDeferredDecoding is set as false (by default) or decode them, when IgnoreDeferredDecoding is set as true.
Except for BER and DER, for all encoding rules, all components of SET, SEQUENCE, CHOICE, SET OF, or SEQUENCE OF types are decoded with their containing type.
Sets a special representation for INTEGERs whose size is not limited by the C# long integer type. When either directive is used, the corresponding INTEGER types are represented by the System.Numerics.BigInteger value type. By default, INTEGER types are represented by int or long depending on the value range constraints imposed on the INTEGER type.
The OSS.HUGE directive supports both global and local forms. When specified globally, type refers to an ASN.1 INTEGER type that will be represented using the BigInteger representation. Also, when OSS.HUGE is applied globally with no parameters, it applies to all integers in the schema. When specified locally, the directive takes no operands.
The ASN1.HugeInteger directive requires a parameter and it cannot be applied to all integers.
We stand with Ukraine HugeInt DEFINITIONS ::= BEGIN
A ::= INTEGER --<HUGE>--
END
--<ASN1.HugeInteger LengthModule.LengthData.lengthOfSolarSystem>--
LengthModule DEFINITIONS ::= BEGIN
LengthData ::= SEQUENCE {
lengthOfSolarSystem INTEGER,
units ENUMERATED{mm(0), cm(1), m(2), km(3), lightyears(4)}
}
END
These directives are available in version 4.4 and later.
Provides an alias to a type or module name from an ASN.1 module to be used in the generated code.
By default, the name used in the generated C# classes is derived from the ASN.1 input file.
In the following notation, the MTN nickname is used for the MyTypeName type, which is an element of MySequence within MyModule.
--<ASN.1.Nickname MyModule.MySequence.MyTypeName MTN>--
The following example illustrates how to name types and identifiers:
| ASN.1 | C# |
|---|---|
--<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
|
public partial class Monkey : System.Collections.Generic.List<Gorilla>
{
...
}
public partial class Gorilla
{
/// <summary>Field 'key'</summary>
public int Gibbon { get; set; }
/// <summary>Field 'fvalue'</summary>
public byte[] Mandrill { get; set; }
...
}
|
"*" 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 | C# |
|---|---|
--<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
|
public partial class E : Oss.Asn1.BasePdu
{
public enum Values
{
NoValue = 0,
new_enum1 = 1,
Enum2 = 2
}
public Values Value { get; set; }
...
}
public partial class B : Oss.Asn1.BasePdu
{
public enum Values
{
NoValue = 0,
new_bit1 = 4,
Bit2 = 8
}
public Oss.Asn1.BitStringWithNamedBits Value { get; set; }
...
}
public partial class I : Oss.Asn1.BasePdu
{
public enum Values
{
NoValue = 0,
new_int1 = 10,
Int2 = 8
}
public int Value { get; set; }
...
}
|
Indicates whether an ASN.1 type should be a Protocol Data Unit (PDU).
By default, only unreferenced types are considered PDUs by the compiler, therefore can be encoded/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 or decimal) to be used 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. By default, the REAL type is represented by the double C# type.
The realKind operand can be binary or decimal. It specifies how the REAL type should be represented in the generated .cs files.
| ASN.1 | C# |
|---|---|
--<ASN1.RealRepresentation decimal Module.MyType.a1.b2>--
Module DEFINITIONS ::= BEGIN
MyType ::= SEQUENCE {
a1 SET { b1 INTEGER, b2 REAL },
a2 REAL
}
END
|
///<summary>Field 'b2'</summary>
public decimal B2 { get; set; }
///<summary>Field 'a2'</summary>
public double A2 { get; set; }
|
In the above example, the decimal C# type is used to represent the field b2 of the field a1 of the type MyType, while the field a2 of the type MyType is represented by the double C# type.
For a global effect, the ASN1.RealRepresentation directive must be used with no type references and placed before the first module in the ASN.1 input.
Instructs the ASN.1 compiler to ignore certain ASN.1 types or components. The compiler does not generate code for these types. This is useful when you want to omit certain parts of an ASN.1 specification without modifying the original ASN.1 source.
ref can refer to: defined types, defined values, members of CHOICE types (excluding the last of the remaining), components that are marked OPTIONAL in a SEQUENCE or SET type, components that have a DEFAULT value in a SEQUENCE or SET type, information object classes, information objects that are not included in information object sets, information object sets.
The ASN1.Remove directive informs the compiler that an ASN.1 item should be treated as if it was not included in the ASN.1 source text, in other words, no associated code is generated in the .cs files for this type for use by the application. However, removal of components leads to encodings that are perfectly compatible with counterpart applications that do not use the ASN1.Remove directive. By default, all parts of the ASN.1 input are included in the compiler-generated files.
In the following example, after compiling the syntax, an empty class structure S with no component accessor or mutator methods is generated in the .cs file:
| ASN.1 | C# |
|---|---|
--<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
}
v S ::= {}
Int ::= INTEGER
i Int ::= 10
END
|
/// <summary>
/// Represents schema type 'S' (SET)
/// </summary>
[System.Serializable]
public partial class S : Oss.Asn1.BasePdu
{
/// <summary>
/// Determines whether the specified object is equal to the current object.
/// </summary>
/// <param name="right">The object to compare with this object. </param>
/// <returns>true if the specified object is equal to the current object; otherwise, false.</returns>
public override bool Equals(object right)
...
}
|
Also, no static readonly variable and static property are created in the Values.cs module class to represent the value i.
--<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
The .rmv file will contain the following ASN1.Remove directives for types, values, components that reference items marked for removal:
When an ASN.1 item is marked for removal, any references to the item must also be removed (by using the ASN1.Remove directive). 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 a file with an .rmv extension (this file will have the same prefix as the .gen file).
The generated .rmv file can be passed at the command-line (before any compiler options) to let the compiler automatically remove the types that are causing problems.
Under special circumstances, the ASN1.Remove directives cannot be generated into the .rmv file. In such a case, you should successively call the ASN.1 compiler several times (correcting the syntax) until the ASN.1 notation compiles correctly.
The listing file generated with the -listingFile command-line option omits removed items entirely. To get a full listing with removed items included, use the -modListingFile command-line option.
Standard directives applied to or found inside ASN.1 items marked for removal have no effect.
The ASN1.Remove directive applied to the fields of a parameterized type results in removing those fields from each instance of the parameterized type, and therefore we do not recommend it.
Removing fields from a type that is referenced in the COMPONENTS OF type notation results in removing those fields from each type specified with the COMPONENTS OF type notation.
With the CANONICAL-XER encoder the ASN1.Remove directive cannot be applied to a SET or SEQUENCE component with a default value (see the ITU-T Recommendation X.693 (11/2008) paragraphs 9.5 and 9.6.3).
This directive is useful for applications that have several versions of ASN.1 source in use.
If ASN1.Version conflicts with a -1990 | -2021 compiler option, the higher version year 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.
name 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.
If type is a module name, this directive has the same effect as the OSS.ROOT directive, which causes all unreferenced types within this module to be considered PDUs.
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.
Determines the representation of the ASN.1 UTF8String type as either a C# string (default) or int[], which is the same as the representation of an ASN.1 UniversalString.
In the following example, TwoByteLocal is set to the BMPString representation and FourTypeGlobal - to the UniversalString representation.
| ASN.1 | C# |
|---|---|
--<OSS.UNIVERSALSTRING Module.FourByteGlobal>--
Module DEFINITIONS ::= BEGIN
DefaultRepresentation ::= UTF8String
TwoByteLocal ::= UTF8String --<BMPSTRING>--
FourByteGlobal ::= UTF8String
END
|
public partial class DefaultRepresentation : Oss.Asn1.BasePdu
{
public string Value { get; set; }
...
}
public partial class TwoByteLocal : Oss.Asn1.BasePdu
{
public string Value { get; set; }
...
}
public partial class FourByteGlobal : Oss.Asn1.BasePdu
{
public int[] Value { get; set; }
...
}
|
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.
Associates a field of a SEQUENCE or SET type, an alternative of a CHOICE type, or an element of a SEQUENCE OF or 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 absoluteReference to a field.
FunctionName is used to construct names of the user-defined callback methods. There are two callback methods per directive: BeginFunctionName() and EndFunctionName().
When specified locally, the OSS.DataCallback directive must be placed next to the field definition, as shown in the following example:
age INTEGER(1..100) --<DataCallback "FunctionName">--,
It is 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.
Determines the representation of the ASN.1 REAL type as either a C# double (default) or decimal.
In the following example, the OSS.DECIMAL directive is used, therefore the local DOUBLE directive overrides the global default set:
| ASN.1 | C# |
|---|---|
--<OSS.DECIMAL>--
--<OSS.DOUBLE Module.DataFolder.b>--
Module DEFINITIONS ::= BEGIN
DataFolder ::= SEQUENCE {
a REAL --<DOUBLE>--,
b REAL,
c REAL
}
END
|
public partial class DataFolder : Oss.Asn1.BasePdu
{
/// <summary>Field 'a'</summary>
public double A { get; set; }
/// <summary>Field 'b'</summary>
public double B { get; set; }
/// <summary>Field 'c'</summary>
public decimal C { get; set; }
...
}
|
Instructs the ASN.1 compiler to use the specified newName for a value, field in a structure, or a type.
| ASN.1 | C# |
|---|---|
--<OSS.FIELDNAME MyMo.Item.available inStock>--
--<OSS.TYPENAME MyMo.Name Title>--
MyMo DEFINITIONS ::= BEGIN
Name ::= IA5String Item ::= SEQUENCE {
available BOOLEAN,
count INTEGER
}
END
|
public partial class Item : Oss.Asn1.BasePdu
{
/// <summary>Field 'available'</summary>
public bool inStock { get; set; }
/// <summary>Field 'count'</summary>
public int Count { get; set; }
...
}
public partial class Title : Oss.Asn1.BasePdu
{
public string Value { get; set; }
...
}
|
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.
Used when an OSS.DataCallback directive is applied to a type that occurs in multiple locations in a message.
For the following 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 such as
--<OSS.DataCallback M.Address.zipcode "ZipCode">--
would cause the BeginZipCode() and EndZipCode() methods to be called for both PackageInfo.from.zipcode and PackageInfo.to.zipcode, but the methods would not be able to differentiate the two fields. Use OSS.InfoCallback to solve the problem. By employing --<OSS.InfoCallback M.PackageInfo.from "fromAddress">-- you instruct the compiler to use the BeginfromAddress() and EndfromAddress() callback methods. The BeginfromAddress() method is invoked before partial decoding of the from field begins and the EndfromAddress() method is invoked after its decoding is finished.
Determines the representation of the ASN.1 INTEGER type as a C# long (64-bit).
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 locally (inline).
Disables generation of C# value representations for the specified name.
| ASN.1 | C# |
|---|---|
--<OSS.NOVALUE Module.ID>-- Module DEFINITIONS ::= BEGIN Name ::= IA5String ID ::= INTEGER myName Name ::= "John" myID ID ::= 12345 END |
public static class Values
{
private static readonly Name _myName = new Name {
Value = "John"
};
/// <summary>Represents schema value 'Module.myName'</summary>
public static Name MyName {
get {
return _myName;
}
}
}
|
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. If no module is provided, all input modules are considered 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)}>--
Disables printing of specific informatory and warning messages.
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 are 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
This documentation applies to the OSS® ASN.1 Tools for C# release 5.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.