File: //usr/share/gtk-doc/html/bonobo-activation/bonobo-activation-Query-and-Activation.html
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Query and Activation</title>
<meta name="generator" content="DocBook XSL Stylesheets V1.69.1">
<link rel="start" href="index.html" title="Bonobo Activation API Reference Manual">
<link rel="up" href="api-reference.html" title="API Reference">
<link rel="prev" href="bonobo-activation-Initialization.html" title="Initialization">
<link rel="next" href="bonobo-activation-Utilities.html" title="Utilities">
<meta name="generator" content="GTK-Doc V1.7 (XML mode)">
<link rel="stylesheet" href="style.css" type="text/css">
<link rel="chapter" href="tutorial.html" title="Bonobo Activation tutorial">
<link rel="chapter" href="configuring.html" title="Configuring Bonobo Activation">
<link rel="chapter" href="architecture.html" title="Bonobo Activation Architecture">
<link rel="chapter" href="query-langage.html" title="Bonobo Activation Query Langage">
<link rel="chapter" href="server-xml-reference.html" title=".server file format reference">
<link rel="chapter" href="migrating.html" title="Migrating from gnorba to Bonobo-activation">
<link rel="chapter" href="api-reference.html" title="API Reference">
<link rel="article" href="lgpl.html" title="GNU Lesser General Public License">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2">
<tr valign="middle">
<td><a accesskey="p" href="bonobo-activation-Initialization.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
<td><a accesskey="u" href="api-reference.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
<td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
<th width="100%" align="center">Bonobo Activation API Reference Manual</th>
<td><a accesskey="n" href="bonobo-activation-Utilities.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
</tr>
<tr><td colspan="5" class="shortcuts"><nobr><a href="#id2973211" class="shortcut">Top</a>
 | 
