<!-- ##### SECTION Title ##### -->
MateComponentObject

<!-- ##### SECTION Short_Description ##### -->
Base object for wrapping MateComponent::Unknown derived objects. Implements
<xref linkend="matecomponent-unknown-img"/>.

<!-- ##### SECTION Long_Description ##### -->

<para>
  MateComponentObject provides an easy to use way of writing CORBA servers. It
  drastically simplifies the issues of epv and vepv construction by
  automating these, and automatically instantiates a CORBA_Object on
  g_object_new. This removes clutter from construction time. For
  libmatecomponent-2.0, it strongly deprecates #MateComponentXObject.
</para>

<figure id="matecomponent-unknown-img">
    <title>The MateComponent::Unknown interface</title>
    <mediaobject>
	<imageobject>
	    <imagedata fileref="unknown.png" format="PNG"/>
	</imageobject>
    </mediaobject>
</figure>

<para>
  The <classname>MateComponent::Unknown</classname> interface (wrapped by
  MateComponentObject) is the foundation for the component system: it provides
  life cycle management for objects as well as service discovery.
</para>

<para>
  The MateComponent interfaces are all based on the
  <classname>MateComponent::Unknown</classname> interface.  This
  interface is very simple and provides two basic services:
  object lifetime management and object
  functionality-discovery.   This interface only contains three
  methods, here it is:

  <programlisting>
  module MateComponent {
      interface Unknown {
          void void ref ();
          void void unref ();
          Object query_interface (in string repoid);
      };
  };
  </programlisting>
</para>

<para>
  The <function>ref()</function> and <function>unref()</function>
  methods are used to control the lifetime of an object.  The
  <function>query_interface</function> method is used to discover
  optional functionality provided by the object implementation.
</para>

<para>
  The lifetime management is based on reference counting: when a
  component is initially launched, it starts life with a reference
  count of one.  This reference is held by the component invoker.
  Each time a reference is kept to this object (say, you store a
  copy of the object in an array), the reference count is
  incremented.  Every time a reference goes out of scope, the
  reference count needs to be decremented.  When the reference
  count reaches zero, the component knows that there are no
  outstanding references to it, and it is safe to shutdown.  At
  this point, the component shuts down.
</para>

<para>
  It is possible to ask an object which implements the
  <classname>MateComponent::Unknown</classname> interface if it supports
  other CORBA interfaces.  For example, it would be possible to
  ask an object whether it supports the
  "IDL:MateComponent/EmbeddablePrint:1.0" interface to find out if it is
  possible to print its contents.  If the return value from
  invoking the <function>query_interface</function> method on the
  interface is CORBA_OBJECT_NIL, then we know that the requested interface
  is not supported.  Otherwise, we can invoke
  IDL:MateComponent/EmbeddablePrint:1.0 methods on the returned CORBA
  Object.
</para>

<para>
  Clients of the <function>query_interface</function> method use
  it to discover dynamically if a component supports a given
  interface.  Sometimes the client code would require a specific
  interface to exist, but many times it is possible to operate in
  a "downgraded" mode.  You should design your code to be able to
  cope with the lack of interfaces in objects.  This will allow
  your program to deal with more components, and this also allows
  components to work in more situations.
</para>

<para>
  For example, a help browser can load an HTML renderer component and
  ask this component which sort of features are supported by it:
  <programlisting>
stop_animations (BrowserHTML html)
{
  BrowserControl control

  control = html->query_interface ("IDL:Browser/Control:1.0");
  if (control)
          control->stop_animations ();
}
  </programlisting>
</para>

<para>
  The return value of the query_interface invocation contains a
  reference to a CORBA object that is derived from the
  <classname>MateComponent::Unknown</classname> interface or
  CORBA_OBJECT_NIL if the interface is not supported by the
  object.  And this interface would have been already
  <function>ref()</function>ed before it was returned.  It is up
  to the caller to call <function>unref()</function> when they are
  done using the interface.
</para>

<para>
  MateComponentObject implements the MateComponent::Unknown interface and exports the
  implementations of the methods in this class to simplify creating
  new objects that inherit from MateComponent::Unknown.  This base object
  provides default implementations for the ref, unref and
  query_interface methods.
</para>

<para>
  Other implementations reuse this implementation by listing on their
  VEPV tables the matecomponent_object_epv entry point vector.
</para>

<para>
  The <classname>MateComponent::Unknown</classname> interface is inspired
  by the Microsoft COM <classname>IUnknown</classname> interface
  but it has been translated into the CORBA world.
</para>

<!-- ##### SECTION See_Also ##### -->
<para>
#GObject
</para>

<!-- ##### SECTION Stability_Level ##### -->


<!-- ##### SECTION Image ##### -->


<!-- ##### MACRO MATECOMPONENT_OBJECT_TYPE ##### -->
<para>
Returns the #GtkType for the MateComponentObject object.
</para>



<!-- ##### MACRO MATECOMPONENT_OBJREF ##### -->
<para>
    This macro returns the CORBA object reference inside a #MateComponentObject.
</para>

@o: a #MateComponentObject


<!-- ##### USER_FUNCTION MateComponentObjectPOAFn ##### -->
<para>
Signature of POA initialization and finalization functions
</para>

@servant: the object's servant
@ev: CORBA environment


<!-- ##### STRUCT MateComponentObject ##### -->
<para>
Implements MateComponent::Unknown.
</para>


<!-- ##### SIGNAL MateComponentObject::destroy ##### -->
<para>
    Signal emitted when the last reference of a MateComponentObject has been
    lost and the object is being destroyed / finalized / deactivated.
</para>

@matecomponentobject: the object which received the signal.

<!-- ##### SIGNAL MateComponentObject::system-exception ##### -->
<para>
    Signal emitted from matecomponent_object_check_env if a system exception is identified.
