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.smolik@wo.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);
144 typedef void (*ORTETypeProcessEndianness)(CDR_Codec *cdrCodec, void *param);
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
156 * Contains description of registered data type. See @ORTETypeRegisterAdd function for details.
158 typedef struct ORTETypeRegister {
159 const char *typeName;
160 ORTETypeSerialize serialize;
161 ORTETypeDeserialize deserialize;
162 ORTETypeGetMaxSize getMaxSize;
163 unsigned int maxSize;
164 ORTETypeProcessEndianness processEndianness;
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)
187 typedef struct ORTEDomainBaseProp {
188 unsigned int registrationMgrRetries;
189 NtpTime registrationMgrPeriod;
190 unsigned int registrationAppRetries;
191 NtpTime registrationAppPeriod;
192 NtpTime expirationTime;
193 NtpTime refreshPeriod;
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;
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)
211 typedef struct ORTEDomainWireProp {
212 unsigned int metaBytesPerPacket;
213 unsigned int metaBytesPerFastPacket;
214 unsigned int metabitsPerACKBitmap;
215 unsigned int userBytesPerPacket;
216 } ORTEDomainWireProp;
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
234 typedef struct ORTEPublProp {
237 TypeChecksum typeChecksum;
240 uint32_t reliabilityOffered;
241 uint32_t sendQueueSize;
243 uint32_t criticalQueueLevel;
244 NtpTime HBNornalRate;
246 unsigned int HBMaxRetries;
247 NtpTime maxBlockTime;
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)
262 typedef struct ORTESubsProp {
265 TypeChecksum typeChecksum;
266 NtpTime minimumSeparation;
267 uint32_t recvQueueSize;
268 uint32_t reliabilityRequested;
269 //additional parameters
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
288 typedef struct ORTEAppInfo {
291 IPAddress *unicastIPAddressList;
292 unsigned char unicastIPAddressCount;
293 IPAddress *metatrafficMulticastIPAddressList;
294 unsigned char metatrafficMulticastIPAddressCount;
295 Port metatrafficUnicastPort;
296 Port userdataUnicastPort;
298 ProtocolVersion protocolVersion;
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
307 typedef struct ORTEPubInfo {
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
319 typedef struct ORTESubInfo {
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
331 typedef struct ORTEPublStatus {
333 unsigned int bestEffort;
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
343 typedef struct ORTESubsStatus {
345 unsigned int bestEffort;
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
359 typedef struct ORTERecvInfo {
360 ORTERecvStatus status;
363 GUID_RTPS senderGUID;
364 NtpTime localTimeReceived;
365 NtpTime remoteTimePublished;
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
377 typedef struct ORTESendInfo {
378 ORTESendStatus status;
381 GUID_RTPS senderGUID;
388 (*ORTERecvCallBack)(const ORTERecvInfo *info,void *instance, void *recvCallBackParam);
390 (*ORTESendCallBack)(const ORTESendInfo *info,void *instance, void *sendCallBackParam);
391 typedef ORTESubscription*
392 (*ORTESubscriptionPatternCallBack)(const char *topic, const char *type, void *Param);
395 * struct ORTEPublicationSendParam - description of sending data
396 * @instance: pointer to new data instance
397 * @data_endian: endianing of sending data (BIG | LITTLE)
399 typedef struct ORTEPublicationSendParam {
402 } ORTEPublicationSendParam;
406 (*ORTEPatternCheck)(const char *string);
408 (*ORTEPatternMatch)(const char *topic,const char *pattern,void *param);
410 ORTEPatternCheckDefault(const char *topic);
412 ORTEPatternMatchDefault(const char *topic,const char *pattern,void *param);
414 ORTEPatternRegister(ORTEDomain *d,ORTEPatternCheck check,
415 ORTEPatternMatch match,void *param);
420 (*ORTEOnRegFail)(void *param);
422 (*ORTEOnMgrNew)(const struct ORTEAppInfo *appInfo, void *param);
424 (*ORTEOnMgrDelete)(const struct ORTEAppInfo *appInfo, void *param);
427 (*ORTEOnAppRemoteNew)(const struct ORTEAppInfo *appInfo, void *param);
428 typedef void (*ORTEOnAppDelete)
429 (const struct ORTEAppInfo *appInfo, void *param);
432 (*ORTEOnPubRemote)(const struct ORTEAppInfo *appInfo,
433 const struct ORTEPubInfo *pubInfo, void *param);
435 (*ORTEOnPubDelete)(const struct ORTEAppInfo *appInfo,
436 const struct ORTEPubInfo *pubInfo, void *param);
439 (*ORTEOnSubRemote)(const struct ORTEAppInfo *appInfo,
440 const struct ORTESubInfo *subInfo, void *param);
442 (*ORTEOnSubDelete)(const struct ORTEAppInfo *appInfo,
443 const struct ORTESubInfo *subInfo, void *param);
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
470 * Prototypes of events handler fucntions can be found in file typedefs_api.h.
472 typedef struct ORTEDomainAppEvents {
473 ORTEOnRegFail onRegFail;
474 void *onRegFailParam;
475 ORTEOnMgrNew onMgrNew;
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;
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
505 typedef struct ORTETasksProp {
506 Boolean realTimeEnabled;
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
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
542 IPAddress appLocalManager; //applications
544 char version[60]; //string product version
553 #endif /* _TYPEDEFS_API_H */