TOP

IAAPI Functions Reference

Applies to: ASN.1/C 10.5

Contents

Functions that retrieve control table information

ossBoolean ossConstrainWasSpecified(OssGlobal *world);

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.

Arguments

world is a pointer to the OSS global environment variable.

Return Value

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.

See Also

-constraints | -noConstraints


unsigned short ossCtlTblVersionNumber(OssGlobal *world);

Returns the internal version number of the control table in use. This function can be used to compare two different control tables for compatibility.

Arguments

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).

Return Value

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.


ossBoolean ossCtlTblUsableOnlyByBER(OssGlobal *world);

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.

Arguments

world is a pointer to the OSS global environment variable.

Return Value

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.

See Also

-per | -uper


ossBoolean ossCtlTblUsableOnlyByPER(OssGlobal *world);

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.

Arguments

world is a pointer to the global OSS environment variable.

Return Value

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.

See Also

-ber | | -der | -per | -uper


ossBoolean ossDebugWasSpecified(OssGlobal *world);

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.

Arguments

world is a pointer to the OSS global environment variable.

Return Value

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.

See Also


Functions that inform users about the ASN.1 specification associated with a type

const char *ossAsn1ItemName(OssGlobal *world, TypeHndl type, unsigned int ix);

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.

Arguments

world
Pointer to the OSS global environment variable.
type
Handle of the type for which the identifier of the (ix + 1)st / nd / rd / th element is desired.
ix starts from 0 and goes up to higher numbers sequentially. For example, an ix value of 2 corresponds to the second (counting from the left) named bit/number or the second element (counting from the top) of a structured type (SEQUENCE, SET, or CHOICE).

Return Value

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.

Remarks

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.

See Also


ASN1TagClass ossAsn1TagClass(OssGlobal *world, TypeHndl type, int ix);

Is used to find the ASN.1 class of a specified tag in an ASN.1 type definition.

Arguments

world
Pointer to the OSS global environment variable.
type
Handle of the PDU for which the ASN.1 class of the (ix + 1)st / nd / rd / th tag is desired.

Return Value

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:

typedef enum ASN1TagClass {
        UNIVERSAL, APPLICATION, CONTEXT_SPECIFIC, PRIVATE, NULLENCODING
} ASN1TagClass;

int ossAsn1TagNumber(OssGlobal *world, TypeHndl type, int ix);

Retrieves the ASN.1 tag number (23 in [UNIVERSAL 23], for example) of a specified tag in the ASN.1 type definition.

Arguments

world
Pointer to the OSS global environment variable.
type
Handle of the type for which the tag number of the (ix + 1)st / nd / rd / th tag is desired.

Return Value

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).


int ossAsn1TypeId(OssGlobal *world, TypeHndl type);

Checks the ASN.1 compiler-generated control table to determine the basic ASN.1 built-in type of data based on its type handle.

Arguments

world
Pointer to the OSS global environment variable.
type
Handle of the ASN.1 type whose corresponding built-in type you wish to see.

Return Value

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.

Example

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 */
}

....

const char *ossBuiltinTypeName(OssGlobal *world, ASN1Type typeId);

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.

Arguments

world
Pointer to the OSS global environment variable.
typeId
An enumerator that is returned by an IAAPI function (ossAsn1TypeId(), for example).

Return Value

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"

ossBoolean ossExtensionMarkerIsPresent(OssGlobal *world, TypeHndl type);

Reports whether a PER-visible extension marker is present in a specified ASN.1 type.

Arguments

world
Pointer to the OSS global environment variable.
type
Handle of the ASN.1 type to check for an extension marker.

Return Value

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.


long ossItemIntValue(OssGlobal *world, TypeHndl type, unsigned int ix);

Returns the number associated with a named bit, named number, or enumerator associated with a BIT STRING, INTEGER, or ENUMERATED type.

Arguments

world
Pointer to the OSS global environment variable.
type
Handle of the type for which the associated number of the (ix + 1)st / nd / rd / th named bit, named number, or enumerator is desired.

Return Value

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.

Remarks

The function could work incorrectly with a named number that does not fit the LONG_MIN..LONG_MAX range.


LONG_LONG ossItemIntValueLL(OssGlobal *world, TypeHndl type, unsigned int ix);

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.

Arguments

world
Pointer to the OSS global environment variable.
type
Handle of the type for which the associated number of the (ix + 1)st / nd / rd / th named bit, named number, or enumerator is desired.

Remarks

To correctly work with a named number that does not fit the LONG_MIN..LONG_MAX range, use the ossItemIntValueLL() function instead of ossItemIntValue().

Return Value

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.


int ossNumberOfArtificialPDUs(OssGlobal *world);

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.

Arguments

world is a pointer to the OSS global environment variable that is initialized (via ossinit() or ossWinit()) for a particular control table.

Return Value

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.


int ossNumberOfNamedItems(OssGlobal *world, TypeHndl type);

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).

Arguments

world
Pointer to the OSS global environment variable.
type
Type handle of the ASN.1 type whose named components you wish to count.

Return Value

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.


int ossNumberOfPDUs(OssGlobal *world);

Returns the total number of messages (PDUs) found in an ASN.1 specification.

Arguments

world is a pointer to the OSS global environment variable that is initialized (via ossinit() or ossWinit()) for a particular control table.

Return Value

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.


int ossNumberOfTags(OssGlobal *world, TypeHndl type);

Returns the number of ASN.1 tags found in a particular ASN.1 type.

Arguments

world
Pointer to the OSS global environment variable.
type
Type handle whose number of tags is desired.

Return Value

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).

Example

....
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.


int ossPduNumberByType(OssGlobal *world, TypeHndl type);

Retrieves the PDU number of a type based on its type handle.

Arguments

world
Pointer to the OSS global environment variable.
type
Type handle that references the ASN.1 type whose associated PDU number you would like to retrieve.

Return Value

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.

Remarks

PDU numbers assigned by the OSS ASN.1 Tools start from 1.


TypeHndl ossPduTypeHandleByName(OssGlobal *world, const char *name);

Retrieves a type handle of a PDU based on its type reference in the ASN.1 input.

Arguments

world
Pointer to the OSS global environment variable.
name
Address of a character string that contains the name of the type handle ("RequestParam", for example).

Return Value

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.


TypeHndl ossTypeHandleOfPDU(OssGlobal *world, int pduNum);

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.

Arguments

world
Pointer to the OSS global environment variable.
pdunum
Holds the compiler-generated identification constant (the #defined typename_PDU constant in the generated header file) for the type handle.

Return Value

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.


const char *ossTypeReferenceName(OssGlobal *world, TypeHndl type);

Retrieves the name given to a particular user-defined type in the input ASN.1 specification.

Arguments

world
Pointer to the OSS global environment variable.
type
Type handle that references the ASN.1 type whose associated reference or name you would like to retrieve.

Return Value

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).

Remarks

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.

See Also


Functions that retrieve ASN.1 type constraint information

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.

See Also

ossConstrainWasSpecified()

ossBoolean ossLowerBoundIsPresent(OssGlobal *world, TypeHndl type);

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.

Arguments

world
Pointer to the OSS global environment variable.
type
Type handle for which you wish to know whether a subtype constraint with a finite lower bound exists.

Return Value

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.


unsigned long ossLowerBoundOfSizeConstraint(OssGlobal *world, TypeHndl type);

Returns the smallest allowed size of a specified type, as indicated by a subtype constraint in the ASN.1 specification.

Arguments

world
Pointer to the OSS global environment variable.
type
Type handle whose smallest allowable size you wish to know.

Return Value

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.

Remarks

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.


void ossMinValueOfInteger(OssGlobal *world, TypeHndl type, IntValue *val);

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.

Arguments

world
Pointer to the OSS global environment variable.
type
Handle of the INTEGER whose minimum value you wish to retrieve.
val
Pointer to an IntValue structure (which you declared) that will contain the minimum value of the specified INTEGER type.

Return Value

ossMinValueOfInteger() does not return a value.

See Also

ossMaxValueOfInteger()


void ossMaxValueOfInteger(OssGlobal *world, TypeHndl type, IntValue *val);

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.

Arguments

world
Pointer to the OSS global environment variable.
type
Handle of the INTEGER whose largest value you wish to retrieve.
val
Pointer to an IntValue structure (which you declared) that will contain the largest value of the specified INTEGER type.

Return Value

ossMaxValueOfInteger() does not return a value.

Remarks

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.


const long *ossPermittedAlphabetConstraint(OssGlobal *world, TypeHndl type);

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.

Arguments

world
Pointer to the OSS global environment variable.
type
Handle of a NumericString, PrintableString, VisibleString, or IA5String type.

Return Value

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.

Remarks

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:

  • For NumericString, the length is 11.
  • For PrintableString, the length is 74.
  • For VisibleString, the length is 95.
  • For IA5String, the length is 128.

unsigned long ossPermittedAlphabetLength(OssGlobal *world, TypeHndl type);

Returns the length of the permitted alphabet of a type defined with a PER-visible permitted alphabet constraint.

Arguments

world
Pointer to the OSS global environment variable.
type
Handle of a restricted character string that has a PER-visible permitted alphabet.

Return Value

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.

Remarks

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.


ossBoolean ossTypeIsConstrained(OssGlobal *world, TypeHndl type);

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.

Arguments

world
Pointer to the OSS global environment variable.
type
Handle of the type to test for subtype constraint information.

Return Value

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.


ossBoolean ossUpperBoundIsPresent(OssGlobal *world, TypeHndl type);

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.

Arguments

world
Pointer to the OSS global environment variable.
type
Handle of the type for which you wish to know whether a subtype constraint with a finite upper bound exists.

Return Value

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.

Remarks

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.


unsigned long ossUpperBoundOfSizeConstraint(OssGlobal *world, TypeHndl type);

Returns the largest allowed size of a specified type, as indicated by a subtype constraint in the ASN.1 specification.

Arguments

world
Pointer to the OSS global environment variable.
type
Handle of the type whose largest allowed size you wish to know.

Return Value

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.

Remarks

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.


unsigned long *ossWidePermittedAlphabet(OssGlobal *world, TypeHndl type, unsigned long *length);

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.

Arguments

world
Pointer to the OSS global environment variable.
type
Handle of a NumericString, PrintableString, VisibleString, IA5String type, BMPString, UniversalString, or UTF8String.
length
Is returned by the function and includes the number of characters in the alphabet.

Remarks

The array returned by the function must be freed by the caller with ossFreeMemory().

Return Value

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.

Example

....
 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);
}

See Also


Functions that handle contents constraint information

The IAAPI supports functions for retrieving contents constraints information as defined in the ASN.1:2015 standard.

Remarks

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.

int ossContainedTypeEncodingRule(OssGlobal *world, TypeHndl type);

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.

Arguments

world
Pointer to the OSS global environment variable.
type
Handle of the type whose contents constraint information you wish to retrieve.

Return Value

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.


int ossContainedTypePduNumber(OssGlobal *world, TypeHndl type);

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.

Arguments

world
Pointer to the OSS global environment variable.
type
Handle of the type with a contents constraint applied.

Remarks

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().

Return Value

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.


const char *ossEncodingRuleObjid(OssGlobal *world, int ruleId);

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.

Arguments

world
Pointer to the OSS global environment variable.
ruleId
Value of an ossEncodingRules enumeration defined in ossglobl.h as follows:
 typedef enum  {
    OSS_BER = 0,
    OSS_PER_ALIGNED,
    OSS_PER_UNALIGNED,
    OSS_DER,
    OSS_ECN,
    OSS_XER,
    OSS_CXER,
    OSS_CER,
	OSS_EXER
} ossEncodingRules;

Return Value

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)}"

IAAPI_ERRTYPE ossGetContainedTypeValue(OssGlobal *world, TypeHndl type, void *containingValue, void **decodedValue, OssBuf *encodedValue);

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.

Arguments

world
Pointer to the OSS global environment variable.
type
Type handle that references the BIT STRING or OCTET STRING type with contents constraint whose contents information you wish to retrieve.
containingValue
Void pointer that references the address of the containing value structure whose contents you wish to see.
decodedValue
Address of a void pointer that will reference the decoded value of the contained type (it is a type specified in the CONTAINING clause) or NULL if no decoded value is present.
encodedValue
Address of an OssBuf structure that will contain the length and encoded fields of the contained type encoded value, if it is present. Note that for BIT STRING types, the length field contains the number of significant bits.

Return Value

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.


IAAPI_ERRTYPE ossPutContainedTypeDecodedValue(OssGlobal *world, TypeHndl type, void *containedDecodedValue, void **containingValue);

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.

Arguments

world
Pointer to the OSS global environment variable.
type
Type handle that references the BIT STRING or OCTET STRING with a contents constraint whose contained type decoded value you wish to set.
containedDecodedValue
Pointer to the new decoded value of the contained type.
containingValue
Pointer that will reference the new value of the BIT STRING or OCTET STRING type with a contents constraint. If containingValue points to a NULL pointer, memory is automatically allocated for the new containing type structure (you can later free the memory with a call to ossFreeDecodedValue()).

Remarks

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.

Return Value

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.

See Also

ossPutEncodedValue()


