Oracle Video Server 3.0.3.1/OVS_3031_NT.iso/win32/medianet/server/include/yotk.h

C/C++ Source or Header | 1997-01-06 | 19.7 KB | 567 lines

/* Copyright (c) 1995 by Oracle Corporation.  All Rights Reserved.
 *
 * yotk.h - Oracle OMX Typecode manipulation
 */

#ifndef YOTK_ORACLE
#define YOTK_ORACLE

#ifndef SYSX_ORACLE
#include <sysx.h>
#endif
#ifndef YS_ORACLE
#include <ys.h>
#endif
#ifndef YSLOG_ORACLE
#include <yslog.h>
#endif
#ifndef YRTYPES_ORACLE
#include <yrtypes.h>
#endif

EXTC_START

/*
 * yotk - Typecode Definitions
 *
 * DESCRIPTION
 * Typecodes are an encoded form of describing the structure of possible data
 * values that can be manipulated by the object layer.  They are generally
 * constructed by the IDL compiler, but may be synthesized dynamically.
 */
typedef ub1 yotk;

/*
 * yotkKind - Classes of Typecode
 */
typedef ub4 yotkKind;

/*
 * yoany - any descriptor
 *
 * DESCRIPTION
 * yoany is the structure describing an any type, which consists of a pointer
 * to the value and the typecode which describes the value.
 * NOTE: this definition should probably be somewhere like in yodefs.h,
 * but needs to be here for yotkParam() and yotkUnMbr
 */
/* DISABLE check_naming */
typedef struct yoany yoany;
struct yoany
{
  yotk  *_type;
  dvoid *_value;
};
/* ENABLE check_naming */

#define yotkNull      ((yotkKind) 0)    /* empty */
#define yotkVoid      ((yotkKind) 1)    /* empty */
#define yotkShort     ((yotkKind) 2)    /* empty */
#define yotkLong      ((yotkKind) 3)    /* empty */
#define yotkUshort    ((yotkKind) 4)    /* empty */
#define yotkUlong     ((yotkKind) 5)    /* empty */
#define yotkFloat     ((yotkKind) 6)    /* empty */
#define yotkDouble    ((yotkKind) 7)    /* empty */
#define yotkBoolean   ((yotkKind) 8)    /* empty */
#define yotkChar      ((yotkKind) 9)    /* empty */
#define yotkOctet     ((yotkKind) 10)   /* empty */
#define yotkAny       ((yotkKind) 11)   /* empty */
#define yotkTypeCode  ((yotkKind) 12)   /* empty */
#define yotkPrincipal ((yotkKind) 13)   /* empty */
#define yotkObjref    ((yotkKind) 14)   /* repository ID, interface-name */
#define yotkStruct    ((yotkKind) 15)   /* repository ID, struct-name, count,
                       { member-name, TypeCode } */
#define yotkUnion     ((yotkKind) 16)   /* repository ID, union-name,
                       discriminatorTypeCode, default,
                       { label-value, member-name,
                       TypeCode } */
#define yotkEnum      ((yotkKind) 17)   /* repository ID, enum-name,
                       { enumerator-name } */
#define yotkString    ((yotkKind) 18)   /* maxlen */
#define yotkSequence  ((yotkKind) 19)   /* TypeCode, maxlen */
#define yotkArray     ((yotkKind) 20)   /* TypeCode, maxlen */
#define yotkAlias     ((yotkKind) 21)   /* repository ID, name, TypeCode */
#define yotkExcept    ((yotkKind) 22)   /* repository ID, except-name,
                       { member-name, TypeCode } */
#define yotkLongLong  ((yotkKind) 23)   /* empty */
#define yotkRecurs    ((yotkKind) ~0)   /* long (indirection offset) */

/*
 * yoTc Constants - Primitive Type Code Constants
 *
 * DESCRIPTION
 * Typecodes for all the primitive types in the IDL are pre-defined
 * so they don't have to be created dynamically.
 */
CONST yotk *yoTcNull__getTC(void);
CONST yotk *yoTcVoid__getTC(void);
CONST yotk *yoTcShort__getTC(void);
CONST yotk *yoTcUshort__getTC(void);
CONST yotk *yoTcFloat__getTC(void);
CONST yotk *yoTcDouble__getTC(void);
CONST yotk *yoTcBoolean__getTC(void);
CONST yotk *yoTcChar__getTC(void);
CONST yotk *yoTcOctet__getTC(void);
CONST yotk *yoTcAny__getTC(void);
CONST yotk *yoTcTypeCode__getTC(void);
CONST yotk *yoTcPrincipal__getTC(void);
CONST yotk *yoTcObject__getTC(void);

