src/forb.h

   1 /**************************************************************************/
   2 /* ---------------------------------------------------------------------- */
   3 /* Copyright (C) 2006 - 2008 FRESCOR consortium partners:                 */
   4 /*                                                                        */
   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                */
  11 /*   ENEA                                   SWEDEN                        */
  12 /*   Thales Communication S.A.              FRANCE                        */
  13 /*   Visual Tools S.A.                      SPAIN                         */
  14 /*   Rapita Systems Ltd                     UK                            */
  15 /*   Evidence                               ITALY                         */
  16 /*                                                                        */
  17 /*   See http://www.frescor.org for a link to partners' websites          */
  18 /*                                                                        */
  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.                                               */
  23 /*                                                                        */
  24 /*                                                                        */
  25 /*  This file is part of FORB (Frescor Object Request Broker)             */
  26 /*                                                                        */
  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.                                              */
  37 /*                                                                        */
  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 /**************************************************************************/
  46
  47 /**
  48  * @file   forb.h
  49  * @author Michal Sojka <sojkam1@fel.cvut.cz>
  50  * @date   Fri Aug 29 09:37:27 2008
  51  *
  52  * @brief  Public interface to FORB. To be used by applications (both servers and clients).
  53  *
  54  *
  55  */
  56
  57 /**
  58 @mainpage
  59
  60 @section Introduction
  61
  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
  67 features.
  68
  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:
  74
  75 - serialization and deserialization of parameters and return values,
  76 - communication protocol to pass requests and replies between
  77   processes,
  78 - finding the process, where the remote operation is implemented.
  79
  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.
  83
  84 This documentation documents the @c libforb library. The IDL compiler
  85 is derived form Orbit project, and its documentation is out of scope
  86 of this document.
  87
  88 @section Compilation
  89
  90 See README file.
  91
  92 @section Usage
  93
  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
 100 Semantics).
 101
 102 An example IDL file called @c myinterface.idl can look like this:
 103 @include tests-idl/myinterface.idl
 104
 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:
 108
 109 \verbatim
 110 $ forb-idl myinterface.idl
 111 \endverbatim
 112
 113 It generates four files: @c myinterface.h, @c myinterface-stubs.c, @c
 114 myinterface-skels.c and @c myinterface-common.c.
 115
 116 The code of a server which implements the first two methods of this
 117 interface could look like this:
 118
 119 @include tests-idl/example_server.c
 120
 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
 123 pthread rt ulut.
 124
 125 The client code which uses our implementation of @c myinterface could
 126 look like this:
 127
 128 @include tests-idl/example_client.c
 129
 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.
 133
 134 Note that in these examples we intentionally skipped checking for
 135 errors to achieve more readable code.
 136 */
 137
 138
 139 #ifndef FORB_H
 140 #define FORB_H
 141
 142 #include <forb/forb-idl.h>
 143 #include <forb/basic_types.h>
 144 #include <fosa.h>
 145 #include <forb/types.h>
 146 #include <forb/executor.h>
 147 #include <forb/object_type.h>
 148
 149
 150 /* Incomplete types - declared in forb-internal.h */
 151 struct forb_interface;
 152 typedef struct forb_interface forb_interface_t;
 153
 154 /**
 155  * Initializes FORB. This function has to be called before any other
 156  * FORB function.
 157  *
 158  * Any command line arguments used by FORB are removed from the array
 159  * and @a argc and @a argv are updated accordingly.
 160  *
 161  * @param argc a pointer to the number of command line arguments.
 162  * @param argv a pointer to the array of command line arguments.
 163  * @param orb_id Name of the FORB used for debugging purposes.
 164  *
 165  * @return FORB object reference of NULL in case of error.
 166  */
 167 forb_orb forb_init(int *argc, char **argv[], const char *orb_id);
 168
 169 /**
 170  * Deallocates all resources consumed by FORB.
 171  *
 172  * @note Called automatically on application exit.
 173  *
 174  * @param orb FORB object reference to destroy.
 175  */
 176 void forb_destroy(forb_orb orb);
 177
 178 void
 179 forb_object_release(forb_object obj);
 180
 181 forb_object
 182 forb_object_duplicate(const forb_object obj);
 183
 184 void *
 185 forb_instance_data(const forb_object obj);
 186
 187 int
 188 forb_register_reference(forb_object object, const char *name);
 189
 190 int
 191 forb_unregister_reference(forb_orb orb, const char *name);
 192
 193 forb_object
 194 forb_resolve_reference(const forb_orb orb, const char *name);
 195
 196 forb_object
 197 forb_string_to_object(const forb_orb orb, const char *string);
 198
 199 char *
 200 forb_object_to_string(const forb_object obj);
 201
 202 forb_orb
 203 forb_get_orb_of(const forb_object obj);
 204
 205 const char *
 206 forb_strerror(CORBA_Environment *env);
 207
 208 #endif