/* The Object Manager
 *
 * This is the kernel interface through which objects, interfaces, and
 * interfaces are opened, created and destroyed.  The instantiated objmgr
 * object is always id 1.
 */ 

interface Object {
	guid: "C227980E-EA8B-11D9-84F1-000A95BB581A";
};

struct VStruct virtual {
	guid: "E2E3AF5F-2858-11DA-9FBB-00112431A05E";
};

namespace Objects {
	// FIXME: make this a built-in ID type that fixes things
	// up when moving between systems.  It can be native word
	// sized, rather than always long.

	typedef ulong ID;

	struct TypeDesc {
		enum BasicType {
			Bool, Short, Int, Long,
			UShort, UInt, ULong,
			FShort, FLong, Octet, Enum, 
			Bitfield, Interface, Struct
		} type;
	
		ID id;            // ID of interface, struct, bitfield, or enum (or 0).
		ulong length;     // Type length: bits in bitfield, bytes in
		                  //              struct, max value of enum, or 0. 

		struct Array {
			// Inclusive lower and upper bounds of the array.  If the
			// array has no upper bound, upper should be -1.  If the
			// array has no lower bound, lower should be 0.  If this is
			// not an array, both should be 0.

			long lower, upper;
		} array;
	};
	
	struct ParamDesc {
		TypeDesc type;
	
		enum Dir {
			In, Out, InOut
		} dir;
	
		bitfield Attr:32 {
			copy:1,   /* If input argument references memory, a
			             copy will be made (possibly via copy-on-write)
			             before the method receives control.
			             If the parameter is inout, the changes (if any)
			             will be copied to the original memory area (or
			             the copy-on-write mapping will occur on return
			             from the method).  This is an implementation
			             attribute and is incompatible with shared. */
	
			shared:1, /* If input argument references memory, the
			             method may continue to access the memory
			             until it explicitly releases it.  The memory
			             region must remain valid until then, and all
			             changes to the memory area will be shared by
			             both the caller and the callee.  This is an
			             interface attribute and is incompatible with
			             copy.  The argument should be page aligned
			             and its size must be a multiple of the page
			             size; otherwise, the caller will have
			             access to data outside the region passed. */
		} attr;
	};
	
	struct MethodDesc {
		char[] name;
		ulong entry;      /* Address of method entry point */
		ParamDesc[] params;
	
		bitfield Flags:32 {
			async:1,       /* Method is invoked indirectly via message passing,
			                  and the caller does not wait for completion.  No
			                  out parameters may be used in such a method. */
			
			ordered:1,     /* Method requires strong ordering; all ordered methods
			                  from the same thread will be delivered in order, and
			                  the next such method will not be delivered until
			                  the recipient of the previous invocation message
			                  acknowledges it.  This flag is only valid on async
			                  methods, as synchronous methods are inherently
			                  ordered. 
			                  
			                  An alternative is to invoke methods through
			                  a serialization object, which allows finer
			                  control over the level of serialization.
			                  This flag may go away in favor of always
			                  using explicit serialization objects when
			                  needed. */
		} flags;
	};
	
	struct ClassDesc {
		ulong[] super;		/* superinterface(es) */
		MethodDesc[] methods;
		ulong instantiate, subinterface, remove;	/* access tokens */
	};
	
	struct DatumDesc {
		char[] name;
		TypeDesc type;
	};
	
	struct StructDesc {
		DatumDesc[] data;
	};

	interface Class {
		guid: "C30D0A85-EA8B-11D9-B985-000A95BB581A";
		query_interface(Interface iface, bool supported out);
		instantiate(Object instance out);
	};
	
	interface Interface {
		guid: "C36EBE18-EA8B-11D9-896D-000A95BB581A";
	};
	
	interface Method {
		guid: "C3D1BA69-EA8B-11D9-9439-000A95BB581A";
	};
	
	interface Struct {
		guid: "C4384909-EA8B-11D9-B856-000A95BB581A";
	};

	interface Filter {
		guid: "C4A89048-EA8B-11D9-BB2C-000A95BB581A";

		// Returns the object from which the filter was created.
		// This will only succeed if the calling process already
		// has a reference to the real object.  If the filter
		// points to another filter, it will return the transitive
		// real object if possible, or else the filter closest to
		// the real object for which the process already has a
		// reference.  If neither the real object nor a closer
		// filter can be returned, this filter itself is returned.
		// This should not be used for comparing filter references,
		// as separately created filters for the same object will
		// have different IDs and pointers, even if they contain
		// the same subset of interfaces.
		
		get_real_obj(Object obj out);
		
		// Returns a local ID of the real object, regardless of whether
		// the calling process has a reference to it, or whether there
		// are other intervening filters.  The ID cannot be used to
		// invoke methods, but it can be used to compare the identities
		// of the objects behind different filter objects.  If a real
		// reference to the object is later obtained, it will have
		// the same local ID.
		
		get_real_obj_id(ID id out);
	};
	
	interface ObjectManager {
		guid: "C28596AB-EA8B-11D9-8DEB-000A95BB581A";

		new_object(ID cla, ID obj out);
		delete_object(ID obj) async;
	
		new_interface(ID cd, ID cla out);
		delete_interface(ID cla, bool call_del) async;
	
		open_object(ID obj, uint handle out);
		close_object(uint handle) async;
	
		// Create a filter object that implements only some of the
		// interfaces implemented by "obj".  This is useful to create a
		// more limited reference to pass to less trusted processes.  If
		// "exclude" is true, then all interfaces but those specified will
		// be included.  Otherwise, only those interfaces specified will be
		// included.  A filter with no interfaces may be created to act as
		// a (mostly) opaque handle.
		//
		// A holder of a filter reference can convert it into the real
		// object if it already has (or later obtains) a reference to to
		// the real object.  It can also compare the identities of
		// separately created filters pointing at the same object
		// regardless of what it has a real reference to.  Thus, filters
		// should be used only to limit access granted by passing a
		// reference to another process; it should not be used to hide the
		// identity of the real object.
		
		create_filter(Object obj, bool exclude, Interface[] ifaces,
		              Filter filter out);
	};
	
	// This is a generic Factory interface; specific factories may
	// (but do not need to) implement a more specific interface that
	// guarantees that the generated object will comply with some
	// particular interface.
	
	interface Factory {
		guid: "9C084DD0-5D69-11DA-BD5A-000A95BB581A";
		create(Object obj out);
	};
}