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

C/C++ Source or Header | 1996-07-15 | 15.5 KB | 423 lines

/* Copyright (c) 1996 by Oracle Corporation.  All Rights Reserved.
 *
 * yslog.h - Log Operations
 *
 * DESCRIPTION
 * The logging mechanism provides a backbone for portable logging
 * operations.  Messages are recorded by "facilities", or component
 * parts of a "product".  Every message that is recorded is filtered
 * and possibly passed to a "sink" which can process the message as
 * is appropriate for the type of sink.  Most developers will need
 * to use only ysRecord().
 */

#ifndef YSLOG_ORACLE
#define YSLOG_ORACLE

#ifndef SYSX_ORACLE
#include <sysx.h>
#endif
#ifndef YSX_ORACLE
#include <ysx.h>
#endif

EXTC_START

/*
 * BASIC PRIMITIVES
 *
 */

/*
 * ysRecord - log a message
 *
 * DESCRIPTION
 * ysRecord() causes a message to be logged.  The prod and fac identify
 * where the message is generated from.  msgid is a message id number of
 * the message.  Message identifiers must be unique within a product.
 *
 * The severity may be one of the following (following syslog conventions):
 *
 *   YSLSEV_EMERG    - a panic condition
 *   YSLSEV_ALERT    - a condition that should be corrected immediately
 *   YSLSEV_CRIT     - critical conditions
 *   YSLSEV_ERR      - errors
 *   YSLSEV_WARNING  - warning messages
 *   YSLSEV_NOTICE   - conditions that are not errors, but may require
 *                     special handling
 *   YSLSEV_INFO     - informational messages
 *   YSLSEV_DEBUG(n) - messages that contain information normally of use
 *                     only when debugging; (debugging messages are further
 *                     subdivided into debug severities ranging from 0 to 8)
 *
 * assoc is an abstract association for the message.  It should be used to
 * indicate in some sense on whose behalf the program is working when the
 * message is recorded.
 *
 * The variable argument list passed to ysRecord() must be built using
 * the following macros:
 *
 *   YSLSTR(char *v) - for strings
 *   YSLUB4(ub4 v) - for unsigned integers
 *   YSLSB4(sb4 v) - for signed integers
 *   YSLSB8(sysb8 *v) - for signed 64-bit integers
 *   YSLPTR(dvoid *ptr) - for raw pointers (converted to strings)
 *   YSLOCTETS(size_t len, ub1 *buf) - for opaque buffers
 *   YSLANY(CONST yotk *type, dvoid *ptr) - for all extended data types
 *
 * To terminate the argument list, use YSLEND.  An empty argument list
 * should be denoted with YSLNONE in place of the variable part of the
 * argument list.
 */
#define YSLSEV_EMERG    ((ub4) 0)
#define YSLSEV_ALERT    ((ub4) 1)
#define YSLSEV_CRIT     ((ub4) 2)
#define YSLSEV_ERR      ((ub4) 3)
#define YSLSEV_WARNING  ((ub4) 4)
#define YSLSEV_NOTICE   ((ub4) 5)
#define YSLSEV_INFO     ((ub4) 6)
#define YSLSEV_DEBUG(n) ((ub4) (7 + (n)))
#define YSLSEV_MAX      YSLSEV_DEBUG(8)

#define YSLSTR(v)       YSLSTR_ID, (v)
#define YSLUB4(v)       YSLUB4_ID, (ub4) (v)
#define YSLSB4(v)       YSLSB4_ID, (sb4) (v)
#define YSLSB8(v)       YSLSB8_ID, (v)
#define YSLPTR(p)       YSLPTR_ID, (dvoid *) (p)
#define YSLOCTETS(l, b) YSLOCTETS_ID, (size_t) (l), (b)
#define YSLANY(t, p)    YSLANY_ID, (CONST ub1 *) (t), (dvoid *) (p)
#define YSLARGS(n, a)   YSLARGS_ID, (sword) (n), (a)              /* private */
#define YSLEND          ((ub4) 0)
#define YSLNONE         ((ub4) 0)

void ysRecord(CONST char *prod, CONST char *fac, ub4 msgid, ub4 sev,
          CONST char *assoc, ...);

