bonobo-async

Bonobo API Reference Manual
<<< Previous Page	Home	Up

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.