ossBoolean ossTypeHasContentsConstraint(OssGlobal *world, TypeHndl type);

Informs you of whether a BIT STRING or OCTET STRING has contents constraint in the input ASN.1 syntax.

Arguments

world
Pointer to the OSS global environment variable.
type
Handle of the ASN.1 type which you would like to test for being defined with a contents constraint.

Return Value

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.


Functions that handle structured types with components

ossBoolean ossCompAppearsAfterExtensionMarker(OssGlobal *world, TypeHndl type, unsigned int ix);

Determines whether a component of a SET, SEQUENCE, or CHOICE type appears after an extension marker ("...") and is optional.

Arguments

world
Pointer to the OSS global environment variable.
type
Handle of the SET or SEQUENCE type whose component you wish to check for occurring after an extension marker.
ix
Index of the component to check. The index starts from zero.

Return Value

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.


const void *ossComponentDefaultValue(OssGlobal *world, TypeHndl parentType, unsigned int ix);

Retrieves the DEFAULT value of a component in a SET or SEQUENCE type.

Arguments

world
Pointer to the OSS global environment variable.
parentType
Handle of the SET or SEQUENCE type whose component's DEFAULT value you wish to retrieve.
ix
Index of the component to check. The index starts from zero.

Return Value

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).


ossBoolean ossComponentHasDefaultValue(OssGlobal *world, TypeHndl parentType, unsigned int ix);

Checks whether a DEFAULT value is present for a component of a SET or SEQUENCE type.

Arguments

world
Pointer to the OSS global environment variable.
parentType
Handle of the SET or SEQUENCE type whose component you wish to check for a DEFAULT value.
ix
Index of the component to check. The index starts from zero.

Return Value

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).


ossBoolean ossComponentIsInitializationValue(OssGlobal *world, TypeHndl childType, void *compAddress);

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.

Arguments

world
Pointer to the OSS global environment variable.
childType
Handle of a component of a SET or SEQUENCE type to test for initialization.
compAddress
Address of the actual component to check for initialization.

Return Value

ossComponentIsInitializationValue() returns an ossBoolean type. If the component was initialized with a value, TRUE is returned; otherwise, a value of FALSE is returned.

See Also

ossSetInitializationValues()


ossBoolean ossComponentIsOptional(OssGlobal *world, TypeHndl type, unsigned int ix);

Informs whether a component of a SET or SEQUENCE type is marked as OPTIONAL or has a DEFAULT value.

Arguments

world
Pointer to the OSS global environment variable.
type
Handle of the ASN.1 type whose (ix + 1)st / nd / rd / th element will be checked for being OPTIONAL or having a DEFAULT value.

Return 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.

Remarks

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.


ossBoolean ossComponentValueIsPresent(OssGlobal *world, TypeHndl parentType, unsigned int ix, void *parentValue);

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.

Arguments

world
Pointer to the OSS global environment variable.
parentType
Handle of the SET, SEQUENCE, or CHOICE type whose component you wish to check for presence.
ix
Index of the component to check. The index starts from zero.
parentValue
Address of the decoded parent structure to check for an optional component.

Return Value

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.


ossBoolean ossComponentWasRemoved(OssGlobal *world, TypeHndl type, unsigned int ix);

Informs whether a component of a SET, SEQUENCE, or CHOICE type was removed using the ASN1.Remove directive in the input ASN.1 syntax.

Arguments

world
Pointer to the OSS global environment variable.
type
Handle of the ASN.1 type whose (ix + 1)nd/rd/th element is checked for removal.

Return Value

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.


IAAPI_ERRTYPE ossDeleteComponent(OssGlobal *world, TypeHndl parentType, unsigned int compIndex, void **parentValue);

Deletes the value of a component within an ASN.1 structured type (for example, SET, SEQUENCE, SET OF, SEQUENCE OF, and CHOICE).

Arguments

world
Pointer to the OSS global environment variable.
parentType
Type handle referencing the PDU whose component will be deleted.
compIndex
Index of the component to be deleted.
parentValue
Pointer to the decoded structure containing the component to be deleted.

Return Value

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.

Remarks

The memory allocated for the component for deletion is freed by the ossDeleteComponent() function. Additionally, any nested components are also deleted.


IAAPI_ERRTYPE ossGetComponentByAbsRef(OssGlobal *world, char *compAbsref, void *parentValue, TypeHndl *compType, void **compValue);

Retrieves a value of a component of a structured type in decoded internal format given its absolute reference.

Arguments

world
Pointer to the OSS global environment variable.
compAbsref
Address of the character string containing the absolute reference (for example, "Module1.SeqType1.compA") of the component you wish to retrieve.
parentValue
Address of the parent structure containing the component you wish to retrieve.
compType
Address of a type handle that will be set as the component handle upon return.
compValue
Address of a pointer that will reference the desired component upon return. Note that no memory is allocated for the component's value; compValue will simply reference the original component within the parent type.

Remarks

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.

Return Value

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.

Remarks

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.

Example

The example below uses the Baseball Card Abstract Syntax, which is found in samples/bcas.asn:

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;
} BBCard;

extern BBCard myCard;
....

struct ossGlobal w, *world = &w;  /* OSS environment variable */
BBCard *myCardPtr = NULL;          /* address of decoded data  */ int retcode;		               /* return code              */ TypeHndl compTypeHndl1;          /* typehandle of component  */ TypeHndl compTypeHndl2, compTypeHndl3;
void *nameValue, *teamValue, *batting_averageValue; 
....

if (ossGetComponentByAbsRef(world, "BBCard.name", myCardPtr,                              &compTypeHndl1, &nameValue) ||    ossGetComponentByAbsRef(world, "BBCard.team", myCardPtr,                              &compTypeHndl2, &teamValue) ||    ossGetComponentByAbsRef(world, "BBCard.batting-average", myCardPtr,                              &compTypeHndl3, &batting_averageValue)) {    ossterm(world);    retcode = 1; } else {		    ossPrint(world, "%s of the %s has a batting average of %0.3f\n",             (char *)nameValue, (char *)teamValue,              *(double *)batting_averageValue);    ossFreePDU(world, pdu_num, myCardPtr);    retcode = 0; }

See Also

ossPutComponentByAbsRef()


IAAPI_ERRTYPE ossGetDecodedValueOfComponent(OssGlobal *world, TypeHndl parentType, void *parentDecodedStruct, unsigned int compIndex, void **compValue);

Retrieves a value of a component of a structured type in decoded internal format. The original structure is not modified.

Arguments

world
Pointer to the OSS global environment variable.
parentType
Type handle referencing the structured type whose component's value you wish to retrieve.
parentDecodedStruct
Pointer to the structure in decoded format containing the desired component.
compIndex
Index of the desired component in the parent structured type.
compValue
Address of a pointer which will reference the decoded value of the component contained within the parent type. Note that no memory is allocated for the component's value; compValue references the original component within the parent type (for this reason, create a copy of the retrieved value before attempting to insert it into another structure).

Return Value

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.


unsigned int ossItemIndexByName(OssGlobal *world, TypeHndl type, const char *name);

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.

Arguments

world
Pointer to the OSS global environment variable.
type
Type handle referencing the ASN.1 type containing a component with the identifier name whose index you wish to retrieve.

Return Value

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.

Remarks

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.


int ossNumberOfRootItems(OssGlobal *world, TypeHndl type);

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().

Arguments

world
Pointer to the OSS global environment variable.
type
Type handle for the ASN.1 type whose non-extension-addition components you wish to count.

Return Value

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.


IAAPI_ERRTYPE ossPutComponentByAbsRef(OssGlobal *world, char *compAbsref, void *parentValue, void *compValue);

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.

Arguments

world
Pointer to the OSS global environment variable.
compAbsref
Pointer to a character string containing the absolute reference (for example, "Module.seqtType.a") of the component whose value you desire to set.
parentType
Pointer to the SET, SEQUENCE, SET OF, SEQUENCE OF, or CHOICE type containing the component whose value will be set.
compValue
Pointer referencing the new desired value of the component in decoded internal format.

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()).

Return Value

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.

See Also

ossGetComponentByAbsRef()


IAAPI_ERRTYPE ossPutStructTypeValue(OssGlobal *world, TypeHndl parentType, void *compValue, unsigned int compIndex, void **structToUpdate);

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.

Arguments

world
Pointer to the OSS global environment variable.
parentType
Type handle of the ASN.1 type whose component value will be changed.
compValue
Pointer to a decoded (unencoded) value that will be assigned to a component of a structured type.
compIndex
Index of the component to modify within the parent structure.
structToUpdate
Pointer that will reference the output parent structure with the modified component value. If structToUpdate is NULL, memory will automatically be allocated for a new structure. This memory can later be freed by a call to ossFreeDecodedValue().

Return Value

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.

Remarks

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.

Example


/******************************************************************************
 * 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;

#ifndef SKIP_DELETE_COMPONENTS
    for (k = 0; k < 2; k++) {
#endif /* SKIP_DELETE_COMPONENTS */
	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.


IAAPI_ERRTYPE ossPutStructTypeValueByComponentAbsRef( OssGlobal *world, TypeHndl outerType, void *compValue char *compAbsref, void **outerStructToUpdate);

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.

Arguments

world
Pointer to the OSS global environment variable.
outerType
Type handle of the outer SET, SEQUENCE, SET OF, SEQUENCE OF, CHOICE type, or CLASS whose value should be either created or updated with the input decoded value of the component that appears inside this type at any level of nesting (the value of outerType can be NULL, in which case the type handle of the outermost parent is determined based upon the first node specified in the component absolute reference, which must be a PDU).
compValue
Pointer referencing the new desired value of the component in decoded internal format.
compAbsref
Pointer to a character string containing the absolute reference without a module reference (for example, "SqtType.a.2.b.1.c") of the component whose value will be set.
outerStructToUpdate
Pointer which will reference the output outermost parent structure with the modified component value inserted into it. If outerStructToUpdate is NULL, memory will automatically be allocated for a new structure and this memory can later be freed by a call to ossFreeDecodedValue().

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()).

Return Value

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.

See Also

ossPutComponentByAbsRef()


TypeHndl ossTypeHandleOfComponent(OssGlobal *world, TypeHndl parent, unsigned int ix);

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.

Arguments

world
Pointer to the OSS global environment variable.
parent
Type handle of the ASN.1 type containing the component whose handle you want.
ix
Index of the component in the parent ASN.1 type whose handle you wish to retrieve.

Return Value

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.

Warning

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.


Functions that handle open types

IAAPI_ERRTYPE ossGetOpenTypeValue(OssGlobal *world, TypeHndl type, void *openValue, unsigned int *pduNum, void **decodedValue, OssBuf *encodedValue);

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.

Arguments

world
Pointer to the OSS global environment variable.
type
Type handle referencing the open type whose contents information you wish to retrieve.
openValue
Void pointer referencing the address of the OpenType structure whose contents you desire.
pduNum
Address of an int which will contain the PDU number associated with the open type.
decodedValue
Address of a void pointer which will reference the contents of the decoded field of the open type.
encodedValue
Address of an OssBuf structure which will contain the length and encoded fields of the open type (in its own OssBuf.length and OssBuf.value fields).

Return Value

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.

Example

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);

IAAPI_ERRTYPE ossPutEncodedValue(OssGlobal *world, TypeHndl type, OssBuf encodedValue, void **decodedValue);

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.

Arguments

world
Pointer to the OSS global environment variable.
type
Type handle referencing the open type or ANY type whose value you desire to set.
encodedValue
OssBuf type structure whose value field contains the open-type/ANY encoding that you desire and whose length field contains the length in bytes of this encoding.
decodedValue
Pointer which will reference the new OpenType or ANY structure with the proper encoded/value and length fields. If decodedValue is NULL, then memory will be allocated for a new OpenType/ANY type structure (you can free this memory by a call to ossFreeDecodedValue()).

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.

Return Value

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.


IAAPI_ERRTYPE ossPutOpenTypeDecodedValue(OssGlobal *world, TypeHndl type, unsigned int pduNum, void *decodedValue, void **openValue);

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.

Arguments

world
Pointer to the OSS global environment variable.
type
Type handle referencing the open type PDU whose pduNum and decoded fields you desire to set.
pduNum
Compiler-assigned PDU number of the structure containing the open type.
decodedValue
Pointer to the new desired decoded value of the open type.
openValue
Pointer which will reference the new OpenType or OpenTypeExtended structure containing the desired values. If a NULL pointer is passed as the openValue argument, memory is automatically allocated for the new open type (you can then later free this memory by a call to ossFreeDecodedValue()).

Return Value

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.


Functions that convert values between display and decoded formats

IAAPI_ERRTYPE ossDecodeValueNotationOfPDU(OssGlobal *world, int pduNum, OssBuf *displayValue, void **decodedValue);

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.

Arguments

world
Pointer to the OSS global environment variable.
pduNum
Integer holding the compiler-assigned PDU number of the type whose display format value will be converted.
displayValue
Pointer an OssBuf type structure whose value field references a character string holding the display value and whose length field is either zero (if the character string is null-terminating) or holds the length of the character string (if the character string is not null-terminating).
decodedValue
A NULL pointer which will reference the output decoded PDU. The memory allocated for this structure can be freed by a call to ossFreeDecodedValue().

Return Value

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.

Remarks

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.


IAAPI_ERRTYPE ossDecodeValueNotationOfType(OssGlobal *world, TypeHndl type, OssBuf *displayValue, void **decodedValue);

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.

Arguments

world
Pointer to the OSS global environment variable.
type
Type handle which references the type whose display format value will be converted.
displayValue
Pointer an OssBuf type structure whose value field references a character string holding the display value and whose length field is either zero (if the character string is null-terminating) or holds the length of the character string (if the character string is not null-terminating).
decodedValue
A NULL pointer which will reference the output decoded PDU. The memory allocated for this structure can be freed by a call to ossFreeDecodedValue().

Return Value

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.

Remarks

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.

Warning

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()).


char *ossGetValueNotationOfPDU(OssGlobal *world, int pduNum, void *decodedValue);

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.

Arguments

world
Pointer to the OSS global environment variable.
pduNum
A Compiler-assigned PDU number of the type whose value you wish to convert
decodedValue
Pointer to the original data type which is in the decoded internal format

Return Value

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.


char *ossGetValueNotationOfType(OssGlobal *world, TypeHndl type, void *decodedValue);

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.

Arguments

world
Pointer to the OSS global environment variable.
type
Type handle referencing the type whose value you wish to convert.
decodedValue
Pointer to the original data type which is in the decoded internal format.

Remarks

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}

Return Value

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.


char *ossGetValueOfSimpleType(OssGlobal *world, TypeHndl type, void *decodedValue);

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.

Arguments

world
Pointer to the OSS global environment variable.
type
Type handle referencing the simple type whose value you wish to convert.
decodedValue
Pointer to the original simple type which is in the decoded internal format.

Return Value

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.


IAAPI_ERRTYPE ossPutDecodedValueOfPDU(OssGlobal *world, int pduNum, char *displayValue, void **pduDecodedValue);

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 value notations that are returned by another IAAPI function, ossGetValueNotationOfPDU(), that begin with the "valueName PduTyperefName ::=" string.

Arguments

world
Pointer to the OSS global environment variable.
pduNum
Integer holding the compiler-assigned PDU number of the type whose display format value will be converted.
displayValue
Character string holding text data to convert to the internal format.
pduDecodedValue
An address of a NULL pointer which will reference the output decoded internal format structure. The memory allocated for this structure can be freed by a call to ossFreeDecodedValue().

Return Value

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.

Example

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);

....

IAAPI_ERRTYPE ossPutSimpleTypeValue(OssGlobal *world, TypeHndl type, char *displayValue, void **pduDecodedValue);

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.

Arguments

world
Pointer to the OSS global environment variable.
type
Type handle of the type whose display format value will be converted.
displayValue
Character string holding text data to convert to the internal format.
pduDecodedValue
Address of a NULL pointer which will reference the output decoded internal format value. The memory allocated for this structure can be freed by a call ossFreeDecodedValue().

Return Value

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.

Example

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

void *ossUpdateValueOfSimpleType(OssGlobal *world, TypeHndl type, char *displayValue, void *oldDecodedValue);

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.

Arguments

world
Pointer to the OSS global environment variable.
type
Type handle referencing the original simple type whose value you desire to change.
displayValue
Pointer referencing a character string containing the new value for the simple type in display format (for example, "1235").
oldDecodedValue
Pointer referencing the original decoded value of the simple type (the memory for this value will be freed upon a successful return).

Return Value

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.

Example

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

Remarks

The ossUpdateValueOfSimpleType() function is usually used on values created via the ossPutSimpleTypeValue() function or retrieved via the ossGetValueOfSimpleType() function.


Functions that handle ASN.1 value references

The functions in this section will only work properly if you compiled the input ASN.1 syntax with the -valueRefs command-line option.

const void *ossGetDecodedValueOfValueReference(OssGlobal *world, unsigned short valRefIndex);

Retrieves the actual value of a value reference in the decoded internal format given its index.

Arguments

world
Pointer to the OSS global environment variable.
valRefIndex
Index (this index starts from zero) of the value reference.

Return Value

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.

Example

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&lt;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.


const char *ossGetNameOfValueReference(OssGlobal *world, unsigned short valRefIndex);

Retrieves the character string name of a particular value reference in the ASN.1 input given its index.

Arguments

world
Pointer to the OSS global environment variable.
valRefIndex
Index of the value reference. The index starts at zero.

Return Value

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.


unsigned short int ossGetNumberOfValueReferences(OssGlobal *world);

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.

Arguments

world is a pointer to the global OSS environment variable.

Return Value

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.


TypeHndl ossGetTypeHandleOfValueReference(OssGlobal *world, unsigned short valRefIndex);

Retrieves the type handle of a value reference given its index.

Arguments

world
Pointer to the OSS global environment variable.
valRefIndex
Index of the value reference.

Return Value

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.


Functions that serve as an interface to the encoder

IAAPI_ERRTYPE ossValueEncode(OssGlobal *world, TypeHndl type, void *decodedValue, OssBuf *encodedValue);

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.

Arguments

world
Pointer to the OSS global environment variable.
type
Type handle which references the type which you wish to encode.
decodedValue
Pointer to the value in decoded internal format which will be encoded.
encodedValue
Address of an empty OssBuf structure (set OssBuf.value to NULL and OssBuf.length to zero) which is to contain the encoding of the passed decoded value.

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().

Return Value

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.


Functions that retrieve parts of or general information about a BER-based encoding

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.

ASN1TagClass ossEncodingASN1Class(OssGlobal *world, unsigned char *currentEncoding, long bufLength, int ix);

Is used to find the ASN.1 tag class of a specified tag in a BER/DER encoding.

Arguments

world
Pointer to the OSS global environment variable.
currentEncoding
Pointer to a BER/DER encoding.
bufLength
The length in bytes of the encoding.
ix
Index of the tag in the sent encoding whose tag class you desire. The index starts at 1 and not zero.

Return Value

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;

LONG_LONG ossEncodingASN1Tag(OssGlobal *world, unsigned char *currentEncoding, long bufLength, int ix);

Is used to find the ASN.1 tag number (for example, 3 in [UNIVERSAL 3]) of a specified tag in a BER/DER encoding.

Arguments

world
Pointer to the OSS global environment variable.
currentEncoding
Pointer to a BER/DER encoding.
bufLength
The length in bytes of the encoding.
ix
Index of the tag in the sent encoding whose tag number you desire. The index starts at 1 and not zero.

Return Value

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.


char *ossEncodingASN1Type(OssGlobal *world, unsigned char *currentEncoding, long bufLength);

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]).

Arguments

world
Pointer to the OSS global environment variable.
currentEncoding
Pointer to a BER/DER encoding.
bufLength
The length in bytes of the encoding.

Return Value

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.


char *ossEncodingContents(OssGlobal *world, unsigned char *currentEncoding, long bufLength);

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).

Arguments

world
Pointer to the OSS global environment variable.
currentEncoding
Pointer to the buffer which contains the encoding whose contents you wish to extract.
bufLength
The length in bytes of the BER/DER encoding.

Return Value

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)

unsigned long ossEncodingLength(OssGlobal *world, unsigned char *currentEncoding, long bufLength);

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.

Arguments

world
Pointer to the OSS global environment variable.
currentEncoding
Pointer to a BER/DER encoding.
bufLength
The entire length in bytes of the encoding.

Return Value

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).

Remarks

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.


int ossEncodingIdentifierLength(OssGlobal *world, unsigned char *currentEncoding, long bufLength);

Retrieves the number of octets occupied by the type (identifier) field in a BER/DER encoding which is in the type-length-value format.

Arguments

world
Pointer to the OSS global environment variable.
currentEncoding
Pointer to a BER/DER encoding.
bufLength
The entire length in bytes of the encoding.

Return Value

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).


ossBoolean ossEncodingIsConstructed(OssGlobal *world, unsigned char *currentEncoding, long bufLength);

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.

Arguments

world
Pointer to the OSS global environment variable.
currentEncoding
Pointer to a BER/DER encoding.
bufLength
The length in bytes of the encoding.

Return Value

ossEncodingIsConstructed() returns an ossBoolean type. If sent encoding is constructed, a value of TRUE of returned; otherwise, a value of FALSE is returned.


unsigned long ossEncodingLength(OssGlobal *world, unsigned char *currentEncoding, long bufLength);

Retrieves the value of the length field in a BER/DER encoding which is in the type-length-value format.

Arguments

world
Pointer to the OSS global environment variable.
currentEncoding
Pointer to a BER/DER encoding.
bufLength
the entire length in bytes of the encoding.

Return Value

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).

Remarks

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.


unsigned char *ossGetNestedBEREncoding(OssGlobal *world, unsigned char *currentEncoding, long *remainingBufLength);

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.

Arguments

world
Pointer to the OSS global environment variable.
currentEncoding
Address of a constructed BER encoding whose first nested encoded value you wish to retrieve.
bufLength
Pointer to the length in bytes of the current BER encoding (remainingBufLength is updated to reflect the number of bytes remaining in the nested encoding upon a successful return).

Return Value

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.


unsigned char *ossGetNextBEREncoding(OssGlobal *world, unsigned char *currentLocation, long *remainingBufLength);

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.

Arguments

world
Pointer to the OSS global environment variable.
currentLocation
Pointer to the place in the encoding buffer from which to search for the subsequent value.
remainingBufLength
Pointer to the length in bytes from the current location to the end of the BER encoding (remainingBufLength is updated to reflect the number of bytes remaining in the current encoding after the new returned address upon a successful return).

Return Value

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.


long ossNumberOfEncodingTags(OssGlobal *world, unsigned char *currentEncoding, long bufLength);

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.

Arguments

world
Pointer to the OSS global environment variable.
currentEncoding
Address of a BER/DER encoding whose number of tags you wish to retrieve.
bufLength
The length in bytes of the current encoding which you wish to search for tags.

Return Value

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.


Functions that convert values between the binary/hexidecimal and encoded formats

IAAPI_ERRTYPE ossConvertBinFmtToEncoding(OssGlobal *world, unsigned char *binBufin, long bufLength, OssBuf *encVal);

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.

Arguments

world
Pointer to the OSS global environment variable.
binBufin
Pointer to an encoding in binary display format.
bufLength
The length in bytes of the binary display format value.
encVal
Address of an empty OssBuf structure (set OssBuf.value to NULL and OssBuf.length to 0) which will contain the encoding in internal format. The memory allocated for the value field of the OssBuf structure must be freed by you later (for example, by a call to ossFreeBuf()).

Return Value

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.


char *ossConvertEncodingIntoDisplayBinFmt(OssGlobal *world, unsigned char *encodedBufin, long bufLength);

Converts a BER/DER encoding to a binary character string in display format which you can easily view or parse.

Arguments

world
Pointer to the OSS global environment variable.
encodedBufin
Pointer to an encoding.
bufLength
The length in bytes of the encoding.

Return Value

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().


char *ossConvertEncodingIntoDisplayHexFmt(OssGlobal *world, unsigned char *encodedBufin, long bufLength);

Converts a BER/DER encoding to a hexadecimal character string in display format which you can easily view or parse.

Arguments

world
Pointer to the OSS global environment variable.
encodedBufin
Pointer to an encoding.
bufLength
The length in bytes of the encoding.

Return Value

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().


IAAPI_ERRTYPE ossConvertHexFmtToEncoding(OssGlobal *world, unsigned char *hexBufin, long bufLength, OssBuf *encVal);

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.

Arguments

world
Pointer to the OSS global environment variable.
hexBufin
Pointer to an encoding in hexadecimal display format.
bufLength
The length in bytes of the input hexadecimal display string.
encVal
Address of an empty OssBuf structure (set OssBuf.value to NULL and OssBuf.length to 0) which will contain the encoding in internal format. The memory allocated for the value field of the OssBuf structure must be freed by you later (for example, by a call to ossFreeBuf()).

Return Value

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.


Functions that handle external objects

These are functions that handle data objects read from or written to files or sockets, for example.

TypeHndl ossDeferTypeHandle(OssGlobal *world, TypeHndl type);

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.

Arguments

world
Pointer to the OSS global environment variable.
type
Type handle of the open type generated for the type marked with the ASN1.DeferDecoding directive.

Return Value

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.


OssObjType ossGetObjectType(OssGlobal *world, TypeHndl type, void *object);

Determines the nature of a specified external object (for example, whether it is a file or socket external object).

Arguments

world
Pointer to the OSS global environment variable.
type
Type handle of a type marked with the OSS.OBJHANDLE | OSS.NOCOPY directive.
object
Address of a marked object (for example, a marked structure containing a length and value field) returned by ossIaapiMarkObject().

Return Value

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.


IAAPI_ERRTYPE ossGetObjectValue(OssGlobal *world, TypeHndl type, void *decodedValue, OssBufExtended *objectValue);

Retrieves a marked object from a decoded value and returns it via the fourth function argument.

Arguments

world
Pointer to the OSS global environment variable.
type
Type handle of an ASN.1 type defined with the OSS.OBJHANDLE | OSS.NOCOPY directive.
decodedValue
Address of a decoded value/structure whose marked object you wish to retrieve.
objectValue
Address of an empty OssBufExtended structure whose value field will reference the marked object (for example, be a file handle or socket id) or will reference the name of the file containing the actual unmarked value (if the object was marked as an OSS_FILE external object).

