idl/objmgr.idl

   1 /* The Object Manager
   2  *
   3  * This is the kernel interface through which objects, interfaces, and
   4  * interfaces are opened, created and destroyed.  The instantiated objmgr
   5  * object is always id 1.
   6  */
   7
   8 interface Object {
   9         guid: "C227980E-EA8B-11D9-84F1-000A95BB581A";
  10 };
  11
  12 struct VStruct virtual {
  13         guid: "E2E3AF5F-2858-11DA-9FBB-00112431A05E";
  14 };
  15
  16 namespace Objects {
  17         typedef uint ID;
  18
  19         struct GUID {
  20                 ulong[2] data;
  21         };
  22
  23         struct IHash {
  24                 uint[5] data;
  25         };
  26
  27         struct TypeDesc {
  28                 enum BasicType {
  29                         Bool, Short, Int, Long,
  30                         UShort, UInt, ULong,
  31                         FShort, FLong, Octet, Enum,
  32                         Bitfield, Interface, Struct
  33                 } type;
  34
  35                 ID id;            // ID of interface, struct, bitfield, or enum (or 0).
  36                 ulong length;     // Type length: bits in bitfield, bytes in
  37                                   //              struct, max value of enum, or 0.
  38
  39                 struct Array {
  40                         // Inclusive lower and upper bounds of the array.  If the
  41                         // array has no upper bound, upper should be -1.  If the
  42                         // array has no lower bound, lower should be 0.  If this is
  43                         // not an array, both should be 0.
  44
  45                         long lower, upper;
  46                 } array;
  47         };
  48
  49         struct ParamDesc {
  50                 TypeDesc type;
  51
  52                 enum Dir {
  53                         In, Out, InOut
  54                 } dir;
  55
  56                 bitfield Attr:32 {
  57                         copy:1,   /* If input argument references memory, a
  58                                      copy will be made (possibly via copy-on-write)
  59                                      before the method receives control.
  60                                      If the parameter is inout, the changes (if any)
  61                                      will be copied to the original memory area (or
  62                                      the copy-on-write mapping will occur on return
  63                                      from the method).  This is an implementation
  64                                      attribute and is incompatible with shared. */
  65
  66                         shared:1, /* If input argument references memory, the
  67                                      method may continue to access the memory
  68                                      until it explicitly releases it.  The memory
  69                                      region must remain valid until then, and all
  70                                      changes to the memory area will be shared by
  71                                      both the caller and the callee.  This is an
  72                                      interface attribute and is incompatible with
  73                                      copy.  The argument should be page aligned
  74                                      and its size must be a multiple of the page
  75                                      size; otherwise, the caller will have
  76                                      access to data outside the region passed. */
  77                 } attr;
  78         };
  79
  80         struct MethodDesc {
  81                 char[] name;
  82                 ulong entry;      /* Address of method entry point */
  83                 ParamDesc[] params;
  84
  85                 bitfield Flags:32 {
  86                         async:1,       /* Method is invoked indirectly via message passing,
  87                                           and the caller does not wait for completion.  No
  88                                           out parameters may be used in such a method. */
  89
  90                         ordered:1,     /* Method requires strong ordering; all ordered methods
  91                                           from the same thread will be delivered in order, and
  92                                           the next such method will not be delivered until
  93                                           the recipient of the previous invocation message
  94                                           acknowledges it.  This flag is only valid on async
  95                                           methods, as synchronous methods are inherently
  96                                           ordered.
  97
  98                                           An alternative is to invoke methods through
  99                                           a serialization object, which allows finer
 100                                           control over the level of serialization.
 101                                           This flag may go away in favor of always
 102                                           using explicit serialization objects when
 103                                           needed. */
 104                 } flags;
 105         };
 106
 107         struct ClassDesc {
 108                 ulong[] super;          /* superinterface(es) */
 109                 MethodDesc[] methods;
 110                 ulong instantiate, subinterface, remove;        /* access tokens */
 111         };
 112
 113         struct DatumDesc {
 114                 char[] name;
 115                 TypeDesc type;
 116         };
 117
 118         struct StructDesc {
 119                 DatumDesc[] data;
 120         };
 121
 122         interface IDSpace {
 123                 guid: "06489629-9C25-4C14-9A5B-6C59639C87D6";
 124
 125                 new_object(ID obj, IHash hash);
 126
 127                 // Release "num" references on the object.  If exactly "num"
 128                 // references remain, the object handle is closed and "gone" is
 129                 // true.  If more references remain, the handle is not closed and
 130                 // "gone" is false.  If fewer references than "num" are present
 131                 // when called, no references are released, and RefCountException
 132                 // is thrown.
 133                 //
 134                 // A handle's refcount is incremented whenever a reference is
 135                 // received via IPC.  Objects created with new_object start with
 136                 // a refcount of 1.
 137
 138                 release(ID obj, int num, bool gone out);
 139
 140                 // Delete an object regardless of the number of references.
 141                 // If the object is local, then all remote references will
 142                 // become dangling; any attempt to pass the handle to the
 143                 // ORB will result in an InvalidReference exception.
 144
 145                 revoke(ID obj);
 146
 147                 // Return the number of references to an object.
 148                 // This method is intended for debugging only.
 149
 150                 get_refs(ID obj, int num out);
 151         };
 152
 153         // This is a generic Factory interface; specific factories may
 154         // (but do not need to) implement a more specific interface that
 155         // guarantees that the generated object will comply with some
 156         // particular interface.
 157
 158         interface Factory {
 159                 guid: "9C084DD0-5D69-11DA-BD5A-000A95BB581A";
 160                 create(Object obj out);
 161         };
 162 }