MateComponentGenericFactory

## MateComponentGenericFactory MateComponentGenericFactory — The basic, generic MateComponent object factory implementation |

## Synopsis

    MateComponentObject *      (*MateComponentFactoryCallback)            (MateComponentGenericFactory *factory,
                                                             const char *component_id,
                                                             gpointer closure);
    MateComponentGenericFactory * matecomponent_generic_factory_new       (const char *act_iid,
                                                             MateComponentFactoryCallback factory_cb,
                                                             gpointer user_data);
    MateComponentGenericFactory * matecomponent_generic_factory_new_closure
                                                            (const char *act_iid,
                                                             GClosure *factory_closure);
    MateComponentGenericFactory * matecomponent_generic_factory_construct (MateComponentGenericFactory *factory,
                                                             const char *act_iid,
                                                             GClosure *factory_closure);
    void                matecomponent_generic_factory_construct_noreg
                                                            (MateComponentGenericFactory *factory,
                                                             const char *act_iid,
                                                             GClosure *factory_closure);
    int                 matecomponent_generic_factory_main         (const char *act_iid,
                                                             MateComponentFactoryCallback factory_cb,
                                                             gpointer user_data);
    int                 matecomponent_generic_factory_main_timeout (const char *act_iid,
                                                             MateComponentFactoryCallback factory_cb,
                                                             gpointer user_data,
                                                             guint quit_timeout);
    #define             MATECOMPONENT_FACTORY_INIT                 (descr,
                                                             version,
                                                             argcp,
                                                             argv)
    #define             MATECOMPONENT_OAF_FACTORY                  (oafiid,
                                                             descr,
                                                             version,
                                                             callback,
                                                             data)
    #define             MATECOMPONENT_OAF_FACTORY_MULTI            (oafiid,
                                                             descr,
                                                             version,
                                                             callback,
                                                             data)
    #define             MATECOMPONENT_ACTIVATION_FACTORY           (oafiid,
                                                             descr,
                                                             version,
                                                             callback,
                                                             data)
    #define             MATECOMPONENT_ACTIVATION_FACTORY_TIMEOUT   (oafiid,
                                                             descr,
                                                             version,
                                                             callback,
                                                             data,
                                                             quit_timeout)

## Description

The vast majority of MateComponent objects are created by the MateComponentGenericFactory implementation. This provides a very simple C sugar wrapper of the MATE::ObjectFactory IDL interface, used by OAF to instantiate new objects.

Most applications when they start up will register their MateComponent object factory with OAF, this can be done like this:

Example 7. How to register a factory with OAF

    1
    2
    3
    4
    5
    MateComponentGenericFactory *factory;
    factory = matecomponent_generic_factory_new (
        "OAFIID:MATE_MyApp_myId",
        my_factory_function, NULL);
    matecomponent_running_context_auto_exit_unref (MATECOMPONENT_OBJECT (factory));

This registers the factory with OAF, associated with your factory's OAFIID ( as specified in the installed .oaf file ). The running_context_auto_exit_unref function is used to ensure that the program exits the gtk main loop when all of the factory's ( or any derived ) objects are destroyed.

When an object that is created by your factory is demanded from OAF the my_factory_function will be called:

Example 8. A simple factory

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    static MateComponentObject *
    my_factory_fn (MateComponentGenericFactory *this,
                   const char           *object_id,
                   void                 *data)
    {
        MateComponentObject *object = NULL;
        g_return_val_if_fail (object_id != NULL, NULL);
        if (!strcmp (object_id, "OAFIID:MateComponent_Sample_Clock"))
            object = matecomponent_clock_control_new ();
        else
            g_warning ("Unknown OAFIID '%s'", object_id);
        return object;
    }

This will return the newly constructed object via OAF to the Object requestor.

There is a macro that can be used for simple components to remove the burden of writing the main function and getting the initialization correct, see MATECOMPONENT_ACTIVATION_FACTORY.

## Details

### MateComponentFactoryCallback ()

    MateComponentObject *      (*MateComponentFactoryCallback)            (MateComponentGenericFactory *factory,
                                                             const char *component_id,
                                                             gpointer closure);

Type of function that is called when it's time for the factory to create a new instance.

`factory` : | the factory that invoked this callback
`component_id` : | OAFIID of the component that should be activated
`closure` : | user data
Returns : | the newly created MateComponentObject

### matecomponent_generic_factory_new ()

    MateComponentGenericFactory * matecomponent_generic_factory_new       (const char *act_iid,
                                                             MateComponentFactoryCallback factory_cb,
                                                             gpointer user_data);

This is a helper routine that simplifies the creation of factory objects for MATE objects. The `factory` function will be invoked by the CORBA server when a request arrives to create a new instance of an object supporting the MateComponent::Generic interface. The factory callback routine is passed the `data` pointer to provide the creation function with some state information.

`act_iid` : | The GOAD id that this factory implements
`factory_cb` : | A callback which is used to create new MateComponentObject instances.
`user_data` : | The closure data to be passed to the `factory` callback routine.
Returns : | A MateComponentGenericFactory object that has an activated MateComponent::GenericFactory object that has registered with the MATE name server.