#define yoTcNull        yoTcNull__getTC()
#define yoTcVoid        yoTcVoid__getTC()
#define yoTcShort       yoTcShort__getTC()
#define yoTcUshort      yoTcUshort__getTC()
#define yoTcFloat       yoTcFloat__getTC()
#define yoTcDouble      yoTcDouble__getTC()
#define yoTcBoolean     yoTcBoolean__getTC()
#define yoTcChar        yoTcChar__getTC()
#define yoTcOctet       yoTcOctet__getTC()
#define yoTcAny         yoTcAny__getTC()
#define yoTcTypeCode    yoTcTypeCode__getTC()
#define yoTcPrincipal   yoTcPrincipal__getTC()
#define yoTcObject      yoTcObject__getTC()

/* these are used/defined in ys instead of here, sigh. */
#define yoTcLong        (CONST yotk *)YSLSB4_TC
#define yoTcUlong       (CONST yotk *)YSLUB4_TC
#define yoTcString      (CONST yotk *)YSLSTR_TC
#define yoTcLongLong    (CONST yotk *)YSLSB8_TC

/*
 * Exceptions raised by TypeCode routines
 */
externref ysidDecl(YO_EX_BADCODE);
externref ysidDecl(YO_EX_BOUNDS);
externref ysidDecl(YO_EX_BOUNDSMISMATCH);

/*
 * TypeCode manipulation routines
 */

/*
 * yotkDuplicate - copy a typecode
 *
 * DESCRIPTION
 * yotkDuplicate() returns a copy of a typecode.  The typecode returned should
 * be freed using yotkFree().
 */
yotk *yotkDuplicate(CONST yotk *tk);

/*
 * yotkFree - free a typecode
 *
 * DESCRIPTION
 * yotkFree() safely frees any memory used by a typecode.  Typecodes
 * can be returned by yotkDecode() and also by a number of the typecode
 * inspection routines below.  These should be freed using this routine
 * in case any real memory was used by these typecodes.
 */
void yotkFree(yotk *tk);

/*
 * yotkCmp - compair two typecodes
 *
 * DESCRIPTION
 * yotkCmp() compairs two typecodes.  0 is returned if the two typecodes are
 * identical.  A negative value indicates that the first typecode is less than
 * the second.  A positive value indicates that the first typecode is greater
 * then the second.
 */
sword yotkCmp(CONST yotk *tk1, CONST yotk *tk2);

/*
 * yotkToStr - convert a typecode to a string representation
 *
 * DESCRIPTION
 * yotkToStr() creates a string representation of the specified typecode.
 * The string returned should be freed using ysmGlbFree() when it is no
 * longer needed.
 */
char *yotkToStr(CONST yotk *tk);

/*
 * Typecode Inspection Routines
 */

/*
 * yotkGetKind - get the typecode kind
 *
 * DESCRIPTION
 * yotkGetKind() gets the kind of the typecode, as one of the yotkKinds
 * defined above.
 */
yotkKind yotkGetKind(CONST yotk *tk);

/*
 * yotkGetBaseKind, yotkGetBaseType - get the base kind/ typecode for an alias
 *
 * DESCRIPTION
 * yotkGetBaseKind() gets the basic kind of the typecode. If the typecode
 * is an alias/typedef, it returns the type of the base chain, and not
 * yotkAlias. yotkGetBaseType() does the same thing for typecodes (as
 * opposed to kinds). So:
 *
 *    typedef long a;
 *    typedef a b;
 *
 * returns yotkLong and yoTcLong when called on either a or b.
 */
yotkKind    yotkGetBaseKind(CONST yotk *tk);
CONST yotk *yotkGetBaseType(CONST yotk *tk);

/*
 * yotkGetName - get the name embedded in the typecode
 *
 * DESCRIPTION
 * yotkGetName() returns the name embedded in the typecode (if any).
 *   If no name is available, NULL is returned. Only object
 * references, structs, unions, enums, aliases, and exceptions have names
 * and repository id's.
 */
CONST char *yotkGetName(CONST yotk *tk);

/*
 * yotkGetId   - get the repository id embedded in the typecode
 *
 * DESCRIPTION
 * yotkGetId() returns the repository id embedded in the typecode (if any).
 *   If no id is available YO_EX_BADCODE is raised. Only object references,
 * structs, unions, enums, aliases, and exceptions have repository id's.
 */
CONST char *yotkGetId(CONST yotk *tk);