<a href="#id2973597" class="shortcut">Description</a></nobr></td></tr>
</table>
<div class="refentry" lang="en">
<a name="bonobo-activation-Query-and-Activation"></a><div class="titlepage"></div>
<div class="refnamediv"><table width="100%"><tr>
<td valign="top">
<h2>
<a name="id2973211"></a><span class="refentrytitle">Query and Activation</span>
</h2>
<p>Query and Activation — Querying for components and Activating them</p>
</td>
<td valign="top" align="right"></td>
</tr></table></div>
<div class="refsynopsisdiv">
<h2>Synopsis</h2>
<pre class="synopsis">
#include <bonobo-activation/bonobo-activation.h>
typedef <a href="bonobo-activation-Query-and-Activation.html#Bonobo-ImplementationID">Bonobo_ImplementationID</a>;
typedef <a href="bonobo-activation-Query-and-Activation.html#Bonobo-ActivationID">Bonobo_ActivationID</a>;
typedef <a href="bonobo-activation-Query-and-Activation.html#Bonobo-ActivationFlags">Bonobo_ActivationFlags</a>;
enum <a href="bonobo-activation-Query-and-Activation.html#Bonobo-ActivationResultType">Bonobo_ActivationResultType</a>;
<a href="bonobo-activation-Utilities.html#Bonobo-ServerInfoList">Bonobo_ServerInfoList</a>* <a href="bonobo-activation-Query-and-Activation.html#bonobo-activation-query">bonobo_activation_query</a>
(const char *requirements,
char *const *selection_order,
CORBA_Environment *ev);
CORBA_Object <a href="bonobo-activation-Query-and-Activation.html#bonobo-activation-activate">bonobo_activation_activate</a> (const char *requirements,
char *const *selection_order,
<a href="bonobo-activation-Query-and-Activation.html#Bonobo-ActivationFlags">Bonobo_ActivationFlags</a> flags,
<a href="bonobo-activation-Query-and-Activation.html#Bonobo-ActivationID">Bonobo_ActivationID</a> *ret_aid,
CORBA_Environment *ev);
CORBA_Object <a href="bonobo-activation-Query-and-Activation.html#bonobo-activation-activate-from-id">bonobo_activation_activate_from_id</a>
(const <a href="bonobo-activation-Query-and-Activation.html#Bonobo-ActivationID">Bonobo_ActivationID</a> aid,
<a href="bonobo-activation-Query-and-Activation.html#Bonobo-ActivationFlags">Bonobo_ActivationFlags</a> flags,
<a href="bonobo-activation-Query-and-Activation.html#Bonobo-ActivationID">Bonobo_ActivationID</a> *ret_aid,
CORBA_Environment *ev);
void (<a href="bonobo-activation-Query-and-Activation.html#BonoboActivationCallback">*BonoboActivationCallback</a>) (CORBA_Object activated_object,
const char *error_reason,
<a
href="/usr/share/gtk-doc/html/glib/glib-Basic-Types.html#gpointer"
>gpointer</a> user_data);
void <a href="bonobo-activation-Query-and-Activation.html#bonobo-activation-activate-async">bonobo_activation_activate_async</a>
(const char *requirements,
char *const *selection_order,
<a href="bonobo-activation-Query-and-Activation.html#Bonobo-ActivationFlags">Bonobo_ActivationFlags</a> flags,
<a href="bonobo-activation-Query-and-Activation.html#BonoboActivationCallback">BonoboActivationCallback</a> callback,
<a
href="/usr/share/gtk-doc/html/glib/glib-Basic-Types.html#gpointer"
>gpointer</a> user_data,
CORBA_Environment *ev);
void <a href="bonobo-activation-Query-and-Activation.html#bonobo-activation-activate-from-id-async">bonobo_activation_activate_from_id_async</a>
(const <a href="bonobo-activation-Query-and-Activation.html#Bonobo-ActivationID">Bonobo_ActivationID</a> aid,
<a href="bonobo-activation-Query-and-Activation.html#Bonobo-ActivationFlags">Bonobo_ActivationFlags</a> flags,
<a href="bonobo-activation-Query-and-Activation.html#BonoboActivationCallback">BonoboActivationCallback</a> callback,
<a
href="/usr/share/gtk-doc/html/glib/glib-Basic-Types.html#gpointer"
>gpointer</a> user_data,
CORBA_Environment *ev);
void <a href="bonobo-activation-Query-and-Activation.html#bonobo-activation-set-activation-env-value">bonobo_activation_set_activation_env_value</a>
(const char *name,
const char *value);
</pre>
</div>
<div class="refsect1" lang="en">
<a name="id2973597"></a><h2>Description</h2>
<p>
This section describes how you can query for components
and activate them.
</p>
<p>
Two set of functions are described: synchronous and
asynchronous ones. The asynchronous version of the functions
allow you to avoid blocking your application while the CORBA
servers are started.
</p>
</div>
<div class="refsect1" lang="en">
<a name="id2973620"></a><h2>Details</h2>
<div class="refsect2" lang="en">
<a name="id2973630"></a><h3>
<a name="Bonobo-ImplementationID"></a>Bonobo_ImplementationID</h3>
<a class="indexterm" name="id2973643"></a><pre class="programlisting">typedef CORBA_string Bonobo_ImplementationID;
</pre>
<p>
</p>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id2973658"></a><h3>
<a name="Bonobo-ActivationID"></a>Bonobo_ActivationID</h3>
<a class="indexterm" name="id2973671"></a><pre class="programlisting">typedef CORBA_string Bonobo_ActivationID;
</pre>
<p>
</p>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id2973687"></a><h3>
<a name="Bonobo-ActivationFlags"></a>Bonobo_ActivationFlags</h3>
<a class="indexterm" name="id2973700"></a><pre class="programlisting">typedef CORBA_long Bonobo_ActivationFlags;
</pre>
<p>
</p>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id2973715"></a><h3>
<a name="Bonobo-ActivationResultType"></a>enum Bonobo_ActivationResultType</h3>
<a class="indexterm" name="id2973729"></a><pre class="programlisting">typedef enum {
Bonobo_ACTIVATION_RESULT_OBJECT,
Bonobo_ACTIVATION_RESULT_SHLIB,
Bonobo_ACTIVATION_RESULT_NONE
} Bonobo_ActivationResultType;
</pre>
<p>
</p>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id2973746"></a><h3>
<a name="bonobo-activation-query"></a>bonobo_activation_query ()</h3>
<a class="indexterm" name="id2973758"></a><pre class="programlisting"><a href="bonobo-activation-Utilities.html#Bonobo-ServerInfoList">Bonobo_ServerInfoList</a>* bonobo_activation_query
(const char *requirements,
char *const *selection_order,
CORBA_Environment *ev);</pre>
<p>
Executes the <em class="parameter"><code>requirements</code></em> query on the bonobo-activation-server.
The result is sorted according to <em class="parameter"><code>selection_order</code></em>.
<em class="parameter"><code>selection_order</code></em> can safely be NULL as well as <em class="parameter"><code>ev</code></em>.
The returned list has to be freed with CORBA_free.</p>
<p>
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td>
<span class="term"><em class="parameter"><code>requirements</code></em> :</span></td>
<td> query string.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>selection_order</code></em> :</span></td>
<td> sort criterion for returned list.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>ev</code></em> :</span></td>
<td> a <code class="literal">CORBA_Environment</code> structure which will contain
the CORBA exception status of the operation, or NULL
</td>
</tr>
<tr>
<td>
<span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td>
<td> the list of servers matching the requirements.
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id2973903"></a><h3>
<a name="bonobo-activation-activate"></a>bonobo_activation_activate ()</h3>
<a class="indexterm" name="id2973916"></a><pre class="programlisting">CORBA_Object bonobo_activation_activate (const char *requirements,
char *const *selection_order,
<a href="bonobo-activation-Query-and-Activation.html#Bonobo-ActivationFlags">Bonobo_ActivationFlags</a> flags,
<a href="bonobo-activation-Query-and-Activation.html#Bonobo-ActivationID">Bonobo_ActivationID</a> *ret_aid,
CORBA_Environment *ev);</pre>
<p>
Activates a given object. <em class="parameter"><code>ret_aid</code></em> can be safely NULLed as well
as <em class="parameter"><code>ev</code></em> and <em class="parameter"><code>selection_order</code></em>. <em class="parameter"><code>flags</code></em> can be set to zero if you do
not what to use.</p>
<p>
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td>
<span class="term"><em class="parameter"><code>requirements</code></em> :</span></td>
<td> query string.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>selection_order</code></em> :</span></td>
<td> sort criterion for returned list.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>flags</code></em> :</span></td>
<td> how to activate the object.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>ret_aid</code></em> :</span></td>
<td> AID of the activated object.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>ev</code></em> :</span></td>
<td> <code class="literal">CORBA_Environment</code> structure which will contain
the CORBA exception status of the operation.
</td>
</tr>
<tr>
<td>
<span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td>
<td> the CORBA object reference of the activated object.
This value can be CORBA_OBJECT_NIL: you are supposed
to check <em class="parameter"><code>ev</code></em> for success.
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id2974111"></a><h3>
<a name="bonobo-activation-activate-from-id"></a>bonobo_activation_activate_from_id ()</h3>
<a class="indexterm" name="id2974125"></a><pre class="programlisting">CORBA_Object bonobo_activation_activate_from_id
(const <a href="bonobo-activation-Query-and-Activation.html#Bonobo-ActivationID">Bonobo_ActivationID</a> aid,
<a href="bonobo-activation-Query-and-Activation.html#Bonobo-ActivationFlags">Bonobo_ActivationFlags</a> flags,
<a href="bonobo-activation-Query-and-Activation.html#Bonobo-ActivationID">Bonobo_ActivationID</a> *ret_aid,
CORBA_Environment *ev);</pre>
<p>
Activates the server corresponding to <em class="parameter"><code>aid</code></em>. <em class="parameter"><code>ret_aid</code></em> can be safely
NULLed as well as <em class="parameter"><code>ev</code></em>. <em class="parameter"><code>flags</code></em> can be zero if you do not know what
to do.</p>
<p>
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td>
<span class="term"><em class="parameter"><code>aid</code></em> :</span></td>
<td> AID or IID of the object to activate.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>flags</code></em> :</span></td>
<td> activation flag.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>ret_aid</code></em> :</span></td>
<td> AID of the activated server.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>ev</code></em> :</span></td>
<td> <code class="literal">CORBA_Environment</code> structure which will contain
the CORBA exception status of the operation.
</td>
</tr>
<tr>
<td>
<span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td>
<td> a CORBA object reference to the newly activated
server. Do not forget to check <em class="parameter"><code>ev</code></em> for failure!!
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id2974296"></a><h3>
<a name="BonoboActivationCallback"></a>BonoboActivationCallback ()</h3>
<a class="indexterm" name="id2974309"></a><pre class="programlisting">void (*BonoboActivationCallback) (CORBA_Object activated_object,
const char *error_reason,
<a
href="/usr/share/gtk-doc/html/glib/glib-Basic-Types.html#gpointer"
>gpointer</a> user_data);</pre>
<p>
This is the signature of the function which you must pass
as a callback to the asynchrounous activation functions.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td>
<span class="term"><em class="parameter"><code>activated_object</code></em> :</span></td>
<td>
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>error_reason</code></em> :</span></td>
<td>
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>user_data</code></em> :</span></td>
<td>
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id2974401"></a><h3>
<a name="bonobo-activation-activate-async"></a>bonobo_activation_activate_async ()</h3>
<a class="indexterm" name="id2974414"></a><pre class="programlisting">void bonobo_activation_activate_async
(const char *requirements,
char *const *selection_order,
<a href="bonobo-activation-Query-and-Activation.html#Bonobo-ActivationFlags">Bonobo_ActivationFlags</a> flags,
<a href="bonobo-activation-Query-and-Activation.html#BonoboActivationCallback">BonoboActivationCallback</a> callback,
<a
href="/usr/share/gtk-doc/html/glib/glib-Basic-Types.html#gpointer"
>gpointer</a> user_data,
CORBA_Environment *ev);</pre>
<p>
This function will asynchronously try to activate a component
given the <em class="parameter"><code>requirements</code></em> query string. When the component is
activated or when the activation fails, it will call <em class="parameter"><code>callback</code></em>
with the given <em class="parameter"><code>user_data</code></em> data as parameter.
callback will be called with a CORBA_OBJECT_NIL object if the
activation fails. If the activation fails, the callback will be
given a human-readable string containing a description of the
error. In case of sucess, the error string value is undefined.
</p>
<p>
<em class="parameter"><code>selection_order</code></em> can be safely NULLed as well as <em class="parameter"><code>ev</code></em> and
<em class="parameter"><code>user_data</code></em>. <em class="parameter"><code>flags</code></em> can be set to 0 if you do not know what to
use.</p>
<p>
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td>
<span class="term"><em class="parameter"><code>requirements</code></em> :</span></td>
<td> the bonobo-activation query string.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>selection_order</code></em> :</span></td>
<td> preference array.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>flags</code></em> :</span></td>
<td> activation flags.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>callback</code></em> :</span></td>
<td> callback function.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>user_data</code></em> :</span></td>
<td> data to be poassed to the callback function.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>ev</code></em> :</span></td>
<td> exception structure.
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id2974629"></a><h3>
<a name="bonobo-activation-activate-from-id-async"></a>bonobo_activation_activate_from_id_async ()</h3>
<a class="indexterm" name="id2974643"></a><pre class="programlisting">void bonobo_activation_activate_from_id_async
(const <a href="bonobo-activation-Query-and-Activation.html#Bonobo-ActivationID">Bonobo_ActivationID</a> aid,
<a href="bonobo-activation-Query-and-Activation.html#Bonobo-ActivationFlags">Bonobo_ActivationFlags</a> flags,
<a href="bonobo-activation-Query-and-Activation.html#BonoboActivationCallback">BonoboActivationCallback</a> callback,
<a
href="/usr/share/gtk-doc/html/glib/glib-Basic-Types.html#gpointer"
>gpointer</a> user_data,
CORBA_Environment *ev);</pre>
<p>
This function will asynchronously try to activate a component
with the given <em class="parameter"><code>aid</code></em>. When the component is
activated or when the activation fails, it will call <em class="parameter"><code>callback</code></em>
with the given <em class="parameter"><code>user_data</code></em> data as parameter.
callback will be called with a CORBA_OBJECT_NIL object if the
activation fails. If the activation fails, the callback will be
given a human-readable string containing a description of the
error. In case of sucess, the error string value is undefined.
</p>
<p>
<em class="parameter"><code>flags</code></em> can be 0 if you do not know what to set it to and
<em class="parameter"><code>ev</code></em> can be safely set to NULL.</p>
<p>
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td>
<span class="term"><em class="parameter"><code>aid</code></em> :</span></td>
<td> the AID or IID of the component to activate.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>flags</code></em> :</span></td>
<td> activation flags.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>callback</code></em> :</span></td>
<td> callback function.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>user_data</code></em> :</span></td>
<td> data to be poassed to the callback function.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>ev</code></em> :</span></td>
<td> exception structure.
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id2974824"></a><h3>
<a name="bonobo-activation-set-activation-env-value"></a>bonobo_activation_set_activation_env_value ()</h3>
<a class="indexterm" name="id2974839"></a><pre class="programlisting">void bonobo_activation_set_activation_env_value
(const char *name,
const char *value);</pre>
<p>
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td>
<span class="term"><em class="parameter"><code>name</code></em> :</span></td>
<td>
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>value</code></em> :</span></td>
<td>
</td>
</tr>
</tbody>
</table></div>
</div>
</div>
</div>
</body>
</html>