/*****************************************************************************/
/* Copyright (C) 1992-1996 Open Systems Solutions, Inc. All rights reserved.*/
/*****************************************************************************/
/* THIS FILE IS PROPRIETARY MATERIAL OF OPEN SYSTEMS SOLUTIONS, INC. AND
* MAY BE USED ONLY BY DIRECT LICENSEES OF OPEN SYSTEMS SOLUTIONS, INC.
* THIS FILE MAY NOT BE DISTRIBUTED. */
/*****************************************************************************/
/* FILE: @(#)osstrace.h 4.7 96/05/01 */
/* */
/* When tracing is in effect in the OSS ASN.1 Tools encoder/decoder the */
/* user user-replaceable trace routine, osstrace(), is called to trace */
/* the value that is being encoded/decoded. This header file describes */
/* the parameters passed to osstrace(). */
/* */
/* Detailed descriptions appear after the declarations. */
/*****************************************************************************/
#include "ossdll.h"
#if defined(_MSC_VER) && (defined(_WIN32) || defined(WIN32))
#pragma pack(push, ossPacking, 4)
#elif defined(_MSC_VER) && (defined(_WINDOWS) || defined(_MSDOS))
#pragma pack(1)
#elif defined(__BORLANDC__) && defined(__MSDOS__)
#pragma option -a1
#elif defined(__BORLANDC__) && defined(__WIN32__)
#pragma option -a4
#elif defined(__IBMC__)
#pragma pack(4)
#endif /* _MSC_VER && _WIN32 */
/* traceKind: describes the type of TraceRecord */
enum traceKind
{
endOfContentsTrace = 0, /* end-of-contents octets */
valueTrace, /* traceRecord contains a traced value */
skippedFieldTrace, /* a value whose type is not recognized
* is being skipped */
messageTrace /* error message is in the field "value" */
};
/* fieldKind: describes the contents of "fieldNumber". "fieldKind" is
* meaningful only if "fieldNumber" is not 0
*/
enum fieldKind
{
setOrSequenceField = 0, /* "fieldNumber" is the position of the
* component within a SET or SEQUENCE */
pduNumber, /* "fieldNumber" is a PDU number */
setOrSequenceOfElement, /* "fieldNumber" is the position of the
* component within a SET OF or SEQUENCE OF
* components */
stringElement /* "fieldNumber" is the position of the
* substring within a constructed STRING */
};
enum prtType
{
seqsetType = 0, /* SEQUENCE and SET uses [fieldcount = n] */
seqofType, /* SEQUENCE OF and SET OF use [length = n] */
choiceType, /* CHOICE type uses format [index = n] */
pseudoType, /* No length info is printed or [not encoded] */
primeType, /* All other types use the format */
/* [length = [(not encoded)] nbytes.nbits] */
/* fragmentation is printed for OCTET */
/* STRING and BIT STRING. */
closeType /* Trace message at the end of encoding. */
};
/* tag_length: specifies the tag and length of a value. */
struct tag_length
{
unsigned long int length; /* length of type, if definite */
unsigned short int tag; /* 16 bits of the form CCTTTTTTTTTTTTTT,
* with "CC" the class number, and "T...T"
* the tag. (If tag is 0, then "length",
* "primitive" and "definite" are
* not significant). */
unsigned int definite: 1; /* 1: definite-length encoding */
};
/* traceRecord: OSS ASN.1 Tools trace record */
struct traceRecord
{
enum traceKind kind; /* kind of trace record */
void *p; /* reserved for OSS */
char *identifier, /* SET/SEQUENCE/CHOICE component name*/
*typeReference,/* defined type name */
*builtinTypeName; /* ASN.1 builtin type defined in *
* ISO 8824 or "Character String"*/
void *valueName; /* reserved for future use */
unsigned taggingCount; /* number of entries in the tag&length
* or content-end-octet array */
union /* tag&length or end-of-contents-octets array. */
{
struct tag_length *tag_length;
int *depth;
} tagging;
enum prtType prtType; /* Refer to prtType above for details */
char lenEncoded; /* Indicate whether length is encoded */
long length; /* Length in bits for all prime types */
/* fieldcount for SET and SEQUENCE */
/* length of components for SET OF */
/* choice index for type CHOICE */
int fragment; /* Fragment for OCTET STRING and BIT */
/* STRING, PER fragment when too long */
enum fieldKind fieldKind; /* kind of value in "fieldNumber" */
unsigned int fieldNumber; /* component number, 0 if not
* applicable */
unsigned int depth; /* the depth of this value, from 0 on up */
unsigned int primitive: 1; /* indicates structure of encoding */
char value[1]; /* the formatted value for simple
* type and ANY. If the first byte
* is 0, no value is present. */
};
extern void DLL_ENTRY osstrace(struct ossGlobal *g, struct traceRecord *p, size_t traceRecordLen);
/* osstrace(): User-replaceable trace routine.
*
* Parameters:
* g - Reserved. This is always set to NULL for now.
* p - traceRecord, described below.
* traceRecordLen - True length of traceRecord, including first \0 in "value"
*
* osstrace() is called:
*
* - once for each builtin ASN.1 type, regardless of tagging, with the
* field "kind" set to valueTrace. So given a PDU of value "fooBar":
*
* Sample DEFINITIONS EXPLICIT TAGS ::= BEGIN
* fooBar Foo ::= {age 6, living TRUE}
* Foo ::= SET {age INTEGER, living [1] [2] Alive}
* Alive ::= BOOLEAN
* END
*
* it is called called three times with "kind" set to valueTrace - once
* for the SET, once for the INTEGER, and once for the BOOLEAN.
*
* When the traceRecord "kind" field is set to valueTrace ...
*
* The field "identifier" contains the component identifier of
* the type if one is present in the ASN.1 definition. So in
* the above example, "identifier" will be empty on the call for
* the SET, while on the call for the INTEGER it will contain "age",
* and "living" on the call for the BOOLEAN.
*
* The field "typeReference" contains the name of the associated ASN.1
* typereference, if any. So in the above example, "typeReference"
* will contain "Foo" on the call for the SET, "Alive" on the call
* for the BOOLEAN, and will be empty on the call for the INTEGER.
*
* The field "builtinTypeName" contains the name of the ASN.1 builtin
* type. So in the above example, "builtinTypeName" will contain
* "SET", "INTEGER", and "BOOLEAN" on the calls as appropriate.
* Note that for all character string types "builtinTypeName" is
* set to "Character String". This will be changed in the near future
* to reflect the true character string type.
*
* The field "taggingCount" contains the number of entries in the array
* of tag_length structs pointed to by tagging.tag_length, and reflects
* the number of tags present in the encoding. Note that an entry
* exists in the tag_length array for each ANY and CHOICE value as
* though they had tags defined for them in the ASN.1 Standard. So in
* the above example, "taggingCount" is 1 on the calls for the SET and
* INTEGER, and on the call for the BOOLEAN "taggingCount" is 3 since
* EXPLICIT TAGS is in effect.
*
* The field "tagging.tag_length" points to an array of tag_length
* structs.
*
* The field "tagging.tag_length->tag" is the BER tag represented
* in the form CCTTTTTTTTTTTTTT with "CC" the class number, and
* "TTTTTTTTTTTTTT" the tag number. Since the ANY and CHOICE
* types do not have tags of their own, the last entry in the
* tag_length array for these types always has 0 as the value of
* the "tag" field. So in the above example, "tag" is 0x11 on the
* call for the the SET.
*
* The field "tagging.tag_length->length" is the length of the
* encoded value if the length is of definite form (i.e.,
* "definite" is 1).
*
* The field "tagging.tag_length->definite" indicates when the
* length is definite or indefinite. This field is significant
* only if "tag" is non-zero.
*
* The field "fieldKind" indicates whether the number in "field" is:
* -- the position of a component within a SET or SEQUENCE, or
* -- the PDU number assigned by the ASN.1 compiler, or
* -- the position of a component within a SET OF or SEQUENCE OF, or
* -- the position of a substring within a constructed string.
* "fieldKind" is significant only if "field" is non-zero. So in
* the example above, "fieldKind" has a value of pduNumber on the
* call for the SET, and a value of setOrSequenceField on the calls for
* the INTEGER and BOOLEAN.
*
* The field "fieldNumber" is a ordinal number indicating the position
* of a component within a SET, SEQUENCE, SET OF, SEQUENCE OF, or
* constructed string, or the PDU number assigned by the ASN.1 compiler.
* So in the above example, "fieldNumber" is 1 (the PDU number) on the
* call for the SET, 1 (the position of the component "age") on the
* call for the INTEGER, and 2 (the position of the component "living"
* on the call for the BOOLEAN.
*
* The field "depth" is the level of nesting of the value relative to
* the outermost type, which has a "depth" value of 0. So in the above
* example, "depth" is 0 on the call for the SET, and 1 on the calls
* for the INTEGER and BOOLEAN.
*
* The field "primitive" is set to 1 if the builtin ASN.1 type is
* simple (i.e., the primitive/constructed bit in the identifier
* octet is set to 0), so it is 0 for SET, SEQUENCE, SET OF, SEQUENCE
* OF, and CHOICE because they are structured. It is also set to 0 if
* the type is an ANY. It is 1 for all other builtin types.
*
* The field "value" contains formatted data if the builtin type
* is simple or ANY, regardless of tagging. Hence, in the above
* example the call for SET will not contain any data in "value"
* (because the builtin type is a constructed type), while for the
* INTEGER and BOOLEAN types "value" will contain formatted data.
* The maximum number of bytes of formatted data placed into "value"
* is controlled by the external variable "asn1chop". If "asn1chop"
* is set to 0 the maximum length of the traced value is determined
* by the maximum internal buffer size variable, "ossblock".
*
* - once for each end-of-contents octets pair that is generated/
* encountered while encoding/decoding a constructed value whose
* length is of the indefinite-length form. A call with a "valueTrace"
* record is always made to osstrace() before one is made with an
* "endOfContentsTrace" record.
*
* A single "endOfContentsTrace" call is made to osstrace() for each
* builtin type that is processed if the indefinite-length form of
* encoding is used. If the builtin type is a structured type (CHOICE,
* SET, SEQUENCE, SET OF, SEQUENCE OF) then there may be multiple
* "valueTrace" and possible "endOfContentsTrace" calls made to
* osstrace() before the matching "endOfContentsTrace" call is made.
*
* When the traceRecord "kind" field is set to endOfContentsTrace ...
*
* The field "taggingCount" contains the number of entries in the array
* of "depth" indicators pointed to by tagging.depth, and reflects
* the nesting of each pair of end-of-contents-octets associated with
* the builtin type being encoded/decoded. So in the above example,
* if indefinite-length encoding is being used, "taggingCount" will
* be 1 on the call for the SET (since it has a single constructed
* tag), and 2 on the call for the BOOLEAN (since it has two explicit
* tags, for which the "constructed" bit in the encoding must be set).
*
* The field "tagging.depth" points to an array of "depth" indicators
* that reflect the nesting of each pair of end-of-contents-octets
* associated with a builtin type. So in the above example, if
* indefinite-length encoding is being used, "tagging.depth" will point
* to a single 0 on the call for the SET since it has a single tag for
* which the constructed bit is set; while on the call for the BOOLEAN
* "tagging.depth" will point to an array whose two entries are 1 and 2
* since there are two explicit tags on the BOOLEAN.
*
* All other fields in the traceRecord are insignificant for an
* endOfContentsTrace record.
*
* - once for each value that is skipped while decoding, with a "kind"
* value of skippedFieldTrace. The skippedFieldTrace "kind" is just
* means of indicating that an unexpected value was encountered in the
* message and is being skipped. This is not an error if the type is
* extensible.
*
* When the traceRecord "kind" field is set to skippedFieldTrace ...
*
* The field of the traceRecord are the same as when "kind" is set to
* valueTrace, except that:
* -- the skipped value is always reported as having one tag, hence
* -- there is only one entry in the tag_length array.
* -- the content of the field "value" is always "<skipped>", and
* -- "typeReference" is always NULL.
*
* - once for each error message issued, in which case the "kind" field
* is set to messageTrace.
*
* When the traceRecord "kind" field is set to messageTrace the "value"
* field contains the error message, and other fields are
* insignificant.
*/
/* tag_length: describes the tag and length of a value.
*
* "tag" is 0 if the value is an ANY or CHOICE value, in which
* case "definite" is not significant since ANY and CHOICE do
* not have a tag of their own.
*
* If "tag" is not 0, "definite" indicates whether the value
* is encoded using definite- or indefinite-length form.
*
* If "definite" is 1, "length" is the length of the value, else
* it is not significant (indefinite-length encoding was used).
*/
/* tagging: tag&length or end-of-contents-octets array.
*
* The tag and length array, tag_length, is present if this
* is a valueTrace or skippedFieldTrace record. There is one array
* entry for each tag present in the encoding of a given value, so
* "[1] EXPLICIT [2] EXPLICIT INTEGER" gets three tag_length
* array entries, where each entry describes the tag and length
* information that precedes the value.
*
* The depth array, "depth", is present only if this is a
* endOfContentsTrace record. There is one array entry for each
* indefinite length present in the encoding of a value, so
* "[1] EXPLICIT [2] EXPLICIT INTEGER" gets two "depth" entries
* corresponding to the two explicit tags, where the value of each
* tag indicates the depth of the tagged value relative to outmost type
* that contains the INTEGER (e.g., relative to the containing SET).
*/
/* Odds and ends:
*
* - When the value of a field is not significant the field is set to 0.
*/
/* Augmenting for Packed Encoding Rule (PER) tracing.
*
* PER does not encode tag for any ASN.1 type. For some types, length
* may or may not be encoded. PER does not always use octet aligned
* encoding, therefore, the length should be in unit of bit.
*
* We classified ASN.1 types in to the following:
*
* (1). For all primitive types (including ANY), the prtType in traceRecord
* is set to primeType, length is the total length of the content
* in bits. The file osstrace.c prints length in the format
* length = nbytes.nbits, and the total length should be 8*nbytes+nbits.
* If the length is not encoded, "(not encoded)" will be added to the
* output string. For BIT STRING with length longer than 64K (bits), and
* for OCTET STRING longer that 16K (bytes), fragmentation is needed
* and this is indicated by the string "fragment = n" after the length.
* The fragmentation index is field fragment in traceRecord.
* (2). For SEQUENCE and SET, prtType is seqsetType. In this case, the length
* in traceRecord is the fieldcount of the SEQUENCE or SET.
* (3). For SEQUENCE OF and SET OF, prtType is seqofType, and the length
* in traceRecord is the count of components in the SEQUENCE OF (SET OF).
* (4). For CHOICE, prtType is choiceType, and the length field in
* traceRecord indicates the choice index.
* (5). Total number of bits for the entire encoding is reported at the end
* of encoding and decoding. The prtType for this trace is closeType.
*/
#if defined(_MSC_VER) && (defined(_WIN32) || defined(WIN32))
#pragma pack(pop, ossPacking)
#elif defined(_MSC_VER) && (defined(_WINDOWS) || defined(_MSDOS))
#pragma pack()
#elif defined(__BORLANDC__) && (defined(__WIN32__) || defined(__MSDOS__))
#pragma option -a.
#elif defined(__IBMC__)
#pragma pack()
#endif /* _MSC_VER && _WIN32 */