/*
 * yotkMbrCount - get # of members in a typecode
 * yotkMbrName  - get name associated a particular index
 * yotkMbrType  - get type of a particular index
 *
 * DESCRIPTION
 * structures, exceptions, and unions contain multiple fields, or members.
 * these members can be thought of as having "index numbers" depending on
 * which field they are in a definition. Example:
 *
 *  struct foo { int a; float b; };
 *
 * field 'a' has index number zero; field 'b', index 1. These routines can
 * extract field/member information from the corresponding typecode.
 * yotkMbrCount() returns the # of members in the typecode.
 * yotkMbrName() returns the name associated with a particular member index.
 * yotkMbrType() returns the type of a given member.
 *   If an incorrect or inapplicable typecode is passed in, YO_EX_BADCODE
 * is raised. If an index number is out of range, YO_EX_BOUNDS is raised.
 * if a name is not represented in a typecode, YO_EX_BADPARAM is raised.
 */
ub4         yotkMbrCount(CONST yotk *tk);
CONST char *yotkMbrName(CONST yotk *tk, ub4 index);
CONST yotk *yotkMbrType(CONST yotk *tk, ub4 index);

/*
 * yotkDiscType - return the discriminator type for a union
 * yotkMbrLabel - return the label value for a union
 * yotkDefIndex - returns the index of the default value (if any) in a union
 *
 * DESCRIPTION
 * These routines are applicable only to union typecodes. yotkDiscType()
 * returns the type of the union discriminator. yotkMbrLabel() returns the
 * value of a given label for a union. yotkDefIndex() returns the index
 * value of a default case in a union (if there is no default, ((ub4)-1)
 * is returned).
 *   If an incorrect or inapplicable typecode is passed in, YO_EX_BADCODE
 * is raised. If an index number is out of range, YO_EX_BOUNDS is raised.
 */
CONST yotk  *yotkDiscType(CONST yotk *tk);
yoany        yotkMbrLabel(CONST yotk *tk, ub4 index);
ub4          yotkDefIndex(CONST yotk *tk);

/*
 * yotkLength - return the length of a sequence, array, or string
 *
 * yotkLength() returns the length of a sequence, array, or string.
 * If the sequence or array is unbounded, zero is returned. If any other
 * type is passed in, YO_EX_BADCODE is raised.
 */
ub4 yotkLength(CONST yotk *tk);

/*
 * yotkRecOffset - get the typecode offset of a recursive sequence
 *
 * yotkRecOffset() returns the offset of the enclosing typecode that describes
 * the element type of the sequence. If a non-recursive typecode is passed
 * in, YO_EX_BADCODE is raised. Note: the number returned is the indirection
 * level, not the byte offset of the CDR representation of the typecode.
 */
ub4 yotkRecOffset(CONST yotk *tk);

/*
 * yotkContentType - return the type of the contained elements
 *
 * yotkContentType() returns the type of the contained elements for sequences,
 * aliases, and arrays. If any other typecode is passed in, YO_EX_BADCODE
 * is raised.
 */
CONST yotk *yotkContentType(CONST yotk *tk);

/*
 * yotkParamCount - return # of parameters in a typecode
 * yotkParam      - return the given param of a typecode
 *
 * DESCRIPTION
 * These two routines are deprecated, and provide backwards compatibility
 * with the CORBA 1.2 spec. yotkParamCount() returns the number of parameters
 * in a typecode, and yotkParam() returns the given parameter. For example,
 * a sequence typecode has two parameters: a typecode for the element
 * type, and a ub4 for the bound (if any). This routine may raise
 * YO_EX_BOUNDS if the parameter is out of range. The calling routine should
 * free ret->_value when done with it, using ysmGlbFree.
 *   For information on the numbering of indices, see Table 12 on pg. 6-37
 * of the CORBA 2.0 spec.
 */
ub4   yotkParamCount(CONST yotk *tk);
yoany yotkParam(CONST yotk *tk, ub4 index);

/*
 * TypeCode synthesis routines
 */

typedef struct yotkStrMbr yotkStrMbr;
struct yotkStrMbr
{
  ysid    *name;
  yotk    *type;
};

typedef struct yotkUnMbr yotkUnMbr;
struct yotkUnMbr
{
  ysid    *name;
  yoany   label;
  yotk    *type;
};

typedef struct yotkStrMbrSeq yotkStrMbrSeq;
struct yotkStrMbrSeq
{
  ub4 _length;
  ub4 _maximum;
  yotkStrMbr *_buffer;
};

typedef struct yotkUnMbrSeq yotkUnMbrSeq;
struct yotkUnMbrSeq
{
  ub4 _length;
  ub4 _maximum;
  yotkUnMbr *_buffer;
};

typedef struct yotkEnumMbrSeq yotkEnumMbrSeq;
struct yotkEnumMbrSeq
{
  ub4 _length;
  ub4 _maximum;
  ysid **_buffer;
};

