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