Return Value

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).

Remarks

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.


IAAPI_ERRTYPE ossIaapiMarkObject(OssGlobal *world, TypeHndl type, OssObjType objectType, void *object);

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.

Arguments

world
Pointer to the OSS global environment variable.
type
Type handle of the type you wish to mark.
objectType
An enumerator of type OssObjType (for example, OSS_FILE, OSS_SOCKET, or OSS_UNKNOWN_OBJECT) which indicates the sort of external object you want to mark.
object
The external object you wish to mark (for example, an OssBufExtended type with a value field or an OpenType with a encoded field).

Return Value

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.


IAAPI_ERRTYPE ossPutObjectValue(OssGlobal *world, TypeHndl type, OssBufExtended *objectValue, OssObjType objectType, void **decodedValue);

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.

Arguments

world
Pointer to the OSS global environment variable.
type
Type handle of the marked object to decode.
objectValue
An OssBufExtended structure whose value field references the marked object or contains the name of the file or socket id containing the actual value, objectType is an enumerator (for example, OSS_UNKNOWN_OBJECT, OSS_FILE, or OSS_SOCKET) that specifies the type of object to be decoded.
decodedValue
Address of a pointer which will reference the value in decoded internal format.

Return Value

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;

Remarks

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.


IAAPI_ERRTYPE ossSetTypeAsExternalObject(OssGlobal *world, TypeHndl type, ossBoolean marked);

Marks or unmarks a type associated with a given type handle as an external object.

Arguments

world
Pointer to the OSS global environment variable.
type
Type handle of the type you wish to mark or unmark.
marked
An ossBoolean variable set either to TRUE (this indicates that you wish to mark the type) or FALSE (this indicates that you wish to unmark the type).

Return Value

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.


ossBoolean ossTypeIsDeferDecoding(OssGlobal *world, TypeHndl type);

Determines whether or not a particular open type was generated due to an ASN1.DeferDecoding directive application in the ASN.1 input.

Arguments

world is a pointer to the global OSS environment variable and type is the type handle of an open type.

Return Value

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.


ossBoolean typeIsExternalObject(OssGlobal *world, TypeHndl type);

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.

Arguments

world
Pointer to the OSS global environment variable.
type
Type handle of the type which will be tested.

Return Value

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.


Functions that print and display data

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.

void ossPrintASN1DescriptionOfPDU(OssGlobal *world, int pduNum, ossBoolean refTypes);

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.

Arguments

world
Pointer to the OSS global environment variable.
pduNum
Compiler-generated PDU number of the type whose ASN.1 source you want to print.
refTypes
The ossBoolean variable that specifies whether or not the description of user-defined types referenced by the specified PDU should also be printed (i.e. the description of referenced user-defined types is also printed after the specified PDU if refTypes is TRUE).

Return Value

ossPrintASN1DescriptionOfPDU() does not return a value.

See Also

ossPrintPDUs()


void ossPrintASN1DescriptionOfType(OssGlobal *world, TypeHndl type, ossBoolean refTypes);

Generates and prints the ASN.1 source (type notation) for a particular type in the input ASN.1 specification given its type handle.

Arguments

world
Pointer to the OSS global environment variable.
type
Handle of the type whose ASN.1 source you want to print.
refTypes
The ossBoolean variable that specifies whether or not the description of user-defined types referenced by the specified PDU should also be printed (i.e. the description of referenced user-defined types is also printed after the specified PDU if refTypes is TRUE).

Return Value

ossPrintASN1DescriptionOfType() does not return a value.

See Also

ossPrintPDUs()


void ossPrintDecodedValueOfPDU(OssGlobal *world, int pduNum, void *decodedValue);

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.

Arguments

world
Pointer to the OSS global environment variable.
pduNum
A compiler-assigned PDU number of the type whose associated value notation you wish to print.
decodedValue
Address of the value of the type in decoded internal format to print.

Return Value

ossPrintDecodedValueOfPDU() does not return a value.

See Also

ossPrintDecodedValueOfPDUByName()


void ossPrintDecodedValueOfPDUByName(OssGlobal *world, TypeHndl type, char *name, void *decodedValue);

Generates and prints the ASN.1 source (value notation) for a particular PDU in the input ASN.1 specification given its type handle.

Arguments

world
Pointer to the OSS global environment variable.
type
Type handle of the value reference whose value notation you wish to print.
name
Any name that you wish to print as the value reference in the value notation.
decodedValue
Address of the value in decoded internal format to print.

Return Value

ossPrintDecodedValueOfPDUByName() does not return a value.

Example

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.


void ossPrintDecodedValuesOfPDUs(OssGlobal *world);

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.

Arguments

world is a pointer to the global OSS environment variable.

Return Value

ossPrintDecodedValuesOfPDUs() does not return a value.

See Also

ossPrintDecodedValueOfPDUByName()


void ossPrintDecodedValueOfType(OssGlobal *world, TypeHndl type, void *decodedValue);

Prints the value of an ASN.1 type in display format given the type's handle and value in decoded internal format.

Arguments

world
Pointer to the OSS global environment variable.
type
Type handle the ASN.1 type whose value you wish to print.
decodedValue
Address of the value in decoded internal format to print.

Return Value

ossPrintDecodedValueOfType() does not return a value.

Example

Refer to the example in the ossGetDecodedValueOfValueReference() section.


void ossPrintEncodingInDecomposedTLV(OssGlobal *world, OssBuf *encodedValue);

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.

Arguments

world
Pointer to the OSS global environment variable.
encodedValue
Address of an OssBuf structure whose value field points to the buffer containing the BER/DER encoding and whose length field holds the length in bytes of the encoding.

Return Value

ossPrintEncodingInDecomposedTLV() does not return a value.

See Also

ossPrintEncodingInTLV()


void ossPrintEncodingInHexTLV(OssGlobal *world, OssBuf *encodedValue);

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.

Arguments

world
Pointer to the OSS global environment variable.
encodedValue
Address of an OssBuf structure whose value field points to the buffer containing the BER/DER encoding to be printed and whose length field holds the length in bytes of the encoding.

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.

Return Value

ossPrintEncodingInHexTLV() does not return a value.

See Also

ossPrintEncodingInTLV()


void ossPrintEncodingInSyntaxTLV(OssGlobal *world, OssBuf *encodedValue);

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.

Arguments

world
Pointer to the OSS global environment variable.
encodedValue
Address of an OssBuf structure whose value field points to the buffer containing the BER/DER encoding to be printed and whose length field holds the length in bytes of the encoding.

Return Value

ossPrintEncodingInSyntaxTLV() does not return a value.

See Also

ossPrintEncodingInTLV()


void ossPrintEncodingInTLV(OssGlobal *world, unsigned long flags, OssBufExtended *inbuf);

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:

  • CDR files with a 3GPP header. The 3GPP header typically occupies 50 or 54 octets; the first four octets hold the file length, and octets 5 through 8 hold the file header length. Each CDR consists of a CDR record header and a BER-based encoded message. The first two octets hold the record data length, and the next two or three octets hold the record identifiers. NOTE: The 3GPP header is also known as the CDR file header.
  • CDR files consisting of CDR records that include a CDR record header and a BER-based encoded message. The first two octets of a CDR record header hold the record identifiers, and the next two octets hold the record data length. Each record can be placed inside fixed-size blocks that are filled with 00 or FF padding bytes.

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.

Arguments

world
Pointer to the OSS global environment variable.
flags
One or more of the following literals separated by vertical bars ('|'):
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.

Remarks

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.

Return Value

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.


void ossPrintPDUs(OssGlobal *world);

Generates and prints the ASN.1 source (type notation) for all PDUs in the input ASN.1 specification.

Arguments

world is a pointer to the global OSS environment variable.

Return Value

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:

  • Input compiler directives are not generated by ossPrintPDUs().
  • When the -per ASN.1 compiler option is specified, the order of the alternatives in a CHOICE cannot be preserved (due to the sort that takes place).
  • The constraints for types marked with the OSS.LINKED or OSS.DLINKED directive are not printed.

Functions that check for data consistency and length

ossBoolean ossCheck8601Time(OssGlobal *world, TypeHndl type, char *stime, int *errpos);

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:2015 | ISO/IEC 8824-1:2015. 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:2015, 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.

Arguments

world
Pointer to the global OSS environment variable.
type
Handle of the time type that, if it is one of useful time types (DATE, DATE-TIME, DURATION, or TIME-OF-DAY), must be compatible with and checked for valid structure against the passed value, or NULL if all valid time formats are permitted.
stime
Pointer to the time value as a string to be checked for validity of its general structure and characters.
errpos
Pointer which will contain the position of the first invalid character if the input string has an invalid format.

Return Value

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:2015, 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.


unsigned long ossGetValueLength(OssGlobal *world, TypeHndl type, void *decodedValue);

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.

Arguments

world
Pointer to the OSS global environment variable.
type
Type handle referencing the ASN.1 type whose decoded length you wish to determine.
decodedValue
The value of the ASN.1 type in decoded internal format.

Return 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

TypesCompatibilityCodes ossTypesCompatible(OssGlobal *world, TypeHndl *type1, TypeHndl *type2);

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).

Arguments

world
Pointer to the OSS global environment variable.
type1 type2
Type handle of the two types which you wish to compare for compatibility.

Return Value

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.

ossBoolean ossValueIsValid(OssGlobal *world, TypeHndl type, void *value);

Determines whether or not a decoded value is compatible with a certain type and whether or not it satisfies all applied constraints.

Arguments

world
Pointer to the OSS global environment variable.
type
Handle of the type that the passed value has to be compatible with and checked for validity against.
value
Pointer to the decoded value to be checked for validity/compatibility with the specified type.

Return Value

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.

Remarks

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 shipment (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.


Functions that copy, compare, and initialize values

IAAPI_ERRTYPE ossCmpTypeValue(OssGlobal *world, TypeHndl type, void *value1, void *value2);

Compares two decoded values of the same simple or structured ASN.1 type.

Arguments

world
Pointer to the OSS global environment variable.
type
Type handle of the values you wish to compare.
value1
Address of the first decoded value you wish to compare.
value2
Address of the second value you wish to compare.

Return Value

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.


IAAPI_ERRTYPE ossCopyTypeValue(OssGlobal *world, TypeHndl type, void *valueIn, void **valueOut);

Copies a decoded value (simple or structured) into a new identical data structure.

Arguments

world
Pointer to the OSS global environment variable.
type
Type handle of the data you wish to copy.
valueIn
Address of the decoded value you wish to copy.
valueOut
Address of a NULL pointer which will contain the copied value. You can free the memory allocated for valueOut by a call to ossFreeDecodedValue().

Return Value

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.


IAAPI_ERRTYPE ossCreateUnencodedValueOfPDU (OssGlobal *world, int pduNum, void **pduValue);

Creates an instance of the input PDU in the internal format which can be understood by the encoder/decoder and by other IAAPI functions.

Arguments

world
Pointer to the OSS global environment variable.
pduNum
Integer holding the compiler-assigned PDU number of the type whose unencoded instance will be created.
pduValue
Address of a NULL pointer which will contain the unencoded value in the internal format. You can free the memory allocated for pduValue by a call to ossFreeDecodedValue().

Return Value

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.

Remarks

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 type
CHOICE {
    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 type
SEQUENCE {
     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".

IAAPI_ERRTYPE ossCreateUnencodedValueOfType (OssGlobal *world, TypeHndl type, void **value);

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.

Arguments

world
Pointer to the OSS global environment variable.
type
Type handle of the ASN.1 type whose value you wish to create.
value
Address of a NULL pointer which will contain the unencoded value in the internal format. You can free the memory allocated for value by a call to ossFreeDecodedValue().

Return Value

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.


void ossSetInitializationValues(OssGlobal *world, IAAPI_initializers *initStruct);

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.

Arguments

world
Pointer to the OSS global environment variable.
initStruct
Address of a series of values filled in accordance to the IAAPI_initializers structure, which is defined as follows in ossiaapi.h:
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).

Return Value

ossSetInitializationValues() does not return a value.

Example

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);

Functions that free IAAPI resources

IAAPI_ERRTYPE ossFreeDecodedValue(OssGlobal *world, TypeHndl type, void *valPtr);

Frees memory for a decoded value allocated by ossPutSimpleTypeValue(), ossPutStructTypeValue(), ossUpdateValueOfSimpleType(), and similar functions that return a value in decoded internal format.

Arguments

world
Pointer to the OSS global environment variable.
type
Type handle for the decoded value you wish to free.
valPtr
Pointer to the decoded value whose memory will be freed.

Return Value

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.


void ossFreeDisplayString(OssGlobal *world, char *displayString);

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).

Arguments

world
Pointer to the OSS global environment variable.
displayString
Pointer referencing the memory area to free returned by one of the IAAPI functions.

Return Value

ossFreeDisplayString() does not return a value.


void ossTermIAAPI(OssGlobal *world);

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.

Arguments

world is a pointer to the global OSS environment variable.

Return Value

ossTermIAAPI() does not return a value.

