351 lines
11 KiB
C
351 lines
11 KiB
C
/*
|
|
* Copyright(c) 2006 to 2022 ZettaScale Technology and others
|
|
*
|
|
* This program and the accompanying materials are made available under the
|
|
* terms of the Eclipse Public License v. 2.0 which is available at
|
|
* http://www.eclipse.org/legal/epl-2.0, or the Eclipse Distribution License
|
|
* v. 1.0 which is available at
|
|
* http://www.eclipse.org/org/documents/edl-v10.php.
|
|
*
|
|
* SPDX-License-Identifier: EPL-2.0 OR BSD-3-Clause
|
|
*/
|
|
/* TODO: do we really need to expose all of this as an API? maybe some, but all? */
|
|
|
|
/** @file
|
|
*
|
|
* @brief DDS C Implementation API
|
|
*
|
|
* This header file defines the public API for all kinds of things in the
|
|
* Eclipse Cyclone DDS C language binding.
|
|
*/
|
|
#ifndef DDS_IMPL_H
|
|
#define DDS_IMPL_H
|
|
|
|
#include <stdint.h>
|
|
#include <stdbool.h>
|
|
#include "dds/export.h"
|
|
#include "dds/features.h"
|
|
#include "dds/ddsrt/align.h"
|
|
#include "dds/ddsc/dds_public_alloc.h"
|
|
#include "dds/ddsc/dds_opcodes.h"
|
|
|
|
#if defined (__cplusplus)
|
|
extern "C" {
|
|
#endif
|
|
|
|
/**
|
|
* @defgroup implementation (Public Implementation Details)
|
|
* @ingroup dds
|
|
* Miscellaneous types and functions that are required to be public, since they are
|
|
* in the output of the IDL compiler, but are not intended for direct use.
|
|
*/
|
|
|
|
/**
|
|
* @ingroup implementation
|
|
* @brief Datastructure of a Sequence type
|
|
* Container for a sequence of bytes. The general model of this type is also used in IDL output,
|
|
* where the uint8_t * _buffer is replaced by the appropriate subtype of what is contained.
|
|
*/
|
|
typedef struct dds_sequence
|
|
{
|
|
uint32_t _maximum; /**< Allocated space in _buffer */
|
|
uint32_t _length; /**< Used space in _buffer */
|
|
uint8_t * _buffer; /**< Sequence of bytes */
|
|
bool _release; /**< Whether a CycloneDDS _free method should free the contained buffer.
|
|
if you put in your own allocated _buffer set this to false to avoid
|
|
CycloneDDS calling free() on it. */
|
|
}
|
|
dds_sequence_t;
|
|
|
|
/**
|
|
* @ingroup implementation
|
|
* @brief Key Descriptor
|
|
* Used to describe a named key field in a type with the offset from the start of a struct.
|
|
*/
|
|
typedef struct dds_key_descriptor
|
|
{
|
|
const char * m_name; /**< name of keyfield */
|
|
uint32_t m_offset; /**< offset from pointer */
|
|
uint32_t m_idx; /**< m_idx'th key of type */
|
|
}
|
|
dds_key_descriptor_t;
|
|
|
|
/**
|
|
* @defgroup topic_definition (Topic Definition)
|
|
* @ingroup implementation
|
|
* Topic definitions are output by the IDL compiler and have an
|
|
* implementation-private definition. The only thing exposed on the
|
|
* API is a pointer to the "dds_topic_descriptor_t" struct type.
|
|
*/
|
|
|
|
/**
|
|
* @ingroup topic_definition
|
|
* @brief Simple sized byte container to hold serialized type info
|
|
* Holds XTypes information (TypeInformation, TypeMapping) for a
|
|
* type
|
|
*/
|
|
struct dds_type_meta_ser
|
|
{
|
|
unsigned char * data; /**< data pointer */
|
|
uint32_t sz; /**< data size */
|
|
};
|
|
|
|
/**
|
|
* @anchor DDS_DATA_REPRESENTATION_XCDR1
|
|
* @ingroup topic_definition
|
|
* @brief Data representation XCDR1
|
|
* Type can be represented using XCDR1
|
|
*/
|
|
#define DDS_DATA_REPRESENTATION_XCDR1 0
|
|
|
|
/**
|
|
* @anchor DDS_DATA_REPRESENTATION_XML
|
|
* @ingroup topic_definition
|
|
* @brief Data representation XML
|
|
* Type can be represented using XML
|
|
*/
|
|
#define DDS_DATA_REPRESENTATION_XML 1
|
|
|
|
/**
|
|
* @anchor DDS_DATA_REPRESENTATION_XCDR2
|
|
* @ingroup topic_definition
|
|
* @brief Data representation XCDR2
|
|
* Type can be represented using XCDR2
|
|
*/
|
|
#define DDS_DATA_REPRESENTATION_XCDR2 2
|
|
|
|
|
|
/**
|
|
* @anchor DDS_DATA_REPRESENTATION_FLAG_XCDR1
|
|
* @ingroup topic_definition
|
|
* @brief Data representation XCDR1 flag
|
|
* Type can be represented using XCDR1, preshifted
|
|
*/
|
|
#define DDS_DATA_REPRESENTATION_FLAG_XCDR1 (1u << DDS_DATA_REPRESENTATION_XCDR1)
|
|
|
|
/**
|
|
* @anchor DDS_DATA_REPRESENTATION_FLAG_XML
|
|
* @ingroup topic_definition
|
|
* @brief Data representation XML flag
|
|
* Type can be represented using XML, preshifted
|
|
*/
|
|
#define DDS_DATA_REPRESENTATION_FLAG_XML (1u << DDS_DATA_REPRESENTATION_XML)
|
|
|
|
/**
|
|
* @anchor DDS_DATA_REPRESENTATION_FLAG_XCDR2
|
|
* @ingroup topic_definition
|
|
* @brief Data representation XCDR2 flag
|
|
* Type can be represented using XCDR2, preshifted
|
|
*/
|
|
#define DDS_DATA_REPRESENTATION_FLAG_XCDR2 (1u << DDS_DATA_REPRESENTATION_XCDR2)
|
|
|
|
/**
|
|
* @anchor DDS_DATA_REPRESENTATION_RESTRICT_DEFAULT
|
|
* @ingroup topic_definition
|
|
* @brief Default datarepresentation flag, XCDR1 and XCDR2 flags
|
|
*/
|
|
#define DDS_DATA_REPRESENTATION_RESTRICT_DEFAULT (DDS_DATA_REPRESENTATION_FLAG_XCDR1 | DDS_DATA_REPRESENTATION_FLAG_XCDR2)
|
|
|
|
/**
|
|
* @brief Topic Descriptor
|
|
* @ingroup topic_definition
|
|
* @warning Unstable/Private API
|
|
* Contains all meta information about a type, usually produced by the IDL compiler
|
|
* Since this type is not intended for public consumption it can change without warning.
|
|
*/
|
|
typedef struct dds_topic_descriptor
|
|
{
|
|
const uint32_t m_size; /**< Size of topic type */
|
|
const uint32_t m_align; /**< Alignment of topic type */
|
|
const uint32_t m_flagset; /**< Flags */
|
|
const uint32_t m_nkeys; /**< Number of keys (can be 0) */
|
|
const char * m_typename; /**< Type name */
|
|
const dds_key_descriptor_t * m_keys; /**< Key descriptors (NULL iff m_nkeys 0) */
|
|
const uint32_t m_nops; /**< Number of ops in m_ops */
|
|
const uint32_t * m_ops; /**< Marshalling meta data */
|
|
const char * m_meta; /**< XML topic description meta data */
|
|
struct dds_type_meta_ser type_information; /**< XCDR2 serialized TypeInformation, only present if flag DDS_TOPIC_XTYPES_METADATA is set */
|
|
struct dds_type_meta_ser type_mapping; /**< XCDR2 serialized TypeMapping: maps type-id to type object and minimal to complete type id,
|
|
only present if flag DDS_TOPIC_XTYPES_METADATA is set */
|
|
const uint32_t restrict_data_representation; /**< restrictions on the data representations allowed for the top-level type for this topic,
|
|
only present if flag DDS_TOPIC_RESTRICT_DATA_REPRESENTATION */
|
|
}
|
|
dds_topic_descriptor_t;
|
|
|
|
/**
|
|
* @defgroup reading_masks (Reading Masks)
|
|
* @ingroup conditions
|
|
* Masks for read condition, read, take: there is only one mask here,
|
|
* which combines the sample, view and instance states.
|
|
*/
|
|
|
|
/**
|
|
* @anchor DDS_READ_SAMPLE_STATE
|
|
* @ingroup reading_masks
|
|
* @brief Samples that were already returned once by a read/take operation
|
|
*/
|
|
#define DDS_READ_SAMPLE_STATE 1u
|
|
|
|
/**
|
|
* @anchor DDS_NOT_READ_SAMPLE_STATE
|
|
* @ingroup reading_masks
|
|
* @brief Samples that have not been returned by a read/take operation yet
|
|
*/
|
|
#define DDS_NOT_READ_SAMPLE_STATE 2u
|
|
|
|
/**
|
|
* @anchor DDS_ANY_SAMPLE_STATE
|
|
* @ingroup reading_masks
|
|
* @brief Samples \ref DDS_READ_SAMPLE_STATE or \ref DDS_NOT_READ_SAMPLE_STATE
|
|
*/
|
|
#define DDS_ANY_SAMPLE_STATE (1u | 2u)
|
|
|
|
|
|
/**
|
|
* @anchor DDS_NEW_VIEW_STATE
|
|
* @ingroup reading_masks
|
|
* @brief Samples that belong to a new instance (unique key value)
|
|
*/
|
|
#define DDS_NEW_VIEW_STATE 4u
|
|
|
|
/**
|
|
* @anchor DDS_NOT_NEW_VIEW_STATE
|
|
* @ingroup reading_masks
|
|
* @brief Samples that belong to an existing instance (previously received key value)
|
|
*/
|
|
#define DDS_NOT_NEW_VIEW_STATE 8u
|
|
|
|
/**
|
|
* @anchor DDS_ANY_VIEW_STATE
|
|
* @ingroup reading_masks
|
|
* @brief Samples \ref DDS_NEW_VIEW_STATE or \ref DDS_NOT_NEW_VIEW_STATE
|
|
*/
|
|
#define DDS_ANY_VIEW_STATE (4u | 8u)
|
|
|
|
|
|
/**
|
|
* @anchor DDS_ALIVE_INSTANCE_STATE
|
|
* @ingroup reading_masks
|
|
* @brief Samples that belong to a write
|
|
*/
|
|
#define DDS_ALIVE_INSTANCE_STATE 16u
|
|
|
|
/**
|
|
* @anchor DDS_NOT_ALIVE_DISPOSED_INSTANCE_STATE
|
|
* @ingroup reading_masks
|
|
* @brief Samples that belong to a (write)dispose
|
|
*/
|
|
#define DDS_NOT_ALIVE_DISPOSED_INSTANCE_STATE 32u
|
|
|
|
/**
|
|
* @anchor DDS_NOT_ALIVE_NO_WRITERS_INSTANCE_STATE
|
|
* @ingroup reading_masks
|
|
* @brief Samples that belong a writer that is gone
|
|
*/
|
|
#define DDS_NOT_ALIVE_NO_WRITERS_INSTANCE_STATE 64u
|
|
|
|
/**
|
|
* @anchor DDS_ANY_INSTANCE_STATE
|
|
* @ingroup reading_masks
|
|
* @brief Samples \ref DDS_ALIVE_INSTANCE_STATE, \ref DDS_NOT_ALIVE_DISPOSED_INSTANCE_STATE or \ref DDS_NOT_ALIVE_NO_WRITERS_INSTANCE_STATE
|
|
*/
|
|
#define DDS_ANY_INSTANCE_STATE (16u | 32u | 64u)
|
|
|
|
/**
|
|
* @anchor DDS_ANY_STATE
|
|
* @ingroup reading_masks
|
|
* @brief Any and all samples
|
|
* Equivalen to \ref DDS_ANY_SAMPLE_STATE | \ref DDS_ANY_VIEW_STATE | \ref DDS_ANY_INSTANCE_STATE
|
|
*/
|
|
#define DDS_ANY_STATE (DDS_ANY_SAMPLE_STATE | DDS_ANY_VIEW_STATE | DDS_ANY_INSTANCE_STATE)
|
|
|
|
/**
|
|
* @anchor DDS_DOMAIN_DEFAULT
|
|
* @ingroup domain
|
|
* @brief Select the default domain
|
|
*/
|
|
#define DDS_DOMAIN_DEFAULT ((uint32_t) 0xffffffffu)
|
|
|
|
#ifndef DOXYGEN_SHOULD_SKIP_THIS
|
|
#define DDS_HANDLE_NIL 0
|
|
#define DDS_ENTITY_NIL 0
|
|
#endif
|
|
|
|
/**
|
|
* @brief DDS Entity Kind constants
|
|
* @ingroup internal
|
|
* @warning Unstable/Private API
|
|
* Used throughout the library to indicate what entity is what.
|
|
*/
|
|
typedef enum dds_entity_kind
|
|
{
|
|
DDS_KIND_DONTCARE, /**< Retrieving any entity */
|
|
DDS_KIND_TOPIC, /**< Topic entity */
|
|
DDS_KIND_PARTICIPANT, /**< Domain Participant entity */
|
|
DDS_KIND_READER, /**< Reader entity */
|
|
DDS_KIND_WRITER, /**< Writer entity */
|
|
DDS_KIND_SUBSCRIBER, /**< Subscriber entity */
|
|
DDS_KIND_PUBLISHER, /**< Publisher entity */
|
|
DDS_KIND_COND_READ, /**< ReadCondition entity */
|
|
DDS_KIND_COND_QUERY, /**< QueryCondition entity */
|
|
DDS_KIND_COND_GUARD, /**< GuardCondition entity */
|
|
DDS_KIND_WAITSET, /**< WaitSet entity */
|
|
DDS_KIND_DOMAIN, /**< Domain entity */
|
|
DDS_KIND_CYCLONEDDS /**< CycloneDDS library entity */
|
|
} dds_entity_kind_t;
|
|
/**
|
|
* @anchor DDS_KIND_MAX
|
|
* @ingroup internal
|
|
* @brief Max entity kind, used for loops.
|
|
*/
|
|
#define DDS_KIND_MAX DDS_KIND_CYCLONEDDS
|
|
|
|
/**
|
|
* @ingroup internal
|
|
* @warning Private API
|
|
* @brief Instance handles are uint64_t behind the scenes
|
|
*/
|
|
typedef uint64_t dds_instance_handle_t;
|
|
|
|
/**
|
|
* @ingroup domain
|
|
* @brief Domain IDs are 32 bit unsigned integers.
|
|
*/
|
|
typedef uint32_t dds_domainid_t;
|
|
|
|
/**
|
|
* @ingroup topic
|
|
* @brief Scope for dds_find_topic()
|
|
*/
|
|
typedef enum dds_find_scope
|
|
{
|
|
DDS_FIND_SCOPE_GLOBAL, /**< locate the topic anywhere CycloneDDS knows about */
|
|
DDS_FIND_SCOPE_LOCAL_DOMAIN, /**< locate the topic locally within domain boundaries */
|
|
DDS_FIND_SCOPE_PARTICIPANT /**< locate the topic within the current participant */
|
|
}
|
|
dds_find_scope_t;
|
|
|
|
/**
|
|
* @ingroup builtintopic
|
|
* @brief Type identifier kind for getting endpoint type identifier
|
|
*/
|
|
typedef enum dds_typeid_kind
|
|
{
|
|
DDS_TYPEID_MINIMAL, /**< XTypes Minimal Type ID */
|
|
DDS_TYPEID_COMPLETE /**< XTypes Complete Type ID */
|
|
}
|
|
dds_typeid_kind_t;
|
|
|
|
/**
|
|
* @brief Enable or disable write batching.
|
|
* Overrides default configuration setting for write batching (Internal/WriteBatch).
|
|
*
|
|
* @param[in] enable Enables or disables write batching for all writers.
|
|
*/
|
|
DDS_EXPORT void dds_write_set_batch (bool enable);
|
|
|
|
#if defined (__cplusplus)
|
|
}
|
|
#endif
|
|
#endif
|