</para>

@matecomponentobject: the #MateComponentObject which received the signal.
@arg1: the CORBA_Object contained in @matecomponentobject.
@arg2: the exception that has just occurred.

<!-- ##### ARG MateComponentObject:poa ##### -->
<para>
    Pass this property during construction to specify a custom POA for a MateComponentObject. Example:
    <informalexample>
	<programlisting>
MateComponentObject * my_matecomponent_object_new (void)
{
	MateComponentObject *object;

	object = g_object_new (MY_TYPE_MATECOMPONENT_OBJECT, "poa",
			       matecomponent_poa_get_threaded (MATECOMPONENT_POA_ALL_AT_IDLE), NULL);
	return object;
}
	</programlisting>
    </informalexample>
</para>

<!-- ##### STRUCT MateComponentObjectClass ##### -->
<para>
MateComponentObject's class.
</para>

@parent_class: 
@destroy: 
@system_exception: 
@poa_init_fn: 
@poa_fini_fn: 
@vepv: 
@epv_struct_offset: 
@base_epv: 
@epv: 
@dummy: 

<!-- ##### FUNCTION matecomponent_object_add_interface ##### -->
<para>

</para>

@object: 
@newobj: 


<!-- ##### FUNCTION matecomponent_object_query_local_interface ##### -->
<para>

</para>

@object: 
@repo_id: 
@Returns: 


<!-- ##### FUNCTION matecomponent_object_query_interface ##### -->
<para>

</para>

@object: 
@repo_id: 
@opt_ev: 
@Returns: 


<!-- ##### FUNCTION matecomponent_object_query_remote ##### -->
<para>

</para>

@unknown: 
@repo_id: 
@opt_ev: 
@Returns: 


<!-- ##### FUNCTION matecomponent_object_corba_objref ##### -->
<para>

</para>

@object: 
@Returns: 


<!-- ##### FUNCTION matecomponent_object_dup_ref ##### -->
<para>

</para>

@object: 
@opt_ev: 
@Returns: 


<!-- ##### FUNCTION matecomponent_object_release_unref ##### -->
<para>

</para>

@object: 
@opt_ev: 
@Returns: 


<!-- ##### FUNCTION matecomponent_object_ref ##### -->
<para>

</para>

@obj: 
@Returns: 


<!-- ##### FUNCTION matecomponent_object_idle_unref ##### -->
<para>

</para>

@obj: 


<!-- ##### FUNCTION matecomponent_object_unref ##### -->
<para>

</para>

@obj: 
@Returns: 


<!-- ##### FUNCTION matecomponent_object_set_immortal ##### -->
<para>

</para>

@object: 
@immortal: 


<!-- ##### FUNCTION matecomponent_object_trace_refs ##### -->
<para>

</para>

@obj: 
@fn: 
@line: 
@ref: 
@Returns: 


<!-- ##### FUNCTION matecomponent_object_dump_interfaces ##### -->
<para>

</para>

@object: 


<!-- ##### FUNCTION matecomponent_object_check_env ##### -->
<para>

</para>

@object: 
@corba_object: 
@ev: 


<!-- ##### MACRO MATECOMPONENT_OBJECT_CHECK ##### -->
<para>
   Checks if the exception in @e needs to be signaled.  If so, then
   the proper exception signal is generated on the MateComponentObject object
   @o for the CORBA reference @c.
</para>

@o: 
@c: 
@e: 


<!-- ##### FUNCTION matecomponent_unknown_ping ##### -->
<para>

</para>

@object: 
@opt_ev: 
@Returns: 


<!-- ##### FUNCTION matecomponent_object_list_unref_all ##### -->
<para>

</para>

@list: 


<!-- ##### FUNCTION matecomponent_object_slist_unref_all ##### -->
<para>

</para>

@list: 


<!-- ##### FUNCTION matecomponent_object ##### -->
<para>

</para>

@p: 
@Returns: 


<!-- ##### MACRO matecomponent_object_fast ##### -->
<para>

</para>

@o: 


<!-- ##### MACRO matecomponent_object_from_servant ##### -->
<para>

</para>

@s: 
@Returns: 


<!-- ##### MACRO matecomponent_object_get_servant ##### -->
<para>

</para>

@o: 
@Returns: 


<!-- ##### FUNCTION matecomponent_object_get_poa ##### -->
<para>

</para>

@object: 
@Returns: 


<!-- ##### FUNCTION matecomponent_type_unique ##### -->
<para>

</para>

@parent_type: 
@init_fn: 
@fini_fn: 
@epv_struct_offset: 
@info: 
@type_name: 
@Returns: 


<!-- ##### FUNCTION matecomponent_type_setup ##### -->
<para>

</para>

@type: 
@init_fn: 
@fini_fn: 
@epv_struct_offset: 
@Returns: 


<!-- ##### MACRO MATECOMPONENT_TYPE_FUNC_FULL ##### -->
<para>
    Macro that includes all the boilerplate code need to register a
    new MateComponentObject-derived class.  The programmer has to define two
    functions only: @prefix_init and @prefix_class_init.  As a result
    of the macro expansion, a function named @prefix_get_type() is
    defined.
</para>

@class_name: Name of the GObject class, LikeThis
@corba_name: Name of the CORBA interface, with IDL-to-C mapping, Like_This
@parent: GType of the parent class, LIKE_TYPE_THIS
@prefix: prefix of the implementation functions


<!-- ##### MACRO MATECOMPONENT_TYPE_FUNC ##### -->
<para>
    Like #MATECOMPONENT_TYPE_FUNC, but doesn't set POA ini and fini functions.
</para>

@class_name: 
@parent: 
@prefix: 