### matecomponent_generic_factory_new_closure ()

    MateComponentGenericFactory * matecomponent_generic_factory_new_closure
                                                            (const char *act_iid,
                                                             GClosure *factory_closure);

This is a helper routine that simplifies the creation of factory objects for MATE objects. The `factory_closure` closure will be invoked by the CORBA server when a request arrives to create a new instance of an object supporting the MateComponent::Generic interface. The factory callback routine is passed the `data` pointer to provide the creation function with some state information.

`act_iid` : | The GOAD id that this factory implements
`factory_closure` : | A closure which is used to create new MateComponentObject instances.
Returns : | A MateComponentGenericFactory object that has an activated MateComponent::GenericFactory object that has registered with the MATE name server.

### matecomponent_generic_factory_construct ()

    MateComponentGenericFactory * matecomponent_generic_factory_construct (MateComponentGenericFactory *factory,
                                                             const char *act_iid,
                                                             GClosure *factory_closure);

Initializes `c_factory` with and registers the new factory with the name server.

`factory` : | The object to be initialized.
`act_iid` : | The MateComponent activation id that the new factory will implement. MateComponent::GenericFactory interface and which will be used to construct this MateComponentGenericFactory Gtk object.
`factory_closure` : | A Multi object factory closure.
Returns : | The initialized MateComponentGenericFactory object or NULL if already registered.

### matecomponent_generic_factory_construct_noreg ()

    void                matecomponent_generic_factory_construct_noreg
                                                            (MateComponentGenericFactory *factory,
                                                             const char *act_iid,
                                                             GClosure *factory_closure);

Initializes `c_factory` with the supplied closure and iid.

`factory` : | The object to be initialized.
`act_iid` : | The GOAD id that the new factory will implement.
`factory_closure` : | A Multi object factory closure.

### matecomponent_generic_factory_main ()

    int                 matecomponent_generic_factory_main         (const char *act_iid,
                                                             MateComponentFactoryCallback factory_cb,
                                                             gpointer user_data);

A Generic 'main' routine so we don't stick a load of code inside a public macro. See also `matecomponent_generic_factory_main_timeout()`.

`act_iid` : | the oaf iid of the factory
`factory_cb` : | the factory callback
`user_data` : | a user data pointer
Returns : | 0 on success, 1 on failure.

### matecomponent_generic_factory_main_timeout ()

    int                 matecomponent_generic_factory_main_timeout (const char *act_iid,
                                                             MateComponentFactoryCallback factory_cb,
                                                             gpointer user_data,
                                                             guint quit_timeout);

A Generic 'main' routine so we don't stick a load of code inside a public macro.

`act_iid` : | the oaf iid of the factory
`factory_cb` : | the factory callback
`user_data` : | a user data pointer
`quit_timeout` : | ammount of time to wait (miliseconds) after all objects have been released before quitting the main loop.
Returns : | 0 on success, 1 on failure.

### MATECOMPONENT_FACTORY_INIT()

    #define             MATECOMPONENT_FACTORY_INIT(descr, version, argcp, argv)

Macro that expands to the code need to initialize an exe factory. Should be placed at the beginning of the `main()` function.

`descr` : | factory description string
`version` : | version string
`argcp` : | pointer to `main()`'s argc
`argv` : | main()'s argv

### MATECOMPONENT_OAF_FACTORY()

    #define             MATECOMPONENT_OAF_FACTORY(oafiid, descr, version, callback, data)

Deprecated; see `MATECOMPONENT_ACTIVATION_FACTORY()`.

`oafiid` : |
`descr` : |
`version` : |
`callback` : |
`data` : |

### MATECOMPONENT_OAF_FACTORY_MULTI()

    #define             MATECOMPONENT_OAF_FACTORY_MULTI(oafiid, descr, version, callback, data)

Deprecated; see `MATECOMPONENT_ACTIVATION_FACTORY()`.

`oafiid` : |
`descr` : |
`version` : |
`callback` : |
`data` : |

### MATECOMPONENT_ACTIVATION_FACTORY()

    #define             MATECOMPONENT_ACTIVATION_FACTORY(oafiid, descr, version, callback, data)

Macro that includes all boiler-plate code necessary to create an exe type factory, including a `main()` function and a generic factory.

`oafiid` : | The factory's OAFIID
`descr` : | Description of the factory
`version` : | Version string of the factory program
`callback` : | Function (MateComponentFactoryCallback) responsible for intantiating components
`data` : | Additional data to be passed to the callback

### MATECOMPONENT_ACTIVATION_FACTORY_TIMEOUT()

    #define             MATECOMPONENT_ACTIVATION_FACTORY_TIMEOUT(oafiid, descr, version, callback, data, quit_timeout)

Like `MATECOMPONENT_ACTIVATION_FACTORY()`, but has an extra `quit_timeout` argument.

`oafiid` : | The factory's OAFIID
`descr` : | Description of the factory
`version` : | Version string of the factory program
`callback` : | Function (MateComponentFactoryCallback) responsible for intantiating components
`data` : | Additional data to be passed to the callback
`quit_timeout` : | Ammount of time to wait (in milliseconds) before deciding to quit the factory. A larger value prevents frequent respawning of a new factory process when there are many consecutive one-time requests, so that your factory appears to start faster after the first time.