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 #ifdef __cplusplus
 150 extern "C" {
 151 #endif
 152
 153 /* Incomplete types - declared in forb-internal.h */
 154 struct forb_interface;
 155 typedef struct forb_interface forb_interface_t;
 156
 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;
 164
 165 } forb_init_attr_t;
 166
 167 /**
 168  * Initializes FORB. This function has to be called before any other
 169  * FORB function.
 170  *
 171  * Any command line arguments used by FORB are removed from the array
 172  * and @a argc and @a argv are updated accordingly.
 173  *
 174  * @param argc a pointer to the number of command line arguments.
 175  * @param argv a pointer to the array of command line arguments.
 176  * @param attr attributes that control FORB initialization.
 177  *
 178  * @return FORB object reference of NULL in case of error.
 179  */
 180 forb_orb forb_init(int *argc, char **argv[], const forb_init_attr_t *attr);
 181
 182 /**
 183  * Deallocates all resources consumed by FORB.
 184  *
 185  * @note Called automatically on application exit.
 186  *
 187  * @param orb FORB object reference to destroy.
 188  */
 189 void forb_destroy(forb_orb orb);
 190
 191 void
 192 forb_object_release(forb_object obj);
 193
 194 forb_object
 195 forb_object_duplicate(const forb_object obj);
 196
 197 void *
 198 forb_instance_data(const forb_object obj);
 199
 200 int
 201 forb_register_reference(forb_object object, const char *name);
 202
 203 int
 204 forb_unregister_reference(forb_orb orb, const char *name);
 205
 206 forb_object
 207 forb_resolve_reference(const forb_orb orb, const char *name);
 208
 209 forb_object
 210 forb_string_to_object(const forb_orb orb, const char *string);
 211
 212 char *
 213 forb_object_to_string(const forb_object obj);
 214
 215 bool forb_object_is_stale(forb_object object);
 216
 217 forb_orb
 218 forb_get_orb_of(const forb_object obj);
 219
 220 void
 221 forb_get_server_id(const forb_object obj, forb_server_id *dest);
 222
 223 void
 224 forb_get_req_source(const forb_object obj, forb_server_id *req_source);
 225
 226 const char *
 227 forb_strerror(CORBA_Environment *env);
 228
 229 #ifdef __cplusplus
 230 } /* extern "C"*/
 231 #endif
 232
 233 #endif