orte/include/orte/protos_api.h

   1 /*
   2  *  $Id: protos_api.h,v 0.0.0.1             2003/09/10
   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 _PROTOS_API_H
  22 #define _PROTOS_API_H
  23
  24 #ifdef __cplusplus
  25 extern "C" {
  26 #endif
  27
  28 ///////////////////////////////////////////////////////////////////////////////
  29 // conv.c
  30 /**
  31  * IPAddressToString - converts IP address IPAddress to its string representation
  32  * @ipAddress: source IP address
  33  * @buff: output buffer
  34  */
  35 extern char*
  36 IPAddressToString(IPAddress ipAddress,char *buff);
  37
  38 /**
  39  * StringToIPAddress - converts IP address from string into IPAddress
  40  * @string: source string
  41  */
  42 extern IPAddress
  43 StringToIPAddress(const char *string);
  44
  45 /**
  46  * NtpTimeToStringMs - converts NtpTime to its text representation in miliseconds
  47  * @time: time given in NtpTime structure
  48  * @buff: output buffer
  49  */
  50 extern char *
  51 NtpTimeToStringMs(NtpTime time,char *buff);
  52
  53 /**
  54  * NtpTimeToStringUs - converts NtpTime to its text representation in microseconds
  55  * @time: time given in NtpTime structure
  56  * @buff: output buffer
  57  */
  58 extern char *
  59 NtpTimeToStringUs(NtpTime time,char *buff);
  60
  61
  62 ///////////////////////////////////////////////////////////////////////////////
  63 // ORTEDomain.c
  64 /**
  65  * ORTEDomainStart - start specific threads
  66  * @d: domain object handle
  67  * @recvUnicastMetatrafficThread: specifies whether recvUnicastMetatrafficThread should be started (ORTE_TRUE) or remain suspended (ORTE_FALSE).
  68  * @recvMulticastMetatrafficThread: specifies whether recvMulticastMetatrafficThread should be started (ORTE_TRUE) or remain suspended (ORTE_FALSE).
  69  * @recvUnicastUserdataThread: specifies whether recvUnicastUserdataThread should be started (ORTE_TRUE) or remain suspended (ORTE_FALSE).
  70  * @recvMulticastUserdataThread: specifies whether recvMulticastUserdataThread should be started (ORTE_TRUE) or remain suspended (ORTE_FALSE).
  71  * @sendThread: specifies whether sendThread should be started (ORTE_TRUE) or remain suspended (ORTE_FALSE).
  72  *
  73  * Functions @ORTEDomainAppCreate and @ORTEDomainMgrCreate provide facility to create an object with its threads suspended. Use function @ORTEDomainStart to resume those
  74  * suspended threads.
  75  */
  76 extern void
  77 ORTEDomainStart(ORTEDomain *d,
  78                 Boolean recvUnicastMetatrafficThread,
  79                 Boolean recvMulticastMetatrafficThread,
  80                 Boolean recvUnicastUserdataThread,
  81                 Boolean recvMulticastUserdataThread,
  82                 Boolean sendThread);
  83 /**
  84  * ORTEDomainPropDefaultGet - returns default properties of a domain
  85  * @prop: pointer to struct ORTEDomainProp
  86  *
  87  * Structure ORTEDomainProp referenced by @prop will be filled by its default values. Returns ORTE_TRUE if successful or ORTE_FALSE in case of any error.
  88  */
  89 extern Boolean
  90 ORTEDomainPropDefaultGet(ORTEDomainProp *prop);
  91
  92 /**
  93  * ORTEDomainInitEvents - initializes list of events
  94  * @events: pointer to struct ORTEDomainAppEvents
  95  *
  96  * Initializes structure pointed by @events. Every member is set to NULL. Returns ORTE_TRUE if successful or ORTE_FALSE in case of any error.
  97  */
  98 extern Boolean
  99 ORTEDomainInitEvents(ORTEDomainAppEvents *events);
 100
 101
 102 ///////////////////////////////////////////////////////////////////////////////
 103 // ORTEDomainApp.c
 104 /**
 105  * ORTEDomainAppCreate - creates an application object within given domain
 106  * @domain: given domain
 107  * @prop: properties of application
 108  * @events: events associated with application or NULL
 109  * @suspended: specifies whether threads of this application should be started as well (ORTE_FALSE) or stay suspended (ORTE_TRUE). See @ORTEDomainStart for details how to resume
 110  * suspended threads
 111  *
 112  * Creates new Application object and sets its properties and events. Return handle to created object or NULL in case of any error.
 113  */
 114 extern ORTEDomain *
 115 ORTEDomainAppCreate(int domain,ORTEDomainProp *prop,ORTEDomainAppEvents *events,
 116     Boolean suspended);
 117
 118 /**
 119  * ORTEDomainAppDestroy - destroy Application object
 120  * @d: domain
 121  *
 122  * Destroys all application objects in specified domain. Returns ORTE_TRUE or ORTE_FALSE in case of any error.
 123  */
 124 extern Boolean
 125 ORTEDomainAppDestroy(ORTEDomain *d);
 126
 127 /**
 128  * ORTEDomainAppSubscriptionPatternAdd - create pattern-based subscription
 129  * @d: domain object
 130  * @topic: pattern for topic
 131  * @type: pattern for type
 132  * @subscriptionCallBack: pointer to callback function which will be called whenever any data are received through this subscription
 133  * @param: user params for callback function
 134  *
 135  * This function is intended to be used in application interesded in more published data from possibly more remote applications, which should be received through single
 136  * subscription. These different publications are specified by pattern given to @topic and @type parameters.
 137  *
 138  * For example suppose there are publications of topics like @temperatureEngine1, @temperatureEngine2, @temperatureEngine1Backup and @temperatureEngine2Backup
 139  * somewhere on our network. We can subscribe to each of Engine1 temperations by creating single subscription with pattern for topic set to "temperatureEngine1*".
 140  * Or, if we are interested only in values from backup measurements, we can use pattern "*Backup".
 141  *
 142  * Syntax for patterns is the same as syntax for @fnmatch function, which is employed for pattern recognition.
 143  *
 144  * Returns ORTE_TRUE if successful or ORTE_FALSE in case of any error.
 145  */
 146
 147 extern Boolean
 148 ORTEDomainAppSubscriptionPatternAdd(ORTEDomain *d,const char *topic,
 149     const char *type,ORTESubscriptionPatternCallBack subscriptionCallBack,
 150     void *param);
 151
 152 /**
 153  * ORTEDomainAppSubscriptionPatternRemove - remove subscription pattern
 154  * @d: domain handle
 155  * @topic: pattern to be removed
 156  * @type: pattern to be removed
 157  *
 158  * Removes subscritions created by @ORTEDomainAppSubscriptionPatternAdd. Patterns for @type and @topic must be exactly the same strings as when
 159  * @ORTEDomainAppSubscriptionPatternAdd function was called.
 160  *
 161  * Returns ORTE_TRUE if successful or ORTE_FALSE if none matching record was found
 162  */
 163 extern Boolean
 164 ORTEDomainAppSubscriptionPatternRemove(ORTEDomain *d,const char *topic,
 165     const char *type);
 166
 167 /**
 168  * ORTEDomainAppSubscriptionPatternDestroy - destroys all subscription patterns
 169  * @d: domain handle
 170  *
 171  * Destroys all subscription patterns which were specified previously by @ORTEDomainAppSubscriptionPatternAdd function.
 172  *
 173  * Returns ORTE_TRUE if successful or ORTE_FALSE in case of any error.
 174  */
 175 extern Boolean
 176 ORTEDomainAppSubscriptionPatternDestroy(ORTEDomain *d);
 177
 178 ///////////////////////////////////////////////////////////////////////////////
 179 // ORTEDomainMgr.c
 180
 181 /**
 182  * ORTEDomainMgrCreate - create manager object in given domain
 183  * @domain: given domain
 184  * @prop: desired manager's properties
 185  * @events: manager's event handlers or NULL
 186  * @suspended: specifies whether threads of this manager should be started as well (ORTE_FALSE) or stay suspended (ORTE_TRUE). See @ORTEDomainStart for details how to resume
 187  * suspended threads
 188  *
 189  * Creates new manager object and sets its properties and events. Return handle to created object or NULL in case of any error.
 190  */
 191 extern ORTEDomain *
 192 ORTEDomainMgrCreate(int domain, ORTEDomainProp *prop,
 193     ORTEDomainAppEvents *events,Boolean suspended);
 194
 195 /**
 196  * ORTEDomainMgrDestroy - destroy manager object
 197  * @d: manager object to be destroyed
 198  *
 199  * Returns ORTE_TRUE if successful or ORTE_FALSE in case of any error.
 200  */
 201 extern Boolean
 202 ORTEDomainMgrDestroy(ORTEDomain *d);
 203
 204 ///////////////////////////////////////////////////////////////////////////////
 205 // ORTEPublication.c
 206 /**
 207  * ORTEAppPubAdd - creates new publication
 208  * @d: pointer to application object
 209  * @topic: name of topic
 210  * @typeName: data type description
 211  * @instance: output buffer where application stores data for publication
 212  * @persistence: persistence of publication
 213  * @strength: strength of publication
 214  * @sendCallBack: pointer to callback function
 215  * @sendCallBackParam: user parameters for callback function
 216  * @sendCallBackDelay: periode for timer which issues callback function
 217  *
 218  * Creates new publication object with specified parameters. The @sendCallBack function is called periodically with @sendCallBackDelay periode. In strict reliable mode the @sendCallBack
 219  * function will be called only if there is enough room in transmitting queue in order to prevent any data loss. The @sendCallBack function should prepare data to be published by
 220  * this publication and place them into @instance buffer.
 221  *
 222  * Returns handle to publication object.
 223  */
 224 extern ORTEPublication *
 225 ORTEPublicationCreate(ORTEDomain *d,
 226                       const char *topic,
 227                       const char *typeName,
 228                       void *instance,
 229                       NtpTime *persistence,
 230                       int strength,
 231                       ORTESendCallBack sendCallBack,
 232                       void *sendCallBackParam,
 233                       NtpTime *sendCallBackDelay);
 234 /**
 235  * ORTEPublicationDestroy - removes a publication
 236  * @cstWriter: handle to publication to be removed
 237  *
 238  * Returns ORTE_OK if successful or ORTE_BAD_HANDLE if @cstWriter is not valid cstWriter handle.
 239  */
 240 extern int
 241 ORTEPublicationDestroy(ORTEPublication *cstWriter);
 242 extern int
 243
 244 /**
 245  * ORTEPublicationPropertiesGet - read properties of a publication
 246  * @cstWriter: pointer to cstWriter object which provides this publication
 247  * @pp: pointer to ORTEPublProp structure where values of publication's properties will be stored
 248  *
 249  * Returns ORTE_OK if successful or ORTE_BAD_HANDLE if @cstWriter is not valid cstWriter handle.
 250  */
 251 ORTEPublicationPropertiesGet(ORTEPublication *cstWriter,ORTEPublProp *pp);
 252
 253 /**
 254  * ORTEPublicationPropertiesSet - set properties of a publication
 255  * @cstWriter: pointer to cstWriter object which provides this publication
 256  * @pp: pointer to ORTEPublProp structure containing values of publication's properties
 257  *
 258  * Returns ORTE_OK if successful or ORTE_BAD_HANDLE if @cstWriter is not valid publication handle.
 259  */
 260 extern int
 261 ORTEPublicationPropertiesSet(ORTEPublication *cstWriter,ORTEPublProp *pp);
 262
 263 /*
 264  * ORTEAppPublWaitForSubs - waits for given number of subscriptions
 265  * @cstWriter: pointer to cstWriter object which provides this publication
 266  * @wait: time how long to wait
 267  * @retries: number of retries if specified number of subscriptions was not reached
 268  * @noSubscriptions: desired number of subscriptions
 269  *
 270  * Returns ORTE_OK if successful or ORTE_BAD_HANDLE if @cstWriter is not valid publication handle or ORTE_TIMEOUT if number of retries has been exhausted.
 271 */
 272 extern int
 273 ORTEPublicationWaitForSubscriptions(ORTEPublication *cstWriter,
 274                                     NtpTime wait,
 275                                     unsigned int retries,
 276                                     unsigned int noSubscriptions);
 277
 278 /**
 279  * ORTEPublicationGetStatus - removes a publication
 280  * @cstWriter: pointer to cstWriter object which provides this publication
 281  * @status: pointer to ORTEPublStatus structure
 282  *
 283  * Returns ORTE_OK if successful or ORTE_BAD_HANDLE if @happ is not valid publication handle.
 284  */
 285
 286 extern int
 287 ORTEPublicationGetStatus(ORTEPublication *cstWriter,ORTEPublStatus *status);
 288
 289 /**
 290  * ORTEPublicationSend - force publication object to issue new data
 291  * @cstWriter: publication object
 292  *
 293  * Returns ORTE_OK if successful.
 294  */
 295 extern int
 296 ORTEPublicationSend(ORTEPublication *cstWriter);
 297
 298 /**
 299  * ORTEPublicationSendEx - force publication object to issue new data with additional parameters
 300  * @cstWriter: publication object
 301  * @psp: publication parameters
 302  *
 303  * Returns ORTE_OK if successful.
 304  */
 305 extern int
 306 ORTEPublicationSendEx(ORTEPublication *cstWriter,
 307     ORTEPublicationSendParam *psp);
 308
 309 /**
 310  * ORTEPublicationGetInstance - return pointer to an instance
 311  * @cstWriter: publication object
 312  *
 313  * Returns handle
 314  */
 315 extern void *
 316 ORTEPublicationGetInstance(ORTEPublication *cstWriter);
 317
 318
 319 ///////////////////////////////////////////////////////////////////////////////
 320 // ORTESubscription.c
 321
 322 /**
 323  * ORTESubscriptionCreate - adds a new subscription
 324  * @d: pointer to ORTEDomain object where this subscription will be created
 325  * @mode: see enum SubscriptionMode
 326  * @sType: see enum SubscriptionType
 327  * @topic: name of topic
 328  * @typeName: name of data type
 329  * @instance: pointer to output buffer
 330  * @deadline: deadline
 331  * @minimumSeparation: minimum time interval between two publications sent by Publisher as requested by Subscriber (strict - minumSep musi byt 0)
 332  * @recvCallBack: callback function called when new Subscription has been received or if any change of subscription's status occures
 333  * @recvCallBackParam: user parameters for @recvCallBack
 334  * @multicastIPAddress: in case multicast subscripton specify multicast IP address or use IPADDRESS_INVALID to unicast communication
 335  *
 336  * Returns handle to Subscription object.
 337  */
 338 extern ORTESubscription *
 339 ORTESubscriptionCreate(ORTEDomain *d,
 340                        SubscriptionMode mode,
 341                        SubscriptionType sType,
 342                        const char *topic,
 343                        const char *typeName,
 344                        void *instance,
 345                        NtpTime *deadline,
 346                        NtpTime *minimumSeparation,
 347                        ORTERecvCallBack recvCallBack,
 348                        void *recvCallBackParam,
 349                        IPAddress multicastIPAddress);
 350
 351 /**
 352  * ORTESubscriptionDestroy - removes a subscription
 353  * @cstReader: handle to subscriotion to be removed
 354  *
 355  * Returns ORTE_OK if successful or ORTE_BAD_HANDLE if @cstReader is not valid subscription handle.
 356  */
 357 extern int
 358 ORTESubscriptionDestroy(ORTESubscription *cstReader);
 359
 360 /**
 361  * ORTESubscriptionPropertiesGet - get properties of a subscription
 362  * @cstReader: handle to publication
 363  * @sp: pointer to ORTESubsProp structure where properties of subscrition will be stored
 364  */
 365 extern int
 366 ORTESubscriptionPropertiesGet(ORTESubscription *cstReader,ORTESubsProp *sp);
 367
 368 /**
 369  * ORTESubscriptionPropertiesSet - set properties of a subscription
 370  * @cstReader: handle to publication
 371  * @sp: pointer to ORTESubsProp structure containing desired properties of the subscription
 372  *
 373  * Returns ORTE_OK if successful or ORTE_BAD_HANDLE if @cstReader is not valid subscription handle.
 374  */
 375 extern int
 376 ORTESubscriptionPropertiesSet(ORTESubscription *cstReader,ORTESubsProp *sp);
 377
 378 /**
 379  * ORTESubscriptionWaitForPublications - waits for given number of publications
 380  * @cstReader: handle to subscription
 381  * @wait: time how long to wait
 382  * @retries: number of retries if specified number of publications was not reached
 383  * @noPublications: desired number of publications
 384  *
 385  * Returns ORTE_OK if successful or ORTE_BAD_HANDLE if @cstReader is not valid subscription handle or ORTE_TIMEOUT if number of retries has been exhausted..
 386  */
 387 extern int
 388 ORTESubscriptionWaitForPublications(ORTESubscription *cstReader,NtpTime wait,
 389     unsigned int retries,unsigned int noPublications);
 390
 391 /**
 392  * ORTESubscriptionGetStatus - get status of a subscription
 393  * @cstReader: handle to subscription
 394  * @status: pointer to ORTESubsStatus structure
 395  *
 396  * Returns ORTE_OK if successful or ORTE_BAD_HANDLE if @cstReader is not valid subscription handle.
 397  */
 398 extern int
 399 ORTESubscriptionGetStatus(ORTESubscription *cstReader,ORTESubsStatus *status);
 400
 401 /**
 402  * ORTESubscriptionPull - read data from receiving buffer
 403  * @cstReader: handle to subscription
 404  *
 405  * Returns ORTE_OK if successful or ORTE_BAD_HANDLE if @cstReader is not valid subscription handle.
 406  */
 407 extern int
 408 ORTESubscriptionPull(ORTESubscription *cstReader);
 409
 410 /**
 411  * ORTESubscriptionGetInstance - return pointer to an instance
 412  * @cstReader: publication object
 413  *
 414  * Returns handle
 415  */
 416 extern void *
 417 ORTESubscriptionGetInstance(ORTESubscription *cstReader);
 418
 419
 420 ///////////////////////////////////////////////////////////////////////////////
 421 // ORTETypeRegister.c
 422 /**
 423  * ORTETypeRegisterAdd - register new data type
 424  * @d: domain object handle
 425  * @typeName: name of data type
 426  * @ts: pointer to serialization function. If NULL data will be copied without any processing.
 427  * @ds: deserialization function. If NULL data will be copied without any processing.
 428  * @gms: pointer to a function given maximum length of data (in bytes)
 429  * @ms: default maximal size
 430  *
 431  * Each data type has to be registered. Main purpose of this process is to define serialization and deserialization functions for given data type. The same data type can be
 432  * registered several times, previous registrations of the same type will be overwritten.
 433  *
 434  * Examples of serialization and deserialization functions can be found if contrib/shape/ortedemo_types.c file.
 435  *
 436  * Returns ORTE_OK if new data type has been succesfully registered.
 437  */
 438 extern int
 439 ORTETypeRegisterAdd(ORTEDomain *d,const char *typeName,ORTETypeSerialize ts,
 440                     ORTETypeDeserialize ds,ORTETypeGetMaxSize gms,unsigned int ms);
 441 /**
 442  * ORTETypeRegisterDestroyAll - destroy all registered data types
 443  * @d: domain object handle
 444  *
 445  * Destroys all data types which were previously registered by function @ORTETypeRegisterAdd.
 446  *
 447  * Return ORTE_OK if all data types has been succesfully destroyed.
 448  */
 449 extern int
 450 ORTETypeRegisterDestroyAll(ORTEDomain *d);
 451
 452 ///////////////////////////////////////////////////////////////////////////////
 453 // ORTEVerbosity.c
 454 /**
 455  * ORTEVerbositySet - set verbosity options
 456  * @options: verbosity options
 457  *
 458  * There are 10 levels of verbosity ranging from 1 (lowest) to 10 (highest).
 459  * It is possible to specify certain level of verbosity for each module of ORTE library. List of all supported modules can be found in  linorte/usedSections.txt file.
 460  * Every module has been aasigned with a number as can be seen in usedSections.txt file.
 461  *
 462  * For instance:
 463  * options = "ALL,7"
 464  * Verbosity will be set to level 7 for all modules.
 465  *
 466  * options = "51,7:32,5"
 467  * Modules 51 (RTPSCSTWrite.c) will use verbosity level 7 and module 32 (ORTEPublicationTimer.c) will use verbosity level 5.
 468  *
 469  * Maximum number of modules and verbosity levels can be changed in order to save some memory space if small memory footprint is neccessary. These values are defined as macros
 470  * MAX_DEBUG_SECTIONS and MAX_DEBUG_LEVEL in file @include/defines.h.
 471  *
 472  * Return ORTE_OK if desired verbosity levels were successfuly set.
 473  */
 474 extern void
 475 ORTEVerbositySetOptions(const char *options);
 476
 477 /**
 478  * ORTEVerbositySetLogFile - set log file
 479  * @logfile: log file name
 480  *
 481  * Sets output file where debug messages will be writen to. By default these messages are written to stdout.
 482  */
 483 extern void
 484 ORTEVerbositySetLogFile(const char *logfile);
 485
 486
 487 ///////////////////////////////////////////////////////////////////////////////
 488 // ORTEInit.c
 489
 490 /**
 491  * ORTEInit - initialization of ORTE layer (musi se zavolat)
 492 */
 493
 494 extern void ORTEInit(void);
 495
 496 ///////////////////////////////////////////////////////////////////////////////
 497 // ORTEMisc.c
 498 /**
 499  * ORTESleepMs - suspends calling thread for given time
 500  * @ms: miliseconds to sleep
 501 */
 502 extern void
 503 ORTESleepMs(unsigned int ms);
 504
 505 #ifdef __cplusplus
 506 } /* extern "C"*/
 507 #endif
 508
 509 #endif /* _PROTOS_API_H */