orte/include/orte/protos_api.h

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