/*
 * SINK MANIPULATION
 *
 * DESCRIPTION
 * A sink is the possible destination of messages recorded using
 * ysLogRecord().  Multiple independent sinks can be created.  For
 * each sink, there is an associated filter callback and a record
 * callback.  For every message, the filter callback is invoked.  If
 * the filter callback returns TRUE, then the record callback is invoked
 * to record the message.
 */
typedef struct yssnk  yssnk;                                  /* sink handle */
typedef struct yslrec yslrec;                           /* record descriptor */
typedef struct yslarg yslarg;                         /* argument descriptor */

/*
 * ysFilterCB - filter callback
 *
 * DESCRIPTION
 * The filter callback is invoked by the logging mechanism to determine
 * if the record passed is selected by the filter.  fusrp is the same as
 * passed to ysSinkSetFilter().  fes is a list of compiled filter
 * expressions added to the sink with ysAddFilter().
 */
typedef boolean (*ysFilterCB)(dvoid *fusrp, yslst *fes, yslrec *rec);

/*
 * ysRecordCB - record callback
 *
 * DESCRIPTION
 * The record callback is invoked by the logging mechanism whenever
 * the filter for the sink selects the message.  rusrp is the same as
 * passed to ysSinkCreate().  The rec fields are set to describe the
 * message.  See yslrec below for more information.
 *
 * This function is called once when the sink is destroyed for any
 * cleanup that may be necessary.  This call is indicated by a null
 * pointer for rec.
 */
typedef void (*ysRecordCB)(dvoid *rusrp, yslrec *rec);

/*
 * ysSinkCreate - create a sink
 *
 * DESCRIPTION
 * ysSinkCreate() creates a sink and returns a handle to the created sink.
 * nm is the name of the sink, used for identification purposes.  sink names
 * must be unique.
 *
 * reccb is the callback function that will be called to record messages.
 * rusrp is the user pointer passed back to the callback function.  See
 * ysRecordCB above.
 *
 * The nm argument is not copied.  The sink is created with no filter.
 * This means that all records are selected by default.
 *
 * EXCEPTIONS
 * YS_EX_ALREADY if the name is already in use
 */
yssnk *ysSinkCreate(CONST char *nm, ysRecordCB cb, dvoid *rusrp);

/*
 * ysSinkDestroy - destroy a sink
 *
 * DESCRIPTION
 * ysSinkDestroy() destroys a sink previously created with ysSinkCreate().
 */
void ysSinkDestroy(yssnk *sink);

/*
 * ysSinkFind - find a sink by name
 *
 * DESCRIPTION
 * ysSinkFind() finds a sink by name.  If it doesn't exist, a null pointer
 * is returned.
 */
yssnk *ysSinkFind(CONST char *nm);

/*
 * ysSinkSetFilter - set or replace filter for sink
 *
 * DESCRIPTION
 * ysSinkSetFilter() associates a filter callback with a sink.  fusrp
 * is the user pointer passed back to the callback when invoked.  See
 * ysFilterCB above for more information.
 *
 * If oldfiltcb and oldfusrp are not null, the previous filter callback
 * and user pointer are written.
 */
void ysSinkSetFilter(yssnk *sink, ysFilterCB filtcb, dvoid *fusrp,
             ysFilterCB *oldfiltcb, dvoid **oldfusrp);

/*
 * yslrec - record descriptor
 *
 * DESCRIPTION
 * yslrec is the type of the record descriptor used to pass recorded
 * messages to a callback sink routine.
 *
 * Product & Facility
 *   The prod field points to the product name.  The fac field points
 *   to the facility name.
 *
 * Association
 *   The association is whatever was passed to ysLogRecord().  The pointer
 *   is not guaranteed to be valid upon return from the callback.
 *
 * Severity
 *   The sev field contains the severity of the message.  For the open
 *   action, this field contains the severity of the sink.
 *
 * Message ID
 *   The msgid field contains the message ID of the message.  For the
 *   open action, this field contains the ID or range of the sink.
 *
 * Sequence
 *   The seqid field contains a sequence ID that is process-wide, and is
 *   incremented once for every call to ysLogRecord().
 *
 * Arguments
 *   The arguments are passed in an argvec, whose shape is exactly
 *   identical to YCIDL_sequence_yoany and may be safely cast to that.
 *   The dummy slot exists for sequence compatibility.  narg specifies
 *   the number of arguments in the args array.  Each element of the args
 *   array is an argument passed to ysLogRecord().
 */
/* DISABLE check_naming */
struct yslrec
{
  CONST char *prod;                                          /* product name */
  CONST char *fac;                                          /* facility name */
  CONST char *assoc;                                          /* association */
  ub4         sev;                                               /* severity */
  ub4         msgid;                                   /* message identifier */
  ub4         seqid;                                      /* sequence number */
  struct
    {
      ub4     dummy;                                          /* slot holder */
      ub4     narg;                                   /* number of arguments */
      yslarg *args;                                  /* argument descriptors */
    } argvec;
};
/* ENABLE check_naming */

/*
 * yslarg - argument descriptor
 *
 * DESCRIPTION
 * yslarg is the type of the argument descriptors used to pass the variadic
 * arguments passed to ysLogRecord().  A yslarg is exactly equivalent to
 * an any structure in the object layer (and may be cast safely to yoany).
 * The typecodes are themselves also typecodes as defined by the object
 * layer.  They are safely castable to yotk.  (Pointers via YSLPTR have
 * been converted to strings by the time it is passed to the callback.)
 */

/* DISABLE check_naming */
struct yslarg
{
  CONST ub1 *tc;                                                 /* typecode */
  dvoid     *val;                                        /* pointer to value */
};
/* ENABLE check_naming */

/*
 * ysSinkGetTypeId - get type id from typecode
 *
 * DESCRIPTION
 * For processing of yslargs without requiring the object layer,
 * (and for use in a switch statement), ysSinkGetTypeId() may be
 * used to translate a typecode into one of the simple types below
 * (convenient for doing a switch as well).
 *
 * Any unrecognized type code is identified with YSLANY_ID.  This
 * does not mean that the val is a itself a yoany.  It simply means
 * that the type code is not one of the other simple types.
 *
 * Note that YSLPTR_ID will never be returned by this function, since
 * there is no typecode for pointers.
 */
#define YSLSTR_ID    ((ub4) 1)
#define YSLUB4_ID    ((ub4) 2)
#define YSLSB4_ID    ((ub4) 3)
#define YSLSB8_ID    ((ub4) 4)
#define YSLPTR_ID    ((ub4) 5)
#define YSLOCTETS_ID ((ub4) 6)
#define YSLANY_ID    ((ub4) 7)
#define YSLARGS_ID   ((ub4) 8)                                    /* private */

ub4 ysSinkGetTypeId(CONST ub1 *tc);

/*
 * TYPE CONVERSION REGISTRY
 *
 * DESCRIPTION
 * Media Net maintains a registry for translation functions that apply
 * to arbitrary typecodes.  There are two kinds of translation possible.
 * The first translates a value into a stringified, printable form.  The
 * second translates a value into an encoded binary form.
 *
 * These translations are suitable for the extension of almost any
 * imaginable sink.  The translation functions may be registered at any
 * time.  Registration associates a typecode with a callback.  When
 * processing arguments, sinks will look up the appropriate callback
 * by typecode.  Registering a null typecode provides a default callback
 * that can handle any typecode.  yotkEncode() and yotkFormat() are such
 * routines, and are automatically registered by yoInit().
 *
 * ysSinkRegister() registers one or the other or both callbacks for
 * a particular typecode.  The typecode is not copied.  A null value
 * may be passed for an inapplicable callback.  To unregister the
 * callbacks, simply re-register with null callbacks.  ysSinkFmtLookup()
 * and ysSinkEncLookup() look up the appropriate callback for the given
 * typecode.  If none is found, null is returned.
 */
typedef char *(*ysSinkFmtCB)(CONST ub1 *tc, dvoid *val);
typedef void (*ysSinkEncCB)(CONST ub1 *tc, dvoid *val, ysx *x);

void ysSinkRegister(CONST ub1 *tc, size_t tcsz,
            ysSinkFmtCB fmtcb, ysSinkEncCB enccb);

ysSinkFmtCB ysSinkFmtLookup(CONST ub1 *tc);
ysSinkEncCB ysSinkEncLookup(CONST ub1 *tc);

/*
 * Typecode Names (PRIVATE USE ONLY)
 */
