2 * $Id: typedefs_api.h,v 0.0.0.1 2003/08/21
4 * -------------------------------------------------------------------
6 * Open Real-Time Ethernet
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
13 * Author: Petr Smolik petr@smoliku.cz
15 * Project Responsible: Zdenek Hanzalek
16 * --------------------------------------------------------------------
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.
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.
30 #ifndef _TYPEDEFS_API_H
31 #define _TYPEDEFS_API_H
37 typedef struct ORTEDomain ORTEDomain; //forward declaration
38 typedef struct CSTWriter ORTEPublication; //forward declaration
39 typedef struct CSTReader ORTESubscription; //forward declaration
42 * enum SubscriptionMode - mode of subscription
44 * @IMMEDIATE: using callback function
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.
48 typedef enum SubscriptionMode {
54 * enum SubscriptionType - type of subcsription
55 * @BEST_EFFORTS: best effort subscription
56 * @STRICT_RELIABLE: strict reliable subscription.
58 * Specifies which mode will be used for this subscription.
60 typedef enum SubscriptionType {
62 STRICT_RELIABLE = 0x02
66 * enum ORTERecvStatus - status of a subscription
67 * @NEW_DATA: new data has arrived
68 * @DEADLINE: deadline has occurred
70 * Specifies which event has occurred in the subscription object.
72 typedef enum ORTERecvStatus {
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.
82 * Specifies which event has occurred in the publication object. Critical level of transmit queue is specified as one of publication properties (ORTEPublProp.criticalQueueLevel).
84 typedef enum ORTESendStatus {
90 * struct ORTEIFProp - interface flags
92 * @ipAddress: IP address
94 * Flags for network interface.
96 typedef struct ORTEIFProp {
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
108 * Properties for ORTE multicast subsystem which is not fully supported yet. Multicast IP address is assigned by the ORTE middleware itself.
110 typedef struct ORTEMulticastProp {
113 Boolean loopBackEnabled;
119 * struct ORTETypeGetMaxSizeParam - parameters for function ORTETypeGetMaxSize
127 * It used to determine maximal size of intermal buffer for incomming data
129 typedef struct ORTEGetMaxSizeParam {
130 CDR_Endianness host_endian;
131 CDR_Endianness data_endian;
133 unsigned int max_size;
136 } ORTEGetMaxSizeParam;
138 typedef void (*ORTETypeSerialize)(CDR_Codec *cdrCodec, void *instance);
140 typedef void (*ORTETypeDeserialize)(CDR_Codec *cdrCodec, void *instance);
142 typedef int (*ORTETypeGetMaxSize)(ORTEGetMaxSizeParam *gms, int num);
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
152 * Contains description of registered data type. See @ORTETypeRegisterAdd function for details.
154 typedef struct ORTETypeRegister {
155 const char *typeName;
156 ORTETypeSerialize serialize;
157 ORTETypeDeserialize deserialize;
158 ORTETypeGetMaxSize getMaxSize;
159 unsigned int maxSize;
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)
181 typedef struct ORTEDomainBaseProp {
182 unsigned int registrationMgrRetries;
183 NtpTime registrationMgrPeriod;
184 unsigned int registrationAppRetries;
185 NtpTime registrationAppPeriod;
186 NtpTime expirationTime;
187 NtpTime refreshPeriod;
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;
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)
205 typedef struct ORTEDomainWireProp {
206 unsigned int metaBytesPerPacket;
207 unsigned int metaBytesPerFastPacket;
208 unsigned int metabitsPerACKBitmap;
209 unsigned int userBytesPerPacket;
210 } ORTEDomainWireProp;
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
228 typedef struct ORTEPublProp {
231 TypeChecksum typeChecksum;
234 uint32_t reliabilityOffered;
235 uint32_t sendQueueSize;
237 uint32_t criticalQueueLevel;
238 NtpTime HBNornalRate;
240 unsigned int HBMaxRetries;
241 NtpTime maxBlockTime;
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)
256 typedef struct ORTESubsProp {
259 TypeChecksum typeChecksum;
260 NtpTime minimumSeparation;
261 uint32_t recvQueueSize;
262 uint32_t reliabilityRequested;
263 //additional parameters
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
282 typedef struct ORTEAppInfo {
285 IPAddress *unicastIPAddressList;
286 unsigned char unicastIPAddressCount;
287 IPAddress *metatrafficMulticastIPAddressList;
288 unsigned char metatrafficMulticastIPAddressCount;
289 Port metatrafficUnicastPort;
290 Port userdataUnicastPort;
292 ProtocolVersion protocolVersion;
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
301 typedef struct ORTEPubInfo {
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
313 typedef struct ORTESubInfo {
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
325 typedef struct ORTEPublStatus {
327 unsigned int bestEffort;
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
337 typedef struct ORTESubsStatus {
339 unsigned int bestEffort;
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
354 typedef struct ORTERecvInfo {
355 ORTERecvStatus status;
358 GUID_RTPS senderGUID;
359 NtpTime localTimeReceived;
360 NtpTime remoteTimePublished;
362 CDR_Endianness data_endian;
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
373 typedef struct ORTESendInfo {
374 ORTESendStatus status;
377 GUID_RTPS senderGUID;
384 (*ORTERecvCallBack)(const ORTERecvInfo *info,void *instance, void *recvCallBackParam);
386 (*ORTESendCallBack)(const ORTESendInfo *info,void *instance, void *sendCallBackParam);
387 typedef ORTESubscription*
388 (*ORTESubscriptionPatternCallBack)(const char *topic, const char *type, void *Param);
391 * struct ORTEPublicationSendParam - description of sending data
392 * @instance: pointer to new data instance
393 * @data_endian: endianing of sending data (BIG | LITTLE)
395 typedef struct ORTEPublicationSendParam {
398 } ORTEPublicationSendParam;
402 (*ORTEPatternCheck)(const char *string);
404 (*ORTEPatternMatch)(const char *topic,const char *pattern,void *param);
406 ORTEPatternCheckDefault(const char *topic);
408 ORTEPatternMatchDefault(const char *topic,const char *pattern,void *param);
410 ORTEPatternRegister(ORTEDomain *d,ORTEPatternCheck check,
411 ORTEPatternMatch match,void *param);
416 (*ORTEOnRegFail)(void *param);
418 (*ORTEOnMgrNew)(const struct ORTEAppInfo *appInfo, void *param);
420 (*ORTEOnMgrDelete)(const struct ORTEAppInfo *appInfo, void *param);
423 (*ORTEOnAppRemoteNew)(const struct ORTEAppInfo *appInfo, void *param);
424 typedef void (*ORTEOnAppDelete)
425 (const struct ORTEAppInfo *appInfo, void *param);
428 (*ORTEOnPubRemote)(const struct ORTEAppInfo *appInfo,
429 const struct ORTEPubInfo *pubInfo, void *param);
431 (*ORTEOnPubDelete)(const struct ORTEAppInfo *appInfo,
432 const struct ORTEPubInfo *pubInfo, void *param);
435 (*ORTEOnSubRemote)(const struct ORTEAppInfo *appInfo,
436 const struct ORTESubInfo *subInfo, void *param);
438 (*ORTEOnSubDelete)(const struct ORTEAppInfo *appInfo,
439 const struct ORTESubInfo *subInfo, void *param);
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
466 * Prototypes of events handler fucntions can be found in file typedefs_api.h.
468 typedef struct ORTEDomainAppEvents {
469 ORTEOnRegFail onRegFail;
470 void *onRegFailParam;
471 ORTEOnMgrNew onMgrNew;
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;
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
501 typedef struct ORTETasksProp {
502 Boolean realTimeEnabled;
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
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
538 IPAddress appLocalManager; //applications
540 char version[60]; //string product version
549 #endif /* _TYPEDEFS_API_H */