Remarks

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.)


Functions that handle IAAPI errors

int ossDefaultIAAPI_ERR(OssGlobal *world, int err_code, char *parm, long num);

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).

Arguments

world
Pointer to the OSS global environment variable.
error_code
One of the IAAPI_ERRTYPE enumerators listed in the IAAPI Error Codes section.
parm
Pointer of type char whose significance is explained in the ossSetIaapiErrorHandlingFunction() section.
num
A long integer whose significance is explained the ossSetIaapiErrorHandlingFunction() section.

Return Value

ossDefaultIAAPI_ERR() returns the err_code value that was passed in its second argument.


char *ossDescribeIaapiReturnCode(OssGlobal *world, int retcode);

Is used to get a textual generic description of the numeric return code obtained from any IAAPI function.

Arguments

world
Pointer to the OSS global environment variable.
retcode
Integer variable that contains the return code obtained from any IAAPI function.

Return Value

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.


char *ossGetIaapiErrMsg(OssGlobal *world);

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().

Arguments

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);

Return Value

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.

Example

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));

See Also


void *ossGetIaapiErrorHandlingFunction(OssGlobal *world);

Returns the address of the current error message handling function that the IAAPI is set to use.

Arguments

world is a pointer to the global OSS environment variable.

Return Value

ossGetIaapiErrorHandlingFunction() returns a function pointer referencing the current error message builder/handler function.


int ossIaapiErrMsgHandle (OssGlobal *world, int err_code, char *parm, long num);

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.

Arguments

world
Pointer to the OSS global environment variable.
error_code
One of the IAAPI_ERRTYPE enumerators listed in the IAAPI Error Codes section.
parm
Pointer of type char.
num
A long integer.

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);

Return Value

ossIaapiErrMsgHandle() returns the error_code value that was passed to it as its second parameter.

See Also


void ossSetIaapiErrorHandlingFunction(OssGlobal *world, int (*userErrFunc)(OssGlobal *world, int error_code, char *parm, long num));

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.

Arguments

world
Pointer to the OSS global environment variable.
userErrFunc
Function pointer referencing the error handling function that the IAAPI should invoke in the case of an error.

Return Value

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);

Arguments

world
Pointer to the OSS global environment variable.
error_code
One of the IAAPI_ERRTYPE enumerators listed in the IAAPI Error Codes section.
parm
Pointer of type char whose significance is explained below.
num
A long integer whose significance is also explained below.

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.)

Functions that improve performance and support user-allocated values

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.

iaapiCtype ossCtypeId(OssGlobal *world, TypeHndl type);

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.

Arguments

world
Pointer to the OSS global environment variable.
type
Type handle of the ASN.1 type whose C representation type you wish to know.

Return Value

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:

ia_bool
An ossBoolean type defined as char.
ia_int
A signed char, short, int, long or long long integer type; the ossCtypeLengthSize() function can be used to determine the actual integer representation.
ia_uint
An unsigned char, short, int, long or long long integer type, the ossCtypeLengthSize() function can be used to determine the actual integer representation.
ia_huge_int
A structure with a length field and a pointer to a huge integer value in a special format:
 struct HugeInteger{
    unsigned short  length;
    unsigned char   *value;
};
ia_enum
In most cases, this corresponds to a signed integer of 4 bytes. The actual number of bytes occupied by this integer can be obtained by a call to the ossCtypeLengthSize() function.
ia_uenum
In most cases it corresponds to an unsigned integer of 4 bytes. The actual number of bytes occupied by this integer can be obtained by a call to the ossCtypeLengthSize() function.
ia_null
A Nulltype type defined as char.
ia_real
A float or double type. The actual type can be determined based upon the value returned by the ossCtypeLengthSize() function.
ia_char_real
Pointer to the char string containing a real value; for example: "1.E2".
ia_mixed_real
A MixedReal structure defined as follows:
  enum MixedReal_kind {OSS_BINARY, OSS_DECIMAL};
typedef struct {
  enum MixedReal_kind kind;
  union {
      double base2;
      char  *base10;
  } u;
} MixedReal;
ia_pad_bit
A single char generated for BIT STRING types defined with the OSS.PADDED directive and a size constraint whose upper bound fits a char type.
ia_big_pad_bit
An array of chars generated for BIT STRING types defined with the OSS.PADDED directive and a large upper bounded size constraint.
ia_pad_char
A char array generated for CharacterString types defined with the OSS.PADDED directive (padded CharacterString types are always size constrained).
ia_unbnd_bit, ia_unbnd_octet, ia_unbnd_char
An unbounded bit, octet, or character string generated for BIT STRING, OCTET STRING, or CharacterString types defined with the OSS.UNBOUNDED directive:
       struct UnboundedStr{
            unsigned int    length;
            unsigned char   *value;
       };
ia_vary_bit, ia_vary_octet
A varying bit or octet string generated for BIT STRING or OCTET STRING types defined with an OSS.VARYING directive:
       struct VaryingStr {
            unsigned short  length; 
            unsigned char   value[1];  /* first element of the array */
       };
ia_vary_char
A varying character string generated for CharacterString with the VARYING directive:
       struct VaryingStr {
            unsigned short  length; 
            char                  value[1];  /* first element of the array */
       };
ia_nlltrm_char
Pointer to the null-terminated character string.
ia_array_objid
A structure containing a count field that identifies the number of subidentifiers and an array of subidentifier values.
	struct ArrayObjid {
      	    unsigned short  count;
           unsigned short  value[1];
    };  
ia_unbnd_objid
A structure containing a count field that identifies the number of subidentifiers and a pointer to the subidentifiers' values.
	struct UnboundedObjid {
      	    unsigned short  count;
           unsigned short  *value;
    };  
ia_encoded_objid
A structure containing a length field and a pointer to the encoded values of the contained subidentifiers.
typedef struct EncodedObjid {
    unsigned short  length;
    unsigned char   *value;
};
ia_encoded_reloid
A structure containing a length field and a pointer to encoded values of subidentifiers of RELATIVE-OID.
typedef struct OssReativeOid {
    unsigned short  length;
    unsigned char   *value;
};
ia_utc_time and ia_gen_time
Have the same structure:
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 */
ia_2byte_char
A structure with a length field and a pointer to unsigned short values:
	struct Char2bytes{
		unsigned int    length;
   		unsigned short  *value;
    };
ia_4byte_char
A structure with a length field and a pointer to int values:
struct Char4bytes{
	unsigned int    length;
	int                  *value;
};
ia_opentype
An OpenType structure defined as follows:
typedef struct {
  int            pduNum;
  long           length;       /* length of encoded */
  void          *encoded;
  void          *decoded;
} OpenType;
ia_any
An Any structure defined as follows:
typedef struct Any {
    unsigned long   length;
    unsigned char   *value;
} Any;
ia_set, ia_seq, ia_choice, ia_setof, ia_seqof
C types for complex ASN.1 types SET, SEQUENCE, CHOICE, SET OF and SEQUENCE OF are provided only to avoid extra calls to the ossAsn1TypeId() function. Structures for these types can be allocated only by calling the ossPutStructTypeValue() IAAPI function.
ia_nlltrm_date_time
Pointer to the null-terminated string containing the value of an ISO 8601 time type.
ia_fixed_octet
An array of unsigned chars generated for OCTET STRING types defined with the OSS.PADDED directive and a fixed size constraint.

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

See Also

ossCtypeLengthSize()


unsigned short ossCtypeLengthSize(OssGlobal *world, TypeHndl type);

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.

Arguments

world
Pointer to the OSS global environment variable.
type
Type handle of a simple type whose byte-length you wish to know.

Return Value

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];
};

IAAPI_ERRTYPE ossFreeNonUserDecodedValue(OssGlobal *world, TypeHndl type, void *valPtr);

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.

Arguments

world
Pointer to the OSS global environment variable.
type
Type handle for the decoded value you wish to free.
valPtr
Pointer to the decoded value whose memory will be freed (if you are using a version prior to 7.0, you have to take into account possible user-allocated nested values that are never freed).

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.

Return Value

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.

See Also


unsigned long ossGetIAAPIFlags(OssGlobal *world);

Returns the flags set by the ossSetIAAPIFlags() function.

Arguments

world is a pointer to the global OSS environment variable.

Here are the flags that can be returned:

  • IAAPI_IGNORE_COMPLEX_CONSTRAINTS
  • IAAPI_NOSIGNAL
  • IAAPI_NOSETJMP
  • IAAPI_NOCONSTRAIN
  • IAAPI_DONT_PRINT_REFERENCED_TYPES
  • IAAPI_INIT_OPTIONALS
  • IAAPI_NODEFAULT_VALUES
  • IAAPI_NONAMED_ITEMS
  • IAAPI_PRINT_ERRMSG
  • IAAPI_PRINT_REAL_VALUES_USING_BRACE_NOTATION
  • A logical OR of these flags. If IAAPI_NOSETJMP is set, then IAAPI_NOSIGNAL is also set (but not vice versa)

Return Value

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.


IAAPI_ERRTYPE ossPutStructTypeUserValue(OssGlobal *world, TypeHndl parentType, void *compUserValue, unsigned int compIndex, void **structToUpdate);

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.

Remarks

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.

Arguments

world
Pointer to the OSS global environment variable.
parentType
Type handle of the structured ASN.1 type whose component value you want to change.
compUserValue
Pointer to the user-allocated value that you wish to assign to a component of a structured type.
compIndex
Index of the component to modify within the parent structure.
structToUpdate
Pointer which will reference the output parent structure with the modified component value. If structToUpdate is NULL, memory will be automatically allocated for a new structure and this memory can later be freed by a call to ossFreeNonUserDecodedValue().

Return Value

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.

See Also


void ossRemoveUserValue(OssGlobal *world, void *valPtr);

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.

Arguments

world
Pointer to the OSS global environment variable.
valPtr
Pointer to the user-allocated value used in calls to ossPutStructTypeUserValue() or ossUpdateStructTypeUserValue() whose information will be removed from the IAAPI environment (taking into account that the user-allocated value itself is never freed by the IAAPI).

Return Value

This function does not return a value.

See Also


void ossRemoveUserValues(OssGlobal *world);

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.

Arguments

world is a pointer to the global OSS environment variable.

Return Value

This function does not return a value.

See Also


int ossSetIAAPIFlags(OssGlobal *world, unsigned long flags);

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.

Arguments

world
Pointer to the OSS global environment variable.
flags
One or more of the following literals separated by ("|"): IAAPI_NOSIGNAL, IAAPI_NOSETJMP, IAAPI_NOCONSTRAIN, IAAPI_DONT_PRINT_REFERENCED_TYPES, IAAPI_IGNORE_COMPLEX_CONSTRAINTS. To disable all flags, pass a value of zero for the flags argument.
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 / 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_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);

Return Value

This function returns an integer. Upon a successful call, a value of zero is returned; otherwise, a non-zero value is returned.

See Also

ossGetIAAPIFlags()


ossBoolean ossCtypeHasPointerDirective(OssGlobal *world, TypeHndl type);

Returns TRUE if the type is defined with the POINTER directive.

Arguments

world
Pointer to the OSS global environment variable.
type
Type handle of the ASN.1 type whose C representation type you wish to know.

Return Value

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.


IAAPI_ERRTYPE ossUpdateStructTypeUserValue(OssGlobal *world, TypeHndl parentType, void *compUserValue, unsigned int compIndex, void **structToUpdate);

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.

Remarks

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.

Arguments

world
Pointer to the OSS global environment variable.
parentType
Type handle of the original structure ASN.1 type whose component value you desire to change.
compUserValue
Pointer to the user-allocated value that you wish to assign to a component of a structured type.
structToUpdate
Pointer which will reference the output parent structure with the modified component value. If structToUpdate is NULL, memory will be automatically allocated for a new structure and this memory can later be freed by a call to ossFreeNonUserDecodedValue().

Return Value

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.

See Also

Example

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;
}

Example

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.


Functions for information object classes and their fields

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:

  • Functions that return information about information object classes defined in the input ASN.1 notation. The functions allow you to get the IAAPI TypeHndl of an information class (which is analogous to the IAAPI TypeHndl of ASN.1 types (for example, SEQUENCE, etc.). All IAAPI functions (except functions that parse ASN.1 syntax notations) such as ossNumberOfNamedItems() or ossTypeHandleOfComponent() have been modified to return information about the fields within information object classes and information objects. The latter are considered as "decoded values" of information object classes.
  • Functions to access all information object sets defined in the input ASN.1 notation including information about objects they contain and about whether or not object sets are extensible.
  • Functions to access information stored in simple table and component relation constraints.
  • Functions to access specifics about information object notation from complex structured types
  • Functions for performing manipulations on extensible information object sets.
  • Functions to determine types stored in open types based on component relation constraint.

Additionally, an IAAPI FieldHndl identifies components within SET, SEQUENCE, SET OF, SEQUENCE OF, CHOICE and CLASS structures. It is used in several functions.


IAAPI_ERRTYPE ossGetInfoObjSetCarriedByClassFieldValue(OssGlobal *world, FieldHndl field, void **objSet, void *fieldValue);

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.

Arguments

world
Pointer to the OSS global environment variable.
field
The field handle of an ObjectSetField within an information object.
objSet
Address of a pointer which will reference the returned information object set upon exit.
fieldValue
The value of the field containing the address of the information object set.

Return Value

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.


IAAPI_ERRTYPE ossGetTypeHandleCarriedByClassFieldValue(OssGlobal *world, FieldHndl field, TypeHndl **type, void *fieldValue);

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.

Arguments

world
Pointer to the OSS global environment variable.
field
The field handle of TypeField, FixedTypeValueSetField, or VariableTypeValueSetField within an information object.
type
Is set upon exit to the type handle of the type with the sent fieldValue.
fieldValue
The value of the field containing the type handle of the actual type or the type handle of the value set.

Return Value

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.


int ossInfoObjClassFieldId(OssGlobal *world, FieldHndl field);

Determines the type of field within an information object class. The field is identified by its field handle.

Arguments

world
Pointer to the OSS global environment variable.
field
The field handle of an information object class field that you want to identify.

Return Value

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
}

