]> rtime.felk.cvut.cz Git - orte.git/blob - orte/include/orte/typedefs_api.h
a23292481839eba59fdcb596baf95b64a42a7ca1
[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.smolik@wo.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 typedef void (*ORTETypeProcessEndianness)(CDR_Codec *cdrCodec, void *param);
145
146 /**
147  * struct ORTETypeRegister - registered data type
148  * @typeName: name of data type 
149  * @serialize: pointer to serialization function
150  * @deserialize: pointer to deserialization function
151  * @getMaxSize: pointer to function given maximal data length
152  * @maxSize: maximal size of ser./deser. data
153  * @processEndianness: allows application to adjust some preferences according to byte order
154  * @processParam: pointer to user structure containing parameters for processEndianness
155  *
156  * Contains description of registered data type. See @ORTETypeRegisterAdd function for details.
157  */
158 typedef struct ORTETypeRegister {
159   const char                  *typeName;
160   ORTETypeSerialize           serialize;
161   ORTETypeDeserialize         deserialize;
162   ORTETypeGetMaxSize          getMaxSize;
163   unsigned int                maxSize;
164   ORTETypeProcessEndianness   processEndianness;
165   void                        *processParam;
166 } ORTETypeRegister;
167
168 /**
169  * struct ORTEDomainBaseProp - base properties of a domain
170  * @registrationMgrRetries: a manager which want to start communication have to register to other manager. This parametr
171  * is used for specify maximal repetition retries of registration process when it fail.
172  * @registrationMgrPeriod: an application which want to start communication have to register to a manager. This parametr
173  * is used for specify maximal repetition retries of registration process when it fail.
174  * @registrationAppRetries: same like registrationMgrRetries parameter, but is used for an application
175  * @registrationAppPeriod: repetition time for registration process
176  * @expirationTime: specifies how long is this application taken as alive in other applications/managers (default 180s)
177  * @refreshPeriod: how often an application refresh itself to its manager or manager to other managers (default 60s)
178  * @purgeTime: how often the local database should be cleaned from invalid (expired) objects (default 60s)
179  * @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.
180  * @repeatActiveQueryTime: ???
181  * @delayResponceTimeACKMin: minimum time the CSTWriter waits before responding to an incoming message.
182  * @delayResponceTimeACKMax: maximum time the CSTWriter waits before responding to an incoming message.
183  * @HBMaxRetries: how many times a HB message is retransmitted if no response has been received until timeout
184  * @ACKMaxRetries: how many times an ACK message is retransmitted if no response has been received until timeout
185  * @maxBlockTime: timeout for send functions if sending queue is full (default 30s)
186  */
187 typedef struct ORTEDomainBaseProp {
188   unsigned int           registrationMgrRetries;
189   NtpTime                registrationMgrPeriod;
190   unsigned int           registrationAppRetries;
191   NtpTime                registrationAppPeriod;
192   NtpTime                expirationTime;
193   NtpTime                refreshPeriod;
194   NtpTime                purgeTime;
195   NtpTime                repeatAnnounceTime;
196   NtpTime                repeatActiveQueryTime;
197   NtpTime                delayResponceTimeACKMin;
198   NtpTime                delayResponceTimeACKMax;
199   unsigned int           HBMaxRetries;
200   unsigned int           ACKMaxRetries;
201   NtpTime                maxBlockTime;
202 } ORTEDomainBaseProp;
203
204 /**
205  * struct ORTEDomainWireProp - wire properties of a message
206  * @metaBytesPerPacket: maximum number of bytes in single frame (default 1500B)
207  * @metaBytesPerFastPacket: maximum number of bytes in single frame if transmitting queue has reached @criticalQueueLevel level (see @ORTEPublProp struct)
208  * @metabitsPerACKBitmap: not supported yet (default 32)
209  * @userMaxSerDeserSize: maximum number of user data in frame (default 0x3000B) 
210  */
211 typedef struct ORTEDomainWireProp {
212   unsigned int           metaBytesPerPacket;
213   unsigned int           metaBytesPerFastPacket;
214   unsigned int           metabitsPerACKBitmap;
215   unsigned int           userBytesPerPacket;
216 } ORTEDomainWireProp;
217
218 /**
219  * struct ORTEPublProp - properties of a publication
220  * @topic: the name of the information in the Network that is published or subscribed to
221  * @typeName: the name of the type of this data 
222  * @typeChecksum: a checksum that identifies the CDR-representation of the data
223  * @expectsAck: indicates wherther publication expects to receive ACKs to its messages
224  * @persistence: indicates how long the issue is valid
225  * @reliabilityOffered: reliability policy as offered by the publication
226  * @sendQueueSize: size of transmitting queue
227  * @strength: precedence of the issue sent by the publication
228  * @criticalQueueLevel: treshold for transmitting queue content length indicating the queue can became full immediately 
229  * @HBNornalRate: how often send HBs to subscription objects
230  * @HBCQLRate: how often send HBs to subscription objects if transmittiong queue has reached @criticalQueueLevel
231  * @HBMaxRetries: how many times retransmit HBs if no replay from target object has not been received
232  * @maxBlockTime: unsupported
233  */
234 typedef struct ORTEPublProp {
235   PathName               topic;
236   TypeName               typeName; 
237   TypeChecksum           typeChecksum;
238   Boolean                expectsAck;
239   NtpTime                persistence;
240   uint32_t               reliabilityOffered;
241   uint32_t               sendQueueSize;
242   int32_t                strength;
243   uint32_t               criticalQueueLevel;
244   NtpTime                HBNornalRate;
245   NtpTime                HBCQLRate;
246   unsigned int           HBMaxRetries;
247   NtpTime                maxBlockTime;
248 } ORTEPublProp;
249
250 /**
251  * struct ORTESubsProp - properties of a subscription
252  * @topic: the name of the information in the Network that is published or subscribed to
253  * @typeName: the name of the type of this data
254  * @typeChecksum: a checksum that identifies the CDR-representation of the data
255  * @minimumSeparation: minimum time between two consecutive issues received by the subscription
256  * @recvQueueSize: size of receiving queue
257  * @reliabilityRequested: reliability policy requested by the subscription
258  * @deadline: deadline for subscription, a callback function  (see @ORTESubscriptionCreate) will be called if no data were received within this period of time
259  * @mode: mode of subscription (strict reliable/best effort), see @SubscriptionType enum for values
260  * @multicast: registered multicast IP address(read only)
261  */
262 typedef struct ORTESubsProp {
263   PathName               topic;
264   TypeName               typeName;
265   TypeChecksum           typeChecksum;
266   NtpTime                minimumSeparation;
267   uint32_t               recvQueueSize;
268   uint32_t               reliabilityRequested;
269   //additional parameters
270   NtpTime                deadline;
271   uint32_t               mode;
272   IPAddress              multicast;
273 }  ORTESubsProp;
274
275 /**
276  * struct ORTEAppInfo - 
277  * @hostId: hostId of application
278  * @appId: appId of application
279  * @unicastIPAddressList: unicast IP addresses of the host on which the application runs (there can be multiple addresses on a multi-NIC host)
280  * @unicastIPAddressCount: number of IPaddresses in @unicastIPAddressList
281  * @metatrafficMulticastIPAddressList: for the purposes of meta-traffic, an application can also accept Messages on this set of multicast addresses
282  * @metatrafficMulticastIPAddressCount: number of IPaddresses in @metatrafficMulticastIPAddressList
283  * @metatrafficUnicastPort: UDP port used for metatraffic communication
284  * @userdataUnicastPort: UDP port used for metatraffic communication
285  * @vendorId: identifies the vendor of the middleware implementing the RTPS protocol and allows this vendor to add specific extensions to the protocol
286  * @protocolVersion: describes the protocol version
287  */
288 typedef struct ORTEAppInfo {
289   HostId                 hostId;
290   AppId                  appId;
291   IPAddress              *unicastIPAddressList;
292   unsigned char          unicastIPAddressCount;
293   IPAddress              *metatrafficMulticastIPAddressList;
294   unsigned char          metatrafficMulticastIPAddressCount;
295   Port                   metatrafficUnicastPort;
296   Port                   userdataUnicastPort;
297   VendorId               vendorId;
298   ProtocolVersion        protocolVersion;
299 } ORTEAppInfo;
300
301 /**
302  * struct ORTEPubInfo -information about publication
303  * @topic: the name of the information in the Network that is published or subscribed to
304  * @type: the name of the type of this data
305  * @objectId: object providing this publication
306  */
307 typedef struct ORTEPubInfo {
308   const char            *topic;
309   const char            *type;
310   ObjectId              objectId;
311 } ORTEPubInfo;
312
313 /**
314  * struct ORTEPubInfo - information about subscription
315  * @topic: the name of the information in the Network that is published or subscribed to
316  * @type: the name of the type of this data
317  * @objectId: object with this subscription 
318  */
319 typedef struct ORTESubInfo {
320   const char            *topic;
321   const char            *type;
322   ObjectId              objectId;
323 } ORTESubInfo;
324
325 /**
326  * struct ORTEPublStatus - status of a publication
327  * @strict: count of unreliable subscription (strict) connected on responsible subscription
328  * @bestEffort: count of reliable subscription (best effort) connected on responsible subscription
329  * @issues: number of messages in transmitting queue
330  */
331 typedef struct ORTEPublStatus {
332   unsigned int           strict;
333   unsigned int           bestEffort;
334   unsigned int           issues;
335 } ORTEPublStatus;
336
337 /**
338  * struct ORTESubsStatus - status of a subscription
339  * @strict: count of unreliable publications (strict) connected to responsible subscription
340  * @bestEffort: count of reliable publications (best effort) connected to responsible subscription
341  * @issues: number of messages in receiving queue
342  */
343 typedef struct ORTESubsStatus {
344   unsigned int           strict;
345   unsigned int           bestEffort;
346   unsigned int           issues;
347 } ORTESubsStatus;
348
349 /**
350  * struct ORTERecvInfo - description of received data
351  * @status: status of this event
352  * @topic: the name of the information
353  * @type: the name of the type of this data
354  * @senderGUID: GUID of object who sent this information
355  * @localTimeReceived: local timestamp when data were received
356  * @remoteTimePublished: remote timestam when data were published
357  * @sn: sequencial number of data 
358  */
359 typedef struct ORTERecvInfo {
360   ORTERecvStatus        status;
361   const char            *topic;
362   const char            *type;
363   GUID_RTPS             senderGUID;
364   NtpTime               localTimeReceived;
365   NtpTime               remoteTimePublished;
366   SequenceNumber        sn;
367 } ORTERecvInfo;
368
369 /**
370  * struct ORTESendInfo - description of sending data
371  * @status: status of this event
372  * @topic: the name of the information
373  * @type: the name of the type of this information
374  * @senderGUID: GUID of object who sent this information
375  * @sn: sequencial number of information 
376  */
377 typedef struct ORTESendInfo {
378   ORTESendStatus        status;
379   const char            *topic;
380   const char            *type;
381   GUID_RTPS             senderGUID;
382   SequenceNumber        sn;
383 } ORTESendInfo;
384
385 //CallBackRoutines
386
387 typedef void 
388 (*ORTERecvCallBack)(const ORTERecvInfo *info,void *instance, void *recvCallBackParam);
389 typedef void 
390 (*ORTESendCallBack)(const ORTESendInfo *info,void *instance, void *sendCallBackParam);
391 typedef ORTESubscription*
392 (*ORTESubscriptionPatternCallBack)(const char *topic, const char *type, void *Param);
393
394 /**
395  * struct ORTEPublicationSendParam - description of sending data
396  * @instance: pointer to new data instance
397  * @data_endian: endianing of sending data (BIG | LITTLE)
398  */
399 typedef struct ORTEPublicationSendParam {
400   void                  *instance;
401   int                   data_endian;
402 } ORTEPublicationSendParam;
403
404 //Pattern
405 typedef Boolean
406 (*ORTEPatternCheck)(const char *string);
407 typedef Boolean
408 (*ORTEPatternMatch)(const char *topic,const char *pattern,void *param);
409 extern Boolean
410 ORTEPatternCheckDefault(const char *topic);
411 extern Boolean
412 ORTEPatternMatchDefault(const char *topic,const char *pattern,void *param);
413 extern void
414 ORTEPatternRegister(ORTEDomain *d,ORTEPatternCheck check,
415      ORTEPatternMatch match,void *param);
416
417
418 //Manager
419 typedef void
420 (*ORTEOnRegFail)(void *param);
421 typedef Boolean 
422 (*ORTEOnMgrNew)(const struct ORTEAppInfo *appInfo, void *param);
423 typedef void 
424 (*ORTEOnMgrDelete)(const struct ORTEAppInfo *appInfo, void *param);
425 //Application
426 typedef Boolean 
427 (*ORTEOnAppRemoteNew)(const struct ORTEAppInfo *appInfo, void *param);
428 typedef void (*ORTEOnAppDelete)
429 (const struct ORTEAppInfo *appInfo, void *param);
430 //Publication
431 typedef Boolean 
432 (*ORTEOnPubRemote)(const struct ORTEAppInfo *appInfo,
433                    const struct ORTEPubInfo *pubInfo, void *param);
434 typedef void 
435 (*ORTEOnPubDelete)(const struct ORTEAppInfo *appInfo,
436                    const struct ORTEPubInfo *pubInfo, void *param);
437 //Subscription
438 typedef Boolean 
439 (*ORTEOnSubRemote)(const struct ORTEAppInfo *appInfo,
440                    const struct ORTESubInfo *subInfo, void *param);
441 typedef void 
442 (*ORTEOnSubDelete)(const struct ORTEAppInfo *appInfo,
443                    const struct ORTESubInfo *subInfo, void *param);
444
445 /**
446  * struct ORTEDomainAppEvents - Domain event handlers of an application
447  * @onRegFail: registration protocol has been failed
448  * @onRegFailParam: user parameters for @onRegFail handler
449  * @onMgrNew: new manager has been created
450  * @onMgrNewParam: user parameters for @onMgrNew handler
451  * @onMgrDelete: manager has been deleted
452  * @onMgrDeleteParam: user parameters for @onMgrDelete handler
453  * @onAppRemoteNew: new remote application has been registered
454  * @onAppRemoteNewParam: user parameters for @onAppRemoteNew handler
455  * @onAppDelete: an application has been removed
456  * @onAppDeleteParam: user parameters for @onAppDelete handler
457  * @onPubRemoteNew: new remote publication has been registered
458  * @onPubRemoteNewParam: user parameters for @onPubRemoteNew handler
459  * @onPubRemoteChanged: a remote publication's parameters has been changed
460  * @onPubRemoteChangedParam: user parameters for @onPubRemoteChanged handler
461  * @onPubDelete: a publication has been deleted
462  * @onPubDeleteParam: user parameters for @onPubDelete handler
463  * @onSubRemoteNew: a new remote subscription has been registered
464  * @onSubRemoteNewParam: user parameters for @onSubRemoteNew handler
465  * @onSubRemoteChanged: a remote subscription's parameters has been changed
466  * @onSubRemoteChangedParam: user parameters for @onSubRemoteChanged handler
467  * @onSubDelete: a publication has been deleted
468  * @onSubDeleteParam: user parameters for @onSubDelete handler
469  *
470  * Prototypes of events handler fucntions can be found in file typedefs_api.h.
471  */
472 typedef struct ORTEDomainAppEvents {
473   ORTEOnRegFail          onRegFail;
474   void                   *onRegFailParam;
475   ORTEOnMgrNew           onMgrNew;
476   void                   *onMgrNewParam;
477   ORTEOnMgrDelete        onMgrDelete;
478   void                   *onMgrDeleteParam;
479   ORTEOnAppRemoteNew     onAppRemoteNew;
480   void                   *onAppRemoteNewParam;
481   ORTEOnAppDelete        onAppDelete;
482   void                   *onAppDeleteParam;
483   ORTEOnPubRemote        onPubRemoteNew;
484   void                   *onPubRemoteNewParam;
485   ORTEOnPubRemote        onPubRemoteChanged;
486   void                   *onPubRemoteChangedParam;
487   ORTEOnPubDelete        onPubDelete;
488   void                   *onPubDeleteParam;
489   ORTEOnSubRemote        onSubRemoteNew;
490   void                   *onSubRemoteNewParam;
491   ORTEOnSubRemote        onSubRemoteChanged;
492   void                   *onSubRemoteChangedParam;
493   ORTEOnSubDelete        onSubDelete;
494   void                   *onSubDeleteParam;
495 } ORTEDomainAppEvents;
496
497 /**
498  * struct ORTETaskProp - ORTE task properties, not supported 
499  * @realTimeEnabled: not supported
500  * @smtStackSize: not supported
501  * @smtPriority: not supported
502  * @rmtStackSize: not supported
503  * @rmtPriority: not supported 
504  */
505 typedef struct ORTETasksProp {
506   Boolean                realTimeEnabled;
507   int                    smtStackSize;
508   int                    smtPriority;
509   int                    rmtStackSize;
510   int                    rmtPriority;
511 } ORTETasksProp; 
512
513 /**
514  * struct ORTEDomainApp - domain properties 
515  * @tasksProp: task properties
516  * @IFProp: properties of network interfaces
517  * @IFCount: number of network interfaces              
518  * @baseProp: base properties (see @ORTEDomainBaseProp for details)
519  * @wireProp: wire properties (see @ORTEDomainWireProp for details)
520  * @multicast: multicast properties (see @ORTEMulticastProp for details)               
521  * @publPropDefault: default properties of publiciations (see @ORTEPublProp for details)      
522  * @subsPropDefault: default properties of subscriptions (see @ORTESubsProp for details)
523  * @mgrs: list of known managers               
524  * @keys: access keys for managers             
525  * @appLocalManager: IP address of local manager (default localhost)      
526  * @listen: IP address to listen on
527  * @version: string product version
528  * @recvBuffSize: receiving queue length
529  * @sendBuffSize: transmitting queue length
530  */
531 typedef struct ORTEDomainProp {
532   ORTETasksProp          tasksProp;
533   ORTEIFProp             IFProp[MAX_INTERFACES];  //interface properties
534   unsigned char          IFCount;                 //count of interfaces
535   ORTEDomainBaseProp     baseProp;
536   ORTEDomainWireProp     wireProp;
537   ORTEMulticastProp      multicast;               //multicast properies
538   ORTEPublProp           publPropDefault;         //default properties for a Publ/Sub
539   ORTESubsProp           subsPropDefault;
540   char                   *mgrs;                   //managers
541   char                   *keys;                   //keys
542   IPAddress              appLocalManager;         //applications
543   IPAddress              listen;
544   char                   version[60];             //string product version
545   int                    recvBuffSize;
546   int                    sendBuffSize;      
547 } ORTEDomainProp;
548
549 #ifdef __cplusplus
550 } /* extern "C"*/
551 #endif
552
553 #endif  /* _TYPEDEFS_API_H */
554