2 * $Id: protos_api.h,v 0.0.0.1 2003/09/10
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@smoliku.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.
37 ///////////////////////////////////////////////////////////////////////////////
40 * IPAddressToString - converts IP address IPAddress to its string representation
41 * @ipAddress: source IP address
42 * @buff: output buffer
45 IPAddressToString(IPAddress ipAddress,char *buff);
48 * StringToIPAddress - converts IP address from string into IPAddress
49 * @string: source string
52 StringToIPAddress(const char *string);
55 * NtpTimeToStringMs - converts NtpTime to its text representation in miliseconds
56 * @time: time given in NtpTime structure
57 * @buff: output buffer
60 NtpTimeToStringMs(NtpTime time,char *buff);
63 * NtpTimeToStringUs - converts NtpTime to its text representation in microseconds
64 * @time: time given in NtpTime structure
65 * @buff: output buffer
68 NtpTimeToStringUs(NtpTime time,char *buff);
71 ///////////////////////////////////////////////////////////////////////////////
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).
82 * Functions @ORTEDomainAppCreate and @ORTEDomainMgrCreate provide facility to create an object with its threads suspended. Use function @ORTEDomainStart to resume those
86 ORTEDomainStart(ORTEDomain *d,
87 Boolean recvUnicastMetatrafficThread,
88 Boolean recvMulticastMetatrafficThread,
89 Boolean recvUnicastUserdataThread,
90 Boolean recvMulticastUserdataThread,
93 * ORTEDomainPropDefaultGet - returns default properties of a domain
94 * @prop: pointer to struct ORTEDomainProp
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.
99 ORTEDomainPropDefaultGet(ORTEDomainProp *prop);
102 * ORTEDomainInitEvents - initializes list of events
103 * @events: pointer to struct ORTEDomainAppEvents
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.
108 ORTEDomainInitEvents(ORTEDomainAppEvents *events);
111 ///////////////////////////////////////////////////////////////////////////////
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
121 * Creates new Application object and sets its properties and events. Return handle to created object or NULL in case of any error.
124 ORTEDomainAppCreate(int domain,ORTEDomainProp *prop,ORTEDomainAppEvents *events,
128 * ORTEDomainAppDestroy - destroy Application object
131 * Destroys all application objects in specified domain. Returns ORTE_TRUE or ORTE_FALSE in case of any error.
134 ORTEDomainAppDestroy(ORTEDomain *d);
137 * ORTEDomainAppSubscriptionPatternAdd - create pattern-based subscription
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
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.
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".
151 * Syntax for patterns is the same as syntax for @fnmatch function, which is employed for pattern recognition.
153 * Returns ORTE_TRUE if successful or ORTE_FALSE in case of any error.
157 ORTEDomainAppSubscriptionPatternAdd(ORTEDomain *d,const char *topic,
158 const char *type,ORTESubscriptionPatternCallBack subscriptionCallBack,
162 * ORTEDomainAppSubscriptionPatternRemove - remove subscription pattern
164 * @topic: pattern to be removed
165 * @type: pattern to be removed
167 * Removes subscritions created by @ORTEDomainAppSubscriptionPatternAdd. Patterns for @type and @topic must be exactly the same strings as when
168 * @ORTEDomainAppSubscriptionPatternAdd function was called.
170 * Returns ORTE_TRUE if successful or ORTE_FALSE if none matching record was found
173 ORTEDomainAppSubscriptionPatternRemove(ORTEDomain *d,const char *topic,
177 * ORTEDomainAppSubscriptionPatternDestroy - destroys all subscription patterns
180 * Destroys all subscription patterns which were specified previously by @ORTEDomainAppSubscriptionPatternAdd function.
182 * Returns ORTE_TRUE if successful or ORTE_FALSE in case of any error.
185 ORTEDomainAppSubscriptionPatternDestroy(ORTEDomain *d);
187 ///////////////////////////////////////////////////////////////////////////////
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
198 * Creates new manager object and sets its properties and events. Return handle to created object or NULL in case of any error.
201 ORTEDomainMgrCreate(int domain, ORTEDomainProp *prop,
202 ORTEDomainAppEvents *events,Boolean suspended);
205 * ORTEDomainMgrDestroy - destroy manager object
206 * @d: manager object to be destroyed
208 * Returns ORTE_TRUE if successful or ORTE_FALSE in case of any error.
211 ORTEDomainMgrDestroy(ORTEDomain *d);
213 ///////////////////////////////////////////////////////////////////////////////
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
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.
231 * Returns handle to publication object.
233 extern ORTEPublication *
234 ORTEPublicationCreate(ORTEDomain *d,
236 const char *typeName,
238 NtpTime *persistence,
240 ORTESendCallBack sendCallBack,
241 void *sendCallBackParam,
242 NtpTime *sendCallBackDelay);
244 * ORTEPublicationDestroy - removes a publication
245 * @cstWriter: handle to publication to be removed
247 * Returns ORTE_OK if successful or ORTE_BAD_HANDLE if @cstWriter is not valid cstWriter handle.
250 ORTEPublicationDestroy(ORTEPublication *cstWriter);
253 * ORTEPublicationPropertiesGet - read properties of a publication
254 * @cstWriter: pointer to cstWriter object which provides this publication
255 * @pp: pointer to ORTEPublProp structure where values of publication's properties will be stored
257 * Returns ORTE_OK if successful or ORTE_BAD_HANDLE if @cstWriter is not valid cstWriter handle.
260 ORTEPublicationPropertiesGet(ORTEPublication *cstWriter,ORTEPublProp *pp);
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
267 * Returns ORTE_OK if successful or ORTE_BAD_HANDLE if @cstWriter is not valid publication handle.
270 ORTEPublicationPropertiesSet(ORTEPublication *cstWriter,ORTEPublProp *pp);
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
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.
282 ORTEPublicationWaitForSubscriptions(ORTEPublication *cstWriter,
284 unsigned int retries,
285 unsigned int noSubscriptions);
288 * ORTEPublicationGetStatus - removes a publication
289 * @cstWriter: pointer to cstWriter object which provides this publication
290 * @status: pointer to ORTEPublStatus structure
292 * Returns ORTE_OK if successful or ORTE_BAD_HANDLE if @happ is not valid publication handle.
296 ORTEPublicationGetStatus(ORTEPublication *cstWriter,ORTEPublStatus *status);
299 * ORTEPublicationSend - force publication object to issue new data
300 * @cstWriter: publication object
302 * Returns ORTE_OK if successful.
305 ORTEPublicationSend(ORTEPublication *cstWriter);
308 * ORTEPublicationSendEx - force publication object to issue new data with additional parameters
309 * @cstWriter: publication object
310 * @psp: publication parameters
312 * Returns ORTE_OK if successful.
315 ORTEPublicationSendEx(ORTEPublication *cstWriter,
316 ORTEPublicationSendParam *psp);
319 * ORTEPublicationGetInstance - return pointer to an instance
320 * @cstWriter: publication object
325 ORTEPublicationGetInstance(ORTEPublication *cstWriter);
328 ///////////////////////////////////////////////////////////////////////////////
329 // ORTESubscription.c
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
345 * Returns handle to Subscription object.
347 extern ORTESubscription *
348 ORTESubscriptionCreate(ORTEDomain *d,
349 SubscriptionMode mode,
350 SubscriptionType sType,
352 const char *typeName,
355 NtpTime *minimumSeparation,
356 ORTERecvCallBack recvCallBack,
357 void *recvCallBackParam,
358 IPAddress multicastIPAddress);
361 * ORTESubscriptionDestroy - removes a subscription
362 * @cstReader: handle to subscriotion to be removed
364 * Returns ORTE_OK if successful or ORTE_BAD_HANDLE if @cstReader is not valid subscription handle.
367 ORTESubscriptionDestroy(ORTESubscription *cstReader);
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
375 ORTESubscriptionPropertiesGet(ORTESubscription *cstReader,ORTESubsProp *sp);
378 * ORTESubscriptionPropertiesSet - set properties of a subscription
379 * @cstReader: handle to publication
380 * @sp: pointer to ORTESubsProp structure containing desired properties of the subscription
382 * Returns ORTE_OK if successful or ORTE_BAD_HANDLE if @cstReader is not valid subscription handle.
385 ORTESubscriptionPropertiesSet(ORTESubscription *cstReader,ORTESubsProp *sp);
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
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..
397 ORTESubscriptionWaitForPublications(ORTESubscription *cstReader,NtpTime wait,
398 unsigned int retries,unsigned int noPublications);
401 * ORTESubscriptionGetStatus - get status of a subscription
402 * @cstReader: handle to subscription
403 * @status: pointer to ORTESubsStatus structure
405 * Returns ORTE_OK if successful or ORTE_BAD_HANDLE if @cstReader is not valid subscription handle.
408 ORTESubscriptionGetStatus(ORTESubscription *cstReader,ORTESubsStatus *status);
411 * ORTESubscriptionPull - read data from receiving buffer
412 * @cstReader: handle to subscription
414 * Returns ORTE_OK if successful or ORTE_BAD_HANDLE if @cstReader is not valid subscription handle.
417 ORTESubscriptionPull(ORTESubscription *cstReader);
420 * ORTESubscriptionGetInstance - return pointer to an instance
421 * @cstReader: publication object
426 ORTESubscriptionGetInstance(ORTESubscription *cstReader);
429 ///////////////////////////////////////////////////////////////////////////////
430 // ORTETypeRegister.c
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
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.
443 * Examples of serialization and deserialization functions can be found if contrib/shape/ortedemo_types.c file.
445 * Returns ORTE_OK if new data type has been succesfully registered.
448 ORTETypeRegisterAdd(ORTEDomain *d,const char *typeName,ORTETypeSerialize ts,
449 ORTETypeDeserialize ds,ORTETypeGetMaxSize gms,unsigned int ms);
451 * ORTETypeRegisterDestroyAll - destroy all registered data types
452 * @d: domain object handle
454 * Destroys all data types which were previously registered by function @ORTETypeRegisterAdd.
456 * Return ORTE_OK if all data types has been succesfully destroyed.
459 ORTETypeRegisterDestroyAll(ORTEDomain *d);
461 ///////////////////////////////////////////////////////////////////////////////
464 * ORTEVerbositySet - set verbosity options
465 * @options: verbosity options
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.
473 * Verbosity will be set to level 7 for all modules.
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.
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.
481 * Return ORTE_OK if desired verbosity levels were successfuly set.
484 ORTEVerbositySetOptions(const char *options);
487 * ORTEVerbositySetLogFile - set log file
488 * @logfile: log file name
490 * Sets output file where debug messages will be writen to. By default these messages are written to stdout.
493 ORTEVerbositySetLogFile(const char *logfile);
496 ///////////////////////////////////////////////////////////////////////////////
500 * ORTEInit - initialization of ORTE layer (musi se zavolat)
503 extern void ORTEInit(void);
505 ///////////////////////////////////////////////////////////////////////////////
508 * ORTESleepMs - suspends calling thread for given time
509 * @ms: miliseconds to sleep
512 ORTESleepMs(unsigned int ms);
518 #endif /* _PROTOS_API_H */