bonobo-application

## bonobo-application bonobo-application — a framework for unique application instance and automation |

## Synopsis

    void        (*BonoboAppHookFunc)            (BonoboApplication *app,
                                                 gpointer data);
    BonoboApplication* bonobo_application_new   (const char *name);
    void        bonobo_application_register_message
                                                (BonoboApplication *app,
                                                 const gchar *name,
                                                 const gchar *description,
                                                 GClosure *opt_closure,
                                                 GType return_type,
                                                 GType first_arg_type,
                                                 ...);
    void        bonobo_application_register_message_v
                                                (BonoboApplication *app,
                                                 const gchar *name,
                                                 const gchar *description,
                                                 GClosure *opt_closure,
                                                 GType return_type,
                                                 GType const         arg_types[]);
    void        bonobo_application_register_message_va
                                                (BonoboApplication *app,
                                                 const gchar *name,
                                                 const gchar *description,
                                                 GClosure *opt_closure,
                                                 GType return_type,
                                                 GType first_arg_type,
                                                 va_list var_args);
    gint        bonobo_application_new_instance (BonoboApplication *app,
                                                 gint argc,
                                                 gchar *argv[]);
    gchar*      bonobo_application_create_serverinfo
                                                (BonoboApplication *app,
                                                 gchar const        *envp[]);
    Bonobo_RegistrationResult bonobo_application_register_unique
                                                (BonoboApplication *app,
                                                 gchar const        *serverinfo,
                                                 BonoboAppClient **client);
    void        bonobo_application_add_hook     (BonoboAppHookFunc func,
                                                 gpointer data);
    void        bonobo_application_remove_hook  (BonoboAppHookFunc func,
                                                 gpointer data);

## Description

## Details

### BonoboAppHookFunc ()

    void        (*BonoboAppHookFunc)            (BonoboApplication *app,
                                                 gpointer data);

`app` : |
`data` : |

### bonobo_application_new ()

    BonoboApplication* bonobo_application_new   (const char *name);

Creates a new BonoboApplication object.

`name` : | application name
Returns : | a new BonoboApplication

### bonobo_application_register_message ()

    void        bonobo_application_register_message
                                                (BonoboApplication *app,
                                                 const gchar *name,
                                                 const gchar *description,
                                                 GClosure *opt_closure,
                                                 GType return_type,
                                                 GType first_arg_type,
                                                 ...);

Registers a new message type that the application supports.

When `opt_closure` is provided (and is non-`NULL`) it takes care of calling the callback function with the same arguments as registered for the message. On the other hand if `opt_closure` is `NULL`, the function arguments are provided in a GValueArray. This enables defining functions that accept variable number of arguments, but is perhaps a little more tedious to implement.

Example 5. Function with a closure

    static void
    message_open_url_cb (BonoboApplication *app, const char *url, gboolean new_win)
    {
    	...
    }
    ...
    closure = g_cclosure_new (G_CALLBACK (message_open_url_cb), NULL, NULL);
    g_closure_set_marshal (closure, my_marshal_VOID__STRING_BOOLEAN);
    bonobo_application_register_message (app, "open-url", "Opens a new URL in the browser."
                                         " Parameters: url(string), open-in-new-window(boolean)",
                                         closure, G_TYPE_NONE, G_TYPE_STRING, G_TYPE_BOOLEAN, G_TYPE_NONE);

Example 6. Function accepting variable number of arguments

    static GValue *
    message_open_url_cb (BonoboApplication *app, const char *message, GValueArray *args)
    {
    	const char *url;
    	gboolean    new_win = TRUE;

    	g_return_val_if_fail (strcmp (message, "open-url") == 0, NULL);
    	g_return_val_if_fail (args->n_values > 0, NULL);
    	g_return_val_if_fail (G_VALUE_HOLDS_STRING (&args->values[0]), NULL);

    	url = g_value_get_string (&args->values[0]);
    	if (args->n_values > 1)
    	{
    		g_return_val_if_fail (G_VALUE_HOLDS_BOOLEAN (&args->values[1]), NULL);
    		new_win = g_value_get_boolean (&args->values[1]);
    	}

    	...

    	return NULL;
    }
    ...
    bonobo_application_register_message (app, "open-url", "Opens a new URL in the browser."
                                         " Parameters: url(string) [, open-in-new-window(boolean)]",
                                         NULL, G_TYPE_NONE, G_TYPE_STRING, G_TYPE_BOOLEAN, G_TYPE_NONE);

    g_signal_connect (app, "message::open-url", G_CALLBACK (message_open_url_cb), NULL);

### Note

You are not required to register any messages for your application. However, only registered functions are included in the list returned by `bonobo_app_client_msg_list()`

`app` : | a BonoboApplication
`name` : | message string identifier
`description` : | a string containing a human readable description of the message
`opt_closure` : | a GClosure that will be called for this message, or `NULL`; Function takes ownership of this closure.
`return_type` : | Message return GType.
`first_arg_type` : | GType of first argument of message, or `G_TYPE_NONE`.
`...` : | `G_TYPE_NONE` -terminated list of argument GType's

### bonobo_application_register_message_v ()

    void        bonobo_application_register_message_v
                                                (BonoboApplication *app,
                                                 const gchar *name,
                                                 const gchar *description,
                                                 GClosure *opt_closure,
                                                 GType return_type,
                                                 GType const         arg_types[]);

See `bonobo_application_register_message()`.

`app` : | a BonoboApplication
`name` : | message string identifier
`description` : | a string containing a human readable description of the message
`opt_closure` : | a GClosure that will be called for this message, or `NULL`; Function takes ownership of this closure.
`return_type` : | Message return GType.
`arg_types` : | `G_TYPE_NONE` -terminated vector of argument GType's

### bonobo_application_register_message_va ()

    void        bonobo_application_register_message_va
                                                (BonoboApplication *app,
                                                 const gchar *name,
                                                 const gchar *description,
                                                 GClosure *opt_closure,
                                                 GType return_type,
                                                 GType first_arg_type,
                                                 va_list var_args);

See `bonobo_application_register_message()`.

`app` : | a BonoboApplication
`name` : | message string identifier
`description` : | a string containing a human readable description of the message
`opt_closure` : | a GClosure that will be called for this message, or `NULL`; Function takes ownership of this closure.
`return_type` : | Message return GType.
`first_arg_type` : | GType of first argument of message, or `G_TYPE_NONE`
`var_args` : | `G_TYPE_NONE` -terminated valist of argument GType's

### bonobo_application_new_instance ()

    gint        bonobo_application_new_instance (BonoboApplication *app,
                                                 gint argc,
                                                 gchar *argv[]);

Emit the "new-instance" signal of the BonoboApplication with the given arguments.

`app` : | a BonoboApplication
`argc` : | number of elements in `argv`
`argv` : | array of strings (command-line arguments)
Returns : | signal return value

### bonobo_application_create_serverinfo ()

    gchar*      bonobo_application_create_serverinfo
                                                (BonoboApplication *app,
                                                 gchar const        *envp[]);

This utility function provides a simple way to contruct a valid serverinfo XML string.

`app` : | a BonoboApplication
`envp` : | `NULL`-terminated string vector, containing the enviroment variables we wish to include in the server description.
Returns : | a newly allocated string; caller must `g_free()` it.

### bonobo_application_register_unique ()

    Bonobo_RegistrationResult bonobo_application_register_unique
                                                (BonoboApplication *app,
                                                 gchar const        *serverinfo,
                                                 BonoboAppClient **client);

Try to register the running application, or check for an existing application already registered and get a reference to it. Applications already running but on different environments (as defined by the bonobo:environenment server property) than this one are ignored and do not interfere.

If the registration attempt indicates that another instance of this application is already running, then the output variable `client` will receive a newly created BonoboAppClient associated with the running application. Otherwise, *`client` is set to `NULL`.

`app` : | a BonoboApplication instance
`serverinfo` : | the XML server description. `bonobo_application_create_server_description()` may be used to easily create such description.
`client` : | output parameter that will contain a client object, in case another instance has already running, or `NULL` if we are the first to register.
Returns : | the registration result. `Bonobo_ACTIVATION_REG_SUCCESS` means the application was registered, since no other running instance was detected. If, however, a running application is detected, `Bonobo_ACTIVATION_REG_ALREADY_ACTIVE` is returned.

### bonobo_application_add_hook ()

    void        bonobo_application_add_hook     (BonoboAppHookFunc func,
                                                 gpointer data);

Add a hook function to be called whenever a new BonoboApplication instance is created.

`func` : | hook function
`data` : | user data

### bonobo_application_remove_hook ()

    void        bonobo_application_remove_hook  (BonoboAppHookFunc func,
                                                 gpointer data);

Removes a hook function previously set with `bonobo_application_add_hook()`.

`func` : | hook function
`data` : | user data