ossBoolean ossInfoObjClassFieldIsUnique(OssGlobal *world, FieldHndl field);

Determines whether or not a field within an information object class is marked as UNIQUE.

Arguments

world
Pointer to the OSS global environment variable.
field
The field handle of the field within an information object class (for example, obtained via the ossGetComponentInfoObjClassFieldHandle() function).

Return Value

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.


TypeHndl ossTypeHandleOfInfoObjClassByIndex(OssGlobal *world, unsigned int ix);

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.

Arguments

world
Pointer to the OSS global environment variable.
ix
Index of the information object class in the list of all information object classes defined in the input ASN.1 notation. The index starts at zero.

Return Value

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.


TypeHndl ossInfoObjClassTypeHandleByName(OssGlobal *world, const char *name)

Returns the type handle of the information object class identified by its ASN.1 name in the input ASN.1 notation.

Arguments

world
Pointer to the OSS global environment variable.
name
The information object class name in the input ASN.1 notation.

Return Value

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.


int ossNumberOfInfoObjClasses(OssGlobal *world);

Returns the number of information object classes defined in the input ASN.1 specification.

Arguments

world is a pointer to the global OSS environment variable.

Return Value

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.


char *ossObjectClassFieldTypeNotationOfConstrainedType(OssGlobal *world, TypeHndl type);

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.

Arguments

world
Pointer to the OSS global environment variable.
type
Type handle for the type with a table or component relation constraint that is defined using an ObjectClassFieldType notation.

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})}

Return Value

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.


IAAPI_ERRTYPE ossPutInfoObjSetCarriedByClassFieldValue(OssGlobal *world, FieldHndl field, void *objSet, void **fieldValue);

Creates a value for an ObjectClassField containing a specified information object set address.

Arguments

world
Pointer to the OSS global environment variable.
field
The field handle of the ObjectSetField within an information object.
objSet
Pointer to the information object set to be inserted into the ObjectSetField value.
fieldValue
Contains the value of the field containing the address of the information object set upon exit.

Return Value

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.


IAAPI_ERRTYPE ossPutTypeHandleCarriedByClassFieldValue(OssGlobal *world, FieldHndl field, TypeHndl type, void **fieldValue);

Creates the value of a TypeField, FixedTypeValueSetField, or VariableTypeValueSetField containing a specified type handle unique identifier inside an information object.

Arguments

world
Pointer to the OSS global environment variable.
field
The field handle of TypeField, FixedTypeValueSetField, or VariableTypeValueSetField within an information object.
type
Type handle of the actual type or of the value set type whose unique identifier will be inserted into the field value.
fieldValue
will hold upon exit the value of the field containing the type handle of the specified type or the type handle of the specified value set.

Return Value

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.


FieldHndl ossTypeFieldHandleRelativeToVariableTypeField(OssGlobal *world, FieldHndl field);

Returns the field handle of a TypeField relative to the specified VariableTypeField inside an information object class.

Arguments

world
Pointer to the OSS global environment variable.
field
The field handle of VariableTypeField within an information object class that is relative to the type field whose field handle you wish to learn of.

Return Value

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.


Functions for information object sets and information objects

IAAPI_ERRTYPE ossAddInfoObjectByIndex(OssGlobal *world, unsigned int from_oset_ix, unsigned int to_oset_ix, unsigned int obj_ix);

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.

Arguments

world
Pointer to the OSS global environment variable.
from_oset_ix
Index of an extensible information object set in the list of all information object sets defined in the input ASN.1 notation and used in table or component relation constraints that includes the object that you would like to add into another information object set.
to_oset_ix
Index of an extensible information object set in the list of all information object sets that you wish to add an object to.
obj_ix
Index of the particular information object in the source object set that you wish to add.

Return Value

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.


IAAPI_ERRTYPE ossAddInfoObjectByName(OssGlobal *world, const char *oset_name, const char *obj_name);

Adds an information object identified by its name to an extensible information object set identified by its name.

Arguments

world
Pointer to the OSS global environment variable.
oset_name
The ASN.1 name of the containing information object set.
obj_name
The name of the particular information object you wish to add.

Return Value

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.


IAAPI_ERRTYPE ossGetInfoObjectByFieldValue(OssGlobal *world, FieldHndl field, void *fld_value, void **prev_obj);

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.

Arguments

world
Pointer to the OSS global environment variable.
fieldHndl
The field handle of a field within a SET or SEQUENCE that has a table or a component relation constraint.
fld_value
The value of the field identified by FieldHndl. If prev_obj is set to NULL, then the first matching information object is returned; if prev_obj is not NULL, it must refer to a valid information object obtained by a previous call to ossGetInfoObjectByFieldValue(), and in such a case the next matching information object is returned.

Return Value

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.


IAAPI_ERRTYPE ossGetInfoObjectByIndex(OssGlobal *world, unsigned int oset_ix, unsigned int obj_ix, void **object);

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.

Arguments

world
Pointer to the OSS global environment variable.
oset_ix
Index of the information object set from which you wish to retrieve an object. The index starts at zero.
obj_ix
Index of a particular information object you wish to retrieve. The index starts at zero.
object
Contains the address of the information object value upon exiting the function.

After obtaining the information object, you can use functions for handling decoded values to access the values of contained fields.

Return Value

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.


IAAPI_ERRTYPE ossGetInfoObjectByName(OssGlobal *world, const char *oset_name, const char *obj_name, void **object);

Returns the address of an information object identified by its ASN.1 name within the information object set identified by its ASN.1 name.

Arguments

world
Pointer to the OSS global environment variable.
oset_name
The name of the information object set from which you wish to retrieve an object.
obj_name
The name of the information object you wish to retrieve.
object
Contains the address of the requested information object upon exit.

After obtaining the information object, you can use functions for handling decoded values to access the values of contained fields.

Return Value

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.


IAAPI_ERRTYPE ossGetNextInfoObject(OssGlobal *world, void *objSet, void **object);

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.

Arguments

world
Pointer to the OSS global environment variable.
objSet
The information object set from which you wish to retrieve an object.
object
On exit, it will contain the address of the first information object (if it points to NULL on entering) or the address of the next information object after the one passed in the last parameter on entering.

Return Value

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.


IAAPI_ERRTYPE ossGetNextInfoObjectAndName(OssGlobal *world, void *objSet, void **object, const char **name);

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.

Arguments

world
Pointer to the OSS global environment variable.
objSet
The information object set from which you wish to retrieve an object.
object
On exit, it will contain the address of the first information object (if it points to NULL on entering) or the address of the next information object after the one passed in the last parameter on entering, and the name of the object if it is a defined object.

Return Value

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.


const char *ossInfoObjectName(OssGlobal *world, unsigned int oset_ix, unsigned int obj_ix);

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).

Arguments

world
Pointer to the OSS global environment variable.
oset_ix
Index of the information object set from which you wish to retrieve the name of the object. The index starts at zero.
obj_ix
Index of the particular information object whose name you wish to retrieve. The index starts at zero.

Return Value

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.


void *ossGetInfoObjSetHandle(OssGlobal *world, unsigned int objSetIndex);

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.

Arguments

world
Pointer to the OSS global environment variable.
objSetIndex
The information object set index.

Return Value

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.


unsigned int ossGetInfoObjSetIndex(OssGlobal *world, void *objSet);

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.

Arguments

world
Pointer to the OSS global environment variable.
objSet
Address of the information object set.

Return 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.


unsigned int ossGetInfoObjSetIndexByName(OssGlobal *world, const char *name);

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.

Arguments

world
Pointer to the OSS global environment variable.
name
The name of the information object set in the input ASN.1 notation.

Return 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.


ossBoolean ossInfoObjSetIsExtensible(OssGlobal *world, unsigned int ix);

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.

Arguments

world
Pointer to the OSS global environment variable.
ix
Index of the information object set. The index starts at zero.

Return Value

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.


const char *ossInfoObjSetName(OssGlobal *world, unsigned int ix);

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.

Arguments

world
Pointer to the OSS global environment variable.
ix
Index of the information object set in the list of all information object sets in the input ASN.1 notation. The index starts at zero.

Return Value

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.


TypeHndl ossInfoObjSetTypeHandle(OssGlobal *world, unsigned int ix);

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.

Arguments

world
Pointer to the OSS global environment variable.
ix
Index of the information object set in the list of all information object sets in the input ASN.1 notation. The index starts at zero.

Return Value

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.


int ossNumberOfInfoObjects(OssGlobal *world, unsigned int oset_ix);

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.

Arguments

world
Pointer to the OSS global environment variable.
oset_ix
Index of the information object set. The index starts at zero.

Return Value

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.


int ossNumberOfInfoObjSets(OssGlobal *world);

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.

Arguments

world is a pointer to the global OSS environment variable.

Return Value

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.


int ossNumberOfRootInfoObjects(OssGlobal *world, unsigned int ix);

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.

Arguments

world
Pointer to the OSS global environment variable.
ix
Index of the information object set for which you wish to know the number of objects that appear before an extension marker. The index starts at zero.

Return Value

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.


IAAPI_ERRTYPE ossRemoveInfoObjectByIndex(OssGlobal *world, unsigned int oset_ix, unsigned int obj_ix);

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.

Arguments

world
Pointer to the OSS global environment variable.
oset_ix
Index of an extensible information object set in the list of all information object sets defined in the input ASN.1 notation.
obj_ix
Index of the particular information object you wish to remove.

Return Value

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.


IAAPI_ERRTYPE ossRemoveInfoObjectByName(OssGlobal *world, const char *oset_name, const char *obj_name);

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.

Arguments

world
Pointer to the OSS global environment variable.
oset_name
The ASN.1 name of the containing information object set.
obj_name
The name of the particular information object you wish to remove.

Return Value

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.


Functions that handle table and component relation constraints

NOTE: The FieldHndl handle references simple table and component relation constraints.

FieldHndl ossComponentFieldHandle(OssGlobal *world, TypeHndl type, unsigned int ix);

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.

Arguments

world
Pointer to the OSS global environment variable.
type
Type handle of the containing SEQUENCE, SET, CHOICE, or CLASS.
ix
Index of the component. The index starts at zero.

Return Value

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.


unsigned int ossComponentIndexByFieldHandle(OssGlobal *world, FieldHndl field)

Returns the index of the component identified by its FieldHndl within a SEQUENCE, SET, CHOICE or information object class.

Arguments

world
Pointer to the OSS global environment variable.
field
The component field handle within a SEQUENCE, SET, CHOICE, or CLASS whose index needs to be retrieved.

Return Value

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.


FieldHndl ossComponentInfoObjClassFieldHandle(OssGlobal *world, FieldHndl field);

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).

Arguments

world
Pointer to the OSS global environment variable.
fieldHndl
The field handle of a field within a SEQUENCE, SET, or CHOICE whose type has an object class field type notation applied.

Return Value

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.


TypeHndl ossComponentInfoObjClassTypeHandle(OssGlobal *world, FieldHndl field);

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.

Arguments

world
Pointer to the OSS global environment variable.
fieldHndl
The field handle of the component within a SEQUENCE, SET, or CHOICE (whose type has an object class field type notation) for which you wish to obtain the type handle of the information object class specified as the base class in the object class field notation.

Return Value

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./


unsigned int ossComponentInfoObjSetIndex(OssGlobal *world, FieldHndl field);

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.

Arguments

world
Pointer to the OSS global environment variable.
fieldHndl
The field handle of a field within a SEQUENCE, SET, or CHOICE with a simple table constraint or component relation constraint applied for which you wish to obtain the index of the information object set constraining its type.

Return Value

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.


TypeHndl ossComponentParentTypeHandle(OssGlobal *world, FieldHndl field)

Returns the type handle of the parent of a component identified by its FieldHndl within a SEQUENCE, SET, CHOICE or information object class.

Arguments

world
Pointer to the OSS global environment variable.
field
The field handle of the component within a SEQUENCE, SET, CHOICE or CLASS whose parent type handle needs to be retrieved.

Return Value

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.


const char *ossFieldNameByFieldHandle(OssGlobal *world, FieldHndl field)

Returns the identifier of the component identified by its FieldHndl within a SEQUENCE, SET, CHOICE or information object class.

Arguments

world
Pointer to the OSS global environment variable.
field
The field handle of the component within a SEQUENCE, SET, CHOICE, or CLASS whose identifier needs to be retrieved.

