MateComponentMonikerExtender

MateComponentMonikerExtender — A way to extend arbitary monikers

Synopsis

struct              MateComponentMonikerExtender;
                    MateComponentMonikerExtenderClass;
MateComponent_Unknown (*MateComponentMonikerExtenderFn) (MateComponentMonikerExtender *extender,
                                                         const MateComponent_Moniker parent,
                                                         const MateComponent_ResolveOptions *options,
                                                         const CORBA_char *display_name,
                                                         const CORBA_char *requested_interface,
                                                         CORBA_Environment *ev);
MateComponentMonikerExtender * matecomponent_moniker_extender_new
                                                        (MateComponentMonikerExtenderFn resolve,
                                                         gpointer data);
MateComponent_MonikerExtender matecomponent_moniker_find_extender
                                                        (const gchar *name,
                                                         const gchar *interface,
                                                         CORBA_Environment *opt_ev);
MateComponent_Unknown matecomponent_moniker_use_extender
                                                        (const gchar *extender_oafiid,
                                                         MateComponentMoniker *moniker,
                                                         const MateComponent_ResolveOptions *options,
                                                         const CORBA_char *requested_interface,
                                                         CORBA_Environment *opt_ev);

Object Hierarchy

  GObject
   +----MateComponentObject
         +----MateComponentMonikerExtender

Description

A moniker extender is used to extend the functionality of a moniker. There are two standard moniker extenders that cannot be system wide, since they use the oaf database to expand the scope of a moniker to arbitrarily many interfaces. These are invoked explicitely by monikers implementing the stream interface in the following way:

Example 18. Explicit Stream extender usage example

MateComponent_Unknown
example_moniker_resolve (MateComponentMoniker               *moniker,
			 const MateComponent_ResolveOptions *options,
			 const CORBA_char            *requested_interface,
			 CORBA_Environment           *ev)
{
	if (!strcmp (requested_interface, "IDL:MateComponent/Stream:1.0"))
		return handle_stream (moniker, options, ev);
	else
		return matecomponent_moniker_use_extender (
			"OAFIID:MateComponent_MonikerExtender_stream",
			moniker, options, requested_interface, ev);
}


The moniker extender essentialy resolves 'moniker' against stream and by some means ( not known when the moniker was written ) converts this to a new exotic interface - via. the PersistStream interface.

All standard moniker extenders are registered by adding a fragment like this:

Example 19. Oaf information for an extender

<oaf_attribute name="matecomponent:moniker_extender" type="stringv">
	<item value="file:"/>
</oaf_attribute>


to the .oaf file. This registers the extender with the system, such that when a moniker resolve fails an extender can be found for any of the monikers with prefix specified in the "matecomponent:moniker_extender" stringv.

Implementing your own extender is extremely simple, much like MateComponentMonikerSimple.

Example 20. Oaf information for an extender

MateComponent_Unknown
example_extender_resolve (MateComponentMonikerExtender *extender,
			  const MateComponent_Moniker   m,
			  const MateComponent_ResolveOptions *options,
			  const CORBA_char      *display_name,
			  const CORBA_char      *requested_interface,
			  CORBA_Environment     *ev)
{
	... resolve 'm' against an interface we know it supports ...
	... then use that interface to provide requested_interface ...
}


It is registered again in much the same way in your factory:

Example 21. Creating a new simple moniker

static MateComponentObject *
matecomponent_std_moniker_factory (MateComponentGenericFactory *this,
			    const char           *object_id,
			    void                 *data)
{
	g_return_val_if_fail (object_id != NULL, NULL);
	if (!strcmp (object_id, "OAFIID:MateComponent_MonikerExtender_file"))
		return MATECOMPONENT_OBJECT (matecomponent_moniker_extender_new (
			example_extender_resolve, NULL));
	else
		return NULL;
}


Details

struct MateComponentMonikerExtender

struct MateComponentMonikerExtender;

Implements a moniker extender: MateComponent::MonikerExtender.

MateComponentMonikerExtenderClass

typedef struct {
	MateComponentObjectClass      parent_class;

	POA_MateComponent_MonikerExtender__epv epv;

	MateComponentMonikerExtenderFn resolve;
} MateComponentMonikerExtenderClass;

MateComponentMonikerExtender's class.

MateComponentMonikerExtenderFn ()

MateComponent_Unknown (*MateComponentMonikerExtenderFn) (MateComponentMonikerExtender *extender,
                                                         const MateComponent_Moniker parent,
                                                         const MateComponent_ResolveOptions *options,
                                                         const CORBA_char *display_name,
                                                         const CORBA_char *requested_interface,
                                                         CORBA_Environment *ev);

Moniker resolution callback function.

extender :

 extender (self)

parent :

 parent moniker

options :

 resolve options

display_name :

 ? FIXME

requested_interface :

 ? FIXME

Returns :

 the resolution resulting object

matecomponent_moniker_extender_new ()

MateComponentMonikerExtender * matecomponent_moniker_extender_new
                                                        (MateComponentMonikerExtenderFn resolve,
                                                         gpointer data);

This creates a new moniker extender.

resolve :

 the resolve function that will be used to do the extension

data :

 user data to be passed back to the resolve function.

Returns :

 the extender object

matecomponent_moniker_find_extender ()

MateComponent_MonikerExtender matecomponent_moniker_find_extender
                                                        (const gchar *name,
                                                         const gchar *interface,
                                                         CORBA_Environment *opt_ev);

This routine tries to locate an extender for our moniker by examining a registry of extenders that map new interfaces to certain moniker names.

name :

 the name of the moniker we want to extend eg. 'file:'

interface :

 the interface we want to resolve to

opt_ev :

 an optional corba exception environment.

Returns :

 an appropriate extender or CORBA_OBJECT_NIL.

matecomponent_moniker_use_extender ()

MateComponent_Unknown matecomponent_moniker_use_extender
                                                        (const gchar *extender_oafiid,
                                                         MateComponentMoniker *moniker,
                                                         const MateComponent_ResolveOptions *options,
                                                         const CORBA_char *requested_interface,
                                                         CORBA_Environment *opt_ev);

Locates a known extender via. OAFIID; eg. OAFIID:MateComponent_Moniker_Extender_file

extender_oafiid :

 The IID of the extender to use

moniker :

 the moniker to extend

options :

 resolve options

requested_interface :

 the requested interface

opt_ev :

 optional corba environment

Returns :

 the resolved result or CORBA_OBJECT_NIL.
Generated by GTK-Doc V1.18