CONST ub1 *YSLSB4__getTC(void);
CONST ub1 *YSLUB4__getTC(void);
CONST ub1 *YSLSB8__getTC(void);
CONST ub1 *YSLSTR__getTC(void);
CONST ub1 *YSLOCTETS__getTC(void);

#define YSLSB4_TC       YSLSB4__getTC()
#define YSLUB4_TC       YSLUB4__getTC()
#define YSLSB8_TC       YSLSB8__getTC()
#define YSLSTR_TC       YSLSTR__getTC()
#define YSLOCTETS_TC    YSLOCTETS__getTC()

/*
 * FILTER MANIPULATION
 *
 * DESCRIPTION
 * During startup, a single sink named "tty" is created using
 * ysSimpleFilter().  If the resource ys.log.tty.filter exists,
 * the resource values are passed to ysAddFilter() for the tty
 * sink.  The tty sink writes messages using yslError().  The
 * messages are formatted using message text obtained from a
 * message file.  The values of resource ys.log.msg-path define
 * paths where the message file is searched for.
 */

/*
 * ysAddFilter - add a filter expression to a sink
 *
 * DESCRIPTION
 * ysAddFilter() adds a filter expression to the given sink.  Filter
 * expressions supported by this routine observe the following syntax:
 *
 *   expr ::= and-expr [ or and_expr ]
 *   or ::= "OR" | ","
 *   and-expr ::= primary [ [ "AND" ] primary ]
 *   primary ::= "NOT" primary | predicate literal | relop-expr | "(" expr ")"
 *   relop-expr ::= variable relop literal
 *   relop ::= "<" | "<=" | "==" | "!=" | ">=" | ">"
 *   literal ::= unquoted-string | quoted-string
 *
 * All whitespace is ignored, except as a token separator.  variable and
 * predicate are identifiers, following C syntax.  An unquoted-string means
 * that any unrecognized word (bounded by spaces, parentheses, commas and
 * relational operators) constitutes a single string.  A quoted-string is
 * a string that contains any character between two quotes (").
 *
 * The following predicates are defined:
 *   prod <string> - true if the product is <string>
 *   fac <string> - true if the facility is <string>
 *   msg <int> - true if the message id is <int1>
 *   msg <int1>:<int2> - true if the message id is between int1 and int2
 *   maxsev <int> - true if the severity of the message is <= int
 *
 * The following variables are defined:
 *   msgid - the message id
 *   sev - the severity
 *   assoc - the association
 *   seqid - the sequence id
 *
 * To build your own filter as a superset of this, see ysLogGetMap() below.
 */
void ysAddFilter(yssnk *sink, CONST char *srcexpr);
void ysClearFilters(yssnk *sink);

/*
 * BUILT-IN FILTERS
 */

/*
 * ysFilterSimple - simple filter
 *
 * DESCRIPTION
 * This simple filter merely evaluates each of the compiled filter
 * expressions in turn until one of them is TRUE or until the list
 * is exhausted, in which case the filter returns FALSE.
 */
boolean ysFilterSimple(dvoid *fusrp, yslst *les, yslrec *rec);

/*
 * ysLogGetFilterMap - get built-in filter map
 *
 * DESCRIPTION
 * To construct extended filters, call ysLogGetMap() to get the base
 * filter map.  Then, extend this by adding additional rows in a new
 * array.  The number of rows in the base filter map is written to
 * *nmap.  The base filter map expects values to be in the vals array
 * according to the index constants below.
 */
#define YSLOGFEVAL_PROD   ((ub1) 0)                                /* char * */
#define YSLOGFEVAL_FAC    ((ub1) 1)                                /* char * */
#define YSLOGFEVAL_MSGID  ((ub1) 2)                                 /* ub4 * */
#define YSLOGFEVAL_SEV    ((ub1) 3)                                 /* ub4 * */
#define YSLOGFEVAL_ASSOC  ((ub1) 4)                                /* char * */
#define YSLOGFEVAL_SEQID  ((ub1) 5)                                 /* ub4 * */
#define YSLOGFEVAL_MAX    6

CONST struct ysfemap *ysLogGetMap(sword *nmap);

EXTC_END
#endif /* YSLOG_ORACLE */