Contents
Checks whether runtime constraint-checking information is present in the ASN.1 compiler-generated control table. This information enables extensive constraint checking at runtime.
By default, constraint-checking information is generated.
world is a pointer to the OSS global environment variable.
ossConstrainWasSpecified() returns an ossBoolean type. When the -constraints compiler option is specified, a value of TRUE is returned. When the -noConstraints option is specified, a value of FALSE is returned.
Returns the internal version number of the control table in use. This function can be used to compare two different control tables for compatibility.
world is a pointer to the global OSS environment variable, which is initialized with a call to ossinit() or ossWinit() with a pointer to a control table (the pointer declared at the end of the generated header file).
ossCtlTblVersionNumber() returns an unsigned short integer. If the passed OssGlobal variable is valid, a positive two-digit integer is returned; otherwise, a value of zero or a negative value is issued.
Checks whether PER encoding/decoding information is present in the ASN.1 compiler-generated control table. The information consists of preprocessed subtype data and data for sorting SET and CHOICE types required by PER.
By default, information for PER encoding/decoding is not generated.
world is a pointer to the OSS global environment variable.
ossCtlTblUsableOnlyByBER() returns an ossBoolean type. When the -per ASN.1 compiler option is not specified, a value of TRUE is returned; otherwise when the -per or -uper option is specified, a value of FALSE is returned.
Checks whether BER encoding/decoding information is present in the ASN.1 compiler-generated control table. The information consists of tag information for ASN.1 types required by BER.
By default, information for BER encoding/decoding is generated.
world is a pointer to the global OSS environment variable.
ossCtlTblUsableOnlyByPER() returns an ossBoolean type. When the -ber compiler option is specified, a value of TRUE is returned; otherwise when the -per or -uper option is specified and the -ber or -der option is not specified, a value of FALSE is returned.
Checks whether debugging code is present in the ASN.1 compiler-generated control table.
By default, additional code is generated. The code contains information about the identifiers and type references in the input ASN.1 syntax.
world is a pointer to the OSS global environment variable.
ossDebugWasSpecified() returns an ossBoolean type. When the -debug compiler option is specified, a value of TRUE is returned; otherwise when the -noDebug or -minimize compiler option is specified, a value of FALSE is returned.
Returns the ASN.1 identifier of a specified element in a BIT STRING with a named bit list, ENUMERATED, INTEGER with a named number list, SEQUENCE, SET, or CHOICE type.
ossAsn1ItemName() returns a pointer to a character string. If debugging information exists for the element in question, the ASN.1 identifier of the element is returned; otherwise, an empty " " string is returned. (-noDebug was specified or implied). A value of NULL is returned if the specified type cannot have an identifier or the specified index is out of range.
The ossAsn1ItemName() function has no effect if the input ASN.1 specification is compiled with the -noDebug option. To check if the option was specified, use the ossDebugWasSpecified() function at runtime.
Since the ASN.1 compiler sorts the components of SET and CHOICE types by the tag order when -per is specified, their order in the control table can be different from their definition order. However, when -per is not specified, the definition order is preserved.
Is used to find the ASN.1 class of a specified tag in an ASN.1 type definition.
ossAsn1TagClass() returns an enumerator of type ASN1TagClass. If tag information exists for the element in question, the ASN.1 tag class of the element is returned; otherwise, the UNIVERSAL enumerator is returned, which indicates that no tag information is present (-per is specified instead of -ber). ASN1TagClass has the following definition in ossiaapi.h:
We stand with Ukraine 
typedef enum ASN1TagClass {
UNIVERSAL, APPLICATION, CONTEXT_SPECIFIC, PRIVATE, NULLENCODING
} ASN1TagClass;
Retrieves the ASN.1 tag number (23 in [UNIVERSAL 23], for example) of a specified tag in the ASN.1 type definition.
ossAsn1TagNumber() returns an integer. If tag information exists for the element in question, the ASN.1 tag number of the element is returned; otherwise, a value of zero is returned, which indicates that no tag information is present (-per was specified instead -ber).
Checks the ASN.1 compiler-generated control table to determine the basic ASN.1 built-in type of data based on its type handle.
ossAsn1TypeId() returns the integer value that corresponds to an enumerator of type ASN1Type. If the passed type handle corresponds to a basic built-in ASN.1 type, its appropriate enumerator is returned; otherwise, the asn1UnknownType enumerator is returned. ASN1Type has the following definition in the ossiaapi.h header file:
typedef enum ASN1Type {
asn1UnknownType = 0,
asn1ANY = 1,
asn1BIT_STRING = 2,
asn1BMPString = 3,
asn1BOOLEAN = 4,
asn1CHARACTER_STRING = 5,
asn1CHOICE = 6,
asn1CLASS = 7,
asn1DATE = 8,
asn1DATE_TIME = 9,
asn1DURATION = 10,
asn1EMBEDDED_PDV = 11,
asn1ENUMERATED = 12,
asn1EXTERNAL = 13,
asn1GeneralizedTime = 14,
asn1GeneralString = 15,
asn1GraphicString = 16,
asn1IA5String = 17,
asn1INSTANCE_OF = 18,
asn1INTEGER = 19,
asn1NULL = 20,
asn1NumericString = 21,
asn1ObjectDescriptor = 22,
asn1OBJECT_IDENTIFIER = 23,
asn1OCTET_STRING = 24,
asn1OID_IRI = 25,
asn1OpenType = 26,
asn1PrintableString = 27,
asn1REAL = 28,
asn1RELATIVE_OID = 29,
asn1RELATIVE_OID_IRI = 30,
asn1SEQUENCE = 31,
asn1SEQUENCE_OF = 32,
asn1SET = 33,
asn1SET_OF = 34,
asn1TeletexString = 35,
asn1TIME = 36,
asn1TIME_OF_DAY = 37,
asn1UniversalString = 38,
asn1UTCTime = 39,
asn1UTF8String = 40,
asn1VideotexString = 41,
asn1VisibleString = 42,
asn1ArbitraryType = 43
} ASN1Type;
The above enumerators are in alphabetical order. Also, asn1SEQUENCE is returned for EXTERNAL types.
int typeId;
....
typeId = ossAsn1TypeId(world, handleOfPDU);
switch(typeId) {
case asn1SET: case asn1SEQUENCE:
case asn1CHOICE:
case asn1SET_OF: case asn1SEQUENCE_OF:
case asn1OpenType:
/* handle as structured type */
break;
default:
/* handle as a simple type */
}
....
Converts an enumerator of type ASN1Type into a parsable character string whose name is derived from the ASN.1 built-in type to which the enumerator corresponds.
ossBuiltinTypeName() returns the address of the character string. If the passed enumerator corresponds to the one found in the ASN1Type enumeration type, the corresponding character string name is returned; otherwise the "Unknown type" character string is returned. The following table lists the character strings that are returned for each enumerator:
| Enumerator | Corresponding Character String |
|---|---|
asn1UnknownType |
"Unknown type" |
asn1ANY |
"ANY" |
asn1BIT_STRING |
"BIT STRING" |
asn1BMPString |
"BMPString" |
asn1BOOLEAN |
"BOOLEAN" |
asn1CHARACTER_STRING |
"CHARACTER STRING" |
asn1CHOICE |
"CHOICE" |
asn1CLASS |
"CLASS" |
asn1DATE |
"DATE" |
asn1DATE_TIME |
"DATE-TIME" |
asn1DURATION |
"DURATION" |
asn1EMBEDDED_PDV |
"EMBEDDED PDV" |
asn1ENUMERATED |
"GraphicString" |
asn1EXTERNAL |
"EXTERNAL" |
asn1GeneralizedTime |
"GeneralizedTime" |
asn1GeneralString |
"GeneralString" |
asn1GraphicString |
"GraphicString" |
asn1IA5String |
"IA5String" |
asn1INSTANCE_OF |
"INSTANCE OF" |
asn1INTEGER |
"INTEGER" |
asn1NULL |
"NULL" |
asn1NumericString |
"NumericString" |
asn1ObjectDescriptor |
"ObjectDescriptor" |
asn1OBJECT_IDENTIFIER |
"OBJECT IDENTIFIER" |
asn1OCTET_STRING |
"OCTET STRING" |
asn1OID_IRI |
"OID-IRI" |
asn1OpenType |
"ABSTRACT-SYNTAX.&Type" |
asn1PrintableString |
"PrintableString" |
asn1REAL |
"REAL" |
asn1RELATIVE_OID |
"RELATIVE-OID" |
asn1RELATIVE_OID_IRI |
"RELATIVE-OID-IRI" |
asn1SEQUENCE |
"SEQUENCE" |
asn1SEQUENCE_OF |
"SEQUENCE OF" |
asn1SET |
"SET" |
asn1SET_OF |
"SET OF" |
asn1TeletexString |
"TeletexString" |
asn1TIME |
"TIME" |
asn1TIME_OF_DAY |
"TIME-OF-DAY" |
asn1UniversalString |
"UniversalString" |
asn1UTCTime |
"UTCTime" |
asn1UTF8String |
"UTF8String" |
asn1VideotexString |
"VideotexString" |
asn1VisibleString |
"VisibleString" |
asn1ArbitraryType |
"Arbitrary type" |
Reports whether a PER-visible extension marker is present in a specified ASN.1 type.
ossExtensionMarkerIsPresent() returns an ossBoolean type. If the passed handle corresponds to an ASN.1 type with an extension marker, a value of TRUE is returned; otherwise, a value of FALSE is returned.
Returns the number associated with a named bit, named number, or enumerator associated with a BIT STRING, INTEGER, or ENUMERATED type.
ossItemIntValue() returns a long integer. If the type handle corresponds to a BIT STRING with a named bit list, ENUMERATED, or INTEGER type with a named number list, the number associated with the (ix + 1)st / nd / rd / th named bit, named number, or enumerator is returned; otherwise, a value of LONG_MAX is returned.
The function could work incorrectly with a named number that does not fit the LONG_MIN..LONG_MAX range.
Returns the number associated with a named bit, named number, or enumerator associated with a BIT STRING with a named bit list, an INTEGER with a named number list, or an ENUMERATED type.
To correctly work with a named number that does not fit the LONG_MIN..LONG_MAX range, use the ossItemIntValueLL() function instead of ossItemIntValue().
ossItemIntValueLL() returns a long long integer. If the type handle corresponds to a BIT STRING with a named bit list, ENUMERATED, or INTEGER type with a named number list, the number associated with the (ix + 1)st / nd / rd / th named bit, named number, or enumerator is returned; otherwise, a value of LLONG_MAX is returned.
Retrieves the number of artificial PDUs created by the ASN.1 compiler for built-in types defined in information objects or in open type values. Artificial PDUs are created only if the input ASN.1 syntax contains at least one information object set.
world is a pointer to the OSS global environment variable that is initialized (via ossinit() or ossWinit()) for a particular control table.
ossNumberOfArtificialPDUs() returns an integer. If the input ASN.1 specification has at least one information object set and there are PDUs artificially created by the ASN.1 compiler for built-in types from information objects or open type values, the number of artificial PDUs is returned; otherwise, a value of zero is returned.
Returns the number of named items in an ASN.1 type with named items (alternatives of a CHOICE type or named bits of a BIT STRING type, for example).
ossNumberOfNamedItems() returns an integer. If the passed type handle corresponds to a BIT STRING with a named bit list, CHOICE, ENUMERATED, INTEGER with a named number list, SEQUENCE, or SET type, a count of the named items in the type is returned; otherwise, a value of zero is returned.
Returns the total number of messages (PDUs) found in an ASN.1 specification.
world is a pointer to the OSS global environment variable that is initialized (via ossinit() or ossWinit()) for a particular control table.
ossNumberOfPDUs() returns an integer. If the input ASN.1 specification has unreferenced types or types explicitly marked with the PDU directive, the number of PDUs is returned; otherwise, a value of zero is returned.
Returns the number of ASN.1 tags found in a particular ASN.1 type.
ossNumberOfTags() returns an integer. If tag information exists for the specified type, the number of ASN.1 tags present in the type's original specification is returned; otherwise, a value of zero is returned, which indicates that no tag information is present (in other words, -per is specified, but -ber is not specified).
....
TypeHndl th1;
ossinit(world, asn1data);
th1 = ossTypeHandleOfPDU(world, CallRecord_PDU);
ossPrint(world, "PDU CallRecord contains %d tag(s).\n",
ossNumberOfTags(world, th1));
ossterm(world);
CallRecord can be an ASN.1 type with explicit user-defined tagging. The number of tags returned indicates how many tags would be encoded for that type in BER/DER. Thus, implicitly tagged types will usually have one encoded tag and explicitly tagged types will have two encoded tags.
Retrieves the PDU number of a type based on its type handle.
ossPduNumberByType() returns an integer. If the passed type handle corresponds to a PDU, the PDU number of this type is returned; otherwise, a value of zero is returned.
PDU numbers assigned by the OSS ASN.1 Tools start from 1.
Retrieves a type handle of a PDU based on its type reference in the ASN.1 input.
ossPduTypeHandleByName() returns a TypeHndl type. If the sent name corresponds to a type reference of a PDU in the input ASN.1 specification, a type handle for this specified PDU is returned; otherwise, a value of NULL is returned.
Retrieves the type handle associated with a PDU based on its compiler-generated typename_PDU constant. You can pass the returned handle to the other IAAPI functions that require this type of handle for type identification.
ossTypeHandleOfPDU() returns a TypeHndl type. If the input ASN.1 specification has unreferenced types or types explicitly marked with the PDU directive, the type handle of the PDU with the passed identification constant is returned; otherwise, a value of NULL is returned.
Retrieves the name given to a particular user-defined type in the input ASN.1 specification.
ossTypeReferenceName() returns a character string pointer. If the passed type handle corresponds to a user-defined type (and the -noDebug option is not specified or implied), the user-defined name of this type is returned. If the passed type handle corresponds to a built-in type, a value of NULL is returned. If no debugging information is generated for the input ASN.1 syntax, an empty character string is returned ("", for example).
The ossTypeReferenceName() has no effect if the input ASN.1 specification was compiled with the -noDebug option. To check if the option was specified, use the ossDebugWasSpecified() function at runtime.
The IAAPI functions listed in this section will not work properly if the input ASN.1 specification was compiled with the -noConstraints option. To check if the option was specified, use the ossConstrainWasSpecified() function at runtime.
Reports whether a specified type (a constrained INTEGER, restricted character string, BIT STRING, OCTET STRING, SET OF, or SEQUENCE OF) has a subtype constraint defining a finite lower bound. MIN is not considered a finite lower bound.
ossLowerBoundIsPresent() returns an ossBoolean. If the specified type has a subtype constraint with a finite lower bound, a value of TRUE is returned; otherwise, a value of FALSE is returned.
Returns the smallest allowed size of a specified type, as indicated by a subtype constraint in the ASN.1 specification.
ossLowerBoundOfSizeConstraint() returns an ossBoolean type. If the specified type has a PER-visible size constraint with a finite lower bound, the smallest valid size (for restricted character string, BIT STRING, or OCTET STRING types, for example) or the smallest number of allowed elements (for SEQUENCE OF and SET OF types, for example) is returned; otherwise, a value of zero is returned.
A size constraint is not PER-visible if it is defined with the MIN or MAX keywords or if the difference between the upper and lower bounds is more than 64K.
Retrieves the smallest value that a particular INTEGER type can hold. If the type is constrained with a lower bound, the lower bound is returned; otherwise, the smallest allowed negative integer value (defined in limits.h as LONG_MIN or LLONG_MIN) is returned.
ossMinValueOfInteger() does not return a value.
Retrieves the largest value that a particular INTEGER type can hold. If the type is constrained with an upper bound, the upper bound is returned; otherwise, the largest allowed positive integer value (defined in limits.h as LONG_MAX or LLONG_MAX) is returned.
ossMaxValueOfInteger() does not return a value.
IntValue is defined as follows in ossiaapi.h:
typedef struct {
enum {signedNumber, unsignedNumber} sign;
union {
LONG_LONG signedInt;
ULONG_LONG unsignedInt;
} value;
} IntValue;
The sign enumerator determines whether the returned value is contained in value.signedInt or value.unsignedInt.
Returns an array of character values that form the effective permitted alphabet of a NumericString, PrintableString, VisibleString, or IA5String type. When the type has a PER-visible permitted alphabet constraint applied, the characters in this constraint are returned.
ossPermittedAlphabetConstraint() returns an array of long integers. If the passed type handle corresponds to a supported character string type, an array of long integers is returned. Each element in the array corresponds to a Unicode/ASCII character value; otherwise, a value of NULL is returned.
When the ossPermittedAlphabetLength() function returns a value of zero, the effective permitted alphabet is the default permitted alphabet which is returned by ossPermittedAlphabetConstraint(). The default permitted alphabet is the set of characters that can appear in the string when no permitted alphabet constraint is defined. The length of the default permitted alphabet is as follows:
Returns the length of the permitted alphabet of a type defined with a PER-visible permitted alphabet constraint.
ossPermittedAlphabetLength() returns an unsigned long integer. If the passed type handle corresponds to a type with a PER-visible permitted alphabet constraint applied, the length in characters of the constraint is returned (as long as the permitted alphabet defined by the constraint is different from the default alphabet set); otherwise, a value of zero is returned.
A PER-visible constraint is a constraint for which no value references that violate the constraint are defined. For example:
greeting Msg ::= "Hello"
Msg ::= IA5String (SIZE(5) | FROM("ABC"))
FROM("ABC") in Msg is not a PER-visible permitted alphabet constraint. This is because a value reference exists (greeting), which does not satisfy the constraint. A value of zero is returned by this function for all the non-PER-visible constraints.
Reports whether subtype constraint information is present for a specified type.
Starting with version 10.1, the function returns FALSE for types with contents constraints to which the OSS.NoConstrain directive was applied.
ossTypeIsConstrained() returns an ossBoolean type. If the specified type has subtype constraint information associated with it, a value of TRUE is returned; otherwise, a value of FALSE is returned.
Reports whether a specified type (a constrained INTEGER, restricted character string, BIT STRING, OCTET STRING, SET OF, or SEQUENCE OF) has a subtype constraint that defines a finite upper bound. MAX is not considered a finite upper bound.
ossUpperBoundIsPresent() returns an ossBoolean type. If the specified type has subtype constraint with a finite upper bound, a value of TRUE is returned; otherwise, a value of FALSE is returned.
Upper bound information is not available if an ASN.1 type (restricted character string, BIT STRING, or OCTET STRING) has the --<LINKED>-- or --<DLINKED>-- directive applied to it in the ASN.1 specification.
Returns the largest allowed size of a specified type, as indicated by a subtype constraint in the ASN.1 specification.
ossUpperBoundOfSizeConstraint() returns an ossBoolean type. If the specified type has a PER-visible size constraint with a finite upper bound, the largest valid size (for restricted character string, BIT STRING, or OCTET STRING types, for example) or the largest number of allowed elements (for SEQUENCE OF and SET OF types, for example) is returned; otherwise, a value of zero is returned.
A size constraint is not PER-visible if it is defined with the MIN or MAX keywords or if the difference between the upper and lower bounds is more than 64K.
Returns an array and the number of character values that form the effective permitted alphabet of a NumericString, PrintableString, VisibleString, IA5String type, BMPString, UniversalString, or UTF8String. When the type has a PER-visible permitted alphabet constraint applied, the characters in the constraint are returned.
The array returned by the function must be freed by the caller with ossFreeMemory().
ossWidePermittedAlphabet() returns an array of unsigned long integers. If the type handle passed corresponds to a supported character string type, an array of unsigned long integers is returned in which each element corresponds to a Unicode/ASCII character value and the number of characters is returned in the last parameter; otherwise, a value of NULL is returned.
....
unsigned long permAlphaLen = 0;
unsigned long *permAlphabet = ossWidePermittedAlphabet(world, type,
&permAlphaLen);
if (permAlpabet) {
for (i = 0; i < permAlphaLen; i++) {
unsigned long pa = permAlphabet[i];
...
}
ossFreeMemory(world, permAlphabet);
}
The IAAPI supports functions for retrieving contents constraints information as defined in the ASN.1:2021 standard.
The IAAPI functions listed in this section will not work properly if the input ASN.1 specification was compiled with the -noConstraints option. To check if the option was specified, use the ossConstrainWasSpecified() function at runtime.
Checks whether a type defined with a contents constraint has an associated ENCODED BY clause. If the ENCODED BY clause is specified in the type's contents constraint, the ossContainedTypeEncodingRule() function returns an ossEncodingRules enumeration (OSS_BER, OSS_PER_ALIGNED, OSS_PER_UNALIGNED, OSS_DER, OSS_ECN, OSS_XER, OSS_CXER, and OSS_CER, for example) that corresponds to the encoding rule specified in the ENCODED BY clause.
ossContainedTypeEncodingRule() returns an integer type. If the specified type has a contents constraint with ENCODED BY information associated with it, a value of the ossEncodingRules enumeration defined in ossglobl.h (OSS_BER, OSS_PER_ALIGNED, OSS_PER_UNALIGNED, OSS_DER, OSS_ECN, OSS_XER, OSS_CXER, and OSS_CER) is returned; otherwise, a value of -1 is returned.
Returns a PDU identifier of a type specified in the CONTAINING clause in a contents constraint if it is present in the input ASN.1 notation.
When using control tables created by version 10.1 and later of the ASN.1 compiler, ossContainedTypePduNumber() returns the containing PDU number even if OSS.NoConstrain is applied to the type, though the "decoded" component of the contained type is never initialized or freed by other IAAPI functions. It is your responsibility to free the "decoded" component if you initialize it manually. To determine whether OSS.NoConstrain is applied, call ossTypeIsConstrained().
ossContainedTypePduNumber() returns an integer type. If the specified type has contents constraint with CONTAINING information associated with it, a PDU number of the type specified in the CONTAINING clause is returned; otherwise, a value of 0 is returned.
Returns the value notation of an ASN.1 object identifier given its encoding rules enumerator. You can pass the value returned by ossContainedTypeEncodingRule() to this function.
typedef enum {
OSS_BER = 0,
OSS_PER_ALIGNED,
OSS_PER_UNALIGNED,
OSS_DER,
OSS_ECN,
OSS_XER,
OSS_CXER,
OSS_CER,
OSS_EXER
} ossEncodingRules;
ossEncodingRuleObjid() returns a pointer to a const char value. If the specified ruleId is one of ossEncodingRules enumeration values, a corresponding string from the list below is returned; otherwise, the "unknown encoding rule" string is returned.
"{joint-iso-itu-t(2) asn1(1) basic-encoding(1)}"
"{joint-iso-itu-t(2) asn1(1) packed-encoding(3) basic(0) aligned(0)}"
"{joint-iso-itu-t(2) asn1(1) packed-encoding(3) basic(0) unaligned(1)}"
"{joint-iso-itu-t(2) asn1(1) ber-derived(2) distinguished-encoding(1)}"
"{joint-iso-itu-t(2) asn1(1) ecn(4)}"
"{joint-iso-itu-t(2) asn1(1) xml-encoding(5) basic(0)}"
"{joint-iso-itu-t(2) asn1(1) xml-encoding(5) canonical(1)}"
"{joint-iso-itu-t(2) asn1(1) ber-derived(2) canonical-encoding(0)}"
"{joint-iso-itu-t(2) asn1(1) xml-encoding(5) extended(2)}"
Retrieves contents information for a BIT STRING or OCTET STRING type with a contents constraint. Specifically, either the encoded value of the contained type or its decoded value is retrieved via the last two function arguments.
ossGetContainedTypeValue() returns an enumerator of type IAAPI_ERRTYPE. If the passed type handle and containingValue field correspond to a type with a contents constraint and no other error occurs, the IAAPI_NOERROR enumerator is returned; otherwise, an IAAPI error code which indicates the type of error that occurred is returned.
Inserts the decoded value of a contained type into the value of a BIT STRING or OCTET STRING type with a contents constraint. The latter value is created if the last parameter points to NULL.
The ossPutEncodedValue() function can be used to add the encoded value of the contained type to the containing structure created for BIT STRING and OCTET STRING types with ContentsConstraint.
ossPutContainedTypeDecodedValue() returns an enumerator of type IAAPI_ERRTYPE. If the passed type handle corresponds to a BIT STRING or OCTET STRING type with contents constraint and no other error occurs, the IAAPI_NOERROR enumerator is returned; otherwise, an IAAPI error code is returned.
Informs you of whether a BIT STRING or OCTET STRING has contents constraint in the input ASN.1 syntax.
ossTypeHasContentsConstraint() returns an ossBoolean type. If the specified type was defined with a contents constraint, a value of TRUE is returned; otherwise, a value of FALSE is returned.
Determines whether a component of a SET, SEQUENCE, or CHOICE type appears after an extension marker ("...") and is optional.
ossCompAppearsAfterExtensionMarker() returns an ossBoolean type. If the specified component is an extension addition, a value of TRUE is returned; otherwise, a value of FALSE is returned. A value of FALSE is also returned if the type handle does not correspond to a SET, SEQUENCE, or CHOICE type.
Retrieves the DEFAULT value of a component in a SET or SEQUENCE type.
ossComponentDefaultValue() returns a constant void pointer. If the specified SET or SEQUENCE type has a component with a DEFAULT value at the specified index, the address of the default value (in decoded format) is returned; otherwise, a value of NULL is returned. A value of NULL is also returned if the type handle does not correspond to a SET or SEQUENCE type (for example, it corresponds to a CHOICE type instead).
Checks whether a DEFAULT value is present for a component of a SET or SEQUENCE type.
ossComponentHasDefaultValue() returns an ossBoolean type. If the specified SET or SEQUENCE type has a component with a valid non-NULL DEFAULT value at the specified index, a value of TRUE is returned; otherwise, a value of FALSE is returned. A value of FALSE is also returned if the type handle does not correspond to a SET or SEQUENCE type (it corresponds to a CHOICE type instead).
Determines whether a component of a SET or SEQUENCE type has been set to an initialization value. If the component itself is a SET or SEQUENCE, then all of its components must be set to initialization values before it is considered to be initialized.
ossComponentIsInitializationValue() returns an ossBoolean type. If the component was initialized with a value, TRUE is returned; otherwise, a value of FALSE is returned.
Informs whether a component of a SET or SEQUENCE type is marked as OPTIONAL or has a DEFAULT value.
ossComponentIsOptional() returns an ossBoolean type. If the specified element is a component of a SEQUENCE or SET and is marked as OPTIONAL or has a DEFAULT value, a value of TRUE is returned; otherwise, a value of FALSE is returned.
To find out whether a component is OPTIONAL using this function, you can first call ossComponentIsOptional() and then call ossComponentIsDefault() if the first call returns TRUE. A return value of TRUE from ossComponentIsOptional() can either correspond to an OPTIONAL or DEFAULT value.
Checks whether a value for an optional, default, or extension-addition component in a SET or SEQUENCE is present. This function can also be used to determine whether a CHOICE alternative is present.
ossComponentValueIsPresent() returns an ossBoolean type. If the specified SET or SEQUENCE type has a component with a valid non-NULL value at the specified index, a value of TRUE is returned; otherwise, a value of FALSE is returned. A value of FALSE is also returned if the type handle does not correspond to a SET or SEQUENCE, or CHOICE type or if parentValue is NULL or otherwise invalid.
Informs whether a component of a SET, SEQUENCE, or CHOICE type was removed using the ASN1.Remove directive in the input ASN.1 syntax.
ossComponentWasRemoved() returns an ossBoolean type. If the specified element is a component of a SEQUENCE, SET, or CHOICE and is marked for removal with the ASN1.Remove directive, a value of TRUE is returned; otherwise, a value of FALSE is returned.
Deletes the value of a component within an ASN.1 structured type (for example, SET, SEQUENCE, SET OF, SEQUENCE OF, and CHOICE).
ossDeleteComponent() returns an enumerator of type IAAPI_ERRTYPE. If the parent type has a component at the specified index and no other error occurs, the IAAPI_NOERROR enumerator is returned; otherwise, an IAAPI error code indicating the type of error encountered is returned.
The memory allocated for the component for deletion is freed by the ossDeleteComponent() function. Additionally, any nested components are also deleted.
Retrieves a value of a component of a structured type in decoded internal format given its absolute reference.
parentValue can be set to NULL, so compType will hold the type handle of the desired component upon return. You can then pass the type handle to the other IAAPI functions to access and analyze the component.
ossGetComponentByAbsRef() returns an enumerator of type IAAPI_ERRTYPE. If the passed type handle corresponds to a SET, SEQUENCE, SET OF, SEQUENCE OF, or CHOICE type which contains a component with the passed absolute reference and no other error occurs, the IAAPI_NOERROR enumerator is returned; otherwise, an IAAPI error code which indicates the type of error encountered is returned.
The ossGetComponentByAbsRef() function allows builders of protocol analyzers to set watch points in received messages at runtime. A particular field within an ASN.1 message definition can be singled out by the user at runtime for observation and its value can be analyzed. As each message is decoded, the protocol analyzer can call ossGetComponentByAbsRef() to get the address of the field that was selected by the user. Then, it can compare the value of this field against the value that is being watched for. When the values match in a received message, the protocol analyzer can halt on that particular message and display it for detailed analysis. As for those messages in which there is no match, the protocol analyzer can simply transmit them to the output port without holding them for analysis.
The example below uses the Baseball Card Abstract syntax, which is found in samples/bcas.asn (with an additional values component):
BCAS DEFINITIONS AUTOMATIC TAGS ::= BEGIN
BBCard ::= SEQUENCE {
name IA5String (SIZE (1..60)),
team IA5String (SIZE (1..60)) OPTIONAL,
age INTEGER (1..100) OPTIONAL,
position IA5String (SIZE (1..60)) OPTIONAL,
handedness ENUMERATED
{left-handed(0), right-handed(1), ambidextrous(2)},
values SEQUENCE OF INTEGER
}
myCard BBCard ::= {
name "Jimmy Blake",
team "Mudville Nine",
age 30,
position "left field",
handedness ambidextrous,
values {1, 2}
}
The syntax has the following header file representation:
typedef struct BBCard {
char name[61];
char team[61];
unsigned short age;
char position[61];
enum {
left_handed = 0,
right_handed = 1,
ambidextrous = 2
} handedness;
double batting_average;
struct _seqof1 {
struct _seqof1 *next;
int value;
} *values;
} BBCard;
extern BBCard myCard;
....
struct ossGlobal w, *world = &w; /* OSS environment variable */
BBCard *myCardPtr = NULL; /* address of decoded data */
int retcode; /* return code */
TypeHndl compType = NULL;
void *compValue = NULL;
char *name = NULL, *team = NULL, *batting_average = NULL, *seqOfCompValue = NULL;
....
if (!ossGetComponentByAbsRef(world, "BBCard.name", myCardPtr, &compTypeHndl, &compValue)) {
name = ossGetValueNotationOfType(world, compType, compValue);
}
if (!ossGetComponentByAbsRef(world, "BBCard.team", myCardPtr, &compType, &compValue)) {
team = ossGetValueNotationOfType(world, compType, compValue);
}
if (!ossGetComponentByAbsRef(world, "BBCard.batting-average", myCardPtr, &compType, &compValue)) {
batting_average = ossGetValueNotationOfType(world, compType, compValue);
}
if (!ossGetComponentByAbsRef(world, "BBCard.values.1", myCardPtr, &compType4, &compValue)) {
seqOfCompValue = ossGetValueNotationOfType(world, compType, compValue);
}
if (name && team && batting_average && seqOfCompValue) {
ossPrint(world, "%s of the %s has a batting average of %s with value %s\n",
name, team, batting_average, seqOfCompValue);
ossFreeDisplayString(world, name);
ossFreeDisplayString(world, team);
ossFreeDisplayString(world, batting_average);
ossFreeDisplayString(world, seqOfCompValue);
}
Retrieves a value of a component of a structured type in decoded internal format. The original structure is not modified.
ossGetDecodedValueOfComponent() returns an enumerator of type IAAPI_ERRTYPE. If the passed type handle corresponds to a SET, SEQUENCE, SET OF, SEQUENCE OF, or CHOICE type which contains a component with the passed index and no other error occurs, the IAAPI_NOERROR enumerator is returned; otherwise, an IAAPI error code which indicates the type of error encountered is returned.
Retrieves the ix index of a component within a specified ASN.1 type given its ASN.1 identifier. The returned index can then be passed to other IAAPI functions for identification purposes.
ossItemIndexByName() returns an integer. If the passed type handle corresponds to an ASN.1 type that contains a component named name, the index of this component is returned; otherwise, a value of UINT_MAX is returned. The index starts at zero.
The indices used by the IAAPI functions begin at zero. Thus, the first element will have an index of 0; the second will have an index of 1; the third will have an index of 2 and so on.
Returns either the number of components in a particular SET, SEQUENCE, or CHOICE type or the number of named items in an ENUMERATED, BIT STRING, or INTEGER type that occur before the first extension marker in the type's ASN.1 definition. If the type has no extensibility marker, this function will return the same value as ossNumberOfNamedItems().
ossNumberOfRootItems() returns an integer. If the passed type handle corresponds to a BIT STRING with a named bit list, CHOICE, ENUMERATED, INTEGER with a named number list, SEQUENCE, or SET type, the count of the named items in the type before the first extensibility marker is returned; otherwise, a value of zero is returned.
Sets a component of a SET, SEQUENCE, SET OF, SEQUENCE OF, or CHOICE type to a specified decoded value given the component's absolute reference.
After a successful return, the value contained in compValue is inserted into the parentValue structure. If compValue was dynamically allocated, it will be automatically freed when the structure it was inserted into is freed (for example, via a call to ossFreePDU() or ossFreeDecodedValue()).
ossPutComponentByAbsRef() returns an enumerator of type IAAPI_ERRTYPE. If the parent type is a SET, SEQUENCE, SET OF, SEQUENCE OF, or CHOICE type which contains a component corresponding to the passed absolute reference and no other error occurs, the IAAPI_NOERROR enumerator is returned; otherwise, an IAAPI error code is returned.
Updates a value of a component in a structured type (SET, SEQUENCE, SET OF, SEQUENCE OF, or CHOICE). The original structure can itself be modified (by passing its address as the fourth argument) or a blank copy of the original structure can be created (by passing a NULL pointer as the fourth argument). Note that this function updates only one field at a time. Thus, applications which need to update multiple fields should call this function multiple times with different component values and indices.
ossPutStructTypeValue() returns an enumerator of type IAAPI_ERRTYPE. If the passed type handle corresponds to a SET, SEQUENCE, SET OF, SEQUENCE OF, or CHOICE type which contains a component with the passed index and no other error occurs, the IAAPI_NOERROR enumerator is returned; otherwise, an IAAPI error code indicating the type of error encountered is returned.
If you insert a dynamically-allocated component value to ossPutStructTypeValue(), you can no longer free it separately, as it has become part of the larger structure to which it was input. To free this value, call ossFreeDecodedValue() or ossFreePDU() on the containing structure that you inserted it into. For example if you obtained a component value via ossPutSimpleTypeValue() and then inserted it into a structure via ossPutStructTypeValue(), it is not valid to try to later free that component value. The value will be freed when you call ossFreeDecodedValue() or ossFreePDU() for the structure you inserted into.
/******************************************************************************
* putAndTestDeleteComponent
*
* Function: Creates a decoded value of a SET, SEQUENCE, CHOICE, SET OF,
* or SEQUENCE OF component, identified by "ix", puts it into
* the parent structure. Then, it calls ossDeleteComponent():
* deletes just created component, then again creates it.
*
* Parameters:
* world Global structure passed to all OSS functions.
* parentType Type handle of type to create.
* compAddress Decoded value of component in the control table.
* ix Component index of the parent type to create.
* rc Error return code.
* absRef Absolute reference of the component
* buflen Length of the absRef buffer
* pduDecodedValue Decoded value of the parent PDU.
*
* Returns: IAAPI_NOERROR if the value was created and deleted
* successfully.
*****************************************************************************/
static IAAPI_ERRTYPE putAndTestDeleteComponent ( OssGlobal *world,
TypeHndl parentType,
void **structToUpdate,
void *compAddress,
int ix,
int *rc,
char **absRef,
int *buflen,
void *pduDecodedValue )
{
IAAPI_ERRTYPE errVal = IAAPI_NOERROR;
void *compValue;
int k;
compValue = createValueOfNamedType(world, parentType, ix,
compAddress, rc, absRef, buflen, pduDecodedValue);
if (compValue && !*rc)
errVal = ossPutStructTypeValue(world, parentType,
compValue, ix, structToUpdate);
if (errVal || *rc) {
if (errVal)
*rc = errVal;
else
errVal = *rc;
if (*structToUpdate)
ossFreeDecodedValue(world, parentType, *structToUpdate);
*structToUpdate = NULL;
if (compValue) {
TypeHndl childType = ossTypeHandleOfComponent(world,
parentType, ix);
ossFreeDecodedValue(world, childType, compValue);
}
#ifndef SKIP_DELETE_COMPONENTS
break;
#endif /* SKIP_DELETE_COMPONENTS */
}
/*
* Testing ossDeleteComponent() function for the current component.
*/
#ifndef SKIP_DELETE_COMPONENTS
if (!k && (errVal = ossDeleteComponent(world, parentType, ix,
structToUpdate)))
k++;
}
#endif /* SKIP_DELETE_COMPONENTS */
return errVal;
}
Note that if a NULL pointer is passed to the ossPutStructTypeValue() function as a fourth argument, a blank copy of the original structure is first created. If ossPutStructTypeValue() is not called for a second time for decValue1, the second field (assigned the value of tempFloat) of the MySeq structure would be set to zero.
Inserts a decoded value of a component of a SET, SEQUENCE, SET OF, SEQUENCE OF, or CHOICE type into an outermost parent structure given the component's absolute reference. Additionally, this function allocates decoded values for all first-level components of the outer parent type if they were not yet allocated (if the last parameter of the function points to NULL) before inserting the component's decoded value. Also, this function allows you to insert component values into non-PDU type references whose type handles are passed in the second parameter to the function.
After a successful return, the value contained in compValue is inserted into the parentValue structure. If compValue was dynamically allocated, it will be automatically freed when the structure it was inserted into is freed (for example, via a call to ossFreePDU() or ossFreeDecodedValue()).
ossPutStructTypeValueByComponentAbsRef() returns an enumerator of type IAAPI_ERRTYPE. If the parent type is a SET, SEQUENCE, SET OF, SEQUENCE OF, CHOICE type or a CLASS which contains a component corresponding to the passed absolute reference and no other error occurs, the IAAPI_NOERROR enumerator is returned; otherwise, an IAAPI error code is returned.
Retrieves the type handle associated with a component of a CHARACTER STRING, CHOICE, EMBEDDED PDV, EXTERNAL, SEQUENCE, SEQUENCE OF, SET, or SET OF type. You can pass the returned handle to the other IAAPI functions that require such a handle for type identification.
ossTypeHandleOfComponent() returns a TypeHndl type. If the passed type handle corresponds to one of the allowed parent types (listed above) and this type contains a component of index ix, the type handle of the desired component is returned; otherwise, a value of NULL is returned.
If the ASN.1 compiler command-line option -per was specified, the order in which components are defined in a SET or CHOICE type and the order in which the indices are associated with them is not necessarily the same. You can use the ossItemIndexByName() function if you know the identifier of the component, to determine the index value ix associated with it.
Retrieves contents information for an open type. Specifically, the PDU number corresponding to the open type, the length field, the encoded field, and the decoded field is retrieved via the last three function arguments.
ossGetOpenTypeValue() returns an enumerator of type IAAPI_ERRTYPE. If the passed type handle and the openValue field correspond to an open type and no other error occurs, the IAAPI_NOERROR enumerator is returned; otherwise, an IAAPI error code which indicates the type of error that occurred is returned.
OssBuf openEncodedData;
Msg *decodedDataPtr = NULL; /* address of decoded data */
int myPduNum = 0, checkPduNum=0;
IAAPI_ERRTYPE irc; /* return code */
void *decValue1, *openTypePtr;
TypeHndl th1, th2;
....
th1 = ossTypeHandleOfPDU(world, myPduNum); /* get TH of parent structure */
th2 = ossTypeHandleOfComponent(world, th1, 2); /* OpenType is 3rd component*/
openTypePtr = &decodedDataPtr->tcipType; /* point to OpenType structure */
irc = ossGetOpenTypeValue(world, th2, openTypePtr, &checkPduNum,
&decValue1, &openEncodedData);
ossPrint(world, "\nOpenTypePduNum = %d\n", checkPduNum);
Sets the encoded and length fields of an open type, the value and length fields of an ANY type, or the "encoded" component within the containing structure generated for BIT STRING and OCTET STRING types with ContentsConstraint, to specified values. In the case of the open type, none of the other fields (for example, decoded and pduNum) are set.
Note that the length of the input encoded value for BIT STRING types with ContentsConstraint will be the number of significant bits (not bytes) that the encoded value of a contained type occupies.
ossPutEncodedValue() returns an enumerator of type IAAPI_ERRTYPE. If the passed type handle corresponds to an open type or ANY type, decodedValue is not NULL, and no other error occurs, the IAAPI_NOERROR enumerator is returned; otherwise, an IAAPI error code is returned.
Sets the pduNum and decoded fields of an open type to specified values. None of the other fields in the open type (for example, encoded and length) are set.
ossPutOpenTypeDecodedValue() returns an enumerator of type IAAPI_ERRTYPE. If the passed type handle and PDU number correspond to an open type and no other error occurs, the IAAPI_NOERROR enumerator is returned; otherwise, an IAAPI error code is returned.
Converts a display format value of an entire PDU (simple or structured) into the decoded internal format given the PDU number. This function can also read the display format value from a file. The input value notation string can start with "valueName PduTyperefName ::=", which is not considered a part of the value notation.
ossDecodeValueNotationOfPDU() returns an enumerator of type IAAPI_ERRTYPE. If the display value is compatible with the specified PDU and no other error occurs, the IAAPI_NOERROR enumerator is returned; otherwise, an IAAPI error code which indicates the type of error encountered is returned.
displayValue->value can be marked as an OSS_FILE object (for example, using the ossMarkObj() function). If it is marked, displayValue- >length is interpreted as the offset in the input text file where the display value first starts.
Starting with version 6.0.1, if the input buffer contains multiple concatenated PDUs, the ossDecodeValueNotationOfPDU() function updates the OssBuf.length field to contain the number of bytes remaining in the input buffer after the decode.
Converts a display format value of an entire ASN.1 type (simple or structured) into the decoded internal format given its type handle. This function can also read the display format value from a file.
ossDecodeValueNotationOfType() returns an enumerator of type IAAPI_ERRTYPE. If the display value is compatible with the specified PDU and no other error occurs, the IAAPI_NOERROR enumerator is returned; otherwise, an IAAPI error code which indicates the error that occurred is returned.
displayValue->value can be marked as an OSS_FILE object (for example, using the ossIaapiMarkObject() IAAPI function). If it is marked, displayValue- >length is interpreted as the offset in the input text file where the display value first starts.
Starting with version 6.0.1, if the input buffer contains multiple concatenated PDUs, the ossDecodeValueNotationOfType() function updates the OssBuf.length field to contain the number of bytes remaining in the input buffer after the decode.
Although, the OssBuf structure passed to ossEncode() | ossDecode() structure has the same definition as that passed to ossDecodeValueNotationOfType(), the contents of the two vary greatly. The value field of the OssBuf structure passed to ossDecodeValueNotationOfType() is supposed to contain a character string and not binary data (as is the case for ossEncode() | ossDecode()).
Converts a decoded internal format value for an entire PDU (simple or structured) into the display format which can be easily viewed or parsed. The PDU number of the data type to convert must be specified.
ossGetValueNotationOfPDU() returns an address of a character string that represents a valid ASN.1 value notation of the specified PDU starting with "value PduTyperefName ::=". If you prefer to get a pure value notation string without any addition, consider using ossGetValueNotationOfType() instead. If the sent decoded value is compatible with the ASN.1 type corresponding to the passed PDU number and no other error occurs, the address of a newly allocated character string containing the display format value of the PDU is returned; otherwise, a value of NULL is returned.
The character string which is returned can be freed using the ossFreeDisplayString() function.
Converts a decoded internal format value for an entire ASN.1 type (simple or structured) into the display format which can be easily viewed or parsed. The type handle of the data type to convert must be specified.
The character string returned by ossGetValueOfSimpleType() is simply the ASN.1 value reference notation for that value. For example, an OBJECT IDENTIFIER value can have the following string returned for it:
value ::= { 1 2 3 4 5}
ossGetValueNotationOfType() returns an address of a character string. If the sent decoded value is compatible with the ASN.1 type corresponding to the passed type handle and no other error occurs, the address of a newly allocated character string containing the display value of the ASN.1 type is returned; otherwise, a value of NULL is returned.
The character string which is returned can be freed using the ossFreeDisplayString() function.
Converts a decoded internal format value for a simple (non-structured) ASN.1 type into the display format which can be easily viewed or parsed. The type handle of the value to convert must be specified.
ossGetValueOfSimpleType() returns an address of a character string. If the sent decoded value is compatible with the ASN.1 type corresponding to the passed type handle and no other error occurs, an address of a newly allocated character string containing the display value of the simple type is returned; otherwise, a value of NULL is returned.
The character string which is returned can be freed using the ossFreeDisplayString() function.
Converts a display format value of an entire PDU (simple or structured) into the decoded internal format which can be understood by the encoder/decoder and other IAAPI functions. The PDU number of the type to convert must be specified. Starting with the 8.6 version, the function accepts values that are returned by another IAAPI function, ossGetValueNotationOfPDU(), that begin with the "valueName PduTyperefName ::=" string.
ossPutDecodedValueOfPDU() returns an enumerator of type IAAPI_ERRTYPE. If the display value is compatible with the specified PDU and no other error occurs, the IAAPI_NOERROR enumerator is returned; otherwise, an IAAPI error code which indicates the error type is returned.
Note that the error checks are omitted for brevity:
MySeq *myDataPtr = NULL; /* address of decoded data */ int retcode, irc; /* return code */ void *decValue1=NULL; /* will reference decoded internal format value */ char *userdisp; /* will reference display format value */ .... userdisp = ossGetValueNotationOfType(world, ossTypeHandleOfPDU(world, pdu_num), myDataPtr); .... irc = ossPutDecodedValueOfPDU(world, pdu_num, userdisp, &decValue1); ....
Converts a display format value for a simple (non-structured) ASN.1 type into the decoded internal format which can be understood by many of the OSS API and IAAPI functions. The type handle of the value to convert must be specified.
ossPutSimpleTypeValue() returns an enumerator of type IAAPI_ERRTYPE. If the display value is compatible with the specified ASN.1 type, the specified ASN.1 type is simple, and no other error occurs, the IAAPI_NOERROR enumerator is returned; otherwise, an IAAPI error code which indicates the error type is returned.
Note that the error checks are omitted for brevity:
MyInt intData = 124; MyInt *myIntPtr = NULL; /* address of decoded data */ int pdu_num = 0; struct ossGlobal w, *world = &w; void *decValue1=NULL; TypeHndl th; char *userdisp; .... ossPrintPDU(world, pdu_num, myIntPtr); th = ossTypeHandleOfPDU(world, pdu_num); userdisp = ossGetValueOfSimpleType(world, th, myIntPtr); ossPrint(world, "Display string: %s\n",userdisp); userdisp[2] = '5'; /* change the display format value from "124" to "125" */ ossPutSimpleTypeValue(world, th, userdisp, &decValue1); ossPrintPDU(world, pdu_num, decValue1); ....
Output for example:
value MyInt ::= 124 Display string: 124 value MyInt ::= 125
Updates a decoded value of a simple (non-structured) ASN.1 type given its type handle and address. The memory for the original type is freed so that its pointer can be reassigned to the new modified value which is passed back.
ossUpdateValueOfSimpleType() returns a memory address. If the passed type handle and display value are compatible with each other and no other error occurs, the address of the newly created and modified simple type is returned; otherwise, a value of NULL is returned.
Note that the return error checks are omitted for brevity:
MyInt *myIntPtr = NULL; /* address of decoded data */
void *decValue1=NULL;
TypeHndl th;
....
ossPrintPDU(world, pdu_num, myIntPtr);
th = ossTypeHandleOfPDU(world, pdu_num);
userdisp = ossGetValueOfSimpleType(world, th, myIntPtr);
userdisp[2] = '0';
myIntPtr = (MyInt*)ossUpdateValueOfSimpleType(world, th, userdisp,
myIntPtr);
ossPrintPDU(world, pdu_num, myIntPtr);
....
ossFreeDecodedValue(world, th, decValue1);
ossFreeDisplayString(world, userdisp);
....
Output for example:
value MyInt ::= 124 value MyInt ::= 120
The ossUpdateValueOfSimpleType() function is usually used on values created via the ossPutSimpleTypeValue() function or retrieved via the ossGetValueOfSimpleType() function.
The functions in this section will only work properly if you compiled the input ASN.1 syntax with the -valueRefs command-line option.
Retrieves the actual value of a value reference in the decoded internal format given its index.
ossGetDecodedValueOfValueReference() returns a memory address. If the -valueRefs ASN.1 compiler command-line option was specified and valRefIndex is within range, the decoded value of the value reference with the passed index is returned; otherwise, a value of NULL is returned.
The memory for the return value is statically allocated, so you don't need to free it.
The error checks are omitted for brevity:
const void *decValue;
TypeHndl th1;
unsigned short int numValueRefs, i;
....
numValueRefs = ossGetNumberOfValueReferences(world);
ossPrint(world, "\nNumber of ValueRefs = %d\n", numValueRefs);
for(i=0; i<numValueRefs; i++)
{
ossPrint(world, "\nName of ValueReference[%i] = %s", i,
ossGetNameOfValueReference(world, i));
decValue = (void*)ossGetDecodedValueOfValueReference(world, i);
th1 = ossGetTypeHandleOfValueReference(world, i);
ossPrint(world, " : Decoded_Value = ");
ossPrintDecodedValueOfType(world, th1, (void *)decValue);
}
ossPrint(world, "\n");
Sample output for example:
Number of ValueRefs = 5 Name of ValueReference[0] = aSmallInt : Decoded_Value = 5 Name of ValueReference[1] = bSmallInt : Decoded_Value = 7 Name of ValueReference[2] = cSmallInt : Decoded_Value = 9 Name of ValueReference[3] = dSmallInt : Decoded_Value = 11 Name of ValueReference[4] = eSmallInt : Decoded_Value = 13
Input ASN.1 specification for above sample:
ModuleName DEFINITIONS ::= BEGIN SmallInteger ::= INTEGER anInt INTEGER ::= 500 aSmallInt SmallInteger ::= 5 bSmallInt SmallInteger ::= 7 cSmallInt SmallInteger ::= 9 dSmallInt SmallInteger ::= 11 eSmallInt SmallInteger ::= 13 bInt INTEGER ::= 900 cStr IA5String ::= "This is a cstring" END
Notice how anInt, bInt, and cStr were not stored in the IAAPI value reference table. This is because only value references based upon used-defined types are stored in the generated table. Also, note how the order of the value references in the generated table corresponds to their order of declaration in the input ASN.1 specification.
Retrieves the character string name of a particular value reference in the ASN.1 input given its index.
ossGetNameOfValueReference() returns an address of a character string. If the -valueRefs command-line option was specified and valRefIndex is within range, the ASN.1 identifier of the value references with the passed index is returned; otherwise, a value of NULL is returned.
The memory for the return value is statically allocated, so you don't need to free it.
Returns a positive integer indicating the number of value references declared in the input ASN.1 specification. Note that only value references of user-defined types are counted.
world is a pointer to the global OSS environment variable.
ossGetNumberOfValueReferences() returns an unsigned short integer value. If the passed OssGlobal structure is valid and the -valueRefs command-line option was specified, the number of value references found in the ASN.1 input is returned; otherwise, a value of zero is returned.
Retrieves the type handle of a value reference given its index.
ossGetTypeHandleOfValueReference() returns a TypeHndl type. If the passed OssGlobal structure is valid, the -valueRefs command-line option was specified, and valRefIndex is within range, the type handle of the value references with the passed index is returned; otherwise, a value of NULL is returned.
Calls the ossEncode() function for a particular decoded value given its type handle. This function is useful when you want to obtain the encoding for only a small part of a PDU.
After a successful call, the value field of the OssBuf structure will reference the actual encoding while the length field will contain the length in bytes of the encoding. The memory allocated for the value field can be freed by a call to ossFreeBuf().
ossValueEncode() returns an enumerator of type IAAPI_ERRTYPE. If the decoded value is compatible with the specified type and no other error occurs, the IAAPI_NOERROR enumerator is returned; otherwise, an IAAPI error code which indicates the type of error that occurred is returned.
All IAAPI functions that work with encoded data require a pointer to the "world" OSS global environment variable as the first parameter. If you don't use any other OSS API or OSS IAAPI functions in your application and don't have an ASN.1 specification, you must call ossinit() to initialize the OSS environment. In this case, create a simple .asn file that contains any type assignment, for example:
M DEFINITIONS ::= BEGIN
B ::= BOOLEAN
END
ASN.1 compile it, and use the generated control table as a parameter to the ossinit() function.
Is used to find the ASN.1 tag class of a specified tag in a BER/DER encoding.
ossEncodingASN1Class() returns an enumerator of type ASN1TagClass. If a tag with the ix index exists, an enumerator of type ASN1TagClass is returned; otherwise, if an error occurs, the NULLENCODING enumerator is returned.
Note that ASN1TagClass has the following definition in ossiaapi.h:
typedef enum ASN1TagClass {
UNIVERSAL, APPLICATION, CONTEXT_SPECIFIC, PRIVATE, NULLENCODING
} ASN1TagClass;
Is used to find the ASN.1 tag number (for example, 3 in [UNIVERSAL 3]) of a specified tag in a BER/DER encoding.
ossEncodingASN1Tag() returns a long integer. If a tag with index ixth is present in the sent encoding, its ASN.1 tag number is returned; otherwise if an error occurs, a value of -1 is returned.
Note that the LONG_LONG type is defined as either a long integer or a long long integer in asn1hdr.h, depending on the platform in use.
Retrieves the type name (for example, BOOLEAN, INTEGER, etc.) that an encoding corresponds to. If the type name cannot be determined, then the complete tag is returned (for example, [Private 25]).
ossEncodingASN1Type() returns a character string pointer. If the ASN.1 type of the sent encoding can be determined, a character string containing the name of the ASN.1 type (for example, "ENUMERATED") is returned. If the type cannot be determined, then a character string containing the tag is returned (for example, [APPLICATION 15] or [25] for a CONTEXT-SPECIFIC tag) is returned; otherwise if an error occurs, a value of NULL is returned.
Retrieves the contents of an input BER/DER encoding in the form of a display string which is either the result of decoding the input BER/DER encoding (if the type of the input encoding is one that can be decoded without knowing its original ASN.1 definition) or is simply the BER/DER contents octets in display format (if the type of the encoded value cannot be determined).
ossEncodingContents() returns a pointer to a character string. If the type of the input encoding is one that can be decoded without knowing its ASN.1 definition, a character string containing the result of decoding the input BER/DER encoding is returned. If a decoding failure occurs or if the input encoding corresponds to an ENUMERATED, SEQUENCE, SET, SEQUENCE OF, SET OF, or CHOICE type, a hexadecimal string in display format containing the contents octets of the encoding is returned. A value of NULL is returned if memory for the returned value cannot be allocated or another error occurs.
You can free the memory for the character string returned with a call to the ossFreeDisplayString() function.
Sample output:
ossPrintPDU() of MySeq: value MySeq ::=
{
a 145,
b { 2.350, 10, 0 }
}
ossPrintHex() of MySeq: 300F0202 00910909 80CD12CC CCCCCCCC CD
ossEncodingContents() of MySeq: 02020091090980CD12CCCCCCCCCCCD
ossPrintPDU() of MyInt: value MyInt ::= 124
ossPrintHex() of MyInt: 02017C
ossEncodingContents() of MyInt: 124 (0x7c)
Retrieves the number of octets occupied by the type (identifier) and length fields in a BER/DER encoding which is in the type-length-value format. The type (identifier) is the first part of ever BER/DER encoding.
ossEncodingHeaderLength() returns an unsigned long integer. If the sent encoding has type (identifier) and length fields, the number of octets occupied by the type and length fields is returned; otherwise if an error occurs, the BADLENGTH enumerator is returned (which specifies that the encoding ended before the type and length fields were encountered).
If the number of octets occupied by the type and length fields is greater than the specified remaining length in the encoding's buffer, an error message is issued and the retrieved incorrect number of octets is returned.
Retrieves the number of octets occupied by the type (identifier) field in a BER/DER encoding which is in the type-length-value format.
ossEncodingIdentifierLength() returns an integer. If the sent encoding has a type (identifier) field, the number of octets occupied by the type field is returned; otherwise if an error occurs, the BADLENGTH enumerator is returned (which specifies that the encoding ended before the type and length fields were encountered).
Finds out whether a BER/DER encoding is constructed (for example, corresponds to a structured ASN.1 type (for example, SEQUENCE))) or primitive (for example, corresponds to an unstructured primitive ASN.1 type (for example, INTEGER)). A constructed encoding contains a series of nested encodings.
ossEncodingIsConstructed() returns an ossBoolean type. If sent encoding is constructed, a value of TRUE of returned; otherwise, a value of FALSE is returned.
Retrieves the value of the length field in a BER/DER encoding which is in the type-length-value format.
ossEncodingLength() returns an unsigned long integer. If the sent encoding is of definite length, the value in the length field (which specifies number of octets in the contents/value part of the encoding) is returned. If the encoding is of indefinite length, the INDEFLENGTH enumerator is returned; otherwise if an error occurs, the BADLENGTH enumerator is returned (which specifies that the encoding ended prematurely in the encoding buffer).
If the encoding's length field contains a value that is greater than the remaining length in the encoding's buffer, an error message is issued and the retrieved incorrect length value is returned.
Finds the beginning address of the first nested encoded value within a constructed BER/DER encoding. In other words, this function returns the address of the byte immediately after the tag and length fields of the input constructed BER/DER encoding.
ossGetNestedBEREncoding() returns a memory address. If currentEncoding corresponds to a constructed (not primitive) encoding and it has a nested value field, the address of the first nested value field is returned; otherwise, a value of NULL is returned.
Finds the beginning address of the next value in a BER encoding on the same level of nesting. In other words, this function returns the address of the byte immediately after the contents fields of the input encoding if another value exists on this level.
ossGetNextBEREncoding() returns a memory address. If another value field exists after the currentLocation on the same level of nesting, the address of this subsequent value field is returned; otherwise, a value of NULL is returned.
Retrieves the number of tags that are found in a BER/DER encoding. The returned number reflects both the number of tags on the current level and also tags nested within constructed types on the current level.
ossNumberOfEncodingTags() returns a long integer. If currentEncoding corresponds to an encoding that has tags, the total number of tags (both on the current level and those nested within) is returned; otherwise, a value of zero is returned.
Converts a character string containing binary digits (in display format) representing a BER/DER encoding into the encoded format understood by ossDecode() and other API functions.
ossConvertBinFmtToEncoding() returns an enumerator of type IAAPI_ERRTYPE. If the contents of the sent character string represent a valid encoding, the IAAPI_NOERROR enumerator is returned; otherwise, an IAAPI error code which indicates the error that occurred is returned.
Converts a BER/DER encoding to a binary character string in display format which you can easily view or parse.
ossConvertEncodingIntoDisplayBinFmt() returns a character string pointer. If no error occurs, the address of a newly created character string containing the bits of the sent encoding in binary display format is returned; otherwise, a value of NULL is returned.
The memory for the returned character string can be freed by a call to ossFreeDisplayString().
Converts a BER/DER encoding to a hexadecimal character string in display format which you can easily view or parse.
ossConvertEncodingIntoDisplayHexFmt() returns a character string pointer. If no error occurs, the address of a newly created character string containing the bytes of the sent encoding in hexadecimal display format is returned; otherwise, a value of NULL is returned.
The memory for the returned character string can be freed by a call to ossFreeDisplayString().
Converts a character string containing hexadecimal characters (in display format) representing a BER/DER encoding into the encoded format understood by ossDecode() and other API functions.
ossConvertHexFmtToEncoding() returns an enumerator of type IAAPI_ERRTYPE. If the contents of the sent character string represent a valid encoding, the IAAPI_NOERROR enumerator is returned; otherwise, an IAAPI error code which indicates the error that occurred is returned.
These are functions that handle data objects read from or written to files or sockets, for example.
Retrieves a type handle that can be used in subsequent references to a type marked with the ASN1.DeferDecoding directive in the ASN.1 input.
ossDeferTypeHandle() returns a TypeHndl type. If type corresponds to an open type generated as a result of an ASN1.DeferDecoding directive application, a DeferDecoding type handle is returned; otherwise, a value of NULL is returned.
Determines the nature of a specified external object (for example, whether it is a file or socket external object).
ossGetObjectType() returns an enumerator of type OssObjType. If the value field in object has been marked as an external object, OSS_FILE or OSS_SOCKET is returned; otherwise, OSS_UNKNOWN_OBJECT is returned.
Retrieves a marked object from a decoded value and returns it via the fourth function argument.
ossGetObjectValue() returns an enumerator of type IAAPI_ERRTYPE. If the decoded value is successfully marked or unmarked, the IAAPI_NOERROR enumerator is returned; otherwise, an IAAPI error code which indicates the error that occurred is returned (additionally in the case of a failure, decodedValue will have a value of NULL upon return).
If the object that is returned is marked with OSS_FILE, the object will be unmarked and objectValue->value will contain the name of the file containing the value, objectValue->length will contain the length in bytes of the value, and objectValue->byteOffset will contain the byte offset from where the value starts in the file.
Marks a particular value as an external object (for example, as a file, socket, or unknown object). The original data type must have had the OSS.NOCOPY | OSS.OBJHANDLE | ASN1.Deferdecoding directive applied to it in the ASN.1 input specification.
ossIaapiMarkObject() returns an enumerator of type IAAPI_ERRTYPE. If the external object is successfully marked, the IAAPI_NOERROR enumerator is returned; otherwise, an IAAPI error code which indicates the error that occurred is returned.
Creates a decoded value from a marked object (for example, an object marked with the OSS.OBJHANDLE | OSS.NOCOPY directive) and returns it via the fifth function argument.
ossPutObjectValue() returns an enumerator of type IAAPI_ERRTYPE. If the external object is successfully decoded, the IAAPI_NOERROR enumerator is returned; otherwise, an IAAPI error code which indicates the error that occurred is returned (additionally in the case of a failure, decodedValue will have a value of NULL upon return).
Note that the OssBufExtended and OssObjType structures are defined as follows in asn1code.h:
typedef struct {
long length;
unsigned char *value;
long byteOffset;
} OssBufExtended;
typedef enum {
OSS_UNKNOWN_OBJECT = 0,
OSS_FILE,
OSS_SOCKET,
OSS_OSAK_BUFFER,
OSS_FSTREAM,
OSS_MEMORY
} OssObjType;
objectValue->value can be marked as an OSS_FILE object (using the API function ossMarkObj()). If it is marked, objectValue->length is interpreted as the offset in the input text file where the value first starts. If objectValue->value is not marked while objectType is OSS_FILE, then objectValue->value should contain the input filename containing the value.
Marks or unmarks a type associated with a given type handle as an external object.
ossSetTypeAsExternalObject() returns an enumerator of type IAAPI_ERRTYPE. If the type is successfully marked or unmarked, the IAAPI_NOERROR enumerator is returned; otherwise, an IAAPI error code which indicates the type of error encountered is returned.
Determines whether or not a particular open type was generated due to an ASN1.DeferDecoding directive application in the ASN.1 input.
world is a pointer to the global OSS environment variable and type is the type handle of an open type.
ossTypeIsDeferDecoding() returns an ossBoolean type. If the sent type handle corresponds to an open type generated as a result of an ASN1.DeferDecoding directive application, a value of TRUE is returned; otherwise, a value of FALSE is returned.
Determines whether or not a particular type can be marked as an external object (i.e. is defined with the OBJHANDLE/NOCOPY directive) and thus can be encoded/decoded to/from a file/socket.
ossTypeIsExternalObject() returns an ossBoolean type. If the sent type handle corresponds to a type which is marked as an external object, a value of TRUE is returned; otherwise, a value of FALSE is returned.
Note that the IAAPI data printing functions do not support user print functions. To use a user-defined print function, use the regular ossPrintPDU() OSS API function.
The ossPrintASN1DescriptionOfPDU() function generates and prints the ASN.1 source (type notation) for a particular PDU in the input ASN.1 specification given its compiler-generated PDU number.
ossPrintASN1DescriptionOfPDU() does not return a value.
Generates and prints the ASN.1 source (type notation) for a particular type in the input ASN.1 specification given its type handle.
ossPrintASN1DescriptionOfType() does not return a value.
Generates and prints the ASN.1 source (value notation) for a particular PDU in the input ASN.1 specification given its PDU number and decoded value.
ossPrintDecodedValueOfPDU() does not return a value.
ossPrintDecodedValueOfPDUByName()
Generates and prints the ASN.1 source (value notation) for a particular PDU in the input ASN.1 specification given its type handle.
ossPrintDecodedValueOfPDUByName() does not return a value.
void *decValue; TypeHndl th1; th1 = ossGetTypeHandleOfValueReference(world, 0); decValue = (void *)ossGetDecodedValueOfValueReference(world, 0); ossPrintDecodedValueOfPDUByName(world, th1, "myVeryOwnSmallInt", decValue);
Sample output:
myVeryOwnSmallInt SmallInteger ::= 5
Note that myVeryOwnSmallInt doesn't need to be defined in the ASN.1 syntax. SmallInteger is the base type of the value reference in this example with index 0.
Generates and prints the ASN.1 source (value notation) for all value references in the input ASN.1 specification. The -valueRefs option must be specified in order for this function to work correctly.
world is a pointer to the global OSS environment variable.
ossPrintDecodedValuesOfPDUs() does not return a value.
ossPrintDecodedValueOfPDUByName()
Prints the value of an ASN.1 type in display format given the type's handle and value in decoded internal format.
ossPrintDecodedValueOfType() does not return a value.
Refer to the example in the ossGetDecodedValueOfValueReference() section.
Prints a BER/DER encoding in the easy-to-read decomposed-TLV format. The BER/DER encoding to be printed must be in regular memory.
ossPrintEncodingInDecomposedTLV() does not return a value.
Prints a BER/DER encoding in the easy-to-read hexadecimal-TLV format. The type, length, and value fields are separated by whitespace and nested encodings are indented. The BER/DER encoding to be printed must be in regular memory.
This function prints four numbers: the tag type, the length, in parentheses (the actual bytes that the long form length field occupies), and the value, for example:
02 820001(1) 09
Where (1) is the number of bytes the contents occupies.
ossPrintEncodingInHexTLV() does not return a value.
Prints a BER/DER encoding in the easy-to-read syntax-TLV format. The BER/DER encoding to be printed must be in regular memory.
ossPrintEncodingInSyntaxTLV() does not return a value.
Prints a BER/DER encoding in an easy-to-read type-length-value format. The BER/DER encoding can be in regular memory or contained in a text or binary file. The printed output can be either in hexadecimal-TLV, decomposed-TLV, or syntax-TLV format.
Starting with version 10.3, the function automatically detects CDR headers in two commonly used CDR file formats:
When one of these CDR formats is detected, bytes in the CDR headers are printed in hexadecimal format before BER-based encoded messages are printed in TLV format. To suppress automatic CDR header detection, specify the TLV_NOCDRHEADERS flag.
| Flag | Description |
|---|---|
TLV_TEXT |
Specifies that that the input encoded data is in hexadecimal text format. By default, input data is considered to be in binary format. |
TLV_SYNTAX |
Instructs this function to print the BER/DER encoding in the syntax-TLV format. By, default, this function prints using the hexadecimal-TLV format. |
TLV_DECOMPOSED |
Instructs this function to print the BER/DER encoding in the decomposed-TLV format. By, default, this function prints the encoding in the hexadecimal-TLV format. |
TLV_NOSHORT |
Instructs this function not to truncate long output lines to avoid line wrapping. By default, such long lines are truncated to fit on a single line. |
TLV_NOADDITION |
Instructs this function not to print additional clarifying values for INTEGER and REAL types when printing in the decomposed-TLV or syntax-TLV formats. Use this option if the output is parsed and the output lines must have the same number of tokens. By default, additional values are printed. |
TLV_NOTITLES |
Instructs this function not to print the titles Type, Length, and Contents when printing a BER/DER encoding in the syntax-TLV format. By default, titles are printed. |
TLV_NOCDRHEADERS |
Instructs this function to skip automatic CDR header detection. |
You can also pass a zero value (0) to the flags argument, which results in the default behavior; that is, the input must be binary and the output will be in hexadecimal-TLV format.
inbuf is the address of an OssBufExtended structure. The value, length, and byteOffset fields are interpreted as follows:
| Input Source | value | length | byteOffset |
|---|---|---|---|
| Regular Memory | Real memory address pointing to encoding buffer | Number of bytes to be read from buffer | Number of bytes to skip at the beginning of the input buffer |
| File | Marked with OSS_FILE (for example, using ossMarkObj()) | Number of bytes to be read from file | Number of bytes to skip at the beginning of the input file |
Note that if you set the length field to zero when reading from a file, the contents of the entire file will simply be printed out.
ossPrintEncodingInTLV() does not return a value.
NOTE: OSS Nokalva also provides a useful function for printing out PER encodings in an easy-to-view format. For more information, contact info@oss.com.
Generates and prints the ASN.1 source (type notation) for all PDUs in the input ASN.1 specification.
world is a pointer to the global OSS environment variable.
ossPrintPDUs() does not return a value.
Example output:
MyInt ::= INTEGER (1..300) YourString ::= IA5String
The above is generated for the following ASN.1 syntax:
ModuleName DEFINITIONS ::= BEGIN
MyInt ::= SmallInteger
YourString ::= IA5String --<UNBOUNDED>--
SmallInteger INTEGER (1..300)
END
Consider the following restrictions:
Determines whether or not the input string contains a numeric representation of time points, time intervals, or recurring time intervals in one of the ISO 8601 formats, in accordance with ITU-T Rec. X.680:2021 | ISO/IEC 8824-1:2021. The function checks the input string on valid general structure and valid characters. It does not check different time components on valid values or on different limitations from ITU-T Rec. X.680:2021, except for one. If the second parameter, type, is not NULL and it represents one of the useful time types DATE, DATE-TIME, DURATION, or TIME-OF-DAY, the function expects that the input time string has one of the formats permitted for the corresponding useful time type. For example, for the DATE-TIME type, the input string must contain both the date and time of day parts. If you need a more thorough check of a time type value on all ASN.1 constraints, convert the string value into a decoded value (for example, with ossDecodeValueNotationOfType()) and then use the ossValueIsValid() function. The ossCheck8601Time() function was introduced in version 8.2 of the IAAPI library when support for ISO 8601 time types was added.
ossCheck8601Time() returns an ossBoolean type. If the input string has one of the valid numeric ISO 8601 formats, in accordance with ITU-T Rec. X.680:2021, a value of TRUE is returned; otherwise, a value of FALSE is returned and the last parameter, errpos, will contain the position of the first invalid character.
Returns a positive integer indicating the length of a particular decoded value. The units that the length is returned in depend on the ASN.1 base type of the sent decoded value.
ossGetValueLength() returns an unsigned long integer value. If the passed type handle and decoded value corresponds to a BIT STRING, OCTET STRING, restricted character string, OBJECT IDENTIFIER, ANY, SET OF, or SEQUENCE OF type and no other error occurs, the length of the decoded value is returned; otherwise, a length of zero is returned.
The following table displays the correlation of the units of the return length with the input ASN.1 type.
| ASN.1 Type | Return length indicates |
|---|---|
| BIT STRING | The number of bits |
| OCTET STRING | The number of octets |
| restricted character string | The number of characters |
| OBJECT IDENTIFIER | The number of identifier nodes (however if the OBJECT IDENTIFIER value is in the ENCODED format, then a length of 0 and an error message stating the value is unsupported is returned instead) |
| ANY | The number of hexadecimal characters representing the decoded ANY value |
| SET OF, SEQUENCE OF | The number of components |
Determines whether or not two data types can have values which can be fully assigned to each other (i.e. whether or not two types are compatible with each other).
ossTypesCompatible() returns an enumerator of type TypesCompatibilityCodes. If the two types are compatible, the compatible enumerator is returned; otherwise, an enumerator corresponding to the first incompatibility encountered is returned.
The following table contains the values that can be returned:
| Return value | Global Enumerator | Description |
|---|---|---|
0 |
compatible |
The two types are compatible. |
1 |
differentTypes |
The two types are not compatible. |
2 |
defaultsDifferent |
The two types have different DEFAULT values. |
3 |
onlyOneHasDefault |
Only one of the two types has a DEFAULT value. |
4 |
oneHasPointerOtherDoesnt |
Only one of the two types has an OSS.POINTER directive applied to it. |
5 |
numberOfComponentsDifferent |
The two structured types have different number of components each. |
6 |
oneIsOptionalOtherIsnt |
Only one of the two types is marked as OPTIONAL. |
7 |
oneIsExtensibleOtherIsnt |
Only one of the two types is extensible. |
8 |
differentNamedItems |
The two structured types have different identifiers for their components. |
9 |
differentKinds |
The two types have different representations in the target language (for example, in C/C++). |
10 |
componentsHaveDifferentKinds |
The two structured types have different target language representations for their components. |
11 |
differentSubIdNumber |
The two types have different numbers of subidentifiers in an OBJECT IDENTIFIER with the OBJECTID directive applied. |
12 |
differentSubIdTypes |
The two types have different types of sub-identifiers in an OBJECT IDENTIFIER with the OBJECTID directive applied. |
13 |
differentSize |
The two types have different representation sizes (or bounds) for INTEGER or REAL. |
14 |
type1IsPointerOfTypeRef2 |
The two types are derived from the same type reference, but only the first one has the OSS.POINTER directive applied to it. |
15 |
type2IsPointerOfTypeRef1 |
The two types are derived from the same type reference, but only the second one has the OSS.POINTER directive applied to it. |
16 |
differentSizeOfLengthField |
The length fields for the two types have different target language representations. |
17 |
differentRulesInEncodedBy |
Different encoding rules were specified in the ENCODED BY clause of types with a contents constraint. |
18 |
differentContainedTypes |
Different contained types were specified in the CONTAINING clause of types with a contents constraint. |
19 |
onlyOneWasRemoved |
Only one of two types includes components marked for removal using the ASN1.Remove directive. |
Determines whether or not a decoded value is compatible with a certain type and whether or not it satisfies all applied constraints.
ossValueIsValid() returns an ossBoolean type. If the sent value is valid for the specified type, a value of TRUE is returned; otherwise, a value of FALSE is returned.
If you are constructing the type to check for validity (for example, via the ossPutStructTypeValue() function), make sure that you have completely built the type before calling the ossValueIsValid() function. For example, it is not valid to only set one component of a multiple-component structure and then send it to the ossValueIsValid() function.
The function internally uses the SOED constraint checking functions so if your application is linked with the IAAPI library from a LEAN product installation (not containing the constraint checker) then the application should be compiled with -DOSS_SOED_AND_LED_USED and additionally linked with the SOED library to ensure that the ossValueIsValid() function checks the value against constraints. The function always considers the constraints satisfied if the SOED constraint checker is not available.
Compares two decoded values of the same simple or structured ASN.1 type.
ossCmpTypeValue() returns an enumerator of type IAAPI_ERRTYPE. If the passed type handle is appropriate for the input values, both input values are not NULL and are the same, and no other error occurs, then the IAAPI_NOERROR enumerator is returned; otherwise, an IAAPI error code which indicates the type of error that occurred is returned.
Copies a decoded value (simple or structured) into a new identical data structure.
ossCopyTypeValue() returns an enumerator of type IAAPI_ERRTYPE. If the passed type handle is appropriate for the input value and no other error occurs, the IAAPI_NOERROR enumerator is returned; otherwise, an IAAPI error code which indicates the type of error that occurred is returned.
Creates an instance of the input PDU in the internal format which can be understood by the encoder/decoder and by other IAAPI functions.
ossCreateUnencodedValueOfPDU() returns an enumerator of type IAAPI_ERRTYPE. If the output unencoded value was successfully created (note that it can still violate some complex constraints applied to some ASN.1 types nested within the input PDU) and no other error occurs, the IAAPI_NOERROR enumerator is returned; otherwise, an IAAPI error code is returned which indicates the type of error that occurred.
To create a valid value of each nested type, the function uses the following ASN.1 type information. Special IAAPI flags can be used to control the way in which these values are created. The following table shows the initialization values used for different ASN.1 types and the effect of the IAAPI flags. Note that currently there is no support for some complex constraints.
Starting with version 10.0, this function can use more complex constraints in creating values that can be encoded without constraint violation errors. These constraints are SingleValue, TypeConstraint (for open types), PermittedAlphabet (for character string types), and InnerTypeConstraint (for SET, SEQUENCE, CHOICE, SET OF, and SEQUENCE OF types). The IAAPI_NOCONSTRAIN flag disables this behavior. Note that such operators as ALL EXCEPT, EXCEPT, and INTERSECTION are not supported.
| ASN.1 Type and IAAPI flags | Unencoded Value |
|---|---|
| All types with a SingleValue constraint and no IAAPI_NOCONSTRAIN flag | The value is specified in the SingleValue constraint. |
| ANY, open types without TypeConstraint | The value is initialized with zeroes. |
| BIT STRING constrained and no IAAPI_NOCONSTRAIN flag | The lower bound of a size-constrained BIT STRING type is used to determine the number of zero bits (or number of bits from the value of a SingleValue constraint, if present) included in the initialization value. For example, for the type BIT STRING (SIZE(4)) ('01011111'B) the '0101'B value is created. |
| BIT STRING with named bits and no IAAPI_NONAMED_ITEMS flag | The value consisting of bits whose number is the same as the lower bound, if it is present and the flag IAAPI_NOCONSTRAIN is not set, or the number is not more than the upper bound of the size constraint (if it is present and the IAAPI_NOCONSTRAIN flag is not set) and such as it includes all named bits. Bits whose indices correspond to the values of the named bits are set to "1", other bits are set to "0". For example, for the type BIT STRING {bit1(1), bit3(3), bit5(5)} (SIZE(4..10)) the '0101'B value is created. |
| BIT STRING unconstrained and without named bits | The value of '0'B. |
| BOOLEAN | The value of FALSE. |
| CharacterString types constrained and no IAAPI_NOCONSTRAIN flag | The lower bound of the size constraint is used to determine the number of characters included in the created value. The character itself is determined as follows: If no PermittedAlphabet constraint is present or the "0" character is included in the permitted alphabet, "0" is used as the initialization character. If a PermittedAlphabet constraint is present, the first character from the alphabet is used. For example, for the type PrintableString (SIZE(3)) (FROM "A".."Z")) the value "AAA" is created. |
| CharacterString types unconstrained | The value consisting of one zero character "0". |
| CHOICE without InnerType constraint | The first alternative with a non-recursive type definition is instantiated. |
| CHOICE with InnerType constraint | The first alternative that is not constrained to absence is instantiated. For example, for the typeCHOICE {
name PrintableString,
byte INTEGER
} (WITH COMPONENTS {
name ABSENT,
byte (31)})
the value byte: 31 is created. |
| DATE or TIME constrained to have only dates | The value is created based on PER-visible PropertySettings, the following values are used for types constrained to have: centuries - basic: "20C", proleptic: "01C", negative: "-01C", large: "+100...C" years - basic: "2000", proleptic: "0001", negative: "-0001", large: "+10000..." months - "01" weeks - "W01" days - "001", or "01", or "1" For example, types constrained to have dates with basic years, weeks, and days are instantiated with the "2000-W01-1" value. |
| DATE-TIME or TIME constrained to have only dates and time of day | The value is created based on PER-visible PropertySettings. Depending on whether or not the type is constrained to have years, months, minutes, seconds, and so on, characters specified above for DATE types and below for TIME-OF-DAY types are added for the corresponding date and time component. For example, types constrained to have dates with basic years, months, days, hours, minutes, and seconds are instantiated with the "2000-01-01T00:00:00" value. |
| DURATION or TIME constrained to have only durations | The value of "P0Y". |
| ENUMERATED | The first enumerator with the smallest number. |
| GeneralizedTime | The value of "00000101000000". |
| INTEGER with named numbers and no IAAPI_NONAMED_ITEMS flag | The value of the first number. |
| INTEGER constrained and no IAAPI_NOCONSTRAIN flag | The lower bound of INTEGER types with the Bounds. |
| INTEGER unconstrained and without named numbers | The value of 0. |
| "Non-optional fields with types that have table constraint" and the IAAPI_IGNORE_COMPLEX_CONSTRAINTS and IAAPI_NOCONSTRAIN flags are not set | The value is created based on the value of the corresponding class field in the first information object from the constraining information object set. If an error occurrs, during the recursion for example, the value from the next information object is used. |
| NULL | The value of NULL. |
| OBJECT IDENTIFIER and RELATIVE OBJID | The value with two zero arcs {0 0}. |
| OCTET STRING constrained and no IAAPI_NOCONSTRAIN flag | The lower bound of OCTET STRING types with the size constraint is used to determine the number of zero octets included in the initialization value. |
| OCTET STRING unconstrained | The value of '00'H. |
| OID-IRI | The value of "/ISO/Registration-Authority". |
| Open type with TypeConstraint and no IAAPI_NOCONSTRAIN flag | The value of the type included in the TypeConstraint is created. For example, for the type TYPE-IDENTIFIER.&Type (INTEGER(2)) the INTEGER : 2 value is created. |
| REAL | The value of 0. |
| REAL with DECIMAL or MIXED | The decimal value of 0.0. |
| RELATIVE-OID-IRI | The value of "Registration-Authority". |
| SET and SEQUENCE and IAAPI_INIT_OPTIONALS flag is set | All fields including OPTIONAL ones are instantiated. |
| SET and SEQUENCE with DEFAULT fields and no IAAPI_NODEFAULT_VALUES flag | All fields with the DEFAULT syntax are initialized with default values from this syntax. |
| SET and SEQUENCE and no IAAPI_INIT_OPTIONALS flag | All fields except ones that are marked with OPTIONAL are instantiated. |
| SET and SEQUENCE with InnerType constraint and no IAAPI_NOCONSTRAIN flag | All fields that are marked with OPTIONAL, or have the DEFAULT syntax and are constrained to presence, are present. For example, for the typeSEQUENCE {
a INTEGER OPTIONAL,
b IA5String OPTIONAL
} (WITH COMPONENTS {...,, b (FROM("ABC")) PRESENT})
the value {b "A"} is created. |
| SET OF and SEQUENCE OF constrained and no IAAPI_NOCONSTRAIN flag | The number of instantiated components is determined by the size constraint. If having one component is permitted (for example SIZE(0..5)), then one component is instantiated. Otherwise, the number of components equal to the lower bound of the size constraint results in the instantiation of those components. If the type has an InnerType constraint, the constraints applied to the component are used to create the value. For example, for the type SeqOf (WITH COMPONENT (2)) where SeqOf ::= SEQUENCE OF INTEGER the value { 2 } is created. |
| SET OF and SEQUENCE OF unconstrained or IAAPI_NOCONSTRAIN flag is set | One value of the component is created. |
| TIME constrained to have only intervals | The value is created based on PER-visible PropertySettings. Depending on whether or not the type is constrained to have recurrences and the type of start and end points that can include durations (see above for DURATION), years, months, minutes, seconds, and so on, characters (see above for DATE types and below for TIME-OF-DAY types) are added for the corresponding interval component. For example, types constrained to have intervals with unlimited recurrences with start and end points being dates with large (Year=L5) centuries are instantiated with the "R/+100C/+100C" value. |
| TIME unconstrained | The time of day value of zero hours "00". |
| TIME-OF-DAY or TIME constrained to have only times of a day | The value is created based on PER-visible PropertySettings. Depending on whether or not the type is constrained to have minutes, seconds, a fractional part, and so on, zero characters are added for the corresponding time component. For example, types constrained to have time of day with hours, minutes, and seconds with 3 fractional digits are instantiated with "00:00:00.000" value. |
| UTCTime | The value of "000101000000Z". |
Creates an instance of the input ASN.1 type, identified by the type handle, in the internal format which can be understood by the encoder/decoder and other IAAPI functions. The function uses the ASN.1 type information described in the 3.15.3 clause to create a valid value of each nested type. Special IAAPI flags can be used to control the way in which these values are created.
ossCreateUnencodedValueOfType() returns an enumerator of type IAAPI_ERRTYPE. If the output unencoded value was successfully created (note that it can still violate some complex constraints applied to some ASN.1 types nested within the input PDU) and no other error occurs, the IAAPI_NOERROR enumerator is returned; otherwise, an IAAPI error code is returned which indicates the type of error that occurred.
Allows you to choose your own initialization values for the components of structured types (i.e. contained in a SET, SEQUENCE, or CHOICE) based upon their data type (for example, int, long, char, float, etc.). These initialization values are used to fill the structure when a new copy of a structured type is created or one of its component values is deleted.
typedef struct {
char charInitializer;
short shortInitializer;
int intInitializer;
long longInitializer;
LONG_LONG llongInitializer;
void *pointerInitializer;
char *floatInitializer;
char *doubleInitializer;
} IAAPI_initializers;
For example if charInitializer is set equal to E, then whenever a char type component is deleted from a structured type, its value is initialized to E (which can signify that it is empty).
ossSetInitializationValues() does not return a value.
IAAPI_initializers initValues =
{~0, SHRT_MIN+3, INT_MIN+3, LONG_MIN+3, LONG_MIN+3, NULL, 0.0, 0.0};
ossSetInitializationValues(world, &initValues);
....
ossDeleteComponent(world, parentType, compIndex, *parentValue);
Frees memory for a decoded value allocated by ossPutSimpleTypeValue(), ossPutStructTypeValue(), ossUpdateValueOfSimpleType(), and similar functions that return a value in decoded internal format.
ossFreeDecodedValue() returns an enumerator of type IAAPI_ERRTYPE. If valPtr is not NULL and no other error occurs, the IAAPI_NOERROR enumerator is returned; otherwise, an IAAPI error code which specifies the type of error that occurred is returned.
Frees memory allocated for a character string containing a value in display format returned by an IAAPI function (for example, the ossGetValueNotationOfPDU(), ossGetValueNotationOfType(), and ossGetValueOfSimpleType() functions).
ossFreeDisplayString() does not return a value.
Frees internal resources used by the IAAPI functions. You can still use the IAAPI functions after calling ossTermIAAPI(); however, all IAAPI-specific stored information (for example, permitted alphabet constraint information generated by ossPermittedAlphabetConstraint()) will be lost after a call to this function.
world is a pointer to the global OSS environment variable.
ossTermIAAPI() does not return a value.
The ossterm() | ossWterm() functions automatically call ossTermIAAPI(); there is no need for you to explicitly call this function unless you desire to free the resources used by the IAAPI much before calling ossterm() | ossWterm().
Memory for values and structures passed back by the IAAPI functions must be freed by you explicitly (for example, by a call to ossFreeDecodedValue(), ossFreeDisplayString(), ossFreeBuf(), etc.)
Is called by the IAAPI to build an error message and handle errors by default. You can pass the address of this function as the second argument of ossSetIaapiErrorHandlingFunction() to revert to the default error message handler (after previously changing it).
ossDefaultIAAPI_ERR() returns the err_code value that was passed in its second argument.
Is used to get a textual generic description of the numeric return code obtained from any IAAPI function.
The ossDescribeIaapiReturnCode() function returns a pointer to the string containing the description of the given return code. If the return code is invalid or unknown, "Unknown error code" is returned.
Retrieves error messages generated by IAAPI functions. This function should be called when one of the IAAPI functions returns a non-zero value. The ossIaapiErrMsgHandle() function must be set as the current IAAPI error handling function with a call to ossSetIaapiErrorHandlingFunction().
world is a pointer to the global OSS environment variable.
This function does not alter the state of the OSS IAAPI runtime environment.
Note that, by default, if ossIaapiErrMsgHandle() is set, no error message is printed, but a text message is available. If you wish not only to obtain the error message after the last failed IAAPI function, but also to automatically print this message into the trace file, set the IAAPI_PRINT_ERRMSG flag before the call to the failed function as follows:
ossSetIAAPIFlags(world, ossGetIAAPIFlags(world) | IAAPI_PRINT_ERRMSG);
The ossGetIaapiErrMsg() function returns a character string pointer. If one of the previous calls to an IAAPI function returns a non-zero code, the error message is returned, even if all of the subsequent calls were successful. The error message is preserved until another error occurs or until ossIAAPITerm() is called.
OssGlobal w, *world = &w;
f (rc = ossinit(world, OSS_CTL_TBL))
return 1;
ossSetIaapiErrorHandlingFunction(world, ossIaapiErrMsgHandle);
...
rc = ossDecodeValueNotationOfPDU(world, pduNum, &buf, decodedValue);
if (rc != IAAPI_NOERROR)
ossPrint(world, ossGetIaapiErrMsg(world));
Returns the address of the current error message handling function that the IAAPI is set to use.
world is a pointer to the global OSS environment variable.
ossGetIaapiErrorHandlingFunction() returns a function pointer referencing the current error message builder/handler function.
Is called by the IAAPI to build error messages and to handle errors, if it was set as the current IAAPI error handling function. To obtain error messages with ossGetIaapiErrMsg() you must pass its address as the second parameter of ossSetIaapiErrorHandlingFunction(), to revert to the default error message handler.
Note that, by default, if ossIaapiErrMsgHandle() is set, no error message is printed, and only a text message is available. If you wish to not only obtain the error message after the last failed IAAPI function but also to automatically print this message into the trace output, set the IAAPI_PRINT_ERRMSG flag before the call to the failed function as follows:
ossSetIAAPIFlags(world, ossGetIAAPIFlags(world) | IAAPI_PRINT_ERRMSG);
ossIaapiErrMsgHandle() returns the error_code value that was passed to it as its second parameter.
Allows you to specify your own custom-built error-handling function for the Interpretive ASN.1 API library. Your specified custom function will be invoked by the IAAPI every time an error occurs. Then, your specified custom function can print and handle the errors in a manner that suits your needs.
ossSetIaapiErrorHandlingFunction() does not return a value.
The error handling function that you write must have the following prototype:
int yourErrorHandlingFunctionName(OssGlobal *world, int error_code,
char *parm, long num);
Your error handling function should always simply return the error_code value that it received in its second argument.
The contents and significance of the parm and num arguments varies according to the IAAPI function in which the error was detected.
| Type of function in which the error was detected | Contents/significance of parm |
|---|---|
| Many | Is NULL and signifies that no character string description is available for the error. |
| Functions that parse input values in display format (for example, ossDecodeValueNotationOfPDU(), ossPutDecodedValueOfPDU(), and ossPutSimpleTypeValue() pass an error_code of IAAPI_BADDISPLAYVALUE to the IAAPI error handling function) | Is the address in the input character string at which the error was detected. |
| ossValueEncode() (this function passes an error_code of IAAPI_ENCFAL to the IAAPI error handling function) | Is the character string returned by ossEncode() describing the error |
| ossTypesCompatible() (this function passes an error_code of IAAPI_NOTCOMPATIBLE to the IAAPI error handling function) | Is the name of the value reference to which another value reference (of an incompatible type) was assigned. |
| Functions that read input from a file (for example, ossDecodeValueNotationOfPDU(), ossDecodeValueNotationOfType(), and ossPrintEncodingInTLV()) (these functions pass an error_code of IAAPI_CANT_OPEN_FILE, IAAPI_ERROR_READING_FROM_FILE, or IAAPI_NONHEX to the IAAPI error handling function) | Is the name of the file in which the access or reading error occurred. |
| Functions that parse input BER/DER encodings (for example, ossEncodingLength() and ossEncodingHeaderLength()) (these functions pass an error_code of IAAPI_LENTOOLONG, or IAAPI_BADHEADER to the IAAPI error handling function) | Is the value of the wrong length found in the encoding; to convert the returned value into a form that you can read, you will have to convert the pointer into a long integer. You can do this by using explicit casting. For example if the size of a pointer on your system is unsigned long, then you would write: long len = (long)(unsigned long)parm; then, len will contain the wrong length. |
| Type of function in which the error was detected | Contents/significance of num |
|---|---|
| Many | Is zero and signifies that no number is needed in the description of the error. |
| Functions that parse input values in display format (for example, ossDecodeValueNotationOfPDU(), ossPutDecodedValueOfPDU(), and ossPutSimpleTypeValue()) (these functions pass an error_code of IAAPI_BADDISPLAYVALUE to the IAAPI error handling function) | Is the number of bytes that are incorrect (and cause the error) in the input display format buffer. |
| Functions that parse input BER/DER encodings (for example, ossEncodingLength() and ossEncodingHeaderLength()) (these functions pass an error_code of IAAPI_LENTOOLONG, or IAAPI_BADHEADER to the IAAPI error handling function) | Is the number of bytes that remain in the input encoding buffer after the length field. |
| Functions that handle structured types with components (for example, ossDeleteComponent(), ossGetDecodedValueOfComponent(), and ossPutStructTypeValue()) (these functions pass an error_code of IAAPI_BADINDX to the IAAPI error handling function) | Is the bad index passed to the structured-type-handling function which is out of range. |
| ossEncodingASN1Class() and ossEncodingASN1Tag() (these functions pass an error_code of IAAPI_BADTGINDX to the IAAPI error handling function) | Is the bad out-of-range tag index passed to these functions via their fourth argument. |
| ossDecodeValueNotationOfPDU() and ossPutDecodedValueOfPDU() (these functions pass an error_code of IAAPI_DUPLCOMPVALUE to the IAAPI error handling function) | Is the index of the component for which two values (i.e. extra or duplicate) were found. |
| ossPrintEncodingInTLV(), ossDecodeValueNotationOfPDU(), and ossDecodeValueNotationOfType() (these functions pass an error_code of IAAPI_BADOFFSET or IAAPI_BADSIZE to the IAAPI error handling function) | Is the invalid specified offset for the input file (IAAPI_BADOFFSET) or the incorrect size given for the input file (IAAPI_BADSIZE.) |
Accessing values via IAAPI is a slow operation by its nature. Starting with version 6.0.0, the IAAPI supports functions that allow you to improve performance when working with decoded values and supports functions that aid applications which use user-allocated values with the IAAPI functions. The performance-enhancing functions allow you to turn on CPU-intensive internal IAAPI features like signal handling, error handling or IAAPI constraint checking without affecting common encoding/decoding operations.
Another group of functions allows you to identify the exact C representation of simple ASN.1 types used by the IAAPI and to insert user-allocated values of such types into more complex IAAPI-allocated structures. Normally, user-allocated values will be values of simple ASN.1 types allocated either on the stack or by using a standard memory allocating function (for example, malloc()). In such a case, no calls to the ossPutSimpleTypeValue() function are needed.
If generated typedef names of complex ASN.1-compiler-generated structures are available to your application, you can allocate values of structured ASN.1 types like SET, SEQUENCE, CHOICE, SET OF or SEQUENCE OF by direct references to those typedef names and their fields. You can then insert complex user-allocated values into IAAPI-allocated ones.
To free decoded values of types created by mixing user-allocated and IAAPI-allocated values, use the ossFreeNonUserDecodedValue() IAAPI function. User-allocated values should be freed only after all IAAPI-allocated complex structures containing such values have already been freed.
Checks the input type handle of an ASN.1 type and returns an enumerator which identifies the corresponding C representation of the type in the ASN.1-compiler-generated header file.
ossCtypeId() returns an enumerator of type iaapiCtype. If the type handle is a valid ASN.1 type handle, a corresponding enumerator is returned; otherwise, the ia_unknown_ctype enumerator is returned.
Here are the enumerators available in the iaapiCtype type:
struct HugeInteger{
unsigned short length;
unsigned char *value;
};
enum MixedReal_kind {OSS_BINARY, OSS_DECIMAL};
typedef struct {
enum MixedReal_kind kind;
union {
double base2;
char *base10;
} u;
} MixedReal;
struct UnboundedStr{
unsigned int length;
unsigned char *value;
};
struct VaryingStr {
unsigned short length;
unsigned char value[1]; /* first element of the array */
};
struct VaryingStr {
unsigned short length;
char value[1]; /* first element of the array */
};
struct ArrayObjid {
unsigned short count;
unsigned short value[1];
};
struct UnboundedObjid {
unsigned short count;
unsigned short *value;
};
typedef struct EncodedObjid {
unsigned short length;
unsigned char *value;
};
typedef struct OssReativeOid {
unsigned short length;
unsigned char *value;
};
struct {
short year; /* YYYY format when used for GeneralizedTime */
/* YY format when used for UTCTime */
short month;
short day;
short hour;
short minute;
short second;
short millisec;
short mindiff; /* UTC +/- minute differential */
ossBoolean utc; /* TRUE means UTC time */
} GeneralizedTime; /* UTCTime */
struct Char2bytes{
unsigned int length;
unsigned short *value;
};
struct Char4bytes{
unsigned int length;
int *value;
};
typedef struct {
int pduNum;
long length; /* length of encoded */
void *encoded;
void *decoded;
} OpenType;
typedef struct Any {
unsigned long length;
unsigned char *value;
} Any;
The iaapiCtype enum type includes types for commonly used C representations of simple ASN.1 types supported by the basic non-LED OSS ASN.1 Tools. The ossCtypeLengthSize() function can be used to determine how many bytes should be allocated for values of varying length types, such as INTEGER and REAL. This function can also be used to determine how many bytes the length or count field occupies in the unbounded or varying representations.
Note that when the Lean encoder/decoder is in use, only the following data structure types are supported:
ia_int ia_uint ia_huge_int ia_enum ia_uenum ia_bool ia_null ia_real ia_char_real ia_unbnd_bit ia_unbnd_octet ia_unbnd_char ia_2byte_char ia_4byte_char ia_utc_time ia_gen_time ia_any ia_opentype ia_encoded_objid ia_encoded_reloid ia_set ia_seq ia_choice ia_setof ia_seqof ia_unknown_ctype
Returns the number of bytes occupied by values of simple types like INTEGER and REAL or returns the number of bytes occupied by the length or count field in a generated structure of a simple ASN.1 type, such as an unbounded BIT STRING or unbounded CharacterString type.
ossCtypeLengthSize() returns an unsigned short value. If the type handle is a valid ASN.1 type handle, the following information is returned depending on the type of C type corresponding to the input type handle; a value of 0 is returned for other C type types as follows:
| C type | Return value |
|---|---|
| INTEGER (ia_int, ia_uint) | The number of bytes occupied by the value of an integer in a C structure or type is returned. For example, a short integer occupies two bytes, a long integer occupies four bytes, a long long integer occupies 8 bytes. |
| ENUMERATED (ia_enum, ia_uenum) | The number of bytes occupied by an integer corresponding to the enum C representation is returned. This value is fixed for a particular C compiler. |
| INTEGER --<HUGE>-- (ia_huge_int) | The number of bytes occupied by the length field in the structure below is returned (i.e. it shows whether the length is defined with a short or a long integer).
typedef struct HugeInteger {
unsigned short length;
unsigned char *value;
};
|
| REAL (ia_real) | The number of bytes occupied by the value of a real type in a C is returned. For example, a double occupies 8 bytes and a float occupies 4 bytes. |
| BIT STRING (ia_unbnd_bit), OCTET STRING, (ia_unbnd_octet) CharacterString (ia_unbnd_char), or ANY (ia_any) with UNBOUNDED directive | The number of bytes occupied by the length field is returned (i.e. it shows whether the length is of a short or a long integer in the generated structure):
typedef struct UnboundedBitString {
unsigned int length; /* number of significant bits */
unsigned char *value;
};
|
| BIT STRING (ia_vary_bit), OCTET STRING, (ia_vary_octet) CharacterString (ia_vary_char) with VARYING directive | The number of bytes occupied by the length field is returned (i.e. it shows whether the length is of a short or a long integer in the generated structure):
typedef struct VaryingBitString {
unsigned short length; /* number of significant bits */
unsigned char value[1]; /* first element of the array */
};
|
| OBJECT IDENTIFIER --<UNBOUNDED>-- (ia_unbnd_objid) | The number of bytes occupied by the count field is returned (i.e. it shows whether count is a short or long integer):
typedef struct UnboundedObjectIdentifier {
unsigned short count;
unsigned short *value;
};
|
| OBJECT IDENTIFIER --<ARRAY>-- (ia_array_objid) | The number of bytes occupied by the count field is returned (i.e. it shows whether count is a short or long integer):
typedef struct ArrayObjectIdentifier {
unsigned short count;
unsigned short value[1];
};
|
Frees memory for a decoded value that was either allocated by the ossPutStructTypeUserValue() or by ossUpdateStructTypeUserValue() function. This function can also be used to free memory of nested values that were allocated by calling the ossPutStructTypeUserValue() or ossUpdateStructTypeUserValue() function. All IAAPI-allocated memory at any level of nesting is freed. However, user-allocated memory is not freed by this function. It is your responsibility to free this memory when it is no longer needed. User-allocated values should be freed only after all IAAPI-allocated values which include these values are freed.
Note that ossFreeNonUserDecodedValue() is slower than ossFreeDecodedValue() because of the extra checks needed to avoid freeing of user-allocated memory. ossFreeDecodedValue() should be used to free decoded values that do not include user-allocated memory.
Prior to version 7.0, all user-allocated values needed to be freed after you no longer needed to use the functions to create PDUs with user-allocated values. All information about such values is removed from the IAAPI environment after a call to ossTermIAAPI().
Starting with version 7.0, the ossRemoveUserValue() and ossRemoveUserValues() functions allow you to remove a specified value or all user-allocated values used as parts of the IAAPI-allocated PDUs from the IAAPI environment. To free a user-allocated value that was inserted into the IAAPI-created PDU and continue to use IAAPI functions for user values, remove the freed values from the IAAPI environment by calling one of the functions.
ossFreeNonUserDecodedValue() returns an enumerator of type IAAPI_ERRTYPE. If valPtr is not NULL and no other error occurs, the IAAPI_NOERROR enumerator is returned; otherwise, an IAAPI error code which specifies the type of error that occurred is returned.
Returns the flags set by the ossSetIAAPIFlags() function.
world is a pointer to the global OSS environment variable.
Here are the flags that can be returned:
The ossGetIAAPIFlags() function returns an unsigned long integer. Upon a successful call, all of the flags in place for the IAAPI functions are returned. A value of (unsigned long) -1 is returned if world was found to be NULL. A value of zero is returned if no flags are set.
Inserts a user-allocated value of a component (identified by its index) of a structured type (SET, SEQUENCE, SET OF, SEQUENCE OF, or CHOICE) into the decoded value of its parent structure. It is similar to ossPutStructTypeValue(), except it does not free the input value.
The inserted value should have the same C representation for that value as defined in the ASN.1 compiler generated header file. The input value can correspond either to a simple or structured ASN.1 type. Prior to 7.0, the IAAPI would not free user-allocated input values.
Prior to version 7.0, you had to free all user-allocated values after you were done using the functions for creating PDUs with user-allocated values. Now, all information about such values is removed from the IAAPI environment after a call to ossTermIAAPI().
Starting with version 7.0, the ossRemoveUserValue() and ossRemoveUserValues() functions allow you to remove a specified value or all user-allocated values which are used as parts of the IAAPI-allocated PDUs from the IAAPI environment. To free a user-allocated value that was inserted into the IAAPI-created PDU and continue to use the IAAPI functions for user values, remove freed values from the IAAPI environment by calling one of the functions.
You can also insert a user-allocated structure into an IAAPI-allocated structure and then update the user-allocated structure with a new nested value. But this nested value must also be a user-allocated one as the IAAPI will not free any subcomponents of a user-allocated structure.
If an IAAPI-allocated value of a structured ASN.1 type already contains a value for the component you wish to update, the previous value is freed only if it was IAAPI-allocated and not user allocated. Since this function checks each component to determine its allocation scheme, some overhead related to these extra checks is incurred. If you always use your own allocated values for particular components in a complex IAAPI-allocated value, instead you should use the ossUpdateStructTypeUserValue() function for faster execution. This latter function never checks whether or not the value of a component is already present in the structure before inserting the new user-allocated value.
Note that this function updates only one field at a time. Thus, applications which need to update multiple fields should call this function multiple times with different component values and indices.
ossPutStructTypeUserValue() returns an enumerator of type IAAPI_ERRTYPE. If the passed type handle corresponds to a SET, SEQUENCE, SET OF, SEQUENCE OF, or CHOICE type which contains a component with the passed index and no other error occurs, the IAAPI_NOERROR enumerator is returned; otherwise, an IAAPI error code indicating the type of error encountered is returned.
Removes information about the input user-allocated value from the IAAPI environment. Note that it does not free the value. User-allocated values are added into the IAAPI environment when they are inserted into the IAAPI-created values with the ossPutStructTypeUserValue() or ossUpdateStructTypeUserValue() function. Those values are never freed by the IAAPI but information about them is stored in the IAAPI environment. This information is automatically removed with a call to ossTermIAAPI(). To free user-allocated values between the calls to the above IAAPI functions, you must also remove them from the IAAPI environment.
This function does not return a value.
Removes information about all user-allocated values from the IAAPI environment. Note that it does not free such values. User-allocated values are added into the IAAPI environment when they are inserted into the IAAPI-created values with the ossPutStructTypeUserValue() or ossUpdateStructTypeUserValue() function. Those values are never freed by the IAAPI but information about them is stored in the IAAPI environment. This information is automatically removed with a call to ossTermIAAPI(). To free user-allocated values between the calls to the above IAAPI functions, you must also remove them from the IAAPI environment.
world is a pointer to the global OSS environment variable.
This function does not return a value.
Controls the behavior of IAAPI functions. It allows you to turn off signal handling, setjmp() | longjmp() calls in error handling, and constraint checking in the IAAPI functions. By default, all above features are enabled.
| Flag | Description |
|---|---|
IAAPI _IGNORE_COMPLEX_CONSTRAINTS |
Instructs the functions that create instances of ASN.1 types (ossCreateUnencodedValueOfPDU() and ossCreateUnencodedValueOfType()) to try to create instances of components with TableConstraint based on values extracted from the constraining information object set. |
IAAPI_NOSIGNAL |
Instructs the IAAPI functions to disable all signal handling calls. |
IAAPI_NOSETJMP |
Disables calls to setjmp() and longjmp() in error handling. Setting this flag also causes IAAPI_NOSIGNAL to be automatically set (the opposite is not true). When this flag is set, it is your responsibility to ensure that the input parameters passed to the IAAPI functions are valid. A non-zero integer value is returned by the IAAPI functions when this flag is set. A non-fatal error, such as a constraint violation, could occur. Other errors, such as memory violations or access serialization violations are treated as fatal errors and cause the IAAPI functions to stop the operation. |
IAAPI_NOCONSTRAIN |
Disables constraint checking for IAAPI functions that are used to create decoded values. If this flag is set, the size of string type values and SET OF or SEQUENCE OF values are not checked for falling within the bounds of a size constraint that can be present in the ASN.1 syntax for these types. This flag instructs the ossCreateUnencodedValueOfPDU() and ossCreateUnencodedValueOfType() functions to ignore information about constraints when initialization values are created. When this flag is not set, constraints are checked and a non-fatal error is returned by IAAPI functions if constraint violations occur. |
IAAPI_DONT_PRINT_REFERENCED_TYPES |
Prevents automatic memory allocation from keeping track of names of referenced types for printing. |
IAAPI_INIT_OPTIONALS |
Instructs the functions that create instances of ASN.1 types, ossCreateUnencodedValueOfPDU() and ossCreateUnencodedValueOfType(), to also create instances of all components marked with the OPTIONAL keyword within SET and SEQUENCE types. |
IAAPI_NODEFAULT_VALUES |
Instructs the functions that create instances of ASN.1 types, ossCreateUnencodedValueOfPDU() and ossCreateUnencodedValueOfType(), to not use the values from the DEFAULT syntax within SET and SEQUENCE types as initialization values. |
IAAPI_NONAMED_ITEMS |
Instructs the functions that create instances of ASN.1 types, ossCreateUnencodedValueOfPDU() and ossCreateUnencodedValueOfType(), to ignore named bits for BIT STRING types with NamedBits and named numbers for INTEGER types with NamedNumbers when initialization values are created. |
IAAPI_NON_IAAPI_VALUE_WITH_NOCOPY |
Should be set before the call to the ossFreeDecodedValue() IAAPI function if the type whose value needs to be freed contains types marked with the NOCOPY directive and the value was created with the ossCopyTypeValue() IAAPI function. |
IAAPI_PRINT_ERRMSG |
Instructs the ossIaapiErrMsgHandle() function (if it was set as the current error handling function by a call to ossSetIaapiErrorHandlingFunction()) to automatically print the error message, using ossPrint(), to the current OSS runtime trace output. If this flag is not set, the error message is not printed and can be retrieved by ossGetIaapiErrMsg(). |
IAAPI_PRINT_PDU_NUMBER_IN_COMMENTS_FOR_OPEN_TYPES |
Instructs the functions that print value notation,
ossGetValueNotationOfPDU() and ossGetValueNotationOfType(), to print PDU numbers inside comments after the field name and before an inline PDU type definition for open types derived from component relation constraints. For example: Mod DEFINITIONS ::= BEGIN
ERROR-CLASS ::= CLASS {
&code OBJECT IDENTIFIER UNIQUE,
&Type
} WITH SYNTAX {&code &Type}
ErrorSet ERROR-CLASS ::= {
{ {1 2 3 4} INTEGER (2..3)} |
{ {1 2 3 5} SEQUENCE { a INTEGER (2..3) } } |
{ {1 2 3 5 6 7} ErrorReturn},
...
}
ErrorReturn ::= SEQUENCE {
errorCode ERROR-CLASS.&code ({ErrorSet}),
errorInfo ERROR-CLASS.&Type ({ErrorSet} {@errorCode}) } value ErrorReturn ::= {
errorCode { 1 2 3 5 },
errorInfo SEQUENCE { a INTEGER (2..3) } : { a 2 } } END When the flag is set the internal value "value" is printed with the PDU number in comments: --3--:
value ErrorReturn ::= {
errorCode { 1 2 3 5 },
errorInfo --3-- SEQUENCE {
a INTEGER (2..3)
} : {
a 2
}
}
Note that if you change the ASN.1 syntax so that the PDU number no longer corresponds to the types in the second information object in "ErrorSet", you need to manually change the number; otherwise IAAPI functions that parse value notation won't be able to create an internal value.
|
IAAPI_PRINT_REAL_VALUES_USING_BRACE_NOTATION |
Instructs the functions that print decoded values in value notation to use the representation {mantissa <num>, base 10, exponent <num>} for REAL types. |
Note that IAAPI flags have no effect on ossDecode(), ossEncode() and other non-IAAPI functions. The OSS decoder flag NOTRAPPING also disables signal handling in the IAAPI functions.
Also note that each call to ossSetIAAPIFlags() results in overwriting of the previous flags that were set. To add to the currently set flags, perform a logical OR with the flags returned by ossGetIAAPIFlags(), for example:
ossSetIAAPIFlags(world, ossGetIAAPIFlags() | IAAPI_NOCONSTRAIN);
This function returns an integer. Upon a successful call, a value of zero is returned; otherwise, a non-zero value is returned.
Returns TRUE if the type is defined with the POINTER directive.
ossTypeHasPointerDirective() returns an ossBoolean value. If the type handle is a valid ASN.1 type handle and the type was defined with the POINTER directive, TRUE is returned; otherwise, a value of FALSE is returned.
Inserts an input user-allocated value of a component (identified by its index) of a structured type (SET, SEQUENCE, SET OF, SEQUENCE OF, or CHOICE), into the decoded value of its parent structure. It is similar to ossPutStructTypeUserValue(), however, it does not check and free any previous value for the specified component. This function assumes that a value for the specified component either does not exist or is user-allocated. The input value should have exactly the same C representation as is defined in the ASN.1 compiler generated header file for the component. The input value can be a value of a simple or structured ASN.1 type. The IAAPI never frees the input value.
It is also possible to insert a user-allocated structure into an IAAPI-allocated structure and then update the user-allocated structure with a new nested value. But this nested value must also be a user-allocated one as the IAAPI will not free any subcomponents of a user-allocated structure.
Note that this function updates only one field at a time. Thus, applications which need to update multiple fields should call this function multiple times with different component values and indices.
Prior to version 7.0, you had to free all user-allocated values after you were done using the functions for creating PDUs with user-allocated values. All information about such values is removed from the IAAPI environment after the call to ossTermIAAPI().
Starting with version 7.0, the ossRemoveUserValue() and ossRemoveUserValues() functions allow you to remove a specified value or all user-allocated values used as parts of the IAAPI-allocated PDUs from the IAAPI environment. To free a user-allocated value that was inserted into the IAAPI-created PDU and continue to use IAAPI functions for user values, you have to remove freed values from the IAAPI environment by calling one of the functions.
ossUpdateStructTypeUserValue() returns an enumerator of type IAAPI_ERRTYPE. If the passed type handle corresponds to a SET, SEQUENCE, SET OF, SEQUENCE OF, or CHOICE type which contains a component with the passed index and no other error occurs, the IAAPI_NOERROR enumerator is returned; otherwise, an IAAPI error code indicating the type of error encountered is returned.
The following example illustrates how to use the functions in this section when linking with the Space-optimized encoder/decoder.
The example uses the following ASN.1 notation. It should be ASN.1 compiled with the -charint and -valuerefs options to test char and unsigned char integers and the creation of open type values. The PDU I and value reference i are used in creating such values. The SOED runtime should be used to test all possible C representations.
BCAS DEFINITIONS ::= BEGIN
S ::= SEQUENCE {
bool [1] BOOLEAN OPTIONAL,
int8 [2] INTEGER (-18..8) OPTIONAL,
uint8 [3] INTEGER (0..18) OPTIONAL,
int16 [4] INTEGER (-116 .. 300) OPTIONAL,
uint16 [5] INTEGER (0 .. 300) OPTIONAL,
int32 [6] INTEGER OPTIONAL,
uint32 [7] INTEGER (0..200000) OPTIONAL,
int64 [8] INTEGER (-164..1234567890123) OPTIONAL,
uint64 [9] INTEGER (0..4294967296) OPTIONAL,
hugeInt [10] INTEGER --<HUGE>-- OPTIONAL,
unbnd-cstr [11] PrintableString --<UNBOUNDED>-- OPTIONAL,
nllterm-cstr [12] IA5String --<NULLTERM>-- OPTIONAL,
vary-cstr [13] IA5String --<VARYING>-- OPTIONAL,
arr-objid [18] OBJECT IDENTIFIER --<ARRAY>-- OPTIONAL,
pad-cstr [14] PrintableString (SIZE(6)) --<PADDED>-- OPTIONAL,
char4-str [15] UniversalString OPTIONAL,
char2-str [16] BMPString OPTIONAL,
enc-objid [17] OBJECT IDENTIFIER --<ENCODED>-- OPTIONAL,
unb-objid [19] OBJECT IDENTIFIER --<UNBOUNDED>-- OPTIONAL,
enc-rel-objid [20] RELATIVE-OID --<ENCODED>-- OPTIONAL,
utc-time UTCTime OPTIONAL,
choice CHOICE {
gen-time GeneralizedTime
},
seq SEQUENCE {
unb-bit [1] BIT STRING --<UNBOUNDED>--,
pad-bit [2] BIT STRING (SIZE(10)) --<PADDED>--,
big-pad-bit [3] BIT STRING (SIZE(1..200)) --<PADDED>--,
vary-bit [4] BIT STRING --<VARYING>--
},
set SET {
unb-octet [1] OCTET STRING --<UNBOUNDED>--,
vary-octet [2] OCTET STRING --<VARYING>--
},
seqofseq SEQUENCE --<ARRAY>-- OF SEQUENCE {
nul NULL OPTIONAL,
uenm [1] ENUMERATED {a(1), b(2)} OPTIONAL,
enm [2] ENUMERATED {a(-1), b(-2)} OPTIONAL
},
setofset SET OF SET {
dbl [1] REAL --<DOUBLE>--,
flt [2] REAL --<FLOAT>--,
mixed-real [4] REAL --<MIXED>--
},
char-real [3] REAL --<DECIMAL>--,
any [22] ANY,
opent [24] ABSTRACT-SYNTAX.&Type
}
I ::= INTEGER
i I ::= 10
END
/*****************************************************************************
*
* The test program iausert.c exercises the extended IAAPI for user-allocated
* values. It allocates values of some simple ASN.1 types on the stack or by
* using malloc() and calls ossPutStructTypeUserValue() and
* ossUpdateStructTypeUserValue() to create IAAPI-allocated values of complex
* ASN.1 types including user-allocated values. After a PDU value is created,
* it is printed and encoded. The PDU value is freed by calling the new
* function ossFreeNonUserDecodedValue().
*
*****************************************************************************/
#include <stdio.h>
#include "ossiaapi.h"
#include "iauser.h" /* compiler-generated header file */
/***************************************************************************
* Functions defined in this file.
**************************************************************************/
static IAAPI_ERRTYPE createDecodedValueOfType(OssGlobal *world, TypeHndl type,
ossBoolean update,ossBoolean *userVal, void **retVal);
static IAAPI_ERRTYPE createComponent(OssGlobal *world, TypeHndl parentType,
int ix, ossBoolean update, void **retVal);
static void freeUserAllocatedValues();
/***************************************************************************
* Structure of different C represenations of simple types used in the
* program.
**************************************************************************/
/* Structure UShortUCharPointer is used for C represenations of HUGE INTEGER,
* ENCODED OBJECT IDENTIFIER and RELATIVE-OID types. */
struct UShortUCharPointer {
unsigned short length;
unsigned char *value;
} UShortUCharPointer;
struct UnboundedStr {
unsigned int length;
unsigned char *value;
} UnboundedStr;
struct Char2bytes {
unsigned int length;
unsigned short *value;
} Char2bytes;
struct Char4bytes {
unsigned int length;
int *value;
} Char4bytes;
struct Varying2Bstr {
unsigned short length;
unsigned char value[2];
} Varying2Bstr;
struct Varying4Cstr {
unsigned short length;
char value[4];
} Varying4Cstr;
typedef struct UnboundedOid {
unsigned short count;
unsigned short *value;
} UnboundedOid;
typedef struct Array4Oid {
unsigned short count;
unsigned short value[4];
} Array4Oid;
typedef struct UnboundedAny {
unsigned long length;
unsigned char *value;
} UnboundedAny;
/***************************************************************************
* Static variables used to keep values of simple ASN.1 types on the stack.
**************************************************************************/
static int enm;
static unsigned int uenm;
static double dbl;
static float flt;
static char creal[5];
static MixedReal mxreal;
static ossBoolean bol;
static Nulltype nul;
static char int8;
static unsigned char uint8;
static short int16;
static unsigned short uint16;
static int int32;
static unsigned int uint32;
static LONG_LONG int64;
static ULONG_LONG uint64;
static GeneralizedTime gentm;
static UTCTime utc;
static unsigned char pad_bit;
static unsigned char big_pad_bit[25];
static unsigned char *fixed_oct;
static char *padstr;
static char *nlltstr;
static struct UShortUCharPointer *hint;
static struct UnboundedStr *unb_bit;
static struct UnboundedStr *unb_oct;
static struct UnboundedStr *unb_char;
static struct Char2bytes *bmp;
static struct Char4bytes *unistr;
static struct Varying2Bstr vary_bit;
static struct Varying2Bstr vary_oct;
static struct Varying4Cstr vary_char;
static struct UShortUCharPointer *encoid;
static struct UShortUCharPointer *reloid;
static struct UnboundedOid unb_oid;
static unsigned short unb_oid_val[] = {1,2,3,4};
static struct Array4Oid arr_oid;
static OpenType opent;
static UnboundedAny *any;
static void *ptr1 = NULL;
static void *ptr2 = NULL;
static void *ptr3 = NULL;
static void *ptr4 = NULL;
static void *ptr5 = NULL;
static void *ptr6 = NULL;
static void *ptr7 = NULL;
int main()
{
OssGlobal w, *world = &w; /* OSS environment */
void *pduValue = NULL; /* pointer to a value in internal format */
int rc = 0;
TypeHndl type;
ossBoolean userVal;
/* initialize OSS runtime environment*/
#if defined(_WINDOWS) || defined(_DLL) || defined(OS2_DLL)
#ifdef CONTROL_TABLE_AS_DLL
#ifdef __OS2__
if (ossWinit(world, NULL, "iauser", (HWND)0))
#else
if (ossWinit(world, NULL, "iauser.dll", (HWND)0))
#endif /* __OS2 __ */
#else
if (ossWinit(world, iauser, NULL, (HWND)0))
#endif /* CONTROL_TABLE_AS_DLL */
#else
if (ossinit(world, iauser))
#endif
exit(1);
#ifdef _WINDOWS
if (ossOpenTraceFile(world, "iauser.txt")) {
ossWterm(world);
exit(1);
}
#endif /* _WINDOWS */
ossSetIaapiErrorHandlingFunction(world, ossDefaultIAAPI_ERR);
/* Create IAAPI value of the PDU "S" containing external
* values for simple types. */
type = ossTypeHandleOfPDU(world, S_PDU);
pduValue = NULL;
userVal = FALSE;
rc = createDecodedValueOfType(world, type, FALSE, &userVal, &pduValue);
if (rc)
ossPrint(world, "Creating decoded value of PDU failed with '%d'.\n", rc);
else {
OssBuf buf;
/* Print PDU */
ossPrint(world, "\nPrinting created value ...\n\n");
ossPrintPDU(world, S_PDU, pduValue);
/* Encode PDU */
buf.length = 0;
buf.value = NULL;
ossSetEncodingFlags(world, DEBUGPDU | AUTOMATIC_ENCDEC);
ossPrint(world, "\nTracing from the encoder ...\n\n");
rc = ossEncode(world, S_PDU, pduValue, &buf);
if (rc)
ossPrint(world, "%s\n", ossGetErrMsg(world));
else
ossFreeBuf(world, buf.value);
/* Free old user-allocated values before inserting the new ones
* into the PDU structure. */
freeUserAllocatedValues();
userVal = FALSE;
/* Update user values inside the PDU structure just created. */
rc = createDecodedValueOfType(world, type, TRUE, &userVal, &pduValue);
if (rc)
ossPrint(world, "Updating nested user-allocated values failed with '%d'.\n", rc);
else {
/* Print updated PDU */
ossPrint(world, "\nPrinting updated value ...\n\n");
ossPrintPDU(world, S_PDU, pduValue);
/* Encode updated PDU */
buf.length = 0;
buf.value = NULL;
ossPrint(world, "\nTracing from the encoder after updating values ...\n\n");
rc = ossEncode(world, S_PDU, pduValue, &buf);
if (rc)
ossPrint(world, "%s\n", ossGetErrMsg(world));
else
ossFreeBuf(world, buf.value);
}
/* Free IAPPI-allocated memory containing references to user-allocated
* values that are not freed. */
rc = ossFreeNonUserDecodedValue(world, type, pduValue);
if (rc)
ossPrint(world, "Failed to free decoded value of PDU with return code: %d\n", rc);
/* Free all user-allocated values. */
freeUserAllocatedValues();
}
ossTermIAAPI(world);
#if defined(_DLL) || defined(_WINDOWS)
#ifdef _WINDOWS
MessageBox((HWND)0,
"The trace info was written to the file iauser.txt",
"Info", MB_OK|MB_ICONINFORMATION);
ossCloseTraceFile(world);
#endif /* _WINDOWS */
ossWterm(world);
#else
ossterm(world);
#endif /* _DLL || _WINDOWS */
return 0;
}
/*
* Function frees all values allocated by the program in the
* createDecodedValueOfType() function.
*/
static void freeUserAllocatedValues()
{
free(hint->value);
free(hint);
free(unb_bit->value);
free(unb_bit);
free(unb_oct->value);
free(unb_oct);
free(unb_char->value);
free(unb_char);
free(bmp->value);
free(bmp);
free(unistr->value);
free(unistr);
free(fixed_oct);
free(padstr);
free(nlltstr);
free(encoid);
free(reloid);
free(any);
free(ptr1);
ptr1 = NULL;
free(ptr2);
ptr2 = NULL;
free(ptr3);
ptr3 = NULL;
free(ptr4);
ptr4 = NULL;
free(ptr5);
ptr5 = NULL;
free(ptr6);
ptr6 = NULL;
}
/******************************************************************************
* createDecodedValueOfType
*
* Function: Calls createComponent() that calls createDecodedValueOfType()
* again if the type to be created is a SEQUENCE, SET, SEQUENCE
* OF, SET OF, CHOICE. It initializes static variables for some
* simple types or uses calls to malloc() to allocate more
* complex C representations of simple types.
*
* Parameters:
* world Global structure passed to all OSS functions.
* type Type handle of type to create.
* update TRUE if the function is called for the second time
* to test ossUpdateStructUserValue().
* userVal contains TRUE if user-value was created, returned
* by the function.
* retVal create decoded value returned by the function.
*
* Returns: Zero if no error occurs; otherwise IAAPI_ERRTYPE code is
* returned.
*****************************************************************************/
static IAAPI_ERRTYPE createDecodedValueOfType ( OssGlobal *world,
TypeHndl type,
ossBoolean update,
ossBoolean *userVal,
void **retVal )
{
int ckind = ossCtypeId(world, type);
IAAPI_ERRTYPE rc = IAAPI_NOERROR;
int i = 0, count = 2;
unsigned short sz;
*userVal = TRUE;
switch (ckind) {
case ia_set:
case ia_seq:
case ia_choice:
count = ossNumberOfNamedItems(world, type);
case ia_setof:
case ia_seqof:
/* Create values of each component in SET or SEQUENCE, for the first
* (the only) component in CHOICE and create 2 values of the
* component in SET OF/SEQUENCE OF */
for (i = 0; i < count && !rc; i++) {
rc = createComponent(world, type, i, update, retVal);
if (ckind == ia_choice)
break;
}
*userVal = FALSE;
break;
case ia_int:
sz = ossCtypeLengthSize(world, type);
/* Initialize static variables on the stack with some values which
* are different when ossPutStructTypeUserValue() and
* ossUpdateStructTypeUserValue() are called. */
if (sz == 1) {
int8 = update ? -18 : -8;
*retVal = (void *)&int8;
} else if (sz == 2) {
int16 = update ? -116 : -16;
*retVal = (void *)&int16;
} else if (sz == 4) {
int32 = update ? -132 : -32;
*retVal = (void *)&int32;
} else {
int64 = update ? -164 : -64;
*retVal = (void *)&int64;
}
break;
case ia_uint:
sz = ossCtypeLengthSize(world, type);
if (sz == 1) {
uint8 = update ? 18 : 8;
*retVal = (void *)&uint8;
} else if (sz == 2) {
uint16 = update ? 116 : 16;
*retVal = (void *)&uint16;
} else if (sz == 4) {
uint32 = update ? 132 : 32;
*retVal = (void *)&uint32;
} else {
uint64 = update ? 164 : 64;
*retVal = (void *)&uint64;
}
break;
case ia_huge_int:
hint = malloc(sizeof(struct UShortUCharPointer));
if (update) {
/* Insert "9999" or 0x270F value */
hint->length = 2;
hint->value = malloc(2);
hint->value[0] = 0x27;
hint->value[1] = 0x0F;
} else {
/* Insert "99" or 0x63 value */
hint->length = 1;
hint->value = malloc(1);
hint->value[0] = 0x63;
}
*retVal = (void *)hint;
break;
case ia_enum:
enm = update ? -2 : -1;
*retVal = (void *)&enm;
break;
case ia_uenum:
uenm = update ? 2 : 1;
*retVal = (void *)&uenm;
break;
case ia_bool:
bol = update ? FALSE : TRUE;
*retVal = (void *)&bol;
break;
case ia_null:
nul = '\0';
*retVal = (void *)&nul;
break;
case ia_real:
sz = ossCtypeLengthSize(world, type);
if (sz == 8) {
dbl = update ? 10.5 : 0.5;
*retVal = (void *)&dbl;
} else {
flt = update ? 10.5 : 0.5;
*retVal = (void *)&flt;
}
break;
case ia_char_real:
strcpy(creal, update ? "10.5" : "0.5");
*retVal = (void *)creal;
break;
case ia_mixed_real:
mxreal.kind = OSS_BINARY;
mxreal.u.base2 = update ? 10.5 : 0.5;
*retVal = (void *)&mxreal;
break;
case ia_unbnd_bit:
unb_bit = malloc(sizeof(struct UnboundedStr));
unb_bit->length = 2; /* Number of bits */
unb_bit->value = malloc(1);
unb_bit->value[0] = 0xE0;
*retVal = (void *)unb_bit;
break;
case ia_unbnd_octet:
unb_oct = malloc(sizeof(struct UnboundedStr));
unb_oct->length = 2;
unb_oct->value = malloc(2);
unb_oct->value[0] = 0xFF;
unb_oct->value[1] = 0xF0;
*retVal = (void *)unb_oct;
break;
case ia_unbnd_char:
unb_char = malloc(sizeof(struct UnboundedStr));
unb_char->length = 5;
unb_char->value = malloc(5);
strncpy(unb_char->value, update ? "ABCDE" : "FGHIJ", 5);
*retVal = (void *)unb_char;
break;
case ia_utc_time:
utc.year = update ? 99 : 90;
utc.month = 4;
utc.day = 22;
utc.hour = 16;
utc.minute = 4;
utc.second = 0;
utc.millisec = 0;
utc.mindiff = 0;
utc.utc = TRUE;
*retVal = (void *)&utc;
break;
case ia_gen_time:
gentm.year = update ? 1999 : 1990;
gentm.month = 12;
gentm.day = 25;
gentm.hour = 12;
gentm.minute = 5;
gentm.second = 10;
gentm.millisec = 59;
gentm.mindiff = 23;
gentm.utc = FALSE;
*retVal = (void *)&gentm;
break;
case ia_2byte_char:
bmp = malloc(sizeof(struct Char2bytes));
bmp->length = 2;
bmp->value = malloc(sizeof(unsigned short) * 2);
bmp->value[0] = update ? 0x0041 /* "A" */ : 0x0043;
bmp->value[1] = update ? 0x0042 /* "B" */ : 0x0044;
*retVal = (void *)bmp;
break;
case ia_4byte_char:
unistr = malloc(sizeof(struct Char4bytes));
unistr->length = 2;
unistr->value = malloc(sizeof(int) * 2);
unistr->value[0] = update ? 0x00000057 /* "W" */ : 0x00000059;
unistr->value[1] = update ? 0x00000058 /* "X" */ : 0x0000005a;
*retVal = (void *)unistr;
break;
case ia_pad_bit:
/* Put '0101'B value that corresponds 0x50 hex value*/
pad_bit = 0x50;
*retVal = (void *)&pad_bit;
break;
case ia_big_pad_bit:
/* Put '200'H value */
memset(big_pad_bit, 0, 25);
big_pad_bit[0] = 0x20;
big_pad_bit[1] = 0x00;
*retVal = (void *)&big_pad_bit;
break;
case ia_fixed_octet: {
unsigned long size = ossUpperBoundOfSizeConstraint(world, type);
fixed_oct = malloc(size);
memset(fixed_oct, update ? 0xEE : 0xFF, size);
*retVal = (void *)fixed_oct;
}
break;
case ia_vary_bit:
/* Put '1234'H value, 0x1234 */
vary_bit.length = 16; /* number of bits */
vary_bit.value[0] = 0x12;
vary_bit.value[1] = 0x34;
*retVal = (void *)&vary_bit;
break;
case ia_vary_octet:
/* Put '5678'H value, 0x5678 */
vary_oct.length = 2; /* number of octets */
vary_oct.value[0] = 0x56;
vary_oct.value[1] = 0x78;
*retVal = (void *)&vary_oct;
break;
case ia_pad_char: {
unsigned long len = ossUpperBoundOfSizeConstraint(world, type);
padstr = malloc(len);
memset(padstr, 0, len);
strncpy(padstr, "Padded", 6);
*retVal = (void *)padstr;
break;
}
case ia_vary_char:
/* Put "AAAA" or "BBBB" value */
vary_char.length = 4; /* number of characters */
vary_char.value[0] = update ? 'A' : 'B';
vary_char.value[1] = update ? 'A' : 'B';
vary_char.value[2] = update ? 'A' : 'B';
vary_char.value[3] = update ? 'A' : 'B';
*retVal = (void *)&vary_char;
break;
case ia_nlltrm_char:
nlltstr = malloc(strlen("Null-terminated") + 1);
strcpy(nlltstr, "Null-terminated");
*retVal = (void *)nlltstr;
break;
case ia_array_objid:
/* Put encoded {1 2 3 4} */
arr_oid.count = 4;
arr_oid.value[0] = 0x01;
arr_oid.value[1] = 0x02;
arr_oid.value[2] = 0x03;
arr_oid.value[3] = 0x04;
*retVal = (void *)&arr_oid;
break;
case ia_unbnd_objid:
/* Put encoded {1 2 3 4} */
unb_oid.count = 4;
unb_oid.value = unb_oid_val;
*retVal = (void *)&unb_oid;
break;
case ia_encoded_objid:
/* Put encoded {1 2 3 4} value: {2A0304) */
encoid = malloc(sizeof(struct UShortUCharPointer));
encoid->length = 3;
encoid->value = malloc(3);
encoid->value[0] = 0x2A;
encoid->value[1] = 0x03;
encoid->value[2] = 0x04;
*retVal = (void *)encoid;
break;
case ia_encoded_reloid:
/* Put encoded {1 2 3 4} */
reloid = malloc(sizeof(struct UShortUCharPointer));
reloid->length = 4;
reloid->value = malloc(4);
reloid->value[0] = 0x01;
reloid->value[1] = 0x02;
reloid->value[2] = 0x03;
reloid->value[3] = 0x04;
*retVal = (void *)reloid;
break;
case ia_opentype:
/* Initialize OpenType structure with the valuereference "i"
* of the PDU "I" defined in the control table. */
opent.pduNum = I_PDU;
opent.length = 0;
opent.encoded = NULL;
opent.decoded = (void *)ossGetDecodedValueOfValueReference(world, 0);
*retVal = (void *)&opent;
break;
case ia_any:
/* Put encoded value "72" of INTEGER: "020148" */
any = malloc(sizeof(struct UnboundedAny));
any->length = 3;
any->value = malloc(3);
any->value[0] = 0x02;
any->value[1] = 0x01;
any->value[2] = 0x48;
*retVal = (void *)any;
break;
case ia_unknown_ctype:
default:
ossPrint(world, "Cannot create value of unknown ctype.\n");
rc = 1;
break;
}
/*
* Some representations of simple type may have an extra pointer
* that keeps the actual simple type value, allocate memory
* for this pointer. C kinds of these types are : ia_char_real,
* ia_vary_bit, ia_vary_octet, ia_vary_char, ia_nlltrm_char and
* ia_array_objid. Initialize static variables in order to correctly
* free those pointers. */
if (*userVal && !rc && ossTypeHasPointerDirective(world, type)) {
if (!ptr1) {
ptr1 = malloc(sizeof(void *));
*(void **)ptr1 = *(void **)retVal;
*retVal = ptr1;
} else if (!ptr2) {
ptr2 = malloc(sizeof(void *));
*(void **)ptr2 = *(void **)retVal;
*retVal = ptr2;
} else if (!ptr3) {
ptr3 = malloc(sizeof(void *));
*(void **)ptr3 = *(void **)retVal;
*retVal = ptr3;
} else if (!ptr4) {
ptr4 = malloc(sizeof(void *));
*(void **)ptr4 = *(void **)retVal;
*retVal = ptr4;
} else if (!ptr5) {
ptr5 = malloc(sizeof(void *));
*(void **)ptr5 = *(void **)retVal;
*retVal = ptr5;
} else if (!ptr6) {
ptr6 = malloc(sizeof(void *));
*(void **)ptr6 = *(void **)retVal;
*retVal = ptr6;
}
}
return rc;
}
/******************************************************************************
* createComponent
*
* Function: Create a SET, SEQUENCE, CHOICE, SET OF, SEQUENCE OF component
* value with possible nested user-allocated values of simple
* types.
*
* Parameters:
* world Global structure passed to all OSS functions.
* parentType Type handle of type to create.
* ix Index of the component whose value is to be created.
* update TRUE if the function is called for the second time
* to test ossUpdateStructUserValue().
* retVal create decoded value returned by the function.
*
* Returns: Zero if no error occurs; otherwise IAAPI_ERRTYPE code is
* returned.
*****************************************************************************/
static IAAPI_ERRTYPE createComponent ( OssGlobal *world,
TypeHndl parentType,
int ix,
ossBoolean update,
void **retVal )
{
IAAPI_ERRTYPE rc = IAAPI_NOERROR;
void *compVal = NULL;
TypeHndl compType;
ossBoolean userVal, nested_struct = FALSE;
int itemCnt, i;
userVal = FALSE;
compType = ossTypeHandleOfComponent(world, parentType, ix);
/*
* If the structure is updated and the component with the index "ix"
* is already present and it is a structured type value, extract this
* component, it will be updated but no need to place it back to the
* the parent structure. */
if (update && *retVal) {
int ckind = ossCtypeId(world, compType);
if (ckind == ia_setof || ckind == ia_setof || ckind == ia_set ||
ckind == ia_seq || ckind == ia_choice) {
ckind = ossCtypeId(world, parentType);
if (ckind == ia_setof || ckind == ia_seqof) {
unsigned long cnt = ossGetValueLength(world, parentType, *retVal);
if (ix < cnt)
nested_struct = TRUE;
} else if ((ckind == ia_set || ckind == ia_seq || ckind == ia_choice) &&
ossComponentValueIsPresent(world, parentType, ix, *retVal))
nested_struct = TRUE;
}
if (nested_struct) {
rc = ossGetDecodedValueOfComponent(world, parentType,
*retVal, ix, &compVal);
if (rc) {
ossFreeNonUserDecodedValue(world, parentType, *retVal);
*retVal = NULL;
}
}
}
/* Create the value of the component that may be either IAAPI
* allocated or user-allocated one. */
rc = createDecodedValueOfType(world, compType, update, &userVal, &compVal);
if (!nested_struct && !rc && compVal) {
/* Insert just created value into the parent structure. */
if (userVal) {
if (update)
rc = ossUpdateStructTypeUserValue(world, parentType,
compVal, ix, retVal);
else
rc = ossPutStructTypeUserValue(world, parentType,
compVal, ix, retVal);
} else
rc = ossPutStructTypeValue(world, parentType, compVal, ix, retVal);
}
if (rc) {
if (*retVal)
ossFreeNonUserDecodedValue(world, parentType, *retVal);
*retVal = NULL;
}
return rc;
}
The following example illustrates how to use the functions in this section when linking with the Lean encoder/decoder.
The example uses the following ASN.1 notation. It should be ASN.1 compiled with -lean -valueRefs options specified. The PDU I and value reference i are used in creating an open type value. The LEAN runtime should be used to test all supported C representations.
BCAS DEFINITIONS ::= BEGIN
S ::= SEQUENCE {
bool [1] BOOLEAN OPTIONAL,
int32 [2] INTEGER OPTIONAL,
uint32 [3] INTEGER OPTIONAL,
int64 [4] INTEGER (-1..1234567890123),
uint64 [5] INTEGER (0..4294967295),
hugeInt [10] INTEGER --<HUGE>-- OPTIONAL,
unbnd-cstr [11] PrintableString,
char4-str [12] UniversalString OPTIONAL,
char2-str [13] BMPString OPTIONAL,
enc-objid [17] OBJECT IDENTIFIER,
enc-rel-objid [18] RELATIVE-OID,
utc-time UTCTime OPTIONAL,
choice CHOICE {
gen-time GeneralizedTime
},
seq SEQUENCE {
unb-bit BIT STRING
},
set SET {
unb-octet OCTET STRING
},
seqofseq SEQUENCE OF SEQUENCE {
nul NULL OPTIONAL,
uenm [1] ENUMERATED {a(1), b(2)} OPTIONAL,
enm [2] ENUMERATED {a(-1), b(-2)} OPTIONAL
},
setofset SET OF SET {
dbl REAL
},
char-real REAL --<DECIMAL>--,
any ANY,
opent ABSTRACT-SYNTAX.&Type
}
I ::= INTEGER
i I ::= 10
END
/*****************************************************************************
*
* The test program tiauserl.c exercises the extended LEAN IAAPI for
* user-allocated values. It allocates values of some simple ASN.1 types
* on the stack or by using malloc() and calls ossPutStructTypeUserValue() and
* ossUpdateStructTypeUserValue() to create IAAPI-allocated values of complex
* ASN.1 types including user-allocated values. After a PDU value is created,
* it is printed and encoded. The PDU value is freed by calling the new
* function ossFreeNonUserDecodedValue().
*
*****************************************************************************/
#include <stdio.h>
#include "leandef.h"
#include "ossiaapi.h"
#include "iauserl.h" /* compiler-generated header file */
/***************************************************************************
* Functions defined in this file.
**************************************************************************/
static IAAPI_ERRTYPE createDecodedValueOfType(OssGlobal *world, TypeHndl type,
ossBoolean update,ossBoolean *userVal, void **retVal);
static IAAPI_ERRTYPE createComponent(OssGlobal *world, TypeHndl parentType,
int ix, ossBoolean update, void **retVal);
static void freeUserAllocatedValues();
/***************************************************************************
* Static variables used to keep values of simple ASN.1 types on the stack.
**************************************************************************/
static OSS_INT32 enm;
static OSS_UINT32 uenm;
static ossReal dbl;
static char creal[5];
static ossBoolean bol;
static Nulltype nul;
static OSS_INT32 int32;
static OSS_UINT32 uint32;
static OSS_INT64 int64;
static OSS_UINT64 uint64;
static char *gentm;
static char *utc;
static ossHugeInt *hint;
static ossBitString *unb_bit;
static ossOctetString *unb_oct;
static ossCharString *unb_char;
static ossBMPString *bmp;
static ossUniversalString *unistr;
static ossObjectID *encoid;
static ossObjectID *reloid;
static OpenType opent;
static ossAny *any;
static void *ptr1;
static void *ptr2;
static void *ptr3;
int main()
{
OssGlobal w, *world = &w; /* OSS environment */
void *pduValue = NULL; /* pointer to a value in internal format */
int rc = 0;
TypeHndl type;
ossBoolean userVal;
/* initialize OSS runtime environment*/
#if defined(_WINDOWS) || defined(_DLL) || defined(OS2_DLL)
#ifdef CONTROL_TABLE_AS_DLL
#ifdef __OS2__
if (ossWinit(world, NULL, "iauserl", (HWND)0))
#else
if (ossWinit(world, NULL, "iauserl.dll", (HWND)0))
#endif /* __OS2 __ */
#else
if (ossWinit(world, iauserl, NULL, (HWND)0))
#endif /* CONTROL_TABLE_AS_DLL */
#else
if (ossinit(world, iauserl))
#endif
exit(1);
#ifdef _WINDOWS
if (ossOpenTraceFile(world, "iauserl.txt")) {
ossWterm(world);
exit(1);
}
#endif /* _WINDOWS */
ossSetIaapiErrorHandlingFunction(world, ossDefaultIAAPI_ERR);
/* Create IAAPI value of the PDU "S" containing external
* values for simple types. */
type = ossTypeHandleOfPDU(world, S_PDU);
pduValue = NULL;
userVal = FALSE;
rc = createDecodedValueOfType(world, type, FALSE, &userVal, &pduValue);
if (rc)
ossPrint(world, "Creating decoded value of PDU failed with '%d'.\n", rc);
else {
OssBuf buf;
/* Print PDU */
ossPrint(world, "\nPrinting created value ...\n\n");
ossPrintPDU(world, S_PDU, pduValue);
/* Encode PDU */
buf.length = 0;
buf.value = NULL;
ossSetEncodingFlags(world, AUTOMATIC_ENCDEC);
ossPrint(world, "\nCalling the encoder ...\n\n");
rc = ossEncode(world, S_PDU, pduValue, &buf);
if (rc)
ossPrint(world, "%s\n", ossGetErrMsg(world));
else
ossFreeBuf(world, buf.value);
/* Free old user-allocated values before inserting the new ones
* into the PDU structure. */
freeUserAllocatedValues();
userVal = FALSE;
/* Update user values inside the PDU structure just created. */
rc = createDecodedValueOfType(world, type, TRUE, &userVal, &pduValue);
if (rc)
ossPrint(world, "Updating nested user-allocated values failed with '%d'.\n", rc);
else {
/* Print updated PDU */
ossPrint(world, "\nPrinting updated value ...\n\n");
ossPrintPDU(world, S_PDU, pduValue);
/* Encode updated PDU */
buf.length = 0;
buf.value = NULL;
ossPrint(world, "\nCalling the encoder after updating values ...\n\n");
rc = ossEncode(world, S_PDU, pduValue, &buf);
if (rc)
ossPrint(world, "%s\n", ossGetErrMsg(world));
else
ossFreeBuf(world, buf.value);
}
/* Free IAPPI-allocated memory containing references to user-allocated
* values that are not freed. */
rc = ossFreeNonUserDecodedValue(world, type, pduValue);
if (rc)
ossPrint(world, "Failed to free decoded value of PDU with return code: %d\n", rc);
/* Free all user-allocated values. */
freeUserAllocatedValues();
}
ossTermIAAPI(world);
#if defined(_DLL) || defined(_WINDOWS)
#ifdef _WINDOWS
MessageBox((HWND)0,
"The trace info was written to the file iauserl.txt",
"Info", MB_OK|MB_ICONINFORMATION);
ossCloseTraceFile(world);
#endif /* _WINDOWS */
ossWterm(world);
#else
ossterm(world);
#endif /* _DLL || _WINDOWS */
return 0;
}
/*
* Function frees all values allocated by the program in the
* createDecodedValueOfType() function.
*/
static void freeUserAllocatedValues()
{
free(hint->value);
free(hint);
free(unb_bit->value);
free(unb_bit);
free(unb_oct->value);
free(unb_oct);
free(unb_char->value);
free(unb_char);
free(bmp->value);
free(bmp);
free(unistr->value);
free(unistr);
free(encoid);
free(reloid);
free(utc);
free(gentm);
free(any);
free(ptr1);
free(ptr2);
free(ptr3);
}
/******************************************************************************
* createDecodedValueOfType
*
* Function: Calls createComponent() that calls createDecodedValueOfType()
* again if the type to be created is a SEQUENCE, SET, SEQUENCE
* OF, SET OF, CHOICE. It initializes static variables for some
* simple types or uses calls to malloc() to allocate more
* complex C representations of simple types.
*
* Parameters:
* world Global structure passed to all OSS functions.
* type Type handle of type to create.
* update TRUE if the function is called for the second time
* to test ossUpdateStructUserValue().
* userVal contains TRUE if user-value was created, returned
* by the function.
* retVal create decoded value returned by the function.
*
* Returns: Zero if no error occurs; otherwise IAAPI_ERRTYPE code is
* returned.
*****************************************************************************/
static IAAPI_ERRTYPE createDecodedValueOfType ( OssGlobal *world,
TypeHndl type,
ossBoolean update,
ossBoolean *userVal,
void **retVal )
{
int ckind = ossCtypeId(world, type);
IAAPI_ERRTYPE rc = IAAPI_NOERROR;
int i = 0, count = 2, typeid;
unsigned short sz;
*userVal = TRUE;
switch (ckind) {
case ia_set:
case ia_seq:
case ia_choice:
count = ossNumberOfNamedItems(world, type);
case ia_setof:
case ia_seqof:
/* Create values of each component in SET or SEQUENCE, for the first
* (the only) component in CHOICE and create 2 values of the
* component in SET OF/SEQUENCE OF */
for (i = 0; i < count && !rc; i++) {
rc = createComponent(world, type, i, update, retVal);
if (ckind == ia_choice)
break;
}
*userVal = FALSE;
break;
case ia_int:
sz = ossCtypeLengthSize(world, type);
/* Initialize static variables on the stack with some values which
* are different when ossPutStructTypeUserValue() and
* ossUpdateStructTypeUserValue() are called. */
if (sz == 4) {
int32 = update ? -132 : -32;
*retVal = (void *)&int32;
} else {
int64 = update ? -164 : -64;
*retVal = (void *)&int64;
}
break;
case ia_uint:
sz = ossCtypeLengthSize(world, type);
if (sz == 4) {
uint32 = update ? 132 : 32;
*retVal = (void *)&uint32;
} else {
uint64 = update ? 164 : 64;
*retVal = (void *)&uint64;
}
break;
case ia_huge_int:
hint = malloc(sizeof(struct ossHugeInt));
if (update) {
/* Insert "9999" or 0x270F value */
hint->length = 2;
hint->value = malloc(2);
hint->value[0] = 0x27;
hint->value[1] = 0x0F;
} else {
/* Insert "99" or 0x63 value */
hint->length = 1;
hint->value = malloc(1);
hint->value[0] = 0x63;
}
*retVal = (void *)hint;
break;
case ia_enum:
enm = update ? -2 : -1;
*retVal = (void *)&enm;
break;
case ia_uenum:
uenm = update ? 2 : 1;
*retVal = (void *)&uenm;
break;
case ia_bool:
bol = update ? FALSE : TRUE;
*retVal = (void *)&bol;
break;
case ia_null:
nul = '\0';
*retVal = (void *)&nul;
break;
case ia_real:
sz = ossCtypeLengthSize(world, type);
dbl = update ? 10.5 : 0.5;
break;
case ia_char_real:
strcpy(creal, update ? "10.5" : "0.5");
*retVal = (void *)creal;
if (ossTypeHasPointerDirective(world, type)) {
ptr1 = malloc(sizeof(void *));
*(void **)ptr1 = *(void **)retVal;
*retVal = ptr1;
}
break;
case ia_unbnd_bit:
unb_bit = malloc(sizeof(ossBitString));
unb_bit->length = 2; /* Number of bits */
unb_bit->value = malloc(1);
unb_bit->value[0] = 0xE0;
*retVal = (void *)unb_bit;
break;
case ia_unbnd_octet:
unb_oct = malloc(sizeof(ossOctetString));
unb_oct->length = 2;
unb_oct->value = malloc(2);
unb_oct->value[0] = 0xFF;
unb_oct->value[1] = 0xF0;
*retVal = (void *)unb_oct;
break;
case ia_unbnd_char:
unb_char = malloc(sizeof(ossCharString));
unb_char->length = 5;
unb_char->value = malloc(5);
strncpy(unb_char->value, update ? "ABCDE" : "FGHIJ", 5);
*retVal = (void *)unb_char;
break;
case ia_2byte_char:
bmp = malloc(sizeof(ossBMPString));
bmp->length = 2;
bmp->value = malloc(sizeof(unsigned short) * 2);
bmp->value[0] = update ? 0x0041 /* "A" */ : 0x0043;
bmp->value[1] = update ? 0x0042 /* "B" */ : 0x0044;
*retVal = (void *)bmp;
break;
case ia_4byte_char:
unistr = malloc(sizeof(ossUniversalString));
unistr->length = 2;
unistr->value = malloc(sizeof(int) * 2);
unistr->value[0] = update ? 0x00000057 /* "W" */ : 0x00000059;
unistr->value[1] = update ? 0x00000058 /* "X" */ : 0x0000005a;
*retVal = (void *)unistr;
break;
case ia_encoded_objid:
/* Put encoded {1 2 3 4} value: {2A0304) */
encoid = malloc(sizeof(ossObjectID));
encoid->length = 3;
encoid->value = malloc(3);
encoid->value[0] = 0x2A;
encoid->value[1] = 0x03;
encoid->value[2] = 0x04;
*retVal = (void *)encoid;
break;
case ia_encoded_reloid:
/* Put encoded {1 2 3 4} */
reloid = malloc(sizeof(ossObjectID));
reloid->length = 4;
reloid->value = malloc(4);
reloid->value[0] = 0x01;
reloid->value[1] = 0x02;
reloid->value[2] = 0x03;
reloid->value[3] = 0x04;
*retVal = (void *)reloid;
break;
case ia_opentype:
/* Initialize OpenType structure with the valuereference "i"
* of the PDU "I" defined in the control table. */
opent.pduNum = I_PDU;
opent.length = 0;
opent.encoded = NULL;
opent.decoded = (void *)ossGetDecodedValueOfValueReference(world, 0);
*retVal = (void *)&opent;
break;
case ia_any:
/* Put encoded value "72" of INTEGER: "020148" */
any = malloc(sizeof(ossAny));
any->length = 3;
any->value = malloc(3);
any->value[0] = 0x02;
any->value[1] = 0x01;
any->value[2] = 0x48;
*retVal = (void *)any;
break;
case ia_nlltrm_char:
typeid = ossAsn1TypeId(world, type);
if (typeid == asn1UTCTime) {
utc = malloc(strlen("990422160400Z") + 1);
strcpy(utc, update ? "990422160400Z" : "900422160400Z");
*retVal = (void *)utc;
if (ossTypeHasPointerDirective(world, type)) {
ptr2 = malloc(sizeof(void *));
*(void **)ptr2 = *(void **)retVal;
*retVal = ptr2;
}
break;
} else if (typeid == asn1GeneralizedTime) {
gentm = malloc(strlen("19991225120510.059+0023") + 1);
strcpy(gentm, update ? "19991225120510.059+0023" : "19901225120510.059+0023");
*retVal = (void *)gentm;
if (ossTypeHasPointerDirective(world, type)) {
ptr3 = malloc(sizeof(void *));
*(void **)ptr3 = *(void **)retVal;
*retVal = ptr3;
}
break;
}
case ia_unknown_ctype:
default:
ossPrint(world, "Cannot create value of unknown ctype.\n");
rc = 1;
break;
}
return rc;
}
/******************************************************************************
* createComponent
*
* Function: Create a SET, SEQUENCE, CHOICE, SET OF, SEQUENCE OF component
* value with possible nested user-allocated values of simple
* types.
*
* Parameters:
* world Global structure passed to all OSS functions.
* parentType Type handle of type to create.
* ix Index of the component whose value is to be created.
* update TRUE if the function is called for the second time
* to test ossUpdateStructUserValue().
* retVal create decoded value returned by the function.
*
* Returns: Zero if no error occurs; otherwise IAAPI_ERRTYPE code is
* returned.
*****************************************************************************/
static IAAPI_ERRTYPE createComponent ( OssGlobal *world,
TypeHndl parentType,
int ix,
ossBoolean update,
void **retVal )
{
IAAPI_ERRTYPE rc = IAAPI_NOERROR;
void *compVal = NULL;
TypeHndl compType;
ossBoolean userVal, nested_struct = FALSE;
int itemCnt, i;
userVal = FALSE;
compType = ossTypeHandleOfComponent(world, parentType, ix);
/*
* If the structure is updated and the component with the index "ix"
* is already present and it is a structured type value, extract this
* component, it will be updated but no need to place it back to the
* the parent structure. */
if (update && *retVal) {
int ckind = ossCtypeId(world, compType);
if (ckind == ia_setof || ckind == ia_setof || ckind == ia_set ||
ckind == ia_seq || ckind == ia_choice) {
ckind = ossCtypeId(world, parentType);
if (ckind == ia_setof || ckind == ia_seqof) {
unsigned long cnt = ossGetValueLength(world, parentType, *retVal);
if (ix < cnt)
nested_struct = TRUE;
} else if ((ckind == ia_set || ckind == ia_seq || ckind == ia_choice) &&
ossComponentValueIsPresent(world, parentType, ix, *retVal))
nested_struct = TRUE;
}
if (nested_struct) {
rc = ossGetDecodedValueOfComponent(world, parentType,
*retVal, ix, &compVal);
if (rc) {
ossFreeNonUserDecodedValue(world, parentType, *retVal);
*retVal = NULL;
}
}
}
/* Create the value of the component that may be either IAAPI
* allocated or user-allocated one. */
rc = createDecodedValueOfType(world, compType, update, &userVal, &compVal);
if (!nested_struct && !rc && compVal) {
/* Insert just created value into the parent structure. */
if (userVal) {
if (update)
rc = ossUpdateStructTypeUserValue(world, parentType,
compVal, ix, retVal);
else
rc = ossPutStructTypeUserValue(world, parentType,
compVal, ix, retVal);
} else
rc = ossPutStructTypeValue(world, parentType, compVal, ix, retVal);
}
if (rc) {
if (*retVal)
ossFreeNonUserDecodedValue(world, parentType, *retVal);
*retVal = NULL;
}
return rc;
}
Starting with version 7.0, the IAAPI supports functions that allow users to allocate and free values when inserting them into the existing or newly created PDUs. The ossRemoveUserValue() and ossRemoveUserValues() functions remove a specified value or all user-allocated values which are used as parts of the IAAPI-allocated PDUs from the IAAPI environment. Previously, user-allocated values had to be freed after they were no longer used within IAAPI-allocated PDUs.
The IAAPI has an API for advanced information object notation. This API is a collection of functions that provide access to the ASN.1 notation of information object classes, information object sets, and information objects. The API also allows access to the information stored in simple table and component relation constraints. This allows applications to build information objects from scratch and remove or add new information objects into extensible information object sets. Applications can also determine which ASN.1 types are stored (or can be stored) in open types defined with component relation constraints (for example, based upon values of referenced fields that appear in the @-notation of such constraints) all without any foreknowledge of the original ASN.1 notation.
The API functions can be divided into the following categories:
Additionally, an IAAPI FieldHndl identifies components within SET, SEQUENCE, SET OF, SEQUENCE OF, CHOICE and CLASS structures. It is used in several functions.
Retrieves a pointer to the information object set based upon the value that an ObjectSetField carries inside an information object.
Note that information object sets that appear as values of ObjectSetFields inside information objects generated by the ASN.1 compiler are not included in the common list of all information object sets and, as such, they cannot be accessed via functions that have an information object set index as a parameter, such as ossGetInfoObjectSet() and ossInfoObjSetIndex(). Only the ossGetNextInfoObject() function can be used to access such information object sets and the objects they contain.
This function returns an enumerator of type IAAPI_ERRTYPE. If no other error occurs, the IAAPI_NOERROR enumerator is returned; otherwise, an IAAPI error code indicating the type of error encountered is returned.
Returns the type handle of the actual type stored in the value of a TypeField or the type handle of the value set type stored in the value of a FixedTypeValueSetField or VariableTypeValueSetField inside an information object.
This function returns an enumerator of type IAAPI_ERRTYPE. If no other error occurs, the IAAPI_NOERROR enumerator is returned; otherwise, an IAAPI error code indicating the type of error encountered is returned.
Determines the type of field within an information object class. The field is identified by its field handle.
ossInfoObjClassFieldId() returns an enumerator of type IAAPI_ClassFieldType. If the passed field handle corresponds to a field within an information object class, its appropriate enumerator is returned; otherwise, the ia_ordinaryField enumerator is returned. Note that IAAPI_ClassFieldType has the following definition in the ossiaapi.h header file:
typedef enum IAAPI_ClassFieldType {
ia_ordinaryField,
ia_typeField,
ia_variableTypeValueField,
ia_fixedTypeValueSetField,
ia_variableTypeValueSetField,
ia_objectField,
ia_objectSetField
}IAAPI_ClassFieldType;
For example, the &TypeField field in the EXAMPLE-CLASS class has the ia_typeField type, the &ObjectSetField field has the ia_objectSetField type and so on.
EXAMPLE-CLASS ::= CLASS {
&TypeField,
&fixedTypeValueField INTEGER,
&variableTypeValueField &TypeField,
&FixedTypeValueSetField INTEGER,
&VariableTypeValueSetField &TypeField,
&objectField SIMPLE-CLASS,
&ObjectSetField SIMPLE-CLASS
}
SIMPLE-CLASS ::= CLASS {
&value INTEGER
}
Determines whether or not a field within an information object class is marked as UNIQUE.
The function returns a value of type ossBoolean. If the specified information object class field is marked as UNIQUE, a value of TRUE is returned; otherwise, a value of FALSE is returned.
Returns the type handle of the information object class identified by its index in the list of all information object classes in the input ASN.1 notation.
The ossTypeHandleOfInfoObjClassByIndex() function returns a TypeHndl value. If the input ASN.1 specification contains an information object class with the specified index, its type handle is returned; otherwise, a value of NULL is returned. A type handle of an information object class can be used in calls to many pre-existing IAAPI functions. For example, ossTypeReferenceName() can be used along with the type handle to get the name of an information object class identified by its type handle.
Returns the type handle of the information object class identified by its ASN.1 name in the input ASN.1 notation.
The function returns a TypeHndl value. If the input ASN.1 specification contains an information object class with the specified name, its type handle is returned; otherwise, a value of NULL is returned.
Returns the number of information object classes defined in the input ASN.1 specification.
world is a pointer to the global OSS environment variable.
The function returns an integer. If the input ASN.1 specification contains information object classes and no other error occurs, the number of information objects contained is returned; otherwise, a value less than 1 is returned.
Returns an ObjectClassFieldType notation in the form 'DefinedObjectClass.FieldName1.FieldName2...' for a type that is defined using such notation and has a table or component relation constraint.
For example, the ATTRIBUTE.&equality-match.&AssertionType type is used as an alternative for the built-in type in the syntax below:
AttributeValueAssertion ::= SEQUENCE {
type ATTRIBUTE.&id ({SupportedAttributes}),
assertion ATTRIBUTE.&equality-match.&AssertionType
({SupportedAttributes}{@type})}
This function returns an ObjectClassFieldType notation as a string that MUST be freed by the caller. NULL is returned if the type does not have a table or component relation constraint or if the constraints have been disabled, or if an error occurred.
Creates a value for an ObjectClassField containing a specified information object set address.
This function returns an enumerator of type IAAPI_ERRTYPE. If no other error occurs, the IAAPI_NOERROR enumerator is returned; otherwise, an IAAPI error code indicating the type of error encountered is returned.
Creates the value of a TypeField, FixedTypeValueSetField, or VariableTypeValueSetField containing a specified type handle unique identifier inside an information object.
This function returns an enumerator of type IAAPI_ERRTYPE. If no other error occurs, the IAAPI_NOERROR enumerator is returned; otherwise, an IAAPI error code indicating the type of error encountered is returned.
Returns the field handle of a TypeField relative to the specified VariableTypeField inside an information object class.
This function returns a value of type FieldHndl. If the field with the specified field handle is a VariableTypeField and its relative type field is found, the field handle of the relative type field is returned; otherwise, a value of NULL is returned.
Adds an information object identified by its index within an extensible information object set identified by its index in the list of all information object sets defined in the input ASN.1 notation and used in table or component relation constraints into another information object set identified by its index in the list of all information object sets.
This function returns an enumerator of type IAAPI_ERRTYPE. If no other error occurs, the IAAPI_NOERROR enumerator is returned; otherwise, an IAAPI error code indicating the type of error encountered is returned.
Adds an information object identified by its name to an extensible information object set identified by its name.
This function returns an enumerator of type IAAPI_ERRTYPE. If no other error occurs, the IAAPI_NOERROR enumerator is returned; otherwise, an IAAPI error code indicating the type of error encountered is returned.
Retrieves the next information object within an information object set constraining the field of a SET, SEQUENCE or CHOICE identified by its field handle if the input value of this field is the same as the value of a corresponding information object class field specified in this object. Note that if the corresponding field in the information object class is not unique, there can be several information objects with the same values for this field. To retrieve all objects whose values of a specified field match the specified input value, the function should be called in the loop until no more objects are found. The last parameter should point to NULL before the first call to this function.
This function returns an enumerator of type IAAPI_ERRTYPE. If no other error occurs, the IAAPI_NOERROR enumerator is returned and a pointer to the information object found is returned in the last parameter; otherwise, an IAAPI error code indicating the type of error encountered is returned.
Returns the address of an information object identified by its index within an information object set identified by its index in the list of all information object sets in the input ASN.1 notation that are used in table or component relation constraints.
After obtaining the information object, you can use functions for handling decoded values to access the values of contained fields.
This function returns an enumerator of type IAAPI_ERRTYPE and the address of an information object in the last parameter. If the value retrieval is successful, the IAAPI_NOERROR enumerator is returned and the address of an information object; otherwise, an IAAPI error code indicating the type of error encountered is returned.
Returns the address of an information object identified by its ASN.1 name within the information object set identified by its ASN.1 name.
After obtaining the information object, you can use functions for handling decoded values to access the values of contained fields.
This function returns an enumerator of type IAAPI_ERRTYPE and the address of an information object in the last parameter. If the value retrieval is successful, the IAAPI_NOERROR enumerator is returned along with the address of an information object; otherwise, an IAAPI error code indicating the type of error encountered is returned.
Returns the address of an information object within an information object set identified by its value. The first information object within the set is returned if the last parameter points to NULL; otherwise, the information object immediately after the one pointed to by the last parameter is returned.
This function returns an enumerator of type IAAPI_ERRTYPE and the address of an information object in the last parameter. If the value retrieval is successful, the IAAPI_NOERROR enumerator is returned and the address of an information object; otherwise, an IAAPI error code indicating the type of error encountered is returned.
Returns the address and name (if it has one) of an information object within an information object set identified by its value. The first information object within the set is returned if the last parameter points to NULL; otherwise, the information object immediately after the one pointed to by the last parameter is returned.
This function returns an enumerator of type IAAPI_ERRTYPE, the address of an information object in the third parameter, and the name of the object or NULL as the last parameter. If the value retrieval is successful, the IAAPI_NOERROR enumerator is returned and the address of an information object; otherwise, an IAAPI error code indicating the type of error encountered is returned.
Allows you to retrieve the name of an information object identified by its index in the list of all information objects in an information object set (the latter is identified by its index in the list of all information object sets in the input ASN.1 specification).
This function returns a pointer to a const char value. If the input ASN.1 specification contains an information object and object set with the specified indices, the ASN.1 name of the object is returned; otherwise, a value of NULL is returned.
Allows you to retrieve the internal handle of the information object set identified by its index in the list of all information object sets in the input ASN.1 notation (excluding information object sets defined as values of ObjectSetFields inside information objects). The handle can be used as an input parameter to other IAAPI functions.
This function returns the address of the information object set that is needed for calls to other IAAPI functions, such as ossPrintInfoObjSet(). If the input ASN.1 specification contains an information object set with the specified index, its internal handle is returned. Otherwise, NULL is returned.
Allows you to learn the index of an information object set in the list of all information object sets in the input ASN.1 notation (excluding information object sets defined as values of ObjectSetFields inside information objects) identified by its value.
This function returns an information object set index that is used in calls to other functions, for example ossNumberOfInfoObjects(). If the input ASN.1 specification contains an information object set with the specified name, its index in the list of all information object sets is returned; otherwise, UINT_MAX is returned.
Allows you to retrieve the index of an information object set in the list of all information object sets in the input ASN.1 notation identified by its ASN.1 name.
This function returns an information object set index that is used in calls to other functions, for example ossNumberOfInfoObjects(). If the input ASN.1 specification contains an information object set with the specified name, its index in the list of all information object sets is returned; otherwise, UINT_MAX is returned.
Determines whether or not an information object set identified by its index in the list of all information object sets in the input ASN.1 notation is extensible. New information objects can be added only to extensible information object sets.
This function returns an integer. If the input ASN.1 specification contains an information object sets with the specified index that is extensible, a value of TRUE is returned; otherwise, a value of FALSE is returned.
Allows you to retrieve the name of an information object set identified by its index in the list of all information object sets in the input ASN.1 notation.
This function returns a pointer to a const char value. If the input ASN.1 specification contains an information object set with the specified index, its ASN.1 name is returned; otherwise, a value of NULL is returned.
Allows you to retrieve the type handle of the information object class governing an information object set identified by its index in the list of all information object sets in the input ASN.1 notation.
This function returns a TypeHndl value. If the input ASN.1 specification contains an information object set with the specified index, the type handle of the governing information object class is returned; otherwise, a value of NULL is returned.
Returns the number of information objects contained within an information object set identified by its index in the list of all information object sets in the input ASN.1 notation.
This function returns an integer. If the input ASN.1 specification contains an information object set with the specified index and no other error occurs, the number of information objects that the information object set contains is returned; otherwise, a value of 0 is returned.
Returns the number of information object sets defined in the input ASN.1 specification. Note that this does not include information object sets defined as values of ObjectSetFields inside information objects. The ossGetInfoObjectSet() API function can be used to extract the actual information object set.
world is a pointer to the global OSS environment variable.
This function returns an integer. If the input ASN.1 specification contains information object sets and no other error occurs, the number of information objects contained is returned; otherwise, a value of 0 is returned.
Returns the number of information objects that appear before the extension marker in the information object set identified by its index in the list of all information object sets in the input ASN.1 notation.
This function returns an integer. If the input ASN.1 specification contains an extensible information object sets with the specified index and no other error occurs, the number of information objects that appear before the extension maker or the total number of information objects contained in a non-extensible information object set is returned; otherwise, a value of 0 is returned.
Removes an information object identified by its index from an extensible information object set identified by its index in the list of all information object sets defined in the input ASN.1 notation. Only information objects that appear after the extension marker in the specified information object set or information objects that were added by using IAAPI functions can be removed.
This function returns an enumerator of type IAAPI_ERRTYPE. If no other error occurs, the IAAPI_NOERROR enumerator is returned; otherwise, an IAAPI error code indicating the type of error encountered is returned.
Removes an information object identified by its ASN.1 name from an extensible information object set identified by its ASN.1 name. Only information objects that appear after the extension marker in the specified information object set or information objects that were added by using IAAPI functions can be removed.
This function returns an enumerator of type IAAPI_ERRTYPE. If no other error occurs, the IAAPI_NOERROR enumerator is returned; otherwise, an IAAPI error code indicating the type of error encountered is returned.
NOTE: The FieldHndl handle references simple table and component relation constraints.
Returns the field handle of the component identified by its index within a SEQUENCE, SET, CHOICE or information object class identified by its type handle.
This function returns a value of type FieldHndl. If the component with the specified index exists, its field handle is returned; otherwise, a value of NULL is returned.
Returns the index of the component identified by its FieldHndl within a SEQUENCE, SET, CHOICE or information object class.
This function returns an unsigned integer value. If the field handle of a component within a SEQUENCE, SET, CHOICE or CLASS is correct, the index of the component is returned; otherwise, a value UINT_MAX is returned.
Returns the field handle of the field within an information object class specified in the object class field type notation of the component identified by its field handle within a SEQUENCE, SET or CHOICE type (whose type has an object class field type notation applied).
This function returns a value of type FieldHndl. If the type of the specified field is defined with the object class field type notation, the field handle of the referenced object class field is returned. For example, a field handle of the &id field is returned for the TYPE-IDENTIFIER.&id type. NULL is returned if an error occurs or if the type of the field is not an object class field type.
Returns the type handle of the information object class specified in the object class field type notation of the component identified by its field handle within a SEQUENCE, SET or CHOICE type.
This function returns a value of type TypeHndl. If the type of the specified field is defined with an object class field type notation, the type handle of the information object class specified in this notation is returned (for example, a type handle of TYPE-IDENTIFIER is returned if the type of the field is defined as TYPE-IDENTIFIER.&id); otherwise, a value of NULL is returned./
Returns the index of the information object set in the list of all information object sets defined in the input ASN.1 notation constraining the component identified by its field handle.
This function returns a value of type unsigned int. If the specified field has a simple table constraint or component relation constraint, the index of the constraining information object set is returned; otherwise, a value UINT_MAX is returned.
Returns the type handle of the parent of a component identified by its FieldHndl within a SEQUENCE, SET, CHOICE or information object class.
This function returns a value of type TypeHndl. If the field handle of a component within a SEQUENCE, SET, CHOICE, or CLASS is correct, its parent type handle is returned; otherwise, a value of NULL is returned.
Returns the identifier of the component identified by its FieldHndl within a SEQUENCE, SET, CHOICE or information object class.
This function returns a pointer to a const char value. If the component with the specified field handle has an identifier, it is returned; otherwise, a value of NULL is returned.
Returns the type handle of the actual ASN.1 type that an open type value can carry for open types created for fields of component relation constraints.
This function returns an enumerator of type IAAPI_ERRTYPE. If the type handle retrieval is successful, the IAAPI_NOERROR enumerator is returned; otherwise, an IAAPI error code indicating the type of error encountered is returned.
Determines whether or not the component identified by its index within a SET, SEQUENCE, SET OF, SEQUENCE OF, or CHOICE type has a component relation constraint applied.
This function returns a value of type ossBoolean. If the specified field has a component relation constraint applied, a value of TRUE is returned; otherwise, a value of FALSE is returned.
Determines whether or not the component identified by its index within a SET, SEQUENCE, SET OF, SEQUENCE OF, or CHOICE type has a simple table constraint applied.
This function returns a value of type ossBoolean. If the type of the specified field has a simple table constraint, a value of TRUE is returned; otherwise, a value of FALSE is returned.
Returns the number of referenced fields (for example, fields identified in a component relation constraint of another field identified by its field handle within a SEQUENCE or SET type). In most cases, a component relation constraint references only one such field.
This function returns a value of type int. If the specified field has a component relation constraint, the number of referenced fields is returned; otherwise, a value less than 1 is returned.
Returns the number of referencing fields associated with the input field identified by its field handle within a SET, SEQUENCE, or CHOICE. Referencing fields are fields that have component relation constraints that include the input field as a referenced field (in the @-notation).
This function returns a value of type int. If the specified field is referenced in one or more component relation constraints, the number of referencing fields with such constraints is returned; otherwise, a value less than 1 is returned.
When a component relation constraint is applied to an element of a SET OF or SEQUENCE OF type, the field handle of the topmost SET, SEQUENCE, or CHOICE type is returned.
For example, the following function that is called for the errorCategory field returns that one referencing component exists and it refers to the errorInfo field whose type has no component relation constraint (but a component of the last SEQUENCE OF type does have one).
ErrorReturn ::= SEQUENCE {
errorCategory ERROR-CLASS.&category ({ErrorSet}),
errorInfo SET OF SET OF SEQUENCE OF
ERROR-CLASS.&Type ({ErrorSet}{@errorCategory})
}
Returns the field handle of the referencing field identified by its index in the list of all referencing fields that have component relation constraints that include the field identified by its field handle within SET, SEQUENCE, or CHOICE as a referenced field (in the @-notation).
When a component relation constraint is applied to an element of a SET OF or SEQUENCE OF type, the field handle of the topmost SET, SEQUENCE, or CHOICE type is returned.
For example, the following function that is called for the errorCategory field returns the field handle of the errorInfo field whose type has no component relation constraint (but a component of the last SEQUENCE OF type does have one).
ErrorReturn ::= SEQUENCE {
errorCategory ERROR-CLASS.&category ({ErrorSet}),
errorInfo SET OF SET OF SEQUENCE OF
ERROR-CLASS.&Type ({ErrorSet}{@errorCategory})
}
This function returns a value of type FieldHndl. If the specified field within a SEQUENCE or SET has a component relation constraint, the field handle of the referenced field with the specified index in the list of all referenced fields is returned; otherwise, NULL is returned.
Determines whether or not a referenced field identified by its index in the list of all referenced fields in a component relation constraint applied to another field identified by its field handle appears within the innermost enclosing SET or SEQUENCE.
This function returns a value of type ossBoolean. If the specified referenced field appears within the innermost SEQUENCE or SET, a value of TRUE is returned; otherwise, a value of FALSE is returned.
Determines the scope of the referenced field identified by its index in the list of all referenced fields in a component relation constraint applied to another field identified by its field handle. The scope corresponds to the number of "."(dots) specified in the AtNotation.
This function returns a value of type int. If the specified referenced field appears within the innermost SEQUENCE or SET, a value of 0 is returned. If the specified referenced field appears within a SEQUENCE or SET obtained by moving upward from the innermost textually enclosing SET or SEQUENCE by a number of levels (SET, SEQUENCE, CHOICE, SET OF, and SEQUENCE OF), a number of levels is returned.
Determines whether a component identified by its index within a SEQUENCE or SET type is a referenced component, that is, it is identified in a component relation constraint of some other field in the containing structure.
This function returns a value of type ossBoolean. If the specified field is referenced in a component relation constraint within the same containing structure, a value of TRUE is returned; otherwise, a value of FALSE is returned.
Returns the field handle of the referencing field identified by its index in the list of all referencing fields that have component relation constraints that include the field identified by its field handle as a referenced field (in the @-notation).
This function returns a value of type FieldHndl. If the specified field within a SEQUENCE or SET is referenced in one or more component relation constraint, the field handle of the referencing field with the specified index in the list of all referencing fields is returned; otherwise, NULL is returned.
Returns the type handle of the component identified by its FieldHndl within a SEQUENCE, SET, CHOICE or information object class.
This function returns a value TypeHndl. If the field handle of a component within a SEQUENCE, SET, CHOICE, or CLASS is correct, its type handle is returned; otherwise, a value of NULL is returned.
Returns the index of the information object set in the list of all information object sets defined in the input ASN.1 notation constraining the component identified by its type within a SEQUENCE, SET, CHOICE, SET OF, or SEQUENCE OF type (whose type is defined as ObjectClassFieldType). The function is similar to ossComponentInfoObjSetIndex(), in addition, it can be used for components of SET OF or SEQUENCE OF types that have table constraints.
This function returns a value of type unsigned int. If the specified field has a simple table constraint or component relation constraint, the index of the constraining information object set is returned; otherwise, a value UINT_MAX is returned.
Retrieves the next information object within an information object set constraining the field of a SET, SEQUENCE, CHOICE, SET OF, or SEQUENCE OF identified by its type handle if the input value of this field is the same as the value of a corresponding information object class field specified in this object.
Note that if the corresponding field in the information object class is not unique, there can be several information objects with the same values for this field. To retrieve all objects whose values of a specified field match the specified input value, the function should be called in the loop until no more objects are found. The last parameter should point to NULL before the first call to this function. The function is similar to ossGetInfoObjectByFieldValue(), in addition, it can be used for components of SET OF or SEQUENCE OF types that have table constraints.
This function returns an enumerator of type IAAPI_ERRTYPE. If no other error occurs, the IAAPI_NOERROR enumerator is returned and a pointer to the information object found is returned in the last parameter; otherwise, an IAAPI error code indicating the type of error encountered is returned.
Returns the type handle of the actual ASN.1 type that an open type value can carry for open types created for types with component relation constraints within SET, SEQUENCE, CHOICE, SET OF, or SEQUENCE OF types. The function is similar to ossGetTypeHandleOfActualTypeCarriedByOpenType(), in addition, it can be used for components of SET OF or SEQUENCE OF types that have table constraints.
This function returns an enumerator of type IAAPI_ERRTYPE. If the type handle retrieval is successful, the IAAPI_NOERROR enumerator is returned; otherwise, an IAAPI error code indicating the type of error encountered is returned.
Returns the field handle of the field within an information object class specified in the object class field type notation of the component identified by its type handle within a SEQUENCE, SET, CHOICE, SET OF, or SEQUENCE OF type (whose type is defined as ObjectClassFieldType). The function is similar to ossComponentInfoObjClassFieldHandle(), in addition it can be used for components of SET OF or SEQUENCE OF whose types are defined as ObjectClassFieldType.
This function returns a value of type FieldHndl. If the type of the specified field is defined with object class field type notation, the field handle of the referenced object class field is returned. For example, a field handle of the &id field is returned for the TYPE-IDENTIFIER.&id type. NULL is returned if an error occurs or if the type of the field is not an object class field type.
Returns the type handle of the information object class specified in the object class field type notation of the component identified by its type handle within a SEQUENCE, SET, CHOICE, SET OF, or SEQUENCE OF type (whose type is defined as ObjectClassFieldType). The function is similar to ossComponentInfoObjClassTypeHandle(), in addition, it can be used for components of SET OF or SEQUENCE OF types whose types are defined as ObjectClassFieldType.
This function returns a value of type TypeHndl. If the type of the specified field is defined with an object class field type notation, the type handle of the information object class specified in this notation is returned (for example, a type handle of TYPE-IDENTIFIER is returned if the type of the field is defined as TYPE-IDENTIFIER.&id); otherwise, a value of NULL is returned.
Returns the number of referenced fields (i.e. fields identified in a component relation constraint of another field identified by its type handle within a SET, SEQUENCE, CHOICE, SET OF, or SEQUENCE OF type). Referenced fields and fields with component relation constraint where they are referenced should appear within the same SET or SEQUENCE, possibly at a different level of nesting. The function is similar to ossNumberOfReferencedComponents(), in addition, it can be used for components of SET OF or SEQUENCE OF types that have component relation constraints. In most cases, a component relation constraint references only one such field.
This function returns a value of type int. If the specified field has a component relation constraint, the number of referenced fields is returned; otherwise, a value less than 1 is returned.
Returns the field handle of the referenced component identified by its index in the list of all referenced fields in a component relation constraint applied to another field identified by its type handle that appears within a SET, SEQUENCE, CHOICE, SET OF, or SEQUENCE OF type. Referenced fields and fields with component relation constraint where they are referenced should appear within the same SET or SEQUENCE, possibly at a different level of nesting. The function is similar to ossReferencedComponentFieldHandle(), in addition, it can be used for components of SET OF or SEQUENCE OF types that have component relation constraints.
This function returns a value of type FieldHndl. If the specified field has a component relation constraint, the field handle of the referenced field with the specified index in the list of all referenced fields is returned; otherwise, NULL is returned.
Determines whether or not a referenced field identified by its index in the list of all referenced fields in a component relation constraint applied to another field identified by its type handle appears within the innermost enclosing SET or SEQUENCE type. The function is similar to ossReferencedComponentIsInner(), in addition, it can be used for components of SET OF or SEQUENCE OF types that have component relation constraints.
This function returns a value of type ossBoolean. If the specified referenced field appears within the innermost SEQUENCE or SET, a value of TRUE is returned; otherwise, a value of FALSE is returned.
Determines the scope of the referenced field identified by its index in the list of all referenced fields in a component relation constraint applied to another field identified by its type handle. The scope corresponds to the number of "." specified in the AtNotation. The function is similar to ossReferencedComponentScope(), in addition, it can be used for components of SET OF or SEQUENCE OF types that have component relation constraints.
This function returns a value of type int. If the specified referenced field appears within the innermost SEQUENCE or SET, a value of 0 is returned. If the specified referenced field appears within a SEQUENCE or SET obtained by moving upward from the innermost textually enclosing SET or SEQUENCE by a number of levels (SET, SEQUENCE, CHOICE, SET OF, and SEQUENCE OF), the number of levels is returned.
The following set of functions can be used to access information about values inside value set types obtained by calling the ossGetTypeHandleCarriedByClassFieldValue() function. This function returns the type handle of the value set type stored in the value of a FixedTypeValueSetField or a VariableTypeValueSetField.
Returns the address of the value identified by its index within the value set identified by its type handle returned by the ossGetTypeHandleCarriedByClassFieldValue() for a FixedTypeValueSetField or VariableTypeValueSetField function.
Note that before using the value returned by ossGetValueFromValueSet() in calls to other IAAPI functions, you need to check whether or not the value itself or its address should be used in those calls. Call the ossValuesFromValueSetNeedPointer() function and, if it returns TRUE, pass the address of the returned value to other IAAPI functions.
This function returns an enumerator of type IAAPI_ERRTYPE and the address of an information object in the last parameter. If the value retrieval is successful, the IAAPI_NOERROR enumerator is returned and the address of an information object; otherwise, an IAAPI error code indicating the type of error encountered is returned.
Returns the number of values that appear before the extension marker in the input extensible value set identified by its type handle returned by the ossGetTypeHandleCarriedByClassFieldValue() for a FixedTypeValueSetField or VariableTypeValueSetField function.
This function returns an integer. If the input type handle is a valid type handle of a value set and no other error occurs, the number of values specified before the extension marker for extensible value sets or the total number of values contained in a non-extensible value set is returned; otherwise, a value of zero is returned.
Returns the number of values defined in the input value set identified by its type handle returned by the ossGetTypeHandleCarriedByClassFieldValue() function for a FixedTypeValueSetField or VariableTypeValueSetField.
This function returns an integer. If the input type handle is a valid type handle of a value set and no other error occurs, the number of values contained is returned; otherwise, a value of 0 is returned.
Returns TRUE if a pointer to a value extracted by a call to the ossGetValueFromValueSet() function from the value set identified by its type handle should be used in calls to other IAAPI functions.
This function returns an ossBoolean value. If values extracted from the input value set need a pointer when passing them as parameters to other IAAPI functions, TRUE is returned; otherwise, FALSE is returned.
Generates and prints the ASN.1 notation for a particular information object class in the input ASN.1 specification given its index in the list of all information object classes.
ossPrintASN1DescriptionOfCLASS() does not return a value.
Generates and prints the ASN.1 notation for a particular information object in the input ASN.1 specification given its index in the list of all information objects inside an information object set identified by its index.
ossPrintASN1DescriptionOfInfoObject() does not return a value.
Generates and prints the ASN.1 notation for a particular information object set in the input ASN.1 specification given its index in the list of all information object sets (excluding information object sets defined as values of ObjectSetFields inside information objects).
ossPrintASN1DescriptionOfInfoObjSet() does not return a value.
Prints the ASN.1 descriptions for all information object classes in the input ASN.1 specification.
world is a pointer to the global OSS environment variable.
ossPrintInfoObjClasses() does not return a value.
Generates and prints the ASN.1 notation for a particular information object in the input ASN.1 specification given its value and the type handle of the governing information object class.
ossPrintInfoObject() does not return a value.
Prints the ASN.1 descriptions for all information objects defined in the information object assignment in the input ASN.1 specification.
world is a pointer to the global OSS environment variable.
ossPrintInfoObjSets() does not return a value.
Generates and prints the ASN.1 notation for a particular information object set in the input ASN.1 specification given its value and the type handle of the governing information object class.
ossPrintInfoObject() does not return a value.
Prints the ASN.1 descriptions for all information object sets in the input ASN.1 specification (excluding information object sets defined as values of ObjectSetFields inside information objects).
world is a pointer to the global OSS environment variable.
ossPrintInfoObjSets() does not return a value.
Generates and prints the ASN.1 notation for a particular value set given its type handle returned by the ossGetTypeHandleCarriedByClassFieldValue() function for a FixedTypeValueSetField or VariableTypeValueSetField inside an information object.
ossPrintValueSet() does not return a value.
Functions for printing ASN.1 descriptions can allocate memory to keep names of referenced ASN.1 types or information object classes whose definitions can be printed later by calling the ossPrintRemainingReferencedTypes() function. If you do not intend to print definitions of referenced types or classes later and wish to avoid allocating memory for referenced names, set the IAAPI_DONT_PRINT_REFERENCED_TYPES IAAPI flag by calling ossSetIAAPIFlags() function before any printing function, for example:
ossSetIAAPIFlags(world, ossGetIAAPIFlags() | IAAPI_DONT_PRINT_REFERENCED_TYPES);
Generates and prints ASN.1 descriptions of all ASN.1 types whose names appear inside ASN.1 descriptions of PDUs, information object classes, or information objects when they were printed by calling one or more printing functions. It should be called to free memory allocated by printing functions to keep the names of referenced types. If the IAAPI_DONT_PRINT_REFERENCED_TYPES IAAPI flag is set before calling this function, any memory allocated by previous calls to printing functions is freed. However, printing of ASN.1 referenced type descriptions or information object classes is performed.
world is a pointer to the global OSS environment variable.
ossPrintRemainingReferencedTypes() does not return a value.
NOTE: The IAAPI functions listed in this section will not work properly if the input ASN.1 specification was compiled with the −noConstraints option. To verify this, use the ossConstrainWasSpecified() function at runtime.
The following set of functions was introduced in version 8.2 of the IAAPI library when support for ISO 8601 time types was added. The time types (TIME, DATE, TIME-OF-DAY, DATE-TIME, DURATION) can have complex constraints including PropertySettingsConstraint, TimePointRange, DurationRange, RecurrenceRange, and SingleValue according to ITU-T Rec. X.680:2021 | ISO/IEC 8824-1:2021. The functions can be used only to access PER-visible property settings information that all abstract values of the specified time type have. Such time types must be constrained so that all their abstract values have PER encodings that are not encodings of the MIXED-ENCODING type defined in ITU-T Rec. X.691:2021 | ISO/IEC 8825-2:2021. Note that even if constraints include only SingleValue or TimePointRange constraints, the functions return the settings of the corresponding time properties - not the actual values.
The following flags are returned by the functions and can be used to identify the PER-visible settings of time properties that all abstract values of the specified time type have:
| Flag | Property | Description |
|---|---|---|
IAAPI_CENTURY |
Date | All abstract values include a date identification representing a century. |
IAAPI_YEAR |
Date | All abstract values include a date identification with a year component. |
IAAPI_MONTH |
Date | All abstract values include a date identification with a month component. |
IAAPI_WEEK |
Date | All abstract values include a date identification with a week component. |
IAAPI_DAY |
Date | All abstract values include a date identification with a day component. |
IAAPI_YEAR_BASIC |
Year | All abstract values include a date identification with a year in the range of 1582 to 9999 or a century in the range of 15 to 99. |
IAAPI_YEAR_PROLEPTIC |
Year | All abstract values include a date identification with a year in the range of 0000 to 1581 or a century in the range of 00 to 14. |
IAAPI_YEAR_NEGATIVE |
Year | All abstract values include a date identification with a year in the range of -9999 to -0001 or a century in the range of -99 to -01. |
IAAPI_YEAR_LARGE |
Year | All abstract values include a date identification with years whose decimal representation requires 5, 6, 7, etc. digits (or 3, 4, 5, ... for centuries). |
IAAPI_TIME_FRACTION |
Time | All abstract values include a time-of-day identification with a fractional component. |
IAAPI_HOURS |
Time | All abstract values include a time-of-day identification with hours. |
IAAPI_MINUTES |
Time | All abstract values include a time-of-day identification with minutes. |
IAAPI_SECONDS |
Time | All abstract values include a time-of-day identification with seconds. |
IAAPI_TIME_LOCAL |
Local-or-UTC | All abstract values include a time-of-day identification that specifies local time. |
IAAPI_TIME_UTC |
Local-or-UTC | All abstract values include a time-of-day identification that specifies UTC. |
IAAPI_TIME_DIFF |
Local-or-UTC | All abstract values include a time-of-day identification that specifies local time and the time difference from UTC. |
IAAPI_DURATION |
Interval-type | All abstract values include identification of an interval or recurring interval that specifies a duration, duration, and end point, or start point and duration. |
IAAPI_START_POINT |
Interval-type | All abstract values include identification of an interval or recurring interval that specifies a start and end point or start point and duration. |
IAAPI_END_POINT |
Interval-type | All abstract values include identification of an interval or recurring interval that specifies a start and end point or duration and end point. |
IAAPI_REC_INTERVAL |
Basic | All abstract values include identification of a recurring interval. |
IAAPI_REC_UNLIMITED |
Recurrence | All abstract values include identification of a recurring interval with an unlimited number of recurrence digits. |
Reports whether or not all abstract values of a specified time type include a date identification and have settings for the date properties (Date and Year) that identify the same PER encoding type that is not an encoding of the MIXED-ENCODING type, as defined in ITU-T Rec. X.691:2021 | ISO/IEC 8825-2:2021.
Note that the actual number of digits in large years is not PER-visible. The function returns the minimum possible number of digits.
ossDatePropertySettingsForPER() returns an unsigned int. If the specified type is constrained to have the same PER encoding type for all abstract values that are not encodings of the MIXED-ENCODING type, and all its abstract values include a date identification, then one or more flags from the previous table for the Date and Year properties are returned; otherwise, a value of 0 is returned. Note that dates with basic and proleptic years, as well as dates with negative and large years, have the same non-mixed PER encoding type. The function can return the IAAPI_YEAR_BASIC and IAAPI_YEAR_PROLEPTIC flags as well as IAAPI_YEAR_NEGATIVE and IAAPI_YEAR_LARGE, if both types of years are permitted by the constraints.
Functions that retrieve combined property settings for PER
Reports whether or not all abstract values of a specified time type include identification of an interval or recurring interval and have Interval-type property settings that identify the same PER encoding kind that is not an encoding of the MIXED-ENCODING type, as defined in ITU-T Rec. X.691:2021 | ISO/IEC 8825-2:2021.
where
Note that the actual number of recurrence digits is not PER-visible. The function returns the minimum possible number of digits if the number of recurrence digits has a minimum limit. If all abstract values of the recurring interval are constrained to have Unlimited number of recurrences, the flag IAAPI_REC_UNLIMITED is returned by the function, along with other flags.
ossIntervalPropertySettingsForPER() returns an unsigned int. If the specified type is constrained to have the same PER encoding type for all abstract values that are not encodings of the MIXED-ENCODING type, and all its abstract values include identification of an interval or recurring interval, then one or more flags from the previous table for Interval-type, Basic, and Recurrence properties are returned; otherwise, a value of 0 is returned. The flag IAAPI_REC_INTERVAL is returned if all abstract values of the specified type are recurring intervals.
Functions that retrieve combined property settings for PER
Reports whether or not all abstract values of a specified time type have interval, date, or time-of-day property settings that identify the same PER encoding type that is not an encoding of the MIXED-ENCODING type, as defined in ITU-T Rec. X.691:2021 | ISO/IEC 8825-2:2021.
ossTimeHasNonMixedPEREncoding() returns an ossBoolean. If the specified type is constrained to have the same PER encoding type for all abstract values that are not encodings of the MIXED-ENCODING type, the value of TRUE is returned; otherwise, a value of FALSE is returned. Note that if the function returns TRUE one of these functions: ossTimeOfDayIntervalPropertySettingsForPER(), ossIntervalPropertySettingsForPER(), ossDatePropertySettingsForPER() can be used to determine whether or not all abstract values include the identification of an interval, recurring interval, date, or time-of-day, or some combination of those.
Reports whether or not all abstract values of a specified time type include a time-of-day identification and have settings for the time-of-day properties (Time and Year) that identify the same PER encoding type that is not an encoding of the MIXED-ENCODING type, as defined in ITU-T Rec. X.691:2021 | ISO/IEC 8825-2:2021.
where
ossTimeOfDayPropertySettingsForPER() returns an unsigned int. If the specified type is constrained to have the same PER encoding type for all abstract values that are not encodings of the MIXED-ENCODING type and all its abstract values include a time-of-day identification, one or more flags from the previous table for the Time and Local-or-UTC properties are returned; otherwise, a value of 0 is returned.
Functions that retrieve combined property settings for PER
Returns the URI of the E-XER namespace with the specified index from the list of all E-XER namespaces found in the input specification.
ossNamespaceURI() returns a pointer. If the specified index is correct, the URI of the corresponding E-XER namespace is returned; otherwise, a NULL value is returned.
Returns the number of E-XER namespaces found in the input specification.
world is a pointer to the global OSS environment variable.
ossNumberOfNamespaces() returns an integer. If no error occurs, the number of E-XER namespaces (that can include the predefined XSD namespace and the "urn:oid:2.1.5.2.0.1" namespace) is returned; otherwise, a value of zero is returned.
Accepts the input buffer with BER-based encoded messages, checks for CDR headers in the supported formats, and returns certain CDR header properties.
The following CDR file formats are supported:
typedef struct OssCDRHeaderData {
long fileSize;
int fileHeaderLength;
int recordHeaderLength;
int pduCount;
char recordHeaderId[3];
} OssCDRHeaderData;
ossDetectCDRHeaders() returns an ossBoolean value. If one of the supported CDR file formats is detected, a value of TRUE is returned and the OssCDRHeaderData fields are initialized with data extracted from the detected headers; otherwise, a value of FALSE is returned.
Converts an ASN.1 encoding to Comma-Separated-Value (CSV) format.
The ossASN2CSV() function returns the IAAPI_NOERROR enumerator if no error occurs. If world is NULL, the function returns IAAPI_BADARG.
The ossASN2CSV() function calls ossDecode() to decode the encoded value to its internal decoded format, then calls ossConvertPduValueToCsv() to covert the decoded internal format to its Comma-Separated-Value (CSV) format. Refer to ossDecode() and ossConvertPduValueToCsv() for more details about the conversion process.
Is used as follows:
world is a pointer to the global OSS environment variable.
Converts the comma-separated value (CSV) of an entire PDU (simple or structured) into decoded internal format using its PDU number.
The memory allocated for this structure can be freed by a call to ossFreeDecodedValue().
By default, the ossConvertCsvToPduValue() function uses the CSV settings previously set when ossSetCsvSetting() or other IAAPI CSV conversion function was called.
When values for the OSS_CSV_FORMAT and OSS_CSV_HEADER settings are not previously initialized, ossConvertCsvToPduValue() attempts to automatically determine the CSV format. To enable automatic detection, make sure there are no prior calls to other IAAPI CSV conversion functions or call ossClearCsvSettings() to clear all settings before calling ossConvertCsvToPduValue(). If you know the format of the input CSV call ossSetCsvSetting() to set the corresponding values; ossConvertCsvToPdu/TypeValue() will then skip the extra step needed to determine the CSV structure.
NOTE: In some cases, ossConvertCsvToPduValue() could fail to detect the CSV structure. Examine the input CSV and call ossSetCsvSetting() to set values for the following CSV settings: OSS_CSV_FORMAT, OSS_CSV_HEADER, OSS_CSV_FORMAT_SEPARATOR, and OSS_CSV_HEADER_SEPARATOR (when the OSS_CSV_HEADER setting has an OSS_CHR_ABSREF_NAME value).
NOTE: Automatic detection is not available for OCTET STRING formats, except for ASCII. When OCTET STRING values do not have the OSS.PrintFunctionName directive and are in Binary-Coded Decimal (BCD), Telephony Binary-Coded Decimal (TBCD), or other supported formats, call ossSetCsvSetting() to instruct ossConvertCsvToPduValue() to convert the input value from those formats to the internal OCTET STRING format. For example, to convert from TBCD format, add the following call: ossSetCsvSetting(world, OSS_CSV_OCTET_STRING, OSS_COS_TBCD).
On completion, ossConvertCsvToPduValue() preserves the detected CSV settings for upcoming calls. Call ossGetCsvSetting() to obtain those settings. To process multiple CSVs with different CSV settings, call ossClearCsvSettings() and ossSetCsvSetting() before calling ossConvertCsvToPduValue().
The ossConvertCsvToPduValue() handles one CSV at a time. An input buffer containing multiple concatenated CSVs and a CSV header as the first line must be fed to the function multiple times. The address of the CSV header, when present, is preserved and used on subsequent calls until ossClearCsvSettings() or ossSetDefaultCsvSettings() is called, which clears the preserved CSV header address.
The following example shows how to process multiple concatenated CSVs and assumes that all messages have the same PDU number:
OssBuf csvBuf;
...
/* Add the code to place CSVs in csvBuf.value and initialize csvBuf.length */
...
ossClearCsvSettings(world);
while(csvBuf.length > 0)
{
void decodedValue = NULL;
long bytesRead;
if (ossConvertCsvToPduValue(world, pduNum, &csvBuf,(void**)&decodedValue))
{
ossPrint(world, "Error: %s\n", ossGetIaapiErrMsg(world));
break;
}
/* Add the code to process the decoded value. */
ossPrintPDU(world, pduNum, decodedValue);
...
ossFreePDU(world, pduNum, decodedValue);
bytesRead = ossGetBytesReadByDecoder(world);
csvBuf.length -= bytesRead;
if (bytesRead > 0)
csvBuf.value += bytesRead;
else
break;
}
ossConvertCsvToPduValue() returns an IAAPI_ERRTYPE type enumerator. If the CSV value is compatible with the specified PDU and no other errors occur, the IAAPI_NOERROR enumerator is returned; otherwise, an IAAPI error code indicating the type of error that occurred is returned.
Converts the Comma-Separated Value (CSV) of an entire ASN.1 type (simple or structured) into decoded internal format using its type handle.
The memory allocated for this structure can be freed by a call to ossFreeDecodedValue().
ossConvertCsvToTypeValue() returns an IAAPI_ERRTYPE type enumerator. If the CSV is compatible with the specified PDU and no other errors occur, the IAAPI_NOERROR enumerator is returned; otherwise, an IAAPI error code indicating the type of error that occurred is returned.
Converts a decoded internal format value for an entire PDU (simple or structured) into Comma-Separated Value (CSV) format using the PDU number of the data type to be converted.
When the length and value fields of the output OssBuf (csvValue) variable are initialized to NULL and zero, respectively, the function automatically allocates the space needed for the output buffer. However, if you choose to pre-allocate a memory buffer for the finished data, set the value field of OssBuf to reference the start of the buffer and set the length field to the length of the allocated buffer in bytes. Be sure to allocate additional space when the output CSV includes the CSV header.
On a successful return, the passed OssBuf value field points to the converted data and the OssBuf length field contains the length of the converted data in bytes.
Use the ossSetCsvSetting() function to control the format of the output CSV. For example, you can change the column separator and suppress creation of the CSV header. Following are the default settings used to create CSVs:
ossSetCsvSetting(world, OSS_CSV_MAX_SET_OF_SEQ_OF_COMPONENTS, maxNumber);
If the CSV settings are not set when ossConvertPduValueToCsv() is called, the function initializes the CSV settings to their default values. You can issue a call to ossGetCsvSetting() to obtain these values. Other CSV conversion IAAPI functions can change the CSV settings. To ensure that the desired settings are used to create CSVs, call ossClearCsvSettings() and then use ossSetCsvSetting() to specify the desired CSV settings before calling ossConvertPduValueToCsv().
NOTE: SET OF and SEQUENCE OF type values with multiple components are mapped into several CSV records where only one component differs and the rest are repeated. SET OF and SEQUENCE OF types can be nested inside these types. By default, to avoid significant performance degradation, IAAPI supports an additional CSV for up to 50 components inside each type. To change the maximum number of components for each SET OF and SEQUENCE OF type value, call ossSetCsvSetting() with a value greater than 1 for the OSS_CSV_MAX_SET_OF_SEQ_OF_COMPONENTS setting.
NOTE: Starting with ASN.1/C version 11.1, the ossSetCsvSetting() supports the OSS_CSV_ALL_MAX setting. This setting is used to specify the maximum number of all CSVs to create for a top-level PDU type value that can include multiple components for multiple SET OF and SEQUENCE OF type values for which extra CSVs are created.
When converting multiple decoded values of a PDU to multiple CSVs with a single CSV header, suppress the creation of extra CSV headers before each CSV by specifying the OSS_MORE_CSV flag after the first call to ossConvertPduValueToCsv().
The following example shows how to create multiple concatenated CSVs in the external buffer. Note that the example assumes all messages have the same PDU number.
OssBuf csvBuf;
int cnt = 0;
...
ossClearCsvSettings(world);
while(1)
{
void decodedValue = NULL;
/* Add the code to obtain and initialize the decoded value. */
if (!decodedValue)
break;
csvBuf.value = NULL;
csvBuf.length = 0;
if (ossConvertPduValueToCsv(world, pduNum, decodedValue, &csvBuf))
{
ossPrint(world, "Error: %s\n", ossGetIaapiErrMsg(world));
break;
}
else if (!(*csvBuf.value))
{
ossPrint(world, "CSV is empty");
continue;
}
/* Add the code to append csvBuf.value to some external buffer. */
/* Set the flag to avoid creating CSV header for sequential CSVs. */
if (!cnt)
ossSetCsvSetting(world, OSS_CSV_FLAGS,
ossGetCsvSetting(world, OSS_CSV_FLAGS) | OSS_MORE_CSV);
else
cnt++;
/* Free allocated CSV value buffer. */
if (csvBuf.value)
ossFreeBuf(world, csvBuf.value);
}
NOTE: When using the file memory manager, csvValue->value can be marked as an OSS_FILE object (e.g., using the ossMarkObj() function). If so marked, csvValue->length is interpreted as the offset in the input file where the next output CSV is written.
The following example shows how to create multiple concatenated CSVs in the file. Note that the example assumes all messages have the same PDU number.
OssBuf csvBuf;
int cnt = 0;
long offset = 0;
...
ossClearCsvSettings(world);
/* Mark the output buffer as OSS_FILE. */
csvBuf.value = (unsigned char *)ossMarkObj(world, OSS_FILE, "outfile.csv");
while(1)
{
void decodedValue = NULL;
/* Add the code to obtain and initialize the current decoded value. */
if (!decodedValue)
break;
csvBuf.length = offset;
if (ossConvertPduValueToCsv(world, pduNum, decodedValue, &csvBuf))
{
ossPrint(world, "Error: %s\n", ossGetIaapiErrMsg(world));
break;
}
else if (!(*csvBuf.value))
{
ossPrint(world, "CSV is empty");
continue;
}
/* Advance the offset in the file starting from which the next CSV
will be written to. */
offset += ossBuf.length;
/* Set the flag to avoid creating extra CSV header for sequential CSVs. */
if (!cnt)
ossSetCsvSetting(world, OSS_CSV_FLAGS,
ossGetCsvSetting(world, OSS_CSV_FLAGS) | OSS_MORE_CSV);
else
cnt++;
}
You can create partial CSVs by specifying the minimum or maximum nesting level inside a PDU type, from which simple type values in the output CSV are included. In most cases, such partial CSVs cannot be decoded because, once some values and separators are skipped, the CSV structure no longer corresponds to the PDU type structure. Note that if the specified "slice" of the PDU type between the minimum and maximum nesting levels does not include at least one simple type value, the resulting CSV could be empty.
| ASN.1 | Application | Output CSV |
|---|---|---|
Mod DEFINITIONS AUTOMATIC TAGS ::= BEGIN
Seq ::= SEQUENCE {
a SEQUENCE { b BOOLEAN },
c INTEGER,
d IA5String
}
value Seq ::= {
a { b TRUE},
c 10,
d "Test"
}
END
|
ossSetDefaultCsvSettings(world);
ossSetCsvSetting(world, OSS_CSV_MAX_LEVEL, 1);
if (ossConvertPduValueToCsv(world, pduNum, decodedValue, &csvBuf))
{
ossPrint(world, "Error: %s\n", ossGetIaapiErrMsg(world));
break;
}
else if (!(*csvBuf.value))
{
ossPrint(world, "CSV is empty");
}
|
c,d 10,"Test" |
Mod DEFINITIONS AUTOMATIC TAGS ::= BEGIN
Choice ::= [12] CHOICE {
a SEQUENCE { b BOOLEAN },
c SEQUENCE { d INTEGER }
}
value Choice ::= c : { d 10 }
END
|
ossSetDefaultCsvSettings(world);
ossSetCsvSetting(world, OSS_CSV_MIN_LEVEL, 1);
if (ossConvertPduValueToCsv(world, pduNum, decodedValue, &csvBuf))
{
ossPrint(world, "Error: %s\n", ossGetIaapiErrMsg(world));
break;
}
else if (!(*csvBuf.value))
{
ossPrint(world, "CSV is empty");
}
|
c_d 10 |
The ossConvertPduValueToCsv() returns an IAAPI_ERRTYPE enumerator. If no error occurs, the IAAPI_NOERROR enumerator is returned; otherwise, an IAAPI error code indicating the error is returned.
The allocated CSV value that is returned can be freed using the ossFreeDisplayString() or ossFreeBuf() function.
Converts the decoded internal format value of an entire ASN.1 type (simple or structured) into Comma-Separated Value (CSV) format. The type handle of the data type to convert must be specified.
If you initialize the length and value fields of the output OssBuf (csvValue) variable to NULL and zero, respectively, the function will automatically allocate the space needed for the output buffer. Alternatively, if you pre-allocate a memory buffer for the finished data, set the value field of OssBuf to reference the beginning of the buffer and the length field to the length of the allocated buffer in bytes. Make sure to allocate additional space when the output CSV includes the CSV header.
With a successful return, the value field of the passed OssBuf variable will point to the converted data. In addition, the length field of the OssBuf variable will contain the length of the converted data in bytes.
The ossConvertTypeValueToCsv() function works the same as ossConvertPduValueToCsv().
ossConvertTypeValueToCsv() returns an IAAPI_ERRTYPE enumerator. If no error occurs, the IAAPI_NOERROR enumerator is returned; otherwise, an IAAPI error code indicating the error is returned.
The allocated CSV value that is returned can be freed using the ossFreeDisplayString() or ossFreeBuf() function.
Converts a Comma-Separated-Value (CSV) to an ASN.1 encoding.
The ossCSV2ASN() function returns the IAAPI_NOERROR enumerator if no error occurs. If world is NULL, the function returns IAAPI_BADARG.
The ossCSV2ASN() function calls ossConvertCsvToPduValue() to convert the CSV to the internal decoded format of the type corresponding to the PDU number, then calls ossEncode() to covert the decoded internal format an ASN.1 encoding. Refer to ossConvertCsvToPduValue() and ossEncode() for more details about the conversion process.
Returns the CSV setting value that was set by ossSetCsvSetting(), ossSetDefaultCsvSettings(), ossClearCsvSettings(), or the IAAPI functions that convert decoded values to and from CSV.
The ossGetCsvSetting() function returns an integer value that varies depending on the CSV setting identifier.
Call the ossGetNumberOfExtraCsvs() function after ossConvertPduValueToCsv() or ossConvertTypeValueToCsv() to obtain the number of additional CSVs created for extra SET OF and SEQUENCE OF components.
world is a pointer to the global OSS environment variable.
Note that calls to the ossClearCsvSettings() and ossSetDefaultSettings() functions set the number of extra CSVs preserved by the ossConvertPduValueToCsv() or ossConvertTypeValueToCsv() functions to 0.
This function returns an integer that indicates the number of additional CSVs or 0.
Call the ossGetNumberOfSkippedEmptyCsvs() function after calling ossSetCsvSetting() that contains the OSS_SKIP_EMPTY_CSV flag set for the OSS_CSV_FLAGS setting or after calling ossConvertPduValueToCsv() or ossConvertTypeValueToCsv() to obtain the number of skipped CSVs that include empty values for all simple types.
world is a pointer to the global OSS environment variable.
Note that calls to the ossClearCsvSettings() and ossSetDefaultSettings() functions reset all flags, including OSS_SKIP_EMPTY_CSV, for the OSS_CSV_FLAGS setting.
This function returns an integer that indicates the number of skipped CSVs with empty values for all simple types.
Initializes all CSV settings to their default values. It also clears the internal fields that hold the CSV header address and the number of additional CSVs that were created by calls to the ossConvertPduValueToCsv() or ossConvertTypeValueToCsv() function for multiple components inside SET OF or SEQUENCE OF values. Note that when converting concatenated CSVs into decoded values with multiple calls to the ossConvertCsvToPduValue() or ossConvertCsvToTypeValue() function, the CSV header address is used.
world is a pointer to the global OSS environment variable.
The ossSetDefaultCsvSettings() function sets the following defaults:
Controls the behavior of the IAAPI functions for the CSV conversion.
To change the default format of the entire CSV output or just the values of certain ASN.1 types, call the ossSetCsvSetting() function before you call the ossConvertPduValueToCsv() or ossConvertTypeValueToCsv() function. To specify the input CSV settings, thus allowing the function to skip the additional step of determining the CSV format, call the ossSetCsvSetting() function before you call the ossConvertCsvToPduValue() or ossConvertCsvToTypeValue() function.
The enumerators that identify the CSV settings are included in the OSS_CSV_SETTINGS type. All types are defined in the ossiaapi.h header file.
enum OSS_CSV_SETTINGS {
OSS_CSV_NONE = 0,
OSS_CSV_FORMAT = 1,
OSS_CSV_HEADER = 2,
OSS_CSV_FORMAT_SEPARATOR = 3,
OSS_CSV_HEADER_SEPARATOR = 4,
OSS_CSV_MIN_LEVEL = 5,
OSS_CSV_MAX_LEVEL = 6,
OSS_CSV_FLAGS = 7,
OSS_CSV_MAX_SET_OF_SEQ_OF_COMPONENTS = 8,
OSS_CSV_BOOLEAN = 9,
OSS_CSV_ENUMERATED = 10,
OSS_CSV_OCTET_STRING = 11,
OSS_CSV_OPEN_TYPE = 12,
OSS_CSV_TIME = 13,
OSS_CSV_ALL_MAX = 14
};
The following table lists the values that are returned for each enumerator:
| Enumerator | Corresponding Value |
|---|---|
OSS_CSV_NONE |
0 (unknown CSV setting). |
OSS_CSV_FORMAT |
OSS_CSV_FORMAT_VALUE type enumerator. |
OSS_CSV_HEADER |
OSS_CSV_HEADER_VALUE type enumerator. |
OSS_CSV_FORMAT_SEPARATOR |
',', ';', ':', or '=' character used as a column separator. |
OSS_CSV_HEADER_SEPARATOR |
'-', '_', '.', '/', or '\\' character used as a header name separator. |
OSS_CSV_MIN_LEVEL |
Unsigned integer used as the minimum nesting level inside a PDU type and as a starting point to include simple type values in the output CSV. For the topmost SET, SEQUENCE, or CHOICE types, the deepest level is 0. |
OSS_CSV_MAX_LEVEL |
Unsigned integer used as the maximum nesting level inside a PDU type, starting from which values of simple types should NOT be included in the output CSV. |
OSS_CSV_FLAGS |
Union of one or more of the following flags:OSS_CSV_SPACES_AROUND_SEP OSS_CSV_HEADER_FIRST_WITH_PDU_NAME OSS_CSV_TEXT_FORMAT OSS_MORE_CSV OSS_CSV_NO_CHECK_ON_RECURSION OSS_CSV_HEADER_ALL_WITH_PDU_NAME OSS_CSV_HEADER_STAR_FOR_SOF_COMPONENTS OSS_CSV_HEADER_INDEX_FOR_UNNAMED |
OSS_CSV_MAX_SET_OF_SEQ_OF_COMPONENTS |
Unsigned integer used as the maximum number of components for each SET OF or SEQUENCE OF value for which an extra CSV should be created. The default value is 50. The total number of additional CSVs for all SET OF and SEQUENCE OF types is limited to the maximum between the user-specified number and 50, multiplied by 50. |
OSS_CSV_BOOLEAN |
OSS_CSV_BOOLEAN_VALUE type enumerator. |
OSS_CSV_ENUMERATED |
OSS_CSV_ENUMERATED_VALUE type enumerator. |
OSS_CSV_OCTET_STRING |
OSS_CSV_OCTET_STRING_VALUE type enumerator. |
OSS_CSV_OPEN_TYPE |
OSS_CSV_OPEN_TYPE_VALUE type enumerator |
OSS_CSV_TIME |
OSS_CSV_TIME_VALUE type enumerator. |
OSS_CSV_ALL_MAX |
Unsigned integer greater than 1 used as a limit applied to the total number of CSVs to be created for a top-level PDU value. The default value is the maximum between the user-specified number used as a limit that is applied to the number of CSVs per each SET OF and SEQUENCE OF type value and 50, multipled by 50. |
The values for the OSS_CSV_FORMAT setting are included in the OSS_CSV_FORMAT_VALUE type:
enum OSS_CSV_FORMAT_VALUE {
OSS_CFT_UNKNOWN = 0,
OSS_CFT_ROW = 0x00000001,
OSS_CFT_COLUMN = 0x00000002
};
The values for the OSS_CSV_HEADER setting are included in the OSS_CSV_HEADER_VALUE type:
enum OSS_CSV_HEADER_VALUE {
OSS_CHR_UNKNOWN = 0,
OSS_CHR_ABSENT = 0x00000004,
OSS_CHR_SINGLE_NAME = 0x00000008,
OSS_CHR_ABREF_NAME = 0x00000010
};
The values for the OSS_CSV_BOOLEAN setting are included in the OSS_CSV_BOOLEAN_VALUE type:
enum OSS_CSV_BOOLEAN_VALUE {
OSS_CBL_FALSE_TRUE = 0,
OSS_CBL_0_1 = 0x00000020,
OSS_CBL_false_true = 0x00000040
};
The values for the OSS_CSV_ENUMERATED setting are included in the OSS_CSV_ENUMERATED_VALUE type:
enum OSS_CSV_ENUMERATED_VALUE {
OSS_CEN_ID = 0,
OSS_CEN_NUMBER = 0x00000080
};
The values for the OSS_CSV_OCTET_STRING setting are included in the OSS_CSV_OCTET_STRING_VALUE type:
enum OSS_CSV_OCTET_STRING_VALUE {
OSS_COS_HEX = 0,
OSS_COS_ASCII = 0x00000100,
OSS_COS_BCD = 0x00000200,
OSS_COS_TBCD = 0x00000400,
OSS_COS_IP_ADDRESS = 0x00000800,
OSS_COS_TIME_STAMP = 0x00001000,
OSS_COS_TIME_STAMP_WITH_DASHES = 0x00002000,
OSS_COS_TIME_STAMP_WITH_SLASHES = 0x00004000
};
The values for the OSS_CSV_OPEN_TYPE setting are included in the OSS_CSV_OPEN_TYPE_VALUE type:
enum OSS_CSV_OPEN_TYPE_VALUE {
OSS_COT_DECODED = 0,
OSS_COT_ENCODED = 0x00008000
};
The values for the OSS_CSV_TIME setting are included in the OSS_CSV_TIME_VALUE type:
enum OSS_CSV_TIME_VALUE {
OSS_CTM_ASN1 = 0,
OSS_CTM_DATE_WITH_DASHES = 0x00010000,
OSS_CTM_DATE_WITH_SLASHES = 0x00020000
};
The following table lists the value names and their descriptions:
| Value Name | Description |
|---|---|
OSS_CFT_UNKNOWN |
The CSV format is unknown. |
OSS_CFT_ROW |
The input or output CSV is in row format. This is the default value. |
OSS_CFT_COLUMN |
The input or output CSV is in column format. |
| Value Name | Description |
|---|---|
OSS_CHR_UNKNOWN |
The presence and structure of the CSV header is unknown. |
OSS_CHR_ABSENT |
The CSV header is absent. |
OSS_CHR_SINGLE_NAME |
The CSV header is present and includes single field names for the innermost simple types. |
OSS_CHR_ABSREF_NAME |
The full CSV header is present and includes absolute references for all fields. Special PDU names or numbers are inside parentheses for open type values. This is the default value. |
OSS_CHR_ABREF_EXTENDED |
The full CSV header (OSS_CHR_ABSREF_NAME) is extended as follows:
|
| Value Name | Description |
|---|---|
OSS_CBL_FALSE_TRUE |
FALSE and TRUE are used as BOOLEAN type values. This is the default. |
OSS_CBL_0_1 |
0 and 1 are used as BOOLEAN type values. |
OSS_CBL_false_true |
false and true are used as BOOLEAN type values. |
| Value Name | Description |
|---|---|
OSS_CEN_ID |
Identifiers are used as values for ENUMERATED types. |
OSS_CEN_NUMBER |
Integer values corresponding to identifiers are used for ENUMERATED types. |
| Value Name | Description |
|---|---|
OSS_COS_HEX |
OCTET STRING type values (that do not have the OSS.PrintFunctionName directive with an OSS conversion function name) have the xmlhstring format. |
OSS_COS_ASCII |
Converts OCTET STRING values (that do not have OSS.PrintFunctionName directives with an OSS conversion function name) from ASCII when decoding input CSVs and into ASCII when creating output CSVs. |
OSS_COS_BCD |
Converts OCTET STRING values (that do not have the OSS.PrintFunctionName directive with an OSS conversion function name) to or from BCD. |
OSS_COS_TBCD |
Converts OCTET STRING values (that do not have the OSS.PrintFunctionName directive with an OSS conversion function name) to or from TBCD. |
OSS_COS_IP_ADDRESS |
Converts OCTET STRING values (that do not have the OSS.PrintFunctionName directive with an OSS conversion function name) to or from IP address. |
OSS_COS_TIME_STAMP |
Converts OCTET STRING values (that do not have the OSS.PrintFunctionName directive with an OSS conversion function name) to or from the ASN.1 time stamp format. |
OSS_COS_TIME_STAMP_WITH_DASHES |
Converts OCTET STRING values (that do not have the OSS.PrintFunctionName directive with an OSS conversion function name) to or from the following time stamp format: YYYY-MM-DD HH:MM:SS. For example, 2007-11-07 11:36:49. |
OSS_COS_TIME_STAMP_WITH_SLASHES |
Converts OCTET STRING values (that do not have the OSS.PrintFunctionName directive with an OSS conversion function name) to or from the following time stamp format: MM/DD/YY HH:MM:SS. For example, 06/01/00 11:36:49. |
| Value Name | Description |
|---|---|
OSS_COT_DECODED |
Automatically converts nested open type values to and from CSV. The full CSV header must be present with special PDU names or numbers inside parentheses for open type values. |
OSS_COT_ENCODED |
Indicates that open type values will not be automatically decoded. If the XER encoding rules are available, open type values are printed in XML. Otherwise, the first available encoding rules are used to handle open type values either in XML or in hexadecimal format (for binary encoding rules). |
| Value Name | Description |
|---|---|
OSS_CTM_ASN1 |
The ASN.1 value notation is used for GeneralizedTime values and OCTET STRINGs that have the OSS.PrintFunctionName directive with the ossPrintOctetAsTimeStamp parameter. |
OSS_CTM_DATE_WITH_DASHES |
Converts GeneralizedTime values and OCTET STRINGs that have the OSS.PrintFunctionName directive with the ossPrintOctetAsTimeStamp parameter to or from the following time stamp format: YYYY-MM-DD HH:MM:SS. |
OSS_CTM_DATE_WITH_SLASHES |
Converts GeneralizedTime values and OCTET STRINGs that have the OSS.PrintFunctionName directive with the ossPrintOctetAsTimeStamp parameter to or from the following time stamp format: MM/DD/YY HH:MM:SS. |
| Value Name | Description |
|---|---|
OSS_CSV_SPACES_AROUND_SEP |
Indicates that column separators can have surrounding spaces in the input CSV. Also, when converting to CSV, an extra space character is added before and after the column separator. OSS_CSV_HEADER_FIRST_WITH_PDU_NAME The header name in the first column has the PDU name prefix in the input CSV or the prefix will be added when a CSV is created. |
OSS_CSV_TEXT_FORMAT |
Indicates that the input or output CSV is a null-terminated string in which, when present, Unicode characters are represented as UTF-8 encodings in text format using \x##, a special C-style character sequence. If you know that CSVs in your application will never include Unicode characters, setting this flag could improve the performance of the CSV conversion. |
OSS_MORE_CSV |
Suppresses additional CSV header creation after the first call to ossConvertPduValueToCsv() when converting multiple decoded values from the same PDU to multiple CSVs. |
OSS_CSV_NO_CHECK_ON_RECURSION |
Set this flag to skip checking on recursive type definitions when you already know that the input PDU does not include such definitions. If you know that the PDU type in your application will never include recursive definitions, setting this flag could improve the performance of the CSV conversion. |
OSS_CSV_HEADER_FIRST_WITH_PDU_NAME |
Indicates that the name in the first column is prefixed with a PDU name. |
OSS_CSV_HEADER_ALL_WITH_PDU_NAME |
Indicates that all columns are prefixed with the PDU name. |
OSS_CSV_HEADER_STAR_FOR_SOF_COMPONENTS |
Indicates that the * token is used for unnamed SET OF and SEQUENCE OF components. |
OSS_CSV_HEADER_INDEX_FOR_UNNAMED |
Indicates that the component index, which starts with 1, is used for unnamed SET, SEQUENCE, and CHOICE components. When the OSS_CSV_HEADER_STAR_FOR_SOF_COMPONENTS flag is not set, the component index is used for unnamed SET OF and SEQUENCE OF components. |
OSS_CSV_WITH_UTF8_IN_HEX |
Can be set by IAAPI functions to indicate that the output CSV contains UTF-8 characters in the \\x format. |
OSS_CSV_IGNORE_EXTRA_BYTES |
Indicates that extra undecoded bytes at the end of the CSV line can be skipped without an error. |
OSS_CSV_NO_NEW_LINE |
Can be set by IAAPI functions to indicate that a new line was not encountered after a successful decoding of the input CSV. When the OSS_CSV_IGNORE_EXTRA_BYTES flag is not set, it indicates that the new line was not skipped. |
OSS_SKIP_EMPTY_CSV |
Indicates that CSVs that include only column separators and spaces, that is CSVs with empty values for all nested simple types, are skipped. |
OSS_EMPTY_OCTSTR_IF_CONVERSION_FAILS |
Indicates that values of OCTET STRING types marked with OSS.PrintFunctionName directives that cannot be converted to the specified format are printed as empty strings in the output CSV. |
OSS_CSV_HEADER_EXTENDED |
OSS_CSV_HEADER_ALL_WITH_PDU_NAME | OSS_CSV_HEADER_STAR_FOR_SOF_COMPONENTS | OSS_CSV_HEADER_INDEX_FOR_UNNAMED |
| ASN.1 | Application | Output CSV |
|---|---|---|
PersonnelRecord ::= SEQUENCE {
name PrintableString,
number INTEGER OPTIONAL,
status BOOLEAN,
children SEQUENCE OF ChildInformation
}
ChildInformation ::= SET {
name PrintableString,
gender ENUMERATED {girl(0), boy(1)},
time GeneralizedTime OPTIONAL
}
value PersonnelRecord ::= {
name "Nancy",
number 201,
status TRUE,
children {
{name "James", gender boy, time "20020312123517"},
{name "Martha", gender girl, time "20100820045240"}
}
}
|
if (ossConvertPduValueToCsv(world, pduNum, decodedValue, &csvBuf))
{
ossPrint(world, "Error: %s\n", ossGetIaapiErrMsg(world));
break;
}
else if (!(*csvBuf.value))
{
ossPrint(world, "CSV is empty");
}
|
name,number,status,children_name,children_gender,children_time "Nancy",201,TRUE,"James",boy,20020312123517.000 "Nancy",201,TRUE,"Martha",girl,20100820045240.000 |
|
For the first component in each SET OF and SEQUENCE OF type, create the CSV in column format using the equal sign separator and surrounding spaces, plus the PDU name prefix. Use the time stamp with dashes format for GeneralizedTime values.
ossSetCsvSetting(world, OSS_CSV_FORMAT, OSS_CFT_COLUMN);
ossSetCsvSetting(world, OSS_CSV_FORMAT_SEPARATOR, (unsigned int)'=');
ossSetCsvSetting(world, OSS_CSV_MAX_SET_OF_SEQ_OF_COMPONENTS, 1);
ossSetCsvSetting(world, OSS_CSV_TIME, OSS_COS_TIME_STAMP_WITH_DASHES);
ossSetCsvSetting(world, OSS_CSV_FLAGS,
ossGetCsvSetting(world, OSS_CSV_FLAGS)
| OSS_CSV_SPACES_AROUND_SEP
| OSS_CSV_HEADER_FIRST_WITH_PDU_NAME);
if (ossConvertPduValueToCsv(world, pduNum, decodedValue, &csvBuf))
{
ossPrint(world, "Error: %s\n", ossGetIaapiErrMsg(world));
break;
}
else if (!(*csvBuf.value))
{
ossPrint(world, "CSV is empty");
}
|
PersonnelRecord_name = "Nancy" number = 201 status = TRUE children_name = "James" children_gender = boy children_time = 2002-03-12 12:35:17 |
|
|
Create the CSV in row format as follows:
ossSetDefaultCsvSettings(world);
ossSetCsvSetting(world, OSS_CSV_FORMAT, OSS_CFT_ROW);
ossSetCsvSetting(world, OSS_CSV_FORMAT_SEPARATOR, (unsigned int)';');
ossSetCsvSetting(world, OSS_CSV_HEADER, OSS_CHR_ABSENT);
ossSetCsvSetting(world, OSS_CSV_ENUMERATED, OSS_CEN_NUMBER);
ossSetCsvSetting(world, OSS_CSV_TIME,OSS_COS_TIME_STAMP_WITH_SLASHES);
if (ossConvertPduValueToCsv(world, pduNum, decodedValue, &csvBuf))
{
ossPrint(world, "Error: %s\n", ossGetIaapiErrMsg(world));
break;
}
else if (!(*csvBuf.value))
{
ossPrint(world, "CSV is empty");
}
|
"Nancy",201,1,"James",1,03/12/02 12:35:17 "Nancy",201,1,"Martha",0,08/20/10 04:52:40 |
|
|
Create the CSV with an extended CSV header format as follows:
ossSetDefaultCsvSettings(world);
ossSetCsvSetting(world, OSS_CSV_HEADER, OSS_CHR_ABREF_EXTENDED);
if (ossConvertPduValueToCsv(world, pduNum, decodedValue, &csvBuf))
{
ossPrint(world, "Error: %s\n", ossGetIaapiErrMsg(world));
break;
}
else if (!(*csvBuf.value))
{
ossPrint(world, "CSV is empty");
}
|
PersonnelRecord_name, PersonnelRecord_number, PersonnelRecord_status, PersonnelRecord_children_*_name, PersonnelRecord_children_*_gender, PersonnelRecord_children_*_time "Nancy",201,TRUE,"James",boy,2002031212 3517.000 "Nancy",201,TRUE,"Martha",girl,20100820 045240.000 |
The ossSetCsvSetting() function returns an IAAPI_ERRTYPE enumerator. If no error occurs, the IAAPI_NOERROR enumerator is returned; otherwise, an IAAPI error code is returned.
This documentation applies to the OSS® ASN.1 Tools for C release 10.7 and later. If you are using an earlier version, consult the documentation that was shipped with your product.
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.