Return Value

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.


IAAPI_ERRTYPE ossGetTypeHandleOfActualTypeCarriedByOpenType(OssGlobal *world, FieldHndl constr_field, FieldHndl ref_field, void *ref_field_value, TypeHndl *actual_type);

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.

Arguments

world
Pointer to the OSS global environment variable.
constr_field
The field handle of the field within a SET, SEQUENCE, SET OF, or SEQUENCE OF that has a component relation constraint.
ref_field
The field handle of the referenced field (appears within the @-notation of constr_field) whose value is passed in the third parameter.
ref_field_value
The value of the referenced field.
actual_type
Type handle of the actual type whose value can be carried by the open type value of the constr_field field. If the last parameter contains a non-NULL pointer, it must be a valid type handle received from a previous call to ossGetTypeHandleOfActualTypeCarriedByOpenType(). In this case, the type handle of the actual type specified in the next encoding object within a constraining information object is returned.

Return Value

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.


ossBoolean ossHasComponentRelationConstraint(OssGlobal *world, TypeHndl type, unsigned int ix);

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.

Arguments

world
Pointer to the OSS global environment variable.
type
Type handle of the SEQUENCE, SET or CHOICE the component belongs to.
ix
Index of the component for which you wish to know whether it has a component relation constraint. The index starts at zero.

Return Value

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.


ossBoolean ossHasTableConstraint(OssGlobal *world, TypeHndl type, unsigned int ix)

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.

Arguments

world
Pointer to the OSS global environment variable.
type
Type handle of the parent SEQUENCE, SET, or CHOICE.
ix
Index of the field for which you wish to know whether or not it has a simple table constraint. The index starts at zero.

Return Value

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.


int ossNumberOfReferencedComponents(OssGlobal *world, FieldHndl field);

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.

Arguments

world
Pointer to the OSS global environment variable.
fieldHndl
The field handle of a field within a SEQUENCE or SET with a component relation constraint applied.

Return Value

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.


int ossNumberOfReferencingComponents(OssGlobal *world, FieldHndl field);

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).

Arguments

world
Pointer to the OSS global environment variable.
fieldHndl
The field handle of a field within a SEQUENCE or SET that is referenced in one or more component relation constraints of some other fields.

Return Value

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.

Remarks

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})
}

FieldHndl ossReferencedComponentFieldHandle(OssGlobal *world, FieldHndl field, unsigned int ix);

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).

Arguments

world
Pointer to the OSS global environment variable.
field_handle
The field handle of a field within a SEQUENCE or SET with a component relation constraint applied.
ix
Index of the referenced field whose handle you desire. The index starts at zero.

Remarks

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})
}

Return Value

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.


ossBoolean ossReferencedComponentIsInner(OssGlobal *world, FieldHndl field, unsigned int ix);

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.

Arguments

world
Pointer to the OSS global environment variable.
field
The field handle of a field within a SEQUENCE or SET with a component relation constraint applied.
ix
Index of the referenced field for which you wish to determine whether or not it appears within the innermost enclosing SEQUENCE or SET. The index starts at zero.

Return Value

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.


int ossReferencedComponentScope(OssGlobal *world, FieldHndl field_handle, unsigned int ix);

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.

Arguments

world
Pointer to the OSS global environment variable.
type
The field handle of a field within a SEQUENCE, SET, or CHOICE with a component relation constraint applied.
ix
Index of the referenced field for which you wish to determine the scope. The index starts at zero. Referenced fields and fields with component relation constraint where they are included in the AtNotation are within the same SET or SEQUENCE type, possibly at a different level of nesting.

Return Value

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.


ossBoolean ossReferencedInComponentRelationConstraint(OssGlobal *world, TypeHndl type, unsigned int ix);

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.

Arguments

world
Pointer to the OSS global environment variable.
type
Type handle of the containing SEQUENCE or SET.
ix
Index of the field for which you wish to know whether or not it is referenced in a component relation constraint of some other field. The index starts at zero.

Return Value

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.


FieldHndl ossReferencingComponentFieldHandle(OssGlobal *world, FieldHndl field, unsigned int ix);

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).

Arguments

world
Pointer to the OSS global environment variable.
field_handle
The field handle of a field within a SEQUENCE or SET that is referenced in one or more component relation constraints.
ix
Index of the referencing field in the list of all referencing fields whose handle you desire. The index starts at zero.

Return Value

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.


TypeHndl ossFieldNameByFieldHandle(OssGlobal *world, FieldHndl field)

Returns the type handle of the component identified by its FieldHndl within a SEQUENCE, SET, CHOICE or information object class.

Arguments

world
Pointer to the OSS global environment variable.
field
The field handle of the component within a SEQUENCE, SET, CHOICE or CLASS whose type handle needs to be retrieved.

Return Value

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.


Functions that retrieve specifics about information object notation from complex structured types

unsigned int ossConstrainingInfoObjSetIndex(OssGlobal *world, TypeHndl type);

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.

Arguments

world
Pointer to the OSS global environment variable.
typeHndl
Type handle of a component within a SEQUENCE, SET, CHOICE, SET OF, or SEQUENCE OF type with a simple table constraint or component relation constraint applied for which you wish to obtain the index of the information object set constraining its type.

Return Value

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.


IAAPI_ERRTYPE ossGetInfoObjectByFieldValueAndTypeHandle(OssGlobal *world, TypeHndl type, void *fld_value, void **prev_obj);

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.

Arguments

world
Pointer to the OSS global environment variable.
typeHndl
Type handle of a field within a SET, SEQUENCE, CHOICE, SET OF, or SEQUENCE OF that has a table or a component relation constraint.
fld_value
The value of the field identified by typeHndl. If prev_obj is set to NULL, the first matching information object is returned; if prev_obj is not NULL, it must refer to a valid information object obtained by a previous call to ossGetInfoObjectByFieldValueAndTypeHandle(), and in this case the next matching information object is returned.

Return Value

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.


IAAPI_ERRTYPE ossGetTypeHandleOfActualTypeCarriedByOpenTypeHandle(OssGlobal *world, TypeHndl constr_type, FieldHndl ref_field, void *ref_field_value, TypeHndl *actual_type);

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.

Arguments

world
Pointer to the OSS global environment variable.
constr_type
Type handle of the field within a SET, SEQUENCE, CHOICE, SET OF, or SEQUENCE OF that has a component relation constraint.
ref_field
The field handle of the referenced field (appears within the @-notation of constr_field) whose value is passed in the third parameter.
ref_field_value
The value of the referenced field.
actual_type
Is the type handle of the actual type whose value can be carried by the open type value of the constr_field field. If the last parameter contains a non-NULL pointer, it must be a valid type handle received from the previous call to ossGetTypeHandleOfActualTypeCarriedByOpenTypeHandle(). In this case, the type handle of the actual type specified in the next encoding object within a constraining information object is returned.

Return Value

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.


FieldHndl ossInfoObjClassFieldHandleOfObjClassFieldType(OssGlobal *world, TypeHndl type);

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.

Arguments

world
Pointer to the OSS global environment variable.
typeHndl
Type handle of a component within a SEQUENCE, SET, CHOICE, SET OF, or SEQUENCE OF type whose type is defined as ObjectClassFieldType.

Return Value

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.


TypeHndl ossInfoObjClassTypeHandleOfObjClassFieldType(OssGlobal *world, TypeHndl 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.

Arguments

world
Pointer to the OSS global environment variable.
typeHndl
Type handle of a component within a SEQUENCE, SET, CHOICE, SET OF, or SEQUENCE OF type whose type is defined as ObjectClassFieldType.

Return Value

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.


int ossNumberOfReferencedComponentsByTypeHandle(OssGlobal *world, TypeHandle type);

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.

Arguments

world
Pointer to the OSS global environment variable.
typeHndl
Type handle of a field within a SEQUENCE, SET, CHOICE, SET OF, or SEQUENCE OF with a component relation constraint applied.

Return Value

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.


FieldHndl ossReferencedComponentFieldHandleByTypeHandle(OssGlobal *world, TypeHndl type, unsigned int ix);

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.

Arguments

world
Pointer to the OSS global environment variable.
type
Type handle of a field within a SEQUENCE, SET, CHOICE, SET OF, or SEQUENCE OF with a component relation constraint applied.
ix
Index of the referenced field whose handle you desire. The index starts at zero.

Return Value

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.


ossBoolean ossReferencedComponentByTypeHandleIsInner(OssGlobal *world, TypeHndl type, unsigned int ix);

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.

Arguments

world
Pointer to the OSS global environment variable.
type
Type handle of a field within a SEQUENCE, SET, CHOICE, SET OF, or SEQUENCE OF with a component relation constraint applied.
ix
Index of the referenced field for which you wish to determine whether or not it appears within the innermost enclosing SEQUENCE or SET. The index starts at zero.

Return Value

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.


int ossReferencedComponentScopeByTypeHandle(OssGlobal *world, TypeHndl type, unsigned int ix);

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.

Arguments

world
Pointer to the OSS global environment variable.
type
Type handle of a field within a SEQUENCE, SET, CHOICE, SET OF, or SEQUENCE OF with a component relation constraint applied.
ix
Index of the referenced field for which you wish to determine the scope. The index starts at zero. Referenced fields and fields with component relation constraint where they are included in the AtNotation are within the same SET or SEQUENCE type, possibly at a different level of nesting.

Return Value

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.


Functions for value sets

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.

IAAPI_ERRTYPE ossGetValueFromValueSet(OssGlobal *world, TypeHndl valueSet, unsigned int value_ix, void **value);

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.

Arguments

world
Pointer to the OSS global environment variable.
valueSet
Type handle of the value set from which you wish to retrieve the value.
value_ix
Index of the particular value you wish to retrieve. The index starts at 0.
object
Contains the address of the desired value upon exit.

Return Value

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.


int ossNumberOfRootValueInValueSet(OssGlobal *world, TypeHndl type);

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.

Arguments

world
Pointer to the OSS global environment variable.
type
Type handle of the value set returned by the ossGetTypeHandleCarriedByClassFieldValue() function.

Return Value

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.


int ossNumberOfValueInValueSet(OssGlobal *world, TypeHndl type);

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.

Arguments

world
Pointer to the OSS global environment variable.
type
Type handle of the value set returned by the ossGetTypeHandleCarriedByClassFieldValue() function.

Return Value

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.


ossBoolean ossValuesFromValueSetNeedPointer(OssGlobal *world, TypeHndl valueSet);

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.

Arguments

world
Pointer to the OSS global environment variable.
valueSet
Type handle of the value set for which you wish to check whether or not its values need a pointer.

Return Value

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.


Functions for printing ASN.1 descriptions of information object classes, object sets, objects and value sets

void ossPrintASN1DescriptionOfCLASS(OssGlobal *world, unsigned int class_ix, ossBoolean refTypes);

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.

Arguments

world
Pointer to the OSS global environment variable.
class_ix
Index of the information object class in the list of all classes specified in the input ASN.1 syntax whose ASN.1 description you want to print.
refTypes
An ossBoolean variable which specifies whether or not the description of defined types referenced by the specified information object class should also be printed (i.e. the description of referenced types is also printed after the specified class if refTypes is TRUE).

Return Value

ossPrintASN1DescriptionOfCLASS() does not return a value.


void ossPrintASN1DescriptionOfInfoObject(OssGlobal *world, unsigned int oset_ix, unsigned int obj_ix);

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.

Arguments

world
Pointer to the OSS global environment variable.
oset_ix
Index of an information object set in the list of all information object sets defined in the input ASN.1 notation.
obj_ix
Index of the particular information object within the information object set you wish to print.

Return Value

ossPrintASN1DescriptionOfInfoObject() does not return a value.


void ossPrintASN1DescriptionOfInfoObjSet(OssGlobal *world, unsigned int oset_ix);

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).

Arguments

world
Pointer to the OSS global environment variable.
oset_ix
Index of an information object set in the list of all information object sets defined in the input ASN.1 notation which you wish to print.

Return Value

ossPrintASN1DescriptionOfInfoObjSet() does not return a value.


void ossPrintInfoObjClasses(OssGlobal *world);

Prints the ASN.1 descriptions for all information object classes in the input ASN.1 specification.

Arguments

world is a pointer to the global OSS environment variable.

Return Value

ossPrintInfoObjClasses() does not return a value.


void ossPrintInfoObject(OssGlobal *world, TypeHndl classType, void *object, int indentLevel);

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.

Arguments

world
Pointer to the OSS global environment variable.
classType
Type handle of the information object class governing the information object you wish to print.
object
Address of the information object you wish to print.
indentLevel
The indent level from which you print the value.

Return Value

ossPrintInfoObject() does not return a value.


void ossPrintInfoObjects(OssGlobal *world);

Prints the ASN.1 descriptions for all information objects defined in the information object assignment in the input ASN.1 specification.

Arguments

world is a pointer to the global OSS environment variable.

Return Value

ossPrintInfoObjSets() does not return a value.


void ossPrintInfoObjSet(OssGlobal *world, TypeHndl classType, void *objSet, int indentLevel);

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.

Arguments

