]> rtime.felk.cvut.cz Git - frescor/forb.git/blob - src/proto.h
Fix error reporting in protocols
[frescor/forb.git] / src / proto.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   proto.h
49  * @author Michal Sojka <sojkam1@fel.cvut.cz>
50  * @date   Thu Aug 28 10:36:23 2008
51  * 
52  * @brief  FORB transport protocol declarations
53  * 
54  * 
55  */
56
57 #ifndef FORB_PROTO_H
58 #define FORB_PROTO_H
59
60 #include "forb-internal.h"
61 #include "syncobj.h"
62 #include "request.h"
63 #include <ul_logbase.h>
64 #include "port.h"
65 #include "peer.h"
66
67 typedef struct forb_proto forb_proto_t;
68
69 /**
70  * Description of a FORB transport protocol.
71  */
72 struct forb_proto {
73         /** Number of seconds between sending of HELLO messages for discovery process */
74         unsigned hello_interval;
75
76         /** 
77          * Called to free any protocol resources associated with the port.
78          * 
79          * @param port The port to be destroyed.
80          * 
81          * @return Zero on success, negatove error code on error.
82          */
83         int (*port_destroy)(forb_port_t *port);
84
85         /** 
86          * Sends data to a peer.
87          *
88          * If the protocol is connection-oriented, the connection data
89          * can be stored at @c port->proto_priv and used by later
90          * requests.
91          * 
92          * @param peer Peer to send data
93          * @param buf Data to send
94          * @param len Length of data to send
95          * 
96          * @return Length of the sent data (should be equal to @a len on
97          * success) or negative error code on error.
98          */
99         ssize_t (*send)(forb_peer_t *peer, const void *buf, size_t len);
100
101         /** 
102          * Called to free any protocol resources associated with the
103          * peer.
104          * 
105          * @param peer Peer to destroy
106          * 
107          * @note The memory allocated by @a deserialize_addr (if any)
108          * is deallocated by FORB and should not be deallocated here.
109          */
110         void (*peer_destroy)(forb_peer_t *peer);
111         /** 
112          * Receives data through a port
113          * 
114          * @param port Port to use 
115          * @param buf Where to store the received data
116          * @param len Length the buffer @a buf
117          * 
118          * @return Length of the received data or negative error code
119          * on error.
120          */
121         ssize_t (*recv)(forb_port_t *port, void *buf, size_t len);
122
123         /** 
124          * Broadcasts/multicasts a message. All FORBs connected the
125          * the network/bus represented by the @a port should receive
126          * it.
127          *
128          * This function is used by peer discovery protocol.
129          * 
130          * @param port Port to use 
131          * @param buf Data to broadcast 
132          * @param len Length of the @a data
133          * 
134          * @return Zero or positive number on success, negative error
135          * code on error.
136          */
137         ssize_t (*broadcast)(forb_port_t *port, const void *buf, size_t len);
138
139         /** Serializes the protocol specific address */
140         CORBA_boolean (*serialize_addr)(FORB_CDR_Codec *codec, const void *addr);
141
142         /** Deserializes the protocol specific address. The memory for
143          * storing the address should be allocated by forb_malloc(). */
144         CORBA_boolean (*deserialize_addr)(FORB_CDR_Codec *codec, void **addr);
145
146         /** Converts protocol specific address to string */
147         size_t (*addr2str)(char *dest, size_t maxlen, const void *addr);
148
149         /**
150          * Callback caled when the port is registered to FORB just
151          * before reception and discovery threads are started.
152          */
153         void (*register_cb)(forb_port_t *port);
154 };
155
156 ssize_t forb_proto_send(forb_peer_t *peer, FORB_CDR_Codec *codec);
157
158 forb_peer_t *
159 forb_get_next_hop(forb_t *forb, forb_server_id *server, fosa_abs_time_t *timeout);
160
161
162 #endif