home *** CD-ROM | disk | FTP | other *** search
/ Oracle Video Server 3.0.3.1 / OVS_3031_NT.iso / win32 / medianet / server / include / yo.h < prev    next >
Encoding:
C/C++ Source or Header  |  1997-10-29  |  17.8 KB  |  482 lines
  1. /* Copyright (c) 1995 by Oracle Corporation.  All Rights Reserved.
  2.  *
  3.  * yo.h - Oracle OMX Object Layer Interface
  4.  */
  5.  
  6. #ifndef YO_ORACLE
  7. #define YO_ORACLE
  8.  
  9. #ifndef SYSX_ORACLE
  10. #include <sysx.h>
  11. #endif
  12. #ifndef YS_ORACLE
  13. #include <ys.h>
  14. #endif
  15. #ifndef YSX_ORACLE
  16. #include <ysx.h>
  17. #endif
  18. #ifndef YTEX_ORACLE
  19. #include <ytex.h>
  20. #endif
  21. #ifndef YODEFS_ORACLE
  22. #include <yodefs.h>
  23. #endif
  24. #ifndef YOTK_ORACLE
  25. #include <yotk.h>
  26. #endif
  27. #ifndef MN_ORACLE
  28. #include <mn.h>
  29. #endif
  30.  
  31. EXTC_START
  32.  
  33. /* types */
  34. typedef YCIDL_sequence_ub1 yoRefData;
  35.  
  36. /* Exceptions */
  37. externref ysidDecl(YO_EX_BADREFSTR);       /* object reference string is bad */
  38. externref ysidDecl(YO_EX_UNIMPLEMENTED);         /* function not implemented */
  39. externref ysidDecl(YO_EX_INTERNAL);                     /* YO internal error */
  40. externref ysidDecl(YO_EX_UNEXPECTED);     /* unexpected exception was thrown */
  41. externref ysidDecl(YO_EX_NOOPT);            /* required option not available */
  42. externref ysidDecl(YO_EX_BADOBJ);                    /* bad object reference */
  43. externref ysidDecl(YO_EX_BADOPER);                          /* bad operation */
  44. externref ysidDecl(YO_EX_NORES);         /* required resources not available */
  45. externref ysidDecl(YO_EX_NOIMPL);             /* implemenation not available */
  46.  
  47. /*
  48.  * yoInit - initialize the object manager
  49.  *
  50.  * DESCRIPTION
  51.  * yoInit() initializes the object manager.  The service layer and
  52.  * transport layer must already be initialized.
  53.  */
  54. void yoInit(void);
  55.  
  56. /*
  57.  * yoTerm - terminate the object manager
  58.  *
  59.  * DESCRIPTION
  60.  * yoTerm() terminates the object manager.  All active implementations
  61.  * and objects are automatically deactivated at this time.  Objects with
  62.  * loaders have their loaders invoked to deactivate the object.  Objects
  63.  * without loaders are simply disposed of.
  64.  */
  65. void yoTerm(void);
  66.  
  67. /*
  68.  * yoGetInterface, yoGetImplementation - get interface & implementation
  69.  *
  70.  * DESCRIPTION
  71.  * yoGetInterface() and yoGetImplementation() return the interface id
  72.  * and implementation id for an object, respectively.
  73.  */
  74. CONST ysid *yoGetInterface(CONST dvoid *ref);
  75. CONST char *yoGetImplementation(CONST dvoid *ref);
  76.  
  77. /*
  78.  * yoDuplicate, yoRelease - duplicate & release an object reference
  79.  *
  80.  * DESCRIPTION
  81.  * Object references are opaque so there are operations defined to copy
  82.  * or release an object reference.  yoDuplicate() duplicates an object
  83.  * reference and returns a new one, and yoRelease() releases an object
  84.  * reference.  These operations typically no effect on the object itself.
  85.  */
  86. dvoid *yoDuplicate(CONST dvoid *ref);
  87. void   yoRelease(dvoid *ref);
  88.  
  89. /*
  90.  * yoRefCnt - object reference's reference count.
  91.  *
  92.  * DESCRIPTION
  93.  * yoRefCnt() returns the number of references to the specified object
  94.  * reference in this process.
  95.  */
  96. ub4    yoRefCnt(CONST dvoid *ref);
  97.  
  98. /*
  99.  * yoIsEq - test references for equality
  100.  *
  101.  * DESCRIPTION
  102.  * yoIsEq() returns TRUE if ref1 and ref2 both denote the same object;
  103.  * FALSE otherwise.
  104.  */
  105. boolean yoIsEq(CONST dvoid *ref1, CONST dvoid *ref2);
  106.  
  107. /*
  108.  * yoHash - hash an object reference
  109.  *
  110.  * DESCRIPTION
  111.  * It is often necessary for an application to store a table of object
  112.  * references.  Since the object reference is opaque, the yoHash()
  113.  * routine may be used to compute a hash value between zero and maxval-1.
  114.  * The dummy parameter is ignored and exists for prototype compatibility
  115.  * with the yshsh hash table interface.
  116.  */
  117. ub4 yoHash(CONST dvoid *ref, size_t dummy, ub4 maxval);
  118.  
  119. /*
  120.  * yoCmp - compare / order object references
  121.  *
  122.  * DESCRIPTION
  123.  * yoCmp() compares two object references.  0 is returned if the two references
  124.  * are equal.  Otherwise, a positive or negative value is returned.  If ref1
  125.  * is greater than ref2, a positive value is returned.  yoCmp() should only be
  126.  * used to order references within a process.  This function can be used as a
  127.  * tree comparison function when storing object references in trees.
  128.  */
  129. sword yoCmp(CONST dvoid *ref1, CONST dvoid *ref2);
  130.  
  131. /*
  132.  * yoRefToStr, yoStrToRef - reference-to-string, string-to-reference conversion
  133.  *
  134.  * DESCRIPTION
  135.  * Object references are opaque so writing them to persistent storage
  136.  * and recovering them from persistent storage requires that the reference
  137.  * can be converted into some external form.  yoRefToStr() converts an
  138.  * object reference to a form that may be manipulated as a normal C string.
  139.  * Memory allocated to hold the string may be freed using yoFree().
  140.  * yoStrToRef() converts a string back to an object reference.
  141.  */
  142. char  *yoRefToStr(CONST dvoid *ref);
  143. dvoid *yoStrToRef(CONST char *str);
  144.  
  145. /*
  146.  * yoAlloc, yoRealloc, yoFree - manage argument memory
  147.  *
  148.  * DESCRIPTION
  149.  * The invoked operation may need to allocate memory that is to be
  150.  * returned to the client.  The client may retain allocated storage
  151.  * indefinitely and must indicate when it is no longer needed by
  152.  * calling yoFree().  The server should use yoAlloc() and yoRealloc()
  153.  * to allocate memory that is to be returned as arguments to the client.
  154.  *
  155.  * The simple rule to remember is that the client owns all memory and
  156.  * it is always the client's responsibility to free it, never the server's.
  157.  * If the server wants to retain the memory, it must allocate a second
  158.  * block of memory using a normal allocation routine and copy the
  159.  * information.
  160.  */
  161. dvoid *yoAlloc(size_t len);
  162. dvoid *yoRealloc(dvoid *ptr, size_t len);
  163. void   yoFree(dvoid *ptr);
  164.  
  165. /*
  166.  * yoIsA, yoNarrow - narrow type
  167.  *
  168.  * DESCRIPTION
  169.  * yoIsA() returns TRUE if the given object reference denotes an object
  170.  * that is an instance of a derived interface of the given interface.
  171.  * Note that the object may be an instance of the given interface itself.
  172.  * A network trip may be required to answer the question if the object
  173.  * is not an exact match for the requested interface type and no
  174.  * implementation of the object is available in the requesting process.
  175.  * FALSE is returned if there is no "is a" relationship between the
  176.  * object and the target interface or if no implementation of the object
  177.  * can be found.
  178.  *
  179.  * If there is an "is a" relationship (see above) between the given object
  180.  * and the target interface, yoNarrow() returns a the object reference.
  181.  * On failure, the exception YS_EX_BADPARAM is raised.
  182.  */
  183. boolean yoIsA(CONST dvoid *ref, CONST ysid *intf);
  184. dvoid *yoNarrow(CONST dvoid *ref, CONST ysid *intf);
  185.  
  186. /*
  187.  * yoBind - bind to an object
  188.  *
  189.  * DESCRIPTION
  190.  * yoBind() creates an object reference that is "loosely" bound to an
  191.  * object.  The object reference will denote any object that implements
  192.  * the specified interface.  If impl is non-null, then the object must
  193.  * also use the specified implementation.  If id is non-null, the
  194.  * specified id is copied into the object reference.  If id is
  195.  * non-null, the specified reference data is attached to the reference.
  196.  *
  197.  * In any case, a method invoked on the returned object reference will
  198.  * be delivered to any object that meets the requirements of the binding.
  199.  * (Each invocation may bind to a different object.)  The ORB may activate
  200.  * a server if necessary to complete the invocation.  If no such object
  201.  * can be located, an error will be returned during the method invocation,
  202.  * not during this call.
  203.  */
  204. dvoid *yoBind(CONST ysid *intf, CONST char *impl, CONST yoRefData *id,
  205.               CONST char *ignored);
  206.  
  207. /*
  208.  * yoExists - test existence
  209.  *
  210.  * DESCRIPTION
  211.  * yoExists() returns TRUE if the the object denoted by the object
  212.  * reference still exists.  Since it may take time to determine this,
  213.  * it is possible to start this operation asynchronously.  If evt is
  214.  * non-null the operation will be started asynchronously.  The arg value
  215.  * passed to the completed event is a pointer to the boolean result.
  216.  */
  217. boolean yoExists(CONST dvoid *ref, ysevt *evt);
  218.  
  219. /*
  220.  * yoWatchOwner - watch the process which owns the specified object
  221.  *
  222.  * DESCRIPTION
  223.  * The specified event is triggered when the owner of the object is no longer
  224.  * alive.  To cancel a watch before the event is triggered, destroy the event
  225.  * passed to yoWatchOwner() using ysEvtDestroy().  Passinga loosely bound
  226.  * object reference will result in a YS_EX_BADPARAM exception.
  227.  */
  228. void yoWatchOwner(dvoid *ref, ysevt *evt);
  229.  
  230. /*
  231.  * yoGetAddr - get MN address of the process implementing the object
  232.  *
  233.  * DESCRIPTION
  234.  * yoGetAddr() extracts the MNA of the process which implements the object
  235.  * reference specified.  If the object reference specified is loosely bound,
  236.  * the addr is cleared.
  237.  */
  238. void yoGetAddr(CONST dvoid *ref, mna *addr);
  239.  
  240. /* yoClaim, yoAbandon - stake or abandon a property claim
  241.  *
  242.  * DESCRIPTION
  243.  * yoClaim() attempts to associate the specified object reference with the
  244.  * specified property name.
  245.  * yoAbandon() abandons a claim.  The call will only have an affect if you are
  246.  * the owner of the property.
  247.  */
  248. boolean yoClaim(CONST char *property, dvoid *obj);
  249. void yoAbandon(CONST char *property);
  250.  
  251. /* yoListInitRefs, yoGetInitRef - list and get an inital references
  252.  *
  253.  * DESCRIPTION
  254.  * yoListInitRefs() returns a list of the inital reference names currently
  255.  * available.  Inital references are intended for obtaining object references
  256.  * to essential bootstrap services.  This mechanism is not intended to replace
  257.  * the NameService.  In fact, the inital reference mechanism is used to locate
  258.  * the NameService.
  259.  * yoGetInitRef() returns the object reference associated with the given 
  260.  * inital reference name.  If the reference is not available a null object
  261.  * reference is returned.
  262.  */
  263. void yoListInitRefs(YCIDL_sequence_string *nmlst);
  264. dvoid *yoGetInitRef(CONST char *name);
  265.  
  266. /*
  267.  * yoEnvInit, yoEnvCopy, yoEnvFree - YO environment
  268.  *
  269.  * DESCRIPTION
  270.  * yoEnvInit() initializes the YO environment. yoEnvFree() frees the specified
  271.  * YO environment.  yoEnvCopy() copies the environment specified by src to into
  272.  * the environment specified by dst.
  273.  */
  274. void yoEnvInit(yoenv *ev);
  275. void yoEnvFree(yoenv *ev);
  276. void yoEnvCopy(yoenv *dst, CONST yoenv *src);
  277.  
  278. /*
  279.  * yoEnvGet, yoEnvSet - get or set an environment variable
  280.  *
  281.  * DESCRIPTION
  282.  * yoEnvGet() copies the value for the requested environment variable into
  283.  * value.  If the variable is not found, false is returned.
  284.  * yoEnvSet() copies value into the specified environment variable overwriting
  285.  * any previously existing value. Passing a null pointer for value will remove
  286.  * named value from the environment.
  287.  */
  288. boolean yoEnvGet(CONST yoenv *ev, CONST char *name, yoany *value);
  289. void yoEnvSet(yoenv *ev, CONST char *name, CONST yoany *value);
  290.  
  291. #ifndef yoevt_DECLARED
  292. #define yoevt_DECLARED
  293. typedef struct YCyoevt *yoevt;
  294. CONST yotk* yoevt__getTC(void);
  295. #define YCTC_yoevt   (yoevt__getTC())
  296. #endif /* yoevt_DECLARED */
  297. /*
  298.  * yoToRmtEvt - convert a local event to a remote one
  299.  *
  300.  * DESCRIPTION
  301.  * yoToRmtEvt() converts a local event into a a remote event object reference.
  302.  * This object reference is passed to server interfaces (IDL specified) which
  303.  * require remote events.  evt specifies the ysevt to be triggered when the
  304.  * remote event is triggered.  The arg value of the ysevt associated with a
  305.  * triggered remote event will always point to a yoany.
  306.  *
  307.  * Example of remote event usage:
  308.  *
  309.  *  ysevt *evt;
  310.  *  yoevt revt;
  311.  *  yoany *any;
  312.  *
  313.  *  evt = ysEvtCreate(handler,usrp,q,FALSE);
  314.  *  revt = yoToRmtEvt(evt);                           // create remote event
  315.  *
  316.  *  foo_op(ref, ev, revt);     // invoke remote operation with a remote event
  317.  *
  318.  *  void handler(dvoid *usrp, CONST ysid *exid, dvoid *arg, size_t argsz)
  319.  *  {
  320.  *    yoany *any = arg;
  321.  *
  322.  *    // look at the exid and then any to see how things completed
  323.  *    ...
  324.  *    yotkFreeVal(yoTcAny,&any,yoFree);                      // free the any
  325.  *  }
  326.  */
  327. yoevt yoToRmtEvt(ysevt *evt);
  328.  
  329. /*
  330.  * yoToLocalEvt -  convert a remote event to a local one
  331.  *
  332.  * DESCRIPTION
  333.  * Converts the yoevt passed to a server implementation function to a ysevt.
  334.  * When the local event is triggered, the remote event is triggered. The
  335.  * arg argument passed to ysTrigger() must point to a yoany.
  336.  *
  337.  * Example IDL which specifies an operation requiring a remote event:
  338.  *
  339.  *  interface foo
  340.  *  {
  341.  *    op(yoevt revt); 
  342.  *  }
  343.  *
  344.  *
  345.  * Server implementation function which triggers a remote event with
  346.  * a boolean argument:
  347.  *
  348.  *  void foo_op_i(foo ref, yoenv *ev, yoevt revt)
  349.  *  {
  350.  *     ysevt *evt;
  351.  *     char  *exid = (char *) 0;
  352.  *     boolean value = TRUE;
  353.  *     yoany  any;
  354.  *
  355.  *     evt = yoToLocalEvt(revt);            // convert remote event to ysevt
  356.  *     ...
  357.  *     // populate the any
  358.  *     any._type = yoTcBoolean;
  359.  *     any._value = &value;
  360.  *     // ysTrigger() may be in server impl or happen sometime later
  361.  *     ysTrigger(evt, exid, (dvoid *)&any, sizeof(yoany));
  362.  *  }
  363.  */
  364. ysevt *yoToLocalEvt(yoevt revt);
  365.  
  366. /*
  367.  * yoSetFilter - set a named filter
  368.  *
  369.  * DESCRIPTION
  370.  * yoSetFilter() adds a filter function to the filter list.  The type of filter
  371.  * determines when the filter will be invoked.  When invoked, the filter
  372.  * function is passed the request or replys environment.  The filter may
  373.  * manipulate the environment or take actions based on settings in the
  374.  * environment.
  375.  */
  376. typedef void (*yofilter)(yoenv *ev, dvoid *usrp);
  377. /* filter types */
  378. #define YOFLTR_CSND     0      /* called before client request is marshalled */
  379. #define YOFLTR_CRCV     1    /* called after reply to client is unmarshalled */
  380. #define YOFLTR_SPREOP   2     /* called after server request is unmarshalled */
  381. #define YOFLTR_SPOSTOP  3        /* called before server reply is marshalled */
  382. void yoSetFilter(CONST char *name, sword type, yofilter filter, dvoid *usrp);
  383.  
  384. /*
  385.  * yoFilterRunEx - run filters with exception info
  386.  * yoFilterRun   - run filters
  387.  *
  388.  * DESCRIPTION
  389.  * yoFilterRun/yoFilterRunEx run filters previously set up through 
  390.  * yoSetFilter.  They should only be called to run client-side filters 
  391.  * around DII requests and requests through asynchronous stubs; 
  392.  * normal synchronous object requests have their filters run by the stubs.
  393.  *
  394.  * DII and async stub users who wish filters to be run should call 
  395.  * yoFilterRunEx(..., YOFLTR_CSND before invoking yoSendReq (or their async
  396.  * stub), and yoFilterRunEx(..., YOFLTR_CRCV) after synch'ing with the 
  397.  * call completion event.  If an exception has occurred, either during
  398.  * dispatch or after synch'ing with completion, yoFilterRunEx should
  399.  * be used to make that exception info available to the filters.  If 
  400.  * no exception has occurred, pass in NULL for both exid & exobj.
  401.  * 
  402.  * yoFilterRun has been deprecated and exists only for backward 
  403.  * compatibility.
  404.  */
  405. void yoFilterRunEx(dvoid *ref, yoenv *ev, sword type, 
  406.            CONST ysid *exid, dvoid *exobj);
  407. #define yoFilterRun(ref,ev,type) \
  408.         yoFilterRunEx(ref,ev,type,(CONST ysid*)0,(dvoid*)0);
  409.  
  410. /*
  411.  * yoreqsts - Request completion status
  412.  *
  413.  * Equivalent to CORBA::completion_status. Returned in the body of
  414.  * CORBA style system exceptions.
  415.  */
  416. /* DISABLE check_naming */
  417. typedef ub4 yoreqsts;
  418. #define YOREQ_COMPL_YES ((yoreqsts)0)
  419. #define YOREQ_COMPL_NO ((yoreqsts)1)
  420. #define YOREQ_COMPL_MAYBE ((yoreqsts)2)
  421.  
  422. struct yosysex_t
  423. {
  424.   ub4 minor;
  425.   yoreqsts completed;
  426. };
  427. typedef struct yosysex_t yosysex;
  428. /* ENABLE check_naming */
  429.  
  430. /*
  431.  * yoCurGet, yoCurGetRef, yoCurGetPropCtx, yoSetPropCtx -- CORBA Current
  432.  *    operations.
  433.  *
  434.  * DESCRIPTION
  435.  *
  436.  *   These routines support the CORBA Current pseudo-object.  There is one
  437.  *   yocur assiciated with each thread.  It may be obtained by calling
  438.  *   yoCurGet().  In a client, the yocur exists from the time of the first
  439.  *   yoCurGet() until yoCurDestroy() is called.  In servers, the yocur is
  440.  *   instantiated when a request is received and is destroyed when the
  441.  *   processing of the request is completed.  Therefore, in a server, the
  442.  *   contents of the yocur are local to the request, while in a client it
  443.  *   may persist across multiple operations.
  444.  *
  445.  *   When a request is in progress on the thread, the affected object
  446.  *   reference  can get retrieved with yoCurGetRef(), whose return must
  447.  *   be yoRelease()-ed.  Then the interface and implemenation may be seen
  448.  *   with yoGetInterface() and yoGetImplementation().
  449.  *
  450.  *   On both the client and server, yoCurGetExid may be used to retrieve
  451.  *   exception information from within filter.  yoCurGetExid is
  452.  *   only valid from within filters; information about the last exception
  453.  *   does not persist after the completion of a request.  Caller must
  454.  *   not modify or free the exid or exobj returned by yoCurGetExid.
  455.  *
  456.  *   A CosTransactions::PropagationContext may be set in a client thread
  457.  *   with yoCurSetPropCtx().  This copies the argument propCtx, which may be
  458.  *   freed after the call returns.  If the propCtx given to yoCurSetPropCtx
  459.  *   is null, then any existing one will be freed.  The propCtx may be
  460.  *   retrieved in clients or servers by calling yoCurGetPropCtx(), which
  461.  *   returns a pointer to the saved copy.  Servers may modify it
  462.  *   directly.  It is allocated from the ysm global heap.  If the propCtx is
  463.  *   set at the time of a request, it will be sent with the request and the
  464.  *   server's will be returned with the reply.  On return the possibly
  465.  *   updated value will be put back in the client's copy.
  466.  *
  467.  *   yoCurDestroy destroys the yocur for the client thread.  It should
  468.  *   be called to before exit in each client thread that instantiated one
  469.  *   with a call to yoCurGet().  Server threads must not call this, as their
  470.  *   yocur's are instantiated by the runtime, which cleans up after itself.
  471.  */
  472.  
  473. yocur *yoCurGet(void);
  474. void yoCurDestroy(void);
  475. dvoid *yoCurGetRef(yocur *cur);
  476. void yoCurSetPropCtx(yocur *cur, CosTransactions_PropagationContext *pctx );
  477. CosTransactions_PropagationContext *yoCurGetPropCtx(yocur *cur);
  478. CONST ysid *yoCurGetExid(yocur *cur, dvoid **exobj);
  479.  
  480. EXTC_END
  481. #endif /* YO_ORACLE */
  482.