BonoboObject
Base object for wrapping Bonobo::Unknown derived objects. Implements
.
BonoboObject 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
libbonobo-2.0, it strongly deprecates #BonoboXObject.
The Bonobo::Unknown interface
The Bonobo::Unknown interface (wrapped by
BonoboObject) is the foundation for the component system: it provides
life cycle management for objects as well as service discovery.
The Bonobo interfaces are all based on the
Bonobo::Unknown 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:
module Bonobo {
interface Unknown {
void void ref ();
void void unref ();
Object query_interface (in string repoid);
};
};
The ref() and unref()
methods are used to control the lifetime of an object. The
query_interface method is used to discover
optional functionality provided by the object implementation.
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.
It is possible to ask an object which implements the
Bonobo::Unknown interface if it supports
other CORBA interfaces. For example, it would be possible to
ask an object whether it supports the
"IDL:Bonobo/EmbeddablePrint:1.0" interface to find out if it is
possible to print its contents. If the return value from
invoking the query_interface method on the
interface is CORBA_OBJECT_NIL, then we know that the requested interface
is not supported. Otherwise, we can invoke
IDL:Bonobo/EmbeddablePrint:1.0 methods on the returned CORBA
Object.
Clients of the query_interface 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.
For example, a help browser can load an HTML renderer component and
ask this component which sort of features are supported by it:
stop_animations (BrowserHTML html)
{
BrowserControl control
control = html->query_interface ("IDL:Browser/Control:1.0");
if (control)
control->stop_animations ();
}
The return value of the query_interface invocation contains a
reference to a CORBA object that is derived from the
Bonobo::Unknown interface or
CORBA_OBJECT_NIL if the interface is not supported by the
object. And this interface would have been already
ref()ed before it was returned. It is up
to the caller to call unref() when they are
done using the interface.
BonoboObject implements the Bonobo::Unknown interface and exports the
implementations of the methods in this class to simplify creating
new objects that inherit from Bonobo::Unknown. This base object
provides default implementations for the ref, unref and
query_interface methods.
Other implementations reuse this implementation by listing on their
VEPV tables the bonobo_object_epv entry point vector.
The Bonobo::Unknown interface is inspired
by the Microsoft COM IUnknown interface
but it has been translated into the CORBA world.
#GObject
Returns the #GtkType for the BonoboObject object.
This macro returns the CORBA object reference inside a #BonoboObject.
@o: a #BonoboObject
Signature of POA initialization and finalization functions
@servant: the object's servant
@ev: CORBA environment
Implements Bonobo::Unknown.
Signal emitted when the last reference of a BonoboObject has been
lost and the object is being destroyed / finalized / deactivated.
@bonoboobject: the object which received the signal.
Signal emitted from bonobo_object_check_env if a system exception is identified.
@bonoboobject: the #BonoboObject which received the signal.
@arg1: the CORBA_Object contained in @bonoboobject.
@arg2: the exception that has just occurred.
Pass this property during construction to specify a custom POA for a BonoboObject. Example:
BonoboObject * my_bonobo_object_new (void)
{
BonoboObject *object;
object = g_object_new (MY_TYPE_BONOBO_OBJECT, "poa",
bonobo_poa_get_threaded (BONOBO_POA_ALL_AT_IDLE), NULL);
return object;
}
BonoboObject's class.
@parent_class:
@destroy:
@system_exception:
@poa_init_fn:
@poa_fini_fn:
@vepv:
@epv_struct_offset:
@base_epv:
@epv:
@dummy:
@object:
@newobj:
@object:
@repo_id:
@Returns:
@object:
@repo_id:
@opt_ev:
@Returns:
@unknown:
@repo_id:
@opt_ev:
@Returns:
@object:
@Returns:
@object:
@opt_ev:
@Returns:
@object:
@opt_ev:
@Returns:
@obj:
@Returns:
@obj:
@obj:
@Returns:
@object:
@immortal:
@obj:
@fn:
@line:
@ref:
@Returns:
@object:
@object:
@corba_object:
@ev:
Checks if the exception in @e needs to be signaled. If so, then
the proper exception signal is generated on the BonoboObject object
@o for the CORBA reference @c.
@o:
@c:
@e:
@object:
@opt_ev:
@Returns:
@list:
@list:
@p:
@Returns:
@o:
@s:
@Returns:
@o:
@Returns:
@object:
@Returns:
@parent_type:
@init_fn:
@fini_fn:
@epv_struct_offset:
@info:
@type_name:
@Returns:
@type:
@init_fn:
@fini_fn:
@epv_struct_offset:
@Returns:
Macro that includes all the boilerplate code need to register a
new BonoboObject-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.
@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
Like #BONOBO_TYPE_FUNC, but doesn't set POA ini and fini functions.
@class_name:
@parent:
@prefix: