Bonobo API Reference Manual
<<< Previous Page | Home | Up |

# bonobo-async

## Name

bonobo-async -- Helpers for invoking CORBA methods asynchronously

## Synopsis

    enum        BonoboAsyncArgFlag;
    typedef     BonoboAsyncArg;
    typedef     BonoboAsyncMethod;
    struct      BonoboAsyncReply;
    void        (*BonoboAsyncCallback)          (BonoboAsyncReply *reply,
                                                 CORBA_Environment *ev,
                                                 gpointer user_data);
    void        bonobo_async_demarshal          (BonoboAsyncReply *reply,
                                                 gpointer retval,
                                                 gpointer *out_args);
    void        bonobo_async_invoke             (const BonoboAsyncMethod *method,
                                                 BonoboAsyncCallback cb,
                                                 gpointer user_data,
                                                 guint timeout_msec,
                                                 CORBA_Object object,
                                                 gpointer *args,
                                                 CORBA_Environment *ev);
    GIOPRecvBuffer* bonobo_async_handle_get_recv
                                                (BonoboAsyncReply *reply);

## Description

The bonobo-async interface duplicates much of the equivalent CORBA asynchronous invocation functionality, in a non-standard way. This is regrettable, but appeared neccessary at the time for various reasons. This interface will be short lived, disappearing in the next versions of Bonobo.

The bonobo-async code uses fully type driven marshaling, so before you can invoke a method you need to fully describe the method you wish to invoke by constructing its type data. You probably really don't want to do this, however here is some example code to demonstrate how it can be done:

Example 1. A chunk of the asynchronous moniker code

    typedef struct {
    	Bonobo_Moniker       moniker;
    	BonoboMonikerAsyncFn cb;
    	gpointer             user_data;
    } resolve_async_ctx_t;

    static void
    resolve_async_cb (BonoboAsyncReply  *handle,
    		  CORBA_Environment *ev,
    		  gpointer           user_data)
    {
    	resolve_async_ctx_t *ctx = user_data;

    	if (BONOBO_EX (ev))
    		ctx->cb (CORBA_OBJECT_NIL, ev, ctx->user_data);
    	else {
    		Bonobo_Unknown object;
    		bonobo_async_demarshal (handle, &object, NULL);
    		ctx->cb (object, ev, ctx->user_data);
    	}

    	bonobo_object_release_unref (ctx->moniker, ev);
    	g_free (ctx);
    }

    void
    bonobo_moniker_resolve_async (Bonobo_Moniker         moniker,
    			      Bonobo_ResolveOptions *options,
    			      const char            *interface_name,
    			      CORBA_Environment     *ev,
    			      guint                  timeout_msec,
    			      BonoboMonikerAsyncFn   cb,
    			      gpointer               user_data)
    {
    	/*
    	 * A chunk of data describing the 'resolve' method.
    	 */
    	static const BonoboAsyncArg arguments [] = {
    		{ TC_Bonobo_ResolveOptions, BONOBO_ASYNC_IN },
    		{ TC_string,                BONOBO_ASYNC_IN },
    		{ NULL }
    	};
    	static const CORBA_TypeCode exceptions [] = {
    		TC_Bonobo_Moniker_InterfaceNotFound,
    		TC_Bonobo_Moniker_UnknownPrefix,
    		NULL
    	};
    	static const BonoboAsyncMethod method = {
    		"resolve",
    		TC_Object,
    		arguments,
    		exceptions
    	};
    	gpointer arg_values [2] = { &options, &interface_name };
    	resolve_async_ctx_t *ctx;

    	g_return_if_fail (ev != NULL);
    	g_return_if_fail (cb != NULL);
    	g_return_if_fail (moniker != CORBA_OBJECT_NIL);
    	g_return_if_fail (options != CORBA_OBJECT_NIL);
    	g_return_if_fail (interface_name != CORBA_OBJECT_NIL);

    	ctx = g_new0 (resolve_async_ctx_t, 1);
    	ctx->cb = cb;
    	ctx->user_data = user_data;
    	ctx->moniker = bonobo_object_dup_ref (moniker, ev);

    	bonobo_async_invoke (&method, resolve_async_cb, ctx,
    			     timeout_msec, ctx->moniker, arg_values, ev);
    }

## Details

### enum BonoboAsyncArgFlag

    typedef enum {
    	BONOBO_ASYNC_IN  = 0x1,
    	BONOBO_ASYNC_OUT = 0x2
    } BonoboAsyncArgFlag;

An enumeration flagging the direction of an argument.

`BONOBO_ASYNC_IN` | Flags an argument as being In
`BONOBO_ASYNC_OUT` | Flags an argument as being Out

### BonoboAsyncArg

    typedef struct {
    	const CORBA_TypeCode  type;
    	BonoboAsyncArgFlag    flag;
    } BonoboAsyncArg;

A type describing a single CORBA method argument

### BonoboAsyncMethod

    typedef struct {
    	const char           *name;
    	const CORBA_TypeCode  ret_type;
    	const BonoboAsyncArg *arguments;  /* NULL-terminated */
    	const CORBA_TypeCode *exceptions; /* NULL-terminated */
    } BonoboAsyncMethod;

A type describing a CORBA method

### struct BonoboAsyncReply

    struct BonoboAsyncReply;

An opaque async reply handle

### BonoboAsyncCallback ()

    void        (*BonoboAsyncCallback)          (BonoboAsyncReply *reply,
                                                 CORBA_Environment *ev,
                                                 gpointer user_data);

This callback is invoked either when the invocation times out, in which case an ex_CORBA_COMM_FAILURE system exception will be passed in `ev`. Or with a valid reply, in which case arguments should be de-marshaled using bonobo_async_demarshal.

`reply` : | the reply handle
`ev` : | the CORBA_Environment
`user_data` : | the callback's associated user data.

### bonobo_async_demarshal ()

    void        bonobo_async_demarshal          (BonoboAsyncReply *reply,
                                                 gpointer retval,
                                                 gpointer *out_args);

When a user's async callback happens ( when a method's return data arrives back ) this function is typicaly used by the callback to de-marshal the arguments associated with the method, such as the `retval`, and an array of pointers to memory in which to store the returned InOut / Out arguments in order.

`reply` : |
`retval` : | pointer to variable to store retval in
`out_args` : | array of pointers to vars for InOut / Out params.

### bonobo_async_invoke ()

    void        bonobo_async_invoke             (const BonoboAsyncMethod *method,
                                                 BonoboAsyncCallback cb,
                                                 gpointer user_data,
                                                 guint timeout_msec,
                                                 CORBA_Object object,
                                                 gpointer *args,
                                                 CORBA_Environment *ev);

Given a type based description of a CORBA `method` the method is invoked asynchronously. If an error occurs in invocation an exception is fired in `ev` and `cb` will never be invoked. Otherwise, `cb` is invoked, either on the timeout - in which case an ex_CORBA_COMM_FAILURE system exception will be returned, or when the method returns with whatever data / exceptions are relevant.

`method` : | method description
`cb` : | async callback
`user_data` : | associated callback user data
`timeout_msec` : | timeout in milli-seconds
`object` : | object to invoke method on
`args` : | array of ordered In/InOut arguments in same order as in method
`ev` : | CORBA exception environment

### bonobo_async_handle_get_recv ()

    GIOPRecvBuffer* bonobo_async_handle_get_recv
                                                (BonoboAsyncReply *reply);

This method can be used to extract the internal GIOP buffer on the reply, for advanced custom de-marshaling.

`reply` : |
Returns : | the internal reply buffer.

<<< Previous Page | Home | Up |
BonoboSelector |