Bc78yGg5

1/*
2 * Copyright(c) 2006 to 2018 ADLINK Technology Limited and others
3 *
4 * This program and the accompanying materials are made available under the
5 * terms of the Eclipse Public License v. 2.0 which is available at
6 * http://www.eclipse.org/legal/epl-2.0, or the Eclipse Distribution License
7 * v. 1.0 which is available at
8 * http://www.eclipse.org/org/documents/edl-v10.php.
9 *
10 * SPDX-License-Identifier: EPL-2.0 OR BSD-3-Clause
11 */
12#ifndef DDSC_DDS_H
13#define DDSC_DDS_H
14
15/* All header files distributed with Cyclone DDS reside in dds. This file is
16   merely a proxy for dds/dds.h and must be considered deprecated. */
17/*
18 * Copyright(c) 2006 to 2018 ADLINK Technology Limited and others
19 *
20 * This program and the accompanying materials are made available under the
21 * terms of the Eclipse Public License v. 2.0 which is available at
22 * http://www.eclipse.org/legal/epl-2.0, or the Eclipse Distribution License
23 * v. 1.0 which is available at
24 * http://www.eclipse.org/org/documents/edl-v10.php.
25 *
26 * SPDX-License-Identifier: EPL-2.0 OR BSD-3-Clause
27 */
28#ifndef DDS_H
29#define DDS_H
30
31#include <stddef.h>
32#include <stdint.h>
33
34/** @file
35 *
36 *  @brief Eclipse Cyclone DDS C header
37 */
38
39#if defined (__cplusplus)
40#define restrict
41#endif
42
43#ifndef DDS_EXPORT_H
44#define DDS_EXPORT_H
45
46#ifdef DDS_STATIC_DEFINE
47#  define DDS_EXPORT
48#  define DDS_NO_EXPORT
49#else
50#  ifndef DDS_EXPORT
51#    ifdef ddsc_EXPORTS
52        /* We are building this library */
53#      define DDS_EXPORT __declspec(dllexport)
54#    else
55        /* We are using this library */
56#      define DDS_EXPORT __declspec(dllimport)
57#    endif
58#  endif
59
60#  ifndef DDS_NO_EXPORT
61#    define DDS_NO_EXPORT 
62#  endif
63#endif
64
65#ifndef DDS_DEPRECATED
66#  define DDS_DEPRECATED __declspec(deprecated)
67#endif
68
69#ifndef DDS_DEPRECATED_EXPORT
70#  define DDS_DEPRECATED_EXPORT DDS_EXPORT DDS_DEPRECATED
71#endif
72
73#ifndef DDS_DEPRECATED_NO_EXPORT
74#  define DDS_DEPRECATED_NO_EXPORT DDS_NO_EXPORT DDS_DEPRECATED
75#endif
76
77#if 0 /* DEFINE_NO_DEPRECATED */
78#  ifndef DDS_NO_DEPRECATED
79#    define DDS_NO_DEPRECATED
80#  endif
81#endif
82
83#endif /* DDS_EXPORT_H */
84
85/*
86 * Copyright(c) 2020 ADLINK Technology Limited and others
87 *
88 * This program and the accompanying materials are made available under the
89 * terms of the Eclipse Public License v. 2.0 which is available at
90 * http://www.eclipse.org/legal/epl-2.0, or the Eclipse Distribution License
91 * v. 1.0 which is available at
92 * http://www.eclipse.org/org/documents/edl-v10.php.
93 *
94 * SPDX-License-Identifier: EPL-2.0 OR BSD-3-Clause
95 */
96#ifndef _DDS_PUBLIC_FEATURES_H_
97#define _DDS_PUBLIC_FEATURES_H_
98
99/* Whether or not support for DDS Security is included */
100#define DDS_HAS_SECURITY 1
101
102/* Whether or not support for the lifespan QoS is included */
103#define DDS_HAS_LIFESPAN 1
104
105/* Whether or not support for generating "deadline missed" events is included */
106#define DDS_HAS_DEADLINE_MISSED 1
107
108/* Whether or not support for network partitions is included */
109#define DDS_HAS_NETWORK_PARTITIONS 1
110
111/* Whether or not support for source-specific multicast is included */
112#define DDS_HAS_SSM 1
113
114/* Whether or not features dependent on OpenSSL are included */
115/* #undef DDS_HAS_SSL */
116
117/* Whether or not support for type discovery is included */
118/* #undef DDS_HAS_TYPE_DISCOVERY */
119
120#endif
121
122/**
123 * Handle to an entity. A valid entity handle will always have a positive
124 * integer value. Should the value be negative, it is one of the DDS_RETCODE_*
125 * error codes.
126 */
127typedef int32_t dds_entity_t;
128
129/* Sub components */
130
131/*
132 * Copyright(c) 2006 to 2018 ADLINK Technology Limited and others
133 *
134 * This program and the accompanying materials are made available under the
135 * terms of the Eclipse Public License v. 2.0 which is available at
136 * http://www.eclipse.org/legal/epl-2.0, or the Eclipse Distribution License
137 * v. 1.0 which is available at
138 * http://www.eclipse.org/org/documents/edl-v10.php.
139 *
140 * SPDX-License-Identifier: EPL-2.0 OR BSD-3-Clause
141 */
142
143/**
144 * @file
145 * @brief DDS C Time support API
146 *
147 * This header file defines the public API of the in the
148 * CycloneDDS C language binding.
149 */
150#ifndef DDS_TIME_H
151#define DDS_TIME_H
152
153#include <stdint.h>
154#include <assert.h>
155
156/*
157 * Copyright(c) 2006 to 2018 ADLINK Technology Limited and others
158 *
159 * This program and the accompanying materials are made available under the
160 * terms of the Eclipse Public License v. 2.0 which is available at
161 * http://www.eclipse.org/legal/epl-2.0, or the Eclipse Distribution License
162 * v. 1.0 which is available at
163 * http://www.eclipse.org/org/documents/edl-v10.php.
164 *
165 * SPDX-License-Identifier: EPL-2.0 OR BSD-3-Clause
166 */
167#ifndef DDSRT_TYPES_H
168#define DDSRT_TYPES_H
169
170#include <stdbool.h>
171#include <stdint.h>
172
173#if _WIN32
174/*
175 * Copyright(c) 2006 to 2018 ADLINK Technology Limited and others
176 *
177 * This program and the accompanying materials are made available under the
178 * terms of the Eclipse Public License v. 2.0 which is available at
179 * http://www.eclipse.org/legal/epl-2.0, or the Eclipse Distribution License
180 * v. 1.0 which is available at
181 * http://www.eclipse.org/org/documents/edl-v10.php.
182 *
183 * SPDX-License-Identifier: EPL-2.0 OR BSD-3-Clause
184 */
185#ifndef DDSRT_TYPES_WINDOWS_H
186#define DDSRT_TYPES_WINDOWS_H
187
188#ifndef WIN32_LEAN_AND_MEAN
189#define WIN32_LEAN_AND_MEAN
190#endif
191
192#ifndef NOMINMAX
193#define NOMINMAX
194#endif
195
196#include <windows.h>
197#include <VersionHelpers.h>
198#include <stdint.h>
199#include <inttypes.h>
200#include <wchar.h>
201
202typedef SSIZE_T ssize_t;
203
204#endif /* DDSRT_TYPES_WINDOWS_H */
205
206#elif __VXWORKS__
207/*
208 * Copyright(c) 2006 to 2018 ADLINK Technology Limited and others
209 *
210 * This program and the accompanying materials are made available under the
211 * terms of the Eclipse Public License v. 2.0 which is available at
212 * http://www.eclipse.org/legal/epl-2.0, or the Eclipse Distribution License
213 * v. 1.0 which is available at
214 * http://www.eclipse.org/org/documents/edl-v10.php.
215 *
216 * SPDX-License-Identifier: EPL-2.0 OR BSD-3-Clause
217 */
218#ifndef DDSRT_TYPES_VXWORKS_H
219#define DDSRT_TYPES_VXWORKS_H
220
221#if defined(_WRS_KERNEL)
222/* inttypes.h does not exist in VxWorks DKM. */
223#include <st_inttypes.h>
224#include <cafe/inttypes.h>
225/* The above inttypes includes don't seem to define uintmax_t &c. */
226#ifdef _WRS_CONFIG_LP64 /* Used in cafe/inttypes.h too. */
227#define _PFX_64 "l"
228typedef unsigned long int       uintmax_t;
229#else
230#define _PFX_64 "ll"
231typedef unsigned long long int  uintmax_t;
232#endif
233
234/* Not a complete replacement for inttypes.h (yet); No SCN/PRI?LEAST/FAST/etc. */
235#define PRId8      "d"
236#define PRId16     "d"
237#define PRId32     "d"
238#define PRId64     _PFX_64 "d"
239
240#define PRIi8      "i"
241#define PRIi16     "i"
242#define PRIi32     "i"
243#define PRIi64     _PFX_64 "i"
244
245#define PRIo8      "o"
246#define PRIo16     "o"
247#define PRIo32     "o"
248#define PRIo64     _PFX_64 "o"
249
250#define PRIu8      "u"
251#define PRIu16     "u"
252#define PRIu32     "u"
253#define PRIu64     _PFX_64 "u"
254
255#define PRIx8      "x"
256#define PRIx16     "x"
257#define PRIx32     "x"
258
259#define PRIX8      "X"
260#define PRIX16     "X"
261#define PRIX32     "X"
262#define PRIX64     _PFX_64 "X"
263
264#define PRIdMAX    _PFX_64 "d"
265#define PRIiMAX    _PFX_64 "i"
266#define PRIoMAX    _PFX_64 "o"
267#define PRIuMAX    _PFX_64 "u"
268#define PRIxMAX    _PFX_64 "x"
269#define PRIXMAX    _PFX_64 "X"
270
271#define PRIdPTR    _PFX_64 "d"
272#define PRIiPTR    _PFX_64 "i"
273#define PRIoPTR    _PFX_64 "o"
274#define PRIXPTR    _PFX_64 "X"
275
276#else /* _WRS_KERNEL */
277#include <inttypes.h>
278#endif /* _WRS_KERNEL */
279
280#endif /* DDSRT_TYPES_VXWORKS_H */
281
282#else
283/*
284 * Copyright(c) 2006 to 2018 ADLINK Technology Limited and others
285 *
286 * This program and the accompanying materials are made available under the
287 * terms of the Eclipse Public License v. 2.0 which is available at
288 * http://www.eclipse.org/legal/epl-2.0, or the Eclipse Distribution License
289 * v. 1.0 which is available at
290 * http://www.eclipse.org/org/documents/edl-v10.php.
291 *
292 * SPDX-License-Identifier: EPL-2.0 OR BSD-3-Clause
293 */
294#ifndef DDSRT_TYPES_POSIX_H
295#define DDSRT_TYPES_POSIX_H
296
297#include <stdint.h>
298#include <inttypes.h>
299#if defined(__IAR_SYSTEMS_ICC__)
300typedef long int ssize_t;
301#else
302#include <unistd.h>
303#endif
304
305#endif /* DDSRT_TYPES_POSIX_H */
306
307#endif
308
309#define PRIdSIZE "zd"
310#define PRIuSIZE "zu"
311#define PRIxSIZE "zx"
312
313#endif /* DDSRT_TYPES_H */
314
315#if defined (__cplusplus)
316extern "C" {
317#endif
318
319/*
320  Times are represented using a 64-bit signed integer, encoding
321  nanoseconds since the epoch. Considering the nature of these
322  systems, one would best use TAI, International Atomic Time, rather
323  than something UTC, but availability may be limited.
324
325  Valid times are non-negative and times up to 2**63-2 can be
326  represented. 2**63-1 is defined to represent, essentially, "never".
327  This is good enough for a couple of centuries.
328*/
329
330/** Absolute Time definition */
331typedef int64_t dds_time_t;
332
333/** Relative Time definition in nanoseconds */
334typedef int64_t dds_duration_t;
335
336/** @name Macro definition for time units in nanoseconds.
337  @{**/
338#define DDS_NSECS_IN_SEC INT64_C(1000000000)
339#define DDS_NSECS_IN_MSEC INT64_C(1000000)
340#define DDS_NSECS_IN_USEC INT64_C(1000)
341/** @}*/
342
343/** @name Infinite timeout for indicate absolute time */
344#define DDS_NEVER ((dds_time_t) INT64_MAX)
345
346/** @name Infinite timeout for relative time */
347#define DDS_INFINITY ((dds_duration_t) INT64_MAX)
348
349/** @name Invalid time value for assigning to time output when something goes wrong */
350#define DDS_TIME_INVALID ((dds_time_t) INT64_MIN)
351
352/** @name Invalid duration value */
353#define DDS_DURATION_INVALID ((dds_duration_t) INT64_MIN)
354
355/** @name Macro definition for time conversion to nanoseconds
356  @{**/
357#define DDS_SECS(n) ((n) * DDS_NSECS_IN_SEC)
358#define DDS_MSECS(n) ((n) * DDS_NSECS_IN_MSEC)
359#define DDS_USECS(n) ((n) * DDS_NSECS_IN_USEC)
360/** @}*/
361
362typedef struct {
363  dds_time_t v;
364} ddsrt_mtime_t;
365
366typedef struct {
367  dds_time_t v;
368} ddsrt_wctime_t;
369
370typedef struct {
371  dds_time_t v;
372} ddsrt_etime_t;
373
374#define DDSRT_MTIME_NEVER ((ddsrt_mtime_t) { DDS_NEVER })
375#define DDSRT_WCTIME_NEVER ((ddsrt_wctime_t) { DDS_NEVER })
376#define DDSRT_ETIME_NEVER ((ddsrt_etime_t) { DDS_NEVER })
377#define DDSRT_WCTIME_INVALID ((ddsrt_wctime_t) { INT64_MIN })
378
379/**
380 * @brief Get the current time in nanoseconds since the UNIX Epoch.
381 *
382 * @returns Current time.
383 */
384DDS_EXPORT dds_time_t dds_time(void);
385
386/**
387 * @brief Suspend execution of calling thread until relative time n elapsed.
388 *
389 * Execution is suspended for n nanoseconds. Should the call be interrupted,
390 * the call is re-entered with the remaining time.
391 *
392 * @param[in]  reltime  Relative time in nanoseconds.
393 */
394DDS_EXPORT void dds_sleepfor (dds_duration_t reltime);
395
396/**
397 * @brief Get the current time in nanoseconds since the UNIX Epoch.  Identical
398 * to (ddsrt_wctime_t){dds_time()}
399 *
400 * @returns Curren time.
401 */
402DDS_EXPORT ddsrt_wctime_t ddsrt_time_wallclock(void);
403
404/**
405 * @brief Get high resolution, monotonic time.
406 *
407 * The monotonic clock is a clock with near real-time progression and can be
408 * used when a high-resolution time is needed without the need for it to be
409 * related to the wall-clock. The resolution of the clock is typically the
410 * highest available on the platform.
411 *
412 * The clock is not guaranteed to be strictly monotonic, but on most common
413 * platforms it will be (based on performance-counters or HPET's).
414 *
415 * @returns Monotonic time if available, otherwise real time.
416 */
417DDS_EXPORT ddsrt_mtime_t ddsrt_time_monotonic(void);
418
419/**
420 * @brief Get high resolution, elapsed (and thus monotonic) time since some
421 * fixed unspecified past time.
422 *
423 * The elapsed time clock is a clock with near real-time progression and can be
424 * used when a high-resolution suspend-aware monotonic clock is needed, without
425 * having to deal with the complications of discontinuities if for example the
426 * time is changed. The fixed point from which the elapsed time is returned is
427 * not guaranteed to be fixed over reboots of the system.
428 *
429 * @returns Elapsed time if available, otherwise return monotonic time.
430 */
431DDS_EXPORT ddsrt_etime_t ddsrt_time_elapsed(void);
432
433/**
434 * @brief Convert time into a human readable string in RFC 3339 format.
435 *
436 * Converts the calender time into a null-terminated string in RFC 3339 format.
437 * e.g. "2014-10-24 15:32:27-04:00".
438 *
439 * UTC offset is omitted if time-zone information is unknown.
440 *
441 * @param[in]  abstime  Time in nanoseconds since UNIX Epoch.
442 * @param[in]  str      String to write human readable timestamp to.
443 * @param[in]  size     Number of bytes available in @str.
444 *
445 * @returns Number of bytes written (excluding terminating null byte). The
446 *          string is truncated if str is not sufficiently large enough. Thus,
447 *          a return value of size or more means the output was truncated.
448 */
449#define DDSRT_RFC3339STRLEN (25)
450
451DDS_EXPORT size_t ddsrt_ctime(dds_time_t abstime, char *str, size_t size);
452
453/**
454 * @brief Calculate a time given an offset time and a duration.
455 *
456 * Negative time can become positive by adding a large enough duration, of
457 * course a positive time can become negative given a large enough negative
458 * duration.
459 *
460 * @param[in]  abstime  Timestamp in nanoseconds since UNIX Epoch.
461 * @param[in]  reltime  Relative time in nanoseconds.
462 *
463 * @returns A timestamp in nanoseconds since UNIX Epoch.
464 */
465inline dds_time_t ddsrt_time_add_duration(dds_time_t abstime, dds_duration_t reltime)
466{
467  assert(abstime >= 0);
468  assert(reltime >= 0);
469  return (reltime >= DDS_NEVER - abstime ? DDS_NEVER : abstime + reltime);
470}
471
472/**
473 * @brief Calculate a monotonic time given an offset time and a duration.
474 *
475 * Negative time can become positive by adding a large enough duration, of
476 * course a positive time can become negative given a large enough negative
477 * duration.
478 *
479 * @param[in]  abstime  Timestamp in nanoseconds since UNIX Epoch.
480 * @param[in]  reltime  Relative time in nanoseconds.
481 *
482 * @returns A timestamp in nanoseconds since UNIX Epoch.
483 */
484inline ddsrt_mtime_t ddsrt_mtime_add_duration(ddsrt_mtime_t abstime, dds_duration_t reltime) {
485  ddsrt_mtime_t t;
486  t.v = ddsrt_time_add_duration (abstime.v, reltime);
487  return t;
488}
489
490/**
491 * @brief Calculate a wall-clock time given an offset time and a duration.
492 *
493 * Negative time can become positive by adding a large enough duration, of
494 * course a positive time can become negative given a large enough negative
495 * duration.
496 *
497 * @param[in]  abstime  Timestamp in nanoseconds since UNIX Epoch.
498 * @param[in]  reltime  Relative time in nanoseconds.
499 *
500 * @returns A timestamp in nanoseconds since UNIX Epoch.
501 */
502inline ddsrt_wctime_t ddsrt_wctime_add_duration(ddsrt_wctime_t abstime, dds_duration_t reltime) {
503  ddsrt_wctime_t t;
504  t.v = ddsrt_time_add_duration (abstime.v, reltime);
505  return t;
506}
507
508/**
509 * @brief Calculate an elapsed time given an offset time and a duration.
510 *
511 * Negative time can become positive by adding a large enough duration, of
512 * course a positive time can become negative given a large enough negative
513 * duration.
514 *
515 * @param[in]  abstime  Timestamp in nanoseconds since UNIX Epoch.
516 * @param[in]  reltime  Relative time in nanoseconds.
517 *
518 * @returns A timestamp in nanoseconds since UNIX Epoch.
519 */
520inline ddsrt_etime_t ddsrt_etime_add_duration(ddsrt_etime_t abstime, dds_duration_t reltime) {
521  ddsrt_etime_t t;
522  t.v = ddsrt_time_add_duration (abstime.v, reltime);
523  return t;
524}
525
526#if _WIN32
527/**
528 * @brief Convert a relative time to microseconds rounding up.
529 *
530 * @param[in]  reltime  Relative time to convert.
531 *
532 * @returns INFINITE if @reltime was @DDS_INIFINITY, relative time converted to
533 *          microseconds otherwise.
534 */
535inline DWORD
536ddsrt_duration_to_msecs_ceil(dds_duration_t reltime)
537{
538  if (reltime == DDS_INFINITY) {
539    return INFINITE;
540  } else if (reltime > 0) {
541    assert(INFINITE < (DDS_INFINITY / DDS_NSECS_IN_MSEC));
542    dds_duration_t max_nsecs = (INFINITE - 1) * DDS_NSECS_IN_MSEC;
543
544    if (reltime < (max_nsecs - (DDS_NSECS_IN_MSEC - 1))) {
545      reltime += (DDS_NSECS_IN_MSEC - 1);
546    } else {
547      reltime = max_nsecs;
548    }
549
550    return (DWORD)(reltime / DDS_NSECS_IN_MSEC);
551  }
552
553  return 0;
554}
555#endif
556
557/**
558 * @brief Convert monotonic time seconds & microseconds
559 *
560 * @param[in]   t     Monotonic time to convert
561 * @param[out]  sec   Seconds part
562 * @param[out]  usec  Microseconds part
563 */
564DDS_EXPORT void ddsrt_mtime_to_sec_usec (int32_t * __restrict sec, int32_t * __restrict usec, ddsrt_mtime_t t);
565
566/**
567 * @brief Convert wall-clock time seconds & microseconds
568 *
569 * @param[in]   t     Wall-clock time to convert
570 * @param[out]  sec   Seconds part
571 * @param[out]  usec  Microseconds part
572 */
573DDS_EXPORT void ddsrt_wctime_to_sec_usec (int32_t * __restrict sec, int32_t * __restrict usec, ddsrt_wctime_t t);
574
575/**
576 * @brief Convert elapsed time seconds & microseconds
577 *
578 * @param[in]   t     Elasped time to convert
579 * @param[out]  sec   Seconds part
580 * @param[out]  usec  Microseconds part
581 */
582DDS_EXPORT void ddsrt_etime_to_sec_usec (int32_t * __restrict sec, int32_t * __restrict usec, ddsrt_etime_t t);
583
584#if defined(__cplusplus)
585}
586#endif
587
588#if DDSRT_WITH_FREERTOS
589/*
590 * Copyright(c) 2006 to 2018 ADLINK Technology Limited and others
591 *
592 * This program and the accompanying materials are made available under the
593 * terms of the Eclipse Public License v. 2.0 which is available at
594 * http://www.eclipse.org/legal/epl-2.0, or the Eclipse Distribution License
595 * v. 1.0 which is available at
596 * http://www.eclipse.org/org/documents/edl-v10.php.
597 *
598 * SPDX-License-Identifier: EPL-2.0 OR BSD-3-Clause
599 */
600#ifndef DDSRT_TIME_FREERTOS_H
601#define DDSRT_TIME_FREERTOS_H
602
603#include <assert.h>
604#include <FreeRTOS.h>
605
606#if defined (__cplusplus)
607extern "C" {
608#endif
609
610#define DDSRT_NSECS_PER_TICK (DDS_NSECS_IN_SEC / configTICK_RATE_HZ)
611
612inline TickType_t
613ddsrt_duration_to_ticks_ceil(
614  dds_duration_t reltime)
615{
616  TickType_t ticks = 0;
617
618  assert(portMAX_DELAY > configTICK_RATE_HZ);
619
620  if (reltime == DDS_INFINITY) {
621    ticks = portMAX_DELAY;
622  } else if (reltime > 0) {
623    dds_duration_t max_nsecs =
624      (DDS_INFINITY / DDSRT_NSECS_PER_TICK < portMAX_DELAY
625        ? DDS_INFINITY - 1 : portMAX_DELAY * DDSRT_NSECS_PER_TICK);
626
627    if (reltime > max_nsecs - (DDSRT_NSECS_PER_TICK - 1)) {
628      ticks = portMAX_DELAY;
629    } else {
630      ticks = (TickType_t)((reltime + (DDSRT_NSECS_PER_TICK - 1)) / DDSRT_NSECS_PER_TICK);
631    }
632  }
633
634  return ticks;
635}
636
637#if defined (__cplusplus)
638}
639#endif
640
641#endif /* DDSRT_TIME_FREERTOS_H */
642
643#endif
644
645#endif /* DDSRT_TIME_H */
646
647#ifndef DDS_RETCODE_H
648#define DDS_RETCODE_H
649
650#include <stdint.h>
651
652#if defined (__cplusplus)
653extern "C" {
654#endif
655
656typedef int32_t dds_return_t;
657
658/*
659  State is unchanged following a function call returning an error
660  other than UNSPECIFIED, OUT_OF_RESOURCES and ALREADY_DELETED.
661
662  Error handling functions. Three components to returned int status value.
663
664  1 - The DDS_ERR_xxx error number
665  2 - The file identifier
666  3 - The line number
667
668  All functions return >= 0 on success, < 0 on error
669*/
670
671/**
672 * @name DDS_Error_Type
673 * @{
674 */
675#define DDS_RETCODE_OK                   (0) /**< Success */
676#define DDS_RETCODE_ERROR                (-1) /**< Non specific error */
677#define DDS_RETCODE_UNSUPPORTED          (-2) /**< Feature unsupported */
678#define DDS_RETCODE_BAD_PARAMETER        (-3) /**< Bad parameter value */
679#define DDS_RETCODE_PRECONDITION_NOT_MET (-4) /**< Precondition for operation not met */
680#define DDS_RETCODE_OUT_OF_RESOURCES     (-5) /**< When an operation fails because of a lack of resources */
681#define DDS_RETCODE_NOT_ENABLED          (-6) /**< When a configurable feature is not enabled */
682#define DDS_RETCODE_IMMUTABLE_POLICY     (-7) /**< When an attempt is made to modify an immutable policy */
683#define DDS_RETCODE_INCONSISTENT_POLICY  (-8) /**< When a policy is used with inconsistent values */
684#define DDS_RETCODE_ALREADY_DELETED      (-9) /**< When an attempt is made to delete something more than once */
685#define DDS_RETCODE_TIMEOUT              (-10) /**< When a timeout has occurred */
686#define DDS_RETCODE_NO_DATA              (-11) /**< When expected data is not provided */
687#define DDS_RETCODE_ILLEGAL_OPERATION    (-12) /**< When a function is called when it should not be */
688#define DDS_RETCODE_NOT_ALLOWED_BY_SECURITY (-13) /**< When credentials are not enough to use the function */
689
690/* Extended return codes are not in the DDS specification and are meant
691   exclusively for internal use and must not be returned by the C API. */
692#define DDS_XRETCODE_BASE (-50)
693#define DDS_XRETCODE(x) (DDS_XRETCODE_BASE - (x))
694
695/** Requested resource is busy */
696#define DDS_RETCODE_IN_PROGRESS         DDS_XRETCODE(1)
697/** Resource unavailable, try again */
698#define DDS_RETCODE_TRY_AGAIN           DDS_XRETCODE(2)
699/** Operation was interrupted */
700#define DDS_RETCODE_INTERRUPTED         DDS_XRETCODE(3)
701/** Permission denied */
702#define DDS_RETCODE_NOT_ALLOWED         DDS_XRETCODE(4)
703/** Host not found */
704#define DDS_RETCODE_HOST_NOT_FOUND      DDS_XRETCODE(5)
705/** Network is not available */
706#define DDS_RETCODE_NO_NETWORK          DDS_XRETCODE(6)
707/** Connection is not available */
708#define DDS_RETCODE_NO_CONNECTION       DDS_XRETCODE(7)
709/* Host not reachable is used to indicate that a connection was refused
710   (ECONNREFUSED), reset by peer (ECONNRESET) or that a host or network cannot
711   be reached (EHOSTUNREACH, ENETUNREACH). Generally all system errors that
712   indicate a connection cannot be made or that a message cannot be delivered,
713   map onto host not reachable. */
714/** Not enough space available */
715#define DDS_RETCODE_NOT_ENOUGH_SPACE    DDS_XRETCODE(8)
716/* Not enough space is used to indicate there is not enough buffer space to
717   read a message from the network (i.e. EMSGSIZE), but is also used to
718   indicate there is not enough space left on a device, etc. */
719/** Result too large */
720#define DDS_RETCODE_OUT_OF_RANGE        DDS_XRETCODE(9)
721/** Not found */
722#define DDS_RETCODE_NOT_FOUND           DDS_XRETCODE(10)
723/**
724 * @}
725 */
726
727/**
728 * @brief Takes the error value and outputs a string corresponding to it.
729 *
730 * @param[in]  ret  Error value to be converted to a string
731 *
732 * @returns  String corresponding to the error value
733 */
734DDS_EXPORT const char *dds_strretcode(dds_return_t ret);
735
736#if defined (__cplusplus)
737}
738#endif
739
740#endif /* DDS_RETCODE_H */
741
742/*
743 * Copyright(c) 2006 to 2018 ADLINK Technology Limited and others
744 *
745 * This program and the accompanying materials are made available under the
746 * terms of the Eclipse Public License v. 2.0 which is available at
747 * http://www.eclipse.org/legal/epl-2.0, or the Eclipse Distribution License
748 * v. 1.0 which is available at
749 * http://www.eclipse.org/org/documents/edl-v10.php.
750 *
751 * SPDX-License-Identifier: EPL-2.0 OR BSD-3-Clause
752 */
753
754/** @file
755 *
756 * @brief DDS C Logging API
757 *
758 * This header file defines the public API for logging and controlling logging
759 * in the DDS C language binding.
760 */
761#ifndef DDS_LOG_H
762#define DDS_LOG_H
763
764#include <stdarg.h>
765#include <stdint.h>
766#include <stdio.h>
767
768/*
769 * Copyright(c) 2006 to 2018 ADLINK Technology Limited and others
770 *
771 * This program and the accompanying materials are made available under the
772 * terms of the Eclipse Public License v. 2.0 which is available at
773 * http://www.eclipse.org/legal/epl-2.0, or the Eclipse Distribution License
774 * v. 1.0 which is available at
775 * http://www.eclipse.org/org/documents/edl-v10.php.
776 *
777 * SPDX-License-Identifier: EPL-2.0 OR BSD-3-Clause
778 */
779#ifndef DDSRT_ATTRIBUTES_H
780#define DDSRT_ATTRIBUTES_H
781
782#if __GNUC__
783# define ddsrt_gnuc (__GNUC__ * 10000 + __GNUC_MINOR__ * 100 + __GNUC_PATCHLEVEL__)
784#else
785# define ddsrt_gnuc (0)
786#endif
787
788#if __clang__
789# define ddsrt_clang (__clang_major__ * 10000 + __clang_minor__ * 100 + __clang_patchlevel__)
790#else
791# define ddsrt_clang (0)
792#endif
793
794#ifdef __SUNPRO_C
795# define __attribute__(x)
796#endif
797
798#if defined(__has_attribute)
799# define ddsrt_has_attribute(params) __has_attribute(params)
800#elif ddsrt_gnuc
801# define ddsrt_has_attribute(params) (1) /* GCC < 5 */
802#else
803# define ddsrt_has_attribute(params) (0)
804#endif
805
806#if ddsrt_has_attribute(malloc)
807# define ddsrt_attribute_malloc __attribute__ ((__malloc__))
808#else
809# define ddsrt_attribute_malloc
810#endif
811
812#if ddsrt_has_attribute(unused)
813# define ddsrt_attribute_unused __attribute__((__unused__))
814#else
815# define ddsrt_attribute_unused
816#endif
817
818#if ddsrt_has_attribute(noreturn)
819# define ddsrt_attribute_noreturn __attribute__ ((__noreturn__))
820#else
821# define ddsrt_attribute_noreturn
822#endif
823
824#if ddsrt_has_attribute(nonnull)
825# define ddsrt_nonnull(params) __attribute__ ((__nonnull__ params))
826# define ddsrt_nonnull_all __attribute__ ((__nonnull__))
827#else
828# define ddsrt_nonnull(params)
829# define ddsrt_nonnull_all
830#endif
831
832#if ddsrt_has_attribute(returns_nonnull) && (ddsrt_clang || ddsrt_gnuc >= 40900)
833# define ddsrt_attribute_returns_nonnull __attribute__ ((__returns_nonnull__))
834#else
835# define ddsrt_attribute_returns_nonnull
836#endif
837
838/* GCC <= 4.2.4 has the attribute, but warns that it ignores it. */
839#if !ddsrt_has_attribute(alloc_size) || (ddsrt_gnuc <= 40204)
840# define ddsrt_attribute_alloc_size(params)
841#else
842# define ddsrt_attribute_alloc_size(params) __attribute__ ((__alloc_size__ params))
843#endif
844
845#if ddsrt_has_attribute(const)
846# define ddsrt_attribute_const __attribute__ ((__const__))
847#else
848# define ddsrt_attribute_const
849#endif
850
851#if ddsrt_has_attribute(pure)
852# define ddsrt_attribute_pure __attribute__ ((__pure__))
853#else
854# define ddsrt_attribute_pure
855#endif
856
857#if ddsrt_has_attribute(format)
858# define ddsrt_attribute_format(params) __attribute__ ((__format__ params))
859#else
860# define ddsrt_attribute_format(params)
861#endif
862
863#if ddsrt_has_attribute(warn_unused_result)
864# define ddsrt_attribute_warn_unused_result __attribute__ ((__warn_unused_result__))
865#else
866# define ddsrt_attribute_warn_unused_result
867#endif
868
869#if ddsrt_has_attribute(assume_aligned)
870# define ddsrt_attribute_assume_aligned(params) __attribute__ ((__assume_aligned__ params))
871#else
872# define ddsrt_attribute_assume_aligned(params)
873#endif
874
875#if ddsrt_has_attribute(packed)
876# define ddsrt_attribute_packed __attribute__ ((__packed__))
877#else
878# define ddsrt_attribute_packed
879#endif
880
881#if ddsrt_has_attribute(no_sanitize)
882# define ddsrt_attribute_no_sanitize(params) __attribute__ ((__no_sanitize__ params))
883#else
884# define ddsrt_attribute_no_sanitize(params)
885#endif
886
887#if defined(__has_feature)
888# define ddsrt_has_feature_thread_sanitizer __has_feature(thread_sanitizer)
889#else
890# define ddsrt_has_feature_thread_sanitizer 0
891#endif
892
893#endif /* DDSRT_ATTRIBUTES_H */
894
895#if defined (__cplusplus)
896extern "C" {
897#endif
898
899/** @defgroup log_categories Convenience log category definitions.
900 *
901 * These defines expand into numeric values that can be ORed together to
902 * specify messages of which categories must be passed to the respective sinks.
903 *
904 * Every category other than DDS_LC_FATAL, DDS_LC_ERROR, DDS_LC_WARNING and
905 * DDS_LC_INFO automatically falls into the trace category.
906 *
907 * @{
908 */
909/** Fatal error condition. Immediate abort on sink return. */
910#define DDS_LC_FATAL (1u)
911/** Error condition. */
912#define DDS_LC_ERROR (2u)
913/** Warning condition. */
914#define DDS_LC_WARNING (4u)
915/** Informational message. */
916#define DDS_LC_INFO (8u)
917/** Debug/trace messages related to configuration settings. */
918#define DDS_LC_CONFIG (16u)
919/** Debug/trace messages related to node discovery. */
920#define DDS_LC_DISCOVERY (32u)
921/** Currently unused. */
922#define DDS_LC_DATA (64u)
923/** Debug/trace messages for which no specialized category exists (yet). */
924#define DDS_LC_TRACE (128u)
925/** Debug/trace messages related to receive administration. */
926#define DDS_LC_RADMIN (256u)
927/** Debug/trace messages related to timing. */
928#define DDS_LC_TIMING (512u)
929/** Debug/trace messages related to send administration. */
930#define DDS_LC_TRAFFIC (1024u)
931/** Currently unused. */
932#define DDS_LC_TOPIC (2048u)
933/** Debug/trace messages related to TCP communication. */
934#define DDS_LC_TCP (4096u)
935/** Debug/trace messages related to parameter list processing. */
936#define DDS_LC_PLIST (8192u)
937/** Debug/trace messages related to the writer history cache. */
938#define DDS_LC_WHC (16384u)
939/** Debug/trace messages related to throttling. */
940#define DDS_LC_THROTTLE (32768u)
941/** Reader history cache. */
942#define DDS_LC_RHC (65536u)
943/** Include content in traces. */
944#define DDS_LC_CONTENT (131072u)
945/** All common trace categories. */
946#define DDS_LC_ALL \
947    (DDS_LC_FATAL | DDS_LC_ERROR | DDS_LC_WARNING | DDS_LC_INFO | \
948     DDS_LC_CONFIG | DDS_LC_DISCOVERY | DDS_LC_DATA | DDS_LC_TRACE | \
949     DDS_LC_TIMING | DDS_LC_TRAFFIC | DDS_LC_TCP | DDS_LC_THROTTLE | \
950     DDS_LC_CONTENT)
951/** @}*/
952
953#define DDS_LOG_MASK \
954    (DDS_LC_FATAL | DDS_LC_ERROR | DDS_LC_WARNING | DDS_LC_INFO)
955
956#define DDS_TRACE_MASK \
957    (~DDS_LOG_MASK)
958
959/** Structure with log message and meta data passed to callbacks. */
960typedef struct {
961  /** Log category the message falls into. */
962  uint32_t priority;
963  /** Log domain id, UINT32_MAX is global. */
964  uint32_t domid;
965  /** Filename where message was generated. */
966  const char *file;
967  /** Line number in file where message was generated. */
968  uint32_t line;
969  /** Name of function message where message was generated. */
970  const char *function;
971  /** Log message. */
972  const char *message;
973  /** Size of log message. */
974  size_t size;
975  /** Default log message header length */
976  size_t hdrsize;
977} dds_log_data_t;
978
979/** Function signature that log and trace callbacks must adhere too. */
980typedef void (*dds_log_write_fn_t) (void *, const dds_log_data_t *);
981
982/** Semi-opaque type for log/trace configuration. */
983struct ddsrt_log_cfg_common {
984  /** Mask for testing whether the xLOG macro should forward to the
985      function (and so incur the cost of constructing the parameters).
986      Messages in DDS_LOG_MASK are rare, so the overhead of calling
987      the function and then dropping the message is not an issue, unlike
988      for messages in DDS_TRACE_MASK. */
989  uint32_t mask;
990
991  /** The actual configured trace mask */
992  uint32_t tracemask;
993
994  /** Domain id for reporting; UINT32_MAX = no domain */
995  uint32_t domid;
996};
997
998typedef struct ddsrt_log_cfg {
999  struct ddsrt_log_cfg_common c;
1000  union {
1001    dds_log_write_fn_t fnptr;
1002    void *ptr;
1003    uint32_t u32;
1004    unsigned char pad[72];
1005  } u;
1006} ddsrt_log_cfg_t;
1007
1008DDS_EXPORT extern uint32_t *const dds_log_mask;
1009
1010/**
1011 * @brief Get currently enabled log and trace categories.
1012 *
1013 * @returns A uint32_t with enabled categories set.
1014 */
1015inline uint32_t
1016dds_get_log_mask(void)
1017{
1018    return *dds_log_mask;
1019}
1020
1021/**
1022 * @brief Set enabled log and trace categories.
1023 *
1024 * @param[in]  cats  Log and trace categories to enable.
1025 */
1026DDS_EXPORT void
1027dds_set_log_mask(
1028    uint32_t cats);
1029
1030/**
1031 * @private
1032 */
1033DDS_EXPORT void
1034dds_set_log_file(
1035    FILE *file);
1036
1037/**
1038 * @private
1039 */
1040DDS_EXPORT void
1041dds_set_trace_file(
1042    FILE *file);
1043
1044/**
1045 * @brief Register callback to receive log messages
1046 *
1047 * Callbacks registered to handle log messages will receive messages of type
1048 * info, warning, error and fatal. Messages that fall into the trace category
1049 * will never be delivered to the callback.
1050 *
1051 * This operation is synchronous and only returns once the operation is
1052 * registered with all threads. Meaning that neither callback or userdata will
1053 * be referenced by the DDS stack on return.
1054 *
1055 * @param[in]  callback  Function pointer matching dds_log_write_fn signature
1056 *                       or a null pointer to restore the default sink.
1057 * @param[in]  userdata  User specified data passed along with each invocation
1058 *                       of callback.
1059 */
1060DDS_EXPORT void
1061dds_set_log_sink(
1062    dds_log_write_fn_t callback,
1063    void *userdata);
1064
1065/**
1066 * @brief Register callback to receive trace messages
1067 *
1068 * Callbacks registered to handle trace messages will receive messages of type
1069 * info, warning, error and fatal as well as all message types that fall into
1070 * the trace category depending on the log mask.
1071 *
1072 * This operation is synchronous and only returns once the operation is
1073 * registered with all threads. Meaning that neither callback or
1074 * userdata will be referenced by the DDS stack on return.
1075 *
1076 * @param[in]  callback  Function pointer matching dds_log_write_fn_t signature
1077 *                       or a null pointer to restore the default sink.
1078 * @param[in]  userdata  User specified data passed along with each invocation
1079 *                       of callback.
1080 */
1081DDS_EXPORT void
1082dds_set_trace_sink(
1083    dds_log_write_fn_t callback,
1084    void *userdata);
1085
1086/**
1087 * @brief Initialize a struct ddsrt_log_cfg for use with dds_log_cfg
1088 *
1089 * Callbacks registered to handle log messages will receive messages of type
1090 * info, warning, error and fatal. Messages that fall into the trace category
1091 * will never be delivered to the callback.
1092 *
1093 * Callbacks registered to handle trace messages will receive messages of type
1094 * info, warning, error and fatal as well as all message types that fall into
1095 * the trace category depending on the log mask.
1096 *
1097 * This operation is synchronous and only returns once the operation is
1098 * registered with all threads. Meaning that neither callback or
1099 * userdata will be referenced by the DDS stack on return.
1100 *
1101 * @param[out] cfg            On return, initialised to make dds_log_cfg invoked
1102 *                            with this config object behave as specified by the
1103 *                            other parameters.
1104 * @param[in]  domid          Numerical identifier in log/trace, UINT32_MAX is
1105 *                            reserved for global logging.
1106 * @param[in]  tracemask      Mask determining which traces should be written.
1107 * @param[in]  log_fp         File for default sink.
1108 * @param[in]  trace_fp       File for default sink.
1109 */
1110DDS_EXPORT void
1111dds_log_cfg_init(
1112    struct ddsrt_log_cfg *cfg,
1113    uint32_t domid,
1114    uint32_t tracemask,
1115    FILE *log_fp,
1116    FILE *trace_fp);
1117
1118/**
1119 * @brief Write a log or trace message for a specific logging configuraiton
1120 * (categories, id, sinks).
1121 *
1122 * Direct use of #dds_log is discouraged. Use #DDS_CINFO, #DDS_CWARNING,
1123 * #DDS_CERROR, #DDS_CTRACE or #DDS_CLOG instead.
1124 */
1125DDS_EXPORT void
1126dds_log_cfg(
1127    const struct ddsrt_log_cfg *cfg,
1128    uint32_t prio,
1129    const char *file,
1130    uint32_t line,
1131    const char *func,
1132    const char *fmt,
1133    ...)
1134  ddsrt_attribute_format((__printf__, 6, 7));
1135
1136/**
1137 * @brief Write a log or trace message to the global configuration but with
1138 * specific domain (intended solely for use during domain start-up, while
1139 * the domain-specific logging/tracing hasn't been set yet).
1140 *
1141 * Write a log or trace message to one (or both) of the currently active sinks.
1142 *
1143 * Direct use of #dds_log_id is discouraged. Use #DDS_ILOG instead.
1144 */
1145DDS_EXPORT void
1146dds_log_id(
1147    uint32_t prio,
1148    uint32_t domid,
1149    const char *file,
1150    uint32_t line,
1151    const char *func,
1152    const char *fmt,
1153    ...)
1154  ddsrt_attribute_format((__printf__, 6, 7));
1155
1156/**
1157 * @brief Write a log or trace message to the global log/trace.
1158 *
1159 * Write a log or trace message to one (or both) of the currently active sinks.
1160 *
1161 * Direct use of #dds_log is discouraged. Use #DDS_INFO, #DDS_WARNING,
1162 * #DDS_ERROR, #DDS_FATAL or #DDS_LOG instead.
1163 */
1164DDS_EXPORT void
1165dds_log(
1166    uint32_t prio,
1167    const char *file,
1168    uint32_t line,
1169    const char *func,
1170    const char *fmt,
1171    ...)
1172  ddsrt_attribute_format((__printf__, 5, 6));
1173
1174/**
1175 * @brief Undecorated function name of the current function.
1176 *
1177 * Behavior of DDS_FUNCTION outside a function is undefined. Note that
1178 * implementations differ across compilers and compiler versions. It might be
1179 * implemented as either a string literal or a constant variable.
1180 */
1181#if defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 199901)
1182#   define DDS_FUNCTION __func__
1183#elif defined(__cplusplus) && (__cplusplus >= 201103)
1184#   define DDS_FUNCTION __func__
1185#elif defined(__GNUC__)
1186#   define DDS_FUNCTION __FUNCTION__
1187#elif defined(__clang__)
1188#   define DDS_FUNCTION __FUNCTION__
1189#elif defined(__ghs__)
1190#   define DDS_FUNCTION __FUNCTION__
1191#elif (defined(__SUNPRO_C) || defined(__SUNPRO_CC))
1192/* Solaris Studio had support for __func__ before it supported __FUNCTION__.
1193   Compiler flag -features=extensions is required on older versions. */
1194#   define DDS_FUNCTION __func__
1195#elif defined(__FUNCTION__)
1196/* Visual Studio */
1197#   define DDS_FUNCTION __FUNCTION__
1198#elif defined(__vxworks)
1199/* At least versions 2.9.6 and 3.3.4 of the GNU C Preprocessor only define
1200   __GNUC__ if the entire GNU C compiler is in use. VxWorks 5.5 targets invoke
1201   the preprocessor separately resulting in __GNUC__ not being defined. */
1202#   define DDS_FUNCTION __FUNCTION__
1203#else
1204#   warning "DDS_FUNCTION is not supported"
1205#   define DDS_FUNCTION ""
1206#endif
1207
1208/**
1209 * @brief Function signature of the current function.
1210 *
1211 * See comments on DDS_FUNCTION for details.
1212 */
1213#if defined(__GNUC__)
1214#   define DDS_PRETTY_FUNCTION __PRETTY_FUNCTION__
1215#elif defined(__clang__)
1216#   define DDS_PRETTY_FUNCTION __PRETTY_FUNCTION__
1217#elif defined(__ghs__)
1218#   define DDS_PRETTY_FUNCTION __PRETTY_FUNCTION__
1219#elif (defined(__SUNPRO_C) && __SUNPRO_C >= 0x5100)
1220/* Solaris Studio supports __PRETTY_FUNCTION__ in C since version 12.1 */
1221#   define DDS_PRETTY_FUNCTION __PRETTY_FUNCTION__
1222#elif (defined(__SUNPRO_CC) && __SUNPRO_CC >= 0x5120)
1223/* Solaris Studio supports __PRETTY_FUNCTION__ in C++ since version 12.3 */
1224#   define DDS_PRETTY_FUNCTION __PRETTY_FUNCTION__
1225#elif defined(__FUNCSIG__)
1226/* Visual Studio */
1227#   define DDS_PRETTY_FUNCTION __FUNCSIG__
1228#elif defined(__vxworks)
1229/* See comments on __vxworks macro above. */
1230#   define DDS_PRETTY_FUNCTION __PRETTY_FUNCTION__
1231#else
1232/* Fall back to DDS_FUNCTION. */
1233#   define DDS_PRETTY_FUNCTION DDS_FUNCTION
1234#endif
1235
1236/**
1237 * @brief Write a log message.
1238 *
1239 * Write a log or trace message to the currently active log and/or trace sinks
1240 * if the log category is enabled. Whether or not the category is enabled is
1241 * checked before any dds_log-related activities to save a couple of % CPU.
1242 *
1243 * Only messages that fall into one of the log categories are passed onto
1244 * dds_log. While messages that fall into a trace category could have been
1245 * passed just as easily, they are rejected so that tracing is kept entirely
1246 * separate from logging, if only cosmetic.
1247 */
1248#define DDS_LOG(cat, ...) \
1249    ((dds_get_log_mask() & (cat)) ? \
1250      dds_log((cat), __FILE__, __LINE__, DDS_FUNCTION, __VA_ARGS__) : 0)
1251
1252/**
1253 * @brief Write a log message with a domain id override.
1254 *
1255 * Write a log or trace message to the currently active log and/or trace sinks
1256 * if the log category is enabled. Whether or not the category is enabled is
1257 * checked before any dds_log-related activities to save a couple of % CPU.
1258 *
1259 * Only messages that fall into one of the log categories are passed onto
1260 * dds_log. While messages that fall into a trace category could have been
1261 * passed just as easily, they are rejected so that tracing is kept entirely
1262 * separate from logging, if only cosmetic.
1263 */
1264#define DDS_ILOG(cat, domid, ...) \
1265    ((dds_get_log_mask() & (cat)) ? \
1266      dds_log_id((cat), (domid), __FILE__, __LINE__, DDS_FUNCTION, __VA_ARGS__) : 0)
1267
1268/**
1269 * @brief Write a log message using a specific config.
1270 *
1271 * Write a log or trace message to the currently active log and/or trace sinks
1272 * if the log category is enabled. Whether or not the category is enabled is
1273 * checked before any dds_log-related activities to save a couple of % CPU.
1274 *
1275 * Only messages that fall into one of the log categories are passed onto
1276 * dds_log. While messages that fall into a trace category could have been
1277 * passed just as easily, they are rejected so that tracing is kept entirely
1278 * separate from logging, if only cosmetic.
1279 */
1280#define DDS_CLOG(cat, cfg, ...) \
1281    (((cfg)->c.mask & (cat)) ? \
1282      dds_log_cfg((cfg), (cat), __FILE__, __LINE__, DDS_FUNCTION, __VA_ARGS__) : 0)
1283
1284/** Write a log message of type #DDS_LC_INFO into global log. */
1285#define DDS_INFO(...) \
1286  DDS_LOG(DDS_LC_INFO, __VA_ARGS__)
1287/** Write a log message of type #DDS_LC_WARNING into global log. */
1288#define DDS_WARNING(...) \
1289  DDS_LOG(DDS_LC_WARNING, __VA_ARGS__)
1290/** Write a log message of type #DDS_LC_ERROR into global log. */
1291#define DDS_ERROR(...) \
1292  DDS_LOG(DDS_LC_ERROR, __VA_ARGS__)
1293/** Write a log message of type #DDS_LC_ERROR into global log and abort. */
1294#define DDS_FATAL(...) \
1295  dds_log(DDS_LC_FATAL, __FILE__, __LINE__, DDS_FUNCTION, __VA_ARGS__)
1296
1297/* MSVC mishandles __VA_ARGS__ while claiming to be conforming -- and even
1298   if they have a defensible implement, they still differ from every other
1299   compiler out there.  An extra layer of macro expansion works around it. */
1300#define DDS_CLOG_MSVC_WORKAROUND(x) x
1301
1302/** Write a log message of type #DDS_LC_INFO using specific logging config. */
1303#define DDS_CINFO(...) \
1304  DDS_CLOG_MSVC_WORKAROUND(DDS_CLOG(DDS_LC_INFO, __VA_ARGS__))
1305/** Write a log message of type #DDS_LC_WARNING using specific logging config. */
1306#define DDS_CWARNING(...) \
1307  DDS_CLOG_MSVC_WORKAROUND(DDS_CLOG(DDS_LC_WARNING, __VA_ARGS__))
1308/** Write a log message of type #DDS_LC_ERROR using specific logging config. */
1309#define DDS_CERROR(...) \
1310  DDS_CLOG_MSVC_WORKAROUND(DDS_CLOG(DDS_LC_ERROR, __VA_ARGS__))
1311/** Write a #DDS_LC_TRACE message using specific logging config. */
1312#define DDS_CTRACE(...) \
1313  DDS_CLOG_MSVC_WORKAROUND(DDS_CLOG(DDS_LC_TRACE, __VA_ARGS__))
1314
1315#if defined (__cplusplus)
1316}
1317#endif
1318
1319#endif /* DDS_LOG_H */
1320
1321/*
1322 * Copyright(c) 2006 to 2018 ADLINK Technology Limited and others
1323 *
1324 * This program and the accompanying materials are made available under the
1325 * terms of the Eclipse Public License v. 2.0 which is available at
1326 * http://www.eclipse.org/legal/epl-2.0, or the Eclipse Distribution License
1327 * v. 1.0 which is available at
1328 * http://www.eclipse.org/org/documents/edl-v10.php.
1329 *
1330 * SPDX-License-Identifier: EPL-2.0 OR BSD-3-Clause
1331 */
1332/* TODO: do we really need to expose all of this as an API? maybe some, but all? */
1333
1334/** @file
1335 *
1336 * @brief DDS C Implementation API
1337 *
1338 * This header file defines the public API for all kinds of things in the
1339 * Eclipse Cyclone DDS C language binding.
1340 */
1341#ifndef DDS_IMPL_H
1342#define DDS_IMPL_H
1343
1344#include <stdint.h>
1345#include <stdbool.h>
1346
1347/*
1348 * Copyright(c) 2006 to 2018 ADLINK Technology Limited and others
1349 *
1350 * This program and the accompanying materials are made available under the
1351 * terms of the Eclipse Public License v. 2.0 which is available at
1352 * http://www.eclipse.org/legal/epl-2.0, or the Eclipse Distribution License
1353 * v. 1.0 which is available at
1354 * http://www.eclipse.org/org/documents/edl-v10.php.
1355 *
1356 * SPDX-License-Identifier: EPL-2.0 OR BSD-3-Clause
1357 */
1358/* TODO: do we really need to expose this as an API? */
1359
1360/** @file
1361 *
1362 * @brief DDS C Allocation API
1363 *
1364 * This header file defines the public API of allocation convenience functions
1365 * in the Eclipse Cyclone DDS C language binding.
1366 */
1367#ifndef DDS_ALLOC_H
1368#define DDS_ALLOC_H
1369
1370#include <stddef.h>
1371
1372#if defined (__cplusplus)
1373extern "C" {
1374#endif
1375
1376struct dds_topic_descriptor;
1377struct dds_sequence;
1378
1379#define DDS_FREE_KEY_BIT 0x01
1380#define DDS_FREE_CONTENTS_BIT 0x02
1381#define DDS_FREE_ALL_BIT 0x04
1382
1383typedef enum
1384{
1385  DDS_FREE_ALL = DDS_FREE_KEY_BIT | DDS_FREE_CONTENTS_BIT | DDS_FREE_ALL_BIT,
1386  DDS_FREE_CONTENTS = DDS_FREE_KEY_BIT | DDS_FREE_CONTENTS_BIT,
1387  DDS_FREE_KEY = DDS_FREE_KEY_BIT
1388}
1389dds_free_op_t;
1390
1391typedef struct dds_allocator
1392{
1393  /* Behaviour as C library malloc, realloc and free */
1394
1395  void * (*malloc) (size_t size);
1396  void * (*realloc) (void *ptr, size_t size); /* if needed */
1397  void (*free) (void *ptr);
1398}
1399dds_allocator_t;
1400
1401DDS_EXPORT void * dds_alloc (size_t size);
1402DDS_EXPORT void * dds_realloc (void * ptr, size_t size);
1403DDS_EXPORT void * dds_realloc_zero (void * ptr, size_t size);
1404DDS_EXPORT void dds_free (void * ptr);
1405
1406typedef void * (*dds_alloc_fn_t) (size_t);
1407typedef void * (*dds_realloc_fn_t) (void *, size_t);
1408typedef void (*dds_free_fn_t) (void *);
1409
1410DDS_EXPORT char * dds_string_alloc (size_t size);
1411DDS_EXPORT char * dds_string_dup (const char * str);
1412DDS_EXPORT void dds_string_free (char * str);
1413DDS_EXPORT void dds_sample_free (void * sample, const struct dds_topic_descriptor * desc, dds_free_op_t op);
1414
1415#if defined (__cplusplus)
1416}
1417#endif
1418#endif
1419
1420#if defined (__cplusplus)
1421extern "C" {
1422#endif
1423
1424typedef struct dds_sequence
1425{
1426  uint32_t _maximum;
1427  uint32_t _length;
1428  uint8_t * _buffer;
1429  bool _release;
1430}
1431dds_sequence_t;
1432
1433typedef struct dds_key_descriptor
1434{
1435  const char * m_name;
1436  uint32_t m_index;
1437}
1438dds_key_descriptor_t;
1439
1440/*
1441  Topic definitions are output by a preprocessor and have an
1442  implementation-private definition. The only thing exposed on the
1443  API is a pointer to the "topic_descriptor_t" struct type.
1444*/
1445
1446typedef struct dds_topic_descriptor
1447{
1448  const uint32_t m_size;               /* Size of topic type */
1449  const uint32_t m_align;              /* Alignment of topic type */
1450  const uint32_t m_flagset;            /* Flags */
1451  const uint32_t m_nkeys;              /* Number of keys (can be 0) */
1452  const char * m_typename;             /* Type name */
1453  const dds_key_descriptor_t * m_keys; /* Key descriptors (NULL iff m_nkeys 0) */
1454  const uint32_t m_nops;               /* Number of ops in m_ops */
1455  const uint32_t * m_ops;              /* Marshalling meta data */
1456  const char * m_meta;                 /* XML topic description meta data */
1457}
1458dds_topic_descriptor_t;
1459
1460/* Topic descriptor flag values */
1461
1462#define DDS_TOPIC_NO_OPTIMIZE 0x0001
1463#define DDS_TOPIC_FIXED_KEY 0x0002
1464#define DDS_TOPIC_CONTAINS_UNION 0x0004
1465#define DDS_TOPIC_DISABLE_TYPECHECK 0x0008
1466
1467/*
1468  Masks for read condition, read, take: there is only one mask here,
1469  which combines the sample, view and instance states.
1470*/
1471
1472#define DDS_READ_SAMPLE_STATE 1u
1473#define DDS_NOT_READ_SAMPLE_STATE 2u
1474#define DDS_ANY_SAMPLE_STATE (1u | 2u)
1475
1476#define DDS_NEW_VIEW_STATE 4u
1477#define DDS_NOT_NEW_VIEW_STATE 8u
1478#define DDS_ANY_VIEW_STATE (4u | 8u)
1479
1480#define DDS_ALIVE_INSTANCE_STATE 16u
1481#define DDS_NOT_ALIVE_DISPOSED_INSTANCE_STATE 32u
1482#define DDS_NOT_ALIVE_NO_WRITERS_INSTANCE_STATE 64u
1483#define DDS_ANY_INSTANCE_STATE (16u | 32u | 64u)
1484
1485#define DDS_ANY_STATE (DDS_ANY_SAMPLE_STATE | DDS_ANY_VIEW_STATE | DDS_ANY_INSTANCE_STATE)
1486
1487#define DDS_DOMAIN_DEFAULT ((uint32_t) 0xffffffffu)
1488#define DDS_HANDLE_NIL 0
1489#define DDS_ENTITY_NIL 0
1490
1491typedef enum dds_entity_kind
1492{
1493  DDS_KIND_DONTCARE,
1494  DDS_KIND_TOPIC,
1495  DDS_KIND_PARTICIPANT,
1496  DDS_KIND_READER,
1497  DDS_KIND_WRITER,
1498  DDS_KIND_SUBSCRIBER,
1499  DDS_KIND_PUBLISHER,
1500  DDS_KIND_COND_READ,
1501  DDS_KIND_COND_QUERY,
1502  DDS_KIND_COND_GUARD,
1503  DDS_KIND_WAITSET,
1504  DDS_KIND_DOMAIN,
1505  DDS_KIND_CYCLONEDDS
1506} dds_entity_kind_t;
1507#define DDS_KIND_MAX DDS_KIND_CYCLONEDDS
1508
1509/* Handles are opaque pointers to implementation types */
1510typedef uint64_t dds_instance_handle_t;
1511typedef uint32_t dds_domainid_t;
1512
1513/* Topic encoding instruction types */
1514
1515enum dds_stream_opcode {
1516  /* return from subroutine, exits top-level
1517     [RTS,   0,   0, 0] */
1518  DDS_OP_RTS = 0x00 << 24,
1519  /* data field
1520     [ADR, nBY,   0, k] [offset]
1521     [ADR, STR,   0, k] [offset]
1522     [ADR, BST,   0, k] [offset] [bound]
1523     [ADR, SEQ, nBY, 0] [offset]
1524     [ADR, SEQ, STR, 0] [offset]
1525     [ADR, SEQ, BST, 0] [offset] [bound]
1526     [ADR, SEQ,   s, 0] [offset] [elem-size] [next-insn, elem-insn]
1527       where s = {SEQ,ARR,UNI,STU}
1528     [ADR, ARR, nBY, k] [offset] [alen]
1529     [ADR, ARR, STR, 0] [offset] [alen]
1530     [ADR, ARR, BST, 0] [offset] [alen] [0] [bound]
1531     [ADR, ARR,   s, 0] [offset] [alen] [next-insn, elem-insn] [elem-size]
1532         where s = {SEQ,ARR,UNI,STU}
1533     [ADR, UNI,   d, z] [offset] [alen] [next-insn, cases]
1534       where
1535         d = discriminant type of {1BY,2BY,4BY}
1536         z = default present/not present (DDS_OP_FLAG_DEF)
1537         offset = discriminant offset
1538       followed by alen case labels: in JEQ format
1539     note: [ADR, STU, ...] is illegal
1540   where
1541     s            = subtype
1542     k            = key/not key (DDS_OP_FLAG_KEY)
1543     [offset]     = field offset from start of element in memory
1544     [elem-size]  = element size in memory
1545     [bound]      = string bound + 1
1546     [alen]       = array length, number of cases
1547     [next-insn]  = (unsigned 16 bits) offset to instruction for next field, from start of insn
1548     [elem-insn]  = (unsigned 16 bits) offset to first instruction for element, from start of insn
1549     [cases]      = (unsigned 16 bits) offset to first case label, from start of insn
1550   */
1551  DDS_OP_ADR = 0x01 << 24,
1552  /* jump-to-subroutine (apparently not used at the moment)
1553     [JSR,   0, e]
1554       where
1555         e = (signed 16 bits) offset to first instruction in subroutine, from start of insn
1556             instruction sequence must end in RTS, execution resumes at instruction
1557             following JSR */
1558  DDS_OP_JSR = 0x02 << 24,
1559  /* union case
1560     [JEQ, nBY, 0] [disc] [offset]
1561     [JEQ, STR, 0] [disc] [offset]
1562     [JEQ,   s, e] [disc] [offset]
1563       where
1564         s  = subtype other than {nBY,STR}
1565         e  = (unsigned 16 bits) offset to first instruction for case, from start of insn
1566              instruction sequence must end in RTS, at which point executes continues
1567              at the next field's instruction as specified by the union */
1568  DDS_OP_JEQ = 0x03 << 24
1569};
1570
1571enum dds_stream_typecode {
1572  DDS_OP_VAL_1BY = 0x01, /* one byte simple type (char, octet, boolean) */
1573  DDS_OP_VAL_2BY = 0x02, /* two byte simple type ((unsigned) short) */
1574  DDS_OP_VAL_4BY = 0x03, /* four byte simple type ((unsigned) long, enums, float) */
1575  DDS_OP_VAL_8BY = 0x04, /* eight byte simple type ((unsigned) long long, double) */
1576  DDS_OP_VAL_STR = 0x05, /* string */
1577  DDS_OP_VAL_BST = 0x06, /* bounded string */
1578  DDS_OP_VAL_SEQ = 0x07, /* sequence */
1579  DDS_OP_VAL_ARR = 0x08, /* array */
1580  DDS_OP_VAL_UNI = 0x09, /* union */
1581  DDS_OP_VAL_STU = 0x0a  /* struct */
1582};
1583
1584/* primary type code for DDS_OP_ADR, DDS_OP_JEQ */
1585enum dds_stream_typecode_primary {
1586  DDS_OP_TYPE_1BY = DDS_OP_VAL_1BY << 16,
1587  DDS_OP_TYPE_2BY = DDS_OP_VAL_2BY << 16,
1588  DDS_OP_TYPE_4BY = DDS_OP_VAL_4BY << 16,
1589  DDS_OP_TYPE_8BY = DDS_OP_VAL_8BY << 16,
1590  DDS_OP_TYPE_STR = DDS_OP_VAL_STR << 16,
1591  DDS_OP_TYPE_BST = DDS_OP_VAL_BST << 16,
1592  DDS_OP_TYPE_SEQ = DDS_OP_VAL_SEQ << 16,
1593  DDS_OP_TYPE_ARR = DDS_OP_VAL_ARR << 16,
1594  DDS_OP_TYPE_UNI = DDS_OP_VAL_UNI << 16,
1595  DDS_OP_TYPE_STU = DDS_OP_VAL_STU << 16
1596};
1597#define DDS_OP_TYPE_BOO DDS_OP_TYPE_1BY
1598
1599/* sub-type code:
1600   - encodes element type for DDS_OP_TYPE_{SEQ,ARR},
1601   - discriminant type for DDS_OP_TYPE_UNI */
1602enum dds_stream_typecode_subtype {
1603  DDS_OP_SUBTYPE_1BY = DDS_OP_VAL_1BY << 8,
1604  DDS_OP_SUBTYPE_2BY = DDS_OP_VAL_2BY << 8,
1605  DDS_OP_SUBTYPE_4BY = DDS_OP_VAL_4BY << 8,
1606  DDS_OP_SUBTYPE_8BY = DDS_OP_VAL_8BY << 8,
1607  DDS_OP_SUBTYPE_STR = DDS_OP_VAL_STR << 8,
1608  DDS_OP_SUBTYPE_BST = DDS_OP_VAL_BST << 8,
1609  DDS_OP_SUBTYPE_SEQ = DDS_OP_VAL_SEQ << 8,
1610  DDS_OP_SUBTYPE_ARR = DDS_OP_VAL_ARR << 8,
1611  DDS_OP_SUBTYPE_UNI = DDS_OP_VAL_UNI << 8,
1612  DDS_OP_SUBTYPE_STU = DDS_OP_VAL_STU << 8
1613};
1614#define DDS_OP_SUBTYPE_BOO DDS_OP_SUBTYPE_1BY
1615
1616#define DDS_OP_FLAG_KEY 0x01 /* key field: applicable to {1,2,4,8}BY, STR, BST, ARR-of-{1,2,4,8}BY */
1617#define DDS_OP_FLAG_DEF 0x02 /* union has a default case (for DDS_OP_ADR | DDS_OP_TYPE_UNI) */
1618
1619/* For a union: (1) the discriminator may be a key field; (2) there may be a default value;
1620   and (3) the discriminator can be an integral type (or enumerated - here treated as equivalent).
1621   What it can't be is a floating-point type. So DEF and FP need never be set at the same time.
1622   There are only a few flag bits, so saving one is not such a bad idea. */
1623#define DDS_OP_FLAG_FP  0x02 /* floating-point: applicable to {4,8}BY and arrays, sequences of them */
1624#define DDS_OP_FLAG_SGN 0x04 /* signed: applicable to {1,2,4,8}BY and arrays, sequences of them */
1625
1626/**
1627 * Description : Enable or disable write batching. Overrides default configuration
1628 * setting for write batching (Internal/WriteBatch).
1629 *
1630 * Arguments :
1631 *   -# enable Enables or disables write batching for all writers.
1632 */
1633DDS_EXPORT void dds_write_set_batch (bool enable);
1634
1635#if defined (__cplusplus)
1636}
1637#endif
1638#endif
1639
1640/*
1641 * Copyright(c) 2006 to 2018 ADLINK Technology Limited and others
1642 *
1643 * This program and the accompanying materials are made available under the
1644 * terms of the Eclipse Public License v. 2.0 which is available at
1645 * http://www.eclipse.org/legal/epl-2.0, or the Eclipse Distribution License
1646 * v. 1.0 which is available at
1647 * http://www.eclipse.org/org/documents/edl-v10.php.
1648 *
1649 * SPDX-License-Identifier: EPL-2.0 OR BSD-3-Clause
1650 */
1651
1652/** @file
1653 *
1654 * @brief DDS C QoS API
1655 *
1656 * This header file defines the public API of QoS and Policies in the
1657 * Eclipse Cyclone DDS C language binding.
1658 */
1659#ifndef DDS_QOS_H
1660#define DDS_QOS_H
1661
1662/*
1663 * Copyright(c) 2006 to 2018 ADLINK Technology Limited and others
1664 *
1665 * This program and the accompanying materials are made available under the
1666 * terms of the Eclipse Public License v. 2.0 which is available at
1667 * http://www.eclipse.org/legal/epl-2.0, or the Eclipse Distribution License
1668 * v. 1.0 which is available at
1669 * http://www.eclipse.org/org/documents/edl-v10.php.
1670 *
1671 * SPDX-License-Identifier: EPL-2.0 OR BSD-3-Clause
1672 */
1673
1674/** @file
1675 *
1676 * @brief DDS C QoS API
1677 *
1678 * This header file defines the public API of QoS and Policies in the
1679 * Eclipse Cyclone DDS C language binding.
1680 */
1681#ifndef DDS_QOSDEFS_H
1682#define DDS_QOSDEFS_H
1683
1684#if defined (__cplusplus)
1685extern "C" {
1686#endif
1687
1688#define DDS_LENGTH_UNLIMITED -1
1689
1690/** QoS identifiers */
1691typedef enum dds_qos_policy_id {
1692  DDS_INVALID_QOS_POLICY_ID,
1693  DDS_USERDATA_QOS_POLICY_ID,
1694  DDS_DURABILITY_QOS_POLICY_ID,
1695  DDS_PRESENTATION_QOS_POLICY_ID,
1696  DDS_DEADLINE_QOS_POLICY_ID,
1697  DDS_LATENCYBUDGET_QOS_POLICY_ID,
1698  DDS_OWNERSHIP_QOS_POLICY_ID,
1699  DDS_OWNERSHIPSTRENGTH_QOS_POLICY_ID,
1700  DDS_LIVELINESS_QOS_POLICY_ID,
1701  DDS_TIMEBASEDFILTER_QOS_POLICY_ID,
1702  DDS_PARTITION_QOS_POLICY_ID,
1703  DDS_RELIABILITY_QOS_POLICY_ID,
1704  DDS_DESTINATIONORDER_QOS_POLICY_ID,
1705  DDS_HISTORY_QOS_POLICY_ID,
1706  DDS_RESOURCELIMITS_QOS_POLICY_ID,
1707  DDS_ENTITYFACTORY_QOS_POLICY_ID,
1708  DDS_WRITERDATALIFECYCLE_QOS_POLICY_ID,
1709  DDS_READERDATALIFECYCLE_QOS_POLICY_ID,
1710  DDS_TOPICDATA_QOS_POLICY_ID,
1711  DDS_GROUPDATA_QOS_POLICY_ID,
1712  DDS_TRANSPORTPRIORITY_QOS_POLICY_ID,
1713  DDS_LIFESPAN_QOS_POLICY_ID,
1714  DDS_DURABILITYSERVICE_QOS_POLICY_ID,
1715  DDS_PROPERTY_QOS_POLICY_ID,
1716  DDS_TYPE_CONSISTENCY_ENFORCEMENT_QOS_POLICY_ID,
1717} dds_qos_policy_id_t;
1718
1719/* QoS structure is opaque */
1720/** QoS structure */
1721typedef struct dds_qos dds_qos_t;
1722
1723/** Durability QoS: Applies to Topic, DataReader, DataWriter */
1724typedef enum dds_durability_kind
1725{
1726    DDS_DURABILITY_VOLATILE,
1727    DDS_DURABILITY_TRANSIENT_LOCAL,
1728    DDS_DURABILITY_TRANSIENT,
1729    DDS_DURABILITY_PERSISTENT
1730}
1731dds_durability_kind_t;
1732
1733/** History QoS: Applies to Topic, DataReader, DataWriter */
1734typedef enum dds_history_kind
1735{
1736    DDS_HISTORY_KEEP_LAST,
1737    DDS_HISTORY_KEEP_ALL
1738}
1739dds_history_kind_t;
1740
1741/** Ownership QoS: Applies to Topic, DataReader, DataWriter */
1742typedef enum dds_ownership_kind
1743{
1744    DDS_OWNERSHIP_SHARED,
1745    DDS_OWNERSHIP_EXCLUSIVE
1746}
1747dds_ownership_kind_t;
1748
1749/** Liveliness QoS: Applies to Topic, DataReader, DataWriter */
1750typedef enum dds_liveliness_kind
1751{
1752    DDS_LIVELINESS_AUTOMATIC,
1753    DDS_LIVELINESS_MANUAL_BY_PARTICIPANT,
1754    DDS_LIVELINESS_MANUAL_BY_TOPIC
1755}
1756dds_liveliness_kind_t;
1757
1758/** Reliability QoS: Applies to Topic, DataReader, DataWriter */
1759typedef enum dds_reliability_kind
1760{
1761    DDS_RELIABILITY_BEST_EFFORT,
1762    DDS_RELIABILITY_RELIABLE
1763}
1764dds_reliability_kind_t;
1765
1766/** DestinationOrder QoS: Applies to Topic, DataReader, DataWriter */
1767typedef enum dds_destination_order_kind
1768{
1769    DDS_DESTINATIONORDER_BY_RECEPTION_TIMESTAMP,
1770    DDS_DESTINATIONORDER_BY_SOURCE_TIMESTAMP
1771}
1772dds_destination_order_kind_t;
1773
1774/** Presentation QoS: Applies to Publisher, Subscriber */
1775typedef enum dds_presentation_access_scope_kind
1776{
1777    DDS_PRESENTATION_INSTANCE,
1778    DDS_PRESENTATION_TOPIC,
1779    DDS_PRESENTATION_GROUP
1780}
1781dds_presentation_access_scope_kind_t;
1782
1783/** Ignore-local QoS: Applies to DataReader, DataWriter */
1784typedef enum dds_ignorelocal_kind
1785{
1786    DDS_IGNORELOCAL_NONE,
1787    DDS_IGNORELOCAL_PARTICIPANT,
1788    DDS_IGNORELOCAL_PROCESS
1789}
1790dds_ignorelocal_kind_t;
1791
1792typedef enum dds_type_consistency_kind
1793{
1794    DDS_TYPE_CONSISTENCY_DISALLOW_TYPE_COERCION,
1795    DDS_TYPE_CONSISTENCY_ALLOW_TYPE_COERCION
1796}
1797dds_type_consistency_kind_t;
1798
1799#if defined (__cplusplus)
1800}
1801#endif
1802#endif
1803
1804/* Whether or not the "property list" QoS setting is supported in this version.  If it is,
1805   the "dds.sec." properties are treated specially, preventing the accidental creation of
1806   an non-secure participant by an implementation built without support for DDS Security. */
1807#define DDS_HAS_PROPERTY_LIST_QOS 1
1808
1809#if defined (__cplusplus)
1810extern "C" {
1811#endif
1812
1813/**
1814 * @brief Allocate memory and initialize default QoS-policies
1815 *
1816 * @returns - Pointer to the initialized dds_qos_t structure, NULL if unsuccessful.
1817 */
1818DDS_EXPORT
1819dds_qos_t * dds_create_qos (void);
1820DDS_DEPRECATED_EXPORT
1821dds_qos_t * dds_qos_create (void);
1822
1823/**
1824 * @brief Delete memory allocated to QoS-policies structure
1825 *
1826 * @param[in] qos - Pointer to dds_qos_t structure
1827 */
1828DDS_EXPORT void
1829dds_delete_qos (dds_qos_t * __restrict qos);
1830
1831DDS_DEPRECATED_EXPORT void
1832dds_qos_delete (dds_qos_t * __restrict qos);
1833
1834/**
1835 * @brief Reset a QoS-policies structure to default values
1836 *
1837 * @param[in,out] qos - Pointer to the dds_qos_t structure
1838 */
1839DDS_EXPORT void
1840dds_reset_qos(dds_qos_t * __restrict qos);
1841
1842DDS_DEPRECATED_EXPORT
1843void dds_qos_reset (dds_qos_t * __restrict qos
1844);
1845
1846/**
1847 * @brief Copy all QoS-policies from one structure to another
1848 *
1849 * @param[in,out] dst - Pointer to the destination dds_qos_t structure
1850 * @param[in] src - Pointer to the source dds_qos_t structure
1851 *
1852 * @returns - Return-code indicating success or failure
1853 */
1854DDS_EXPORT dds_return_t
1855dds_copy_qos (dds_qos_t * __restrict dst, const dds_qos_t * __restrict src);
1856
1857DDS_DEPRECATED_EXPORT dds_return_t
1858dds_qos_copy (dds_qos_t * __restrict dst, const dds_qos_t * __restrict src);
1859
1860/**
1861 * @brief Copy all QoS-policies from one structure to another, unless already set
1862 *
1863 * Policies are copied from src to dst, unless src already has the policy set to a non-default value.
1864 *
1865 * @param[in,out] dst - Pointer to the destination qos structure
1866 * @param[in] src - Pointer to the source qos structure
1867 */
1868DDS_EXPORT void
1869dds_merge_qos (dds_qos_t * __restrict dst, const dds_qos_t * __restrict src);
1870
1871DDS_DEPRECATED_EXPORT void
1872dds_qos_merge (dds_qos_t * __restrict dst, const dds_qos_t * __restrict src);
1873
1874/**
1875 * @brief Copy all QoS-policies from one structure to another, unless already set
1876 *
1877 * Policies are copied from src to dst, unless src already has the policy set to a non-default value.
1878 *
1879 * @param[in,out] a - Pointer to the destination qos structure
1880 * @param[in] b - Pointer to the source qos structure
1881 */
1882DDS_EXPORT bool
1883dds_qos_equal (const dds_qos_t * __restrict a, const dds_qos_t * __restrict b);
1884
1885/**
1886 * @brief Set the userdata of a qos structure.
1887 *
1888 * @param[in,out] qos - Pointer to a dds_qos_t structure that will store the userdata
1889 * @param[in] value - Pointer to the userdata
1890 * @param[in] sz - Size of userdata stored in value
1891 */
1892DDS_EXPORT void
1893dds_qset_userdata (
1894  dds_qos_t * __restrict qos,
1895  const void * __restrict value,
1896  size_t sz);
1897
1898/**
1899 * @brief Set the topicdata of a qos structure.
1900 *
1901 * @param[in,out] qos - Pointer to a dds_qos_t structure that will store the topicdata
1902 * @param[in] value - Pointer to the topicdata
1903 * @param[in] sz - Size of the topicdata stored in value
1904 */
1905DDS_EXPORT void
1906dds_qset_topicdata (
1907  dds_qos_t * __restrict qos,
1908  const void * __restrict value,
1909  size_t sz);
1910
1911/**
1912 * @brief Set the groupdata of a qos structure.
1913 *
1914 * @param[in,out] qos - Pointer to a dds_qos_t structure that will store the groupdata
1915 * @param[in] value - Pointer to the group data
1916 * @param[in] sz - Size of groupdata stored in value
1917 */
1918DDS_EXPORT void
1919dds_qset_groupdata (
1920  dds_qos_t * __restrict qos,
1921  const void * __restrict value,
1922  size_t sz);
1923
1924/**
1925 * @brief Set the durability policy of a qos structure.
1926 *
1927 * @param[in,out] qos - Pointer to a dds_qos_t structure that will store the policy
1928 * @param[in] kind - Durability kind value \ref DCPS_QoS_Durability
1929 */
1930DDS_EXPORT void
1931dds_qset_durability (dds_qos_t * __restrict qos, dds_durability_kind_t kind);
1932
1933/**
1934 * @brief Set the history policy of a qos structure.
1935 *
1936 * Note that depth is only relevant for keep last. If you want limited history for keep all, use dds_qset_resource_limits().
1937 *
1938 * @param[in,out] qos - Pointer to a dds_qos_t structure that will store the policy
1939 * @param[in] kind - History kind value \ref DCPS_QoS_History
1940 * @param[in] depth - History depth value \ref DCPS_QoS_History
1941 */
1942DDS_EXPORT void
1943dds_qset_history (
1944  dds_qos_t * __restrict qos,
1945  dds_history_kind_t kind,
1946  int32_t depth);
1947
1948/**
1949 * @brief Set the resource limits policy of a qos structure.
1950 *
1951 * @param[in,out] qos - Pointer to a dds_qos_t structure that will store the policy
1952 * @param[in] max_samples - Number of samples resource-limit value
1953 * @param[in] max_instances - Number of instances resource-limit value
1954 * @param[in] max_samples_per_instance - Number of samples per instance resource-limit value
1955 */
1956DDS_EXPORT void
1957dds_qset_resource_limits (
1958  dds_qos_t * __restrict qos,
1959  int32_t max_samples,
1960  int32_t max_instances,
1961  int32_t max_samples_per_instance);
1962
1963/**
1964 * @brief Set the presentation policy of a qos structure.
1965 *
1966 * @param[in,out] qos - Pointer to a dds_qos_t structure that will store the policy
1967 * @param[in] access_scope - Access-scope kind
1968 * @param[in] coherent_access - Coherent access enable value
1969 * @param[in] ordered_access - Ordered access enable value
1970 */
1971DDS_EXPORT void
1972dds_qset_presentation (
1973  dds_qos_t * __restrict qos,
1974  dds_presentation_access_scope_kind_t access_scope,
1975  bool coherent_access,
1976  bool ordered_access);
1977
1978/**
1979 * @brief Set the lifespan policy of a qos structure.
1980 *
1981 * @param[in,out] qos - Pointer to a dds_qos_t structure that will store the policy
1982 * @param[in] lifespan - Lifespan duration (expiration time relative to source timestamp of a sample)
1983 */
1984DDS_EXPORT void
1985dds_qset_lifespan (
1986  dds_qos_t * __restrict qos,
1987  dds_duration_t lifespan);
1988
1989/**
1990 * @brief Set the deadline policy of a qos structure.
1991 *
1992 * @param[in,out] qos - Pointer to a dds_qos_t structure that will store the policy
1993 * @param[in] deadline - Deadline duration
1994 */
1995DDS_EXPORT void
1996dds_qset_deadline (
1997  dds_qos_t * __restrict qos,
1998  dds_duration_t deadline);
1999
2000/**
2001 * @brief Set the latency-budget policy of a qos structure
2002 *
2003 * @param[in,out] qos - Pointer to a dds_qos_t structure that will store the policy
2004 * @param[in] duration - Latency budget duration
2005 */
2006DDS_EXPORT void
2007dds_qset_latency_budget (
2008  dds_qos_t * __restrict qos,
2009  dds_duration_t duration);
2010
2011/**
2012 * @brief Set the ownership policy of a qos structure
2013 *
2014 * @param[in,out] qos - Pointer to a dds_qos_t structure that will store the policy
2015 * @param[in] kind - Ownership kind
2016 */
2017DDS_EXPORT void
2018dds_qset_ownership (
2019  dds_qos_t * __restrict qos,
2020  dds_ownership_kind_t kind);
2021
2022/**
2023 * @brief Set the ownership strength policy of a qos structure
2024 *
2025 * param[in,out] qos - Pointer to a dds_qos_t structure that will store the policy
2026 * param[in] value - Ownership strength value
2027 */
2028DDS_EXPORT void
2029dds_qset_ownership_strength (dds_qos_t * __restrict qos, int32_t value);
2030
2031/**
2032 * @brief Set the liveliness policy of a qos structure
2033 *
2034 * param[in,out] qos - Pointer to a dds_qos_t structure that will store the policy
2035 * param[in] kind - Liveliness kind
2036 * param[in[ lease_duration - Lease duration
2037 */
2038DDS_EXPORT void
2039dds_qset_liveliness (
2040  dds_qos_t * __restrict qos,
2041  dds_liveliness_kind_t kind,
2042  dds_duration_t lease_duration);
2043
2044/**
2045 * @brief Set the time-based filter policy of a qos structure
2046 *
2047 * @param[in,out] qos - Pointer to a dds_qos_t structure that will store the policy
2048 * @param[in] minimum_separation - Minimum duration between sample delivery for an instance
2049 */
2050DDS_EXPORT void
2051dds_qset_time_based_filter (
2052  dds_qos_t * __restrict qos,
2053  dds_duration_t minimum_separation);
2054
2055/**
2056 * @brief Set the partition policy of a qos structure
2057 *
2058 * @param[in,out] qos - Pointer to a dds_qos_t structure that will store the policy
2059 * @param[in] n - Number of partitions stored in ps
2060 * @param[in] ps - Pointer to string(s) storing partition name(s)
2061 */
2062DDS_EXPORT void
2063dds_qset_partition (
2064  dds_qos_t * __restrict qos,
2065  uint32_t n,
2066  const char ** __restrict ps);
2067
2068/**
2069 * @brief Convenience function to set the partition policy of a qos structure to a
2070 * single name.  Name may be a null pointer.
2071 *
2072 * @param[in,out] qos - Pointer to a dds_qos_t structure that will store the policy
2073 * @param[in] name - Pointer to the name
2074 */
2075DDS_EXPORT void
2076dds_qset_partition1 (
2077  dds_qos_t * __restrict qos,
2078  const char * __restrict name);
2079
2080/**
2081 * @brief Set the reliability policy of a qos structure
2082 *
2083 * @param[in,out] qos - Pointer to a dds_qos_t structure that will store the policy
2084 * @param[in] kind - Reliability kind
2085 * @param[in] max_blocking_time - Max blocking duration applied when kind is reliable. This is how long the writer will block when its history is full.
2086 */
2087DDS_EXPORT void
2088dds_qset_reliability (
2089  dds_qos_t * __restrict qos,
2090  dds_reliability_kind_t kind,
2091  dds_duration_t max_blocking_time);
2092
2093/**
2094 * @brief Set the transport-priority policy of a qos structure
2095 *
2096 * @param[in,out] qos - Pointer to a dds_qos_t structure that will store the policy
2097 * @param[in] value - Priority value
2098 */
2099DDS_EXPORT void
2100dds_qset_transport_priority (dds_qos_t * __restrict qos, int32_t value);
2101
2102/**
2103 * @brief Set the destination-order policy of a qos structure
2104 *
2105 * @param[in,out] qos - Pointer to a dds_qos_t structure that will store the policy
2106 * @param[in] kind - Destination-order kind
2107 */
2108DDS_EXPORT void
2109dds_qset_destination_order (
2110  dds_qos_t * __restrict qos,
2111  dds_destination_order_kind_t kind);
2112
2113/**
2114 * @brief Set the writer data-lifecycle policy of a qos structure
2115 *
2116 * @param[in,out] qos - Pointer to a dds_qos_t structure that will store the policy
2117 * @param[in] autodispose - Automatic disposal of unregistered instances
2118 */
2119DDS_EXPORT void
2120dds_qset_writer_data_lifecycle (dds_qos_t * __restrict qos, bool autodispose);
2121
2122/**
2123 * @brief Set the reader data-lifecycle policy of a qos structure
2124 *
2125 * @param[in,out] qos - Pointer to a dds_qos_t structure that will store the policy
2126 * @param[in] autopurge_nowriter_samples_delay - Delay for purging of samples from instances in a no-writers state
2127 * @param[in] autopurge_disposed_samples_delay - Delay for purging of samples from disposed instances
2128 */
2129DDS_EXPORT void
2130dds_qset_reader_data_lifecycle (
2131  dds_qos_t * __restrict qos,
2132  dds_duration_t autopurge_nowriter_samples_delay,
2133  dds_duration_t autopurge_disposed_samples_delay);
2134
2135/**
2136 * @brief Set the durability-service policy of a qos structure
2137 *
2138 * @param[in,out] qos - Pointer to a dds_qos_t structure that will store the policy
2139 * @param[in] service_cleanup_delay - Delay for purging of abandoned instances from the durability service
2140 * @param[in] history_kind - History policy kind applied by the durability service
2141 * @param[in] history_depth - History policy depth applied by the durability service
2142 * @param[in] max_samples - Number of samples resource-limit policy applied by the durability service
2143 * @param[in] max_instances - Number of instances resource-limit policy applied by the durability service
2144 * @param[in] max_samples_per_instance - Number of samples per instance resource-limit policy applied by the durability service
2145 */
2146DDS_EXPORT void
2147dds_qset_durability_service (
2148  dds_qos_t * __restrict qos,
2149  dds_duration_t service_cleanup_delay,
2150  dds_history_kind_t history_kind,
2151  int32_t history_depth,
2152  int32_t max_samples,
2153  int32_t max_instances,
2154  int32_t max_samples_per_instance);
2155
2156/**
2157 * @brief Set the ignore-local policy of a qos structure
2158 *
2159 * @param[in,out] qos - Pointer to a dds_qos_t structure that will store the policy
2160 * @param[in] ignore - True if readers and writers owned by the same participant should be ignored
2161 */
2162DDS_EXPORT void
2163dds_qset_ignorelocal (
2164  dds_qos_t * __restrict qos,
2165  dds_ignorelocal_kind_t ignore);
2166
2167/**
2168 * @brief Stores a property with the provided name and string value in a qos structure.
2169 *
2170 * In the case a property with the provided name already exists in the qos structure,
2171 * the value for this entry is overwritten with the provided string value. If more than
2172 * one property with the provided name exists, only the value of the first of these
2173 * properties is updated.
2174 *
2175 * @param[in,out] qos - Pointer to a dds_qos_t structure that will store the property
2176 * @param[in] name - Pointer to name of the property
2177 * @param[in] value - Pointer to a (null-terminated) string that will be stored
2178 */
2179DDS_EXPORT void
2180dds_qset_prop (
2181  dds_qos_t * __restrict qos,
2182  const char * name,
2183  const char * value);
2184
2185/**
2186 * @brief Removes the property with the provided name from a qos structure.
2187 *
2188 * In case more than one property exists with this name, only the first property
2189 * is removed.
2190 *
2191 * @param[in,out] qos - Pointer to a dds_qos_t structure that contains the property
2192 * @param[in] name - Pointer to name of the property
2193 */
2194DDS_EXPORT void
2195dds_qunset_prop (
2196  dds_qos_t * __restrict qos,
2197  const char * name);
2198
2199/**
2200 * @brief Stores the provided binary data as a property in a qos structure
2201 *
2202 * In the case a property with the provided name already exists in the qos structure,
2203 * the value for this entry is overwritten with the provided data. If more than one
2204 * property with the provided name exists, only the value of the first of these
2205 * properties is updated.
2206 *
2207 * @param[in,out] qos - Pointer to a dds_qos_t structure that will store the property
2208 * @param[in] name - Pointer to name of the property
2209 * @param[in] value - Pointer to data to be stored in the property
2210 * @param[in] sz - Size of the data
2211 */
2212DDS_EXPORT void
2213dds_qset_bprop (
2214  dds_qos_t * __restrict qos,
2215  const char * name,
2216  const void * value,
2217  const size_t sz);
2218
2219/**
2220 * @brief Removes the binary property with the provided name from a qos structure.
2221 *
2222 * In case more than one binary property exists with this name, only the first binary
2223 * property is removed.
2224 *
2225 * @param[in,out] qos - Pointer to a dds_qos_t structure that contains the binary property
2226 * @param[in] name - Pointer to name of the property
2227 */
2228DDS_EXPORT void
2229dds_qunset_bprop (
2230  dds_qos_t * __restrict qos,
2231  const char * name);
2232
2233/**
2234 * @brief Set the type consistency enforcement policy of a qos structure
2235 *
2236 * @param[in,out] qos - Pointer to a dds_qos_t structure that will store the policy
2237 * @param[in] kind - Type consistency policy kind
2238 * @param[in] ignore_sequence_bounds - Ignore sequence bounds in type assignability checking
2239 * @param[in] ignore_string_bounds - Ignore string bounds in type assignability checking
2240 * @param[in] ignore_member_names - Ignore member names in type assignability checking
2241 * @param[in] prevent_type_widening - Prevent type widening in type assignability checking
2242 * @param[in] force_type_validation - Force type validation in assignability checking
2243 */
2244DDS_EXPORT void
2245dds_qset_type_consistency (
2246  dds_qos_t * __restrict qos,
2247  dds_type_consistency_kind_t kind,
2248  bool ignore_sequence_bounds,
2249  bool ignore_string_bounds,
2250  bool ignore_member_names,
2251  bool prevent_type_widening,
2252  bool force_type_validation);
2253
2254/**
2255 * @brief Get the userdata from a qos structure
2256 *
2257 * @param[in] qos - Pointer to a dds_qos_t structure storing the policy
2258 * @param[in,out] value - Pointer that will store the userdata.  If sz = 0, then a null pointer, else it is a pointer to an allocated buffer of sz+1 bytes where the last byte is always 0
2259 * @param[in,out] sz - Pointer that will store the size of userdata
2260 *
2261 * @returns - false iff any of the arguments is invalid or the qos is not present in the qos object
2262 */
2263DDS_EXPORT bool dds_qget_userdata (const dds_qos_t * __restrict qos, void **value, size_t *sz);
2264
2265/**
2266 * @brief Get the topicdata from a qos structure
2267 *
2268 * @param[in] qos - Pointer to a dds_qos_t structure storing the policy
2269 * @param[in,out] value - Pointer that will store the topicdata.  If sz = 0, then a null pointer, else it is a pointer to an allocated buffer of sz+1 bytes where the last byte is always 0
2270 * @param[in,out] sz - Pointer that will store the size of topicdata
2271 *
2272 * @returns - false iff any of the arguments is invalid or the qos is not present in the qos object
2273*/
2274DDS_EXPORT bool dds_qget_topicdata (const dds_qos_t * __restrict qos, void **value, size_t *sz);
2275
2276/**
2277 * @brief Get the groupdata from a qos structure
2278 *
2279 * @param[in] qos - Pointer to a dds_qos_t structure storing the policy
2280 * @param[in,out] value - Pointer that will store the groupdata.  If sz = 0, then a null pointer, else it is a pointer to an allocated buffer of sz+1 bytes where the last byte is always 0
2281 * @param[in,out] sz - Pointer that will store the size of groupdata
2282 *
2283 * @returns - false iff any of the arguments is invalid or the qos is not present in the qos object
2284 */
2285DDS_EXPORT bool dds_qget_groupdata (const dds_qos_t * __restrict qos, void **value, size_t *sz);
2286
2287/**
2288 * @brief Get the durability policy from a qos structure
2289 *
2290 * @param[in] qos - Pointer to a dds_qos_t structure storing the policy
2291 * @param[in,out] kind - Pointer that will store the durability kind
2292 *
2293 * @returns - false iff any of the arguments is invalid or the qos is not present in the qos object
2294 */
2295DDS_EXPORT bool dds_qget_durability (const dds_qos_t * __restrict qos, dds_durability_kind_t *kind);
2296
2297/**
2298 * @brief Get the history policy from a qos structure
2299 *
2300 * @param[in] qos - Pointer to a dds_qos_t structure storing the policy
2301 * @param[in,out] kind - Pointer that will store the history kind (optional)
2302 * @param[in,out] depth - Pointer that will store the history depth (optional)
2303 *
2304 * @returns - false iff any of the arguments is invalid or the qos is not present in the qos object
2305 */
2306DDS_EXPORT bool dds_qget_history (const dds_qos_t * __restrict qos, dds_history_kind_t *kind, int32_t *depth);
2307
2308/**
2309 * @brief Get the resource-limits policy from a qos structure
2310 *
2311 * @param[in] qos - Pointer to a dds_qos_t structure storing the policy
2312 * @param[in,out] max_samples - Pointer that will store the number of samples resource-limit (optional)
2313 * @param[in,out] max_instances - Pointer that will store the number of instances resource-limit (optional)
2314 * @param[in,out] max_samples_per_instance - Pointer that will store the number of samples per instance resource-limit (optional)
2315 *
2316 * @returns - false iff any of the arguments is invalid or the qos is not present in the qos object
2317 */
2318DDS_EXPORT bool
2319dds_qget_resource_limits (
2320  const dds_qos_t * __restrict qos,
2321  int32_t *max_samples,
2322  int32_t *max_instances,
2323  int32_t *max_samples_per_instance);
2324
2325/**
2326 * @brief Get the presentation policy from a qos structure
2327 *
2328 * @param[in] qos - Pointer to a dds_qos_t structure storing the policy
2329 * @param[in,out] access_scope - Pointer that will store access scope kind (optional)
2330 * @param[in,out] coherent_access - Pointer that will store coherent access enable value (optional)
2331 * @param[in,out] ordered_access - Pointer that will store orderede access enable value (optional)
2332 *
2333 * @returns - false iff any of the arguments is invalid or the qos is not present in the qos object
2334 */
2335DDS_EXPORT bool
2336dds_qget_presentation (
2337  const dds_qos_t * __restrict qos,
2338  dds_presentation_access_scope_kind_t *access_scope,
2339  bool *coherent_access,
2340  bool *ordered_access);
2341
2342/**
2343 * @brief Get the lifespan policy from a qos structure
2344 *
2345 * @param[in] qos - Pointer to a dds_qos_t structure storing the policy
2346 * @param[in,out] lifespan - Pointer that will store lifespan duration
2347 *
2348 * @returns - false iff any of the arguments is invalid or the qos is not present in the qos object
2349 */
2350DDS_EXPORT bool
2351dds_qget_lifespan (
2352  const dds_qos_t * __restrict qos,
2353  dds_duration_t *lifespan);
2354
2355/**
2356 * @brief Get the deadline policy from a qos structure
2357 *
2358 * @param[in] qos - Pointer to a dds_qos_t structure storing the policy
2359 * @param[in,out] deadline - Pointer that will store deadline duration
2360 *
2361 * @returns - false iff any of the arguments is invalid or the qos is not present in the qos object
2362 */
2363DDS_EXPORT bool
2364dds_qget_deadline (
2365  const dds_qos_t * __restrict qos,
2366  dds_duration_t *deadline);
2367
2368/**
2369 * @brief Get the latency-budget policy from a qos structure
2370 *
2371 * @param[in] qos - Pointer to a dds_qos_t structure storing the policy
2372 * @param[in,out] duration - Pointer that will store latency-budget duration
2373 *
2374 * @returns - false iff any of the arguments is invalid or the qos is not present in the qos object
2375 */
2376DDS_EXPORT bool
2377dds_qget_latency_budget (
2378  const dds_qos_t * __restrict qos,
2379  dds_duration_t *duration);
2380
2381/**
2382 * @brief Get the ownership policy from a qos structure
2383 *
2384 * @param[in] qos - Pointer to a dds_qos_t structure storing the policy
2385 * @param[in,out] kind - Pointer that will store the ownership kind
2386 *
2387 * @returns - false iff any of the arguments is invalid or the qos is not present in the qos object
2388 */
2389DDS_EXPORT bool
2390dds_qget_ownership (
2391  const dds_qos_t * __restrict qos,
2392  dds_ownership_kind_t *kind);
2393
2394/**
2395 * @brief Get the ownership strength qos policy
2396 *
2397 * @param[in] qos - Pointer to a dds_qos_t structure storing the policy
2398 * @param[in,out] value - Pointer that will store the ownership strength value
2399 *
2400 * @returns - false iff any of the arguments is invalid or the qos is not present in the qos object
2401 */
2402DDS_EXPORT bool
2403dds_qget_ownership_strength (
2404  const dds_qos_t * __restrict qos,
2405  int32_t *value);
2406
2407/**
2408 * @brief Get the liveliness qos policy
2409 *
2410 * @param[in] qos - Pointer to a dds_qos_t structure storing the policy
2411 * @param[in,out] kind - Pointer that will store the liveliness kind (optional)
2412 * @param[in,out] lease_duration - Pointer that will store the liveliness lease duration (optional)
2413 *
2414 * @returns - false iff any of the arguments is invalid or the qos is not present in the qos object
2415 */
2416DDS_EXPORT bool
2417dds_qget_liveliness (
2418  const dds_qos_t * __restrict qos,
2419  dds_liveliness_kind_t *kind,
2420  dds_duration_t *lease_duration);
2421
2422/**
2423 * @brief Get the time-based filter qos policy
2424 *
2425 * @param[in] qos - Pointer to a dds_qos_t structure storing the policy
2426 * @param[in,out] minimum_separation - Pointer that will store the minimum separation duration (optional)
2427 *
2428 * @returns - false iff any of the arguments is invalid or the qos is not present in the qos object
2429 */
2430DDS_EXPORT bool
2431dds_qget_time_based_filter (
2432  const dds_qos_t * __restrict qos,
2433  dds_duration_t *minimum_separation);
2434
2435/**
2436 * @brief Get the partition qos policy
2437 *
2438 * @param[in] qos - Pointer to a dds_qos_t structure storing the policy
2439 * @param[in,out] n - Pointer that will store the number of partitions (optional)
2440 * @param[in,out] ps - Pointer that will store the string(s) containing partition name(s) (optional)
2441 *
2442 * @returns - false iff any of the arguments is invalid or the qos is not present in the qos object
2443 */
2444DDS_EXPORT bool
2445dds_qget_partition (
2446  const dds_qos_t * __restrict qos,
2447  uint32_t *n,
2448  char ***ps);
2449
2450/**
2451 * @brief Get the reliability qos policy
2452 *
2453 * @param[in] qos - Pointer to a dds_qos_t structure storing the policy
2454 * @param[in,out] kind - Pointer that will store the reliability kind (optional)
2455 * @param[in,out] max_blocking_time - Pointer that will store the max blocking time for reliable reliability (optional)
2456 *
2457 * @returns - false iff any of the arguments is invalid or the qos is not present in the qos object
2458 */
2459DDS_EXPORT bool
2460dds_qget_reliability (
2461  const dds_qos_t * __restrict qos,
2462  dds_reliability_kind_t *kind,
2463  dds_duration_t *max_blocking_time);
2464
2465/**
2466 * @brief Get the transport priority qos policy
2467 *
2468 * @param[in] qos - Pointer to a dds_qos_t structure storing the policy
2469 * @param[in,out] value - Pointer that will store the transport priority value
2470 *
2471 * @returns - false iff any of the arguments is invalid or the qos is not present in the qos object
2472 */
2473DDS_EXPORT bool
2474dds_qget_transport_priority (
2475  const dds_qos_t * __restrict qos,
2476  int32_t *value);
2477
2478/**
2479 * @brief Get the destination-order qos policy
2480 *
2481 * @param[in] qos - Pointer to a dds_qos_t structure storing the policy
2482 * @param[in,out] kind - Pointer that will store the destination-order kind
2483 *
2484 * @returns - false iff any of the arguments is invalid or the qos is not present in the qos object
2485 */
2486DDS_EXPORT bool
2487dds_qget_destination_order (
2488  const dds_qos_t * __restrict qos,
2489  dds_destination_order_kind_t *kind);
2490
2491/**
2492 * @brief Get the writer data-lifecycle qos policy
2493 *
2494 * @param[in] qos - Pointer to a dds_qos_t structure storing the policy
2495 * @param[in,out] autodispose - Pointer that will store the autodispose unregistered instances enable value
2496 *
2497 * @returns - false iff any of the arguments is invalid or the qos is not present in the qos object
2498 */
2499DDS_EXPORT bool
2500dds_qget_writer_data_lifecycle (
2501  const dds_qos_t * __restrict qos,
2502  bool *autodispose);
2503
2504/**
2505 * @brief Get the reader data-lifecycle qos policy
2506 *
2507 * @param[in] qos - Pointer to a dds_qos_t structure storing the policy
2508 * @param[in,out] autopurge_nowriter_samples_delay - Pointer that will store the delay for auto-purging samples from instances in a no-writer state (optional)
2509 * @param[in,out] autopurge_disposed_samples_delay - Pointer that will store the delay for auto-purging of disposed instances (optional)
2510 *
2511 * @returns - false iff any of the arguments is invalid or the qos is not present in the qos object
2512 */
2513DDS_EXPORT bool
2514dds_qget_reader_data_lifecycle (
2515  const dds_qos_t * __restrict qos,
2516  dds_duration_t *autopurge_nowriter_samples_delay,
2517  dds_duration_t *autopurge_disposed_samples_delay);
2518
2519/**
2520 * @brief Get the durability-service qos policy values.
2521 *
2522 * @param[in] qos - Pointer to a dds_qos_t structure storing the policy
2523 * @param[in,out]  service_cleanup_delay - Pointer that will store the delay for purging of abandoned instances from the durability service (optional)
2524 * @param[in,out] history_kind - Pointer that will store history policy kind applied by the durability service (optional)
2525 * @param[in,out] history_depth - Pointer that will store history policy depth applied by the durability service (optional)
2526 * @param[in,out] max_samples - Pointer that will store number of samples resource-limit policy applied by the durability service (optional)
2527 * @param[in,out] max_instances - Pointer that will store number of instances resource-limit policy applied by the durability service (optional)
2528 * @param[in,out] max_samples_per_instance - Pointer that will store number of samples per instance resource-limit policy applied by the durability service (optional)
2529 *
2530 * @returns - false iff any of the arguments is invalid or the qos is not present in the qos object
2531 */
2532DDS_EXPORT bool
2533dds_qget_durability_service (
2534  const dds_qos_t * __restrict qos,
2535  dds_duration_t *service_cleanup_delay,
2536  dds_history_kind_t *history_kind,
2537  int32_t *history_depth,
2538  int32_t *max_samples,
2539  int32_t *max_instances,
2540  int32_t *max_samples_per_instance);
2541
2542  /**
2543   * @brief Get the ignore-local qos policy
2544   *
2545   * @param[in] qos - Pointer to a dds_qos_t structure storing the policy
2546   * @param[in,out] ignore - Pointer that will store whether to ignore readers/writers owned by the same participant (optional)
2547   *
2548   * @returns - false iff any of the arguments is invalid or the qos is not present in the qos object
2549   */
2550DDS_EXPORT bool
2551dds_qget_ignorelocal (
2552  const dds_qos_t * __restrict qos,
2553  dds_ignorelocal_kind_t *ignore);
2554
2555/**
2556 * @brief Gets the names of the properties from a qos structure.
2557 *
2558 * @param[in,out] qos - Pointer to a dds_qos_t structure that contains properties
2559 * @param[in,out] n - Pointer to number of property names that are returned (optional)
2560 * @param[in,out] names - Pointer that will store the string(s) containing property name(s) (optional). This function will allocate the memory for the list of names and for the strings containing the names; the caller gets ownership of the allocated memory
2561 *
2562 * @returns - false iff any of the arguments is invalid or the qos is not present in the qos object
2563 */
2564DDS_EXPORT bool
2565dds_qget_propnames (
2566  const dds_qos_t * __restrict qos,
2567  uint32_t * n,
2568  char *** names);
2569
2570/**
2571 * @brief Get the value of the property with the provided name from a qos structure.
2572 *
2573 * In case more than one property exists with this name, the value for the first
2574 * property with this name will be returned.
2575 *
2576 * @param[in,out] qos - Pointer to a dds_qos_t structure that contains the property
2577 * @param[in] name - Pointer to name of the property
2578 * @param[in,out] value - Pointer to a string that will store the value of the property. The memory for storing the string value will be allocated by this function and the caller gets ownership of the allocated memory
2579 *
2580 * @returns - false iff any of the arguments is invalid, the qos is not present in the qos object or there was no property found with the provided name
2581 */
2582DDS_EXPORT bool
2583dds_qget_prop (
2584  const dds_qos_t * __restrict qos,
2585  const char * name,
2586  char ** value);
2587
2588/**
2589 * @brief Gets the names of the binary properties from a qos structure.
2590 *
2591 * @param[in,out] qos - Pointer to a dds_qos_t structure that contains binary properties
2592 * @param[in,out] n - Pointer to number of binary property names that are returned (optional)
2593 * @param[in,out] names - Pointer that will store the string(s) containing binary property name(s) (optional). This function will allocate the memory for the list of names and for the strings containing the names; the caller gets ownership of the allocated memory
2594 *
2595 * @returns - false iff any of the arguments is invalid or the qos is not present in the qos object
2596 */
2597DDS_EXPORT bool
2598dds_qget_bpropnames (
2599  const dds_qos_t * __restrict qos,
2600  uint32_t * n,
2601  char *** names);
2602
2603/**
2604 * @brief Get the value of the binary property with the provided name from a qos structure.
2605 *
2606 * In case more than one binary property exists with this name, the value for the first
2607 * binary property with this name will be returned.
2608 *
2609 * @param[in,out] qos - Pointer to a dds_qos_t structure that contains the property
2610 * @param[in] name - Pointer to name of the binary property
2611 * @param[in,out] value - Pointer to a buffer that will store the value of the property. If sz = 0 then a NULL pointer. The memory for storing the value will be allocated by this function and the caller gets ownership of the allocated memory
2612 * @param[in,out] sz - Pointer that will store the size of the returned buffer.
2613 *
2614 * @returns - false iff any of the arguments is invalid, the qos is not present in the qos object or there was no binary property found with the provided name
2615 */
2616DDS_EXPORT bool
2617dds_qget_bprop (
2618  const dds_qos_t * __restrict qos,
2619  const char * name,
2620  void ** value,
2621  size_t * sz);
2622
2623/**
2624 * @brief Get the type consistency enforcement qos policy values.
2625 *
2626 * @param[in] qos - Pointer to a dds_qos_t structure storing the policy
2627 * @param[in,out] kind - Pointer that will store the type consistency enforcement kind (optional)
2628 * @param[in,out] ignore_sequence_bounds - Pointer that will store the boolean value for ignoring sequence bounds in type assignability checking (optional)
2629 * @param[in,out] ignore_string_bounds - Pointer that will store the boolean value for ignoring string bounds in type assignability checking (optional)
2630 * @param[in,out] ignore_member_names - Pointer that will store the boolean value for ignoring member names in type assignability checking (optional)
2631 * @param[in,out] prevent_type_widening - Pointer that will store the boolean value to prevent type widening in type assignability checking (optional)
2632 * @param[in,out] force_type_validation - Pointer that will store the boolean value to force type validation in assignability checking (optional)
2633 *
2634 * @returns - false iff any of the arguments is invalid or the qos is not present in the qos object
2635 */
2636DDS_EXPORT bool
2637dds_qget_type_consistency (
2638  const dds_qos_t * __restrict qos,
2639  dds_type_consistency_kind_t *kind,
2640  bool *ignore_sequence_bounds,
2641  bool *ignore_string_bounds,
2642  bool *ignore_member_names,
2643  bool *prevent_type_widening,
2644  bool *force_type_validation);
2645
2646#if defined (__cplusplus)
2647}
2648#endif
2649#endif
2650
2651/*
2652 * Copyright(c) 2006 to 2018 ADLINK Technology Limited and others
2653 *
2654 * This program and the accompanying materials are made available under the
2655 * terms of the Eclipse Public License v. 2.0 which is available at
2656 * http://www.eclipse.org/legal/epl-2.0, or the Eclipse Distribution License
2657 * v. 1.0 which is available at
2658 * http://www.eclipse.org/org/documents/edl-v10.php.
2659 *
2660 * SPDX-License-Identifier: EPL-2.0 OR BSD-3-Clause
2661 */
2662
2663/** @file
2664 *
2665 * @brief DDS C Error API
2666 *
2667 * This header file defines the public API of error values and convenience
2668 * functions in the CycloneDDS C language binding.
2669 */
2670#ifndef DDS_ERROR_H
2671#define DDS_ERROR_H
2672
2673#if defined (__cplusplus)
2674extern "C" {
2675#endif
2676
2677/* ** DEPRECATED ** */
2678
2679/* Error masks for returned status values */
2680
2681#define DDS_ERR_NR_MASK       0x000000ff
2682#define DDS_ERR_LINE_MASK     0x003fff00
2683#define DDS_ERR_FILE_ID_MASK  0x7fc00000
2684
2685/* Error code handling functions */
2686
2687/** Macro to extract error number */
2688#define dds_err_nr(e) (e)
2689
2690/** Macro to extract line number */
2691#define dds_err_line(e) (0)
2692
2693/** Macro to extract file identifier */
2694#define dds_err_file_id(e) (0)
2695
2696#if defined (__cplusplus)
2697}
2698#endif
2699#endif
2700
2701/*
2702 * Copyright(c) 2006 to 2018 ADLINK Technology Limited and others
2703 *
2704 * This program and the accompanying materials are made available under the
2705 * terms of the Eclipse Public License v. 2.0 which is available at
2706 * http://www.eclipse.org/legal/epl-2.0, or the Eclipse Distribution License
2707 * v. 1.0 which is available at
2708 * http://www.eclipse.org/org/documents/edl-v10.php.
2709 *
2710 * SPDX-License-Identifier: EPL-2.0 OR BSD-3-Clause
2711 */
2712
2713/** @file
2714 *
2715 * @brief DDS C Communication Status API
2716 *
2717 * This header file defines the public API of the Communication Status in the
2718 * Eclipse Cyclone DDS C language binding.
2719 */
2720#ifndef DDS_STATUS_H
2721#define DDS_STATUS_H
2722
2723#if defined (__cplusplus)
2724extern "C" {
2725#endif
2726
2727/*
2728  Listeners implemented as structs containing callback functions
2729  that take listener status types as arguments.
2730*/
2731
2732/* Listener status types */
2733/**
2734 * \ref DCPS_Status_OfferedDeadlineMissed
2735 */
2736typedef struct dds_offered_deadline_missed_status
2737{
2738  uint32_t total_count;
2739  int32_t total_count_change;
2740  dds_instance_handle_t last_instance_handle;
2741}
2742dds_offered_deadline_missed_status_t;
2743
2744/**
2745 * \ref DCPS_Status_OfferedIncompatibleQoS
2746 */
2747typedef struct dds_offered_incompatible_qos_status
2748{
2749  uint32_t total_count;
2750  int32_t total_count_change;
2751  uint32_t last_policy_id;
2752}
2753dds_offered_incompatible_qos_status_t;
2754
2755/**
2756 * \ref DCPS_Status_PublicationMatched
2757 */
2758typedef struct dds_publication_matched_status
2759{
2760  uint32_t total_count;
2761  int32_t total_count_change;
2762  uint32_t current_count;
2763  int32_t current_count_change;
2764  dds_instance_handle_t last_subscription_handle;
2765}
2766dds_publication_matched_status_t;
2767
2768/**
2769 * \ref DCPS_Status_LivelinessLost
2770 */
2771typedef struct dds_liveliness_lost_status
2772{
2773  uint32_t total_count;
2774  int32_t total_count_change;
2775}
2776dds_liveliness_lost_status_t;
2777
2778/**
2779 * \ref DCPS_Status_SubscriptionMatched
2780 */
2781typedef struct dds_subscription_matched_status
2782{
2783  uint32_t total_count;
2784  int32_t total_count_change;
2785  uint32_t current_count;
2786  int32_t current_count_change;
2787  dds_instance_handle_t last_publication_handle;
2788}
2789dds_subscription_matched_status_t;
2790
2791/**
2792 * dds_sample_rejected_status_kind
2793 */
2794typedef enum
2795{
2796  DDS_NOT_REJECTED,
2797  DDS_REJECTED_BY_INSTANCES_LIMIT,
2798  DDS_REJECTED_BY_SAMPLES_LIMIT,
2799  DDS_REJECTED_BY_SAMPLES_PER_INSTANCE_LIMIT
2800}
2801dds_sample_rejected_status_kind;
2802
2803/**
2804 * \ref DCPS_Status_SampleRejected
2805 */
2806typedef struct dds_sample_rejected_status
2807{
2808  uint32_t total_count;
2809  int32_t total_count_change;
2810  dds_sample_rejected_status_kind last_reason;
2811  dds_instance_handle_t last_instance_handle;
2812}
2813dds_sample_rejected_status_t;
2814
2815/**
2816 * \ref DCPS_Status_LivelinessChanged
2817 */
2818typedef struct dds_liveliness_changed_status
2819{
2820  uint32_t alive_count;
2821  uint32_t not_alive_count;
2822  int32_t alive_count_change;
2823  int32_t not_alive_count_change;
2824  dds_instance_handle_t last_publication_handle;
2825}
2826dds_liveliness_changed_status_t;
2827
2828/**
2829 * \ref DCPS_Status_RequestedDeadlineMissed
2830 */
2831typedef struct dds_requested_deadline_missed_status
2832{
2833  uint32_t total_count;
2834  int32_t total_count_change;
2835  dds_instance_handle_t last_instance_handle;
2836}
2837dds_requested_deadline_missed_status_t;
2838
2839/**
2840 * \ref DCPS_Status_RequestedIncompatibleQoS
2841 */
2842typedef struct dds_requested_incompatible_qos_status
2843{
2844  uint32_t total_count;
2845  int32_t total_count_change;
2846  uint32_t last_policy_id;
2847}
2848dds_requested_incompatible_qos_status_t;
2849
2850/**
2851 * \ref DCPS_Status_SampleLost
2852 */
2853typedef struct dds_sample_lost_status
2854{
2855  uint32_t total_count;
2856  int32_t total_count_change;
2857}
2858dds_sample_lost_status_t;
2859
2860/**
2861 * \ref DCPS_Status_InconsistentTopic
2862 */
2863typedef struct dds_inconsistent_topic_status
2864{
2865  uint32_t total_count;
2866  int32_t total_count_change;
2867}
2868dds_inconsistent_topic_status_t;
2869
2870/*
2871  get_<status> APIs return the status of an entity and resets the status
2872*/
2873
2874/**
2875 * @brief Get INCONSISTENT_TOPIC status
2876 *
2877 * This operation gets the status value corresponding to INCONSISTENT_TOPIC
2878 * and reset the status. The value can be obtained, only if the status is enabled for an entity.
2879 * NULL value for status is allowed and it will reset the trigger value when status is enabled.
2880 *
2881 * @param[in]  topic  The entity to get the status
2882 * @param[out] status The pointer to \ref DCPS_Status_InconsistentTopic to get the status
2883 *
2884 * @returns  0 - Success
2885 * @returns <0 - Failure
2886 *
2887 * @retval DDS_RETCODE_ERROR
2888 *                  An internal error has occurred.
2889 * @retval DDS_RETCODE_BAD_PARAMETER
2890 *                  One of the given arguments is not valid.
2891 * @retval DDS_RETCODE_ILLEGAL_OPERATION
2892 *                  The operation is invoked on an inappropriate object.
2893 * @retval DDS_RETCODE_ALREADY_DELETED
2894 *                  The entity has already been deleted.
2895 */
2896DDS_EXPORT dds_return_t
2897dds_get_inconsistent_topic_status (
2898  dds_entity_t topic,
2899  dds_inconsistent_topic_status_t * status);
2900
2901/**
2902 * @brief Get PUBLICATION_MATCHED status
2903 *
2904 * This operation gets the status value corresponding to PUBLICATION_MATCHED
2905 * and reset the status. The value can be obtained, only if the status is enabled for an entity.
2906 * NULL value for status is allowed and it will reset the trigger value when status is enabled.
2907 *
2908 * @param[in]  writer  The entity to get the status
2909 * @param[out] status  The pointer to \ref DCPS_Status_PublicationMatched to get the status
2910 *
2911 * @returns  0 - Success
2912 * @returns <0 - Failure
2913 *
2914 * @retval DDS_RETCODE_ERROR
2915 *                  An internal error has occurred.
2916 * @retval DDS_RETCODE_BAD_PARAMETER
2917 *                  One of the given arguments is not valid.
2918 * @retval DDS_RETCODE_ILLEGAL_OPERATION
2919 *                  The operation is invoked on an inappropriate object.
2920 * @retval DDS_RETCODE_ALREADY_DELETED
2921 *                  The entity has already been deleted.
2922 */
2923DDS_EXPORT dds_return_t
2924dds_get_publication_matched_status (
2925  dds_entity_t writer,
2926  dds_publication_matched_status_t * status);
2927
2928/**
2929 * @brief Get LIVELINESS_LOST status
2930 *
2931 * This operation gets the status value corresponding to LIVELINESS_LOST
2932 * and reset the status. The value can be obtained, only if the status is enabled for an entity.
2933 * NULL value for status is allowed and it will reset the trigger value when status is enabled.
2934 *
2935 * @param[in]  writer  The entity to get the status
2936 * @param[out] status  The pointer to \ref DCPS_Status_LivelinessLost to get the status
2937 *
2938 * @returns  0 - Success
2939 * @returns <0 - Failure
2940 *
2941 * @retval DDS_RETCODE_ERROR
2942 *                  An internal error has occurred.
2943 * @retval DDS_RETCODE_BAD_PARAMETER
2944 *                  One of the given arguments is not valid.
2945 * @retval DDS_RETCODE_ILLEGAL_OPERATION
2946 *                  The operation is invoked on an inappropriate object.
2947 * @retval DDS_RETCODE_ALREADY_DELETED
2948 *                  The entity has already been deleted.
2949 */
2950DDS_EXPORT dds_return_t
2951dds_get_liveliness_lost_status (
2952  dds_entity_t writer,
2953  dds_liveliness_lost_status_t * status);
2954
2955/**
2956 * @brief Get OFFERED_DEADLINE_MISSED status
2957 *
2958 * This operation gets the status value corresponding to OFFERED_DEADLINE_MISSED
2959 * and reset the status. The value can be obtained, only if the status is enabled for an entity.
2960 * NULL value for status is allowed and it will reset the trigger value when status is enabled.
2961 *
2962 * @param[in]  writer  The entity to get the status
2963 * @param[out] status  The pointer to \ref DCPS_Status_OfferedDeadlineMissed to get the status
2964 *
2965 * @returns  0 - Success
2966 * @returns <0 - Failure
2967 *
2968 * @retval DDS_RETCODE_ERROR
2969 *                  An internal error has occurred.
2970 * @retval DDS_RETCODE_BAD_PARAMETER
2971 *                  One of the given arguments is not valid.
2972 * @retval DDS_RETCODE_ILLEGAL_OPERATION
2973 *                  The operation is invoked on an inappropriate object.
2974 * @retval DDS_RETCODE_ALREADY_DELETED
2975 *                  The entity has already been deleted.
2976 */
2977DDS_EXPORT dds_return_t
2978dds_get_offered_deadline_missed_status(
2979  dds_entity_t writer,
2980  dds_offered_deadline_missed_status_t *status);
2981
2982/**
2983 * @brief Get OFFERED_INCOMPATIBLE_QOS status
2984 *
2985 * This operation gets the status value corresponding to OFFERED_INCOMPATIBLE_QOS
2986 * and reset the status. The value can be obtained, only if the status is enabled for an entity.
2987 * NULL value for status is allowed and it will reset the trigger value when status is enabled.
2988 *
2989 * @param[in]  writer  The writer entity to get the status
2990 * @param[out] status  The pointer to \ref DCPS_Status_OfferedIncompatibleQoS to get the status
2991 *
2992 * @returns  0 - Success
2993 * @returns <0 - Failure
2994 *
2995 * @retval DDS_RETCODE_ERROR
2996 *                  An internal error has occurred.
2997 * @retval DDS_RETCODE_BAD_PARAMETER
2998 *                  One of the given arguments is not valid.
2999 * @retval DDS_RETCODE_ILLEGAL_OPERATION
3000 *                  The operation is invoked on an inappropriate object.
3001 * @retval DDS_RETCODE_ALREADY_DELETED
3002 *                  The entity has already been deleted.
3003 */
3004DDS_EXPORT dds_return_t
3005dds_get_offered_incompatible_qos_status (
3006  dds_entity_t writer,
3007  dds_offered_incompatible_qos_status_t * status);
3008
3009/**
3010 * @brief Get SUBSCRIPTION_MATCHED status
3011 *
3012 * This operation gets the status value corresponding to SUBSCRIPTION_MATCHED
3013 * and reset the status. The value can be obtained, only if the status is enabled for an entity.
3014 * NULL value for status is allowed and it will reset the trigger value when status is enabled.
3015 *
3016 * @param[in]  reader  The reader entity to get the status
3017 * @param[out] status  The pointer to \ref DCPS_Status_SubscriptionMatched to get the status
3018 *
3019 * @returns  0 - Success
3020 * @returns <0 - Failure
3021 *
3022 * @retval DDS_RETCODE_ERROR
3023 *                  An internal error has occurred.
3024 * @retval DDS_RETCODE_BAD_PARAMETER
3025 *                  One of the given arguments is not valid.
3026 * @retval DDS_RETCODE_ILLEGAL_OPERATION
3027 *                  The operation is invoked on an inappropriate object.
3028 * @retval DDS_RETCODE_ALREADY_DELETED
3029 *                  The entity has already been deleted.
3030 */
3031DDS_EXPORT dds_return_t
3032dds_get_subscription_matched_status (
3033  dds_entity_t reader,
3034  dds_subscription_matched_status_t * status);
3035
3036/**
3037 * @brief Get LIVELINESS_CHANGED status
3038 *
3039 * This operation gets the status value corresponding to LIVELINESS_CHANGED
3040 * and reset the status. The value can be obtained, only if the status is enabled for an entity.
3041 * NULL value for status is allowed and it will reset the trigger value when status is enabled.
3042 *
3043 * @param[in]  reader  The entity to get the status
3044 * @param[out] status  The pointer to \ref DCPS_Status_LivelinessChanged to get the status
3045 *
3046 * @returns  0 - Success
3047 * @returns <0 - Failure
3048 *
3049 * @retval DDS_RETCODE_ERROR
3050 *                  An internal error has occurred.
3051 * @retval DDS_RETCODE_BAD_PARAMETER
3052 *                  One of the given arguments is not valid.
3053 * @retval DDS_RETCODE_ILLEGAL_OPERATION
3054 *                  The operation is invoked on an inappropriate object.
3055 * @retval DDS_RETCODE_ALREADY_DELETED
3056 *                  The entity has already been deleted.
3057 */
3058DDS_EXPORT dds_return_t
3059dds_get_liveliness_changed_status (
3060  dds_entity_t reader,
3061  dds_liveliness_changed_status_t * status);
3062
3063/**
3064 * @brief Get SAMPLE_REJECTED status
3065 *
3066 * This operation gets the status value corresponding to SAMPLE_REJECTED
3067 * and reset the status. The value can be obtained, only if the status is enabled for an entity.
3068 * NULL value for status is allowed and it will reset the trigger value when status is enabled.
3069 *
3070 * @param[in]  reader  The entity to get the status
3071 * @param[out] status  The pointer to \ref DCPS_Status_SampleRejected to get the status
3072 *
3073 * @returns  0 - Success
3074 * @returns <0 - Failure
3075 *
3076 * @retval DDS_RETCODE_ERROR
3077 *                  An internal error has occurred.
3078 * @retval DDS_RETCODE_BAD_PARAMETER
3079 *                  One of the given arguments is not valid.
3080 * @retval DDS_RETCODE_ILLEGAL_OPERATION
3081 *                  The operation is invoked on an inappropriate object.
3082 * @retval DDS_RETCODE_ALREADY_DELETED
3083 *                  The entity has already been deleted.
3084 */
3085DDS_EXPORT dds_return_t
3086dds_get_sample_rejected_status (
3087  dds_entity_t reader,
3088  dds_sample_rejected_status_t * status);
3089
3090/**
3091 * @brief Get SAMPLE_LOST status
3092 *
3093 * This operation gets the status value corresponding to SAMPLE_LOST
3094 * and reset the status. The value can be obtained, only if the status is enabled for an entity.
3095 * NULL value for status is allowed and it will reset the trigger value when status is enabled.
3096 *
3097 * @param[in]  reader  The entity to get the status
3098 * @param[out] status  The pointer to \ref DCPS_Status_SampleLost to get the status
3099 *
3100 * @returns A dds_return_t indicating success or failure
3101 *
3102 * @retval DDS_RETCODE_OK
3103 *            Success
3104 * @retval DDS_RETCODE_ERROR
3105 *            An internal error has occurred.
3106 * @retval DDS_RETCODE_BAD_PARAMETER
3107 *            One of the given arguments is not valid.
3108 * @retval DDS_RETCODE_ILLEGAL_OPERATION
3109 *            The operation is invoked on an inappropriate object.
3110 * @retval DDS_RETCODE_ALREADY_DELETED
3111 *            The entity has already been deleted.
3112 */
3113DDS_EXPORT dds_return_t
3114dds_get_sample_lost_status (
3115  dds_entity_t reader,
3116  dds_sample_lost_status_t * status);
3117
3118/**
3119 * @brief Get REQUESTED_DEADLINE_MISSED status
3120 *
3121 * This operation gets the status value corresponding to REQUESTED_DEADLINE_MISSED
3122 * and reset the status. The value can be obtained, only if the status is enabled for an entity.
3123 * NULL value for status is allowed and it will reset the trigger value when status is enabled.
3124 *
3125 * @param[in]  reader  The entity to get the status
3126 * @param[out] status  The pointer to \ref DCPS_Status_RequestedDeadlineMissed to get the status
3127 *
3128 * @returns A dds_return_t indicating success or failure
3129 *
3130 * @retval DDS_RETCODE_OK
3131 *            Success
3132 * @retval DDS_RETCODE_ERROR
3133 *            An internal error has occurred.
3134 * @retval DDS_RETCODE_BAD_PARAMETER
3135 *            One of the given arguments is not valid.
3136 * @retval DDS_RETCODE_ILLEGAL_OPERATION
3137 *            The operation is invoked on an inappropriate object.
3138 * @retval DDS_RETCODE_ALREADY_DELETED
3139 *            The entity has already been deleted.
3140 */
3141DDS_EXPORT dds_return_t
3142dds_get_requested_deadline_missed_status (
3143  dds_entity_t reader,
3144  dds_requested_deadline_missed_status_t * status);
3145
3146/**
3147 * @brief Get REQUESTED_INCOMPATIBLE_QOS status
3148 *
3149 * This operation gets the status value corresponding to REQUESTED_INCOMPATIBLE_QOS
3150 * and reset the status. The value can be obtained, only if the status is enabled for an entity.
3151 * NULL value for status is allowed and it will reset the trigger value when status is enabled.
3152 *
3153 * @param[in]  reader  The entity to get the status
3154 * @param[out] status  The pointer to \ref DCPS_Status_RequestedIncompatibleQoS to get the status
3155 *
3156 * @returns A dds_return_t indicating success or failure
3157 *
3158 * @retval DDS_RETCODE_OK
3159 *            Success
3160 * @retval DDS_RETCODE_ERROR
3161 *            An internal error has occurred.
3162 * @retval DDS_RETCODE_BAD_PARAMETER
3163 *            One of the given arguments is not valid.
3164 * @retval DDS_RETCODE_ILLEGAL_OPERATION
3165 *            The operation is invoked on an inappropriate object.
3166 * @retval DDS_RETCODE_ALREADY_DELETED
3167 *            The entity has already been deleted.
3168 */
3169DDS_EXPORT dds_return_t
3170dds_get_requested_incompatible_qos_status (
3171  dds_entity_t reader,
3172  dds_requested_incompatible_qos_status_t * status);
3173
3174#if defined (__cplusplus)
3175}
3176#endif
3177#endif
3178
3179/*
3180 * Copyright(c) 2006 to 2018 ADLINK Technology Limited and others
3181 *
3182 * This program and the accompanying materials are made available under the
3183 * terms of the Eclipse Public License v. 2.0 which is available at
3184 * http://www.eclipse.org/legal/epl-2.0, or the Eclipse Distribution License
3185 * v. 1.0 which is available at
3186 * http://www.eclipse.org/org/documents/edl-v10.php.
3187 *
3188 * SPDX-License-Identifier: EPL-2.0 OR BSD-3-Clause
3189 */
3190
3191/** @file
3192 *
3193 * @brief DDS C Listener API
3194 *
3195 * This header file defines the public API of listeners in the
3196 * Eclipse Cyclone DDS C language binding.
3197 */
3198#ifndef _DDS_PUBLIC_LISTENER_H_
3199#define _DDS_PUBLIC_LISTENER_H_
3200
3201#if defined (__cplusplus)
3202extern "C" {
3203#endif
3204
3205/* Listener callbacks */
3206typedef void (*dds_on_inconsistent_topic_fn) (dds_entity_t topic, const dds_inconsistent_topic_status_t status, void* arg);
3207typedef void (*dds_on_liveliness_lost_fn) (dds_entity_t writer, const dds_liveliness_lost_status_t status, void* arg);
3208typedef void (*dds_on_offered_deadline_missed_fn) (dds_entity_t writer, const dds_offered_deadline_missed_status_t status, void* arg);
3209typedef void (*dds_on_offered_incompatible_qos_fn) (dds_entity_t writer, const dds_offered_incompatible_qos_status_t status, void* arg);
3210typedef void (*dds_on_data_on_readers_fn) (dds_entity_t subscriber, void* arg);
3211typedef void (*dds_on_sample_lost_fn) (dds_entity_t reader, const dds_sample_lost_status_t status, void* arg);
3212typedef void (*dds_on_data_available_fn) (dds_entity_t reader, void* arg);
3213typedef void (*dds_on_sample_rejected_fn) (dds_entity_t reader, const dds_sample_rejected_status_t status, void* arg);
3214typedef void (*dds_on_liveliness_changed_fn) (dds_entity_t reader, const dds_liveliness_changed_status_t status, void* arg);
3215typedef void (*dds_on_requested_deadline_missed_fn) (dds_entity_t reader, const dds_requested_deadline_missed_status_t status, void* arg);
3216typedef void (*dds_on_requested_incompatible_qos_fn) (dds_entity_t reader, const dds_requested_incompatible_qos_status_t status, void* arg);
3217typedef void (*dds_on_publication_matched_fn) (dds_entity_t writer, const dds_publication_matched_status_t  status, void* arg);
3218typedef void (*dds_on_subscription_matched_fn) (dds_entity_t reader, const dds_subscription_matched_status_t  status, void* arg);
3219
3220#define DDS_LUNSET 0
3221struct dds_listener;
3222typedef struct dds_listener dds_listener_t;
3223
3224/**
3225 * @brief Allocate memory and initializes to default values (::DDS_LUNSET) of a listener
3226 *
3227 * @param[in] arg optional pointer that will be passed on to the listener callbacks
3228 *
3229 * @return Returns a pointer to the allocated memory for dds_listener_t structure.
3230 */
3231DDS_EXPORT dds_listener_t* dds_create_listener (void* arg);
3232DDS_DEPRECATED_EXPORT dds_listener_t* dds_listener_create (void* arg);
3233
3234/**
3235 * @brief Delete the memory allocated to listener structure
3236 *
3237 * @param[in] listener pointer to the listener struct to delete
3238 */
3239DDS_EXPORT void dds_delete_listener (dds_listener_t * __restrict listener);
3240DDS_DEPRECATED_EXPORT void dds_listener_delete (dds_listener_t * __restrict listener);
3241
3242/**
3243 * @brief Reset the listener structure contents to ::DDS_LUNSET
3244 *
3245 * @param[in,out] listener pointer to the listener struct to reset
3246 */
3247DDS_EXPORT void dds_reset_listener (dds_listener_t * __restrict listener);
3248DDS_DEPRECATED_EXPORT void dds_listener_reset (dds_listener_t * __restrict listener);
3249
3250/**
3251 * @brief Copy the listener callbacks from source to destination
3252 *
3253 * @param[in,out] dst The pointer to the destination listener structure, where the content is to copied
3254 * @param[in] src The pointer to the source listener structure to be copied
3255 */
3256DDS_EXPORT void dds_copy_listener (dds_listener_t * __restrict dst, const dds_listener_t * __restrict src);
3257DDS_DEPRECATED_EXPORT void dds_listener_copy (dds_listener_t * __restrict dst, const dds_listener_t * __restrict src);
3258
3259/**
3260 * @brief Copy the listener callbacks from source to destination, unless already set
3261 *
3262 * Any listener callbacks already set in @p dst (including NULL) are skipped, only
3263 * those set to DDS_LUNSET are copied from @p src.
3264 *
3265 * @param[in,out] dst The pointer to the destination listener structure, where the content is merged
3266 * @param[in] src The pointer to the source listener structure to be copied
3267 */
3268DDS_EXPORT void dds_merge_listener (dds_listener_t * __restrict dst, const dds_listener_t * __restrict src);
3269DDS_DEPRECATED_EXPORT void dds_listener_merge (dds_listener_t * __restrict dst, const dds_listener_t * __restrict src);
3270
3271/************************************************************************************************
3272 *  Setters
3273 ************************************************************************************************/
3274
3275/**
3276 * @brief Set the inconsistent_topic callback in the listener structure.
3277 *
3278 * @param listener The pointer to the listener structure, where the callback will be set
3279 * @param callback The callback to set in the listener, can be NULL, ::DDS_LUNSET or a valid callback pointer
3280 */
3281DDS_EXPORT void dds_lset_inconsistent_topic (dds_listener_t * __restrict listener, dds_on_inconsistent_topic_fn callback);
3282
3283/**
3284 * @brief Set the liveliness_lost callback in the listener structure.
3285 *
3286 * @param[out] listener The pointer to the listener structure, where the callback will be set
3287 * @param[in] callback The callback to set in the listener, can be NULL, ::DDS_LUNSET or a valid callback pointer
3288 */
3289DDS_EXPORT void dds_lset_liveliness_lost (dds_listener_t * __restrict listener, dds_on_liveliness_lost_fn callback);
3290
3291/**
3292 * @brief Set the offered_deadline_missed callback in the listener structure.
3293 *
3294 * @param[in,out] listener The pointer to the listener structure, where the callback will be set
3295 * @param[in] callback The callback to set in the listener, can be NULL, ::DDS_LUNSET or a valid callback pointer
3296 */
3297DDS_EXPORT void dds_lset_offered_deadline_missed (dds_listener_t * __restrict listener, dds_on_offered_deadline_missed_fn callback);
3298
3299/**
3300 * @brief Set the offered_incompatible_qos callback in the listener structure.
3301 *
3302 * @param[in,out] listener The pointer to the listener structure, where the callback will be set
3303 * @param[in] callback The callback to set in the listener, can be NULL, ::DDS_LUNSET or a valid callback pointer
3304 */
3305DDS_EXPORT void dds_lset_offered_incompatible_qos (dds_listener_t * __restrict listener, dds_on_offered_incompatible_qos_fn callback);
3306
3307/**
3308 * @brief Set the data_on_readers callback in the listener structure.
3309 *
3310 * @param[in,out] listener The pointer to the listener structure, where the callback will be set
3311 * @param[in] callback The callback to set in the listener, can be NULL, ::DDS_LUNSET or a valid callback pointer
3312 */
3313DDS_EXPORT void dds_lset_data_on_readers (dds_listener_t * __restrict listener, dds_on_data_on_readers_fn callback);
3314
3315/**
3316 * @brief Set the sample_lost callback in the listener structure.
3317 *
3318 * @param[in,out] listener The pointer to the listener structure, where the callback will be set
3319 * @param[in] callback The callback to set in the listener, can be NULL, ::DDS_LUNSET or a valid callback pointer
3320 */
3321DDS_EXPORT void dds_lset_sample_lost (dds_listener_t * __restrict listener, dds_on_sample_lost_fn callback);
3322
3323/**
3324 * @brief Set the data_available callback in the listener structure.
3325 *
3326 * @param[in,out] listener The pointer to the listener structure, where the callback will be set
3327 * @param[in] callback The callback to set in the listener, can be NULL, ::DDS_LUNSET or a valid callback pointer
3328 */
3329DDS_EXPORT void dds_lset_data_available (dds_listener_t * __restrict listener, dds_on_data_available_fn callback);
3330
3331/**
3332 * @brief Set the sample_rejected callback in the listener structure.
3333 *
3334 * @param[in,out] listener The pointer to the listener structure, where the callback will be set
3335 * @param[in] callback The callback to set in the listener, can be NULL, ::DDS_LUNSET or a valid callback pointer
3336 */
3337DDS_EXPORT void dds_lset_sample_rejected (dds_listener_t * __restrict listener, dds_on_sample_rejected_fn callback);
3338
3339/**
3340 * @brief Set the liveliness_changed callback in the listener structure.
3341 *
3342 * @param[in,out] listener The pointer to the listener structure, where the callback will be set
3343 * @param[in] callback The callback to set in the listener, can be NULL, ::DDS_LUNSET or a valid callback pointer
3344 */
3345DDS_EXPORT void dds_lset_liveliness_changed (dds_listener_t * __restrict listener, dds_on_liveliness_changed_fn callback);
3346
3347/**
3348 * @brief Set the requested_deadline_missed callback in the listener structure.
3349 *
3350 * @param[in,out] listener The pointer to the listener structure, where the callback will be set
3351 * @param[in] callback The callback to set in the listener, can be NULL, ::DDS_LUNSET or a valid callback pointer
3352 */
3353DDS_EXPORT void dds_lset_requested_deadline_missed (dds_listener_t * __restrict listener, dds_on_requested_deadline_missed_fn callback);
3354
3355/**
3356 * @brief Set the requested_incompatible_qos callback in the listener structure.
3357 *
3358 * @param[in,out] listener The pointer to the listener structure, where the callback will be set
3359 * @param[in] callback The callback to set in the listener, can be NULL, ::DDS_LUNSET or a valid callback pointer
3360 */
3361DDS_EXPORT void dds_lset_requested_incompatible_qos (dds_listener_t * __restrict listener, dds_on_requested_incompatible_qos_fn callback);
3362
3363/**
3364 * @brief Set the publication_matched callback in the listener structure.
3365 *
3366 * @param[in,out] listener The pointer to the listener structure, where the callback will be set
3367 * @param[in] callback The callback to set in the listener, can be NULL, ::DDS_LUNSET or a valid callback pointer
3368 */
3369DDS_EXPORT void dds_lset_publication_matched (dds_listener_t * __restrict listener, dds_on_publication_matched_fn callback);
3370
3371/**
3372 * @brief Set the subscription_matched callback in the listener structure.
3373 *
3374 * @param[in,out] listener The pointer to the listener structure, where the callback will be set
3375 * @param[in] callback The callback to set in the listener, can be NULL, ::DDS_LUNSET or a valid callback pointer
3376 */
3377DDS_EXPORT void dds_lset_subscription_matched (dds_listener_t * __restrict listener, dds_on_subscription_matched_fn callback);
3378
3379/************************************************************************************************
3380 *  Getters
3381 ************************************************************************************************/
3382
3383/**
3384 * @brief Get the inconsistent_topic callback from the listener structure.
3385 *
3386 * @param[in] listener The pointer to the listener structure, where the callback will be retrieved from
3387 * @param[in,out] callback Pointer where the retrieved callback can be stored; can be NULL, ::DDS_LUNSET or a valid callback pointer
3388 */
3389DDS_EXPORT void dds_lget_inconsistent_topic (const dds_listener_t * __restrict listener, dds_on_inconsistent_topic_fn *callback);
3390
3391/**
3392 * @brief Get the liveliness_lost callback from the listener structure.
3393 *
3394 * @param[in] listener The pointer to the listener structure, where the callback will be retrieved from
3395 * @param[in,out] callback Pointer where the retrieved callback can be stored; can be NULL, ::DDS_LUNSET or a valid callback pointer
3396 */
3397DDS_EXPORT void dds_lget_liveliness_lost (const dds_listener_t * __restrict listener, dds_on_liveliness_lost_fn *callback);
3398
3399/**
3400 * @brief Get the offered_deadline_missed callback from the listener structure.
3401 *
3402 * @param[in] listener The pointer to the listener structure, where the callback will be retrieved from
3403 * @param[in,out] callback Pointer where the retrieved callback can be stored; can be NULL, ::DDS_LUNSET or a valid callback pointer
3404 */
3405DDS_EXPORT void dds_lget_offered_deadline_missed (const dds_listener_t * __restrict listener, dds_on_offered_deadline_missed_fn *callback);
3406
3407/**
3408 * @brief Get the offered_incompatible_qos callback from the listener structure.
3409 *
3410 * @param[in] listener The pointer to the listener structure, where the callback will be retrieved from
3411 * @param[in,out] callback Pointer where the retrieved callback can be stored; can be NULL, ::DDS_LUNSET or a valid callback pointer
3412 */
3413DDS_EXPORT void dds_lget_offered_incompatible_qos (const dds_listener_t * __restrict listener, dds_on_offered_incompatible_qos_fn *callback);
3414
3415/**
3416 * @brief Get the data_on_readers callback from the listener structure.
3417 *
3418 * @param[in] listener The pointer to the listener structure, where the callback will be retrieved from
3419 * @param[in,out] callback Pointer where the retrieved callback can be stored; can be NULL, ::DDS_LUNSET or a valid callback pointer
3420 */
3421DDS_EXPORT void dds_lget_data_on_readers (const dds_listener_t * __restrict listener, dds_on_data_on_readers_fn *callback);
3422
3423/**
3424 * @brief Get the sample_lost callback from the listener structure.
3425 *
3426 * @param[in] listener The pointer to the listener structure, where the callback will be retrieved from
3427 * @param[in,out] callback Pointer where the retrieved callback can be stored; can be NULL, ::DDS_LUNSET or a valid callback pointer
3428 */
3429DDS_EXPORT void dds_lget_sample_lost (const dds_listener_t *__restrict listener, dds_on_sample_lost_fn *callback);
3430
3431/**
3432 * @brief Get the data_available callback from the listener structure.
3433 *
3434 * @param[in] listener The pointer to the listener structure, where the callback will be retrieved from
3435 * @param[in,out] callback Pointer where the retrieved callback can be stored; can be NULL, ::DDS_LUNSET or a valid callback pointer
3436 */
3437DDS_EXPORT void dds_lget_data_available (const dds_listener_t *__restrict listener, dds_on_data_available_fn *callback);
3438
3439/**
3440 * @brief Get the sample_rejected callback from the listener structure.
3441 *
3442 * @param[in] listener The pointer to the listener structure, where the callback will be retrieved from
3443 * @param[in,out] callback Pointer where the retrieved callback can be stored; can be NULL, ::DDS_LUNSET or a valid callback pointer
3444 */
3445DDS_EXPORT void dds_lget_sample_rejected (const dds_listener_t  *__restrict listener, dds_on_sample_rejected_fn *callback);
3446
3447/**
3448 * @brief Get the liveliness_changed callback from the listener structure.
3449 *
3450 * @param[in] listener The pointer to the listener structure, where the callback will be retrieved from
3451 * @param[in,out] callback Pointer where the retrieved callback can be stored; can be NULL, ::DDS_LUNSET or a valid callback pointer
3452 */
3453DDS_EXPORT void dds_lget_liveliness_changed (const dds_listener_t * __restrict listener, dds_on_liveliness_changed_fn *callback);
3454
3455/**
3456 * @brief Get the requested_deadline_missed callback from the listener structure.
3457 *
3458 * @param[in] listener The pointer to the listener structure, where the callback will be retrieved from
3459 * @param[in,out] callback Pointer where the retrieved callback can be stored; can be NULL, ::DDS_LUNSET or a valid callback pointer
3460 */
3461DDS_EXPORT void dds_lget_requested_deadline_missed (const dds_listener_t * __restrict listener, dds_on_requested_deadline_missed_fn *callback);
3462
3463/**
3464 * @brief Get the requested_incompatible_qos callback from the listener structure.
3465 *
3466 * @param[in] listener The pointer to the listener structure, where the callback will be retrieved from
3467 * @param[in,out] callback Pointer where the retrieved callback can be stored; can be NULL, ::DDS_LUNSET or a valid callback pointer
3468 */
3469DDS_EXPORT void dds_lget_requested_incompatible_qos (const dds_listener_t * __restrict listener, dds_on_requested_incompatible_qos_fn *callback);
3470
3471/**
3472 * @brief Get the publication_matched callback from the listener structure.
3473 *
3474 * @param[in] listener The pointer to the listener structure, where the callback will be retrieved from
3475 * @param[in,out] callback Pointer where the retrieved callback can be stored; can be NULL, ::DDS_LUNSET or a valid callback pointer
3476 */
3477DDS_EXPORT void dds_lget_publication_matched (const dds_listener_t * __restrict listener, dds_on_publication_matched_fn *callback);
3478
3479/**
3480 * @brief Get the subscription_matched callback from the listener structure.
3481 *
3482 * @param[in] callback Pointer where the retrieved callback can be stored; can be NULL, ::DDS_LUNSET or a valid callback pointer
3483 * @param[in,out] listener The pointer to the listener structure, where the callback will be retrieved from
3484 */
3485DDS_EXPORT void dds_lget_subscription_matched (const dds_listener_t * __restrict listener, dds_on_subscription_matched_fn *callback);
3486
3487#if defined (__cplusplus)
3488}
3489#endif
3490
3491#endif /*_DDS_PUBLIC_LISTENER_H_*/
3492
3493#if defined (__cplusplus)
3494extern "C" {
3495#endif
3496
3497struct dds_rhc;
3498struct ddsi_plist;
3499struct ddsi_sertype;
3500struct ddsi_serdata;
3501struct ddsi_sertopic; // deprecated, binary compatibility only
3502
3503#define DDS_MIN_PSEUDO_HANDLE ((dds_entity_t) 0x7fff0000)
3504
3505/** Indicates that the library uses ddsi_sertype (as a replacement for ddsi_sertopic). If sertype
3506 *  is used, the function dds_create_topic_sertype requires a topic name parameter, as this field
3507 *  is not included in ddsi_sertype. */
3508#define DDS_HAS_DDSI_SERTYPE 1
3509
3510/* @defgroup builtintopic_constants Convenience constants for referring to builtin topics
3511 *
3512 * These constants can be used in place of an actual dds_topic_t, when creating
3513 * readers or writers for builtin-topics.
3514 *
3515 * @{
3516 */
3517#define DDS_BUILTIN_TOPIC_DCPSPARTICIPANT  ((dds_entity_t) (DDS_MIN_PSEUDO_HANDLE + 1))
3518#define DDS_BUILTIN_TOPIC_DCPSTOPIC        ((dds_entity_t) (DDS_MIN_PSEUDO_HANDLE + 2))
3519#define DDS_BUILTIN_TOPIC_DCPSPUBLICATION  ((dds_entity_t) (DDS_MIN_PSEUDO_HANDLE + 3))
3520#define DDS_BUILTIN_TOPIC_DCPSSUBSCRIPTION ((dds_entity_t) (DDS_MIN_PSEUDO_HANDLE + 4))
3521/** @}*/
3522
3523/** Special handle representing the entity corresponding to the CycloneDDS library itself */
3524#define DDS_CYCLONEDDS_HANDLE              ((dds_entity_t) (DDS_MIN_PSEUDO_HANDLE + 256))
3525
3526/** @name Communication Status definitions
3527  @{**/
3528typedef enum dds_status_id {
3529  DDS_INCONSISTENT_TOPIC_STATUS_ID,
3530  DDS_OFFERED_DEADLINE_MISSED_STATUS_ID,
3531  DDS_REQUESTED_DEADLINE_MISSED_STATUS_ID,
3532  DDS_OFFERED_INCOMPATIBLE_QOS_STATUS_ID,
3533  DDS_REQUESTED_INCOMPATIBLE_QOS_STATUS_ID,
3534  DDS_SAMPLE_LOST_STATUS_ID,
3535  DDS_SAMPLE_REJECTED_STATUS_ID,
3536  DDS_DATA_ON_READERS_STATUS_ID,
3537  DDS_DATA_AVAILABLE_STATUS_ID,
3538  DDS_LIVELINESS_LOST_STATUS_ID,
3539  DDS_LIVELINESS_CHANGED_STATUS_ID,
3540  DDS_PUBLICATION_MATCHED_STATUS_ID,
3541  DDS_SUBSCRIPTION_MATCHED_STATUS_ID
3542} dds_status_id_t;
3543#define DDS_STATUS_ID_MAX (DDS_SUBSCRIPTION_MATCHED_STATUS_ID)
3544
3545/** Another topic exists with the same name but with different characteristics. */
3546#define DDS_INCONSISTENT_TOPIC_STATUS          (1u << DDS_INCONSISTENT_TOPIC_STATUS_ID)
3547/** The deadline that the writer has committed through its deadline QoS policy was not respected for a specific instance. */
3548#define DDS_OFFERED_DEADLINE_MISSED_STATUS     (1u << DDS_OFFERED_DEADLINE_MISSED_STATUS_ID)
3549/** The deadline that the reader was expecting through its deadline QoS policy was not respected for a specific instance. */
3550#define DDS_REQUESTED_DEADLINE_MISSED_STATUS   (1u << DDS_REQUESTED_DEADLINE_MISSED_STATUS_ID)
3551/** A QoS policy setting was incompatible with what was requested. */
3552#define DDS_OFFERED_INCOMPATIBLE_QOS_STATUS    (1u << DDS_OFFERED_INCOMPATIBLE_QOS_STATUS_ID)
3553/** A QoS policy setting was incompatible with what is offered. */
3554#define DDS_REQUESTED_INCOMPATIBLE_QOS_STATUS  (1u << DDS_REQUESTED_INCOMPATIBLE_QOS_STATUS_ID)
3555/** A sample has been lost (never received). */
3556#define DDS_SAMPLE_LOST_STATUS                 (1u << DDS_SAMPLE_LOST_STATUS_ID)
3557/** A (received) sample has been rejected. */
3558#define DDS_SAMPLE_REJECTED_STATUS             (1u << DDS_SAMPLE_REJECTED_STATUS_ID)
3559/** New information is available. */
3560#define DDS_DATA_ON_READERS_STATUS             (1u << DDS_DATA_ON_READERS_STATUS_ID)
3561/** New information is available. */
3562#define DDS_DATA_AVAILABLE_STATUS              (1u << DDS_DATA_AVAILABLE_STATUS_ID)
3563/** The liveliness that the DDS_DataWriter has committed through its liveliness QoS policy was not respected; thus readers will consider the writer as no longer "alive". */
3564#define DDS_LIVELINESS_LOST_STATUS             (1u << DDS_LIVELINESS_LOST_STATUS_ID)
3565/** The liveliness of one or more writers, that were writing instances read through the readers has changed. Some writers have become "alive" or "not alive". */
3566#define DDS_LIVELINESS_CHANGED_STATUS          (1u << DDS_LIVELINESS_CHANGED_STATUS_ID)
3567/** The writer has found a reader that matches the topic and has a compatible QoS. */
3568#define DDS_PUBLICATION_MATCHED_STATUS         (1u << DDS_PUBLICATION_MATCHED_STATUS_ID)
3569/** The reader has found a writer that matches the topic and has a compatible QoS. */
3570#define DDS_SUBSCRIPTION_MATCHED_STATUS        (1u << DDS_SUBSCRIPTION_MATCHED_STATUS_ID)
3571/** @}*/
3572
3573/** Read state for a data value */
3574typedef enum dds_sample_state
3575{
3576  DDS_SST_READ = DDS_READ_SAMPLE_STATE, /**<DataReader has already accessed the sample by read */
3577  DDS_SST_NOT_READ = DDS_NOT_READ_SAMPLE_STATE /**<DataReader has not accessed the sample before */
3578}
3579dds_sample_state_t;
3580
3581/** View state of an instance relative to the samples */
3582typedef enum dds_view_state
3583{
3584  /** DataReader is accessing the sample for the first time when the instance is alive */
3585  DDS_VST_NEW = DDS_NEW_VIEW_STATE,
3586  /** DataReader accessed the sample before */
3587  DDS_VST_OLD = DDS_NOT_NEW_VIEW_STATE
3588}
3589dds_view_state_t;
3590
3591/** Defines the state of the instance */
3592typedef enum dds_instance_state
3593{
3594  /** Samples received for the instance from the live data writers */
3595  DDS_IST_ALIVE = DDS_ALIVE_INSTANCE_STATE,
3596  /** Instance was explicitly disposed by the data writer */
3597  DDS_IST_NOT_ALIVE_DISPOSED = DDS_NOT_ALIVE_DISPOSED_INSTANCE_STATE,
3598  /** Instance has been declared as not alive by data reader as there are no live data writers writing that instance */
3599  DDS_IST_NOT_ALIVE_NO_WRITERS = DDS_NOT_ALIVE_NO_WRITERS_INSTANCE_STATE
3600}
3601dds_instance_state_t;
3602
3603/** Contains information about the associated data value */
3604typedef struct dds_sample_info
3605{
3606  /** Sample state */
3607  dds_sample_state_t sample_state;
3608  /** View state */
3609  dds_view_state_t view_state;
3610  /** Instance state */
3611  dds_instance_state_t instance_state;
3612  /** Indicates whether there is a data associated with a sample
3613   *  - true, indicates the data is valid
3614   *  - false, indicates the data is invalid, no data to read */
3615  bool valid_data;
3616  /** timestamp of a data instance when it is written */
3617  dds_time_t source_timestamp;
3618  /** handle to the data instance */
3619  dds_instance_handle_t instance_handle;
3620  /** handle to the publisher */
3621  dds_instance_handle_t publication_handle;
3622  /** count of instance state change from NOT_ALIVE_DISPOSED to ALIVE */
3623  uint32_t disposed_generation_count;
3624  /** count of instance state change from NOT_ALIVE_NO_WRITERS to ALIVE */
3625  uint32_t no_writers_generation_count;
3626  /** indicates the number of samples of the same instance that follow the current one in the collection */
3627  uint32_t sample_rank;
3628  /** difference in generations between the sample and most recent sample of the same instance that appears in the returned collection */
3629  uint32_t generation_rank;
3630  /** difference in generations between the sample and most recent sample of the same instance when read/take was called */
3631  uint32_t absolute_generation_rank;
3632}
3633dds_sample_info_t;
3634
3635typedef struct dds_builtintopic_guid
3636{
3637  uint8_t v[16];
3638}
3639dds_builtintopic_guid_t;
3640
3641/* "dds_builtintopic_guid_t" is a bit of a weird name for what everyone just calls a GUID,
3642   so let us try and switch to using the more logical one */
3643typedef struct dds_builtintopic_guid dds_guid_t;
3644
3645typedef struct dds_builtintopic_participant
3646{
3647  dds_guid_t key;
3648  dds_qos_t *qos;
3649}
3650dds_builtintopic_participant_t;
3651
3652typedef struct dds_builtintopic_endpoint
3653{
3654  dds_guid_t key;
3655  dds_guid_t participant_key;
3656  dds_instance_handle_t participant_instance_handle;
3657  char *topic_name;
3658  char *type_name;
3659  dds_qos_t *qos;
3660}
3661dds_builtintopic_endpoint_t;
3662
3663/*
3664  All entities are represented by a process-private handle, with one
3665  call to enable an entity when it was created disabled.
3666  An entity is created enabled by default.
3667  Note: disabled creation is currently not supported.
3668*/
3669
3670/**
3671 * @brief Enable entity.
3672 *
3673 * @note Delayed entity enabling is not supported yet (CHAM-96).
3674 *
3675 * This operation enables the dds_entity_t. Created dds_entity_t objects can start in
3676 * either an enabled or disabled state. This is controlled by the value of the
3677 * entityfactory policy on the corresponding parent entity for the given
3678 * entity. Enabled entities are immediately activated at creation time meaning
3679 * all their immutable QoS settings can no longer be changed. Disabled Entities are not
3680 * yet activated, so it is still possible to change their immutable QoS settings. However,
3681 * once activated the immutable QoS settings can no longer be changed.
3682 * Creating disabled entities can make sense when the creator of the DDS_Entity
3683 * does not yet know which QoS settings to apply, thus allowing another piece of code
3684 * to set the QoS later on.
3685 *
3686 * The default setting of DDS_EntityFactoryQosPolicy is such that, by default,
3687 * entities are created in an enabled state so that it is not necessary to explicitly call
3688 * dds_enable on newly-created entities.
3689 *
3690 * The dds_enable operation produces the same results no matter how
3691 * many times it is performed. Calling dds_enable on an already
3692 * enabled DDS_Entity returns DDS_RETCODE_OK and has no effect.
3693 *
3694 * If an Entity has not yet been enabled, the only operations that can be invoked
3695 * on it are: the ones to set, get or copy the QosPolicy settings, the ones that set
3696 * (or get) the Listener, the ones that get the Status and the dds_get_status_changes
3697 * operation (although the status of a disabled entity never changes). Other operations
3698 * will return the error DDS_RETCODE_NOT_ENABLED.
3699 *
3700 * Entities created with a parent that is disabled, are created disabled regardless of
3701 * the setting of the entityfactory policy.
3702 *
3703 * If the entityfactory policy has autoenable_created_entities
3704 * set to TRUE, the dds_enable operation on the parent will
3705 * automatically enable all child entities created with the parent.
3706 *
3707 * The Listeners associated with an Entity are not called until the
3708 * Entity is enabled. Conditions associated with an Entity that
3709 * is not enabled are "inactive", that is, have a trigger_value which is FALSE.
3710 *
3711 * @param[in]  entity  The entity to enable.
3712 *
3713 * @returns A dds_return_t indicating success or failure.
3714 *
3715 * @retval DDS_RETCODE_OK
3716 *             The listeners of to the entity have been successfully been copied
3717 *             into the specified listener parameter.
3718 * @retval DDS_RETCODE_ERROR
3719 *             An internal error has occurred.
3720 * @retval DDS_RETCODE_ILLEGAL_OPERATION
3721 *             The operation is invoked on an inappropriate object.
3722 * @retval DDS_RETCODE_ALREADY_DELETED
3723 *             The entity has already been deleted.
3724 * @retval DDS_RETCODE_PRECONDITION_NOT_MET
3725 *             The parent of the given Entity is not enabled.
3726 */
3727DDS_EXPORT dds_return_t
3728dds_enable(dds_entity_t entity);
3729
3730/*
3731  All entities are represented by a process-private handle, with one
3732  call to delete an entity and all entities it logically contains.
3733  That is, it is equivalent to combination of
3734  delete_contained_entities and delete_xxx in the DCPS API.
3735*/
3736
3737/**
3738 * @brief Delete given entity.
3739 *
3740 * This operation will delete the given entity. It will also automatically
3741 * delete all its children, childrens' children, etc entities.
3742 *
3743 * @param[in]  entity  Entity to delete.
3744 *
3745 * @returns A dds_return_t indicating success or failure.
3746 *
3747 * @retval DDS_RETCODE_OK
3748 *             The entity and its children (recursive are deleted).
3749 * @retval DDS_RETCODE_ERROR
3750 *             An internal error has occurred.
3751 * @retval DDS_RETCODE_ILLEGAL_OPERATION
3752 *             The operation is invoked on an inappropriate object.
3753 * @retval DDS_RETCODE_ALREADY_DELETED
3754 *             The entity has already been deleted.
3755 */
3756/* TODO: Link to generic dds entity relations documentation. */
3757DDS_EXPORT dds_return_t
3758dds_delete(dds_entity_t entity);
3759
3760/**
3761 * @brief Get entity publisher.
3762 *
3763 * This operation returns the publisher to which the given entity belongs.
3764 * For instance, it will return the Publisher that was used when
3765 * creating a DataWriter (when that DataWriter was provided here).
3766 *
3767 * @param[in]  writer  Entity from which to get its publisher.
3768 *
3769 * @returns A valid entity or an error code.
3770 *
3771 * @retval >0
3772 *             A valid publisher handle.
3773 * @retval DDS_RETCODE_ERROR
3774 *             An internal error has occurred.
3775 * @retval DDS_RETCODE_ILLEGAL_OPERATION
3776 *             The operation is invoked on an inappropriate object.
3777 * @retval DDS_RETCODE_ALREADY_DELETED
3778 *             The entity has already been deleted.
3779 */
3780/* TODO: Link to generic dds entity relations documentation. */
3781DDS_EXPORT dds_entity_t
3782dds_get_publisher(dds_entity_t writer);
3783
3784/**
3785 * @brief Get entity subscriber.
3786 *
3787 * This operation returns the subscriber to which the given entity belongs.
3788 * For instance, it will return the Subscriber that was used when
3789 * creating a DataReader (when that DataReader was provided here).
3790 *
3791 * @param[in]  entity  Entity from which to get its subscriber.
3792 *
3793 * @returns A valid subscriber handle or an error code.
3794 *
3795 * @retval >0
3796 *             A valid subscriber handle.
3797 * @retval DDS_RETCODE_ERROR
3798 *             An internal error has occurred.
3799 * @retval DDS_RETCODE_ILLEGAL_OPERATION
3800 *             The operation is invoked on an inappropriate object.
3801 * @retval DDS_RETCODE_ALREADY_DELETED
3802 *             The entity has already been deleted.
3803 */
3804/* TODO: Link to generic dds entity relations documentation. */
3805DDS_EXPORT dds_entity_t
3806dds_get_subscriber(dds_entity_t entity);
3807
3808/**
3809 * @brief Get entity datareader.
3810 *
3811 * This operation returns the datareader to which the given entity belongs.
3812 * For instance, it will return the DataReader that was used when
3813 * creating a ReadCondition (when that ReadCondition was provided here).
3814 *
3815 * @param[in]  condition  Entity from which to get its datareader.
3816 *
3817 * @returns A valid reader handle or an error code.
3818 *
3819 * @retval >0
3820 *             A valid reader handle.
3821 * @retval DDS_RETCODE_ERROR
3822 *             An internal error has occurred.
3823 * @retval DDS_RETCODE_ILLEGAL_OPERATION
3824 *             The operation is invoked on an inappropriate object.
3825 * @retval DDS_RETCODE_ALREADY_DELETED
3826 *             The entity has already been deleted.
3827 */
3828/* TODO: Link to generic dds entity relations documentation. */
3829DDS_EXPORT dds_entity_t
3830dds_get_datareader(dds_entity_t condition);
3831
3832/**
3833 * @brief Get the mask of a condition.
3834 *
3835 * This operation returns the mask that was used to create the given
3836 * condition.
3837 *
3838 * @param[in]  condition  Read or Query condition that has a mask.
3839 *
3840 * @returns A dds_return_t indicating success or failure.
3841 *
3842 * @retval DDS_RETCODE_OK
3843 *             Success (given mask is set).
3844 * @retval DDS_RETCODE_ERROR
3845 *             An internal error has occurred.
3846 * @retval DDS_RETCODE_BAD_PARAMETER
3847 *             The mask arg is NULL.
3848 * @retval DDS_RETCODE_ILLEGAL_OPERATION
3849 *             The operation is invoked on an inappropriate object.
3850 * @retval DDS_RETCODE_ALREADY_DELETED
3851 *             The entity has already been deleted.
3852 */
3853DDS_EXPORT dds_return_t
3854dds_get_mask(dds_entity_t condition, uint32_t *mask);
3855
3856/**
3857 * @brief Returns the instance handle that represents the entity.
3858 *
3859 * @param[in]   entity  Entity of which to get the instance handle.
3860 * @param[out]  ihdl    Pointer to dds_instance_handle_t.
3861 *
3862 * @returns A dds_return_t indicating success or failure.
3863 *
3864 * @retval DDS_RETCODE_OK
3865 *             Success.
3866 * @retval DDS_RETCODE_ERROR
3867 *             An internal error has occurred.
3868 */
3869/* TODO: Check list of return codes is complete. */
3870DDS_EXPORT dds_return_t
3871dds_get_instance_handle(dds_entity_t entity, dds_instance_handle_t *ihdl);
3872
3873/**
3874 * @brief Returns the GUID that represents the entity in the network,
3875 * and therefore only supports participants, readers and writers.
3876 *
3877 * @param[in]   entity  Entity of which to get the instance handle.
3878 * @param[out]  guid    Where to store the GUID.
3879 *
3880 * @returns A dds_return_t indicating success or failure.
3881 *
3882 * @retval DDS_RETCODE_OK
3883 *             Success.
3884 * @retval DDS_RETCODE_ILLEGAL_OPERATION
3885 *             The operation is invoked on an inappropriate object.
3886 * @retval DDS_RETCODE_ERROR
3887 *             An internal error has occurred.
3888 */
3889/* TODO: Check list of return codes is complete. */
3890DDS_EXPORT dds_return_t
3891dds_get_guid (dds_entity_t entity, dds_guid_t *guid);
3892
3893/*
3894  All entities have a set of "status conditions" (following the DCPS
3895  spec), read peeks, take reads & resets (analogously to read & take
3896  operations on reader). The "mask" allows operating only on a subset
3897  of the statuses. Enabled status analogously to DCPS spec.
3898*/
3899
3900/**
3901 * @brief Read the status set for the entity
3902 *
3903 * This operation reads the status(es) set for the entity based on
3904 * the enabled status and mask set. It does not clear the read status(es).
3905 *
3906 * @param[in]  entity  Entity on which the status has to be read.
3907 * @param[out] status  Returns the status set on the entity, based on the enabled status.
3908 * @param[in]  mask    Filter the status condition to be read (can be NULL).
3909 *
3910 * @returns A dds_return_t indicating success or failure.
3911 *
3912 * @retval DDS_RETCODE_OK
3913 *             Success.
3914 * @retval DDS_RETCODE_BAD_PARAMETER
3915 *             The entity parameter is not a valid parameter.
3916 * @retval DDS_RETCODE_ILLEGAL_OPERATION
3917 *             The operation is invoked on an inappropriate object.
3918 * @retval DDS_RETCODE_ALREADY_DELETED
3919 *             The entity has already been deleted.
3920 */
3921DDS_EXPORT dds_return_t
3922dds_read_status(dds_entity_t entity, uint32_t *status, uint32_t mask);
3923
3924/**
3925 * @brief Read the status set for the entity
3926 *
3927 * This operation reads the status(es) set for the entity based on the enabled
3928 * status and mask set. It clears the status set after reading.
3929 *
3930 * @param[in]  entity  Entity on which the status has to be read.
3931 * @param[out] status  Returns the status set on the entity, based on the enabled status.
3932 * @param[in]  mask    Filter the status condition to be read (can be NULL).
3933 *
3934 * @returns A dds_return_t indicating success or failure.
3935 *
3936 * @retval DDS_RETCODE_OK
3937 *             Success.
3938 * @retval DDS_RETCODE_BAD_PARAMETER
3939 *             The entity parameter is not a valid parameter.
3940 * @retval DDS_RETCODE_ILLEGAL_OPERATION
3941 *             The operation is invoked on an inappropriate object.
3942 * @retval DDS_RETCODE_ALREADY_DELETED
3943 *             The entity has already been deleted.
3944 */
3945DDS_EXPORT dds_return_t
3946dds_take_status(dds_entity_t entity, uint32_t *status, uint32_t mask);
3947
3948/**
3949 * @brief Get changed status(es)
3950 *
3951 * This operation returns the status changes since they were last read.
3952 *
3953 * @param[in]  entity  Entity on which the statuses are read.
3954 * @param[out] status  Returns the current set of triggered statuses.
3955 *
3956 * @returns A dds_return_t indicating success or failure.
3957 *
3958 * @retval DDS_RETCODE_OK
3959 *             Success.
3960 * @retval DDS_RETCODE_BAD_PARAMETER
3961 *             The entity parameter is not a valid parameter.
3962 * @retval DDS_RETCODE_ILLEGAL_OPERATION
3963 *             The operation is invoked on an inappropriate object.
3964 * @retval DDS_RETCODE_ALREADY_DELETED
3965 *             The entity has already been deleted.
3966 */
3967DDS_EXPORT dds_return_t
3968dds_get_status_changes(dds_entity_t entity, uint32_t *status);
3969
3970/**
3971 * @brief Get enabled status on entity
3972 *
3973 * This operation returns the status enabled on the entity
3974 *
3975 * @param[in]  entity  Entity to get the status.
3976 * @param[out] mask    Mask of enabled statuses set on the entity.
3977 *
3978 * @returns A dds_return_t indicating success or failure.
3979 *
3980 * @retval DDS_RETCODE_OK
3981 *             Success.
3982 * @retval DDS_RETCODE_BAD_PARAMETER
3983 *             The entity parameter is not a valid parameter.
3984 * @retval DDS_RETCODE_ILLEGAL_OPERATION
3985 *             The operation is invoked on an inappropriate object.
3986 * @retval DDS_RETCODE_ALREADY_DELETED
3987 *             The entity has already been deleted.
3988 */
3989DDS_EXPORT dds_return_t
3990dds_get_status_mask(dds_entity_t entity, uint32_t *mask);
3991
3992DDS_DEPRECATED_EXPORT dds_return_t
3993dds_get_enabled_status(dds_entity_t entity, uint32_t *mask);
3994
3995/**
3996 * @brief Set status enabled on entity
3997 *
3998 * This operation enables the status(es) based on the mask set
3999 *
4000 * @param[in]  entity  Entity to enable the status.
4001 * @param[in]  mask    Status value that indicates the status to be enabled.
4002 *
4003 * @returns A dds_return_t indicating success or failure.
4004 *
4005 * @retval DDS_RETCODE_OK
4006 *             Success.
4007 * @retval DDS_RETCODE_BAD_PARAMETER
4008 *             The entity parameter is not a valid parameter.
4009 * @retval DDS_RETCODE_ILLEGAL_OPERATION
4010 *             The operation is invoked on an inappropriate object.
4011 * @retval DDS_RETCODE_ALREADY_DELETED
4012 *             The entity has already been deleted.
4013 */
4014DDS_EXPORT dds_return_t
4015dds_set_status_mask(dds_entity_t entity, uint32_t mask);
4016
4017DDS_DEPRECATED_EXPORT dds_return_t
4018dds_set_enabled_status(dds_entity_t entity, uint32_t mask);
4019
4020/*
4021  Almost all entities have get/set qos operations defined on them,
4022  again following the DCPS spec. But unlike the DCPS spec, the
4023  "present" field in qos_t allows one to initialize just the one QoS
4024  one wants to set & pass it to set_qos.
4025*/
4026
4027/**
4028 * @brief Get entity QoS policies.
4029 *
4030 * This operation allows access to the existing set of QoS policies
4031 * for the entity.
4032 *
4033 * @param[in]  entity  Entity on which to get qos.
4034 * @param[out] qos     Pointer to the qos structure that returns the set policies.
4035 *
4036 * @returns A dds_return_t indicating success or failure. The QoS object will have
4037 * at least all QoS relevant for the entity present and the corresponding dds_qget_...
4038 * will return true.
4039 *
4040 * @retval DDS_RETCODE_OK
4041 *             The existing set of QoS policy values applied to the entity
4042 *             has successfully been copied into the specified qos parameter.
4043 * @retval DDS_RETCODE_ERROR
4044 *             An internal error has occurred.
4045 * @retval DDS_RETCODE_BAD_PARAMETER
4046 *             The qos parameter is NULL.
4047 * @retval DDS_RETCODE_ILLEGAL_OPERATION
4048 *             The operation is invoked on an inappropriate object.
4049 * @retval DDS_RETCODE_ALREADY_DELETED
4050 *             The entity has already been deleted.
4051 */
4052/* TODO: Link to generic QoS information documentation. */
4053DDS_EXPORT dds_return_t
4054dds_get_qos(dds_entity_t entity, dds_qos_t *qos);
4055
4056/**
4057 * @brief Set entity QoS policies.
4058 *
4059 * This operation replaces the existing set of Qos Policy settings for an
4060 * entity. The parameter qos must contain the struct with the QosPolicy
4061 * settings which is checked for self-consistency.
4062 *
4063 * The set of QosPolicy settings specified by the qos parameter are applied on
4064 * top of the existing QoS, replacing the values of any policies previously set
4065 * (provided, the operation returned DDS_RETCODE_OK).
4066 *
4067 * Not all policies are changeable when the entity is enabled.
4068 *
4069 * @note Currently only Latency Budget and Ownership Strength are changeable QoS
4070 *       that can be set.
4071 *
4072 * @param[in]  entity  Entity from which to get qos.
4073 * @param[in]  qos     Pointer to the qos structure that provides the policies.
4074 *
4075 * @returns A dds_return_t indicating success or failure.
4076 *
4077 * @retval DDS_RETCODE_OK
4078 *             The new QoS policies are set.
4079 * @retval DDS_RETCODE_ERROR
4080 *             An internal error has occurred.
4081 * @retval DDS_RETCODE_BAD_PARAMETER
4082 *             The qos parameter is NULL.
4083 * @retval DDS_RETCODE_ILLEGAL_OPERATION
4084 *             The operation is invoked on an inappropriate object.
4085 * @retval DDS_RETCODE_ALREADY_DELETED
4086 *             The entity has already been deleted.
4087 * @retval DDS_RETCODE_IMMUTABLE_POLICY
4088 *             The entity is enabled and one or more of the policies of the QoS
4089 *             are immutable.
4090 * @retval DDS_RETCODE_INCONSISTENT_POLICY
4091 *             A few policies within the QoS are not consistent with each other.
4092 */
4093/* TODO: Link to generic QoS information documentation. */
4094DDS_EXPORT dds_return_t
4095dds_set_qos(dds_entity_t entity, const dds_qos_t * qos);
4096
4097/*
4098  Get or set listener associated with an entity, type of listener
4099  provided much match type of entity.
4100*/
4101
4102/**
4103 * @brief Get entity listeners.
4104 *
4105 * This operation allows access to the existing listeners attached to
4106 * the entity.
4107 *
4108 * @param[in]  entity   Entity on which to get the listeners.
4109 * @param[out] listener Pointer to the listener structure that returns the
4110 *                      set of listener callbacks.
4111 *
4112 * @returns A dds_return_t indicating success or failure.
4113 *
4114 * @retval DDS_RETCODE_OK
4115 *             The listeners of to the entity have been successfully been
4116 *             copied into the specified listener parameter.
4117 * @retval DDS_RETCODE_ERROR
4118 *             An internal error has occurred.
4119 * @retval DDS_RETCODE_BAD_PARAMETER
4120 *             The listener parameter is NULL.
4121 * @retval DDS_RETCODE_ILLEGAL_OPERATION
4122 *             The operation is invoked on an inappropriate object.
4123 * @retval DDS_RETCODE_ALREADY_DELETED
4124 *             The entity has already been deleted.
4125 */
4126/* TODO: Link to (generic) Listener and status information. */
4127DDS_EXPORT dds_return_t
4128dds_get_listener(dds_entity_t entity, dds_listener_t * listener);
4129
4130/**
4131 * @brief Set entity listeners.
4132 *
4133 * This operation attaches a dds_listener_t to the dds_entity_t. Only one
4134 * Listener can be attached to each Entity. If a Listener was already
4135 * attached, this operation will replace it with the new one. In other
4136 * words, all related callbacks are replaced (possibly with NULL).
4137 *
4138 * When listener parameter is NULL, all listener callbacks that were possibly
4139 * set on the Entity will be removed.
4140 *
4141 * @note Not all listener callbacks are related to all entities.
4142 *
4143 * <b><i>Communication Status</i></b><br>
4144 * For each communication status, the StatusChangedFlag flag is initially set to
4145 * FALSE. It becomes TRUE whenever that plain communication status changes. For
4146 * each plain communication status activated in the mask, the associated
4147 * Listener callback is invoked and the communication status is reset
4148 * to FALSE, as the listener implicitly accesses the status which is passed as a
4149 * parameter to that operation.
4150 * The status is reset prior to calling the listener, so if the application calls
4151 * the get_<status_name> from inside the listener it will see the
4152 * status already reset.
4153 *
4154 * <b><i>Status Propagation</i></b><br>
4155 * In case a related callback within the Listener is not set, the Listener of
4156 * the Parent entity is called recursively, until a Listener with the appropriate
4157 * callback set has been found and called. This allows the application to set
4158 * (for instance) a default behaviour in the Listener of the containing Publisher
4159 * and a DataWriter specific behaviour when needed. In case the callback is not
4160 * set in the Publishers' Listener either, the communication status will be
4161 * propagated to the Listener of the DomainParticipant of the containing
4162 * DomainParticipant. In case the callback is not set in the DomainParticipants'
4163 * Listener either, the Communication Status flag will be set, resulting in a
4164 * possible WaitSet trigger.
4165 *
4166 * @param[in]  entity    Entity on which to get the listeners.
4167 * @param[in]  listener  Pointer to the listener structure that contains the
4168 *                       set of listener callbacks (maybe NULL).
4169 *
4170 * @returns A dds_return_t indicating success or failure.
4171 *
4172 * @retval DDS_RETCODE_OK
4173 *             The listeners of to the entity have been successfully been
4174 *             copied into the specified listener parameter.
4175 * @retval DDS_RETCODE_ERROR
4176 *             An internal error has occurred.
4177 * @retval DDS_RETCODE_ILLEGAL_OPERATION
4178 *             The operation is invoked on an inappropriate object.
4179 * @retval DDS_RETCODE_ALREADY_DELETED
4180 *             The entity has already been deleted.
4181 */
4182/* TODO: Link to (generic) Listener and status information. */
4183DDS_EXPORT dds_return_t
4184dds_set_listener(dds_entity_t entity, const dds_listener_t * listener);
4185
4186/*
4187  Creation functions for various entities. Creating a subscriber or
4188  publisher is optional: if one creates a reader as a descendant of a
4189  participant, it is as if a subscriber is created specially for
4190  that reader.
4191
4192  QoS default values are those of the DDS specification, but the
4193  inheritance rules are different:
4194
4195    * publishers and subscribers inherit from the participant QoS
4196    * readers and writers always inherit from the topic QoS
4197    * the QoS's present in the "qos" parameter override the inherited values
4198*/
4199
4200/**
4201 * @brief Creates a new instance of a DDS participant in a domain
4202 *
4203 * If domain is set (not DDS_DOMAIN_DEFAULT) then it must match if the domain has also
4204 * been configured or an error status will be returned.
4205 * Currently only a single domain can be configured by providing configuration file.
4206 * If no configuration file exists, the default domain is configured as 0.
4207 *
4208 *
4209 * @param[in]  domain The domain in which to create the participant (can be DDS_DOMAIN_DEFAULT). DDS_DOMAIN_DEFAULT is for using the domain in the configuration.
4210 * @param[in]  qos The QoS to set on the new participant (can be NULL).
4211 * @param[in]  listener Any listener functions associated with the new participant (can be NULL).
4212
4213 * @returns A valid participant handle or an error code.
4214 *
4215 * @retval >0
4216 *             A valid participant handle.
4217 * @retval DDS_RETCODE_NOT_ALLOWED_BY_SECURITY
4218 *             An invalid DDS Security configuration was specified (whether
4219 *             that be missing or incorrect entries, expired certificates,
4220 *             or anything else related to the security settings and
4221 *             implementation).
4222 * @retval DDS_RETCODE_PRECONDITION_NOT_MET
4223 *             Some security properties specified in the QoS, but the Cyclone
4224 *             build does not include support for DDS Security.
4225 * @retval DDS_RETCODE_OUT_OF_RESOURCES
4226 *             Some resource limit (maximum participants, memory, handles,
4227 *             &c.) prevented creation of the participant.
4228 * @retval DDS_RETCODE_ERROR
4229 *             The "CYCLONEDDS_URI" environment variable lists non-existent
4230 *             or invalid configuration files, or contains invalid embedded
4231 *             configuration items; or an unspecified internal error has
4232 *             occurred.
4233 */
4234DDS_EXPORT dds_entity_t
4235dds_create_participant(
4236  const dds_domainid_t domain,
4237  const dds_qos_t *qos,
4238  const dds_listener_t *listener);
4239
4240/**
4241 * @brief Creates a domain with a given configuration
4242 *
4243 * To explicitly create a domain based on a configuration passed as a string.
4244 *
4245 * It will not be created if a domain with the given domain id already exists.
4246 * This could have been created implicitly by a dds_create_participant().
4247 *
4248 * Please be aware that the given domain_id always takes precedence over the
4249 * configuration.
4250 *
4251 *   | domain_id | domain id in config | result
4252 *   +-----------+---------------------+----------
4253 *   | n         | any (or absent)     | n, config is used
4254 *   | n         | m == n              | n, config is used
4255 *   | n         | m != n              | n, config is ignored: default
4256 *
4257 *     Config models:
4258 *     1: <CycloneDDS>
4259 *          <Domain id="X">...</Domain>
4260 *          <Domain .../>
4261 *        </CycloneDDS>
4262 *        where ... is all that can today be set in children of CycloneDDS
4263 *        with the exception of the id
4264 *     2: <CycloneDDS>
4265 *          <Domain><Id>X</Id></Domain>
4266 *          ...
4267 *        </CycloneDDS>
4268 *        legacy form, domain id must be the first element in the file with
4269 *        a value (if nothing has been set previously, it a warning is good
4270 *        enough)
4271 *
4272 * Using NULL or "" as config will create a domain with default settings.
4273 *
4274 *
4275 * @param[in]  domain The domain to be created. DEFAULT_DOMAIN is not allowed.
4276 * @param[in]  config A configuration string containing file names and/or XML fragments representing the configuration.
4277 *
4278 * @returns A valid entity handle or an error code.
4279 *
4280 * @retval DDS_RETCODE_BAD_PARAMETER
4281 *             Illegal value for domain id or the configfile parameter is NULL.
4282 * @retval DDS_RETCODE_PRECONDITION_NOT_MET
4283 *             The domain already existed and cannot be created again.
4284 * @retval DDS_RETCODE_ERROR
4285 *             An internal error has occurred.
4286 */
4287DDS_EXPORT dds_entity_t
4288dds_create_domain(const dds_domainid_t domain, const char *config);
4289
4290struct ddsi_config;
4291/**
4292 * @brief Creates a domain with a given configuration, specified as an
4293 * initializer (unstable interface)
4294 *
4295 * To explicitly create a domain based on a configuration passed as a raw
4296 * initializer rather than as an XML string. This allows bypassing the XML
4297 * parsing, but tightly couples the initializing to implementation.  See
4298 * dds/ddsi/ddsi_config.h:ddsi_config_init_default for a way to initialize
4299 * the default configuration.
4300 *
4301 * It will not be created if a domain with the given domain id already exists.
4302 * This could have been created implicitly by a dds_create_participant().
4303 *
4304 * Please be aware that the given domain_id always takes precedence over the
4305 * configuration.
4306 *
4307 * @param[in]  domain The domain to be created. DEFAULT_DOMAIN is not allowed.
4308 * @param[in]  config A configuration initializer.  The lifetime of any pointers
4309 *             in config must be at least that of the lifetime of the domain.
4310 *
4311 * @returns A valid entity handle or an error code.
4312 *
4313 * @retval DDS_RETCODE_BAD_PARAMETER
4314 *             Illegal value for domain id or the config parameter is NULL.
4315 * @retval DDS_RETCODE_PRECONDITION_NOT_MET
4316 *             The domain already existed and cannot be created again.
4317 * @retval DDS_RETCODE_ERROR
4318 *             An internal error has occurred.
4319 */
4320DDS_EXPORT dds_entity_t
4321dds_create_domain_with_rawconfig(const dds_domainid_t domain, const struct ddsi_config *config);
4322
4323/**
4324 * @brief Get entity parent.
4325 *
4326 * This operation returns the parent to which the given entity belongs.
4327 * For instance, it will return the Participant that was used when
4328 * creating a Publisher (when that Publisher was provided here).
4329 *
4330 * When a reader or a writer are created with a participant, then a
4331 * subscriber or publisher are created implicitly.
4332 * This function will return the implicit parent and not the used
4333 * participant.
4334 *
4335 * @param[in]  entity  Entity from which to get its parent.
4336 *
4337 * @returns A valid entity handle or an error code.
4338 *
4339 * @retval >0
4340 *             A valid entity handle.
4341 * @retval DDS_ENTITY_NIL
4342 *             Called with a participant.
4343 * @retval DDS_RETCODE_ERROR
4344 *             An internal error has occurred.
4345 * @retval DDS_RETCODE_ILLEGAL_OPERATION
4346 *             The operation is invoked on an inappropriate object.
4347 * @retval DDS_RETCODE_ALREADY_DELETED
4348 *             The entity has already been deleted.
4349 */
4350/* TODO: Link to generic dds entity relations documentation. */
4351DDS_EXPORT dds_entity_t
4352dds_get_parent(dds_entity_t entity);
4353
4354/**
4355 * @brief Get entity participant.
4356 *
4357 * This operation returns the participant to which the given entity belongs.
4358 * For instance, it will return the Participant that was used when
4359 * creating a Publisher that was used to create a DataWriter (when that
4360 * DataWriter was provided here).
4361 *
4362 * TODO: Link to generic dds entity relations documentation.
4363 *
4364 * @param[in]  entity  Entity from which to get its participant.
4365 *
4366 * @returns A valid entity or an error code.
4367 *
4368 * @retval >0
4369 *             A valid participant handle.
4370 * @retval DDS_RETCODE_ERROR
4371 *             An internal error has occurred.
4372 * @retval DDS_RETCODE_ILLEGAL_OPERATION
4373 *             The operation is invoked on an inappropriate object.
4374 * @retval DDS_RETCODE_ALREADY_DELETED
4375 *             The entity has already been deleted.
4376 */
4377DDS_EXPORT dds_entity_t
4378dds_get_participant(dds_entity_t entity);
4379
4380/**
4381 * @brief Get entity children.
4382 *
4383 * This operation returns the children that the entity contains.
4384 * For instance, it will return all the Topics, Publishers and Subscribers
4385 * of the Participant that was used to create those entities (when that
4386 * Participant is provided here).
4387 *
4388 * This functions takes a pre-allocated list to put the children in and
4389 * will return the number of found children. It is possible that the given
4390 * size of the list is not the same as the number of found children. If
4391 * less children are found, then the last few entries in the list are
4392 * untouched. When more children are found, then only 'size' number of
4393 * entries are inserted into the list, but still complete count of the
4394 * found children is returned. Which children are returned in the latter
4395 * case is undefined.
4396 *
4397 * When supplying NULL as list and 0 as size, you can use this to acquire
4398 * the number of children without having to pre-allocate a list.
4399 *
4400 * When a reader or a writer are created with a participant, then a
4401 * subscriber or publisher are created implicitly.
4402 * When used on the participant, this function will return the implicit
4403 * subscriber and/or publisher and not the related reader/writer.
4404 *
4405 * @param[in]  entity   Entity from which to get its children.
4406 * @param[out] children Pre-allocated array to contain the found children.
4407 * @param[in]  size     Size of the pre-allocated children's list.
4408 *
4409 * @returns Number of children or an error code.
4410 *
4411 * @retval >=0
4412 *             Number of found children (can be larger than 'size').
4413 * @retval DDS_RETCODE_ERROR
4414 *             An internal error has occurred.
4415 * @retval DDS_RETCODE_BAD_PARAMETER
4416 *             The children parameter is NULL, while a size is provided.
4417 * @retval DDS_RETCODE_ILLEGAL_OPERATION
4418 *             The operation is invoked on an inappropriate object.
4419 * @retval DDS_RETCODE_ALREADY_DELETED
4420 *             The entity has already been deleted.
4421 */
4422/* TODO: Link to generic dds entity relations documentation. */
4423DDS_EXPORT dds_return_t
4424dds_get_children(dds_entity_t entity, dds_entity_t *children, size_t size);
4425
4426/**
4427 * @brief Get the domain id to which this entity is attached.
4428 *
4429 * When creating a participant entity, it is attached to a certain domain.
4430 * All the children (like Publishers) and childrens' children (like
4431 * DataReaders), etc are also attached to that domain.
4432 *
4433 * This function will return the original domain ID when called on
4434 * any of the entities within that hierarchy.  For entities not associated
4435 * with a domain, the id is set to DDS_DOMAIN_DEFAULT.
4436 *
4437 * @param[in]  entity   Entity from which to get its children.
4438 * @param[out] id       Pointer to put the domain ID in.
4439 *
4440 * @returns A dds_return_t indicating success or failure.
4441 *
4442 * @retval DDS_RETCODE_OK
4443 *             Domain ID was returned.
4444 * @retval DDS_RETCODE_ERROR
4445 *             An internal error has occurred.
4446 * @retval DDS_RETCODE_BAD_PARAMETER
4447 *             The id parameter is NULL.
4448 * @retval DDS_RETCODE_ILLEGAL_OPERATION
4449 *             The operation is invoked on an inappropriate object.
4450 * @retval DDS_RETCODE_ALREADY_DELETED
4451 *             The entity has already been deleted.
4452 */
4453DDS_EXPORT dds_return_t
4454dds_get_domainid(dds_entity_t entity, dds_domainid_t *id);
4455
4456/**
4457 * @brief Get participants of a domain.
4458 *
4459 * This operation acquires the participants created on a domain and returns
4460 * the number of found participants.
4461 *
4462 * This function takes a domain id with the size of pre-allocated participant's
4463 * list in and will return the number of found participants. It is possible that
4464 * the given size of the list is not the same as the number of found participants.
4465 * If less participants are found, then the last few entries in an array stay
4466 * untouched. If more participants are found and the array is too small, then the
4467 * participants returned are undefined.
4468 *
4469 * @param[in]  domain_id    The domain id.
4470 * @param[out] participants The participant for domain.
4471 * @param[in]  size         Size of the pre-allocated participant's list.
4472 *
4473 * @returns Number of participants found or and error code.
4474 *
4475 * @retval >0
4476 *             Number of participants found.
4477 * @retval DDS_RETCODE_ERROR
4478 *             An internal error has occurred.
4479 * @retval DDS_RETCODE_BAD_PARAMETER
4480 *             The participant parameter is NULL, while a size is provided.
4481 */
4482DDS_EXPORT dds_return_t
4483dds_lookup_participant(
4484  dds_domainid_t domain_id,
4485  dds_entity_t *participants,
4486  size_t size);
4487
4488/**
4489 * @brief Creates a new topic with default type handling.
4490 *
4491 * The type name for the topic is taken from the generated descriptor. Topic
4492 * matching is done on a combination of topic name and type name. Each successful
4493 * call to dds_create_topic creates a new topic entity sharing the same QoS
4494 * settings with all other topics of the same name.
4495 *
4496 * @param[in]  participant  Participant on which to create the topic.
4497 * @param[in]  descriptor   An IDL generated topic descriptor.
4498 * @param[in]  name         Name of the topic.
4499 * @param[in]  qos          QoS to set on the new topic (can be NULL).
4500 * @param[in]  listener     Any listener functions associated with the new topic (can be NULL).
4501 *
4502 * @returns A valid, unique topic handle or an error code.
4503 *
4504 * @retval >=0
4505 *             A valid unique topic handle.
4506 * @retval DDS_RETCODE_BAD_PARAMETER
4507 *             Either participant, descriptor, name or qos is invalid.
4508 * @retval DDS_RETCODE_BAD_PARAMETER
4509 *             Either participant, descriptor, name or qos is invalid.
4510 * @retval DDS_RETCODE_INCONSISTENT_POLICY
4511 *             QoS mismatch between qos and an existing topic's QoS.
4512 * @retval DDS_RETCODE_PRECONDITION_NOT_MET
4513 *             Mismatch between type name in descriptor and pre-existing
4514 *             topic's type name.
4515 */
4516DDS_EXPORT dds_entity_t
4517dds_create_topic(
4518  dds_entity_t participant,
4519  const dds_topic_descriptor_t *descriptor,
4520  const char *name,
4521  const dds_qos_t *qos,
4522  const dds_listener_t *listener);
4523
4524#define DDS_HAS_CREATE_TOPIC_SERTYPE 1
4525/**
4526 * @brief Creates a new topic with provided type handling.
4527 *
4528 * The name for the type is taken from the provided "sertype" object. Type
4529 * matching is done on a combination of topic name and type name. Each successful
4530 * call to dds_create_topic creates a new topic entity sharing the same QoS
4531 * settings with all other topics of the same name.
4532 *
4533 * In case this function returns a valid handle, the ownership of the provided
4534 * sertype is handed over to Cyclone. On return, the caller gets in the sertype parameter a
4535 * pointer to the sertype that is actually used by the topic. This can be the provided sertype
4536 * (if this sertype was not yet known in the domain), or a sertype thas was
4537 * already known in the domain.
4538 *
4539 * @param[in]     participant  Participant on which to create the topic.
4540 * @param[in]     name         Topic name
4541 * @param[in,out] sertype      Internal description of the type . On return, the sertype parameter is set to the actual sertype that is used by the topic.
4542 * @param[in]     qos          QoS to set on the new topic (can be NULL).
4543 * @param[in]     listener     Any listener functions associated with the new topic (can be NULL).
4544 * @param[in]     sedp_plist   Topic description to be published as part of discovery (if NULL, not published).
4545 *
4546 * @returns A valid, unique topic handle or an error code. Iff a valid handle, the domain takes ownership of provided serdata.
4547 *
4548 * @retval >=0
4549 *             A valid unique topic handle.
4550 * @retval DDS_RETCODE_BAD_PARAMETER
4551 *             Either participant, descriptor, name or qos is invalid.
4552 * @retval DDS_RETCODE_BAD_PARAMETER
4553 *             Either participant, descriptor, name or qos is invalid.
4554 * @retval DDS_RETCODE_INCONSISTENT_POLICY
4555 *             QoS mismatch between qos and an existing topic's QoS.
4556 * @retval DDS_RETCODE_PRECONDITION_NOT_MET
4557 *             Mismatch between type name in sertype and pre-existing
4558 *             topic's type name.
4559 */
4560DDS_EXPORT dds_entity_t
4561dds_create_topic_sertype (
4562  dds_entity_t participant,
4563  const char *name,
4564  struct ddsi_sertype **sertype,
4565  const dds_qos_t *qos,
4566  const dds_listener_t *listener,
4567  const struct ddsi_plist *sedp_plist);
4568
4569#define DDS_HAS_CREATE_TOPIC_GENERIC 1
4570/**
4571 * @brief Creates a new topic with provided type handling.
4572 *
4573 * The name for the type is taken from the provided "sertype" object. Type
4574 * matching is done on a combination of topic name and type name. Each successful
4575 * call to dds_create_topic creates a new topic entity sharing the same QoS
4576 * settings with all other topics of the same name.
4577 *
4578 * In case this function returns a valid handle, the ownership of the provided
4579 * sertype is handed over to Cyclone. On return, the caller gets in the sertype parameter a
4580 * pointer to the sertype that is actually used by the topic. This can be the provided sertype
4581 * (if this sertype was not yet known in the domain), or a sertype thas was
4582 * already known in the domain.
4583 *
4584 * @param[in]     participant  Participant on which to create the topic.
4585 * @param[in,out] sertopic     Legacy internal description of the type. On return, the sertype parameter is set to the actual sertype that is used by the topic.
4586 * @param[in]     qos          QoS to set on the new topic (can be NULL).
4587 * @param[in]     listener     Any listener functions associated with the new topic (can be NULL).
4588 * @param[in]     sedp_plist   Topic description to be published as part of discovery (if NULL, not published).
4589 *
4590 * @returns A valid, unique topic handle or an error code. Iff a valid handle, the domain takes ownership of provided serdata.
4591 *
4592 * @retval >=0
4593 *             A valid unique topic handle.
4594 * @retval DDS_RETCODE_BAD_PARAMETER
4595 *             Either participant, descriptor, name or qos is invalid.
4596 * @retval DDS_RETCODE_BAD_PARAMETER
4597 *             Either participant, descriptor, name or qos is invalid.
4598 * @retval DDS_RETCODE_INCONSISTENT_POLICY
4599 *             QoS mismatch between qos and an existing topic's QoS.
4600 * @retval DDS_RETCODE_PRECONDITION_NOT_MET
4601 *             Mismatch between type name in sertype and pre-existing
4602 *             topic's type name.
4603 */
4604DDS_EXPORT dds_entity_t
4605dds_create_topic_generic (
4606  dds_entity_t participant,
4607  struct ddsi_sertopic **sertopic,
4608  const dds_qos_t *qos,
4609  const dds_listener_t *listener,
4610  const struct ddsi_plist *sedp_plist);
4611
4612DDS_DEPRECATED_EXPORT dds_entity_t
4613dds_create_topic_arbitrary (
4614  dds_entity_t participant,
4615  struct ddsi_sertopic *sertopic,
4616  const dds_qos_t *qos,
4617  const dds_listener_t *listener,
4618  const struct ddsi_plist *sedp_plist);
4619
4620/**
4621 * @brief Finds a named topic.
4622 *
4623 * The returned topic should be released with dds_delete.
4624 *
4625 * @param[in]  participant  The participant on which to find the topic.
4626 * @param[in]  name         The name of the topic to find.
4627 *
4628 * @returns A valid topic handle or an error code.
4629 *
4630 * @retval >0
4631 *             A valid topic handle.
4632 * @retval DDS_RETCODE_BAD_PARAMETER
4633 *             Participant was invalid.
4634 * @retval DDS_RETCODE_PRECONDITION_NOT_MET
4635 *             No topic of this name existed yet in the participant
4636 */
4637DDS_EXPORT dds_entity_t
4638dds_find_topic(dds_entity_t participant, const char *name);
4639
4640/**
4641 * @brief Returns the name of a given topic.
4642 *
4643 * @param[in]  topic  The topic.
4644 * @param[out] name   Buffer to write the topic name to.
4645 * @param[in]  size   Number of bytes available in the buffer.
4646 *
4647 * @returns A dds_return_t indicating success or failure.
4648 *
4649 * @retval DDS_RETCODE_OK
4650 *             Success.
4651 */
4652DDS_EXPORT dds_return_t
4653dds_get_name(dds_entity_t topic, char *name, size_t size);
4654
4655/**
4656 * @brief Returns the type name of a given topic.
4657 *
4658 * @param[in]  topic  The topic.
4659 * @param[out] name   Buffer to write the topic type name to.
4660 * @param[in]  size   Number of bytes available in the buffer.
4661 *
4662 * @returns A dds_return_t indicating success or failure.
4663 *
4664 * @return DDS_RETCODE_OK
4665 *             Success.
4666 */
4667DDS_EXPORT dds_return_t
4668dds_get_type_name(dds_entity_t topic, char *name, size_t size);
4669
4670/** Topic filter functions, as with the setters/getters: no guarantee that any
4671    of this will be maintained for backwards compatibility.
4672
4673    Sampleinfo is all zero when filtering in a write call (i.e., writer created
4674    using a filtered topic, which one perhaps shouldn't be doing), otherwise it
4675    has as much filled in correctly as is possible given the context and the rest
4676    fixed:
4677    - sample_state         DDS_SST_NOT_READ;
4678    - publication_handle   set to writer's instance handle
4679    - source_timestamp     set to source timestamp of sample
4680    - ranks                0
4681    - valid_data           true
4682    - instance_handle      set to instance handle of existing instance if the
4683                           sample matches an existing instance, otherwise to what
4684                           the instance handle will be if it passes the filter
4685    - view_state           set to instance view state if sample being filtered
4686                           matches an existing instance, NEW if not
4687    - instance_state       set to instance state if sample being filtered
4688                           matches an existing instance, NEW if not
4689    - generation counts    set to instance's generation counts if the sample
4690                           matches an existing instance instance, 0 if not */
4691typedef bool (*dds_topic_filter_sample_fn) (const void * sample);
4692typedef bool (*dds_topic_filter_sample_arg_fn) (const void * sample, void * arg);
4693typedef bool (*dds_topic_filter_sampleinfo_arg_fn) (const dds_sample_info_t * sampleinfo, void * arg);
4694typedef bool (*dds_topic_filter_sample_sampleinfo_arg_fn) (const void * sample, const dds_sample_info_t * sampleinfo, void * arg);
4695typedef dds_topic_filter_sample_fn dds_topic_filter_fn;
4696typedef dds_topic_filter_sample_arg_fn dds_topic_filter_arg_fn;
4697
4698/** Topic filter mode; no guarantee of backwards compatibility */
4699enum dds_topic_filter_mode {
4700  DDS_TOPIC_FILTER_NONE,
4701  DDS_TOPIC_FILTER_SAMPLE,
4702  DDS_TOPIC_FILTER_SAMPLE_ARG,
4703  DDS_TOPIC_FILTER_SAMPLEINFO_ARG,
4704  DDS_TOPIC_FILTER_SAMPLE_SAMPLEINFO_ARG,
4705};
4706
4707/** Union of all filter function types; no guarantee of backwards compatibility */
4708union dds_topic_filter_function_union {
4709  dds_topic_filter_sample_fn sample;
4710  dds_topic_filter_sample_arg_fn sample_arg;
4711  dds_topic_filter_sampleinfo_arg_fn sampleinfo_arg;
4712  dds_topic_filter_sample_sampleinfo_arg_fn sample_sampleinfo_arg;
4713};
4714
4715/** Filter description: mode, function pointer, argument; no guarantee of backwards compatibility */
4716struct dds_topic_filter {
4717  enum dds_topic_filter_mode mode;
4718  union dds_topic_filter_function_union f;
4719  void *arg;
4720};
4721
4722/**
4723 * @brief Sets a filter on a topic. To be replaced by proper filtering on readers,
4724 * no guarantee that this will be maintained for backwards compatibility.
4725 *
4726 * Not thread-safe with respect to data being read/written using readers/writers
4727 * using this topic.  Be sure to create a topic entity specific to the reader you
4728 * want to filter, then set the filter function, and only then create the reader.
4729 * And don't change it unless you know there are no concurrent writes.
4730 *
4731 * @param[in]  topic   The topic on which the content filter is set.
4732 * @param[in]  filter  The filter function used to filter topic samples.
4733 */
4734DDS_DEPRECATED_EXPORT void
4735dds_set_topic_filter(dds_entity_t topic, dds_topic_filter_fn filter);
4736
4737DDS_DEPRECATED_EXPORT void
4738dds_topic_set_filter(dds_entity_t topic, dds_topic_filter_fn filter);
4739
4740/**
4741 * @brief Sets a filter and filter argument on a topic. To be replaced by proper
4742 * filtering on readers, no guarantee that this will be maintained for backwards
4743 * compatibility.
4744 *
4745 * Not thread-safe with respect to data being read/written using readers/writers
4746 * using this topic.  Be sure to create a topic entity specific to the reader you
4747 * want to filter, then set the filter function, and only then create the reader.
4748 * And don't change it unless you know there are no concurrent writes.
4749 *
4750 * @param[in]  topic   The topic on which the content filter is set.
4751 * @param[in]  filter  The filter function used to filter topic samples.
4752 * @param[in]  arg     Argument for the filter function.
4753 *
4754 * @returns A dds_return_t indicating success or failure.
4755 *
4756 * @retval DDS_RETCODE_OK  Filter set successfully
4757 * @retval DDS_RETCODE_BAD_PARAMETER  The topic handle is invalid
4758*/
4759DDS_EXPORT dds_return_t
4760dds_set_topic_filter_and_arg(
4761  dds_entity_t topic,
4762  dds_topic_filter_arg_fn filter,
4763  void *arg);
4764
4765/**
4766 * @brief Sets a filter and filter argument on a topic. To be replaced by proper
4767 * filtering on readers, no guarantee that this will be maintained for backwards
4768 * compatibility.
4769 *
4770 * Not thread-safe with respect to data being read/written using readers/writers
4771 * using this topic.  Be sure to create a topic entity specific to the reader you
4772 * want to filter, then set the filter function, and only then create the reader.
4773 * And don't change it unless you know there are no concurrent writes.
4774 *
4775 * @param[in]  topic   The topic on which the content filter is set.
4776 * @param[in]  filter  The filter specification.
4777 *
4778 * @returns A dds_return_t indicating success or failure.
4779 *
4780 * @retval DDS_RETCODE_OK  Filter set successfully
4781 * @retval DDS_RETCODE_BAD_PARAMETER  The topic handle is invalid
4782*/
4783DDS_EXPORT dds_return_t
4784dds_set_topic_filter_extended(
4785  dds_entity_t topic,
4786  const struct dds_topic_filter *filter);
4787
4788/**
4789 * @brief Gets the filter for a topic. To be replaced by proper filtering on readers,
4790 * no guarantee that this will be maintained for backwards compatibility.
4791 *
4792 * @param[in]  topic  The topic from which to get the filter.
4793 *
4794 * @returns The topic filter, or 0 when of type other than "sample".
4795 */
4796DDS_DEPRECATED_EXPORT dds_topic_filter_fn
4797dds_get_topic_filter(dds_entity_t topic);
4798
4799DDS_DEPRECATED_EXPORT dds_topic_filter_fn
4800dds_topic_get_filter(dds_entity_t topic);
4801
4802/**
4803 * @brief Gets the filter for a topic. To be replaced by proper filtering on readers,
4804 * no guarantee that this will be maintained for backwards compatibility.
4805 *
4806 * @param[in]  topic  The topic from which to get the filter.
4807 * @param[out] fn     The topic filter function (fn may be NULL).
4808 * @param[out] arg    Filter function argument (arg may be NULL).
4809 *
4810 * @retval DDS_RETCODE_OK  Filter set successfully
4811 * @retval DDS_RETCODE_PRECONDITION_NOT_MET  Filter is not of "none" or "sample_arg"
4812 * @retval DDS_RETCODE_BAD_PARAMETER  The topic handle is invalid
4813 */
4814DDS_EXPORT dds_return_t
4815dds_get_topic_filter_and_arg (
4816  dds_entity_t topic,
4817  dds_topic_filter_arg_fn *fn,
4818  void **arg);
4819
4820/**
4821 * @brief Gets the filter for a topic. To be replaced by proper filtering on readers,
4822 * no guarantee that this will be maintained for backwards compatibility.
4823 *
4824 * @param[in]  topic  The topic from which to get the filter.
4825 * @param[out] filter The topic filter specification.
4826 *
4827 * @retval DDS_RETCODE_OK  Filter set successfully
4828 * @retval DDS_RETCODE_BAD_PARAMETER  The topic handle is invalid
4829 */
4830DDS_EXPORT dds_return_t
4831dds_get_topic_filter_extended (
4832  dds_entity_t topic,
4833  struct dds_topic_filter *filter);
4834
4835/**
4836 * @brief Creates a new instance of a DDS subscriber
4837 *
4838 * @param[in]  participant The participant on which the subscriber is being created.
4839 * @param[in]  qos         The QoS to set on the new subscriber (can be NULL).
4840 * @param[in]  listener    Any listener functions associated with the new subscriber (can be NULL).
4841 *
4842 * @returns A valid subscriber handle or an error code.
4843 *
4844 * @retval >0
4845 *             A valid subscriber handle.
4846 * @retval DDS_RETCODE_ERROR
4847 *             An internal error has occurred.
4848 * @retval DDS_RETCODE_BAD_PARAMETER
4849 *             One of the parameters is invalid.
4850 */
4851DDS_EXPORT dds_entity_t
4852dds_create_subscriber(
4853  dds_entity_t participant,
4854  const dds_qos_t *qos,
4855  const dds_listener_t *listener);
4856
4857/**
4858 * @brief Creates a new instance of a DDS publisher
4859 *
4860 * @param[in]  participant The participant to create a publisher for.
4861 * @param[in]  qos         The QoS to set on the new publisher (can be NULL).
4862 * @param[in]  listener    Any listener functions associated with the new publisher (can be NULL).
4863 *
4864 * @returns A valid publisher handle or an error code.
4865 *
4866 * @retval >0
4867 *            A valid publisher handle.
4868 * @retval DDS_RETCODE_ERROR
4869 *            An internal error has occurred.
4870 */
4871/* TODO: Check list of error codes is complete. */
4872DDS_EXPORT dds_entity_t
4873dds_create_publisher(
4874  dds_entity_t participant,
4875  const dds_qos_t *qos,
4876  const dds_listener_t *listener);
4877
4878/**
4879 * @brief Suspends the publications of the Publisher
4880 *
4881 * This operation is a hint to the Service so it can optimize its performance by e.g., collecting
4882 * modifications to DDS writers and then batching them. The Service is not required to use the hint.
4883 *
4884 * Every invocation of this operation must be matched by a corresponding call to @see dds_resume
4885 * indicating that the set of modifications has completed.
4886 *
4887 * @param[in]  publisher The publisher for which all publications will be suspended.
4888 *
4889 * @returns A dds_return_t indicating success or failure.
4890 *
4891 * @retval DDS_RETCODE_OK
4892 *             Publications suspended successfully.
4893 * @retval DDS_RETCODE_BAD_PARAMETER
4894 *             The pub parameter is not a valid publisher.
4895 * @retval DDS_RETCODE_UNSUPPORTED
4896 *             Operation is not supported.
4897 */
4898DDS_EXPORT dds_return_t
4899dds_suspend(dds_entity_t publisher);
4900
4901/**
4902 * @brief Resumes the publications of the Publisher
4903 *
4904 * This operation is a hint to the Service to indicate that the application has
4905 * completed changes initiated by a previous dds_suspend(). The Service is not
4906 * required to use the hint.
4907 *
4908 * The call to resume_publications must match a previous call to @see suspend_publications.
4909 *
4910 * @param[in]  publisher The publisher for which all publications will be resumed.
4911 *
4912 * @returns A dds_return_t indicating success or failure.
4913 *
4914 * @retval DDS_RETCODE_OK
4915 *             Publications resumed successfully.
4916 * @retval DDS_RETCODE_BAD_PARAMETER
4917 *             The pub parameter is not a valid publisher.
4918 * @retval DDS_RETCODE_PRECONDITION_NOT_MET
4919 *             No previous matching dds_suspend().
4920 * @retval DDS_RETCODE_UNSUPPORTED
4921 *             Operation is not supported.
4922 */
4923DDS_EXPORT dds_return_t
4924dds_resume(dds_entity_t publisher);
4925
4926/**
4927 * @brief Waits at most for the duration timeout for acks for data in the publisher or writer.
4928 *
4929 * This operation blocks the calling thread until either all data written by the publisher
4930 * or writer is acknowledged by all matched reliable reader entities, or else the duration
4931 * specified by the timeout parameter elapses, whichever happens first.
4932 *
4933 * @param[in]  publisher_or_writer Publisher or writer whose acknowledgments must be waited for
4934 * @param[in]  timeout             How long to wait for acknowledgments before time out
4935 *
4936 * @returns A dds_return_t indicating success or failure.
4937 *
4938 * @retval DDS_RETCODE_OK
4939 *             All acknowledgments successfully received with the timeout.
4940 * @retval DDS_RETCODE_BAD_PARAMETER
4941 *             The publisher_or_writer is not a valid publisher or writer.
4942 * @retval DDS_RETCODE_TIMEOUT
4943 *             Timeout expired before all acknowledgments from reliable reader entities were received.
4944 * @retval DDS_RETCODE_UNSUPPORTED
4945 *             Operation is not supported.
4946 */
4947DDS_EXPORT dds_return_t
4948dds_wait_for_acks(dds_entity_t publisher_or_writer, dds_duration_t timeout);
4949
4950/**
4951 * @brief Creates a new instance of a DDS reader.
4952 *
4953 * When a participant is used to create a reader, an implicit subscriber is created.
4954 * This implicit subscriber will be deleted automatically when the created reader
4955 * is deleted.
4956 *
4957 * @param[in]  participant_or_subscriber The participant or subscriber on which the reader is being created.
4958 * @param[in]  topic                     The topic to read.
4959 * @param[in]  qos                       The QoS to set on the new reader (can be NULL).
4960 * @param[in]  listener                  Any listener functions associated with the new reader (can be NULL).
4961 *
4962 * @returns A valid reader handle or an error code.
4963 *
4964 * @retval >0
4965 *            A valid reader handle.
4966 * @retval DDS_RETCODE_ERROR
4967 *            An internal error occurred.
4968 */
4969/* TODO: Complete list of error codes */
4970DDS_EXPORT dds_entity_t
4971dds_create_reader(
4972  dds_entity_t participant_or_subscriber,
4973  dds_entity_t topic,
4974  const dds_qos_t *qos,
4975  const dds_listener_t *listener);
4976
4977/**
4978 * @brief Creates a new instance of a DDS reader with a custom history cache.
4979 *
4980 * When a participant is used to create a reader, an implicit subscriber is created.
4981 * This implicit subscriber will be deleted automatically when the created reader
4982 * is deleted.
4983 *
4984 * @param[in]  participant_or_subscriber The participant or subscriber on which the reader is being created.
4985 * @param[in]  topic                     The topic to read.
4986 * @param[in]  qos                       The QoS to set on the new reader (can be NULL).
4987 * @param[in]  listener                  Any listener functions associated with the new reader (can be NULL).
4988 * @param[in]  rhc                       Reader history cache to use, reader becomes the owner
4989 *
4990 * @returns A valid reader handle or an error code.
4991 *
4992 * @retval >0
4993 *            A valid reader handle.
4994 * @retval DDS_RETCODE_ERROR
4995 *            An internal error occurred.
4996 */
4997/* TODO: Complete list of error codes */
4998DDS_EXPORT dds_entity_t
4999dds_create_reader_rhc(
5000  dds_entity_t participant_or_subscriber,
5001  dds_entity_t topic,
5002  const dds_qos_t *qos,
5003  const dds_listener_t *listener,
5004  struct dds_rhc *rhc);
5005
5006/**
5007 * @brief Wait until reader receives all historic data
5008 *
5009 * The operation blocks the calling thread until either all "historical" data is
5010 * received, or else the duration specified by the max_wait parameter elapses, whichever happens
5011 * first. A return value of 0 indicates that all the "historical" data was received; a return
5012 * value of TIMEOUT indicates that max_wait elapsed before all the data was received.
5013 *
5014 * @param[in]  reader    The reader on which to wait for historical data.
5015 * @param[in]  max_wait  How long to wait for historical data before time out.
5016 *
5017 * @returns a status, 0 on success, TIMEOUT on timeout or a negative value to indicate error.
5018 */
5019/* TODO: Complete list of error codes */
5020DDS_EXPORT dds_return_t
5021dds_reader_wait_for_historical_data(
5022  dds_entity_t reader,
5023  dds_duration_t max_wait);
5024
5025/**
5026 * @brief Creates a new instance of a DDS writer.
5027 *
5028 * When a participant is used to create a writer, an implicit publisher is created.
5029 * This implicit publisher will be deleted automatically when the created writer
5030 * is deleted.
5031 *
5032 * @param[in]  participant_or_publisher The participant or publisher on which the writer is being created.
5033 * @param[in]  topic The topic to write.
5034 * @param[in]  qos The QoS to set on the new writer (can be NULL).
5035 * @param[in]  listener Any listener functions associated with the new writer (can be NULL).
5036 *
5037 * @returns A valid writer handle or an error code.
5038 *
5039 * @returns >0
5040 *              A valid writer handle.
5041 * @returns DDS_RETCODE_ERROR
5042 *              An internal error occurred.
5043 */
5044/* TODO: Complete list of error codes */
5045DDS_EXPORT dds_entity_t
5046dds_create_writer(
5047  dds_entity_t participant_or_publisher,
5048  dds_entity_t topic,
5049  const dds_qos_t *qos,
5050  const dds_listener_t *listener);
5051
5052/*
5053  Writing data (and variants of it) is straightforward. The first set
5054  is equivalent to the second set with -1 passed for "timestamp",
5055  meaning, substitute the result of a call to time(). The dispose
5056  and unregister operations take an object of the topic's type, but
5057  only touch the key fields; the remained may be undefined.
5058*/
5059/**
5060 * @brief Registers an instance
5061 *
5062 * This operation registers an instance with a key value to the data writer and
5063 * returns an instance handle that could be used for successive write & dispose
5064 * operations. When the handle is not allocated, the function will return an
5065 * error and the handle will be un-touched.
5066 *
5067 * @param[in]  writer  The writer to which instance has be associated.
5068 * @param[out] handle  The instance handle.
5069 * @param[in]  data    The instance with the key value.
5070 *
5071 * @returns A dds_return_t indicating success or failure.
5072 *
5073 * @retval DDS_RETCODE_OK
5074 *            The operation was successful.
5075 * @retval DDS_RETCODE_BAD_PARAMETER
5076 *            One of the given arguments is not valid.
5077 * @retval DDS_RETCODE_ILLEGAL_OPERATION
5078 *            The operation is invoked on an inappropriate object.
5079 */
5080DDS_EXPORT dds_return_t
5081dds_register_instance(
5082  dds_entity_t writer,
5083  dds_instance_handle_t *handle,
5084  const void *data);
5085
5086/**
5087 * @brief Unregisters an instance
5088 *
5089 * This operation reverses the action of register instance, removes all information regarding
5090 * the instance and unregisters an instance with a key value from the data writer.
5091 *
5092 * @param[in]  writer  The writer to which instance is associated.
5093 * @param[in]  data    The instance with the key value.
5094 *
5095 * @returns A dds_return_t indicating success or failure.
5096 *
5097 * @retval DDS_RETCODE_OK
5098 *             The operation was successful.
5099 * @retval DDS_RETCODE_BAD_PARAMETER
5100 *             One of the given arguments is not valid.
5101 * @retval DDS_RETCODE_ILLEGAL_OPERATION
5102 *             The operation is invoked on an inappropriate object.
5103 */
5104DDS_EXPORT dds_return_t
5105dds_unregister_instance(dds_entity_t writer, const void *data);
5106
5107/**
5108 * @brief Unregisters an instance
5109 *
5110 *This operation unregisters the instance which is identified by the key fields of the given
5111 *typed instance handle.
5112 *
5113 * @param[in]  writer  The writer to which instance is associated.
5114 * @param[in]  handle  The instance handle.
5115 *
5116 * @returns A dds_return_t indicating success or failure.
5117 *
5118 * @retval DDS_RETCODE_OK
5119 *             The operation was successful.
5120 * @retval DDS_RETCODE_BAD_PARAMETER
5121 *             One of the given arguments is not valid.
5122 * @retval DDS_RETCODE_ILLEGAL_OPERATION
5123 *             The operation is invoked on an inappropriate object.
5124 */
5125DDS_EXPORT dds_return_t
5126dds_unregister_instance_ih(dds_entity_t writer, dds_instance_handle_t handle);
5127
5128/**
5129 * @brief Unregisters an instance
5130 *
5131 * This operation reverses the action of register instance, removes all information regarding
5132 * the instance and unregisters an instance with a key value from the data writer. It also
5133 * provides a value for the timestamp explicitly.
5134 *
5135 * @param[in]  writer    The writer to which instance is associated.
5136 * @param[in]  data      The instance with the key value.
5137 * @param[in]  timestamp The timestamp used at registration.
5138 *
5139 * @returns A dds_return_t indicating success or failure.
5140 *
5141 * @retval DDS_RETCODE_OK
5142 *             The operation was successful.
5143 * @retval DDS_RETCODE_BAD_PARAMETER
5144 *             One of the given arguments is not valid.
5145 * @retval DDS_RETCODE_ILLEGAL_OPERATION
5146 *             The operation is invoked on an inappropriate object.
5147 */
5148DDS_EXPORT dds_return_t
5149dds_unregister_instance_ts(
5150  dds_entity_t writer,
5151  const void *data,
5152  dds_time_t timestamp);
5153
5154/**
5155 * @brief Unregisters an instance
5156 *
5157 * This operation unregisters an instance with a key value from the handle. Instance can be identified
5158 * from instance handle. If an unregistered key ID is passed as an instance data, an error is logged and
5159 * not flagged as return value.
5160 *
5161 * @param[in]  writer    The writer to which instance is associated.
5162 * @param[in]  handle    The instance handle.
5163 * @param[in]  timestamp The timestamp used at registration.
5164 *
5165 * @returns A dds_return_t indicating success or failure.
5166 *
5167 * @retval DDS_RETCODE_OK
5168 *             The operation was successful
5169 * @retval DDS_RETCODE_BAD_PARAMETER
5170 *             One of the given arguments is not valid
5171 * @retval DDS_RETCODE_ILLEGAL_OPERATION
5172 *             The operation is invoked on an inappropriate object
5173 */
5174DDS_EXPORT dds_return_t
5175dds_unregister_instance_ih_ts(
5176  dds_entity_t writer,
5177  dds_instance_handle_t handle,
5178  dds_time_t timestamp);
5179
5180/**
5181 * @brief This operation modifies and disposes a data instance.
5182 *
5183 * This operation requests the Data Distribution Service to modify the instance and
5184 * mark it for deletion. Copies of the instance and its corresponding samples, which are
5185 * stored in every connected reader and, dependent on the QoS policy settings (also in
5186 * the Transient and Persistent stores) will be modified and marked for deletion by
5187 * setting their dds_instance_state_t to DDS_IST_NOT_ALIVE_DISPOSED.
5188 *
5189 * <b><i>Blocking</i></b><br>
5190 * If the history QoS policy is set to DDS_HISTORY_KEEP_ALL, the
5191 * dds_writedispose operation on the writer may block if the modification
5192 * would cause data to be lost because one of the limits, specified in the
5193 * resource_limits QoS policy, to be exceeded. In case the synchronous
5194 * attribute value of the reliability Qos policy is set to true for
5195 * communicating writers and readers then the writer will wait until
5196 * all synchronous readers have acknowledged the data. Under these
5197 * circumstances, the max_blocking_time attribute of the reliability
5198 * QoS policy configures the maximum time the dds_writedispose operation
5199 * may block.
5200 * If max_blocking_time elapses before the writer is able to store the
5201 * modification without exceeding the limits and all expected acknowledgements
5202 * are received, the dds_writedispose operation will fail and returns
5203 * DDS_RETCODE_TIMEOUT.
5204 *
5205 * @param[in]  writer The writer to dispose the data instance from.
5206 * @param[in]  data   The data to be written and disposed.
5207 *
5208 * @returns A dds_return_t indicating success or failure.
5209 *
5210 * @retval DDS_RETCODE_OK
5211 *             The sample is written and the instance is marked for deletion.
5212 * @retval DDS_RETCODE_ERROR
5213 *             An internal error has occurred.
5214 * @retval DDS_RETCODE_BAD_PARAMETER
5215 *             At least one of the arguments is invalid.
5216 * @retval DDS_RETCODE_ILLEGAL_OPERATION
5217 *             The operation is invoked on an inappropriate object.
5218 * @retval DDS_RETCODE_ALREADY_DELETED
5219 *             The entity has already been deleted.
5220 * @retval DDS_RETCODE_TIMEOUT
5221 *             Either the current action overflowed the available resources as
5222 *             specified by the combination of the reliability QoS policy,
5223 *             history QoS policy and resource_limits QoS policy, or the
5224 *             current action was waiting for data delivery acknowledgement
5225 *             by synchronous readers. This caused blocking of this operation,
5226 *             which could not be resolved before max_blocking_time of the
5227 *             reliability QoS policy elapsed.
5228 */
5229DDS_EXPORT dds_return_t
5230dds_writedispose(dds_entity_t writer, const void *data);
5231
5232/**
5233 * @brief This operation modifies and disposes a data instance with a specific
5234 *        timestamp.
5235 *
5236 * This operation performs the same functions as dds_writedispose except that
5237 * the application provides the value for the source_timestamp that is made
5238 * available to connected reader objects. This timestamp is important for the
5239 * interpretation of the destination_order QoS policy.
5240 *
5241 * @param[in]  writer    The writer to dispose the data instance from.
5242 * @param[in]  data      The data to be written and disposed.
5243 * @param[in]  timestamp The timestamp used as source timestamp.
5244 *
5245 * @returns A dds_return_t indicating success or failure.
5246 *
5247 * @retval DDS_RETCODE_OK
5248 *             The sample is written and the instance is marked for deletion.
5249 * @retval DDS_RETCODE_ERROR
5250 *             An internal error has occurred.
5251 * @retval DDS_RETCODE_BAD_PARAMETER
5252 *             At least one of the arguments is invalid.
5253 * @retval DDS_RETCODE_ILLEGAL_OPERATION
5254 *             The operation is invoked on an inappropriate object.
5255 * @retval DDS_RETCODE_ALREADY_DELETED
5256 *             The entity has already been deleted.
5257 * @retval DDS_RETCODE_TIMEOUT
5258 *             Either the current action overflowed the available resources as
5259 *             specified by the combination of the reliability QoS policy,
5260 *             history QoS policy and resource_limits QoS policy, or the
5261 *             current action was waiting for data delivery acknowledgement
5262 *             by synchronous readers. This caused blocking of this operation,
5263 *             which could not be resolved before max_blocking_time of the
5264 *             reliability QoS policy elapsed.
5265 */
5266DDS_EXPORT dds_return_t
5267dds_writedispose_ts(
5268  dds_entity_t writer,
5269  const void *data,
5270  dds_time_t timestamp);
5271
5272/**
5273 * @brief This operation disposes an instance, identified by the data sample.
5274 *
5275 * This operation requests the Data Distribution Service to modify the instance and
5276 * mark it for deletion. Copies of the instance and its corresponding samples, which are
5277 * stored in every connected reader and, dependent on the QoS policy settings (also in
5278 * the Transient and Persistent stores) will be modified and marked for deletion by
5279 * setting their dds_instance_state_t to DDS_IST_NOT_ALIVE_DISPOSED.
5280 *
5281 * <b><i>Blocking</i></b><br>
5282 * If the history QoS policy is set to DDS_HISTORY_KEEP_ALL, the
5283 * dds_writedispose operation on the writer may block if the modification
5284 * would cause data to be lost because one of the limits, specified in the
5285 * resource_limits QoS policy, to be exceeded. In case the synchronous
5286 * attribute value of the reliability Qos policy is set to true for
5287 * communicating writers and readers then the writer will wait until
5288 * all synchronous readers have acknowledged the data. Under these
5289 * circumstances, the max_blocking_time attribute of the reliability
5290 * QoS policy configures the maximum time the dds_writedispose operation
5291 * may block.
5292 * If max_blocking_time elapses before the writer is able to store the
5293 * modification without exceeding the limits and all expected acknowledgements
5294 * are received, the dds_writedispose operation will fail and returns
5295 * DDS_RETCODE_TIMEOUT.
5296 *
5297 * @param[in]  writer The writer to dispose the data instance from.
5298 * @param[in]  data   The data sample that identifies the instance
5299 *                    to be disposed.
5300 *
5301 * @returns A dds_return_t indicating success or failure.
5302 *
5303 * @retval DDS_RETCODE_OK
5304 *             The sample is written and the instance is marked for deletion.
5305 * @retval DDS_RETCODE_ERROR
5306 *             An internal error has occurred.
5307 * @retval DDS_RETCODE_BAD_PARAMETER
5308 *             At least one of the arguments is invalid.
5309 * @retval DDS_RETCODE_ILLEGAL_OPERATION
5310 *             The operation is invoked on an inappropriate object.
5311 * @retval DDS_RETCODE_ALREADY_DELETED
5312 *             The entity has already been deleted.
5313 * @retval DDS_RETCODE_TIMEOUT
5314 *             Either the current action overflowed the available resources as
5315 *             specified by the combination of the reliability QoS policy,
5316 *             history QoS policy and resource_limits QoS policy, or the
5317 *             current action was waiting for data delivery acknowledgement
5318 *             by synchronous readers. This caused blocking of this operation,
5319 *             which could not be resolved before max_blocking_time of the
5320 *             reliability QoS policy elapsed.
5321 */
5322DDS_EXPORT dds_return_t
5323dds_dispose(dds_entity_t writer, const void *data);
5324
5325/**
5326 * @brief This operation disposes an instance with a specific timestamp, identified by the data sample.
5327 *
5328 * This operation performs the same functions as dds_dispose except that
5329 * the application provides the value for the source_timestamp that is made
5330 * available to connected reader objects. This timestamp is important for the
5331 * interpretation of the destination_order QoS policy.
5332 *
5333 * @param[in]  writer    The writer to dispose the data instance from.
5334 * @param[in]  data      The data sample that identifies the instance
5335 *                       to be disposed.
5336 * @param[in]  timestamp The timestamp used as source timestamp.
5337 *
5338 * @returns A dds_return_t indicating success or failure.
5339 *
5340 * @retval DDS_RETCODE_OK
5341 *             The sample is written and the instance is marked for deletion
5342 * @retval DDS_RETCODE_ERROR
5343 *             An internal error has occurred
5344 * @retval DDS_RETCODE_BAD_PARAMETER
5345 *             At least one of the arguments is invalid
5346 * @retval DDS_RETCODE_ILLEGAL_OPERATION
5347 *             The operation is invoked on an inappropriate object
5348 * @retval DDS_RETCODE_ALREADY_DELETED
5349 *             The entity has already been deleted
5350 * @retval DDS_RETCODE_TIMEOUT
5351 *             Either the current action overflowed the available resources as
5352 *             specified by the combination of the reliability QoS policy,
5353 *             history QoS policy and resource_limits QoS policy, or the
5354 *             current action was waiting for data delivery acknowledgment
5355 *             by synchronous readers. This caused blocking of this operation,
5356 *             which could not be resolved before max_blocking_time of the
5357 *             reliability QoS policy elapsed.
5358 */
5359DDS_EXPORT dds_return_t
5360dds_dispose_ts(
5361  dds_entity_t writer,
5362  const void *data,
5363  dds_time_t timestamp);
5364
5365/**
5366 * @brief This operation disposes an instance, identified by the instance handle.
5367 *
5368 * This operation requests the Data Distribution Service to modify the instance and
5369 * mark it for deletion. Copies of the instance and its corresponding samples, which are
5370 * stored in every connected reader and, dependent on the QoS policy settings (also in
5371 * the Transient and Persistent stores) will be modified and marked for deletion by
5372 * setting their dds_instance_state_t to DDS_IST_NOT_ALIVE_DISPOSED.
5373 *
5374 * <b><i>Instance Handle</i></b><br>
5375 * The given instance handle must correspond to the value that was returned by either
5376 * the dds_register_instance operation, dds_register_instance_ts or dds_lookup_instance.
5377 * If there is no correspondence, then the result of the operation is unspecified.
5378 *
5379 * @param[in]  writer The writer to dispose the data instance from.
5380 * @param[in]  handle The handle to identify an instance.
5381 *
5382 * @returns A dds_return_t indicating success or failure.
5383 *
5384 * @retval DDS_RETCODE_OK
5385 *             The sample is written and the instance is marked for deletion.
5386 * @retval DDS_RETCODE_ERROR
5387 *             An internal error has occurred.
5388 * @retval DDS_RETCODE_BAD_PARAMETER
5389 *             At least one of the arguments is invalid
5390 * @retval DDS_RETCODE_ILLEGAL_OPERATION
5391 *             The operation is invoked on an inappropriate object
5392 * @retval DDS_RETCODE_ALREADY_DELETED
5393 *             The entity has already been deleted
5394 * @retval DDS_RETCODE_PRECONDITION_NOT_MET
5395 *             The instance handle has not been registered with this writer
5396 */
5397DDS_EXPORT dds_return_t
5398dds_dispose_ih(dds_entity_t writer, dds_instance_handle_t handle);
5399
5400/**
5401 * @brief This operation disposes an instance with a specific timestamp, identified by the instance handle.
5402 *
5403 * This operation performs the same functions as dds_dispose_ih except that
5404 * the application provides the value for the source_timestamp that is made
5405 * available to connected reader objects. This timestamp is important for the
5406 * interpretation of the destination_order QoS policy.
5407 *
5408 * @param[in]  writer    The writer to dispose the data instance from.
5409 * @param[in]  handle    The handle to identify an instance.
5410 * @param[in]  timestamp The timestamp used as source timestamp.
5411 *
5412 * @returns A dds_return_t indicating success or failure.
5413 *
5414 * @retval DDS_RETCODE_OK
5415 *             The sample is written and the instance is marked for deletion.
5416 * @retval DDS_RETCODE_ERROR
5417 *             An internal error has occurred.
5418 * @retval DDS_RETCODE_BAD_PARAMETER
5419 *             At least one of the arguments is invalid.
5420 * @retval DDS_RETCODE_ILLEGAL_OPERATION
5421 *             The operation is invoked on an inappropriate object.
5422 * @retval DDS_RETCODE_ALREADY_DELETED
5423 *             The entity has already been deleted.
5424 * @retval DDS_RETCODE_PRECONDITION_NOT_MET
5425 *             The instance handle has not been registered with this writer.
5426 */
5427DDS_EXPORT dds_return_t
5428dds_dispose_ih_ts(
5429  dds_entity_t writer,
5430  dds_instance_handle_t handle,
5431  dds_time_t timestamp);
5432
5433/**
5434 * @brief Write the value of a data instance
5435 *
5436 * With this API, the value of the source timestamp is automatically made
5437 * available to the data reader by the service.
5438 *
5439 * @param[in]  writer The writer entity.
5440 * @param[in]  data Value to be written.
5441 *
5442 * @returns dds_return_t indicating success or failure.
5443 */
5444DDS_EXPORT dds_return_t
5445dds_write(dds_entity_t writer, const void *data);
5446
5447/*TODO: What is it for and is it really needed? */
5448DDS_EXPORT void
5449dds_write_flush(dds_entity_t writer);
5450
5451/**
5452 * @brief Write a serialized value of a data instance
5453 *
5454 * This call causes the writer to write the serialized value that is provided
5455 * in the serdata argument.  Timestamp and statusinfo fields are set to the
5456 * current time and 0 (indicating a regular write), respectively.
5457 *
5458 * @param[in]  writer The writer entity.
5459 * @param[in]  serdata Serialized value to be written.
5460 *
5461 * @returns A dds_return_t indicating success or failure.
5462 *
5463 * @retval DDS_RETCODE_OK
5464 *             The writer successfully wrote the serialized value.
5465 * @retval DDS_RETCODE_ERROR
5466 *             An internal error has occurred.
5467 * @retval DDS_RETCODE_BAD_PARAMETER
5468 *             One of the given arguments is not valid.
5469 * @retval DDS_RETCODE_ILLEGAL_OPERATION
5470 *             The operation is invoked on an inappropriate object.
5471 * @retval DDS_RETCODE_ALREADY_DELETED
5472 *             The entity has already been deleted.
5473 * @retval DDS_RETCODE_TIMEOUT
5474 *             The writer failed to write the serialized value reliably within the specified max_blocking_time.
5475 */
5476DDS_EXPORT dds_return_t
5477dds_writecdr(dds_entity_t writer, struct ddsi_serdata *serdata);
5478
5479/**
5480 * @brief Write a serialized value of a data instance
5481 *
5482 * This call causes the writer to write the serialized value that is provided
5483 * in the serdata argument.  Timestamp and statusinfo are used as is.
5484 *
5485 * @param[in]  writer The writer entity.
5486 * @param[in]  serdata Serialized value to be written.
5487 *
5488 * @returns A dds_return_t indicating success or failure.
5489 *
5490 * @retval DDS_RETCODE_OK
5491 *             The writer successfully wrote the serialized value.
5492 * @retval DDS_RETCODE_ERROR
5493 *             An internal error has occurred.
5494 * @retval DDS_RETCODE_BAD_PARAMETER
5495 *             One of the given arguments is not valid.
5496 * @retval DDS_RETCODE_ILLEGAL_OPERATION
5497 *             The operation is invoked on an inappropriate object.
5498 * @retval DDS_RETCODE_ALREADY_DELETED
5499 *             The entity has already been deleted.
5500 * @retval DDS_RETCODE_TIMEOUT
5501 *             The writer failed to write the serialized value reliably within the specified max_blocking_time.
5502 */
5503DDS_EXPORT dds_return_t
5504dds_forwardcdr(dds_entity_t writer, struct ddsi_serdata *serdata);
5505
5506/**
5507 * @brief Write the value of a data instance along with the source timestamp passed.
5508 *
5509 * @param[in]  writer The writer entity.
5510 * @param[in]  data Value to be written.
5511 * @param[in]  timestamp Source timestamp.
5512 *
5513 * @returns A dds_return_t indicating success or failure.
5514 */
5515DDS_EXPORT dds_return_t
5516dds_write_ts(
5517  dds_entity_t writer,
5518  const void *data,
5519  dds_time_t timestamp);
5520
5521/**
5522 * @brief Creates a readcondition associated to the given reader.
5523 *
5524 * The readcondition allows specifying which samples are of interest in
5525 * a data reader's history, by means of a mask. The mask is or'd with
5526 * the flags that are dds_sample_state_t, dds_view_state_t and
5527 * dds_instance_state_t.
5528 *
5529 * Based on the mask value set, the readcondition gets triggered when
5530 * data is available on the reader.
5531 *
5532 * Waitsets allow waiting for an event on some of any set of entities.
5533 * This means that the readcondition can be used to wake up a waitset when
5534 * data is in the reader history with states that matches the given mask.
5535 *
5536 * @note The parent reader and every of its associated conditions (whether
5537 *       they are readconditions or queryconditions) share the same resources.
5538 *       This means that one of these entities reads or takes data, the states
5539 *       of the data will change for other entities automatically. For instance,
5540 *       if one reads a sample, then the sample state will become 'read' for all
5541 *       associated reader/conditions. Or if one takes a sample, then it's not
5542 *       available to any other associated reader/condition.
5543 *
5544 * @param[in]  reader  Reader to associate the condition to.
5545 * @param[in]  mask    Interest (dds_sample_state_t|dds_view_state_t|dds_instance_state_t).
5546 *
5547 * @returns A valid condition handle or an error code.
5548 *
5549 * @retval >0
5550 *             A valid condition handle
5551 * @retval DDS_RETCODE_ERROR
5552 *             An internal error has occurred.
5553 * @retval DDS_RETCODE_ILLEGAL_OPERATION
5554 *             The operation is invoked on an inappropriate object.
5555 * @retval DDS_RETCODE_ALREADY_DELETED
5556 *             The entity has already been deleted.
5557 */
5558DDS_EXPORT dds_entity_t
5559dds_create_readcondition(dds_entity_t reader, uint32_t mask);
5560
5561typedef bool (*dds_querycondition_filter_fn) (const void * sample);
5562
5563/**
5564 * @brief Creates a queryondition associated to the given reader.
5565 *
5566 * The queryondition allows specifying which samples are of interest in
5567 * a data reader's history, by means of a mask and a filter. The mask is
5568 * or'd with the flags that are dds_sample_state_t, dds_view_state_t and
5569 * dds_instance_state_t.
5570 *
5571 * Based on the mask value set and data that matches the filter, the
5572 * querycondition gets triggered when data is available on the reader.
5573 *
5574 * Waitsets allow waiting for an event on some of any set of entities.
5575 * This means that the querycondition can be used to wake up a waitset when
5576 * data is in the reader history with states that matches the given mask
5577 * and filter.
5578 *
5579 * @note The parent reader and every of its associated conditions (whether
5580 *       they are readconditions or queryconditions) share the same resources.
5581 *       This means that one of these entities reads or takes data, the states
5582 *       of the data will change for other entities automatically. For instance,
5583 *       if one reads a sample, then the sample state will become 'read' for all
5584 *       associated reader/conditions. Or if one takes a sample, then it's not
5585 *       available to any other associated reader/condition.
5586 *
5587 * @param[in]  reader  Reader to associate the condition to.
5588 * @param[in]  mask    Interest (dds_sample_state_t|dds_view_state_t|dds_instance_state_t).
5589 * @param[in]  filter  Callback that the application can use to filter specific samples.
5590 *
5591 * @returns A valid condition handle or an error code
5592 *
5593 * @retval >=0
5594 *             A valid condition handle.
5595 * @retval DDS_RETCODE_ERROR
5596 *             An internal error has occurred.
5597 * @retval DDS_RETCODE_ILLEGAL_OPERATION
5598 *             The operation is invoked on an inappropriate object.
5599 * @retval DDS_RETCODE_ALREADY_DELETED
5600 *             The entity has already been deleted.
5601 */
5602/* TODO: Explain the filter (aka expression & parameters) of the (to be
5603 *       implemented) new querycondition implementation.
5604 * TODO: Update parameters when new querycondition is introduced.
5605 */
5606DDS_EXPORT dds_entity_t
5607dds_create_querycondition(
5608  dds_entity_t reader,
5609  uint32_t mask,
5610  dds_querycondition_filter_fn filter);
5611
5612/**
5613 * @brief Creates a guardcondition.
5614 *
5615 * Waitsets allow waiting for an event on some of any set of entities.
5616 * This means that the guardcondition can be used to wake up a waitset when
5617 * data is in the reader history with states that matches the given mask.
5618 *
5619 * @returns A valid condition handle or an error code.
5620 *
5621 * @retval >0
5622 *             A valid condition handle
5623 * @retval DDS_RETCODE_ERROR
5624 *             An internal error has occurred.
5625 * @retval DDS_RETCODE_ILLEGAL_OPERATION
5626 *             The operation is invoked on an inappropriate object.
5627 * @retval DDS_RETCODE_ALREADY_DELETED
5628 *             The entity has already been deleted.
5629 */
5630DDS_EXPORT dds_entity_t
5631dds_create_guardcondition(dds_entity_t participant);
5632
5633/**
5634 * @brief Sets the trigger status of a guardcondition.
5635 *
5636 * @retval DDS_RETCODE_OK
5637 *             Operation successful
5638 * @retval DDS_RETCODE_ERROR
5639 *             An internal error has occurred.
5640 * @retval DDS_RETCODE_ILLEGAL_OPERATION
5641 *             The operation is invoked on an inappropriate object.
5642 * @retval DDS_RETCODE_ALREADY_DELETED
5643 *             The entity has already been deleted.
5644 */
5645DDS_EXPORT dds_return_t
5646dds_set_guardcondition(dds_entity_t guardcond, bool triggered);
5647
5648/**
5649 * @brief Reads the trigger status of a guardcondition.
5650 *
5651 * @retval DDS_RETCODE_OK
5652 *             Operation successful
5653 * @retval DDS_RETCODE_ERROR
5654 *             An internal error has occurred.
5655 * @retval DDS_RETCODE_ILLEGAL_OPERATION
5656 *             The operation is invoked on an inappropriate object.
5657 * @retval DDS_RETCODE_ALREADY_DELETED
5658 *             The entity has already been deleted.
5659 */
5660DDS_EXPORT dds_return_t
5661dds_read_guardcondition(dds_entity_t guardcond, bool *triggered);
5662
5663/**
5664 * @brief Reads and resets the trigger status of a guardcondition.
5665 *
5666 * @retval DDS_RETCODE_OK
5667 *             Operation successful
5668 * @retval DDS_RETCODE_ERROR
5669 *             An internal error has occurred.
5670 * @retval DDS_RETCODE_ILLEGAL_OPERATION
5671 *             The operation is invoked on an inappropriate object.
5672 * @retval DDS_RETCODE_ALREADY_DELETED
5673 *             The entity has already been deleted.
5674 */
5675DDS_EXPORT dds_return_t
5676dds_take_guardcondition(dds_entity_t guardcond, bool *triggered);
5677
5678/**
5679 * @brief Waitset attachment argument.
5680 *
5681 * Every entity that is attached to the waitset can be accompanied by such
5682 * an attachment argument. When the waitset wait is unblocked because of an
5683 * entity that triggered, then the returning array will be populated with
5684 * these attachment arguments that are related to the triggered entity.
5685 */
5686typedef intptr_t dds_attach_t;
5687
5688/**
5689 * @brief Create a waitset and allocate the resources required
5690 *
5691 * A WaitSet object allows an application to wait until one or more of the
5692 * conditions of the attached entities evaluates to TRUE or until the timeout
5693 * expires.
5694 *
5695 * @param[in]  participant  Domain participant which the WaitSet contains.
5696 *
5697 * @returns A valid waitset handle or an error code.
5698 *
5699 * @retval >=0
5700 *             A valid waitset handle.
5701 * @retval DDS_RETCODE_ERROR
5702 *             An internal error has occurred.
5703 * @retval DDS_RETCODE_ILLEGAL_OPERATION
5704 *             The operation is invoked on an inappropriate object.
5705 * @retval DDS_RETCODE_ALREADY_DELETED
5706 *             The entity has already been deleted.
5707 */
5708DDS_EXPORT dds_entity_t
5709dds_create_waitset(dds_entity_t participant);
5710
5711/**
5712 * @brief Acquire previously attached entities.
5713 *
5714 * This functions takes a pre-allocated list to put the entities in and
5715 * will return the number of found entities. It is possible that the given
5716 * size of the list is not the same as the number of found entities. If
5717 * less entities are found, then the last few entries in the list are
5718 * untouched. When more entities are found, then only 'size' number of
5719 * entries are inserted into the list, but still the complete count of the
5720 * found entities is returned. Which entities are returned in the latter
5721 * case is undefined.
5722 *
5723 * @param[in]  waitset  Waitset from which to get its attached entities.
5724 * @param[out] entities Pre-allocated array to contain the found entities.
5725 * @param[in]  size     Size of the pre-allocated entities' list.
5726 *
5727 * @returns A dds_return_t with the number of children or an error code.
5728 *
5729 * @retval >=0
5730 *             Number of children found (can be larger than 'size').
5731 * @retval DDS_RETCODE_ERROR
5732 *             An internal error has occurred.
5733 * @retval DDS_RETCODE_BAD_PARAMETER
5734 *             The entities parameter is NULL, while a size is provided.
5735 * @retval DDS_RETCODE_ILLEGAL_OPERATION
5736 *             The operation is invoked on an inappropriate object.
5737 * @retval DDS_RETCODE_ALREADY_DELETED
5738 *             The waitset has already been deleted.
5739 */
5740DDS_EXPORT dds_return_t
5741dds_waitset_get_entities(
5742  dds_entity_t waitset,
5743  dds_entity_t *entities,
5744  size_t size);
5745
5746/**
5747 * @brief This operation attaches an Entity to the WaitSet.
5748 *
5749 * This operation attaches an Entity to the WaitSet. The dds_waitset_wait()
5750 * will block when none of the attached entities are triggered. 'Triggered'
5751 * (dds_triggered()) doesn't mean the same for every entity:
5752 *  - Reader/Writer/Publisher/Subscriber/Topic/Participant
5753 *      - These are triggered when their status changed.
5754 *  - WaitSet
5755 *      - Triggered when trigger value was set to true by the application.
5756 *        It stays triggered until application sets the trigger value to
5757 *        false (dds_waitset_set_trigger()). This can be used to wake up an
5758 *        waitset for different reasons (f.i. termination) than the 'normal'
5759 *        status change (like new data).
5760 *  - ReadCondition/QueryCondition
5761 *      - Triggered when data is available on the related Reader that matches
5762 *        the Condition.
5763 *
5764 * Multiple entities can be attached to a single waitset. A particular entity
5765 * can be attached to multiple waitsets. However, a particular entity can not
5766 * be attached to a particular waitset multiple times.
5767 *
5768 * @param[in]  waitset  The waitset to attach the given entity to.
5769 * @param[in]  entity   The entity to attach.
5770 * @param[in]  x        Blob that will be supplied when the waitset wait is
5771 *                      triggerd by the given entity.
5772 *
5773 * @returns A dds_return_t indicating success or failure.
5774 *
5775 * @retval DDS_RETCODE_OK
5776 *             Entity attached.
5777 * @retval DDS_RETCODE_ERROR
5778 *             An internal error has occurred.
5779 * @retval DDS_RETCODE_BAD_PARAMETER
5780 *             The given waitset or entity are not valid.
5781 * @retval DDS_RETCODE_ILLEGAL_OPERATION
5782 *             The operation is invoked on an inappropriate object.
5783 * @retval DDS_RETCODE_ALREADY_DELETED
5784 *             The waitset has already been deleted.
5785 * @retval DDS_RETCODE_PRECONDITION_NOT_MET
5786 *             The entity was already attached.
5787 */
5788DDS_EXPORT dds_return_t
5789dds_waitset_attach(
5790  dds_entity_t waitset,
5791  dds_entity_t entity,
5792  dds_attach_t x);
5793
5794/**
5795 * @brief This operation detaches an Entity to the WaitSet.
5796 *
5797 * @param[in]  waitset  The waitset to detach the given entity from.
5798 * @param[in]  entity   The entity to detach.
5799 *
5800 * @returns A dds_return_t indicating success or failure.
5801 *
5802 * @retval DDS_RETCODE_OK
5803 *             Entity detached.
5804 * @retval DDS_RETCODE_ERROR
5805 *             An internal error has occurred.
5806 * @retval DDS_RETCODE_BAD_PARAMETER
5807 *             The given waitset or entity are not valid.
5808 * @retval DDS_RETCODE_ILLEGAL_OPERATION
5809 *             The operation is invoked on an inappropriate object.
5810 * @retval DDS_RETCODE_ALREADY_DELETED
5811 *             The waitset has already been deleted.
5812 * @retval DDS_RETCODE_PRECONDITION_NOT_MET
5813 *             The entity is not attached.
5814 */
5815DDS_EXPORT dds_return_t
5816dds_waitset_detach(
5817  dds_entity_t waitset,
5818  dds_entity_t entity);
5819
5820/**
5821 * @brief Sets the trigger_value associated with a waitset.
5822 *
5823 * When the waitset is attached to itself and the trigger value is
5824 * set to 'true', then the waitset will wake up just like with an
5825 * other status change of the attached entities.
5826 *
5827 * This can be used to forcefully wake up a waitset, for instance
5828 * when the application wants to shut down. So, when the trigger
5829 * value is true, the waitset will wake up or not wait at all.
5830 *
5831 * The trigger value will remain true until the application sets it
5832 * false again deliberately.
5833 *
5834 * @param[in]  waitset  The waitset to set the trigger value on.
5835 * @param[in]  trigger  The trigger value to set.
5836 *
5837 * @returns A dds_return_t indicating success or failure.
5838 *
5839 * @retval DDS_RETCODE_OK
5840 *             Trigger value set.
5841 * @retval DDS_RETCODE_ERROR
5842 *             An internal error has occurred.
5843 * @retval DDS_RETCODE_BAD_PARAMETER
5844 *             The given waitset is not valid.
5845 * @retval DDS_RETCODE_ILLEGAL_OPERATION
5846 *             The operation is invoked on an inappropriate object.
5847 * @retval DDS_RETCODE_ALREADY_DELETED
5848 *             The waitset has already been deleted.
5849 */
5850DDS_EXPORT dds_return_t
5851dds_waitset_set_trigger(
5852  dds_entity_t waitset,
5853  bool trigger);
5854
5855/**
5856 * @brief This operation allows an application thread to wait for the a status
5857 *        change or other trigger on (one of) the entities that are attached to
5858 *        the WaitSet.
5859 *
5860 * The "dds_waitset_wait" operation blocks until the some of the attached
5861 * entities have triggered or "reltimeout" has elapsed.
5862 * 'Triggered' (dds_triggered()) doesn't mean the same for every entity:
5863 *  - Reader/Writer/Publisher/Subscriber/Topic/Participant
5864 *      - These are triggered when their status changed.
5865 *  - WaitSet
5866 *      - Triggered when trigger value was set to true by the application.
5867 *        It stays triggered until application sets the trigger value to
5868 *        false (dds_waitset_set_trigger()). This can be used to wake up an
5869 *        waitset for different reasons (f.i. termination) than the 'normal'
5870 *        status change (like new data).
5871 *  - ReadCondition/QueryCondition
5872 *      - Triggered when data is available on the related Reader that matches
5873 *        the Condition.
5874 *
5875 * This functions takes a pre-allocated list to put the "xs" blobs in (that
5876 * were provided during the attach of the related entities) and will return
5877 * the number of triggered entities. It is possible that the given size
5878 * of the list is not the same as the number of triggered entities. If less
5879 * entities were triggered, then the last few entries in the list are
5880 * untouched. When more entities are triggered, then only 'size' number of
5881 * entries are inserted into the list, but still the complete count of the
5882 * triggered entities is returned. Which "xs" blobs are returned in the
5883 * latter case is undefined.
5884 *
5885 * In case of a time out, the return value is 0.
5886 *
5887 * Deleting the waitset while the application is blocked results in an
5888 * error code (i.e. < 0) returned by "wait".
5889 *
5890 * Multiple threads may block on a single waitset at the same time;
5891 * the calls are entirely independent.
5892 *
5893 * An empty waitset never triggers (i.e., dds_waitset_wait on an empty
5894 * waitset is essentially equivalent to a sleep).
5895 *
5896 * The "dds_waitset_wait_until" operation is the same as the
5897 * "dds_waitset_wait" except that it takes an absolute timeout.
5898 *
5899 * @param[in]  waitset    The waitset to set the trigger value on.
5900 * @param[out] xs         Pre-allocated list to store the 'blobs' that were
5901 *                        provided during the attach of the triggered entities.
5902 * @param[in]  nxs        The size of the pre-allocated blobs list.
5903 * @param[in]  reltimeout Relative timeout
5904 *
5905 * @returns A dds_return_t with the number of entities triggered or an error code
5906 *
5907 * @retval >0
5908 *             Number of entities triggered.
5909 * @retval  0
5910 *             Time out (no entities were triggered).
5911 * @retval DDS_RETCODE_ERROR
5912 *             An internal error has occurred.
5913 * @retval DDS_RETCODE_BAD_PARAMETER
5914 *             The given waitset is not valid.
5915 * @retval DDS_RETCODE_ILLEGAL_OPERATION
5916 *             The operation is invoked on an inappropriate object.
5917 * @retval DDS_RETCODE_ALREADY_DELETED
5918 *             The waitset has already been deleted.
5919 */
5920DDS_EXPORT dds_return_t
5921dds_waitset_wait(
5922  dds_entity_t waitset,
5923  dds_attach_t *xs,
5924  size_t nxs,
5925  dds_duration_t reltimeout);
5926
5927/**
5928 * @brief This operation allows an application thread to wait for the a status
5929 *        change or other trigger on (one of) the entities that are attached to
5930 *        the WaitSet.
5931 *
5932 * The "dds_waitset_wait" operation blocks until the some of the attached
5933 * entities have triggered or "abstimeout" has been reached.
5934 * 'Triggered' (dds_triggered()) doesn't mean the same for every entity:
5935 *  - Reader/Writer/Publisher/Subscriber/Topic/Participant
5936 *      - These are triggered when their status changed.
5937 *  - WaitSet
5938 *      - Triggered when trigger value was set to true by the application.
5939 *        It stays triggered until application sets the trigger value to
5940 *        false (dds_waitset_set_trigger()). This can be used to wake up an
5941 *        waitset for different reasons (f.i. termination) than the 'normal'
5942 *        status change (like new data).
5943 *  - ReadCondition/QueryCondition
5944 *      - Triggered when data is available on the related Reader that matches
5945 *        the Condition.
5946 *
5947 * This functions takes a pre-allocated list to put the "xs" blobs in (that
5948 * were provided during the attach of the related entities) and will return
5949 * the number of triggered entities. It is possible that the given size
5950 * of the list is not the same as the number of triggered entities. If less
5951 * entities were triggered, then the last few entries in the list are
5952 * untouched. When more entities are triggered, then only 'size' number of
5953 * entries are inserted into the list, but still the complete count of the
5954 * triggered entities is returned. Which "xs" blobs are returned in the
5955 * latter case is undefined.
5956 *
5957 * In case of a time out, the return value is 0.
5958 *
5959 * Deleting the waitset while the application is blocked results in an
5960 * error code (i.e. < 0) returned by "wait".
5961 *
5962 * Multiple threads may block on a single waitset at the same time;
5963 * the calls are entirely independent.
5964 *
5965 * An empty waitset never triggers (i.e., dds_waitset_wait on an empty
5966 * waitset is essentially equivalent to a sleep).
5967 *
5968 * The "dds_waitset_wait" operation is the same as the
5969 * "dds_waitset_wait_until" except that it takes an relative timeout.
5970 *
5971 * The "dds_waitset_wait" operation is the same as the "dds_wait"
5972 * except that it takes an absolute timeout.
5973 *
5974 * @param[in]  waitset    The waitset to set the trigger value on.
5975 * @param[out] xs         Pre-allocated list to store the 'blobs' that were
5976 *                        provided during the attach of the triggered entities.
5977 * @param[in]  nxs        The size of the pre-allocated blobs list.
5978 * @param[in]  abstimeout Absolute timeout
5979 *
5980 * @returns A dds_return_t with the number of entities triggered or an error code.
5981 *
5982 * @retval >0
5983 *             Number of entities triggered.
5984 * @retval  0
5985 *             Time out (no entities were triggered).
5986 * @retval DDS_RETCODE_ERROR
5987 *             An internal error has occurred.
5988 * @retval DDS_RETCODE_BAD_PARAMETER
5989 *             The given waitset is not valid.
5990 * @retval DDS_RETCODE_ILLEGAL_OPERATION
5991 *             The operation is invoked on an inappropriate object.
5992 * @retval DDS_RETCODE_ALREADY_DELETED
5993 *             The waitset has already been deleted.
5994 */
5995DDS_EXPORT dds_return_t
5996dds_waitset_wait_until(
5997  dds_entity_t waitset,
5998  dds_attach_t *xs,
5999  size_t nxs,
6000  dds_time_t abstimeout);
6001
6002/*
6003  There are a number of read and take variations.
6004
6005  Return value is the number of elements returned. "max_samples"
6006  should have the same type, as one can't return more than MAX_INT
6007  this way, anyway. X, Y, CX, CY return to the various filtering
6008  options, see the DCPS spec.
6009
6010  O ::= read | take
6011
6012  X             => CX
6013  (empty)          (empty)
6014  _next_instance   instance_handle_t prev
6015
6016  Y             => CY
6017  (empty)          uint32_t mask
6018  _cond            cond_t cond -- refers to a read condition (or query if implemented)
6019 */
6020
6021/**
6022 * @brief Access and read the collection of data values (of same type) and sample info from the
6023 *        data reader, readcondition or querycondition.
6024 *
6025 * Return value provides information about number of samples read, which will
6026 * be <= maxs. Based on the count, the buffer will contain data to be read only
6027 * when valid_data bit in sample info structure is set.
6028 * The buffer required for data values, could be allocated explicitly or can
6029 * use the memory from data reader to prevent copy. In the latter case, buffer and
6030 * sample_info should be returned back, once it is no longer using the Data.
6031 * Data values once read will remain in the buffer with the sample_state set to READ
6032 * and view_state set to NOT_NEW.
6033 *
6034 * @param[in]  reader_or_condition Reader, readcondition or querycondition entity.
6035 * @param[out] buf An array of pointers to samples into which data is read (pointers can be NULL).
6036 * @param[out] si Pointer to an array of \ref dds_sample_info_t returned for each data value.
6037 * @param[in]  bufsz The size of buffer provided.
6038 * @param[in]  maxs Maximum number of samples to read.
6039 *
6040 * @returns A dds_return_t with the number of samples read or an error code.
6041 *
6042 * @retval >=0
6043 *             Number of samples read.
6044 * @retval DDS_RETCODE_ERROR
6045 *             An internal error has occurred.
6046 * @retval DDS_RETCODE_BAD_PARAMETER
6047 *             One of the given arguments is not valid.
6048 * @retval DDS_RETCODE_ILLEGAL_OPERATION
6049 *             The operation is invoked on an inappropriate object.
6050 * @retval DDS_RETCODE_ALREADY_DELETED
6051 *             The entity has already been deleted.
6052 */
6053DDS_EXPORT dds_return_t
6054dds_read(
6055  dds_entity_t reader_or_condition,
6056  void **buf,
6057  dds_sample_info_t *si,
6058  size_t bufsz,
6059  uint32_t maxs);
6060
6061/**
6062 * @brief Access and read loaned samples of data reader, readcondition or querycondition.
6063 *
6064 * After dds_read_wl function is being called and the data has been handled, dds_return_loan function must be called to possibly free memory.
6065 *
6066 * @param[in]  reader_or_condition Reader, readcondition or querycondition entity
6067 * @param[out] buf An array of pointers to samples into which data is read (pointers can be NULL)
6068 * @param[out] si Pointer to an array of \ref dds_sample_info_t returned for each data value
6069 * @param[in]  maxs Maximum number of samples to read
6070 *
6071 * @returns A dds_return_t with the number of samples read or an error code
6072 *
6073 * @retval >=0
6074 *             Number of samples read.
6075 * @retval DDS_RETCODE_ERROR
6076 *             An internal error has occurred.
6077 * @retval DDS_RETCODE_BAD_PARAMETER
6078 *             One of the given arguments is not valid.
6079 * @retval DDS_RETCODE_ILLEGAL_OPERATION
6080 *             The operation is invoked on an inappropriate object.
6081 * @retval DDS_RETCODE_ALREADY_DELETED
6082 *             The entity has already been deleted.
6083 */
6084DDS_EXPORT dds_return_t
6085dds_read_wl(
6086  dds_entity_t reader_or_condition,
6087  void **buf,
6088  dds_sample_info_t *si,
6089  uint32_t maxs);
6090
6091/**
6092 * @brief Read the collection of data values and sample info from the data reader, readcondition
6093 *        or querycondition based on mask.
6094 *
6095 * When using a readcondition or querycondition, their masks are or'd with the given mask.
6096 *
6097 * @param[in]  reader_or_condition Reader, readcondition or querycondition entity.
6098 * @param[out] buf An array of pointers to samples into which data is read (pointers can be NULL).
6099 * @param[out] si Pointer to an array of \ref dds_sample_info_t returned for each data value.
6100 * @param[in]  bufsz The size of buffer provided.
6101 * @param[in]  maxs Maximum number of samples to read.
6102 * @param[in]  mask Filter the data based on dds_sample_state_t|dds_view_state_t|dds_instance_state_t.
6103 *
6104 * @returns A dds_return_t with the number of samples read or an error code.
6105 *
6106 * @retval >=0
6107 *             Number of samples read.
6108 * @retval DDS_RETCODE_ERROR
6109 *             An internal error has occurred.
6110 * @retval DDS_RETCODE_BAD_PARAMETER
6111 *             One of the given arguments is not valid.
6112 * @retval DDS_RETCODE_ILLEGAL_OPERATION
6113 *             The operation is invoked on an inappropriate object.
6114 * @retval DDS_RETCODE_ALREADY_DELETED
6115 *             The entity has already been deleted.
6116 */
6117DDS_EXPORT dds_return_t
6118dds_read_mask(
6119  dds_entity_t reader_or_condition,
6120  void **buf,
6121  dds_sample_info_t *si,
6122  size_t bufsz,
6123  uint32_t maxs,
6124  uint32_t mask);
6125
6126/**
6127 * @brief Access and read loaned samples of data reader, readcondition
6128 *        or querycondition based on mask
6129 *
6130 * When using a readcondition or querycondition, their masks are or'd with the given mask.
6131 *
6132 * After dds_read_mask_wl function is being called and the data has been handled, dds_return_loan function must be called to possibly free memory
6133 *
6134 * @param[in]  reader_or_condition Reader, readcondition or querycondition entity.
6135 * @param[out] buf An array of pointers to samples into which data is read (pointers can be NULL).
6136 * @param[out] si Pointer to an array of \ref dds_sample_info_t returned for each data value.
6137 * @param[in]  maxs Maximum number of samples to read.
6138 * @param[in]  mask Filter the data based on dds_sample_state_t|dds_view_state_t|dds_instance_state_t.
6139 *
6140 * @returns A dds_return_t with the number of samples read or an error code.
6141 *
6142 * @retval >=0
6143 *             Number of samples read.
6144 * @retval DDS_RETCODE_ERROR
6145 *             An internal error has occurred.
6146 * @retval DDS_RETCODE_BAD_PARAMETER
6147 *             One of the given arguments is not valid.
6148 * @retval DDS_RETCODE_ILLEGAL_OPERATION
6149 *             The operation is invoked on an inappropriate object.
6150 * @retval DDS_RETCODE_ALREADY_DELETED
6151 *             The entity has already been deleted.
6152 */
6153DDS_EXPORT dds_return_t
6154dds_read_mask_wl(
6155  dds_entity_t reader_or_condition,
6156  void **buf,
6157  dds_sample_info_t *si,
6158  uint32_t maxs,
6159  uint32_t mask);
6160
6161/**
6162 * @brief Access and read the collection of data values (of same type) and sample info from the
6163 *        data reader, readcondition or querycondition, coped by the provided instance handle.
6164 *
6165 * This operation implements the same functionality as dds_read, except that only data scoped to
6166 * the provided instance handle is read.
6167 *
6168 * @param[in]  reader_or_condition Reader, readcondition or querycondition entity.
6169 * @param[out] buf An array of pointers to samples into which data is read (pointers can be NULL).
6170 * @param[out] si Pointer to an array of \ref dds_sample_info_t returned for each data value.
6171 * @param[in]  bufsz The size of buffer provided.
6172 * @param[in]  maxs Maximum number of samples to read.
6173 * @param[in]  handle Instance handle related to the samples to read.
6174 *
6175 * @returns A dds_return_t with the number of samples read or an error code.
6176 *
6177 * @retval >=0
6178 *             Number of samples read.
6179 * @retval DDS_RETCODE_ERROR
6180 *             An internal error has occurred.
6181 * @retval DDS_RETCODE_BAD_PARAMETER
6182 *             One of the given arguments is not valid.
6183 * @retval DDS_RETCODE_ILLEGAL_OPERATION
6184 *             The operation is invoked on an inappropriate object.
6185 * @retval DDS_RETCODE_ALREADY_DELETED
6186 *             The entity has already been deleted.
6187 * @retval DDS_RETCODE_PRECONDITION_NOT_MET
6188 *             The instance handle has not been registered with this reader.
6189 */
6190DDS_EXPORT dds_return_t
6191dds_read_instance(
6192  dds_entity_t reader_or_condition,
6193  void **buf,
6194  dds_sample_info_t *si,
6195  size_t bufsz,
6196  uint32_t maxs,
6197  dds_instance_handle_t handle);
6198
6199/**
6200 * @brief Access and read loaned samples of data reader, readcondition or querycondition,
6201 *        scoped by the provided instance handle.
6202 *
6203 * This operation implements the same functionality as dds_read_wl, except that only data
6204 * scoped to the provided instance handle is read.
6205 *
6206 * @param[in]  reader_or_condition Reader, readcondition or querycondition entity.
6207 * @param[out] buf An array of pointers to samples into which data is read (pointers can be NULL).
6208 * @param[out] si Pointer to an array of \ref dds_sample_info_t returned for each data value.
6209 * @param[in]  maxs Maximum number of samples to read.
6210 * @param[in]  handle Instance handle related to the samples to read.
6211 *
6212 * @returns A dds_return_t with the number of samples read or an error code.
6213 *
6214 * @retval >=0
6215 *             Number of samples read.
6216 * @retval DDS_RETCODE_ERROR
6217 *             An internal error has occurred.
6218 * @retval DDS_RETCODE_BAD_PARAMETER
6219 *             One of the given arguments is not valid.
6220 * @retval DDS_RETCODE_ILLEGAL_OPERATION
6221 *             The operation is invoked on an inappropriate object.
6222 * @retval DDS_RETCODE_ALREADY_DELETED
6223 *             The entity has already been deleted.
6224 * @retval DDS_RETCODE_PRECONDITION_NOT_MET
6225 *             The instance handle has not been registered with this reader.
6226 */
6227DDS_EXPORT dds_return_t
6228dds_read_instance_wl(
6229  dds_entity_t reader_or_condition,
6230  void **buf,
6231  dds_sample_info_t *si,
6232  uint32_t maxs,
6233  dds_instance_handle_t handle);
6234
6235/**
6236 * @brief Read the collection of data values and sample info from the data reader, readcondition
6237 *        or querycondition based on mask and scoped by the provided instance handle.
6238 *
6239 * This operation implements the same functionality as dds_read_mask, except that only data
6240 * scoped to the provided instance handle is read.
6241 *
6242 * @param[in]  reader_or_condition Reader, readcondition or querycondition entity.
6243 * @param[out] buf An array of pointers to samples into which data is read (pointers can be NULL).
6244 * @param[out] si Pointer to an array of \ref dds_sample_info_t returned for each data value.
6245 * @param[in]  bufsz The size of buffer provided.
6246 * @param[in]  maxs Maximum number of samples to read.
6247 * @param[in]  handle Instance handle related to the samples to read.
6248 * @param[in]  mask Filter the data based on dds_sample_state_t|dds_view_state_t|dds_instance_state_t.
6249 *
6250 * @returns A dds_return_t with the number of samples read or an error code.
6251 *
6252 * @retval >=0
6253 *             Number of samples read.
6254 * @retval DDS_RETCODE_ERROR
6255 *             An internal error has occurred.
6256 * @retval DDS_RETCODE_BAD_PARAMETER
6257 *             One of the given arguments is not valid.
6258 * @retval DDS_RETCODE_ILLEGAL_OPERATION
6259 *             The operation is invoked on an inappropriate object.
6260 * @retval DDS_RETCODE_ALREADY_DELETED
6261 *             The entity has already been deleted.
6262 * @retval DDS_RETCODE_PRECONDITION_NOT_MET
6263 *             The instance handle has not been registered with this reader.
6264 */
6265DDS_EXPORT dds_return_t
6266dds_read_instance_mask(
6267  dds_entity_t reader_or_condition,
6268  void **buf,
6269  dds_sample_info_t *si,
6270  size_t bufsz,
6271  uint32_t maxs,
6272  dds_instance_handle_t handle,
6273  uint32_t mask);
6274
6275/**
6276 * @brief Access and read loaned samples of data reader, readcondition or
6277 *        querycondition based on mask, scoped by the provided instance handle.
6278 *
6279 * This operation implements the same functionality as dds_read_mask_wl, except that
6280 * only data scoped to the provided instance handle is read.
6281 *
6282 * @param[in]  reader_or_condition Reader, readcondition or querycondition entity.
6283 * @param[out] buf An array of pointers to samples into which data is read (pointers can be NULL).
6284 * @param[out] si Pointer to an array of \ref dds_sample_info_t returned for each data value.
6285 * @param[in]  maxs Maximum number of samples to read.
6286 * @param[in]  handle Instance handle related to the samples to read.
6287 * @param[in]  mask Filter the data based on dds_sample_state_t|dds_view_state_t|dds_instance_state_t.
6288 *
6289 * @returns A dds_return_t with the number of samples read or an error code.
6290 *
6291 * @retval >=0
6292 *             Number of samples read.
6293 * @retval DDS_RETCODE_ERROR
6294 *             An internal error has occurred.
6295 * @retval DDS_RETCODE_BAD_PARAMETER
6296 *             One of the given arguments is not valid.
6297 * @retval DDS_RETCODE_ILLEGAL_OPERATION
6298 *             The operation is invoked on an inappropriate object.
6299 * @retval DDS_RETCODE_ALREADY_DELETED
6300 *             The entity has already been deleted.
6301 * @retval DDS_RETCODE_PRECONDITION_NOT_MET
6302 *             The instance handle has not been registered with this reader.
6303 */
6304DDS_EXPORT dds_return_t
6305dds_read_instance_mask_wl(
6306  dds_entity_t reader_or_condition,
6307  void **buf,
6308  dds_sample_info_t *si,
6309  uint32_t maxs,
6310  dds_instance_handle_t handle,
6311  uint32_t mask);
6312
6313/**
6314 * @brief Access the collection of data values (of same type) and sample info from the
6315 *        data reader, readcondition or querycondition.
6316 *
6317 * Data value once read is removed from the Data Reader cannot to
6318 * 'read' or 'taken' again.
6319 * Return value provides information about number of samples read, which will
6320 * be <= maxs. Based on the count, the buffer will contain data to be read only
6321 * when valid_data bit in sample info structure is set.
6322 * The buffer required for data values, could be allocated explicitly or can
6323 * use the memory from data reader to prevent copy. In the latter case, buffer and
6324 * sample_info should be returned back, once it is no longer using the Data.
6325 *
6326 * @param[in]  reader_or_condition Reader, readcondition or querycondition entity.
6327 * @param[out] buf An array of pointers to samples into which data is read (pointers can be NULL).
6328 * @param[out] si Pointer to an array of \ref dds_sample_info_t returned for each data value.
6329 * @param[in]  bufsz The size of buffer provided.
6330 * @param[in]  maxs Maximum number of samples to read.
6331 *
6332 * @returns A dds_return_t with the number of samples read or an error code.
6333 *
6334 * @retval >=0
6335 *             Number of samples read.
6336 * @retval DDS_RETCODE_ERROR
6337 *             An internal error has occurred.
6338 * @retval DDS_RETCODE_BAD_PARAMETER
6339 *             One of the given arguments is not valid.
6340 * @retval DDS_RETCODE_ILLEGAL_OPERATION
6341 *             The operation is invoked on an inappropriate object.
6342 * @retval DDS_RETCODE_ALREADY_DELETED
6343 *             The entity has already been deleted.
6344 */
6345DDS_EXPORT dds_return_t
6346dds_take(
6347  dds_entity_t reader_or_condition,
6348  void **buf,
6349  dds_sample_info_t *si,
6350  size_t bufsz,
6351  uint32_t maxs);
6352
6353/**
6354 * @brief Access loaned samples of data reader, readcondition or querycondition.
6355 *
6356 * After dds_take_wl function is being called and the data has been handled, dds_return_loan function must be called to possibly free memory
6357 *
6358 * @param[in]  reader_or_condition Reader, readcondition or querycondition entity.
6359 * @param[out] buf An array of pointers to samples into which data is read (pointers can be NULL).
6360 * @param[out] si Pointer to an array of \ref dds_sample_info_t returned for each data value.
6361 * @param[in]  maxs Maximum number of samples to read.
6362 *
6363 * @returns A dds_return_t with the number of samples read or an error code.
6364 *
6365 * @retval >=0
6366 *             Number of samples read.
6367 * @retval DDS_RETCODE_ERROR
6368 *             An internal error has occurred.
6369 * @retval DDS_RETCODE_BAD_PARAMETER
6370 *             One of the given arguments is not valid.
6371 * @retval DDS_RETCODE_ILLEGAL_OPERATION
6372 *             The operation is invoked on an inappropriate object.
6373 * @retval DDS_RETCODE_ALREADY_DELETED
6374 *             The entity has already been deleted.
6375 */
6376DDS_EXPORT dds_return_t
6377dds_take_wl(
6378  dds_entity_t reader_or_condition,
6379  void **buf,
6380  dds_sample_info_t *si,
6381  uint32_t maxs);
6382
6383/**
6384 * @brief Take the collection of data values (of same type) and sample info from the
6385 *        data reader, readcondition or querycondition based on mask
6386 *
6387 * When using a readcondition or querycondition, their masks are or'd with the given mask.
6388 *
6389 * @param[in]  reader_or_condition Reader, readcondition or querycondition entity.
6390 * @param[out] buf An array of pointers to samples into which data is read (pointers can be NULL).
6391 * @param[out] si Pointer to an array of \ref dds_sample_info_t returned for each data value.
6392 * @param[in]  bufsz The size of buffer provided.
6393 * @param[in]  maxs Maximum number of samples to read.
6394 * @param[in]  mask Filter the data based on dds_sample_state_t|dds_view_state_t|dds_instance_state_t.
6395 *
6396 * @returns A dds_return_t with the number of samples read or an error code.
6397 *
6398 * @retval >=0
6399 *             Number of samples read.
6400 * @retval DDS_RETCODE_ERROR
6401 *             An internal error has occurred.
6402 * @retval DDS_RETCODE_BAD_PARAMETER
6403 *             One of the given arguments is not valid.
6404 * @retval DDS_RETCODE_ILLEGAL_OPERATION
6405 *             The operation is invoked on an inappropriate object.
6406 * @retval DDS_RETCODE_ALREADY_DELETED
6407 *             The entity has already been deleted.
6408 */
6409DDS_EXPORT dds_return_t
6410dds_take_mask(
6411  dds_entity_t reader_or_condition,
6412  void **buf,
6413  dds_sample_info_t *si,
6414  size_t bufsz,
6415  uint32_t maxs,
6416  uint32_t mask);
6417
6418/**
6419 * @brief  Access loaned samples of data reader, readcondition or querycondition based on mask.
6420 *
6421 * When using a readcondition or querycondition, their masks are or'd with the given mask.
6422 *
6423 * After dds_take_mask_wl function is being called and the data has been handled, dds_return_loan function must be called to possibly free memory
6424 *
6425 * @param[in]  reader_or_condition Reader, readcondition or querycondition entity.
6426 * @param[out] buf An array of pointers to samples into which data is read (pointers can be NULL).
6427 * @param[out] si Pointer to an array of \ref dds_sample_info_t returned for each data value.
6428 * @param[in]  maxs Maximum number of samples to read.
6429 * @param[in]  mask Filter the data based on dds_sample_state_t|dds_view_state_t|dds_instance_state_t.
6430 *
6431 * @returns A dds_return_t with the number of samples read or an error code.
6432 *
6433 * @retval >=0
6434 *             Number of samples read.
6435 * @retval DDS_RETCODE_ERROR
6436 *             An internal error has occurred.
6437 * @retval DDS_RETCODE_BAD_PARAMETER
6438 *             One of the given arguments is not valid.
6439 * @retval DDS_RETCODE_ILLEGAL_OPERATION
6440 *             The operation is invoked on an inappropriate object.
6441 * @retval DDS_RETCODE_ALREADY_DELETED
6442 *             The entity has already been deleted.
6443 */
6444DDS_EXPORT dds_return_t
6445dds_take_mask_wl(
6446  dds_entity_t reader_or_condition,
6447  void **buf,
6448  dds_sample_info_t *si,
6449  uint32_t maxs,
6450  uint32_t mask);
6451
6452#define DDS_HAS_READCDR 1
6453/**
6454 * @brief Access the collection of serialized data values (of same type) and
6455 *        sample info from the data reader, readcondition or querycondition.
6456 *
6457 * This call accesses the serialized data from the data reader, readcondition or
6458 * querycondition and makes it available to the application. The serialized data
6459 * is made available through \ref ddsi_serdata structures. Returned samples are
6460 * marked as READ.
6461 *
6462 * Return value provides information about the number of samples read, which will
6463 * be <= maxs. Based on the count, the buffer will contain serialized data to be
6464 * read only when valid_data bit in sample info structure is set.
6465 * The buffer required for data values, could be allocated explicitly or can
6466 * use the memory from data reader to prevent copy. In the latter case, buffer and
6467 * sample_info should be returned back, once it is no longer using the data.
6468 *
6469 * @param[in]  reader_or_condition Reader, readcondition or querycondition entity.
6470 * @param[out] buf An array of pointers to \ref ddsi_serdata structures that contain
6471 *                 the serialized data. The pointers can be NULL.
6472 * @param[in]  maxs Maximum number of samples to read.
6473 * @param[out] si Pointer to an array of \ref dds_sample_info_t returned for each data value.
6474 * @param[in]  mask Filter the data based on dds_sample_state_t|dds_view_state_t|dds_instance_state_t.
6475 *
6476 * @returns A dds_return_t with the number of samples read or an error code.
6477 *
6478 * @retval >=0
6479 *             Number of samples read.
6480 * @retval DDS_RETCODE_ERROR
6481 *             An internal error has occurred.
6482 * @retval DDS_RETCODE_BAD_PARAMETER
6483 *             One of the given arguments is not valid.
6484 * @retval DDS_RETCODE_ILLEGAL_OPERATION
6485 *             The operation is invoked on an inappropriate object.
6486 * @retval DDS_RETCODE_ALREADY_DELETED
6487 *             The entity has already been deleted.
6488 * @retval DDS_RETCODE_PRECONDITION_NOT_MET
6489 *             The precondition for this operation is not met.
6490 */
6491DDS_EXPORT dds_return_t
6492dds_readcdr(
6493  dds_entity_t reader_or_condition,
6494  struct ddsi_serdata **buf,
6495  uint32_t maxs,
6496  dds_sample_info_t *si,
6497  uint32_t mask);
6498
6499/**
6500 * @brief Access the collection of serialized data values (of same type) and
6501 *        sample info from the data reader, readcondition or querycondition.
6502 *
6503 * This call accesses the serialized data from the data reader, readcondition or
6504 * querycondition and makes it available to the application. The serialized data
6505 * is made available through \ref ddsi_serdata structures. Once read the data is
6506 * removed from the reader and cannot be 'read' or 'taken' again.
6507 *
6508 * Return value provides information about the number of samples read, which will
6509 * be <= maxs. Based on the count, the buffer will contain serialized data to be
6510 * read only when valid_data bit in sample info structure is set.
6511 * The buffer required for data values, could be allocated explicitly or can
6512 * use the memory from data reader to prevent copy. In the latter case, buffer and
6513 * sample_info should be returned back, once it is no longer using the data.
6514 *
6515 * @param[in]  reader_or_condition Reader, readcondition or querycondition entity.
6516 * @param[out] buf An array of pointers to \ref ddsi_serdata structures that contain
6517 *                 the serialized data. The pointers can be NULL.
6518 * @param[in]  maxs Maximum number of samples to read.
6519 * @param[out] si Pointer to an array of \ref dds_sample_info_t returned for each data value.
6520 * @param[in]  mask Filter the data based on dds_sample_state_t|dds_view_state_t|dds_instance_state_t.
6521 *
6522 * @returns A dds_return_t with the number of samples read or an error code.
6523 *
6524 * @retval >=0
6525 *             Number of samples read.
6526 * @retval DDS_RETCODE_ERROR
6527 *             An internal error has occurred.
6528 * @retval DDS_RETCODE_BAD_PARAMETER
6529 *             One of the given arguments is not valid.
6530 * @retval DDS_RETCODE_ILLEGAL_OPERATION
6531 *             The operation is invoked on an inappropriate object.
6532 * @retval DDS_RETCODE_ALREADY_DELETED
6533 *             The entity has already been deleted.
6534 * @retval DDS_RETCODE_PRECONDITION_NOT_MET
6535 *             The precondition for this operation is not met.
6536 */
6537DDS_EXPORT dds_return_t
6538dds_takecdr(
6539  dds_entity_t reader_or_condition,
6540  struct ddsi_serdata **buf,
6541  uint32_t maxs,
6542  dds_sample_info_t *si,
6543  uint32_t mask);
6544
6545/**
6546 * @brief Access the collection of data values (of same type) and sample info from the
6547 *        data reader, readcondition or querycondition but scoped by the given
6548 *        instance handle.
6549 *
6550 * This operation mplements the same functionality as dds_take, except that only data
6551 * scoped to the provided instance handle is taken.
6552 *
6553 * @param[in]  reader_or_condition Reader, readcondition or querycondition entity.
6554 * @param[out] buf An array of pointers to samples into which data is read (pointers can be NULL).
6555 * @param[out] si Pointer to an array of \ref dds_sample_info_t returned for each data value.
6556 * @param[in]  bufsz The size of buffer provided.
6557 * @param[in]  maxs Maximum number of samples to read.
6558 * @param[in]  handle Instance handle related to the samples to read.
6559 *
6560 * @returns A dds_return_t with the number of samples read or an error code.
6561 *
6562 * @retval >=0
6563 *             Number of samples read.
6564 * @retval DDS_RETCODE_ERROR
6565 *             An internal error has occurred.
6566 * @retval DDS_RETCODE_BAD_PARAMETER
6567 *             One of the given arguments is not valid.
6568 * @retval DDS_RETCODE_ILLEGAL_OPERATION
6569 *             The operation is invoked on an inappropriate object.
6570 * @retval DDS_RETCODE_ALREADY_DELETED
6571 *             The entity has already been deleted.
6572 * @retval DDS_RETCODE_PRECONDITION_NOT_MET
6573 *             The instance handle has not been registered with this reader.
6574 */
6575DDS_EXPORT dds_return_t
6576dds_take_instance(
6577  dds_entity_t reader_or_condition,
6578  void **buf,
6579  dds_sample_info_t *si,
6580  size_t bufsz,
6581  uint32_t maxs,
6582  dds_instance_handle_t handle);
6583
6584/**
6585 * @brief Access loaned samples of data reader, readcondition or querycondition,
6586 *        scoped by the given instance handle.
6587 *
6588 * This operation implements the same functionality as dds_take_wl, except that
6589 * only data scoped to the provided instance handle is read.
6590 *
6591 * @param[in]  reader_or_condition Reader, readcondition or querycondition entity.
6592 * @param[out] buf An array of pointers to samples into which data is read (pointers can be NULL).
6593 * @param[out] si Pointer to an array of \ref dds_sample_info_t returned for each data value.
6594 * @param[in]  maxs Maximum number of samples to read.
6595 * @param[in]  handle Instance handle related to the samples to read.
6596 *
6597 * @returns A dds_return_t with the number of samples read or an error code.
6598 *
6599 * @retval >=0
6600 *             Number of samples read.
6601 * @retval DDS_RETCODE_ERROR
6602 *             An internal error has occurred.
6603 * @retval DDS_RETCODE_BAD_PARAMETER
6604 *             One of the given arguments is not valid.
6605 * @retval DDS_RETCODE_ILLEGAL_OPERATION
6606 *             The operation is invoked on an inappropriate object.
6607 * @retval DDS_RETCODE_ALREADY_DELETED
6608 *             The entity has already been deleted.
6609 * @retval DDS_RETCODE_PRECONDITION_NOT_MET
6610 *             The instance handle has not been registered with this reader.
6611 */
6612DDS_EXPORT dds_return_t
6613dds_take_instance_wl(
6614  dds_entity_t reader_or_condition,
6615  void **buf,
6616  dds_sample_info_t *si,
6617  uint32_t maxs,
6618  dds_instance_handle_t handle);
6619
6620/**
6621 * @brief Take the collection of data values (of same type) and sample info from the
6622 *        data reader, readcondition or querycondition based on mask and scoped
6623 *        by the given instance handle.
6624 *
6625 * This operation implements the same functionality as dds_take_mask, except that only
6626 * data scoped to the provided instance handle is read.
6627 *
6628 * @param[in]  reader_or_condition Reader, readcondition or querycondition entity.
6629 * @param[out] buf An array of pointers to samples into which data is read (pointers can be NULL).
6630 * @param[out] si Pointer to an array of \ref dds_sample_info_t returned for each data value.
6631 * @param[in]  bufsz The size of buffer provided.
6632 * @param[in]  maxs Maximum number of samples to read.
6633 * @param[in]  handle Instance handle related to the samples to read.
6634 * @param[in]  mask Filter the data based on dds_sample_state_t|dds_view_state_t|dds_instance_state_t.
6635 *
6636 * @returns A dds_return_t with the number of samples read or an error code.
6637 *
6638 * @retval >=0
6639 *             Number of samples read.
6640 * @retval DDS_RETCODE_ERROR
6641 *             An internal error has occurred.
6642 * @retval DDS_RETCODE_BAD_PARAMETER
6643 *             One of the given arguments is not valid.
6644 * @retval DDS_RETCODE_ILLEGAL_OPERATION
6645 *             The operation is invoked on an inappropriate object.
6646 * @retval DDS_RETCODE_ALREADY_DELETED
6647 *             The entity has already been deleted.
6648 * @retval DDS_RETCODE_PRECONDITION_NOT_MET
6649 *             The instance handle has not been registered with this reader.
6650 */
6651DDS_EXPORT dds_return_t
6652dds_take_instance_mask(
6653  dds_entity_t reader_or_condition,
6654  void **buf,
6655  dds_sample_info_t *si,
6656  size_t bufsz,
6657  uint32_t maxs,
6658  dds_instance_handle_t handle,
6659  uint32_t mask);
6660
6661/**
6662 * @brief  Access loaned samples of data reader, readcondition or querycondition based
6663 *         on mask and scoped by the given intance handle.
6664 *
6665 * This operation implements the same functionality as dds_take_mask_wl, except that
6666 * only data scoped to the provided instance handle is read.
6667 *
6668 * @param[in]  reader_or_condition Reader, readcondition or querycondition entity.
6669 * @param[out] buf An array of pointers to samples into which data is read (pointers can be NULL).
6670 * @param[out] si Pointer to an array of \ref dds_sample_info_t returned for each data value.
6671 * @param[in]  maxs Maximum number of samples to read.
6672 * @param[in]  handle Instance handle related to the samples to read.
6673 * @param[in]  mask Filter the data based on dds_sample_state_t|dds_view_state_t|dds_instance_state_t.
6674 *
6675 * @returns A dds_return_t with the number of samples or an error code.
6676 *
6677 * @retval >= 0
6678 *             Number of samples read.
6679 * @retval DDS_RETCODE_ERROR
6680 *             An internal error has occurred.
6681 * @retval DDS_RETCODE_BAD_PARAMETER
6682 *             One of the given arguments is not valid.
6683 * @retval DDS_RETCODE_ILLEGAL_OPERATION
6684 *             The operation is invoked on an inappropriate object
6685 * @retval DDS_RETCODE_ALREADY_DELETED
6686 *             The entity has already been deleted.
6687 * @retval DDS_RETCODE_PRECONDITION_NOT_MET
6688 *             The instance handle has not been registered with this reader.
6689 */
6690DDS_EXPORT dds_return_t
6691dds_take_instance_mask_wl(
6692  dds_entity_t reader_or_condition,
6693  void **buf,
6694  dds_sample_info_t *si,
6695  uint32_t maxs,
6696  dds_instance_handle_t handle,
6697  uint32_t mask);
6698
6699/*
6700  The read/take next functions return a single sample. The returned sample
6701  has a sample state of NOT_READ, a view state of ANY_VIEW_STATE and an
6702  instance state of ANY_INSTANCE_STATE.
6703*/
6704
6705/**
6706 * @brief Read, copy and remove the status set for the entity
6707 *
6708 * This operation copies the next, non-previously accessed
6709 * data value and corresponding sample info and removes from
6710 * the data reader. As an entity, only reader is accepted.
6711 *
6712 * @param[in]  reader The reader entity.
6713 * @param[out] buf An array of pointers to samples into which data is read (pointers can be NULL).
6714 * @param[out] si The pointer to \ref dds_sample_info_t returned for a data value.
6715 *
6716 * @returns A dds_return_t indicating success or failure.
6717 *
6718 * @retval DDS_RETCODE_OK
6719 *             The operation was successful.
6720 * @retval DDS_RETCODE_BAD_PARAMETER
6721 *             The entity parameter is not a valid parameter.
6722 * @retval DDS_RETCODE_ILLEGAL_OPERATION
6723 *             The operation is invoked on an inappropriate object.
6724 * @retval DDS_RETCODE_ALREADY_DELETED
6725 *             The entity has already been deleted.
6726 */
6727DDS_EXPORT dds_return_t
6728dds_take_next(
6729  dds_entity_t reader,
6730  void **buf,
6731  dds_sample_info_t *si);
6732
6733/**
6734 * @brief Read, copy and remove the status set for the entity
6735 *
6736 * This operation copies the next, non-previously accessed
6737 * data value and corresponding sample info and removes from
6738 * the data reader. As an entity, only reader is accepted.
6739 *
6740 * After dds_take_next_wl function is being called and the data has been handled,
6741 * dds_return_loan function must be called to possibly free memory.
6742 *
6743 * @param[in]  reader The reader entity.
6744 * @param[out] buf An array of pointers to samples into which data is read (pointers can be NULL).
6745 * @param[out] si The pointer to \ref dds_sample_info_t returned for a data value.
6746 *
6747 * @returns A dds_return_t indicating success or failure.
6748 *
6749 * @retval DDS_RETCODE_OK
6750 *             The operation was successful.
6751 * @retval DDS_RETCODE_BAD_PARAMETER
6752 *             The entity parameter is not a valid parameter.
6753 * @retval DDS_RETCODE_ILLEGAL_OPERATION
6754 *             The operation is invoked on an inappropriate object.
6755 * @retval DDS_RETCODE_ALREADY_DELETED
6756 *             The entity has already been deleted.
6757 */
6758DDS_EXPORT dds_return_t
6759dds_take_next_wl(
6760  dds_entity_t reader,
6761  void **buf,
6762  dds_sample_info_t *si);
6763
6764/**
6765 * @brief Read and copy the status set for the entity
6766 *
6767 * This operation copies the next, non-previously accessed
6768 * data value and corresponding sample info. As an entity,
6769 * only reader is accepted.
6770 *
6771 * @param[in]  reader The reader entity.
6772 * @param[out] buf An array of pointers to samples into which data is read (pointers can be NULL).
6773 * @param[out] si The pointer to \ref dds_sample_info_t returned for a data value.
6774 *
6775 * @returns A dds_return_t indicating success or failure.
6776 *
6777 * @retval DDS_RETCODE_OK
6778 *             The operation was successful.
6779 * @retval DDS_RETCODE_BAD_PARAMETER
6780 *             The entity parameter is not a valid parameter.
6781 * @retval DDS_RETCODE_ILLEGAL_OPERATION
6782 *             The operation is invoked on an inappropriate object.
6783 * @retval DDS_RETCODE_ALREADY_DELETED
6784 *             The entity has already been deleted.
6785 */
6786DDS_EXPORT dds_return_t
6787dds_read_next(
6788  dds_entity_t reader,
6789  void **buf,
6790  dds_sample_info_t *si);
6791
6792/**
6793 * @brief Read and copy the status set for the loaned sample
6794 *
6795 * This operation copies the next, non-previously accessed
6796 * data value and corresponding loaned sample info. As an entity,
6797 * only reader is accepted.
6798 *
6799 * After dds_read_next_wl function is being called and the data has been handled,
6800 * dds_return_loan function must be called to possibly free memory.
6801 *
6802 * @param[in]  reader The reader entity.
6803 * @param[out] buf An array of pointers to samples into which data is read (pointers can be NULL).
6804 * @param[out] si The pointer to \ref dds_sample_info_t returned for a data value.
6805 *
6806 * @returns A dds_return_t indicating success or failure.
6807 *
6808 * @retval DDS_RETCODE_OK
6809 *             The operation was successful.
6810 * @retval DDS_RETCODE_BAD_PARAMETER
6811 *             The entity parameter is not a valid parameter.
6812 * @retval DDS_RETCODE_ILLEGAL_OPERATION
6813 *             The operation is invoked on an inappropriate object.
6814 * @retval DDS_RETCODE_ALREADY_DELETED
6815 *             The entity has already been deleted.
6816 */
6817DDS_EXPORT dds_return_t
6818dds_read_next_wl(
6819  dds_entity_t reader,
6820  void **buf,
6821  dds_sample_info_t *si);
6822
6823/**
6824 * @brief Return loaned samples to data-reader or condition associated with a data-reader
6825 *
6826 * Used to release sample buffers returned by a read/take operation. When the application
6827 * provides an empty buffer, memory is allocated and managed by DDS. By calling dds_return_loan,
6828 * the memory is released so that the buffer can be reused during a successive read/take operation.
6829 * When a condition is provided, the reader to which the condition belongs is looked up.
6830 *
6831 * @param[in] reader_or_condition Reader or condition that belongs to a reader.
6832 * @param[in] buf An array of (pointers to) samples.
6833 * @param[in] bufsz The number of (pointers to) samples stored in buf.
6834 *
6835 * @returns A dds_return_t indicating success or failure
6836 */
6837/* TODO: Add list of possible return codes */
6838DDS_EXPORT dds_return_t
6839dds_return_loan(
6840  dds_entity_t reader_or_condition,
6841  void **buf,
6842  int32_t bufsz);
6843
6844/*
6845  Instance handle <=> key value mapping.
6846  Functions exactly as read w.r.t. treatment of data
6847  parameter. On output, only key values set.
6848
6849    T x = { ... };
6850    T y;
6851    dds_instance_handle_t ih;
6852    ih = dds_lookup_instance (e, &x);
6853    dds_instance_get_key (e, ih, &y);
6854*/
6855
6856/**
6857 * @brief This operation takes a sample and returns an instance handle to be used for subsequent operations.
6858 *
6859 * @param[in]  entity Reader or Writer entity.
6860 * @param[in]  data   Sample with a key fields set.
6861 *
6862 * @returns instance handle or DDS_HANDLE_NIL if instance could not be found from key.
6863 */
6864DDS_EXPORT dds_instance_handle_t
6865dds_lookup_instance(dds_entity_t entity, const void *data);
6866
6867DDS_DEPRECATED_EXPORT dds_instance_handle_t
6868dds_instance_lookup(dds_entity_t entity, const void *data);
6869
6870/**
6871 * @brief This operation takes an instance handle and return a key-value corresponding to it.
6872 *
6873 * @param[in]  entity Reader, writer, readcondition or querycondition entity.
6874 * @param[in]  inst   Instance handle.
6875 * @param[out] data   pointer to an instance, to which the key ID corresponding to the instance handle will be
6876 *    returned, the sample in the instance should be ignored.
6877 *
6878 * @returns A dds_return_t indicating success or failure.
6879 *
6880 * @retval DDS_RETCODE_OK
6881 *             The operation was successful.
6882 * @retval DDS_RETCODE_BAD_PARAMETER
6883 *             One of the parameters was invalid or the topic does not exist.
6884 * @retval DDS_RETCODE_ERROR
6885 *             An internal error has occurred.
6886 */
6887/* TODO: Check return codes for completeness */
6888DDS_EXPORT dds_return_t
6889dds_instance_get_key(
6890  dds_entity_t entity,
6891  dds_instance_handle_t inst,
6892  void *data);
6893
6894/**
6895 * @brief Begin coherent publishing or begin accessing a coherent set in a subscriber
6896 *
6897 * Invoking on a Writer or Reader behaves as if dds_begin_coherent was invoked on its parent
6898 * Publisher or Subscriber respectively.
6899 *
6900 * @param[in]  entity The entity that is prepared for coherent access.
6901 *
6902 * @returns A dds_return_t indicating success or failure.
6903 *
6904 * @retval DDS_RETCODE_OK
6905 *             The operation was successful.
6906 * @retval DDS_RETCODE_ERROR
6907 *             An internal error has occurred.
6908 * @retval DDS_RETCODE_BAD_PARAMETER
6909 *             The provided entity is invalid or not supported.
6910 */
6911DDS_EXPORT dds_return_t
6912dds_begin_coherent(dds_entity_t entity);
6913
6914/**
6915 * @brief End coherent publishing or end accessing a coherent set in a subscriber
6916 *
6917 * Invoking on a Writer or Reader behaves as if dds_end_coherent was invoked on its parent
6918 * Publisher or Subscriber respectively.
6919 *
6920 * @param[in] entity The entity on which coherent access is finished.
6921 *
6922 * @returns A dds_return_t indicating success or failure.
6923 *
6924 * @retval DDS_RETCODE_OK
6925 *             The operation was successful.
6926 * @retval DDS_RETCODE_BAD_PARAMETER
6927 *             The provided entity is invalid or not supported.
6928 */
6929DDS_EXPORT dds_return_t
6930dds_end_coherent(dds_entity_t entity);
6931
6932/**
6933 * @brief Trigger DATA_AVAILABLE event on contained readers
6934 *
6935 * The DATA_AVAILABLE event is broadcast to all readers owned by this subscriber that currently
6936 * have new data available. Any on_data_available listener callbacks attached to respective
6937 * readers are invoked.
6938 *
6939 * @param[in] subscriber A valid subscriber handle.
6940 *
6941 * @returns A dds_return_t indicating success or failure.
6942 *
6943 * @retval DDS_RETCODE_OK
6944 *             The operation was successful.
6945 * @retval DDS_RETCODE_BAD_PARAMETER
6946 *             The provided subscriber is invalid.
6947 */
6948DDS_EXPORT dds_return_t
6949dds_notify_readers(dds_entity_t subscriber);
6950
6951/**
6952 * @brief Checks whether the entity has one of its enabled statuses triggered.
6953 *
6954 * @param[in]  entity  Entity for which to check for triggered status.
6955 *
6956 * @returns A dds_return_t indicating success or failure.
6957 *
6958 * @retval DDS_RETCODE_OK
6959 *             The operation was successful.
6960 * @retval DDS_RETCODE_BAD_PARAMETER
6961 *             The entity parameter is not a valid parameter.
6962 * @retval DDS_RETCODE_ILLEGAL_OPERATION
6963 *             The operation is invoked on an inappropriate object.
6964 * @retval DDS_RETCODE_ALREADY_DELETED
6965 *             The entity has already been deleted.
6966 */
6967DDS_EXPORT dds_return_t
6968dds_triggered(dds_entity_t entity);
6969
6970/**
6971 * @brief Get the topic
6972 *
6973 * This operation returns a topic (handle) when the function call is done
6974 * with reader, writer, read condition or query condition. For instance, it
6975 * will return the topic when it is used for creating the reader or writer.
6976 * For the conditions, it returns the topic that is used for creating the reader
6977 * which was used to create the condition.
6978 *
6979 * @param[in] entity The entity.
6980 *
6981 * @returns A dds_return_t indicating success or failure.
6982 *
6983 * @retval DDS_RETCODE_OK
6984 *             The operation was successful.
6985 * @retval DDS_RETCODE_BAD_PARAMETER
6986 *             The entity parameter is not a valid parameter.
6987 * @retval DDS_RETCODE_ILLEGAL_OPERATION
6988 *             The operation is invoked on an inappropriate object.
6989 * @retval DDS_RETCODE_ALREADY_DELETED
6990 *             The entity has already been deleted.
6991 */
6992DDS_EXPORT dds_entity_t
6993dds_get_topic(dds_entity_t entity);
6994
6995/**
6996 * @brief Get instance handles of the data readers matching a writer
6997 *
6998 * This operation fills the provided array with the instance handles
6999 * of the data readers that match the writer.  On successful output,
7000 * the number of entries of "rds" set is the minimum of the return
7001 * value and the value of "nrds".
7002 *
7003 * @param[in] writer   The writer.
7004 * @param[in] rds      The array to be filled.
7005 * @param[in] nrds     The size of the rds array, at most the first
7006 *             nrds entries will be filled.  rds = NULL and nrds = 0
7007 *             is a valid way of determining the number of matched
7008 *             readers, but inefficient compared to relying on the
7009 *             matched publication status.
7010 *
7011 * @returns A dds_return_t indicating the number of matched readers
7012 *             or failure.  The return value may be larger than nrds
7013 *             if there are more matching readers than the array can
7014 *             hold.
7015 *
7016 * @retval >=0
7017 *             The number of matching readers.
7018 * @retval DDS_RETCODE_BAD_PARAMETER
7019 *             The entity parameter is not valid or rds = NULL and
7020 *             nrds > 0.
7021 * @retval DDS_RETCODE_ILLEGAL_OPERATION
7022 *             The operation is invoked on an inappropriate object.
7023 */
7024DDS_EXPORT dds_return_t
7025dds_get_matched_subscriptions (
7026  dds_entity_t writer,
7027  dds_instance_handle_t *rds,
7028  size_t nrds);
7029
7030/**
7031 * @brief Get a description of a reader matched with the provided
7032 * writer
7033 *
7034 * This operation looks up the reader instance handle in the set of
7035 * readers matched with the specified writer, returning a freshly
7036 * allocated sample of the DCPSSubscription built-in topic if found,
7037 * and NULL if not.  The caller is responsible for freeing the
7038 * memory allocated, e.g. using dds_builtintopic_free_endpoint.
7039 *
7040 * This operation is similar to performing a read of the given
7041 * instance handle on a reader of the DCPSSubscription built-in
7042 * topic, but this operation additionally filters on whether the
7043 * reader is matched by the provided writer.
7044 *
7045 * @param[in] writer   The writer.
7046 * @param[in] ih       The instance handle of a reader.
7047 *
7048 * @returns A newly allocated sample containing the information on the
7049 *             reader, or a NULL pointer for any kind of failure.
7050 *
7051 * @retval != NULL
7052 *             The requested data
7053 * @retval NULL
7054 *             The writer is not valid or ih is not an instance handle
7055 *             of a matched reader.
7056 */
7057DDS_EXPORT dds_builtintopic_endpoint_t *
7058dds_get_matched_subscription_data (
7059  dds_entity_t writer,
7060  dds_instance_handle_t ih);
7061
7062/**
7063 * @brief Get instance handles of the data writers matching a reader
7064 *
7065 * This operation fills the provided array with the instance handles
7066 * of the data writers that match the reader.  On successful output,
7067 * the number of entries of "wrs" set is the minimum of the return
7068 * value and the value of "nwrs".
7069 *
7070 * @param[in] reader   The reader.
7071 * @param[in] wrs      The array to be filled.
7072 * @param[in] nwrs     The size of the wrs array, at most the first
7073 *             nwrs entries will be filled.  wrs = NULL and wrds = 0
7074 *             is a valid way of determining the number of matched
7075 *             readers, but inefficient compared to relying on the
7076 *             matched publication status.
7077 *
7078 * @returns A dds_return_t indicating the number of matched writers
7079 *             or failure.  The return value may be larger than nwrs
7080 *             if there are more matching writers than the array can
7081 *             hold.
7082 *
7083 * @retval >=0
7084 *             The number of matching writers.
7085 * @retval DDS_RETCODE_BAD_PARAMETER
7086 *             The entity parameter is not valid or wrs = NULL and
7087 *             nwrs > 0.
7088 * @retval DDS_RETCODE_ILLEGAL_OPERATION
7089 *             The operation is invoked on an inappropriate object.
7090 */
7091DDS_EXPORT dds_return_t
7092dds_get_matched_publications (
7093  dds_entity_t reader,
7094  dds_instance_handle_t *wrs,
7095  size_t nwrs);
7096
7097/**
7098 * @brief Get a description of a writer matched with the provided
7099 * reader
7100 *
7101 * This operation looks up the writer instance handle in the set of
7102 * writers matched with the specified reader, returning a freshly
7103 * allocated sample of the DCPSPublication built-in topic if found,
7104 * and NULL if not.  The caller is responsible for freeing the
7105 * memory allocated, e.g. using dds_builtintopic_free_endpoint.
7106 *
7107 * This operation is similar to performing a read of the given
7108 * instance handle on a reader of the DCPSPublication built-in
7109 * topic, but this operation additionally filters on whether the
7110 * writer is matched by the provided reader.
7111 *
7112 * @param[in] reader   The reader.
7113 * @param[in] ih       The instance handle of a writer.
7114 *
7115 * @returns A newly allocated sample containing the information on the
7116 *             writer, or a NULL pointer for any kind of failure.
7117 *
7118 * @retval != NULL
7119 *             The requested data
7120 * @retval NULL
7121 *             The reader is not valid or ih is not an instance handle
7122 *             of a matched writer.
7123 */
7124DDS_EXPORT dds_builtintopic_endpoint_t *
7125dds_get_matched_publication_data (
7126  dds_entity_t reader,
7127  dds_instance_handle_t ih);
7128
7129#ifdef DDS_HAS_TYPE_DISCOVERY
7130/**
7131 * @brief Gets the type identifier from endpoint information that was
7132 * retrieved by dds_get_matched_subscription_data or
7133 * dds_get_matched_publication_data
7134 *
7135 * @param[in] builtintopic_endpoint  The builtintopic endpoint struct
7136 * @param[out] type_identifier       Buffer that will be allocated for the type identifier. Needs to be freed by the caller of this function.
7137 * @param[out] size                  Number of bytes in type_identifier buffer
7138 */
7139DDS_EXPORT dds_return_t
7140dds_builtintopic_get_endpoint_typeid (
7141  dds_builtintopic_endpoint_t * builtintopic_endpoint,
7142  unsigned char **type_identifier,
7143  size_t *size);
7144#endif
7145
7146/**
7147 * @brief Free the endpoint information that was retrieved by
7148 * dds_get_matched_subscription_data or dds_get_matched_publication_data
7149 *
7150 * This operation deallocates the memory of the fields in a
7151 * dds_builtintopic_endpoint_t struct and deallocates the
7152 * struct itself.
7153 *
7154 * @param[in] builtintopic_endpoint  The builtintopic endpoint struct
7155 */
7156DDS_EXPORT void
7157dds_builtintopic_free_endpoint (
7158  dds_builtintopic_endpoint_t * builtintopic_endpoint);
7159
7160/**
7161 * @brief Free the provided participant information
7162 *
7163 * This operation deallocates the memory of the fields in a
7164 * dds_builtintopic_participant_t struct and deallocates the
7165 * struct itself.
7166 *
7167 * @param[in] builtintopic_participant  The builtintopic participant struct
7168 */
7169DDS_EXPORT void
7170dds_builtintopic_free_participant (
7171  dds_builtintopic_participant_t * builtintopic_participant);
7172
7173/**
7174 * @brief This operation manually asserts the liveliness of a writer
7175 * or domain participant.
7176 *
7177 * This operation manually asserts the liveliness of a writer
7178 * or domain participant. This is used in combination with the Liveliness
7179 * QoS policy to indicate that the entity remains active. This operation need
7180 * only be used if the liveliness kind in the QoS is either
7181 * DDS_LIVELINESS_MANUAL_BY_PARTICIPANT or DDS_LIVELINESS_MANUAL_BY_TOPIC.
7182 *
7183 * @param[in] entity  A domain participant or writer
7184 *
7185 * @returns A dds_return_t indicating success or failure.
7186 *
7187 * @retval DDS_RETCODE_OK
7188 *             The operation was successful.
7189 * @retval DDS_RETCODE_ILLEGAL_OPERATION
7190 *             The operation is invoked on an inappropriate object.
7191 */
7192DDS_EXPORT dds_return_t
7193dds_assert_liveliness (
7194  dds_entity_t entity);
7195
7196/**
7197 * @brief This operation allows making the domain's network stack
7198 * temporarily deaf and/or mute. It is a support function for testing and,
7199 * other special uses and is subject to change.
7200 *
7201 * @param[in] entity  A domain entity or an entity bound to a domain, such
7202 *                    as a participant, reader or writer.
7203 * @param[in] deaf    Whether to network stack should pretend to be deaf and
7204 *                    ignore any incoming packets.
7205 * @param[in] mute    Whether to network stack should pretend to be mute and
7206 *                    discard any outgoing packets where it normally would.
7207 *                    pass them to the operating system kernel for transmission.
7208 * @param[in] reset_after  Any value less than INFINITY will cause it to
7209 *                    set deaf = mute = false after reset_after ns have passed.
7210 *                    This is done by an event scheduled for the appropriate
7211 *                    time and otherwise forgotten. These events are not
7212 *                    affected by subsequent calls to this function.
7213 *
7214 * @returns A dds_return_t indicating success or failure.
7215 *
7216 * @retval DDS_RETCODE_OK
7217 *             The operation was successful.
7218 * @retval DDS_BAD_PARAMETER
7219 *             The entity parameter is not a valid parameter.
7220 * @retval DDS_RETCODE_ILLEGAL_OPERATION
7221 *             The operation is invoked on an inappropriate object.
7222*/
7223DDS_EXPORT dds_return_t
7224dds_domain_set_deafmute (
7225  dds_entity_t entity,
7226  bool deaf,
7227  bool mute,
7228  dds_duration_t reset_after);
7229
7230#ifdef DDS_HAS_TYPE_DISCOVERY
7231
7232/**
7233 * @brief This function resolves the type information for the provided
7234 * type identifier.
7235 *
7236 * @param[in]   entity              A domain entity or an entity bound to a domain, such
7237 *                                  as a participant, reader or writer.
7238 * @param[in]   type_identifier     Type identifier data
7239 * @param[in]   type_identifier_sz  Length of the type identifier data
7240 * @param[in]   timeout             Timeout for waiting for requested type information to be available
7241 * @param[out]  sertype             The type information, or NULL if the type could not be resolved
7242 *
7243 * @remark The resulting type from the sertype out parameter is
7244 * refcounted and needs to be dereferenced at some point. This
7245 * can be done by creating a topic using dds_create_topic_generic,
7246 * which takes over the ownership of the type or alternatively by
7247 * using ddsi_sertype_unref to release the reference.
7248 *
7249 * @returns A dds_return_t indicating success or failure.
7250 *
7251 * @retval DDS_RETCODE_OK
7252 *             The operation was successful.
7253 * @retval DDS_BAD_PARAMETER
7254 *             The entity parameter is not a valid parameter, the type_identifier is not provided or
7255 *             its length is incorrect, or the sertype out parameter is NULL
7256 * @retval DDS_RETCODE_NOT_FOUND
7257 *             A type with the provided type_identifier was not found
7258 * @retval DDS_RETCODE_ILLEGAL_OPERATION
7259 *             The operation is invoked on an inappropriate object.
7260*/
7261DDS_EXPORT dds_return_t
7262dds_domain_resolve_type (
7263  dds_entity_t entity,
7264  unsigned char *type_identifier,
7265  size_t type_identifier_sz,
7266  dds_duration_t timeout,
7267  struct ddsi_sertype **sertype);
7268
7269#endif /* DDS_HAS_TYPE_DISCOVERY */
7270
7271#if defined (__cplusplus)
7272}
7273#endif
7274#endif /* DDS_H */
7275
7276#endif /* DDSC_DDS_H */
7277