/*
 * yotkCr<XXX> - typecode creation routines
 *
 * DESCRIPTION
 * These routines (with one exception) implement the CORBA::ORB TypeCode
 * creation routines. See section 6.7.3 of the CORBA 2.0 spec for more
 * information. The TypeCodes returned use the CDR representation for
 * TypeCodes (see section 12.3, "CDR Transfer Syntax", of the CORBA 2.0
 * spec), and should be freed with ysmGlbFree().
 *
 * yotkCrStruct returns a struct TypeCode, given the rep id, name, and
 * the sequence of members (name and type for each).
 *
 * yotkCrUnion returns a union TypeCode, given the id, name, discriminator
 * type, and sequence of members (name, type, and label value for each).
 * The 'default' label, if it exists, should be indicated by a label value
 * with type yoTcOctet and value zero (0).
 *
 * yotkCrStruct returns a struct TypeCode, given the rep id, name, and
 * the sequence of members (name for each). yotkCrExcept does the same
 * thing except for returning an exception TypeCode.
 *
 * yotkCrAlias returns an alias TypeCode, given the rep id, name, and the
 * TypeCode of the base type.
 *
 * yotkCrInterface returns an object TypeCode, given the rep id, and name
 * of the interface. (XXX: Bug #394208 - this TypeCode is not in CDR format;
 * only the interface name is kept.)
 *
 * yotkCrString returns a string TypeCode with the given bound. Pass in
 * zero (0) to indicate an unbounded string. yotkCrSeq and yotkCrArray
 * do the same thing for sequences and arrays, and require the content type
 * to be passed in as well.
 *
 * yotkCrRecSeq is not CORBA 2.0 compliant - it requires the offset in bytes
 * of the enclosing TypeCode in addition to the logical nesting offset --
 * since without the byte offset the CDR representation of the TypeCode
 * cannot be created, and without the enclosing TypeCode (which cannot be
 * fully computed w/o this TypeCode), the byte offset cannot be determined.
 */

yotk *yotkCrStruct(CONST yrid *id, CONST ysid *nm, CONST yotkStrMbrSeq *mbrs);
yotk *yotkCrExcept(CONST yrid *id, CONST ysid *nm, CONST yotkStrMbrSeq *mbrs);
yotk *yotkCrUnion(CONST yrid *id, CONST ysid *nm, CONST yotk *disc,
          CONST yotkUnMbrSeq *mbrs);
yotk *yotkCrEnum(CONST yrid *id, CONST ysid *nm, CONST yotkEnumMbrSeq *mbrs);
yotk *yotkCrAlias(CONST yrid *id, CONST ysid *nm, CONST yotk *base);
yotk *yotkCrInterface(CONST yrid *id, CONST ysid *nm);
yotk *yotkCrString(ub4 bound);
yotk *yotkCrSeq(ub4 bound, CONST yotk *elt);
yotk *yotkCrArray(ub4 length, CONST yotk *elt);
yotk *yotkCrRecSeq(ub4 bound, ub4 offset, sb4 byteoff);

/*
 * TypeCode traversal / utility routines
 */

/*
 * yotkSizeAlign - compute size and alignment
 *
 * DESCRIPTION
 * yotkSizeAlign() returns the computed size required to hold a value
 * described by the given typecode, and the alignment boundary for the
 * type.  These are returned in *sz and *align, respectively. Both
 * arguments must point to valid storage areas (in other words, don't pass
 * in NULL).
 */
void yotkSizeAlign(CONST yotk *tk, size_t *sz, size_t *align);

/*
 * yotkOffset - returns the pointer to the member in a container
 *
 * DESCRIPTION
 * yotkOffset() returns the byte address of a field or element in a complex
 * value (struct, sequence, etc.), given the base address, the member number,
 * and the TypeCode for the value. Member numbers are zero-based, as they are
 * in the yotkMbr* functions above. If tk doesn't describe a structure,
 * exception, union, sequence, or array (or a typedef to one of these), the
 * exception YO_EX_BADCODE will be raised. If mbr is greater than or equal
 * to the # of fields in a structure or exception or the # of elements in an
 * array or bounded sequence, the exception YO_EX_BOUNDS will be raised.
 */
dvoid * yotkOffset(CONST yotk *tk, ub4 mbr, dvoid *val);

