1 /**************************************************************************/
2 /* ---------------------------------------------------------------------- */
3 /* Copyright (C) 2006 - 2008 FRESCOR consortium partners: */
5 /* Universidad de Cantabria, SPAIN */
6 /* University of York, UK */
7 /* Scuola Superiore Sant'Anna, ITALY */
8 /* Kaiserslautern University, GERMANY */
9 /* Univ. Politécnica Valencia, SPAIN */
10 /* Czech Technical University in Prague, CZECH REPUBLIC */
12 /* Thales Communication S.A. FRANCE */
13 /* Visual Tools S.A. SPAIN */
14 /* Rapita Systems Ltd UK */
17 /* See http://www.frescor.org for a link to partners' websites */
19 /* FRESCOR project (FP6/2005/IST/5-034026) is funded */
20 /* in part by the European Union Sixth Framework Programme */
21 /* The European Union is not liable of any use that may be */
22 /* made of this code. */
25 /* This file is part of FORB (Frescor Object Request Broker) */
27 /* FORB is free software; you can redistribute it and/or modify it */
28 /* under terms of the GNU General Public License as published by the */
29 /* Free Software Foundation; either version 2, or (at your option) any */
30 /* later version. FORB is distributed in the hope that it will be */
31 /* useful, but WITHOUT ANY WARRANTY; without even the implied warranty */
32 /* of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU */
33 /* General Public License for more details. You should have received a */
34 /* copy of the GNU General Public License along with FORB; see file */
35 /* COPYING. If not, write to the Free Software Foundation, 675 Mass Ave, */
36 /* Cambridge, MA 02139, USA. */
38 /* As a special exception, including FORB header files in a file, */
39 /* instantiating FORB generics or templates, or linking other files */
40 /* with FORB objects to produce an executable application, does not */
41 /* by itself cause the resulting executable application to be covered */
42 /* by the GNU General Public License. This exception does not */
43 /* however invalidate any other reasons why the executable file might be */
44 /* covered by the GNU Public License. */
45 /**************************************************************************/
49 * @author Michal Sojka <sojkam1@fel.cvut.cz>
50 * @date Fri Aug 29 09:37:27 2008
52 * @brief Public interface to FORB. To be used by applications (both servers and clients).
62 FORB is a CORBA-like middleware build on top of FOSA (FRESCOR
63 Operating System Adaptation). Its main purpose is to provide unified
64 in-process, inter-process and inter-node communication mechanism
65 needed for implementation of FRESCOR in modular way. FORB is heavily
66 inspired by CORBA, but provides only a very limited number of CORBA
69 FORB supports one communication primitive, which is synchronous call
70 of a remote method. This operation is mapped to a local function call,
71 so that programmer cannot see the difference between the local and
72 remote invocation. FORB implements all of the operations needed for
73 such kind of communication which is:
75 - serialization and deserialization of parameters and return values,
76 - communication protocol to pass requests and replies between
78 - finding the process, where the remote operation is implemented.
80 FORB is composed of the two following components:
81 - IDL compiler (called @c forb-idl) and
82 - FORB runtime represented by @c libforb library.
84 This documentation documents the @c libforb library. The IDL compiler
85 is derived form Orbit project, and its documentation is out of scope
94 To use FORB in an application, an IDL (Interface Description Language)
95 file has to be created first. This IDL file describes the interfaces
96 used in the the application, their methods, parameters and types. The
97 IDL language is similar to a subset of C language and is defined in <a
98 href="http://www.omg.org/spec/CORBA/3.1/Interfaces/PDF/">OMG CORBA
99 specification version 3.1, part 1</a> (chapter 7: OMG IDL Syntax and
102 An example IDL file called @c myinterface.idl can look like this:
103 @include tests-idl/myinterface.idl
105 It defines the interface called @c myinterface and some other
106 (non-basic) types used in interface methods. To implement this
107 interface, we process this file with the IDL compiler:
110 $ forb-idl myinterface.idl
113 It generates four files: @c myinterface.h, @c myinterface-stubs.c, @c
114 myinterface-skels.c and @c myinterface-common.c.
116 The code of a server which implements the first two methods of this
117 interface could look like this:
119 @include tests-idl/example_server.c
121 We have to compile this file and link it with @c -skels.c and @c
122 -common.c files and the following libraries (under Linux): forb fosa
125 The client code which uses our implementation of @c myinterface could
128 @include tests-idl/example_client.c
130 It has to be compiled and linked with @c myinterface-stubs.c and @c
131 myinterface-common.c files and with the following libraries (under
132 Linux): forb fosa pthread rt ulut.
134 Note that in these examples we intentionally skipped checking for
135 errors to achieve more readable code.
142 #include <forb/forb-idl.h>
143 #include <forb/basic_types.h>
145 #include <forb/types.h>
146 #include <forb/executor.h>
147 #include <forb/object_type.h>
153 /* Incomplete types - declared in forb-internal.h */
154 struct forb_interface;
155 typedef struct forb_interface forb_interface_t;
157 typedef struct forb_init_attr {
158 const char *orb_id; /**< Name of the FORB used for debugging purposes */
159 void (*peer_discovery_callback)(const forb_orb peer_orb, const char *orb_id);
160 void (*peer_dead_callback)(const forb_orb peer_orb, const char *orb_id);
161 uint16_t fixed_tcp_port; /**< If we want FORB's inet protocol to listen on a fixed port... */
162 forb_server_id fixed_server_id; /**< If we do not want the ID to be random. (HACK) */
163 bool redistribute_hellos;
168 * Initializes FORB. This function has to be called before any other
171 * Any command line arguments used by FORB are removed from the @a
172 * argv array and @a argc is updated accordingly.
174 * @note Currently, no command line arguments are used by FORB.
176 * @param argc a pointer to the number of command line arguments.
177 * @param argv a pointer to the array of command line arguments.
178 * @param attr attributes that control FORB initialization.
180 * @return FORB object reference of NULL in case of error.
182 forb_orb forb_init(int *argc, char **argv[], const forb_init_attr_t *attr);
185 * Deallocates all resources consumed by FORB.
187 * @note Called automatically on application exit.
189 * @param orb FORB object reference to destroy.
191 void forb_destroy(forb_orb orb);
194 forb_object_release(forb_object obj);
197 forb_object_duplicate(const forb_object obj);
200 forb_instance_data(const forb_object obj);
203 forb_register_reference(forb_object object, const char *name);
206 forb_unregister_reference(forb_orb orb, const char *name);
209 forb_resolve_reference(const forb_orb orb, const char *name);
212 forb_string_to_object(const forb_orb orb, const char *string);
215 forb_object_to_string(const forb_object obj);
217 bool forb_object_is_stale(forb_object object);
220 forb_get_orb_of(const forb_object obj);
223 forb_get_server_id(const forb_object obj, forb_server_id *dest);
226 forb_get_req_source(const forb_object obj, forb_server_id *req_source);
229 forb_strerror(CORBA_Environment *env);
232 forb_daemon_prepare(const char *pid);