orte/include/orte/typedefs_api.h

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