/*
 * yotkTraverse - traverse a value
 *
 * DESCRIPTION
 * yotkTraverse() traverses a value (or pair of values) based on the
 * given typecode.  Either val1 or val2 can be null.  As each sub-component
 * of the value is reached, the visit callback is invoked and passed the
 * typecode and address of the nested value (or values).  The usrp pointer
 * is passed back to the callback for convenience during the traversal.
 * The callback routine is expected to return TRUE so long
 * as the traversal should continue.  yotkTraverse() will return FALSE if
 * the visit routine returned FALSE, or TRUE if the traversal completed.
 *
 * Traversing two values simultaneously is useful for performing comparisons,
 * copies, etc.
 */

boolean yotkTraverse(CONST yotk *tk, dvoid *val1, dvoid *val2, dvoid *usrp,
                     boolean (*visit)(CONST yotk *tk, dvoid *val1, dvoid *val2,
                                      dvoid *usrp));

/*
 * yotkCopyVal - copy a value by typecode
 *
 * DESCRIPTION
 * yotkCopyVal() copies the complex value described by the typecode tk from the
 * space pointed to by src to the space pointed to by dst. dst points to vaild
 * buffer space where the value is to be copied.  For certain types of
 * data, yotkCopy() is required to dynamically allocate memory.  This
 * memory is allocated using the specified allocation function af.
 *
 */
void yotkCopyVal(CONST yotk *tk, dvoid *dst, dvoid *src, ysmaf af);

/*
 * yotkFreeVal() - frees memory allocated during a decode or a copy.
 *
 * DESCRIPTION
 * yotkFreeVal() frees the memory allocated during a decode based on the
 * specified typecode.  The ff specifies the free function to be used to
 * free the memory.
 */
void yotkFreeVal(CONST yotk *tk, dvoid *val, ysmff ff);

/*
 * yotkFmt, yotkFormat - format a value according to the typecode
 *
 * DESCRIPTION
 * yotkFmt produces a "pretty-printed" representation of a value. If
 * YOTKFMT_NAME is set, then the field names are included in the
 * representation. If YOTKFMT_COLLAPSE is set, then unions and anys will
 * be printed as their values, not as types and values.
 *
 * Example:
 *   Suppose you have an any 'val'with type yoTcLong, and value 30:
 *   yotkFmt(yoTcAny, val, (ub4)0)  -> "{ tk_long # 30 }"
 *   yotkFmt(..., YOTKFMT_NAME)     -> "{ _type=tk_long # _value=30 }"
 *   yotkFmt(..., YOTKFMT_COLLAPSE) -> "30"
 *
 * The string returned from yotkFmt should be freed with ysmGlbFree().
 *
 *   yotkFormat is a deprecated interface included for backwards compatibility.
 * It is equivalent to calling yotkFmt(tk, val, YOTKFMT_NAME|YOTKFMT_COLLAPSE).
 */
#define YOTKFMT_NAME     ((ub4) 0x1)
#define YOTKFMT_COLLAPSE ((ub4) 0x2)
char *yotkFmt(CONST yotk *tk, dvoid *val, ub4 flags);
char *yotkFormat(CONST yotk *tk, dvoid *val);

/*
 * PRIVATE INTERFACES
 */

/*
 * typecode implementation-dependent routines
 *
 * DESCRIPTION
 * yotkSize() returns the amount of memory required to hold a typecode.
 * yotkGetLength() returns the length of the typecode after the kind
 * and length field.
 */
size_t  yotkSize(CONST yotk *tk);
size_t  yotkGetLength(CONST yotk *tk);

/*
 * yotkAllocStr, yotkFreeStr - string cache alloc and free
 *
 * DESCRIPTION
 * yotkAllocStr() when passed to yotkCopyVal() as the allocator function causes
 * all unbounded strings to be placed in a string cache to eliminate storage of
 * duplicate values.  yotkFreeStr() should be passed to yotkFreeVal() as the
 * free function when freeing the storage previously allocated by
 * yotkCopyVal() using yotkAllocStr() as the allocation function.
 */
dvoid *yotkAllocStr(size_t len);
void yotkFreeStr(dvoid *ptr);

/*
 * yotkCreateYrObj - return the typecode corresponding to a give IFR object
 *
 * DESCRIPTION
 * yotkCreateYrObj() generates and returns a typecode that describes the
 * given yr object.
 */
yotk *yotkCreateYrObj(yrobj *type);

/*
 * yotkDuplicateWaf, yotkFreeWaf
 *
 * Use these versions of yotkDuplicate and yotkFree to control allocation
 * of duplicated typecodes. Should be used only avoid yr/yc/yo circular
 * dependency inside Media Net.
 */
yotk *yotkDuplicateWaf(CONST yotk *tk, ysmaf af);
void yotkFreeWaf(yotk *tk, ysmff ff);

EXTC_END
#endif /* YOTK_ORACLE */