]> rtime.felk.cvut.cz Git - orte.git/blob - orte/include/orte/typedefs_api.h
updated email address - petr@smoliku.cz
[orte.git] / orte / include / orte / typedefs_api.h
1 /*
2  *  $Id: typedefs_api.h,v 0.0.0.1       2003/08/21 
3  *
4  *  -------------------------------------------------------------------  
5  *                                ORTE                                 
6  *                      Open Real-Time Ethernet                       
7  *                                                                    
8  *                      Copyright (C) 2001-2006                       
9  *  Department of Control Engineering FEE CTU Prague, Czech Republic  
10  *                      http://dce.felk.cvut.cz                       
11  *                      http://www.ocera.org                          
12  *                                                                    
13  *  Author:              Petr Smolik    petr@smoliku.cz             
14  *  Advisor:             Pavel Pisa                                   
15  *  Project Responsible: Zdenek Hanzalek                              
16  *  --------------------------------------------------------------------
17  *
18  *  This program is free software; you can redistribute it and/or modify
19  *  it under the terms of the GNU General Public License as published by
20  *  the Free Software Foundation; either version 2 of the License, or
21  *  (at your option) any later version.
22  *  
23  *  This program is distributed in the hope that it will be useful,
24  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
25  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
26  *  GNU General Public License for more details.
27  *  
28  */
29
30 #ifndef _TYPEDEFS_API_H
31 #define _TYPEDEFS_API_H
32
33 #ifdef __cplusplus
34 extern "C" {
35 #endif
36
37 typedef struct ORTEDomain ORTEDomain;             //forward declaration
38 typedef struct CSTWriter ORTEPublication;         //forward declaration
39 typedef struct CSTReader ORTESubscription;        //forward declaration
40
41 /**
42  * enum SubscriptionMode - mode of subscription
43  * @PULLED: polled
44  * @IMMEDIATE: using callback function 
45  *
46  * Specifies whether user application will poll for data or whether a callback function will be called by ORTE middleware when new data will be available.
47  */
48 typedef enum SubscriptionMode {
49         PULLED           = 0x01,
50         IMMEDIATE        = 0x02
51       } SubscriptionMode;
52
53 /**
54  * enum SubscriptionType - type of subcsription
55  * @BEST_EFFORTS: best effort subscription
56  * @STRICT_RELIABLE: strict reliable subscription.
57  *
58  * Specifies which mode will be used for this subscription.
59  */
60 typedef enum SubscriptionType {
61         BEST_EFFORTS     = 0x01,
62         STRICT_RELIABLE  = 0x02
63       } SubscriptionType;
64
65 /**
66  * enum ORTERecvStatus - status of a subscription
67  * @NEW_DATA: new data has arrived
68  * @DEADLINE: deadline has occurred 
69  *
70  * Specifies which event has occurred in the subscription object.
71  */
72 typedef enum ORTERecvStatus {
73         NEW_DATA         = 0x01, 
74         DEADLINE         = 0x02
75       } ORTERecvStatus;
76
77 /**
78  * enum ORTESendStatus - status of a publication
79  * @NEED_DATA: need new data (set when callback function specified for publciation is beeing called)
80  * @CQL: transmit queue has been filled up to critical level.
81  *
82  * Specifies which event has occurred in the publication object. Critical level of transmit queue is specified as one of publication properties (ORTEPublProp.criticalQueueLevel).
83  */
84 typedef enum ORTESendStatus {
85         NEED_DATA        = 0x01,
86         CQL              = 0x02
87       } ORTESendStatus;
88
89 /**
90  * struct ORTEIFProp - interface flags 
91  * @ifFlags: flags
92  * @ipAddress: IP address
93  *
94  * Flags for network interface.
95  */
96 typedef struct ORTEIFProp {
97   int32_t        ifFlags;
98   IPAddress      ipAddress;
99 } ORTEIFProp;
100
101 /**
102  * struct ORTEMulticastProp - properties for ORTE multicast (not supported yet)
103  * @enabled: ORTE_TRUE if multicast enabled otherwise ORTE_FALSE
104  * @ttl: time-to-live (TTL) for sent datagrams
105  * @loopBackEnabled: ORTE_TRUE if data should be received by sender itself otherwise ORTE_FALSE
106  * @ipAddress: desired multicast IP address 
107  *
108  * Properties for ORTE multicast subsystem which is not fully supported yet. Multicast IP address is assigned by the ORTE middleware itself.
109  */
110 typedef struct ORTEMulticastProp {
111   Boolean        enabled;
112   unsigned char  ttl;
113   Boolean        loopBackEnabled;
114   IPAddress      ipAddress;
115 } ORTEMulticastProp;
116
117
118 /**
119  * struct ORTETypeGetMaxSizeParam - parameters for function ORTETypeGetMaxSize
120  * @host_endian: 
121  * @data_endian: 
122  * @data: 
123  * @max_size: 
124  * @recv_size: 
125  * @csize:
126  *
127  * It used to determine maximal size of intermal buffer for incomming data
128  */
129 typedef struct ORTEGetMaxSizeParam {
130   CDR_Endianness host_endian;
131   CDR_Endianness data_endian;
132   CORBA_octet *data;
133   unsigned int max_size;
134   int recv_size;
135   int csize;
136 } ORTEGetMaxSizeParam;
137
138 typedef void (*ORTETypeSerialize)(CDR_Codec *cdrCodec, void *instance);
139
140 typedef void (*ORTETypeDeserialize)(CDR_Codec *cdrCodec, void *instance);
141
142 typedef int (*ORTETypeGetMaxSize)(ORTEGetMaxSizeParam *gms, int num);
143
144 /**
145  * struct ORTETypeRegister - registered data type
146  * @typeName: name of data type 
147  * @serialize: pointer to serialization function
148  * @deserialize: pointer to deserialization function
149  * @getMaxSize: pointer to function given maximal data length
150  * @maxSize: maximal size of ser./deser. data
151  *
152  * Contains description of registered data type. See @ORTETypeRegisterAdd function for details.
153  */
154 typedef struct ORTETypeRegister {
155   const char             *typeName;
156   ORTETypeSerialize      serialize;
157   ORTETypeDeserialize    deserialize;
158   ORTETypeGetMaxSize     getMaxSize;
159   unsigned int           maxSize;
160 } ORTETypeRegister;
161
162 /**
163  * struct ORTEDomainBaseProp - base properties of a domain
164  * @registrationMgrRetries: a manager which want to start communication have to register to other manager. This parametr
165  * is used for specify maximal repetition retries of registration process when it fail.
166  * @registrationMgrPeriod: an application which want to start communication have to register to a manager. This parametr
167  * is used for specify maximal repetition retries of registration process when it fail.
168  * @registrationAppRetries: same like registrationMgrRetries parameter, but is used for an application
169  * @registrationAppPeriod: repetition time for registration process
170  * @expirationTime: specifies how long is this application taken as alive in other applications/managers (default 180s)
171  * @refreshPeriod: how often an application refresh itself to its manager or manager to other managers (default 60s)
172  * @purgeTime: how often the local database should be cleaned from invalid (expired) objects (default 60s)
173  * @repeatAnnounceTime: This is the period with which the CSTWriter will announce its existence and/or the availability of new CSChanges to the CSTReader. This period determines how quickly the protocol recovers when an announcement of data is lost.
174  * @repeatActiveQueryTime: ???
175  * @delayResponceTimeACKMin: minimum time the CSTWriter waits before responding to an incoming message.
176  * @delayResponceTimeACKMax: maximum time the CSTWriter waits before responding to an incoming message.
177  * @HBMaxRetries: how many times a HB message is retransmitted if no response has been received until timeout
178  * @ACKMaxRetries: how many times an ACK message is retransmitted if no response has been received until timeout
179  * @maxBlockTime: timeout for send functions if sending queue is full (default 30s)
180  */
181 typedef struct ORTEDomainBaseProp {
182   unsigned int           registrationMgrRetries;
183   NtpTime                registrationMgrPeriod;
184   unsigned int           registrationAppRetries;
185   NtpTime                registrationAppPeriod;
186   NtpTime                expirationTime;
187   NtpTime                refreshPeriod;
188   NtpTime                purgeTime;
189   NtpTime                repeatAnnounceTime;
190   NtpTime                repeatActiveQueryTime;
191   NtpTime                delayResponceTimeACKMin;
192   NtpTime                delayResponceTimeACKMax;
193   unsigned int           HBMaxRetries;
194   unsigned int           ACKMaxRetries;
195   NtpTime                maxBlockTime;
196 } ORTEDomainBaseProp;
197
198 /**
199  * struct ORTEDomainWireProp - wire properties of a message
200  * @metaBytesPerPacket: maximum number of bytes in single frame (default 1500B)
201  * @metaBytesPerFastPacket: maximum number of bytes in single frame if transmitting queue has reached @criticalQueueLevel level (see @ORTEPublProp struct)
202  * @metabitsPerACKBitmap: not supported yet (default 32)
203  * @userMaxSerDeserSize: maximum number of user data in frame (default 0x3000B) 
204  */
205 typedef struct ORTEDomainWireProp {
206   unsigned int           metaBytesPerPacket;
207   unsigned int           metaBytesPerFastPacket;
208   unsigned int           metabitsPerACKBitmap;
209   unsigned int           userBytesPerPacket;
210 } ORTEDomainWireProp;
211
212 /**
213  * struct ORTEPublProp - properties of a publication
214  * @topic: the name of the information in the Network that is published or subscribed to
215  * @typeName: the name of the type of this data 
216  * @typeChecksum: a checksum that identifies the CDR-representation of the data
217  * @expectsAck: indicates wherther publication expects to receive ACKs to its messages
218  * @persistence: indicates how long the issue is valid
219  * @reliabilityOffered: reliability policy as offered by the publication
220  * @sendQueueSize: size of transmitting queue
221  * @strength: precedence of the issue sent by the publication
222  * @criticalQueueLevel: treshold for transmitting queue content length indicating the queue can became full immediately 
223  * @HBNornalRate: how often send HBs to subscription objects
224  * @HBCQLRate: how often send HBs to subscription objects if transmittiong queue has reached @criticalQueueLevel
225  * @HBMaxRetries: how many times retransmit HBs if no replay from target object has not been received
226  * @maxBlockTime: unsupported
227  */
228 typedef struct ORTEPublProp {
229   PathName               topic;
230   TypeName               typeName; 
231   TypeChecksum           typeChecksum;
232   Boolean                expectsAck;
233   NtpTime                persistence;
234   uint32_t               reliabilityOffered;
235   uint32_t               sendQueueSize;
236   int32_t                strength;
237   uint32_t               criticalQueueLevel;
238   NtpTime                HBNornalRate;
239   NtpTime                HBCQLRate;
240   unsigned int           HBMaxRetries;
241   NtpTime                maxBlockTime;
242 } ORTEPublProp;
243
244 /**
245  * struct ORTESubsProp - properties of a subscription
246  * @topic: the name of the information in the Network that is published or subscribed to
247  * @typeName: the name of the type of this data
248  * @typeChecksum: a checksum that identifies the CDR-representation of the data
249  * @minimumSeparation: minimum time between two consecutive issues received by the subscription
250  * @recvQueueSize: size of receiving queue
251  * @reliabilityRequested: reliability policy requested by the subscription
252  * @deadline: deadline for subscription, a callback function  (see @ORTESubscriptionCreate) will be called if no data were received within this period of time
253  * @mode: mode of subscription (strict reliable/best effort), see @SubscriptionType enum for values
254  * @multicast: registered multicast IP address(read only)
255  */
256 typedef struct ORTESubsProp {
257   PathName               topic;
258   TypeName               typeName;
259   TypeChecksum           typeChecksum;
260   NtpTime                minimumSeparation;
261   uint32_t               recvQueueSize;
262   uint32_t               reliabilityRequested;
263   //additional parameters
264   NtpTime                deadline;
265   uint32_t               mode;
266   IPAddress              multicast;
267 }  ORTESubsProp;
268
269 /**
270  * struct ORTEAppInfo - 
271  * @hostId: hostId of application
272  * @appId: appId of application
273  * @unicastIPAddressList: unicast IP addresses of the host on which the application runs (there can be multiple addresses on a multi-NIC host)
274  * @unicastIPAddressCount: number of IPaddresses in @unicastIPAddressList
275  * @metatrafficMulticastIPAddressList: for the purposes of meta-traffic, an application can also accept Messages on this set of multicast addresses
276  * @metatrafficMulticastIPAddressCount: number of IPaddresses in @metatrafficMulticastIPAddressList
277  * @metatrafficUnicastPort: UDP port used for metatraffic communication
278  * @userdataUnicastPort: UDP port used for metatraffic communication
279  * @vendorId: identifies the vendor of the middleware implementing the RTPS protocol and allows this vendor to add specific extensions to the protocol
280  * @protocolVersion: describes the protocol version
281  */
282 typedef struct ORTEAppInfo {
283   HostId                 hostId;
284   AppId                  appId;
285   IPAddress              *unicastIPAddressList;
286   unsigned char          unicastIPAddressCount;
287   IPAddress              *metatrafficMulticastIPAddressList;
288   unsigned char          metatrafficMulticastIPAddressCount;
289   Port                   metatrafficUnicastPort;
290   Port                   userdataUnicastPort;
291   VendorId               vendorId;
292   ProtocolVersion        protocolVersion;
293 } ORTEAppInfo;
294
295 /**
296  * struct ORTEPubInfo -information about publication
297  * @topic: the name of the information in the Network that is published or subscribed to
298  * @type: the name of the type of this data
299  * @objectId: object providing this publication
300  */
301 typedef struct ORTEPubInfo {
302   const char            *topic;
303   const char            *type;
304   ObjectId              objectId;
305 } ORTEPubInfo;
306
307 /**
308  * struct ORTEPubInfo - information about subscription
309  * @topic: the name of the information in the Network that is published or subscribed to
310  * @type: the name of the type of this data
311  * @objectId: object with this subscription 
312  */
313 typedef struct ORTESubInfo {
314   const char            *topic;
315   const char            *type;
316   ObjectId              objectId;
317 } ORTESubInfo;
318
319 /**
320  * struct ORTEPublStatus - status of a publication
321  * @strict: count of unreliable subscription (strict) connected on responsible subscription
322  * @bestEffort: count of reliable subscription (best effort) connected on responsible subscription
323  * @issues: number of messages in transmitting queue
324  */
325 typedef struct ORTEPublStatus {
326   unsigned int           strict;
327   unsigned int           bestEffort;
328   unsigned int           issues;
329 } ORTEPublStatus;
330
331 /**
332  * struct ORTESubsStatus - status of a subscription
333  * @strict: count of unreliable publications (strict) connected to responsible subscription
334  * @bestEffort: count of reliable publications (best effort) connected to responsible subscription
335  * @issues: number of messages in receiving queue
336  */
337 typedef struct ORTESubsStatus {
338   unsigned int           strict;
339   unsigned int           bestEffort;
340   unsigned int           issues;
341 } ORTESubsStatus;
342
343 /**
344  * struct ORTERecvInfo - description of received data
345  * @status: status of this event
346  * @topic: the name of the information
347  * @type: the name of the type of this data
348  * @senderGUID: GUID of object who sent this information
349  * @localTimeReceived: local timestamp when data were received
350  * @remoteTimePublished: remote timestam when data were published
351  * @sn: sequencial number of data 
352  * @data_endian: endianness of received data
353  */
354 typedef struct ORTERecvInfo {
355   ORTERecvStatus        status;
356   const char            *topic;
357   const char            *type;
358   GUID_RTPS             senderGUID;
359   NtpTime               localTimeReceived;
360   NtpTime               remoteTimePublished;
361   SequenceNumber        sn;
362   CDR_Endianness        data_endian;
363 } ORTERecvInfo;
364
365 /**
366  * struct ORTESendInfo - description of sending data
367  * @status: status of this event
368  * @topic: the name of the information
369  * @type: the name of the type of this information
370  * @senderGUID: GUID of object who sent this information
371  * @sn: sequencial number of information 
372  */
373 typedef struct ORTESendInfo {
374   ORTESendStatus        status;
375   const char            *topic;
376   const char            *type;
377   GUID_RTPS             senderGUID;
378   SequenceNumber        sn;
379 } ORTESendInfo;
380
381 //CallBackRoutines
382
383 typedef void 
384 (*ORTERecvCallBack)(const ORTERecvInfo *info,void *instance, void *recvCallBackParam);
385 typedef void 
386 (*ORTESendCallBack)(const ORTESendInfo *info,void *instance, void *sendCallBackParam);
387 typedef ORTESubscription*
388 (*ORTESubscriptionPatternCallBack)(const char *topic, const char *type, void *Param);
389
390 /**
391  * struct ORTEPublicationSendParam - description of sending data
392  * @instance: pointer to new data instance
393  * @data_endian: endianing of sending data (BIG | LITTLE)
394  */
395 typedef struct ORTEPublicationSendParam {
396   void                  *instance;
397   int                   data_endian;
398 } ORTEPublicationSendParam;
399
400 //Pattern
401 typedef Boolean
402 (*ORTEPatternCheck)(const char *string);
403 typedef Boolean
404 (*ORTEPatternMatch)(const char *topic,const char *pattern,void *param);
405 extern Boolean
406 ORTEPatternCheckDefault(const char *topic);
407 extern Boolean
408 ORTEPatternMatchDefault(const char *topic,const char *pattern,void *param);
409 extern void
410 ORTEPatternRegister(ORTEDomain *d,ORTEPatternCheck check,
411      ORTEPatternMatch match,void *param);
412
413
414 //Manager
415 typedef void
416 (*ORTEOnRegFail)(void *param);
417 typedef Boolean 
418 (*ORTEOnMgrNew)(const struct ORTEAppInfo *appInfo, void *param);
419 typedef void 
420 (*ORTEOnMgrDelete)(const struct ORTEAppInfo *appInfo, void *param);
421 //Application
422 typedef Boolean 
423 (*ORTEOnAppRemoteNew)(const struct ORTEAppInfo *appInfo, void *param);
424 typedef void (*ORTEOnAppDelete)
425 (const struct ORTEAppInfo *appInfo, void *param);
426 //Publication
427 typedef Boolean 
428 (*ORTEOnPubRemote)(const struct ORTEAppInfo *appInfo,
429                    const struct ORTEPubInfo *pubInfo, void *param);
430 typedef void 
431 (*ORTEOnPubDelete)(const struct ORTEAppInfo *appInfo,
432                    const struct ORTEPubInfo *pubInfo, void *param);
433 //Subscription
434 typedef Boolean 
435 (*ORTEOnSubRemote)(const struct ORTEAppInfo *appInfo,
436                    const struct ORTESubInfo *subInfo, void *param);
437 typedef void 
438 (*ORTEOnSubDelete)(const struct ORTEAppInfo *appInfo,
439                    const struct ORTESubInfo *subInfo, void *param);
440
441 /**
442  * struct ORTEDomainAppEvents - Domain event handlers of an application
443  * @onRegFail: registration protocol has been failed
444  * @onRegFailParam: user parameters for @onRegFail handler
445  * @onMgrNew: new manager has been created
446  * @onMgrNewParam: user parameters for @onMgrNew handler
447  * @onMgrDelete: manager has been deleted
448  * @onMgrDeleteParam: user parameters for @onMgrDelete handler
449  * @onAppRemoteNew: new remote application has been registered
450  * @onAppRemoteNewParam: user parameters for @onAppRemoteNew handler
451  * @onAppDelete: an application has been removed
452  * @onAppDeleteParam: user parameters for @onAppDelete handler
453  * @onPubRemoteNew: new remote publication has been registered
454  * @onPubRemoteNewParam: user parameters for @onPubRemoteNew handler
455  * @onPubRemoteChanged: a remote publication's parameters has been changed
456  * @onPubRemoteChangedParam: user parameters for @onPubRemoteChanged handler
457  * @onPubDelete: a publication has been deleted
458  * @onPubDeleteParam: user parameters for @onPubDelete handler
459  * @onSubRemoteNew: a new remote subscription has been registered
460  * @onSubRemoteNewParam: user parameters for @onSubRemoteNew handler
461  * @onSubRemoteChanged: a remote subscription's parameters has been changed
462  * @onSubRemoteChangedParam: user parameters for @onSubRemoteChanged handler
463  * @onSubDelete: a publication has been deleted
464  * @onSubDeleteParam: user parameters for @onSubDelete handler
465  *
466  * Prototypes of events handler fucntions can be found in file typedefs_api.h.
467  */
468 typedef struct ORTEDomainAppEvents {
469   ORTEOnRegFail          onRegFail;
470   void                   *onRegFailParam;
471   ORTEOnMgrNew           onMgrNew;
472   void                   *onMgrNewParam;
473   ORTEOnMgrDelete        onMgrDelete;
474   void                   *onMgrDeleteParam;
475   ORTEOnAppRemoteNew     onAppRemoteNew;
476   void                   *onAppRemoteNewParam;
477   ORTEOnAppDelete        onAppDelete;
478   void                   *onAppDeleteParam;
479   ORTEOnPubRemote        onPubRemoteNew;
480   void                   *onPubRemoteNewParam;
481   ORTEOnPubRemote        onPubRemoteChanged;
482   void                   *onPubRemoteChangedParam;
483   ORTEOnPubDelete        onPubDelete;
484   void                   *onPubDeleteParam;
485   ORTEOnSubRemote        onSubRemoteNew;
486   void                   *onSubRemoteNewParam;
487   ORTEOnSubRemote        onSubRemoteChanged;
488   void                   *onSubRemoteChangedParam;
489   ORTEOnSubDelete        onSubDelete;
490   void                   *onSubDeleteParam;
491 } ORTEDomainAppEvents;
492
493 /**
494  * struct ORTETaskProp - ORTE task properties, not supported 
495  * @realTimeEnabled: not supported
496  * @smtStackSize: not supported
497  * @smtPriority: not supported
498  * @rmtStackSize: not supported
499  * @rmtPriority: not supported 
500  */
501 typedef struct ORTETasksProp {
502   Boolean                realTimeEnabled;
503   int                    smtStackSize;
504   int                    smtPriority;
505   int                    rmtStackSize;
506   int                    rmtPriority;
507 } ORTETasksProp; 
508
509 /**
510  * struct ORTEDomainApp - domain properties 
511  * @tasksProp: task properties
512  * @IFProp: properties of network interfaces
513  * @IFCount: number of network interfaces              
514  * @baseProp: base properties (see @ORTEDomainBaseProp for details)
515  * @wireProp: wire properties (see @ORTEDomainWireProp for details)
516  * @multicast: multicast properties (see @ORTEMulticastProp for details)               
517  * @publPropDefault: default properties of publiciations (see @ORTEPublProp for details)      
518  * @subsPropDefault: default properties of subscriptions (see @ORTESubsProp for details)
519  * @mgrs: list of known managers               
520  * @keys: access keys for managers             
521  * @appLocalManager: IP address of local manager (default localhost)      
522  * @listen: IP address to listen on
523  * @version: string product version
524  * @recvBuffSize: receiving queue length
525  * @sendBuffSize: transmitting queue length
526  */
527 typedef struct ORTEDomainProp {
528   ORTETasksProp          tasksProp;
529   ORTEIFProp             IFProp[MAX_INTERFACES];  //interface properties
530   unsigned char          IFCount;                 //count of interfaces
531   ORTEDomainBaseProp     baseProp;
532   ORTEDomainWireProp     wireProp;
533   ORTEMulticastProp      multicast;               //multicast properies
534   ORTEPublProp           publPropDefault;         //default properties for a Publ/Sub
535   ORTESubsProp           subsPropDefault;
536   char                   *mgrs;                   //managers
537   char                   *keys;                   //keys
538   IPAddress              appLocalManager;         //applications
539   IPAddress              listen;
540   char                   version[60];             //string product version
541   int                    recvBuffSize;
542   int                    sendBuffSize;      
543 } ORTEDomainProp;
544
545 #ifdef __cplusplus
546 } /* extern "C"*/
547 #endif
548
549 #endif  /* _TYPEDEFS_API_H */
550