home *** CD-ROM | disk | FTP | other *** search
/ Oracle Video Server 3.0.3.1 / OVS_3031_NT.iso / win32 / medianet / server / include / ysr.h < prev    next >
Encoding:
C/C++ Source or Header  |  1996-07-15  |  11.9 KB  |  288 lines
  1. /* Copyright (c) 1995 by Oracle Corporation.  All Rights Reserved.
  2.  *
  3.  * ysr.h - OMX Resource Management
  4.  */
  5.  
  6. #ifndef YSR_ORACLE
  7. #define YSR_ORACLE
  8.  
  9. #ifndef SYSX_ORACLE
  10. #include <sysx.h>
  11. #endif
  12. #ifndef YS_ORACLE
  13. #include <ys.h>
  14. #endif
  15.  
  16. EXTC_START
  17.  
  18. /*
  19.  * Resource Descriptor
  20.  *
  21.  * A resource descriptor is an element in the resource database of the
  22.  * process.  Each resource descriptor is identified by a name and has
  23.  * associated with it one or more values; these values are represented
  24.  * as character strings.
  25.  *
  26.  * The name of a resource must observe the following syntax:
  27.  *
  28.  *   resource_name ::= [ binding ] component_name { binding component_name }
  29.  *   binding       ::= '.' | '*'
  30.  *   component_name::= { 'A'-'Z' | 'a'-'z' | '0'-'9' | '_' | '-' }
  31.  *
  32.  * The '.' binding specifies a tight binding which is used to separate
  33.  * immediately adjacent components.  The '*' binding specifies a loose
  34.  * binding which represents any number of intervening components, including
  35.  * none.
  36.  *
  37.  * Associated with a resource name is a list of values.  Any resource
  38.  * may have multiple values associated with it.  Every time the same
  39.  * resource name is set, the new value is appended to the end of the
  40.  * list.  Individual applications may implement there own semantics
  41.  * as to whether multiple values is meaningful, or whether the first
  42.  * value or the last value set should be used (by simply extracting
  43.  * head or the tail of the list).
  44.  */
  45.  
  46. /*
  47.  * ysResGet, ysResGetLast, ysResGetBool - get a resource descriptor
  48.  *
  49.  * DESCRIPTION
  50.  * ysResGet() gets a resource descriptor.  The resource name must
  51.  * be specified completely using only tight bindings.  Thus, a resource
  52.  * name is formatted as
  53.  *
  54.  *    name ::= component_name { '.' component_name }
  55.  *
  56.  * The given resource name is matched up against the resource database
  57.  * by finding the resource entry that most closely matches the given
  58.  * resource name.  Entries are matched up by choosing those resource
  59.  * names that contain a matching component before those that omit it
  60.  * (using a loose binding); then, they are matched up by those which
  61.  * specify a tight binding over those that match a loose binding.
  62.  * All component name comparisons are done in a case-insenstive manner.
  63.  *
  64.  * If a resource entry is found, the list of resource values is
  65.  * returned.  This list is a pointer directly into the resource
  66.  * database and thus, if the list is altered, this directly alters
  67.  * the resource database.
  68.  *
  69.  * ysResGetLast() retrieves the same resource entry as ysResGet(),
  70.  * except that it returns only the last element of the list that
  71.  * would be returned.  This is convenient for most resources where
  72.  * only one value (the last one assigned) is relevant.
  73.  *
  74.  * If no resource entry is found, both of these routines return null.
  75.  *
  76.  * ysResGetBool() retrieves a resource and tests to see if its value
  77.  * is not false.  The value is false if a) the resource is not defined,
  78.  * or b) the value of the resource is "false" (case-insensitive).  Otherwise,
  79.  * this routine returns TRUE.
  80.  */
  81. yslst  *ysResGet(CONST char *name);
  82. char   *ysResGetLast(CONST char *name);
  83. boolean ysResGetBool(CONST char *name);
  84.  
  85. /*
  86.  * ysResSet - set a resource descriptor
  87.  *
  88.  * DESCRIPTION
  89.  * ysResSet() sets a value for a resource descriptor.  The name given
  90.  * here must observe the semantics specified under the description of
  91.  * the resource descriptor.  If there is already an entry in the
  92.  * database that matches this name EXACTLY (ignoring case), then the
  93.  * given value will appended to the list of values for that resource.
  94.  * Otherwise, a new entry is created.
  95.  */
  96. void ysResSet(CONST char *name, CONST char *val);
  97.  
  98. /*
  99.  * ysargmap - argument-to-resource mapping
  100.  *
  101.  * DESCRIPTION
  102.  * Argument maps are used by ysArgParse() to map command-line options and
  103.  * operands (positional arguments) to resource names and values.  Each map
  104.  * element describes a single option or operand.  An array of map elements
  105.  * forms the argument map.  Ordering of the map elements among the options
  106.  * doesn't matter, but does among the operands, since it is positional.
  107.  *
  108.  * The opt field contains one of: (a) the character value identifying an
  109.  * option; (b) the value YSARG_PARAM identifying a mandatory operand;
  110.  * (c) YSARG_OPTPARAM identifying an optional operand; or (d) zero,
  111.  * terminating a vector of ysargmap elements.
  112.  *
  113.  * The cnt field specifies number of arguments to allow for the option.  If
  114.  * cnt is zero, no arguments are allowed.  If cnt is one, exactly one
  115.  * argument is allowed.  If cnt is YSARG_MANY, then any number of arguments
  116.  * (but at least one) is allowed.  In the case of many arguments, they may
  117.  * appear separately or together.  When option arguments are expected,
  118.  * ysResSet() is called once for each option argument, with the name field
  119.  * as the resource name and the argument as the resource value.  When no
  120.  * option arguments are expected, ysResParse() is called with the name
  121.  * field.  Calling ysResParse() allows the existence of an argument to
  122.  * cause a particular value for a particular resource to be set.
  123.  
  124.  * All elements with opt valuess of YSARG_PARAM or YSARG_OPTPARAM are treated
  125.  * as positional operands.  YSARG_PARAM denotes an element that is required;
  126.  * YSARG_OPTPARAM denotes an element that is optional.  Optional parameters
  127.  * must follow required parameters. Multiple elements may be given and they
  128.  * are matched up with the arguments in the order in which they appear in the
  129.  * argument map array.  If cnt is one, the element matches the next argument.
  130.  * If cnt is YSARG_MANY, then the element will match all remaining argument
  131.  * (but at least one will be required if this is a required element).
  132.  * ysResSet() is called once for each matching operand, with the name field
  133.  * as the resource name and the operand as the resource value.
  134.  */
  135.  
  136. typedef struct ysargmap ysargmap;                 /* argument map descriptor */
  137.  
  138. #define YSARG_MANY      (2)  /* cnt: used to indicate more than one argument */
  139.  
  140. #define YSARG_PARAM    (-1)           /* opt: mandatory positional parameter */
  141. #define YSARG_OPTPARAM (-2)        /* opt: opt trailing positional parameter */
  142.  
  143. /* DISABLE check_naming */
  144. struct ysargmap
  145. {
  146.   sword opt;                                               /* name of option */
  147.   CONST char *name;                                      /* name of resource */
  148.   sword cnt;                                   /* number of option arguments */
  149. };
  150. /* ENABLE check_naming */
  151.  
  152. /*
  153.  * ysArgMapConcat, ysArgMapFree - concatenate argument lists
  154.  *
  155.  * DESCRIPTION
  156.  * Sometimes, it is necessary to combine more than one argument list to
  157.  * be passed to ysArgParse().  ysArgMapConcat() may be used to concatenate
  158.  * two argument maps.  It returns a new argument map that is the combination
  159.  * of the two.  ysArgMapFree() must be used to free an argument map obtained
  160.  * from ysArgMapConcat().
  161.  */
  162. ysargmap *ysArgMapConcat(CONST ysargmap *m1, CONST ysargmap *m2);
  163. void ysArgMapFree(ysargmap *map);
  164.  
  165. /*
  166.  * ysArgParse - parse command-line arguments
  167.  *
  168.  * DESCRIPTION
  169.  * ysArgParse() parses an argument list, maps the arguments on to
  170.  * resources, and adds the resources to the resource database.  map
  171.  * is an argument map to use.
  172.  *
  173.  * To be legally formed, the argument list must observe the following
  174.  * rules:
  175.  *   1) Option names must be one character long.
  176.  *   2) All options must be preceded by a '-'.
  177.  *   3) Options with no arguments may be grouped after a single '-'.
  178.  *   4) The first option argument following an option must be preceded
  179.  *      by white space.
  180.  *   5) Option arguments cannot be optional.
  181.  *   6) Groups of option arguments following an option must either be
  182.  *      separated by commas or separated by white space and quoted.
  183.  *   7) All options must precede operands on the command line.
  184.  *   8) "--" may be used to indicate the end of the options.
  185.  *
  186.  * Whenever more than one option argument is permitted, this routine
  187.  * will attempt to parse groups of option arguments according to rule 6.
  188.  * All option arguments are then added as individual values for the
  189.  * given resource.  Note that '-I . -I ..' is considered equivalent
  190.  * to '-I ". .."'.
  191.  *
  192.  * This routine also intercepts and automatically recognizes the following
  193.  * flags:
  194.  *
  195.  *     -h, -H              show usage
  196.  *     -V                  print version
  197.  *     -T                  verbose
  198.  *     -R <resource>  set resource
  199.  *     -P <parameter-file> load parameter file
  200.  *
  201.  * The option -h prints a usage banner and returns YSARG_HELP.
  202.  * The option -V returns YSARG_VERSION.
  203.  * The option -T adds the resource entry "*verbose" with the value "true".
  204.  * The option -R calls ysResParse() on the option argument.
  205.  * The option -P reads a file containing resources to be added.
  206.  
  207.  * This routine also supplements the given argument map with an argument
  208.  * map that includes platform-specific extensions.
  209.  *
  210.  * If the argument list is not legally formed, one or more errors is
  211.  * reported via yslError() and YSARG_ERROR is returned.  Otherwise,
  212.  * the resource database is updated. and YSARG_NORMAL (0) is returned.
  213.  * The program should not continue unless YSARG_NORMAL is returned.
  214.  *
  215.  * Note that most argument lists include the program name as the zeroeth
  216.  * argument.  This should be skipped in the argument list passed to
  217.  * ysArgParse().
  218.  */
  219. #define YSARG_NORMAL   0
  220. #define YSARG_ERROR    1
  221. #define YSARG_VERSION  2
  222. #define YSARG_HELP     3
  223.  
  224. sword ysArgParse(sword argc, char **argv, CONST ysargmap *map);
  225.  
  226. /*
  227.  * ysResParse - parse a resource line
  228.  *
  229.  * DESCRIPTION
  230.  * ysResParse() parses a resource line and adds the result to the
  231.  * resource database.  The syntax of a resource line is shown:
  232.  *
  233.  *   resource_line ::= comment | resource_spec
  234.  *   comment       ::= '#' <rest-of-string>
  235.  *   resource_spec ::= resource_name { ':' | '=' } value
  236.  *   value         ::= <rest-of-string>
  237.  *
  238.  * Whitespace before and after the resource name and the value are
  239.  * deleted.  After this, ysResSet() is called with the resource
  240.  * name and value.  The usual use for this function is to read a
  241.  * resource file and parse it line-by-line.  nm indicates the file name
  242.  * and ln indicates the line number in the file.  If there is a syntax
  243.  * error, an error is reported using yslError() and FALSE is returned.
  244.  * If the line is not being read from a file, nm and ln should be zero.
  245.  */
  246. boolean ysResParse(CONST char *nm, sword ln, CONST char *res);
  247.  
  248. /*
  249.  * ysResWalk - walk the resource database
  250.  *
  251.  * DESCRIPTION
  252.  * ysResWalk() walks the resource database, invoking the callback function
  253.  * for each defined resource.  The callback function is passed the name of
  254.  * the resource and the ordered list of the values for that resource.  All
  255.  * resource values are 'char *' strings.  ysResWalk() continues to walk the
  256.  * hash table until all resources have been processed, or the callback
  257.  * routine returns FALSE.  Thus, it should return TRUE as long as processing
  258.  * should continue.
  259.  */
  260. typedef boolean (*ysreswcb)(dvoid *usrp, char *nm, yslst *vals);
  261. void ysResWalk(ysreswcb walkcb, dvoid *usrp);
  262.  
  263. /*
  264.  * ysResDefaults - add default resource values
  265.  *
  266.  * DESCRIPTION
  267.  * ysResDefaults() take a null-terminated char * array, where each string
  268.  * in the array is a resource line expressed in a form suitable for
  269.  * ysResParse() (see above).  If ysResGet() on the resource name succeeds,
  270.  * no action is taken; otherwise, the resource name with value supplied is
  271.  * added to the resource database.
  272.  */
  273. void ysResDefaults(char **dflts);
  274.  
  275. /*
  276.  * ysResPfile - read a resource file
  277.  *
  278.  * DESCRIPTION
  279.  * Using the host file I/O package, ysResPfile() reads the text file named
  280.  * by fn for resources.  Each line is assumed to observe the syntax shown
  281.  * for resource_line above.  If no errors were encountered, TRUE is returned;
  282.  * otherwise, diagnostics are written to yslError() and FALSE is returned.
  283.  */
  284. boolean ysResPfile(CONST char *fn);
  285.  
  286. EXTC_END
  287. #endif /* YSR_ORACLE */
  288.