world
Pointer to the OSS global environment variable.
classType
Type handle of the information object class governing the information object set you wish to print.
objSet
Address of the information object set.
indentLevel
The indent level from which you print the value.

Return Value

ossPrintInfoObject() does not return a value.


void ossPrintInfoObjSets(OssGlobal *world);

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).

Arguments

world is a pointer to the global OSS environment variable.

Return Value

ossPrintInfoObjSets() does not return a value.


void ossPrintValueSet(OssGlobal *world, TypeHndl valueSet, int indentLevel);

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.

Arguments

world
Pointer to the OSS global environment variable.
valueSet
Type handle of the value set returned by the ossGetTypeHandleCarriedByClassFieldValue() function.
indentLevel
The indent level from which you print the value.

Return Value

ossPrintValueSet() does not return a value.


Functions for printing ASN.1 descriptions of referenced types

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);

void ossPrintRemainingReferencedTypes(OssGlobal *world);

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.

Arguments

world is a pointer to the global OSS environment variable.

Return Value

ossPrintRemainingReferencedTypes() does not return a value.


Functions that retrieve combined property settings for PER

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:2015 | ISO/IEC 8824-1:2015. 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:2015 | ISO/IEC 8825-2:2015. 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.

unsigned int ossDatePropertySettingsForPER(OssGlobal *world, TypeHndl type, unsigned int *min_year_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:2015 | ISO/IEC 8825-2:2015.

Arguments

world
Pointer to the global OSS environment variable.
type
Handle of the time type for which you wish to get the PER-visible settings of the date properties.
min_year_digits
Is initialized by the function with the minimum number of digits in large years or centuries as permitted by any constraints, or 0 if large years or centuries are not permitted.

Note that the actual number of digits in large years is not PER-visible. The function returns the minimum possible number of digits.

Return Value

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.

See Also

Functions that retrieve PER-visible combined property settings for time types


unsigned int ossIntervalPropertySettingsForPER(OssGlobal *world, TypeHndl type, unsigned int *min_recurrence_digits);

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:2015 | ISO/IEC 8825-2:2015.

where

Arguments

world
Pointer to the global OSS environment variable.
type
Handle of the time type for which you wish to get the PER-visible settings of the interval properties.
min_recurrence_digits
Is initialized by the function with the minimum number of recurrence digits as permitted by any constraints, or 0 if recurring intervals are not permitted or if there is no limitation on the number of recurrence digits.

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.

Return Value

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.

See Also

Functions that retrieve PER-visible combined property settings for time types


ossBoolean ossTimeHasNonMixedPEREncoding(OssGlobal *world, TypeHndl type);

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:2015 | ISO/IEC 8825-2:2015.

Arguments

world
Pointer to the OSS global environment variable.
type
Handle of the ISO 8601 time type for which PER-visible information is desired.

Return Value

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.


unsigned int ossTimeOfDayPropertySettingsForPER(OssGlobal *world, TypeHndl type, unsigned int *fraction_digits);

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:2015 | ISO/IEC 8825-2:2015.

where

Arguments

world
Pointer to the global OSS environment variable.
type
Handle of the time type for which the PER-visible settings of the time-of-day properties are desired.
fraction_digits
Is initialized by the function with the PER-visible number of digits in the fractional part if the type is constrained to have a decimal fraction, or 0 if a fractional part is not permitted in the time-of-day component of all abstract values.

Return Value

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.

See Also

Functions that retrieve PER-visible combined property settings for time types


Functions for E-XER namespaces

void ossNamespaceURI(OssGlobal *world, unsigned int ix);

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.

Arguments

world
Pointer to the OSS global environment variable.
ix
Index of the namespace whose URI you wish to obtain. The index starts from zero.

Return Value

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.


void ossNumberOfNamespaces(OssGlobal *world);

Returns the number of E-XER namespaces found in the input specification.

Arguments

world is a pointer to the global OSS environment variable.

Return Value

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.


Functions for CDR headers

ossBoolean ossDetectCDRHeaders (OssGlobal *world, OssBuf *encodedValue, OssCDRHeaderData *cdrHeader);

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:

  • CDR files with a 3GPP header.
    The 3GPP header typically occupies 50 or 54 octets; the first four octets hold the file length, and octets 5 through 8 hold the file header length. Each CDR consists of a CDR record header and a BER-based encoded message. The first two octets hold the record data length, and the next two or three octets hold the record identifiers. NOTE: The 3GPP header is also known as the CDR file header.
  • CDR files consisting of CDR records that include a CDR record header and a BER-based encoded message.
    The first two octets of a CDR record header hold the record identifiers, and the next two octets hold the record data length. Each record can be placed inside fixed size blocks which are filled up with 00 or FF padding bytes.

Arguments

world
Pointer to the global OSS environment variable.
encodedValue
Address of an OssBuf structure that will contain the length and the encoding with nested BER-based encoded messages and possible CDR headers.
cdrHeader
Address of the OssCDRHeaderData structure, which is defined in ossiaapi.h as follows:
typedef struct OssCDRHeaderData {
    long         fileSize;
    int          fileHeaderLength;
    int          recordHeaderLength;
    int          pduCount;
    char         recordHeaderId[3];
} OssCDRHeaderData;
fileSize
Is set by the ossDetectCDRHeaders() caller to the size of the binary CDR file when encodedValue->value contains all bytes from that file. Set this field to 0 when the input encoding contains only part of the CDR file, to avoid unnecessary reading of huge files. In this case, the function returns the file size extracted from the CDR file header (when present) in this field.
fileHeaderLength
The CDR file header length returned by the function when the CDR file format with a CDR file header is detected.
recordHeaderLength
The CDR record header length returned by the function when one of the supported CDR file formats is detected.
pduCount
The number of CDRs contained in the file. It is returned by the function when the CDR file format with a CDR file header is detected.
recordHeaderId
The format-specific record identifier contained in two or three octets of the CDR record header. It is returned by the function when a supported CDR file format is detected.

Return Value

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.


CSV conversion functions

These functions are available starting with version 10.3 of the IAAPI library.

void ossClearCsvSettings(OssGlobal *world)

Is used as follows:

  • Resets the values of all CSV settings to zero.
  • Clears internal fields that hold the address of the CSV header, which is used when concatenated CSVs are converted into decoded values by multiple calls to ossConvertCsvToPduValue() or ossConvertCsvToTypeValue().
  • Clears the number of extra CSVs preserved after multiple CSVs for SET OF and SEQUENCE OF components were created by calls to ossConvertPduValueToCsv() or ossConvertTypeValueToCsv().

Arguments

world is a pointer to the global OSS environment variable.


IAAPI_ERRTYPE ossConvertCsvToPduValue(OssGlobal *world, int pduNum, OssBuf *csvValue, void **decodedValue);

Converts the comma-separated value (CSV) of an entire PDU (simple or structured) into decoded internal format using its PDU number.

Arguments

world
Pointer to the global OSS environment variable.
pduNum
The PDU number of the type whose CSV value will be converted; it is a compiler-assigned integer.
csvValue
Pointer to an OssBuf structure whose value field references a character string containing the CSV and whose length field is zero when the character string is null-terminating; otherwise, it holds the length of the character string.
decodedValue
Points to a NULL pointer that will reference the output decoded PDU.

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.

Remarks

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;
 }

Return Value

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.

See Also


IAAPI_ERRTYPE ossConvertCsvToTypeValue(OssGlobal *world, TypeHndl type, OssBuf *csvValue, void **decodedValue);

Converts the Comma-Separated Value (CSV) of an entire ASN.1 type (simple or structured) into decoded internal format using its type handle.

world
Pointer to the global OSS environment variable.
type
Type handle that references the type whose CSV will be converted.
csvValue
Pointer to an OssBuf structure whose value field references a character string containing the CSV and whose length field is zero when the character string is null-terminating; otherwise, it holds the length of the character string.
decodedValue
A NULL pointer that will reference the output decoded PDU.

The memory allocated for this structure can be freed by a call to ossFreeDecodedValue().

Return Value

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.

See Also


IAAPI_ERRTYPE ossConvertPduValueToCsv(OssGlobal *world, int pduNum, void *decodedValue, OssBuf *csvValue);

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.

world
Pointer to the global OSS environment variable.
pduNum
The compiler-assigned PDU number of the type whose value will be converted.
decodedValue
Pointer to the value that is in decoded internal format.
csvValue
Address of an OssBuf structure whose value field will contain the output CSV and whose length field will contain the length of the output CSV.

Remarks

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:

  • The rows use comma separators with no surrounding spaces.
  • The full header lists absolute references for all fields and special PDU names or numbers inside the parentheses of open type values. The underscore character is used as a name separator, for example, field1_field2_field3.
  • BOOLEAN types use FALSE and TRUE values.
  • Identifiers are printed for ENUMERATED types.
  • Open type values are automatically decoded.
  • Values of OCTET STRING types without OSS.PrintFunctionName applied are printed as xmlhstrings.
  • Additional CSVs are created for up to 50 components with values from each SET OF and SEQUENCE OF type.

If the CSV settings are not set when ossConvertPduValueToCsv() is called, the function initializes the CSV settings to their default values. You can call ossGetCsvSetting() to obtain these values. Other IAAPI functions for CSV conversion 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: The values of SET OF and SEQUENCE OF types 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. To avoid significant performance degradation, IAAPI supports an additional CSV for up to 50 components inside each type. To set the maximum number of components, call ossSetCsvSetting() with a value between 1 and 50 for the OSS_CSV_MAX_SET_OF_SEQ_OF_COMPONENTS setting.

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.

Example

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

Return Value

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.

See Also


IAAPI_ERRTYPE ossConvertTypeValueToCsv(OssGlobal *world, TypeHndl type, void *decodedValue, OssBuf *csvValue);

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.

Arguments

world
Pointer to the OSS global environment variable.
type
Type handle of the type whose value will be converted.
decodedValue
Pointer to the value that is in decoded internal format.
csvValue
Address of the OssBuf structure whose value field will contain the output CSV and whose length field will contain the length of the output CSV.

Remarks

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().

Return Value

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.

See Also


unsigned int ossGetCsvSetting(OssGlobal *world, unsigned int settingId);

Returns the CSV setting value that was set by ossSetCsvSetting(), ossSetDefaultCsvSettings(), ossClearCsvSettings(), or the IAAPI functions that convert decoded values to and from CSV.

Arguments

world
Pointer to the OSS global environment variable.
settingId
An OSS_CSV_SETTINGS enumerator that uniquely identifies the CSV setting whose value you wish to retrieve.

Return Value

The ossGetCsvSetting() function returns an integer value that varies depending on the CSV setting identifier.


int ossGetNumberOfExtraCsvs(OssGlobal *world);

Call the ossGetNumberOfExtraCsvs() function after ossConvertPduValueToCsv() or ossConvertTypeValueToCsv() to obtain the number of additional CSVs created for extra SET OF and SEQUENCE OF components.

Arguments

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.

Return Value

This function returns an integer that indicates the number of additional CSVs or 0.


void ossSetDefaultCsvSettings (OssGlobal *world);

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.

Arguments

world is a pointer to the global OSS environment variable.

The ossSetDefaultCsvSettings() function sets the following defaults:

  • The row format is used with the comma separator with no surrounding spaces.
  • The full header is used with absolute references for all fields and special PDU names or numbers are placed inside parentheses for open type values. The underscore character is used as a name separator, for example, field1_field2_field3.
  • FALSE and TRUE values are used for BOOLEAN types.
  • Identifiers are printed for ENUMERATED types.
  • Open type values are automatically decoded.
  • OCTET STRING type values are printed as xmlhstrings, if the OSS.PrintFunctionName directive and an OSS conversion function name are not present.
  • Additional CSVs are created for up to 50 components from each SET OF or SEQUENCE OF value.

IAAPI_ERRTYPE ossSetCsvSetting(OssGlobal *world, unsigned int settingId, unsigned int settingValue);

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.

Arguments

world
Pointer to the OSS global environment variable.
settingId
An OSS_CSV_SETTINGS enumerator that uniquely identifies the CSV setting whose value you wish to set.
settingValue
An unsigned integer value suitable for the specified setting.

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
};

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_MAX_SET_OF_SEQ_OF_COMPONENTS
Unsigned integer of 1 to 50 used as the maximum number of components for each SET OF or SEQUENCE OF value for which an extra CSV should be created.
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

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:

OSS_CSV_FORMAT Setting Values
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.
OSS_CSV_HEADER Setting Values
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_CSV_BOOLEAN Setting Values
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.
OSS_CSV_ENUMERATED Setting 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.
OSS_CSV_OCTET_STRING Setting Values
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.
OSS_CSV_OPEN_TYPE Setting Values
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).
OSS_CSV_TIME Setting Values
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.
OSS_CSV_FLAGS Setting Values
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.

Example

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:

  • Use the semi-colon separator with no surrounding spaces
  • No CSV header
  • Print numbers instead of identifiers for ENUMERATED types
  • Use the time stamp with slashes format for GeneralizedTime values
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

Return Value

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.

See Also

IAAPI Error Codes


This documentation applies to the latest version of the OSS® ASN.1 Tools for C. If you are using an earlier version, consult the documentation that was shipped with your product.

Copyright © 2017 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.