2019-01-18 14:10:19 +01:00
/*
* Copyright ( c ) 2006 to 2018 ADLINK Technology Limited 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
*/
# ifndef DDS_H
# define DDS_H
# include <stddef.h>
# include <stdint.h>
/** @file
*
* @ brief Eclipse Cyclone DDS C header
*/
# if defined (__cplusplus)
# define restrict
# endif
# include "dds/export.h"
2020-03-25 10:39:44 +01:00
# include "dds/features.h"
2019-01-18 14:10:19 +01:00
/**
* Handle to an entity . A valid entity handle will always have a positive
2019-05-23 16:51:43 +02:00
* integer value . Should the value be negative , it is one of the DDS_RETCODE_ *
* error codes .
2019-01-18 14:10:19 +01:00
*/
typedef int32_t dds_entity_t ;
/* Sub components */
# include "dds/ddsrt/time.h"
# include "dds/ddsrt/retcode.h"
# include "dds/ddsrt/log.h"
# include "dds/ddsc/dds_public_impl.h"
# include "dds/ddsc/dds_public_alloc.h"
# include "dds/ddsc/dds_public_qos.h"
# include "dds/ddsc/dds_public_error.h"
# include "dds/ddsc/dds_public_status.h"
# include "dds/ddsc/dds_public_listener.h"
# if defined (__cplusplus)
extern " C " {
# endif
2019-09-02 09:08:13 +02:00
struct dds_rhc ;
2020-02-03 10:35:31 +01:00
struct ddsi_plist ;
struct ddsi_sertopic ;
2019-01-18 14:10:19 +01:00
struct ddsi_serdata ;
lift limits on handle allocation and reuse (#95)
The old entity handle mechanism suffered from a number of problems, the
most terrible one being that it would only ever allocate 1000 handles
(not even have at most 1000 in use at the same time). Secondarily, it
was protected by a single mutex that actually does show up as a limiting
factor in, say, a polling-based throughput test with small messages.
Thirdly, it tried to provide for various use cases that don't exist in
practice but add complexity and overhead.
This commit totally rewrites the mechanism, by replacing the old array
with a hash table and allowing a near-arbitrary number of handles as
well as reuse of handles. It also removes the entity "kind" bits in the
most significant bits of the handles, because they only resulted in
incorrect checking of argument validity. All that is taken out, but
there is still more cleaning up to be done. It furthermore removes an
indirection in the handle-to-entity lookup by embedding the
"dds_handle_link" structure in the entity.
Handle allocation is randomized to avoid the have a high probability of
quickly finding an available handle (the total number of handles is
limited to a number much smaller than the domain from which they are
allocated). The likelihood of handle reuse is still dependent on the
number of allocated handles -- the fewer handles there are, the longer
the expected time to reuse. Non-randomized handles would give a few
guarantees more, though.
It moreover moves the code from the "util" to the "core/ddsc" component,
because it really is only used for entities, and besides the new
implementation relies on the deferred freeing (a.k.a. garbage collection
mechanism) implemented in the core.
The actual handle management has two variants, selectable with a macro:
the preferred embodiment uses a concurrent hash table, the actually used
one performs all operations inside a single mutex and uses a
non-concurrent version of the hash table. The reason the
less-predeferred embodiment is used is that the concurrent version
requires the freeing of entity objects to be deferred (much like the
GUID-to-entity hash tables in DDSI function, or indeed the key value to
instance handle mapping). That is a fair bit of work, and the
non-concurrent version is a reasonable intermediate step.
Signed-off-by: Erik Boasson <eb@ilities.com>
2019-02-19 10:57:21 +01:00
# define DDS_MIN_PSEUDO_HANDLE ((dds_entity_t) 0x7fff0000)
2019-01-18 14:10:19 +01:00
/* @defgroup builtintopic_constants Convenience constants for referring to builtin topics
*
* These constants can be used in place of an actual dds_topic_t , when creating
* readers or writers for builtin - topics .
*
* @ {
*/
lift limits on handle allocation and reuse (#95)
The old entity handle mechanism suffered from a number of problems, the
most terrible one being that it would only ever allocate 1000 handles
(not even have at most 1000 in use at the same time). Secondarily, it
was protected by a single mutex that actually does show up as a limiting
factor in, say, a polling-based throughput test with small messages.
Thirdly, it tried to provide for various use cases that don't exist in
practice but add complexity and overhead.
This commit totally rewrites the mechanism, by replacing the old array
with a hash table and allowing a near-arbitrary number of handles as
well as reuse of handles. It also removes the entity "kind" bits in the
most significant bits of the handles, because they only resulted in
incorrect checking of argument validity. All that is taken out, but
there is still more cleaning up to be done. It furthermore removes an
indirection in the handle-to-entity lookup by embedding the
"dds_handle_link" structure in the entity.
Handle allocation is randomized to avoid the have a high probability of
quickly finding an available handle (the total number of handles is
limited to a number much smaller than the domain from which they are
allocated). The likelihood of handle reuse is still dependent on the
number of allocated handles -- the fewer handles there are, the longer
the expected time to reuse. Non-randomized handles would give a few
guarantees more, though.
It moreover moves the code from the "util" to the "core/ddsc" component,
because it really is only used for entities, and besides the new
implementation relies on the deferred freeing (a.k.a. garbage collection
mechanism) implemented in the core.
The actual handle management has two variants, selectable with a macro:
the preferred embodiment uses a concurrent hash table, the actually used
one performs all operations inside a single mutex and uses a
non-concurrent version of the hash table. The reason the
less-predeferred embodiment is used is that the concurrent version
requires the freeing of entity objects to be deferred (much like the
GUID-to-entity hash tables in DDSI function, or indeed the key value to
instance handle mapping). That is a fair bit of work, and the
non-concurrent version is a reasonable intermediate step.
Signed-off-by: Erik Boasson <eb@ilities.com>
2019-02-19 10:57:21 +01:00
# define DDS_BUILTIN_TOPIC_DCPSPARTICIPANT ((dds_entity_t) (DDS_MIN_PSEUDO_HANDLE + 1))
# define DDS_BUILTIN_TOPIC_DCPSTOPIC ((dds_entity_t) (DDS_MIN_PSEUDO_HANDLE + 2))
# define DDS_BUILTIN_TOPIC_DCPSPUBLICATION ((dds_entity_t) (DDS_MIN_PSEUDO_HANDLE + 3))
# define DDS_BUILTIN_TOPIC_DCPSSUBSCRIPTION ((dds_entity_t) (DDS_MIN_PSEUDO_HANDLE + 4))
2019-01-18 14:10:19 +01:00
/** @}*/
2019-08-28 14:15:28 +02:00
/** Special handle representing the entity corresponding to the CycloneDDS library itself */
# define DDS_CYCLONEDDS_HANDLE ((dds_entity_t) (DDS_MIN_PSEUDO_HANDLE + 256))
2019-01-18 14:10:19 +01:00
/** @name Communication Status definitions
@ { * */
typedef enum dds_status_id {
DDS_INCONSISTENT_TOPIC_STATUS_ID ,
DDS_OFFERED_DEADLINE_MISSED_STATUS_ID ,
DDS_REQUESTED_DEADLINE_MISSED_STATUS_ID ,
DDS_OFFERED_INCOMPATIBLE_QOS_STATUS_ID ,
DDS_REQUESTED_INCOMPATIBLE_QOS_STATUS_ID ,
DDS_SAMPLE_LOST_STATUS_ID ,
DDS_SAMPLE_REJECTED_STATUS_ID ,
DDS_DATA_ON_READERS_STATUS_ID ,
DDS_DATA_AVAILABLE_STATUS_ID ,
DDS_LIVELINESS_LOST_STATUS_ID ,
DDS_LIVELINESS_CHANGED_STATUS_ID ,
DDS_PUBLICATION_MATCHED_STATUS_ID ,
DDS_SUBSCRIPTION_MATCHED_STATUS_ID
Address locking order for entity locks
There were inconsistencies in the order in which entity locks were taken
when multiple entities needed to be locked at the same time. In most
cases, the order was first locking entity X, then locking the parent
entity of X. However, in some cases the order was reversed, a likely
cause of deadlocks.
This commit sorts these problems, and in particular propagating
operations into children. The entity refcount is now part of the handle
administration so that it is no longer necessary to lock an entity to
determine whether it is still allowed to be used (previously it had to
check the CLOSED flag afterward). This allows recursing into the
children while holding handles and the underlying objects alive, but
without violating lock order.
Attendant changes that would warrant there own commits but are too hard
to split off:
* Children are now no longer in a singly linked list, but in an AVL
tree; this was necessary at some intermediate stage to allow unlocking
an entity and restarting iteration over all children at the "next"
child (all thanks to the eternally unique instance handle);
* Waitsets shifted to using arrays of attached entities instead of
linked lists; this was a consequence of dealing with some locking
issues in reading triggers and considering which operations on the
"triggered" and "observed" sets are actually needed.
* Entity status flags and waitset/condition trigger counts are now
handled using atomic operations. Entities are now classified as
having a "status" with a corresponding mask, or as having a "trigger
count" (conditions). As there are fewer than 16 status bits, the
status and its mask can squeeze into the same 32-bits as the trigger
count. These atomic updates avoid the need for a separate lock just
for the trigger/status values and results in a significant speedup
with waitsets.
* Create topic now has a more rational behaviour when multiple
participants attempt to create the same topic: each participant now
gets its own topic definition, but the underlying type representation
is shared.
Signed-off-by: Erik Boasson <eb@ilities.com>
2019-06-21 07:13:57 +02:00
} dds_status_id_t ;
/** Another topic exists with the same name but with different characteristics. */
2019-01-18 14:10:19 +01:00
# define DDS_INCONSISTENT_TOPIC_STATUS (1u << DDS_INCONSISTENT_TOPIC_STATUS_ID)
/** The deadline that the writer has committed through its deadline QoS policy was not respected for a specific instance. */
# define DDS_OFFERED_DEADLINE_MISSED_STATUS (1u << DDS_OFFERED_DEADLINE_MISSED_STATUS_ID)
/** The deadline that the reader was expecting through its deadline QoS policy was not respected for a specific instance. */
# define DDS_REQUESTED_DEADLINE_MISSED_STATUS (1u << DDS_REQUESTED_DEADLINE_MISSED_STATUS_ID)
/** A QoS policy setting was incompatible with what was requested. */
# define DDS_OFFERED_INCOMPATIBLE_QOS_STATUS (1u << DDS_OFFERED_INCOMPATIBLE_QOS_STATUS_ID)
/** A QoS policy setting was incompatible with what is offered. */
# define DDS_REQUESTED_INCOMPATIBLE_QOS_STATUS (1u << DDS_REQUESTED_INCOMPATIBLE_QOS_STATUS_ID)
/** A sample has been lost (never received). */
# define DDS_SAMPLE_LOST_STATUS (1u << DDS_SAMPLE_LOST_STATUS_ID)
/** A (received) sample has been rejected. */
# define DDS_SAMPLE_REJECTED_STATUS (1u << DDS_SAMPLE_REJECTED_STATUS_ID)
/** New information is available. */
# define DDS_DATA_ON_READERS_STATUS (1u << DDS_DATA_ON_READERS_STATUS_ID)
/** New information is available. */
# define DDS_DATA_AVAILABLE_STATUS (1u << DDS_DATA_AVAILABLE_STATUS_ID)
/** 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". */
# define DDS_LIVELINESS_LOST_STATUS (1u << DDS_LIVELINESS_LOST_STATUS_ID)
/** 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". */
# define DDS_LIVELINESS_CHANGED_STATUS (1u << DDS_LIVELINESS_CHANGED_STATUS_ID)
/** The writer has found a reader that matches the topic and has a compatible QoS. */
# define DDS_PUBLICATION_MATCHED_STATUS (1u << DDS_PUBLICATION_MATCHED_STATUS_ID)
/** The reader has found a writer that matches the topic and has a compatible QoS. */
# define DDS_SUBSCRIPTION_MATCHED_STATUS (1u << DDS_SUBSCRIPTION_MATCHED_STATUS_ID)
/** @}*/
/** Read state for a data value */
typedef enum dds_sample_state
{
DDS_SST_READ = DDS_READ_SAMPLE_STATE , /**<DataReader has already accessed the sample by read */
DDS_SST_NOT_READ = DDS_NOT_READ_SAMPLE_STATE /**<DataReader has not accessed the sample before */
}
dds_sample_state_t ;
/** View state of an instance relative to the samples */
typedef enum dds_view_state
{
/** DataReader is accessing the sample for the first time when the instance is alive */
DDS_VST_NEW = DDS_NEW_VIEW_STATE ,
/** DataReader accessed the sample before */
DDS_VST_OLD = DDS_NOT_NEW_VIEW_STATE
}
dds_view_state_t ;
/** Defines the state of the instance */
typedef enum dds_instance_state
{
/** Samples received for the instance from the live data writers */
DDS_IST_ALIVE = DDS_ALIVE_INSTANCE_STATE ,
/** Instance was explicitly disposed by the data writer */
DDS_IST_NOT_ALIVE_DISPOSED = DDS_NOT_ALIVE_DISPOSED_INSTANCE_STATE ,
/** Instance has been declared as not alive by data reader as there are no live data writers writing that instance */
DDS_IST_NOT_ALIVE_NO_WRITERS = DDS_NOT_ALIVE_NO_WRITERS_INSTANCE_STATE
}
dds_instance_state_t ;
/** Contains information about the associated data value */
typedef struct dds_sample_info
{
/** Sample state */
dds_sample_state_t sample_state ;
/** View state */
dds_view_state_t view_state ;
/** Instance state */
dds_instance_state_t instance_state ;
/** Indicates whether there is a data associated with a sample
* - true , indicates the data is valid
* - false , indicates the data is invalid , no data to read */
bool valid_data ;
/** timestamp of a data instance when it is written */
dds_time_t source_timestamp ;
/** handle to the data instance */
dds_instance_handle_t instance_handle ;
/** handle to the publisher */
dds_instance_handle_t publication_handle ;
/** count of instance state change from NOT_ALIVE_DISPOSED to ALIVE */
uint32_t disposed_generation_count ;
/** count of instance state change from NOT_ALIVE_NO_WRITERS to ALIVE */
uint32_t no_writers_generation_count ;
/** indicates the number of samples of the same instance that follow the current one in the collection */
uint32_t sample_rank ;
/** difference in generations between the sample and most recent sample of the same instance that appears in the returned collection */
uint32_t generation_rank ;
/** difference in generations between the sample and most recent sample of the same instance when read/take was called */
uint32_t absolute_generation_rank ;
}
dds_sample_info_t ;
typedef struct dds_builtintopic_guid
{
uint8_t v [ 16 ] ;
}
dds_builtintopic_guid_t ;
2020-04-09 13:48:01 +02:00
/* "dds_builtintopic_guid_t" is a bit of a weird name for what everyone just calls a GUID,
so let us try and switch to using the more logical one */
typedef struct dds_builtintopic_guid dds_guid_t ;
2019-01-18 14:10:19 +01:00
typedef struct dds_builtintopic_participant
{
2020-04-09 13:48:01 +02:00
dds_guid_t key ;
2019-01-18 14:10:19 +01:00
dds_qos_t * qos ;
}
dds_builtintopic_participant_t ;
typedef struct dds_builtintopic_endpoint
{
2020-04-09 13:48:01 +02:00
dds_guid_t key ;
dds_guid_t participant_key ;
2019-04-15 11:21:52 +02:00
dds_instance_handle_t participant_instance_handle ;
2019-01-18 14:10:19 +01:00
char * topic_name ;
char * type_name ;
dds_qos_t * qos ;
}
dds_builtintopic_endpoint_t ;
/*
All entities are represented by a process - private handle , with one
call to enable an entity when it was created disabled .
An entity is created enabled by default .
Note : disabled creation is currently not supported .
*/
/**
* @ brief Enable entity .
*
* @ note Delayed entity enabling is not supported yet ( CHAM - 96 ) .
*
* This operation enables the dds_entity_t . Created dds_entity_t objects can start in
* either an enabled or disabled state . This is controlled by the value of the
* entityfactory policy on the corresponding parent entity for the given
* entity . Enabled entities are immediately activated at creation time meaning
* all their immutable QoS settings can no longer be changed . Disabled Entities are not
* yet activated , so it is still possible to change their immutable QoS settings . However ,
* once activated the immutable QoS settings can no longer be changed .
* Creating disabled entities can make sense when the creator of the DDS_Entity
* does not yet know which QoS settings to apply , thus allowing another piece of code
* to set the QoS later on .
*
* The default setting of DDS_EntityFactoryQosPolicy is such that , by default ,
* entities are created in an enabled state so that it is not necessary to explicitly call
* dds_enable on newly - created entities .
*
* The dds_enable operation produces the same results no matter how
* many times it is performed . Calling dds_enable on an already
* enabled DDS_Entity returns DDS_RETCODE_OK and has no effect .
*
* If an Entity has not yet been enabled , the only operations that can be invoked
* on it are : the ones to set , get or copy the QosPolicy settings , the ones that set
* ( or get ) the Listener , the ones that get the Status and the dds_get_status_changes
* operation ( although the status of a disabled entity never changes ) . Other operations
* will return the error DDS_RETCODE_NOT_ENABLED .
*
* Entities created with a parent that is disabled , are created disabled regardless of
* the setting of the entityfactory policy .
*
* If the entityfactory policy has autoenable_created_entities
* set to TRUE , the dds_enable operation on the parent will
* automatically enable all child entities created with the parent .
*
* The Listeners associated with an Entity are not called until the
* Entity is enabled . Conditions associated with an Entity that
* is not enabled are " inactive " , that is , have a trigger_value which is FALSE .
*
* @ param [ in ] entity The entity to enable .
*
* @ returns A dds_return_t indicating success or failure .
*
* @ retval DDS_RETCODE_OK
* The listeners of to the entity have been successfully been copied
* into the specified listener parameter .
* @ retval DDS_RETCODE_ERROR
* An internal error has occurred .
* @ retval DDS_RETCODE_ILLEGAL_OPERATION
* The operation is invoked on an inappropriate object .
* @ retval DDS_RETCODE_ALREADY_DELETED
* The entity has already been deleted .
* @ retval DDS_RETCODE_PRECONDITION_NOT_MET
* The parent of the given Entity is not enabled .
*/
DDS_EXPORT dds_return_t
dds_enable ( dds_entity_t entity ) ;
/*
All entities are represented by a process - private handle , with one
call to delete an entity and all entities it logically contains .
That is , it is equivalent to combination of
delete_contained_entities and delete_xxx in the DCPS API .
*/
/**
* @ brief Delete given entity .
*
* This operation will delete the given entity . It will also automatically
* delete all its children , childrens ' children , etc entities .
*
* @ param [ in ] entity Entity to delete .
*
* @ returns A dds_return_t indicating success or failure .
*
* @ retval DDS_RETCODE_OK
* The entity and its children ( recursive are deleted ) .
* @ retval DDS_RETCODE_ERROR
* An internal error has occurred .
* @ retval DDS_RETCODE_ILLEGAL_OPERATION
* The operation is invoked on an inappropriate object .
* @ retval DDS_RETCODE_ALREADY_DELETED
* The entity has already been deleted .
*/
/* TODO: Link to generic dds entity relations documentation. */
DDS_EXPORT dds_return_t
dds_delete ( dds_entity_t entity ) ;
/**
* @ brief Get entity publisher .
*
* This operation returns the publisher to which the given entity belongs .
* For instance , it will return the Publisher that was used when
* creating a DataWriter ( when that DataWriter was provided here ) .
*
2019-05-23 20:40:51 +02:00
* @ param [ in ] writer Entity from which to get its publisher .
2019-01-18 14:10:19 +01:00
*
* @ returns A valid entity or an error code .
*
* @ retval > 0
* A valid publisher handle .
* @ retval DDS_RETCODE_ERROR
* An internal error has occurred .
* @ retval DDS_RETCODE_ILLEGAL_OPERATION
* The operation is invoked on an inappropriate object .
* @ retval DDS_RETCODE_ALREADY_DELETED
* The entity has already been deleted .
*/
/* TODO: Link to generic dds entity relations documentation. */
DDS_EXPORT dds_entity_t
dds_get_publisher ( dds_entity_t writer ) ;
/**
* @ brief Get entity subscriber .
*
* This operation returns the subscriber to which the given entity belongs .
* For instance , it will return the Subscriber that was used when
* creating a DataReader ( when that DataReader was provided here ) .
*
* @ param [ in ] entity Entity from which to get its subscriber .
*
* @ returns A valid subscriber handle or an error code .
*
* @ retval > 0
* A valid subscriber handle .
* @ retval DDS_RETCODE_ERROR
* An internal error has occurred .
* @ retval DDS_RETCODE_ILLEGAL_OPERATION
* The operation is invoked on an inappropriate object .
* @ retval DDS_RETCODE_ALREADY_DELETED
* The entity has already been deleted .
*/
/* TODO: Link to generic dds entity relations documentation. */
DDS_EXPORT dds_entity_t
dds_get_subscriber ( dds_entity_t entity ) ;
/**
* @ brief Get entity datareader .
*
* This operation returns the datareader to which the given entity belongs .
* For instance , it will return the DataReader that was used when
* creating a ReadCondition ( when that ReadCondition was provided here ) .
*
2019-05-23 20:40:51 +02:00
* @ param [ in ] condition Entity from which to get its datareader .
2019-01-18 14:10:19 +01:00
*
* @ returns A valid reader handle or an error code .
*
* @ retval > 0
* A valid reader handle .
* @ retval DDS_RETCODE_ERROR
* An internal error has occurred .
* @ retval DDS_RETCODE_ILLEGAL_OPERATION
* The operation is invoked on an inappropriate object .
* @ retval DDS_RETCODE_ALREADY_DELETED
* The entity has already been deleted .
*/
/* TODO: Link to generic dds entity relations documentation. */
DDS_EXPORT dds_entity_t
dds_get_datareader ( dds_entity_t condition ) ;
/**
* @ brief Get the mask of a condition .
*
* This operation returns the mask that was used to create the given
* condition .
*
* @ param [ in ] condition Read or Query condition that has a mask .
*
* @ returns A dds_return_t indicating success or failure .
*
* @ retval DDS_RETCODE_OK
* Success ( given mask is set ) .
* @ retval DDS_RETCODE_ERROR
* An internal error has occurred .
* @ retval DDS_RETCODE_BAD_PARAMETER
* The mask arg is NULL .
* @ retval DDS_RETCODE_ILLEGAL_OPERATION
* The operation is invoked on an inappropriate object .
* @ retval DDS_RETCODE_ALREADY_DELETED
* The entity has already been deleted .
*/
DDS_EXPORT dds_return_t
dds_get_mask ( dds_entity_t condition , uint32_t * mask ) ;
/**
* @ brief Returns the instance handle that represents the entity .
*
* @ param [ in ] entity Entity of which to get the instance handle .
* @ param [ out ] ihdl Pointer to dds_instance_handle_t .
*
* @ returns A dds_return_t indicating success or failure .
*
* @ retval DDS_RETCODE_OK
* Success .
* @ retval DDS_RETCODE_ERROR
* An internal error has occurred .
*/
/* TODO: Check list of return codes is complete. */
DDS_EXPORT dds_return_t
dds_get_instance_handle ( dds_entity_t entity , dds_instance_handle_t * ihdl ) ;
2020-04-09 13:49:10 +02:00
/**
* @ brief Returns the GUID that represents the entity in the network ,
* and therefore only supports participants , readers and writers .
*
* @ param [ in ] entity Entity of which to get the instance handle .
* @ param [ out ] guid Where to store the GUID .
*
* @ returns A dds_return_t indicating success or failure .
*
* @ retval DDS_RETCODE_OK
* Success .
* @ retval DDS_RETCODE_ILLEGAL_OPERATION
* The operation is invoked on an inappropriate object .
* @ retval DDS_RETCODE_ERROR
* An internal error has occurred .
*/
/* TODO: Check list of return codes is complete. */
DDS_EXPORT dds_return_t
dds_get_guid ( dds_entity_t entity , dds_guid_t * guid ) ;
2019-01-18 14:10:19 +01:00
/*
All entities have a set of " status conditions " ( following the DCPS
spec ) , read peeks , take reads & resets ( analogously to read & take
operations on reader ) . The " mask " allows operating only on a subset
of the statuses . Enabled status analogously to DCPS spec .
*/
/**
* @ brief Read the status set for the entity
*
* This operation reads the status ( es ) set for the entity based on
* the enabled status and mask set . It does not clear the read status ( es ) .
*
* @ param [ in ] entity Entity on which the status has to be read .
* @ param [ out ] status Returns the status set on the entity , based on the enabled status .
* @ param [ in ] mask Filter the status condition to be read ( can be NULL ) .
*
* @ returns A dds_return_t indicating success or failure .
*
* @ retval DDS_RETCODE_OK
* Success .
* @ retval DDS_RETCODE_BAD_PARAMETER
* The entity parameter is not a valid parameter .
* @ retval DDS_RETCODE_ILLEGAL_OPERATION
* The operation is invoked on an inappropriate object .
* @ retval DDS_RETCODE_ALREADY_DELETED
* The entity has already been deleted .
*/
DDS_EXPORT dds_return_t
dds_read_status ( dds_entity_t entity , uint32_t * status , uint32_t mask ) ;
/**
* @ brief Read the status set for the entity
*
* This operation reads the status ( es ) set for the entity based on the enabled
* status and mask set . It clears the status set after reading .
*
* @ param [ in ] entity Entity on which the status has to be read .
* @ param [ out ] status Returns the status set on the entity , based on the enabled status .
* @ param [ in ] mask Filter the status condition to be read ( can be NULL ) .
*
* @ returns A dds_return_t indicating success or failure .
*
* @ retval DDS_RETCODE_OK
* Success .
* @ retval DDS_RETCODE_BAD_PARAMETER
* The entity parameter is not a valid parameter .
* @ retval DDS_RETCODE_ILLEGAL_OPERATION
* The operation is invoked on an inappropriate object .
* @ retval DDS_RETCODE_ALREADY_DELETED
* The entity has already been deleted .
*/
DDS_EXPORT dds_return_t
dds_take_status ( dds_entity_t entity , uint32_t * status , uint32_t mask ) ;
/**
* @ brief Get changed status ( es )
*
* This operation returns the status changes since they were last read .
*
* @ param [ in ] entity Entity on which the statuses are read .
* @ param [ out ] status Returns the current set of triggered statuses .
*
* @ returns A dds_return_t indicating success or failure .
*
* @ retval DDS_RETCODE_OK
* Success .
* @ retval DDS_RETCODE_BAD_PARAMETER
* The entity parameter is not a valid parameter .
* @ retval DDS_RETCODE_ILLEGAL_OPERATION
* The operation is invoked on an inappropriate object .
* @ retval DDS_RETCODE_ALREADY_DELETED
* The entity has already been deleted .
*/
DDS_EXPORT dds_return_t
dds_get_status_changes ( dds_entity_t entity , uint32_t * status ) ;
/**
* @ brief Get enabled status on entity
*
* This operation returns the status enabled on the entity
*
* @ param [ in ] entity Entity to get the status .
2019-05-23 20:40:51 +02:00
* @ param [ out ] mask Mask of enabled statuses set on the entity .
2019-01-18 14:10:19 +01:00
*
* @ returns A dds_return_t indicating success or failure .
*
* @ retval DDS_RETCODE_OK
* Success .
* @ retval DDS_RETCODE_BAD_PARAMETER
* The entity parameter is not a valid parameter .
* @ retval DDS_RETCODE_ILLEGAL_OPERATION
* The operation is invoked on an inappropriate object .
* @ retval DDS_RETCODE_ALREADY_DELETED
* The entity has already been deleted .
*/
DDS_EXPORT dds_return_t
dds_get_status_mask ( dds_entity_t entity , uint32_t * mask ) ;
DDS_DEPRECATED_EXPORT dds_return_t
dds_get_enabled_status ( dds_entity_t entity , uint32_t * mask ) ;
/**
* @ brief Set status enabled on entity
*
* This operation enables the status ( es ) based on the mask set
*
* @ param [ in ] entity Entity to enable the status .
* @ param [ in ] mask Status value that indicates the status to be enabled .
*
* @ returns A dds_return_t indicating success or failure .
*
* @ retval DDS_RETCODE_OK
* Success .
* @ retval DDS_RETCODE_BAD_PARAMETER
* The entity parameter is not a valid parameter .
* @ retval DDS_RETCODE_ILLEGAL_OPERATION
* The operation is invoked on an inappropriate object .
* @ retval DDS_RETCODE_ALREADY_DELETED
* The entity has already been deleted .
*/
DDS_EXPORT dds_return_t
dds_set_status_mask ( dds_entity_t entity , uint32_t mask ) ;
DDS_DEPRECATED_EXPORT dds_return_t
dds_set_enabled_status ( dds_entity_t entity , uint32_t mask ) ;
/*
Almost all entities have get / set qos operations defined on them ,
again following the DCPS spec . But unlike the DCPS spec , the
" present " field in qos_t allows one to initialize just the one QoS
one wants to set & pass it to set_qos .
*/
/**
* @ brief Get entity QoS policies .
*
* This operation allows access to the existing set of QoS policies
* for the entity .
*
* @ param [ in ] entity Entity on which to get qos .
* @ param [ out ] qos Pointer to the qos structure that returns the set policies .
*
2020-01-28 21:29:14 +01:00
* @ returns A dds_return_t indicating success or failure . The QoS object will have
* at least all QoS relevant for the entity present and the corresponding dds_qget_ . . .
* will return true .
2019-01-18 14:10:19 +01:00
*
* @ retval DDS_RETCODE_OK
* The existing set of QoS policy values applied to the entity
* has successfully been copied into the specified qos parameter .
* @ retval DDS_RETCODE_ERROR
* An internal error has occurred .
* @ retval DDS_RETCODE_BAD_PARAMETER
* The qos parameter is NULL .
* @ retval DDS_RETCODE_ILLEGAL_OPERATION
* The operation is invoked on an inappropriate object .
* @ retval DDS_RETCODE_ALREADY_DELETED
* The entity has already been deleted .
*/
/* TODO: Link to generic QoS information documentation. */
DDS_EXPORT dds_return_t
dds_get_qos ( dds_entity_t entity , dds_qos_t * qos ) ;
/**
* @ brief Set entity QoS policies .
*
* This operation replaces the existing set of Qos Policy settings for an
* entity . The parameter qos must contain the struct with the QosPolicy
* settings which is checked for self - consistency .
*
* The set of QosPolicy settings specified by the qos parameter are applied on
* top of the existing QoS , replacing the values of any policies previously set
* ( provided , the operation returned DDS_RETCODE_OK ) .
*
* Not all policies are changeable when the entity is enabled .
*
* @ note Currently only Latency Budget and Ownership Strength are changeable QoS
* that can be set .
*
* @ param [ in ] entity Entity from which to get qos .
* @ param [ in ] qos Pointer to the qos structure that provides the policies .
*
* @ returns A dds_return_t indicating success or failure .
*
* @ retval DDS_RETCODE_OK
* The new QoS policies are set .
* @ retval DDS_RETCODE_ERROR
* An internal error has occurred .
* @ retval DDS_RETCODE_BAD_PARAMETER
* The qos parameter is NULL .
* @ retval DDS_RETCODE_ILLEGAL_OPERATION
* The operation is invoked on an inappropriate object .
* @ retval DDS_RETCODE_ALREADY_DELETED
* The entity has already been deleted .
* @ retval DDS_RETCODE_IMMUTABLE_POLICY
* The entity is enabled and one or more of the policies of the QoS
* are immutable .
* @ retval DDS_RETCODE_INCONSISTENT_POLICY
* A few policies within the QoS are not consistent with each other .
*/
/* TODO: Link to generic QoS information documentation. */
DDS_EXPORT dds_return_t
dds_set_qos ( dds_entity_t entity , const dds_qos_t * qos ) ;
/*
Get or set listener associated with an entity , type of listener
provided much match type of entity .
*/
/**
* @ brief Get entity listeners .
*
* This operation allows access to the existing listeners attached to
* the entity .
*
* @ param [ in ] entity Entity on which to get the listeners .
* @ param [ out ] listener Pointer to the listener structure that returns the
* set of listener callbacks .
*
* @ returns A dds_return_t indicating success or failure .
*
* @ retval DDS_RETCODE_OK
* The listeners of to the entity have been successfully been
* copied into the specified listener parameter .
* @ retval DDS_RETCODE_ERROR
* An internal error has occurred .
* @ retval DDS_RETCODE_BAD_PARAMETER
* The listener parameter is NULL .
* @ retval DDS_RETCODE_ILLEGAL_OPERATION
* The operation is invoked on an inappropriate object .
* @ retval DDS_RETCODE_ALREADY_DELETED
* The entity has already been deleted .
*/
/* TODO: Link to (generic) Listener and status information. */
DDS_EXPORT dds_return_t
dds_get_listener ( dds_entity_t entity , dds_listener_t * listener ) ;
/**
* @ brief Set entity listeners .
*
* This operation attaches a dds_listener_t to the dds_entity_t . Only one
* Listener can be attached to each Entity . If a Listener was already
* attached , this operation will replace it with the new one . In other
* words , all related callbacks are replaced ( possibly with NULL ) .
*
* When listener parameter is NULL , all listener callbacks that were possibly
* set on the Entity will be removed .
*
* @ note Not all listener callbacks are related to all entities .
*
* < b > < i > Communication Status < / i > < / b > < br >
* For each communication status , the StatusChangedFlag flag is initially set to
* FALSE . It becomes TRUE whenever that plain communication status changes . For
* each plain communication status activated in the mask , the associated
* Listener callback is invoked and the communication status is reset
* to FALSE , as the listener implicitly accesses the status which is passed as a
* parameter to that operation .
* The status is reset prior to calling the listener , so if the application calls
* the get_ < status_name > from inside the listener it will see the
* status already reset .
*
* < b > < i > Status Propagation < / i > < / b > < br >
* In case a related callback within the Listener is not set , the Listener of
* the Parent entity is called recursively , until a Listener with the appropriate
* callback set has been found and called . This allows the application to set
* ( for instance ) a default behaviour in the Listener of the containing Publisher
* and a DataWriter specific behaviour when needed . In case the callback is not
* set in the Publishers ' Listener either , the communication status will be
* propagated to the Listener of the DomainParticipant of the containing
* DomainParticipant . In case the callback is not set in the DomainParticipants '
* Listener either , the Communication Status flag will be set , resulting in a
* possible WaitSet trigger .
*
* @ param [ in ] entity Entity on which to get the listeners .
* @ param [ in ] listener Pointer to the listener structure that contains the
* set of listener callbacks ( maybe NULL ) .
*
* @ returns A dds_return_t indicating success or failure .
*
* @ retval DDS_RETCODE_OK
* The listeners of to the entity have been successfully been
* copied into the specified listener parameter .
* @ retval DDS_RETCODE_ERROR
* An internal error has occurred .
* @ retval DDS_RETCODE_ILLEGAL_OPERATION
* The operation is invoked on an inappropriate object .
* @ retval DDS_RETCODE_ALREADY_DELETED
* The entity has already been deleted .
*/
/* TODO: Link to (generic) Listener and status information. */
DDS_EXPORT dds_return_t
dds_set_listener ( dds_entity_t entity , const dds_listener_t * listener ) ;
/*
Creation functions for various entities . Creating a subscriber or
publisher is optional : if one creates a reader as a descendant of a
participant , it is as if a subscriber is created specially for
that reader .
QoS default values are those of the DDS specification , but the
inheritance rules are different :
* publishers and subscribers inherit from the participant QoS
* readers and writers always inherit from the topic QoS
* the QoS ' s present in the " qos " parameter override the inherited values
*/
/**
* @ brief Creates a new instance of a DDS participant in a domain
*
* If domain is set ( not DDS_DOMAIN_DEFAULT ) then it must match if the domain has also
* been configured or an error status will be returned .
* Currently only a single domain can be configured by providing configuration file .
* If no configuration file exists , the default domain is configured as 0.
*
*
2019-09-13 11:45:14 +02:00
* @ 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 .
2019-01-18 14:10:19 +01:00
* @ param [ in ] qos The QoS to set on the new participant ( can be NULL ) .
* @ param [ in ] listener Any listener functions associated with the new participant ( can be NULL ) .
* @ returns A valid participant handle or an error code .
*
* @ retval > 0
* A valid participant handle .
2020-03-25 14:48:35 +01:00
* @ retval DDS_RETCODE_NOT_ALLOWED_BY_SECURITY
* An invalid DDS Security configuration was specified ( whether
* that be missing or incorrect entries , expired certificates ,
* or anything else related to the security settings and
* implementation ) .
* @ retval DDS_RETCODE_PRECONDITION_NOT_MET
* Some security properties specified in the QoS , but the Cyclone
* build does not include support for DDS Security .
* @ retval DDS_RETCODE_OUT_OF_RESOURCES
* Some resource limit ( maximum participants , memory , handles ,
* & c . ) prevented creation of the participant .
2019-01-18 14:10:19 +01:00
* @ retval DDS_RETCODE_ERROR
2020-03-25 14:48:35 +01:00
* The " CYCLONEDDS_URI " environment variable lists non - existent
* or invalid configuration files , or contains invalid embedded
* configuration items ; or an unspecified internal error has
* occurred .
2019-01-18 14:10:19 +01:00
*/
DDS_EXPORT dds_entity_t
dds_create_participant (
const dds_domainid_t domain ,
const dds_qos_t * qos ,
const dds_listener_t * listener ) ;
2019-09-13 11:45:14 +02:00
/**
* @ brief Creates a domain with a given configuration
*
* To explicitly create a domain based on a configuration passed as a string .
2019-10-31 16:43:34 +01:00
*
* It will not be created if a domain with the given domain id already exists .
* This could have been created implicitly by a dds_create_participant ( ) .
*
* Please be aware that the given domain_id always takes precedence over the
* configuration .
*
* | domain_id | domain id in config | result
* + - - - - - - - - - - - + - - - - - - - - - - - - - - - - - - - - - + - - - - - - - - - -
* | n | any ( or absent ) | n , config is used
* | n | m = = n | n , config is used
* | n | m ! = n | n , config is ignored : default
*
* Config models :
* 1 : < CycloneDDS >
* < Domain id = " X " > . . . < / Domain >
* < Domain . . . / >
* < / CycloneDDS >
* where . . . is all that can today be set in children of CycloneDDS
* with the exception of the id
* 2 : < CycloneDDS >
* < Domain > < Id > X < / Id > < / Domain >
* . . .
* < / CycloneDDS >
* legacy form , domain id must be the first element in the file with
* a value ( if nothing has been set previously , it a warning is good
* enough )
*
* Using NULL or " " as config will create a domain with default settings .
2019-09-13 11:45:14 +02:00
*
*
* @ param [ in ] domain The domain to be created . DEFAULT_DOMAIN is not allowed .
* @ param [ in ] config A configuration string containing file names and / or XML fragments representing the configuration .
*
2019-10-30 14:57:55 +01:00
* @ returns A valid entity handle or an error code .
2019-09-13 11:45:14 +02:00
*
* @ retval DDS_RETCODE_BAD_PARAMETER
* Illegal value for domain id or the configfile parameter is NULL .
2019-10-31 16:43:34 +01:00
* @ retval DDS_RETCODE_PRECONDITION_NOT_MET
2019-09-13 11:45:14 +02:00
* The domain already existed and cannot be created again .
* @ retval DDS_RETCODE_ERROR
* An internal error has occurred .
*/
2019-10-30 14:57:55 +01:00
DDS_EXPORT dds_entity_t
2019-09-13 11:45:14 +02:00
dds_create_domain ( const dds_domainid_t domain , const char * config ) ;
2019-01-18 14:10:19 +01:00
/**
* @ brief Get entity parent .
*
* This operation returns the parent to which the given entity belongs .
* For instance , it will return the Participant that was used when
* creating a Publisher ( when that Publisher was provided here ) .
*
2019-10-31 16:43:34 +01:00
* When a reader or a writer are created with a participant , then a
* subscriber or publisher are created implicitly .
* This function will return the implicit parent and not the used
* participant .
2019-01-18 14:10:19 +01:00
*
* @ param [ in ] entity Entity from which to get its parent .
*
* @ returns A valid entity handle or an error code .
*
* @ retval > 0
* A valid entity handle .
* @ retval DDS_ENTITY_NIL
* Called with a participant .
* @ retval DDS_RETCODE_ERROR
* An internal error has occurred .
* @ retval DDS_RETCODE_ILLEGAL_OPERATION
* The operation is invoked on an inappropriate object .
* @ retval DDS_RETCODE_ALREADY_DELETED
* The entity has already been deleted .
*/
/* TODO: Link to generic dds entity relations documentation. */
DDS_EXPORT dds_entity_t
dds_get_parent ( dds_entity_t entity ) ;
/**
* @ brief Get entity participant .
*
* This operation returns the participant to which the given entity belongs .
* For instance , it will return the Participant that was used when
* creating a Publisher that was used to create a DataWriter ( when that
* DataWriter was provided here ) .
*
* TODO : Link to generic dds entity relations documentation .
*
* @ param [ in ] entity Entity from which to get its participant .
*
* @ returns A valid entity or an error code .
*
* @ retval > 0
* A valid participant handle .
* @ retval DDS_RETCODE_ERROR
* An internal error has occurred .
* @ retval DDS_RETCODE_ILLEGAL_OPERATION
* The operation is invoked on an inappropriate object .
* @ retval DDS_RETCODE_ALREADY_DELETED
* The entity has already been deleted .
*/
DDS_EXPORT dds_entity_t
dds_get_participant ( dds_entity_t entity ) ;
/**
* @ brief Get entity children .
*
* This operation returns the children that the entity contains .
* For instance , it will return all the Topics , Publishers and Subscribers
* of the Participant that was used to create those entities ( when that
* Participant is provided here ) .
*
* This functions takes a pre - allocated list to put the children in and
* will return the number of found children . It is possible that the given
* size of the list is not the same as the number of found children . If
* less children are found , then the last few entries in the list are
* untouched . When more children are found , then only ' size ' number of
* entries are inserted into the list , but still complete count of the
* found children is returned . Which children are returned in the latter
* case is undefined .
*
* When supplying NULL as list and 0 as size , you can use this to acquire
* the number of children without having to pre - allocate a list .
*
2019-10-31 16:43:34 +01:00
* When a reader or a writer are created with a participant , then a
* subscriber or publisher are created implicitly .
* When used on the participant , this function will return the implicit
* subscriber and / or publisher and not the related reader / writer .
2019-01-18 14:10:19 +01:00
*
* @ param [ in ] entity Entity from which to get its children .
* @ param [ out ] children Pre - allocated array to contain the found children .
* @ param [ in ] size Size of the pre - allocated children ' s list .
*
* @ returns Number of children or an error code .
*
* @ retval > = 0
2019-10-31 16:43:34 +01:00
* Number of found children ( can be larger than ' size ' ) .
2019-01-18 14:10:19 +01:00
* @ retval DDS_RETCODE_ERROR
* An internal error has occurred .
* @ retval DDS_RETCODE_BAD_PARAMETER
* The children parameter is NULL , while a size is provided .
* @ retval DDS_RETCODE_ILLEGAL_OPERATION
* The operation is invoked on an inappropriate object .
* @ retval DDS_RETCODE_ALREADY_DELETED
* The entity has already been deleted .
*/
/* TODO: Link to generic dds entity relations documentation. */
DDS_EXPORT dds_return_t
dds_get_children ( dds_entity_t entity , dds_entity_t * children , size_t size ) ;
/**
* @ brief Get the domain id to which this entity is attached .
*
* When creating a participant entity , it is attached to a certain domain .
* All the children ( like Publishers ) and childrens ' children ( like
* DataReaders ) , etc are also attached to that domain .
*
* This function will return the original domain ID when called on
2019-08-28 14:15:28 +02:00
* any of the entities within that hierarchy . For entities not associated
* with a domain , the id is set to DDS_DOMAIN_DEFAULT .
2019-01-18 14:10:19 +01:00
*
* @ param [ in ] entity Entity from which to get its children .
* @ param [ out ] id Pointer to put the domain ID in .
*
* @ returns A dds_return_t indicating success or failure .
*
* @ retval DDS_RETCODE_OK
* Domain ID was returned .
* @ retval DDS_RETCODE_ERROR
* An internal error has occurred .
* @ retval DDS_RETCODE_BAD_PARAMETER
* The id parameter is NULL .
* @ retval DDS_RETCODE_ILLEGAL_OPERATION
* The operation is invoked on an inappropriate object .
* @ retval DDS_RETCODE_ALREADY_DELETED
* The entity has already been deleted .
*/
DDS_EXPORT dds_return_t
dds_get_domainid ( dds_entity_t entity , dds_domainid_t * id ) ;
/**
* @ brief Get participants of a domain .
*
* This operation acquires the participants created on a domain and returns
* the number of found participants .
*
* This function takes a domain id with the size of pre - allocated participant ' s
* list in and will return the number of found participants . It is possible that
* the given size of the list is not the same as the number of found participants .
* If less participants are found , then the last few entries in an array stay
* untouched . If more participants are found and the array is too small , then the
* participants returned are undefined .
*
* @ param [ in ] domain_id The domain id .
* @ param [ out ] participants The participant for domain .
* @ param [ in ] size Size of the pre - allocated participant ' s list .
*
* @ returns Number of participants found or and error code .
*
* @ retval > 0
* Number of participants found .
* @ retval DDS_RETCODE_ERROR
* An internal error has occurred .
* @ retval DDS_RETCODE_BAD_PARAMETER
* The participant parameter is NULL , while a size is provided .
*/
DDS_EXPORT dds_return_t
dds_lookup_participant (
dds_domainid_t domain_id ,
dds_entity_t * participants ,
size_t size ) ;
/**
* @ brief Creates a new topic with default type handling .
*
* The type name for the topic is taken from the generated descriptor . Topic
2020-01-28 21:29:14 +01:00
* matching is done on a combination of topic name and type name . Each successful
* call to dds_create_topic creates a new topic entity sharing the same QoS
* settings with all other topics of the same name .
2019-01-18 14:10:19 +01:00
*
* @ param [ in ] participant Participant on which to create the topic .
* @ param [ in ] descriptor An IDL generated topic descriptor .
* @ param [ in ] name Name of the topic .
* @ param [ in ] qos QoS to set on the new topic ( can be NULL ) .
* @ param [ in ] listener Any listener functions associated with the new topic ( can be NULL ) .
*
2020-01-28 21:29:14 +01:00
* @ returns A valid , unique topic handle or an error code .
2019-01-18 14:10:19 +01:00
*
* @ retval > = 0
2020-01-28 21:29:14 +01:00
* A valid unique topic handle .
* @ retval DDS_RETCODE_BAD_PARAMETER
* Either participant , descriptor , name or qos is invalid .
2019-01-18 14:10:19 +01:00
* @ retval DDS_RETCODE_BAD_PARAMETER
* Either participant , descriptor , name or qos is invalid .
2020-01-28 21:29:14 +01:00
* @ retval DDS_RETCODE_INCONSISTENT_POLICY
* QoS mismatch between qos and an existing topic ' s QoS .
* @ retval DDS_RETCODE_PRECONDITION_NOT_MET
* Mismatch between type name in descriptor and pre - existing
* topic ' s type name .
2019-01-18 14:10:19 +01:00
*/
DDS_EXPORT dds_entity_t
dds_create_topic (
dds_entity_t participant ,
const dds_topic_descriptor_t * descriptor ,
const char * name ,
const dds_qos_t * qos ,
const dds_listener_t * listener ) ;
2020-03-05 15:21:02 +01:00
# define DDS_HAS_CREATE_TOPIC_GENERIC 1
2019-01-18 14:10:19 +01:00
/**
2020-03-05 15:21:02 +01:00
* @ brief Creates a new topic with provided type handling .
2019-01-18 14:10:19 +01:00
*
* The type name for the topic is taken from the provided " sertopic " object . Topic
2020-01-28 21:29:14 +01:00
* matching is done on a combination of topic name and type name . Each successful
* call to dds_create_topic creates a new topic entity sharing the same QoS
* settings with all other topics of the same name .
*
2020-03-05 15:21:02 +01:00
* In case this function returns a valid handle , the ownership of the provided
* sertopic is handed over to Cyclone . On return , the caller gets in the sertopic parameter a
* pointer to the sertopic that is actually used by the topic . This can be the provided sertopic
* ( if this sertopic was not yet known in the domain ) , or a sertopic thas was
* already known in the domain .
2019-01-18 14:10:19 +01:00
*
2020-03-05 15:21:02 +01:00
* @ param [ in ] participant Participant on which to create the topic .
* @ param [ in , out ] sertopic Internal description of the topic type ( includes name ) . On return , the sertopic parameter is set to the actual sertopic that is used by the topic .
* @ param [ in ] qos QoS to set on the new topic ( can be NULL ) .
* @ param [ in ] listener Any listener functions associated with the new topic ( can be NULL ) .
* @ param [ in ] sedp_plist Topic description to be published as part of discovery ( if NULL , not published ) .
2019-01-18 14:10:19 +01:00
*
2020-03-05 15:21:02 +01:00
* @ returns A valid , unique topic handle or an error code . Iff a valid handle , the domain takes ownership of provided serdata .
2019-01-18 14:10:19 +01:00
*
* @ retval > = 0
2020-01-28 21:29:14 +01:00
* A valid unique topic handle .
* @ retval DDS_RETCODE_BAD_PARAMETER
* Either participant , descriptor , name or qos is invalid .
2019-01-18 14:10:19 +01:00
* @ retval DDS_RETCODE_BAD_PARAMETER
* Either participant , descriptor , name or qos is invalid .
2020-01-28 21:29:14 +01:00
* @ retval DDS_RETCODE_INCONSISTENT_POLICY
* QoS mismatch between qos and an existing topic ' s QoS .
* @ retval DDS_RETCODE_PRECONDITION_NOT_MET
* Mismatch between type name in sertopic and pre - existing
* topic ' s type name .
2019-01-18 14:10:19 +01:00
*/
DDS_EXPORT dds_entity_t
2020-03-05 15:21:02 +01:00
dds_create_topic_generic (
dds_entity_t participant ,
struct ddsi_sertopic * * sertopic ,
const dds_qos_t * qos ,
const dds_listener_t * listener ,
const struct ddsi_plist * sedp_plist ) ;
DDS_DEPRECATED_EXPORT dds_entity_t
2019-01-18 14:10:19 +01:00
dds_create_topic_arbitrary (
dds_entity_t participant ,
struct ddsi_sertopic * sertopic ,
const dds_qos_t * qos ,
const dds_listener_t * listener ,
2020-02-03 10:35:31 +01:00
const struct ddsi_plist * sedp_plist ) ;
2019-01-18 14:10:19 +01:00
/**
* @ brief Finds a named topic .
*
* The returned topic should be released with dds_delete .
*
* @ param [ in ] participant The participant on which to find the topic .
* @ param [ in ] name The name of the topic to find .
*
* @ returns A valid topic handle or an error code .
*
* @ retval > 0
* A valid topic handle .
* @ retval DDS_RETCODE_BAD_PARAMETER
* Participant was invalid .
2020-01-28 21:29:14 +01:00
* @ retval DDS_RETCODE_PRECONDITION_NOT_MET
* No topic of this name existed yet in the participant
2019-01-18 14:10:19 +01:00
*/
DDS_EXPORT dds_entity_t
dds_find_topic ( dds_entity_t participant , const char * name ) ;
/**
* @ brief Returns the name of a given topic .
*
* @ param [ in ] topic The topic .
* @ param [ out ] name Buffer to write the topic name to .
* @ param [ in ] size Number of bytes available in the buffer .
*
* @ returns A dds_return_t indicating success or failure .
*
* @ retval DDS_RETCODE_OK
* Success .
*/
DDS_EXPORT dds_return_t
dds_get_name ( dds_entity_t topic , char * name , size_t size ) ;
/**
* @ brief Returns the type name of a given topic .
*
* @ param [ in ] topic The topic .
* @ param [ out ] name Buffer to write the topic type name to .
* @ param [ in ] size Number of bytes available in the buffer .
*
* @ returns A dds_return_t indicating success or failure .
*
* @ return DDS_RETCODE_OK
* Success .
*/
DDS_EXPORT dds_return_t
dds_get_type_name ( dds_entity_t topic , char * name , size_t size ) ;
/** Topic filter function */
typedef bool ( * dds_topic_filter_fn ) ( const void * sample ) ;
/**
* @ brief Sets a filter on a topic .
*
* @ param [ in ] topic The topic on which the content filter is set .
* @ param [ in ] filter The filter function used to filter topic samples .
*/
DDS_EXPORT void
dds_set_topic_filter ( dds_entity_t topic , dds_topic_filter_fn filter ) ;
DDS_DEPRECATED_EXPORT void
dds_topic_set_filter ( dds_entity_t topic , dds_topic_filter_fn filter ) ;
/**
* @ brief Gets the filter for a topic .
*
* @ param [ in ] topic The topic from which to get the filter .
*
* @ returns The topic filter .
*/
DDS_EXPORT dds_topic_filter_fn
dds_get_topic_filter ( dds_entity_t topic ) ;
DDS_DEPRECATED_EXPORT dds_topic_filter_fn
dds_topic_get_filter ( dds_entity_t topic ) ;
/**
* @ brief Creates a new instance of a DDS subscriber
*
* @ param [ in ] participant The participant on which the subscriber is being created .
* @ param [ in ] qos The QoS to set on the new subscriber ( can be NULL ) .
* @ param [ in ] listener Any listener functions associated with the new subscriber ( can be NULL ) .
*
* @ returns A valid subscriber handle or an error code .
*
* @ retval > 0
* A valid subscriber handle .
* @ retval DDS_RETCODE_ERROR
* An internal error has occurred .
* @ retval DDS_RETCODE_BAD_PARAMETER
* One of the parameters is invalid .
*/
DDS_EXPORT dds_entity_t
dds_create_subscriber (
dds_entity_t participant ,
const dds_qos_t * qos ,
const dds_listener_t * listener ) ;
/**
* @ brief Creates a new instance of a DDS publisher
*
* @ param [ in ] participant The participant to create a publisher for .
* @ param [ in ] qos The QoS to set on the new publisher ( can be NULL ) .
* @ param [ in ] listener Any listener functions associated with the new publisher ( can be NULL ) .
*
* @ returns A valid publisher handle or an error code .
*
* @ retval > 0
* A valid publisher handle .
* @ retval DDS_RETCODE_ERROR
* An internal error has occurred .
*/
/* TODO: Check list of error codes is complete. */
DDS_EXPORT dds_entity_t
dds_create_publisher (
dds_entity_t participant ,
const dds_qos_t * qos ,
const dds_listener_t * listener ) ;
/**
* @ brief Suspends the publications of the Publisher
*
* This operation is a hint to the Service so it can optimize its performance by e . g . , collecting
* modifications to DDS writers and then batching them . The Service is not required to use the hint .
*
* Every invocation of this operation must be matched by a corresponding call to @ see dds_resume
* indicating that the set of modifications has completed .
*
* @ param [ in ] publisher The publisher for which all publications will be suspended .
*
* @ returns A dds_return_t indicating success or failure .
*
* @ retval DDS_RETCODE_OK
* Publications suspended successfully .
* @ retval DDS_RETCODE_BAD_PARAMETER
* The pub parameter is not a valid publisher .
* @ retval DDS_RETCODE_UNSUPPORTED
* Operation is not supported .
*/
DDS_EXPORT dds_return_t
dds_suspend ( dds_entity_t publisher ) ;
/**
* @ brief Resumes the publications of the Publisher
*
* This operation is a hint to the Service to indicate that the application has
* completed changes initiated by a previous dds_suspend ( ) . The Service is not
* required to use the hint .
*
* The call to resume_publications must match a previous call to @ see suspend_publications .
*
* @ param [ in ] publisher The publisher for which all publications will be resumed .
*
* @ returns A dds_return_t indicating success or failure .
*
* @ retval DDS_RETCODE_OK
* Publications resumed successfully .
* @ retval DDS_RETCODE_BAD_PARAMETER
* The pub parameter is not a valid publisher .
* @ retval DDS_RETCODE_PRECONDITION_NOT_MET
* No previous matching dds_suspend ( ) .
* @ retval DDS_RETCODE_UNSUPPORTED
* Operation is not supported .
*/
DDS_EXPORT dds_return_t
dds_resume ( dds_entity_t publisher ) ;
/**
* @ brief Waits at most for the duration timeout for acks for data in the publisher or writer .
*
* This operation blocks the calling thread until either all data written by the publisher
* or writer is acknowledged by all matched reliable reader entities , or else the duration
* specified by the timeout parameter elapses , whichever happens first .
*
* @ param [ in ] publisher_or_writer Publisher or writer whose acknowledgments must be waited for
* @ param [ in ] timeout How long to wait for acknowledgments before time out
*
* @ returns A dds_return_t indicating success or failure .
*
* @ retval DDS_RETCODE_OK
* All acknowledgments successfully received with the timeout .
* @ retval DDS_RETCODE_BAD_PARAMETER
* The publisher_or_writer is not a valid publisher or writer .
* @ retval DDS_RETCODE_TIMEOUT
* Timeout expired before all acknowledgments from reliable reader entities were received .
* @ retval DDS_RETCODE_UNSUPPORTED
* Operation is not supported .
*/
DDS_EXPORT dds_return_t
dds_wait_for_acks ( dds_entity_t publisher_or_writer , dds_duration_t timeout ) ;
/**
* @ brief Creates a new instance of a DDS reader .
*
2019-10-31 16:43:34 +01:00
* When a participant is used to create a reader , an implicit subscriber is created .
2019-01-18 14:10:19 +01:00
* This implicit subscriber will be deleted automatically when the created reader
* is deleted .
*
* @ param [ in ] participant_or_subscriber The participant or subscriber on which the reader is being created .
* @ param [ in ] topic The topic to read .
* @ param [ in ] qos The QoS to set on the new reader ( can be NULL ) .
* @ param [ in ] listener Any listener functions associated with the new reader ( can be NULL ) .
*
* @ returns A valid reader handle or an error code .
*
* @ retval > 0
* A valid reader handle .
* @ retval DDS_RETCODE_ERROR
* An internal error occurred .
*/
/* TODO: Complete list of error codes */
DDS_EXPORT dds_entity_t
dds_create_reader (
dds_entity_t participant_or_subscriber ,
dds_entity_t topic ,
const dds_qos_t * qos ,
const dds_listener_t * listener ) ;
2019-09-02 09:08:13 +02:00
/**
* @ brief Creates a new instance of a DDS reader with a custom history cache .
*
2019-10-31 16:43:34 +01:00
* When a participant is used to create a reader , an implicit subscriber is created .
2019-09-02 09:08:13 +02:00
* This implicit subscriber will be deleted automatically when the created reader
* is deleted .
*
* @ param [ in ] participant_or_subscriber The participant or subscriber on which the reader is being created .
* @ param [ in ] topic The topic to read .
* @ param [ in ] qos The QoS to set on the new reader ( can be NULL ) .
* @ param [ in ] listener Any listener functions associated with the new reader ( can be NULL ) .
* @ param [ in ] rhc Reader history cache to use , reader becomes the owner
*
* @ returns A valid reader handle or an error code .
*
* @ retval > 0
* A valid reader handle .
* @ retval DDS_RETCODE_ERROR
* An internal error occurred .
*/
/* TODO: Complete list of error codes */
DDS_EXPORT dds_entity_t
dds_create_reader_rhc (
dds_entity_t participant_or_subscriber ,
dds_entity_t topic ,
const dds_qos_t * qos ,
const dds_listener_t * listener ,
struct dds_rhc * rhc ) ;
2019-01-18 14:10:19 +01:00
/**
* @ brief Wait until reader receives all historic data
*
* The operation blocks the calling thread until either all " historical " data is
* received , or else the duration specified by the max_wait parameter elapses , whichever happens
* first . A return value of 0 indicates that all the " historical " data was received ; a return
* value of TIMEOUT indicates that max_wait elapsed before all the data was received .
*
* @ param [ in ] reader The reader on which to wait for historical data .
* @ param [ in ] max_wait How long to wait for historical data before time out .
*
* @ returns a status , 0 on success , TIMEOUT on timeout or a negative value to indicate error .
*/
/* TODO: Complete list of error codes */
2019-05-23 16:51:43 +02:00
DDS_EXPORT dds_return_t
2019-01-18 14:10:19 +01:00
dds_reader_wait_for_historical_data (
dds_entity_t reader ,
dds_duration_t max_wait ) ;
/**
* @ brief Creates a new instance of a DDS writer .
*
2019-10-31 16:43:34 +01:00
* When a participant is used to create a writer , an implicit publisher is created .
2019-01-18 14:10:19 +01:00
* This implicit publisher will be deleted automatically when the created writer
* is deleted .
*
* @ param [ in ] participant_or_publisher The participant or publisher on which the writer is being created .
* @ param [ in ] topic The topic to write .
* @ param [ in ] qos The QoS to set on the new writer ( can be NULL ) .
* @ param [ in ] listener Any listener functions associated with the new writer ( can be NULL ) .
*
* @ returns A valid writer handle or an error code .
*
* @ returns > 0
* A valid writer handle .
* @ returns DDS_RETCODE_ERROR
* An internal error occurred .
*/
/* TODO: Complete list of error codes */
DDS_EXPORT dds_entity_t
dds_create_writer (
dds_entity_t participant_or_publisher ,
dds_entity_t topic ,
const dds_qos_t * qos ,
const dds_listener_t * listener ) ;
/*
Writing data ( and variants of it ) is straightforward . The first set
is equivalent to the second set with - 1 passed for " timestamp " ,
meaning , substitute the result of a call to time ( ) . The dispose
and unregister operations take an object of the topic ' s type , but
only touch the key fields ; the remained may be undefined .
*/
/**
* @ brief Registers an instance
*
* This operation registers an instance with a key value to the data writer and
* returns an instance handle that could be used for successive write & dispose
2020-02-10 10:10:42 +01:00
* operations . When the handle is not allocated , the function will return an
2019-01-18 14:10:19 +01:00
* error and the handle will be un - touched .
*
* @ param [ in ] writer The writer to which instance has be associated .
* @ param [ out ] handle The instance handle .
* @ param [ in ] data The instance with the key value .
*
* @ returns A dds_return_t indicating success or failure .
*
* @ retval DDS_RETCODE_OK
* The operation was successful .
* @ retval DDS_RETCODE_BAD_PARAMETER
* One of the given arguments is not valid .
* @ retval DDS_RETCODE_ILLEGAL_OPERATION
* The operation is invoked on an inappropriate object .
*/
DDS_EXPORT dds_return_t
dds_register_instance (
dds_entity_t writer ,
dds_instance_handle_t * handle ,
const void * data ) ;
/**
* @ brief Unregisters an instance
*
* This operation reverses the action of register instance , removes all information regarding
* the instance and unregisters an instance with a key value from the data writer .
*
* @ param [ in ] writer The writer to which instance is associated .
* @ param [ in ] data The instance with the key value .
*
* @ returns A dds_return_t indicating success or failure .
*
* @ retval DDS_RETCODE_OK
* The operation was successful .
* @ retval DDS_RETCODE_BAD_PARAMETER
* One of the given arguments is not valid .
* @ retval DDS_RETCODE_ILLEGAL_OPERATION
* The operation is invoked on an inappropriate object .
*/
DDS_EXPORT dds_return_t
dds_unregister_instance ( dds_entity_t writer , const void * data ) ;
/**
* @ brief Unregisters an instance
*
* This operation unregisters the instance which is identified by the key fields of the given
* typed instance handle .
*
* @ param [ in ] writer The writer to which instance is associated .
* @ param [ in ] handle The instance handle .
*
* @ returns A dds_return_t indicating success or failure .
*
* @ retval DDS_RETCODE_OK
* The operation was successful .
* @ retval DDS_RETCODE_BAD_PARAMETER
* One of the given arguments is not valid .
* @ retval DDS_RETCODE_ILLEGAL_OPERATION
* The operation is invoked on an inappropriate object .
*/
DDS_EXPORT dds_return_t
dds_unregister_instance_ih ( dds_entity_t writer , dds_instance_handle_t handle ) ;
/**
* @ brief Unregisters an instance
*
* This operation reverses the action of register instance , removes all information regarding
* the instance and unregisters an instance with a key value from the data writer . It also
* provides a value for the timestamp explicitly .
*
* @ param [ in ] writer The writer to which instance is associated .
* @ param [ in ] data The instance with the key value .
* @ param [ in ] timestamp The timestamp used at registration .
*
* @ returns A dds_return_t indicating success or failure .
*
* @ retval DDS_RETCODE_OK
* The operation was successful .
* @ retval DDS_RETCODE_BAD_PARAMETER
* One of the given arguments is not valid .
* @ retval DDS_RETCODE_ILLEGAL_OPERATION
* The operation is invoked on an inappropriate object .
*/
DDS_EXPORT dds_return_t
dds_unregister_instance_ts (
dds_entity_t writer ,
const void * data ,
dds_time_t timestamp ) ;
/**
* @ brief Unregisters an instance
*
* This operation unregisters an instance with a key value from the handle . Instance can be identified
* from instance handle . If an unregistered key ID is passed as an instance data , an error is logged and
* not flagged as return value .
*
* @ param [ in ] writer The writer to which instance is associated .
* @ param [ in ] handle The instance handle .
* @ param [ in ] timestamp The timestamp used at registration .
*
* @ returns A dds_return_t indicating success or failure .
*
* @ retval DDS_RETCODE_OK
* The operation was successful
* @ retval DDS_RETCODE_BAD_PARAMETER
* One of the given arguments is not valid
* @ retval DDS_RETCODE_ILLEGAL_OPERATION
* The operation is invoked on an inappropriate object
*/
DDS_EXPORT dds_return_t
dds_unregister_instance_ih_ts (
dds_entity_t writer ,
dds_instance_handle_t handle ,
dds_time_t timestamp ) ;
/**
* @ brief This operation modifies and disposes a data instance .
*
* This operation requests the Data Distribution Service to modify the instance and
* mark it for deletion . Copies of the instance and its corresponding samples , which are
* stored in every connected reader and , dependent on the QoS policy settings ( also in
* the Transient and Persistent stores ) will be modified and marked for deletion by
* setting their dds_instance_state_t to DDS_IST_NOT_ALIVE_DISPOSED .
*
* < b > < i > Blocking < / i > < / b > < br >
* If the history QoS policy is set to DDS_HISTORY_KEEP_ALL , the
* dds_writedispose operation on the writer may block if the modification
* would cause data to be lost because one of the limits , specified in the
* resource_limits QoS policy , to be exceeded . In case the synchronous
* attribute value of the reliability Qos policy is set to true for
* communicating writers and readers then the writer will wait until
* all synchronous readers have acknowledged the data . Under these
* circumstances , the max_blocking_time attribute of the reliability
* QoS policy configures the maximum time the dds_writedispose operation
* may block .
* If max_blocking_time elapses before the writer is able to store the
* modification without exceeding the limits and all expected acknowledgements
* are received , the dds_writedispose operation will fail and returns
* DDS_RETCODE_TIMEOUT .
*
* @ param [ in ] writer The writer to dispose the data instance from .
* @ param [ in ] data The data to be written and disposed .
*
* @ returns A dds_return_t indicating success or failure .
*
* @ retval DDS_RETCODE_OK
* The sample is written and the instance is marked for deletion .
* @ retval DDS_RETCODE_ERROR
* An internal error has occurred .
* @ retval DDS_RETCODE_BAD_PARAMETER
* At least one of the arguments is invalid .
* @ retval DDS_RETCODE_ILLEGAL_OPERATION
* The operation is invoked on an inappropriate object .
* @ retval DDS_RETCODE_ALREADY_DELETED
* The entity has already been deleted .
* @ retval DDS_RETCODE_TIMEOUT
* Either the current action overflowed the available resources as
* specified by the combination of the reliability QoS policy ,
* history QoS policy and resource_limits QoS policy , or the
* current action was waiting for data delivery acknowledgement
* by synchronous readers . This caused blocking of this operation ,
* which could not be resolved before max_blocking_time of the
* reliability QoS policy elapsed .
*/
DDS_EXPORT dds_return_t
dds_writedispose ( dds_entity_t writer , const void * data ) ;
/**
* @ brief This operation modifies and disposes a data instance with a specific
* timestamp .
*
* This operation performs the same functions as dds_writedispose except that
* the application provides the value for the source_timestamp that is made
* available to connected reader objects . This timestamp is important for the
* interpretation of the destination_order QoS policy .
*
* @ param [ in ] writer The writer to dispose the data instance from .
* @ param [ in ] data The data to be written and disposed .
* @ param [ in ] timestamp The timestamp used as source timestamp .
*
* @ returns A dds_return_t indicating success or failure .
*
* @ retval DDS_RETCODE_OK
* The sample is written and the instance is marked for deletion .
* @ retval DDS_RETCODE_ERROR
* An internal error has occurred .
* @ retval DDS_RETCODE_BAD_PARAMETER
* At least one of the arguments is invalid .
* @ retval DDS_RETCODE_ILLEGAL_OPERATION
* The operation is invoked on an inappropriate object .
* @ retval DDS_RETCODE_ALREADY_DELETED
* The entity has already been deleted .
* @ retval DDS_RETCODE_TIMEOUT
* Either the current action overflowed the available resources as
* specified by the combination of the reliability QoS policy ,
* history QoS policy and resource_limits QoS policy , or the
* current action was waiting for data delivery acknowledgement
* by synchronous readers . This caused blocking of this operation ,
* which could not be resolved before max_blocking_time of the
* reliability QoS policy elapsed .
*/
DDS_EXPORT dds_return_t
dds_writedispose_ts (
dds_entity_t writer ,
const void * data ,
dds_time_t timestamp ) ;
/**
* @ brief This operation disposes an instance , identified by the data sample .
*
* This operation requests the Data Distribution Service to modify the instance and
* mark it for deletion . Copies of the instance and its corresponding samples , which are
* stored in every connected reader and , dependent on the QoS policy settings ( also in
* the Transient and Persistent stores ) will be modified and marked for deletion by
* setting their dds_instance_state_t to DDS_IST_NOT_ALIVE_DISPOSED .
*
* < b > < i > Blocking < / i > < / b > < br >
* If the history QoS policy is set to DDS_HISTORY_KEEP_ALL , the
* dds_writedispose operation on the writer may block if the modification
* would cause data to be lost because one of the limits , specified in the
* resource_limits QoS policy , to be exceeded . In case the synchronous
* attribute value of the reliability Qos policy is set to true for
* communicating writers and readers then the writer will wait until
* all synchronous readers have acknowledged the data . Under these
* circumstances , the max_blocking_time attribute of the reliability
* QoS policy configures the maximum time the dds_writedispose operation
* may block .
* If max_blocking_time elapses before the writer is able to store the
* modification without exceeding the limits and all expected acknowledgements
* are received , the dds_writedispose operation will fail and returns
* DDS_RETCODE_TIMEOUT .
*
* @ param [ in ] writer The writer to dispose the data instance from .
* @ param [ in ] data The data sample that identifies the instance
* to be disposed .
*
* @ returns A dds_return_t indicating success or failure .
*
* @ retval DDS_RETCODE_OK
* The sample is written and the instance is marked for deletion .
* @ retval DDS_RETCODE_ERROR
* An internal error has occurred .
* @ retval DDS_RETCODE_BAD_PARAMETER
* At least one of the arguments is invalid .
* @ retval DDS_RETCODE_ILLEGAL_OPERATION
* The operation is invoked on an inappropriate object .
* @ retval DDS_RETCODE_ALREADY_DELETED
* The entity has already been deleted .
* @ retval DDS_RETCODE_TIMEOUT
* Either the current action overflowed the available resources as
* specified by the combination of the reliability QoS policy ,
* history QoS policy and resource_limits QoS policy , or the
* current action was waiting for data delivery acknowledgement
* by synchronous readers . This caused blocking of this operation ,
* which could not be resolved before max_blocking_time of the
* reliability QoS policy elapsed .
*/
DDS_EXPORT dds_return_t
dds_dispose ( dds_entity_t writer , const void * data ) ;
/**
* @ brief This operation disposes an instance with a specific timestamp , identified by the data sample .
*
* This operation performs the same functions as dds_dispose except that
* the application provides the value for the source_timestamp that is made
* available to connected reader objects . This timestamp is important for the
* interpretation of the destination_order QoS policy .
*
* @ param [ in ] writer The writer to dispose the data instance from .
* @ param [ in ] data The data sample that identifies the instance
* to be disposed .
* @ param [ in ] timestamp The timestamp used as source timestamp .
*
* @ returns A dds_return_t indicating success or failure .
*
* @ retval DDS_RETCODE_OK
* The sample is written and the instance is marked for deletion
* @ retval DDS_RETCODE_ERROR
* An internal error has occurred
* @ retval DDS_RETCODE_BAD_PARAMETER
* At least one of the arguments is invalid
* @ retval DDS_RETCODE_ILLEGAL_OPERATION
* The operation is invoked on an inappropriate object
* @ retval DDS_RETCODE_ALREADY_DELETED
* The entity has already been deleted
* @ retval DDS_RETCODE_TIMEOUT
* Either the current action overflowed the available resources as
* specified by the combination of the reliability QoS policy ,
* history QoS policy and resource_limits QoS policy , or the
* current action was waiting for data delivery acknowledgment
* by synchronous readers . This caused blocking of this operation ,
* which could not be resolved before max_blocking_time of the
* reliability QoS policy elapsed .
*/
DDS_EXPORT dds_return_t
dds_dispose_ts (
dds_entity_t writer ,
const void * data ,
dds_time_t timestamp ) ;
/**
* @ brief This operation disposes an instance , identified by the instance handle .
*
* This operation requests the Data Distribution Service to modify the instance and
* mark it for deletion . Copies of the instance and its corresponding samples , which are
* stored in every connected reader and , dependent on the QoS policy settings ( also in
* the Transient and Persistent stores ) will be modified and marked for deletion by
* setting their dds_instance_state_t to DDS_IST_NOT_ALIVE_DISPOSED .
*
* < b > < i > Instance Handle < / i > < / b > < br >
* The given instance handle must correspond to the value that was returned by either
* the dds_register_instance operation , dds_register_instance_ts or dds_lookup_instance .
* If there is no correspondence , then the result of the operation is unspecified .
*
* @ param [ in ] writer The writer to dispose the data instance from .
* @ param [ in ] handle The handle to identify an instance .
*
* @ returns A dds_return_t indicating success or failure .
*
* @ retval DDS_RETCODE_OK
* The sample is written and the instance is marked for deletion .
* @ retval DDS_RETCODE_ERROR
* An internal error has occurred .
* @ retval DDS_RETCODE_BAD_PARAMETER
* At least one of the arguments is invalid
* @ retval DDS_RETCODE_ILLEGAL_OPERATION
* The operation is invoked on an inappropriate object
* @ retval DDS_RETCODE_ALREADY_DELETED
* The entity has already been deleted
* @ retval DDS_RETCODE_PRECONDITION_NOT_MET
* The instance handle has not been registered with this writer
*/
DDS_EXPORT dds_return_t
dds_dispose_ih ( dds_entity_t writer , dds_instance_handle_t handle ) ;
/**
* @ brief This operation disposes an instance with a specific timestamp , identified by the instance handle .
*
* This operation performs the same functions as dds_dispose_ih except that
* the application provides the value for the source_timestamp that is made
* available to connected reader objects . This timestamp is important for the
* interpretation of the destination_order QoS policy .
*
* @ param [ in ] writer The writer to dispose the data instance from .
* @ param [ in ] handle The handle to identify an instance .
* @ param [ in ] timestamp The timestamp used as source timestamp .
*
* @ returns A dds_return_t indicating success or failure .
*
* @ retval DDS_RETCODE_OK
* The sample is written and the instance is marked for deletion .
* @ retval DDS_RETCODE_ERROR
* An internal error has occurred .
* @ retval DDS_RETCODE_BAD_PARAMETER
* At least one of the arguments is invalid .
* @ retval DDS_RETCODE_ILLEGAL_OPERATION
* The operation is invoked on an inappropriate object .
* @ retval DDS_RETCODE_ALREADY_DELETED
* The entity has already been deleted .
* @ retval DDS_RETCODE_PRECONDITION_NOT_MET
* The instance handle has not been registered with this writer .
*/
DDS_EXPORT dds_return_t
dds_dispose_ih_ts (
dds_entity_t writer ,
dds_instance_handle_t handle ,
dds_time_t timestamp ) ;
/**
* @ brief Write the value of a data instance
*
* With this API , the value of the source timestamp is automatically made
* available to the data reader by the service .
*
* @ param [ in ] writer The writer entity .
* @ param [ in ] data Value to be written .
*
* @ returns dds_return_t indicating success or failure .
*/
DDS_EXPORT dds_return_t
dds_write ( dds_entity_t writer , const void * data ) ;
/*TODO: What is it for and is it really needed? */
DDS_EXPORT void
dds_write_flush ( dds_entity_t writer ) ;
/**
2019-12-12 14:11:05 +01:00
* @ brief Write a serialized value of a data instance
*
* This call causes the writer to write the serialized value that is provided
* in the serdata argument .
2019-01-18 14:10:19 +01:00
*
* @ param [ in ] writer The writer entity .
2019-12-12 14:11:05 +01:00
* @ param [ in ] serdata Serialized value to be written .
2019-01-18 14:10:19 +01:00
*
* @ returns A dds_return_t indicating success or failure .
2019-12-12 14:11:05 +01:00
*
* @ retval DDS_RETCODE_OK
* The writer successfully wrote the serialized value .
* @ retval DDS_RETCODE_ERROR
* An internal error has occurred .
* @ retval DDS_RETCODE_BAD_PARAMETER
* One of the given arguments is not valid .
* @ retval DDS_RETCODE_ILLEGAL_OPERATION
* The operation is invoked on an inappropriate object .
* @ retval DDS_RETCODE_ALREADY_DELETED
* The entity has already been deleted .
* @ retval DDS_RETCODE_TIMEOUT
* The writer failed to write the serialized value reliably within the specified max_blocking_time .
2019-01-18 14:10:19 +01:00
*/
DDS_EXPORT dds_return_t
dds_writecdr ( dds_entity_t writer , struct ddsi_serdata * serdata ) ;
/**
* @ brief Write the value of a data instance along with the source timestamp passed .
*
* @ param [ in ] writer The writer entity .
* @ param [ in ] data Value to be written .
* @ param [ in ] timestamp Source timestamp .
*
* @ returns A dds_return_t indicating success or failure .
*/
DDS_EXPORT dds_return_t
dds_write_ts (
dds_entity_t writer ,
const void * data ,
dds_time_t timestamp ) ;
/**
* @ brief Creates a readcondition associated to the given reader .
*
* The readcondition allows specifying which samples are of interest in
* a data reader ' s history , by means of a mask . The mask is or ' d with
* the flags that are dds_sample_state_t , dds_view_state_t and
* dds_instance_state_t .
*
* Based on the mask value set , the readcondition gets triggered when
* data is available on the reader .
*
* Waitsets allow waiting for an event on some of any set of entities .
* This means that the readcondition can be used to wake up a waitset when
* data is in the reader history with states that matches the given mask .
*
* @ note The parent reader and every of its associated conditions ( whether
* they are readconditions or queryconditions ) share the same resources .
* This means that one of these entities reads or takes data , the states
* of the data will change for other entities automatically . For instance ,
* if one reads a sample , then the sample state will become ' read ' for all
* associated reader / conditions . Or if one takes a sample , then it ' s not
* available to any other associated reader / condition .
*
* @ param [ in ] reader Reader to associate the condition to .
* @ param [ in ] mask Interest ( dds_sample_state_t | dds_view_state_t | dds_instance_state_t ) .
*
* @ returns A valid condition handle or an error code .
*
* @ retval > 0
* A valid condition handle
* @ retval DDS_RETCODE_ERROR
* An internal error has occurred .
* @ retval DDS_RETCODE_ILLEGAL_OPERATION
* The operation is invoked on an inappropriate object .
* @ retval DDS_RETCODE_ALREADY_DELETED
* The entity has already been deleted .
*/
DDS_EXPORT dds_entity_t
dds_create_readcondition ( dds_entity_t reader , uint32_t mask ) ;
typedef bool ( * dds_querycondition_filter_fn ) ( const void * sample ) ;
/**
* @ brief Creates a queryondition associated to the given reader .
*
* The queryondition allows specifying which samples are of interest in
* a data reader ' s history , by means of a mask and a filter . The mask is
* or ' d with the flags that are dds_sample_state_t , dds_view_state_t and
* dds_instance_state_t .
*
* Based on the mask value set and data that matches the filter , the
* querycondition gets triggered when data is available on the reader .
*
* Waitsets allow waiting for an event on some of any set of entities .
* This means that the querycondition can be used to wake up a waitset when
* data is in the reader history with states that matches the given mask
* and filter .
*
* @ note The parent reader and every of its associated conditions ( whether
* they are readconditions or queryconditions ) share the same resources .
* This means that one of these entities reads or takes data , the states
* of the data will change for other entities automatically . For instance ,
* if one reads a sample , then the sample state will become ' read ' for all
* associated reader / conditions . Or if one takes a sample , then it ' s not
* available to any other associated reader / condition .
*
* @ param [ in ] reader Reader to associate the condition to .
* @ param [ in ] mask Interest ( dds_sample_state_t | dds_view_state_t | dds_instance_state_t ) .
* @ param [ in ] filter Callback that the application can use to filter specific samples .
*
* @ returns A valid condition handle or an error code
*
* @ retval > = 0
* A valid condition handle .
* @ retval DDS_RETCODE_ERROR
* An internal error has occurred .
* @ retval DDS_RETCODE_ILLEGAL_OPERATION
* The operation is invoked on an inappropriate object .
* @ retval DDS_RETCODE_ALREADY_DELETED
* The entity has already been deleted .
*/
/* TODO: Explain the filter (aka expression & parameters) of the (to be
* implemented ) new querycondition implementation .
* TODO : Update parameters when new querycondition is introduced .
*/
DDS_EXPORT dds_entity_t
dds_create_querycondition (
dds_entity_t reader ,
uint32_t mask ,
dds_querycondition_filter_fn filter ) ;
/**
* @ brief Creates a guardcondition .
*
* Waitsets allow waiting for an event on some of any set of entities .
* This means that the guardcondition can be used to wake up a waitset when
* data is in the reader history with states that matches the given mask .
*
* @ returns A valid condition handle or an error code .
*
* @ retval > 0
* A valid condition handle
* @ retval DDS_RETCODE_ERROR
* An internal error has occurred .
* @ retval DDS_RETCODE_ILLEGAL_OPERATION
* The operation is invoked on an inappropriate object .
* @ retval DDS_RETCODE_ALREADY_DELETED
* The entity has already been deleted .
*/
DDS_EXPORT dds_entity_t
dds_create_guardcondition ( dds_entity_t participant ) ;
/**
* @ brief Sets the trigger status of a guardcondition .
*
* @ retval DDS_RETCODE_OK
* Operation successful
* @ retval DDS_RETCODE_ERROR
* An internal error has occurred .
* @ retval DDS_RETCODE_ILLEGAL_OPERATION
* The operation is invoked on an inappropriate object .
* @ retval DDS_RETCODE_ALREADY_DELETED
* The entity has already been deleted .
*/
DDS_EXPORT dds_return_t
dds_set_guardcondition ( dds_entity_t guardcond , bool triggered ) ;
/**
* @ brief Reads the trigger status of a guardcondition .
*
* @ retval DDS_RETCODE_OK
* Operation successful
* @ retval DDS_RETCODE_ERROR
* An internal error has occurred .
* @ retval DDS_RETCODE_ILLEGAL_OPERATION
* The operation is invoked on an inappropriate object .
* @ retval DDS_RETCODE_ALREADY_DELETED
* The entity has already been deleted .
*/
DDS_EXPORT dds_return_t
dds_read_guardcondition ( dds_entity_t guardcond , bool * triggered ) ;
/**
* @ brief Reads and resets the trigger status of a guardcondition .
*
* @ retval DDS_RETCODE_OK
* Operation successful
* @ retval DDS_RETCODE_ERROR
* An internal error has occurred .
* @ retval DDS_RETCODE_ILLEGAL_OPERATION
* The operation is invoked on an inappropriate object .
* @ retval DDS_RETCODE_ALREADY_DELETED
* The entity has already been deleted .
*/
DDS_EXPORT dds_return_t
dds_take_guardcondition ( dds_entity_t guardcond , bool * triggered ) ;
/**
* @ brief Waitset attachment argument .
*
* Every entity that is attached to the waitset can be accompanied by such
* an attachment argument . When the waitset wait is unblocked because of an
* entity that triggered , then the returning array will be populated with
* these attachment arguments that are related to the triggered entity .
*/
typedef intptr_t dds_attach_t ;
/**
* @ brief Create a waitset and allocate the resources required
*
* A WaitSet object allows an application to wait until one or more of the
* conditions of the attached entities evaluates to TRUE or until the timeout
* expires .
*
* @ param [ in ] participant Domain participant which the WaitSet contains .
*
* @ returns A valid waitset handle or an error code .
*
* @ retval > = 0
* A valid waitset handle .
* @ retval DDS_RETCODE_ERROR
* An internal error has occurred .
* @ retval DDS_RETCODE_ILLEGAL_OPERATION
* The operation is invoked on an inappropriate object .
* @ retval DDS_RETCODE_ALREADY_DELETED
* The entity has already been deleted .
*/
DDS_EXPORT dds_entity_t
dds_create_waitset ( dds_entity_t participant ) ;
/**
* @ brief Acquire previously attached entities .
*
* This functions takes a pre - allocated list to put the entities in and
* will return the number of found entities . It is possible that the given
* size of the list is not the same as the number of found entities . If
* less entities are found , then the last few entries in the list are
* untouched . When more entities are found , then only ' size ' number of
* entries are inserted into the list , but still the complete count of the
* found entities is returned . Which entities are returned in the latter
* case is undefined .
*
* @ param [ in ] waitset Waitset from which to get its attached entities .
* @ param [ out ] entities Pre - allocated array to contain the found entities .
* @ param [ in ] size Size of the pre - allocated entities ' list .
*
* @ returns A dds_return_t with the number of children or an error code .
*
* @ retval > = 0
* Number of children found ( can be larger than ' size ' ) .
* @ retval DDS_RETCODE_ERROR
* An internal error has occurred .
* @ retval DDS_RETCODE_BAD_PARAMETER
* The entities parameter is NULL , while a size is provided .
* @ retval DDS_RETCODE_ILLEGAL_OPERATION
* The operation is invoked on an inappropriate object .
* @ retval DDS_RETCODE_ALREADY_DELETED
* The waitset has already been deleted .
*/
DDS_EXPORT dds_return_t
dds_waitset_get_entities (
dds_entity_t waitset ,
dds_entity_t * entities ,
size_t size ) ;
/**
* @ brief This operation attaches an Entity to the WaitSet .
*
* This operation attaches an Entity to the WaitSet . The dds_waitset_wait ( )
* will block when none of the attached entities are triggered . ' Triggered '
* ( dds_triggered ( ) ) doesn ' t mean the same for every entity :
* - Reader / Writer / Publisher / Subscriber / Topic / Participant
* - These are triggered when their status changed .
* - WaitSet
* - Triggered when trigger value was set to true by the application .
* It stays triggered until application sets the trigger value to
* false ( dds_waitset_set_trigger ( ) ) . This can be used to wake up an
* waitset for different reasons ( f . i . termination ) than the ' normal '
* status change ( like new data ) .
* - ReadCondition / QueryCondition
* - Triggered when data is available on the related Reader that matches
* the Condition .
*
* Multiple entities can be attached to a single waitset . A particular entity
* can be attached to multiple waitsets . However , a particular entity can not
* be attached to a particular waitset multiple times .
*
* @ param [ in ] waitset The waitset to attach the given entity to .
* @ param [ in ] entity The entity to attach .
* @ param [ in ] x Blob that will be supplied when the waitset wait is
* triggerd by the given entity .
*
* @ returns A dds_return_t indicating success or failure .
*
* @ retval DDS_RETCODE_OK
* Entity attached .
* @ retval DDS_RETCODE_ERROR
* An internal error has occurred .
* @ retval DDS_RETCODE_BAD_PARAMETER
* The given waitset or entity are not valid .
* @ retval DDS_RETCODE_ILLEGAL_OPERATION
* The operation is invoked on an inappropriate object .
* @ retval DDS_RETCODE_ALREADY_DELETED
* The waitset has already been deleted .
* @ retval DDS_RETCODE_PRECONDITION_NOT_MET
* The entity was already attached .
*/
DDS_EXPORT dds_return_t
dds_waitset_attach (
dds_entity_t waitset ,
dds_entity_t entity ,
dds_attach_t x ) ;
/**
* @ brief This operation detaches an Entity to the WaitSet .
*
* @ param [ in ] waitset The waitset to detach the given entity from .
* @ param [ in ] entity The entity to detach .
*
* @ returns A dds_return_t indicating success or failure .
*
* @ retval DDS_RETCODE_OK
2020-02-10 10:10:42 +01:00
* Entity detached .
2019-01-18 14:10:19 +01:00
* @ retval DDS_RETCODE_ERROR
* An internal error has occurred .
* @ retval DDS_RETCODE_BAD_PARAMETER
* The given waitset or entity are not valid .
* @ retval DDS_RETCODE_ILLEGAL_OPERATION
* The operation is invoked on an inappropriate object .
* @ retval DDS_RETCODE_ALREADY_DELETED
* The waitset has already been deleted .
* @ retval DDS_RETCODE_PRECONDITION_NOT_MET
* The entity is not attached .
*/
DDS_EXPORT dds_return_t
dds_waitset_detach (
dds_entity_t waitset ,
dds_entity_t entity ) ;
/**
* @ brief Sets the trigger_value associated with a waitset .
*
* When the waitset is attached to itself and the trigger value is
* set to ' true ' , then the waitset will wake up just like with an
* other status change of the attached entities .
*
* This can be used to forcefully wake up a waitset , for instance
* when the application wants to shut down . So , when the trigger
* value is true , the waitset will wake up or not wait at all .
*
* The trigger value will remain true until the application sets it
* false again deliberately .
*
* @ param [ in ] waitset The waitset to set the trigger value on .
* @ param [ in ] trigger The trigger value to set .
*
* @ returns A dds_return_t indicating success or failure .
*
* @ retval DDS_RETCODE_OK
2020-02-10 10:10:42 +01:00
* Trigger value set .
2019-01-18 14:10:19 +01:00
* @ retval DDS_RETCODE_ERROR
* An internal error has occurred .
* @ retval DDS_RETCODE_BAD_PARAMETER
* The given waitset is not valid .
* @ retval DDS_RETCODE_ILLEGAL_OPERATION
* The operation is invoked on an inappropriate object .
* @ retval DDS_RETCODE_ALREADY_DELETED
* The waitset has already been deleted .
*/
DDS_EXPORT dds_return_t
dds_waitset_set_trigger (
dds_entity_t waitset ,
bool trigger ) ;
/**
* @ brief This operation allows an application thread to wait for the a status
* change or other trigger on ( one of ) the entities that are attached to
* the WaitSet .
*
* The " dds_waitset_wait " operation blocks until the some of the attached
* entities have triggered or " reltimeout " has elapsed .
* ' Triggered ' ( dds_triggered ( ) ) doesn ' t mean the same for every entity :
* - Reader / Writer / Publisher / Subscriber / Topic / Participant
* - These are triggered when their status changed .
* - WaitSet
* - Triggered when trigger value was set to true by the application .
* It stays triggered until application sets the trigger value to
* false ( dds_waitset_set_trigger ( ) ) . This can be used to wake up an
* waitset for different reasons ( f . i . termination ) than the ' normal '
* status change ( like new data ) .
* - ReadCondition / QueryCondition
* - Triggered when data is available on the related Reader that matches
* the Condition .
*
* This functions takes a pre - allocated list to put the " xs " blobs in ( that
* were provided during the attach of the related entities ) and will return
* the number of triggered entities . It is possible that the given size
* of the list is not the same as the number of triggered entities . If less
* entities were triggered , then the last few entries in the list are
* untouched . When more entities are triggered , then only ' size ' number of
* entries are inserted into the list , but still the complete count of the
* triggered entities is returned . Which " xs " blobs are returned in the
* latter case is undefined .
*
* In case of a time out , the return value is 0.
*
* Deleting the waitset while the application is blocked results in an
* error code ( i . e . < 0 ) returned by " wait " .
*
* Multiple threads may block on a single waitset at the same time ;
* the calls are entirely independent .
*
* An empty waitset never triggers ( i . e . , dds_waitset_wait on an empty
* waitset is essentially equivalent to a sleep ) .
*
* The " dds_waitset_wait_until " operation is the same as the
* " dds_waitset_wait " except that it takes an absolute timeout .
*
* @ param [ in ] waitset The waitset to set the trigger value on .
* @ param [ out ] xs Pre - allocated list to store the ' blobs ' that were
* provided during the attach of the triggered entities .
* @ param [ in ] nxs The size of the pre - allocated blobs list .
* @ param [ in ] reltimeout Relative timeout
*
* @ returns A dds_return_t with the number of entities triggered or an error code
*
* @ retval > 0
* Number of entities triggered .
* @ retval 0
* Time out ( no entities were triggered ) .
* @ retval DDS_RETCODE_ERROR
* An internal error has occurred .
* @ retval DDS_RETCODE_BAD_PARAMETER
* The given waitset is not valid .
* @ retval DDS_RETCODE_ILLEGAL_OPERATION
* The operation is invoked on an inappropriate object .
* @ retval DDS_RETCODE_ALREADY_DELETED
* The waitset has already been deleted .
*/
DDS_EXPORT dds_return_t
dds_waitset_wait (
dds_entity_t waitset ,
dds_attach_t * xs ,
size_t nxs ,
dds_duration_t reltimeout ) ;
/**
* @ brief This operation allows an application thread to wait for the a status
* change or other trigger on ( one of ) the entities that are attached to
* the WaitSet .
*
* The " dds_waitset_wait " operation blocks until the some of the attached
* entities have triggered or " abstimeout " has been reached .
* ' Triggered ' ( dds_triggered ( ) ) doesn ' t mean the same for every entity :
* - Reader / Writer / Publisher / Subscriber / Topic / Participant
* - These are triggered when their status changed .
* - WaitSet
* - Triggered when trigger value was set to true by the application .
* It stays triggered until application sets the trigger value to
* false ( dds_waitset_set_trigger ( ) ) . This can be used to wake up an
* waitset for different reasons ( f . i . termination ) than the ' normal '
* status change ( like new data ) .
* - ReadCondition / QueryCondition
* - Triggered when data is available on the related Reader that matches
* the Condition .
*
* This functions takes a pre - allocated list to put the " xs " blobs in ( that
* were provided during the attach of the related entities ) and will return
* the number of triggered entities . It is possible that the given size
* of the list is not the same as the number of triggered entities . If less
* entities were triggered , then the last few entries in the list are
* untouched . When more entities are triggered , then only ' size ' number of
* entries are inserted into the list , but still the complete count of the
* triggered entities is returned . Which " xs " blobs are returned in the
* latter case is undefined .
*
* In case of a time out , the return value is 0.
*
* Deleting the waitset while the application is blocked results in an
* error code ( i . e . < 0 ) returned by " wait " .
*
* Multiple threads may block on a single waitset at the same time ;
* the calls are entirely independent .
*
* An empty waitset never triggers ( i . e . , dds_waitset_wait on an empty
* waitset is essentially equivalent to a sleep ) .
*
* The " dds_waitset_wait " operation is the same as the
* " dds_waitset_wait_until " except that it takes an relative timeout .
*
* The " dds_waitset_wait " operation is the same as the " dds_wait "
* except that it takes an absolute timeout .
*
* @ param [ in ] waitset The waitset to set the trigger value on .
* @ param [ out ] xs Pre - allocated list to store the ' blobs ' that were
* provided during the attach of the triggered entities .
* @ param [ in ] nxs The size of the pre - allocated blobs list .
* @ param [ in ] abstimeout Absolute timeout
*
* @ returns A dds_return_t with the number of entities triggered or an error code .
*
* @ retval > 0
* Number of entities triggered .
* @ retval 0
* Time out ( no entities were triggered ) .
* @ retval DDS_RETCODE_ERROR
* An internal error has occurred .
* @ retval DDS_RETCODE_BAD_PARAMETER
* The given waitset is not valid .
* @ retval DDS_RETCODE_ILLEGAL_OPERATION
* The operation is invoked on an inappropriate object .
* @ retval DDS_RETCODE_ALREADY_DELETED
* The waitset has already been deleted .
*/
DDS_EXPORT dds_return_t
dds_waitset_wait_until (
dds_entity_t waitset ,
dds_attach_t * xs ,
size_t nxs ,
dds_time_t abstimeout ) ;
/*
There are a number of read and take variations .
Return value is the number of elements returned . " max_samples "
should have the same type , as one can ' t return more than MAX_INT
this way , anyway . X , Y , CX , CY return to the various filtering
options , see the DCPS spec .
O : : = read | take
X = > CX
( empty ) ( empty )
_next_instance instance_handle_t prev
Y = > CY
( empty ) uint32_t mask
_cond cond_t cond - - refers to a read condition ( or query if implemented )
*/
/**
* @ brief Access and read the collection of data values ( of same type ) and sample info from the
* data reader , readcondition or querycondition .
*
* Return value provides information about number of samples read , which will
* be < = maxs . Based on the count , the buffer will contain data to be read only
* when valid_data bit in sample info structure is set .
* The buffer required for data values , could be allocated explicitly or can
* use the memory from data reader to prevent copy . In the latter case , buffer and
* sample_info should be returned back , once it is no longer using the Data .
* Data values once read will remain in the buffer with the sample_state set to READ
* and view_state set to NOT_NEW .
*
* @ param [ in ] reader_or_condition Reader , readcondition or querycondition entity .
* @ param [ out ] buf An array of pointers to samples into which data is read ( pointers can be NULL ) .
* @ param [ out ] si Pointer to an array of \ ref dds_sample_info_t returned for each data value .
* @ param [ in ] bufsz The size of buffer provided .
* @ param [ in ] maxs Maximum number of samples to read .
*
* @ returns A dds_return_t with the number of samples read or an error code .
*
* @ retval > = 0
* Number of samples read .
* @ retval DDS_RETCODE_ERROR
* An internal error has occurred .
* @ retval DDS_RETCODE_BAD_PARAMETER
* One of the given arguments is not valid .
* @ retval DDS_RETCODE_ILLEGAL_OPERATION
* The operation is invoked on an inappropriate object .
* @ retval DDS_RETCODE_ALREADY_DELETED
* The entity has already been deleted .
*/
DDS_EXPORT dds_return_t
dds_read (
dds_entity_t reader_or_condition ,
void * * buf ,
dds_sample_info_t * si ,
size_t bufsz ,
uint32_t maxs ) ;
/**
* @ brief Access and read loaned samples of data reader , readcondition or querycondition .
*
* 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 .
*
* @ param [ in ] reader_or_condition Reader , readcondition or querycondition entity
* @ param [ out ] buf An array of pointers to samples into which data is read ( pointers can be NULL )
* @ param [ out ] si Pointer to an array of \ ref dds_sample_info_t returned for each data value
* @ param [ in ] maxs Maximum number of samples to read
*
* @ returns A dds_return_t with the number of samples read or an error code
*
* @ retval > = 0
* Number of samples read .
* @ retval DDS_RETCODE_ERROR
* An internal error has occurred .
* @ retval DDS_RETCODE_BAD_PARAMETER
* One of the given arguments is not valid .
* @ retval DDS_RETCODE_ILLEGAL_OPERATION
* The operation is invoked on an inappropriate object .
* @ retval DDS_RETCODE_ALREADY_DELETED
* The entity has already been deleted .
*/
DDS_EXPORT dds_return_t
dds_read_wl (
dds_entity_t reader_or_condition ,
void * * buf ,
dds_sample_info_t * si ,
uint32_t maxs ) ;
/**
* @ brief Read the collection of data values and sample info from the data reader , readcondition
* or querycondition based on mask .
*
* When using a readcondition or querycondition , their masks are or ' d with the given mask .
*
* @ param [ in ] reader_or_condition Reader , readcondition or querycondition entity .
* @ param [ out ] buf An array of pointers to samples into which data is read ( pointers can be NULL ) .
* @ param [ out ] si Pointer to an array of \ ref dds_sample_info_t returned for each data value .
* @ param [ in ] bufsz The size of buffer provided .
* @ param [ in ] maxs Maximum number of samples to read .
* @ param [ in ] mask Filter the data based on dds_sample_state_t | dds_view_state_t | dds_instance_state_t .
*
* @ returns A dds_return_t with the number of samples read or an error code .
*
* @ retval > = 0
* Number of samples read .
* @ retval DDS_RETCODE_ERROR
* An internal error has occurred .
* @ retval DDS_RETCODE_BAD_PARAMETER
* One of the given arguments is not valid .
* @ retval DDS_RETCODE_ILLEGAL_OPERATION
* The operation is invoked on an inappropriate object .
* @ retval DDS_RETCODE_ALREADY_DELETED
* The entity has already been deleted .
*/
DDS_EXPORT dds_return_t
dds_read_mask (
dds_entity_t reader_or_condition ,
void * * buf ,
dds_sample_info_t * si ,
size_t bufsz ,
uint32_t maxs ,
uint32_t mask ) ;
/**
* @ brief Access and read loaned samples of data reader , readcondition
* or querycondition based on mask
*
* When using a readcondition or querycondition , their masks are or ' d with the given mask .
*
* 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
*
* @ param [ in ] reader_or_condition Reader , readcondition or querycondition entity .
* @ param [ out ] buf An array of pointers to samples into which data is read ( pointers can be NULL ) .
* @ param [ out ] si Pointer to an array of \ ref dds_sample_info_t returned for each data value .
* @ param [ in ] maxs Maximum number of samples to read .
* @ param [ in ] mask Filter the data based on dds_sample_state_t | dds_view_state_t | dds_instance_state_t .
*
* @ returns A dds_return_t with the number of samples read or an error code .
*
* @ retval > = 0
* Number of samples read .
* @ retval DDS_RETCODE_ERROR
* An internal error has occurred .
* @ retval DDS_RETCODE_BAD_PARAMETER
* One of the given arguments is not valid .
* @ retval DDS_RETCODE_ILLEGAL_OPERATION
* The operation is invoked on an inappropriate object .
* @ retval DDS_RETCODE_ALREADY_DELETED
* The entity has already been deleted .
*/
DDS_EXPORT dds_return_t
dds_read_mask_wl (
dds_entity_t reader_or_condition ,
void * * buf ,
dds_sample_info_t * si ,
uint32_t maxs ,
uint32_t mask ) ;
/**
* @ brief Access and read the collection of data values ( of same type ) and sample info from the
* data reader , readcondition or querycondition , coped by the provided instance handle .
*
* This operation implements the same functionality as dds_read , except that only data scoped to
* the provided instance handle is read .
*
* @ param [ in ] reader_or_condition Reader , readcondition or querycondition entity .
* @ param [ out ] buf An array of pointers to samples into which data is read ( pointers can be NULL ) .
* @ param [ out ] si Pointer to an array of \ ref dds_sample_info_t returned for each data value .
* @ param [ in ] bufsz The size of buffer provided .
* @ param [ in ] maxs Maximum number of samples to read .
* @ param [ in ] handle Instance handle related to the samples to read .
*
* @ returns A dds_return_t with the number of samples read or an error code .
*
* @ retval > = 0
* Number of samples read .
* @ retval DDS_RETCODE_ERROR
* An internal error has occurred .
* @ retval DDS_RETCODE_BAD_PARAMETER
* One of the given arguments is not valid .
* @ retval DDS_RETCODE_ILLEGAL_OPERATION
* The operation is invoked on an inappropriate object .
* @ retval DDS_RETCODE_ALREADY_DELETED
* The entity has already been deleted .
* @ retval DDS_RETCODE_PRECONDITION_NOT_MET
* The instance handle has not been registered with this reader .
*/
DDS_EXPORT dds_return_t
dds_read_instance (
dds_entity_t reader_or_condition ,
void * * buf ,
dds_sample_info_t * si ,
size_t bufsz ,
uint32_t maxs ,
dds_instance_handle_t handle ) ;
/**
* @ brief Access and read loaned samples of data reader , readcondition or querycondition ,
* scoped by the provided instance handle .
*
* This operation implements the same functionality as dds_read_wl , except that only data
* scoped to the provided instance handle is read .
*
* @ param [ in ] reader_or_condition Reader , readcondition or querycondition entity .
* @ param [ out ] buf An array of pointers to samples into which data is read ( pointers can be NULL ) .
* @ param [ out ] si Pointer to an array of \ ref dds_sample_info_t returned for each data value .
* @ param [ in ] maxs Maximum number of samples to read .
* @ param [ in ] handle Instance handle related to the samples to read .
*
* @ returns A dds_return_t with the number of samples read or an error code .
*
* @ retval > = 0
* Number of samples read .
* @ retval DDS_RETCODE_ERROR
* An internal error has occurred .
* @ retval DDS_RETCODE_BAD_PARAMETER
* One of the given arguments is not valid .
* @ retval DDS_RETCODE_ILLEGAL_OPERATION
* The operation is invoked on an inappropriate object .
* @ retval DDS_RETCODE_ALREADY_DELETED
* The entity has already been deleted .
* @ retval DDS_RETCODE_PRECONDITION_NOT_MET
* The instance handle has not been registered with this reader .
*/
DDS_EXPORT dds_return_t
dds_read_instance_wl (
dds_entity_t reader_or_condition ,
void * * buf ,
dds_sample_info_t * si ,
uint32_t maxs ,
dds_instance_handle_t handle ) ;
/**
* @ brief Read the collection of data values and sample info from the data reader , readcondition
* or querycondition based on mask and scoped by the provided instance handle .
*
* This operation implements the same functionality as dds_read_mask , except that only data
* scoped to the provided instance handle is read .
*
* @ param [ in ] reader_or_condition Reader , readcondition or querycondition entity .
* @ param [ out ] buf An array of pointers to samples into which data is read ( pointers can be NULL ) .
* @ param [ out ] si Pointer to an array of \ ref dds_sample_info_t returned for each data value .
* @ param [ in ] bufsz The size of buffer provided .
* @ param [ in ] maxs Maximum number of samples to read .
* @ param [ in ] handle Instance handle related to the samples to read .
* @ param [ in ] mask Filter the data based on dds_sample_state_t | dds_view_state_t | dds_instance_state_t .
*
* @ returns A dds_return_t with the number of samples read or an error code .
*
* @ retval > = 0
* Number of samples read .
* @ retval DDS_RETCODE_ERROR
* An internal error has occurred .
* @ retval DDS_RETCODE_BAD_PARAMETER
* One of the given arguments is not valid .
* @ retval DDS_RETCODE_ILLEGAL_OPERATION
* The operation is invoked on an inappropriate object .
* @ retval DDS_RETCODE_ALREADY_DELETED
* The entity has already been deleted .
* @ retval DDS_RETCODE_PRECONDITION_NOT_MET
* The instance handle has not been registered with this reader .
*/
DDS_EXPORT dds_return_t
dds_read_instance_mask (
dds_entity_t reader_or_condition ,
void * * buf ,
dds_sample_info_t * si ,
size_t bufsz ,
uint32_t maxs ,
dds_instance_handle_t handle ,
uint32_t mask ) ;
/**
* @ brief Access and read loaned samples of data reader , readcondition or
* querycondition based on mask , scoped by the provided instance handle .
*
* This operation implements the same functionality as dds_read_mask_wl , except that
* only data scoped to the provided instance handle is read .
*
* @ param [ in ] reader_or_condition Reader , readcondition or querycondition entity .
* @ param [ out ] buf An array of pointers to samples into which data is read ( pointers can be NULL ) .
* @ param [ out ] si Pointer to an array of \ ref dds_sample_info_t returned for each data value .
* @ param [ in ] maxs Maximum number of samples to read .
* @ param [ in ] handle Instance handle related to the samples to read .
* @ param [ in ] mask Filter the data based on dds_sample_state_t | dds_view_state_t | dds_instance_state_t .
*
* @ returns A dds_return_t with the number of samples read or an error code .
*
* @ retval > = 0
* Number of samples read .
* @ retval DDS_RETCODE_ERROR
* An internal error has occurred .
* @ retval DDS_RETCODE_BAD_PARAMETER
* One of the given arguments is not valid .
* @ retval DDS_RETCODE_ILLEGAL_OPERATION
* The operation is invoked on an inappropriate object .
* @ retval DDS_RETCODE_ALREADY_DELETED
* The entity has already been deleted .
* @ retval DDS_RETCODE_PRECONDITION_NOT_MET
* The instance handle has not been registered with this reader .
*/
DDS_EXPORT dds_return_t
dds_read_instance_mask_wl (
dds_entity_t reader_or_condition ,
void * * buf ,
dds_sample_info_t * si ,
uint32_t maxs ,
dds_instance_handle_t handle ,
uint32_t mask ) ;
/**
* @ brief Access the collection of data values ( of same type ) and sample info from the
* data reader , readcondition or querycondition .
*
* Data value once read is removed from the Data Reader cannot to
* ' read ' or ' taken ' again .
* Return value provides information about number of samples read , which will
* be < = maxs . Based on the count , the buffer will contain data to be read only
* when valid_data bit in sample info structure is set .
* The buffer required for data values , could be allocated explicitly or can
* use the memory from data reader to prevent copy . In the latter case , buffer and
* sample_info should be returned back , once it is no longer using the Data .
*
* @ param [ in ] reader_or_condition Reader , readcondition or querycondition entity .
* @ param [ out ] buf An array of pointers to samples into which data is read ( pointers can be NULL ) .
* @ param [ out ] si Pointer to an array of \ ref dds_sample_info_t returned for each data value .
* @ param [ in ] bufsz The size of buffer provided .
* @ param [ in ] maxs Maximum number of samples to read .
*
* @ returns A dds_return_t with the number of samples read or an error code .
*
* @ retval > = 0
* Number of samples read .
* @ retval DDS_RETCODE_ERROR
* An internal error has occurred .
* @ retval DDS_RETCODE_BAD_PARAMETER
* One of the given arguments is not valid .
* @ retval DDS_RETCODE_ILLEGAL_OPERATION
* The operation is invoked on an inappropriate object .
* @ retval DDS_RETCODE_ALREADY_DELETED
* The entity has already been deleted .
*/
DDS_EXPORT dds_return_t
dds_take (
dds_entity_t reader_or_condition ,
void * * buf ,
dds_sample_info_t * si ,
size_t bufsz ,
uint32_t maxs ) ;
/**
* @ brief Access loaned samples of data reader , readcondition or querycondition .
*
* 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
*
* @ param [ in ] reader_or_condition Reader , readcondition or querycondition entity .
* @ param [ out ] buf An array of pointers to samples into which data is read ( pointers can be NULL ) .
* @ param [ out ] si Pointer to an array of \ ref dds_sample_info_t returned for each data value .
* @ param [ in ] maxs Maximum number of samples to read .
*
* @ returns A dds_return_t with the number of samples read or an error code .
*
* @ retval > = 0
* Number of samples read .
* @ retval DDS_RETCODE_ERROR
* An internal error has occurred .
* @ retval DDS_RETCODE_BAD_PARAMETER
* One of the given arguments is not valid .
* @ retval DDS_RETCODE_ILLEGAL_OPERATION
* The operation is invoked on an inappropriate object .
* @ retval DDS_RETCODE_ALREADY_DELETED
* The entity has already been deleted .
*/
DDS_EXPORT dds_return_t
dds_take_wl (
dds_entity_t reader_or_condition ,
void * * buf ,
dds_sample_info_t * si ,
uint32_t maxs ) ;
/**
* @ brief Take the collection of data values ( of same type ) and sample info from the
* data reader , readcondition or querycondition based on mask
*
* When using a readcondition or querycondition , their masks are or ' d with the given mask .
*
* @ param [ in ] reader_or_condition Reader , readcondition or querycondition entity .
* @ param [ out ] buf An array of pointers to samples into which data is read ( pointers can be NULL ) .
* @ param [ out ] si Pointer to an array of \ ref dds_sample_info_t returned for each data value .
* @ param [ in ] bufsz The size of buffer provided .
* @ param [ in ] maxs Maximum number of samples to read .
* @ param [ in ] mask Filter the data based on dds_sample_state_t | dds_view_state_t | dds_instance_state_t .
*
* @ returns A dds_return_t with the number of samples read or an error code .
*
* @ retval > = 0
* Number of samples read .
* @ retval DDS_RETCODE_ERROR
* An internal error has occurred .
* @ retval DDS_RETCODE_BAD_PARAMETER
* One of the given arguments is not valid .
* @ retval DDS_RETCODE_ILLEGAL_OPERATION
* The operation is invoked on an inappropriate object .
* @ retval DDS_RETCODE_ALREADY_DELETED
* The entity has already been deleted .
*/
DDS_EXPORT dds_return_t
dds_take_mask (
dds_entity_t reader_or_condition ,
void * * buf ,
dds_sample_info_t * si ,
size_t bufsz ,
uint32_t maxs ,
uint32_t mask ) ;
/**
* @ brief Access loaned samples of data reader , readcondition or querycondition based on mask .
*
* When using a readcondition or querycondition , their masks are or ' d with the given mask .
*
* 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
*
* @ param [ in ] reader_or_condition Reader , readcondition or querycondition entity .
* @ param [ out ] buf An array of pointers to samples into which data is read ( pointers can be NULL ) .
* @ param [ out ] si Pointer to an array of \ ref dds_sample_info_t returned for each data value .
* @ param [ in ] maxs Maximum number of samples to read .
* @ param [ in ] mask Filter the data based on dds_sample_state_t | dds_view_state_t | dds_instance_state_t .
*
* @ returns A dds_return_t with the number of samples read or an error code .
*
* @ retval > = 0
* Number of samples read .
* @ retval DDS_RETCODE_ERROR
* An internal error has occurred .
* @ retval DDS_RETCODE_BAD_PARAMETER
* One of the given arguments is not valid .
* @ retval DDS_RETCODE_ILLEGAL_OPERATION
* The operation is invoked on an inappropriate object .
* @ retval DDS_RETCODE_ALREADY_DELETED
* The entity has already been deleted .
*/
DDS_EXPORT dds_return_t
dds_take_mask_wl (
dds_entity_t reader_or_condition ,
void * * buf ,
dds_sample_info_t * si ,
uint32_t maxs ,
uint32_t mask ) ;
2020-04-19 17:38:25 +02:00
# define DDS_HAS_READCDR 1
/**
* @ brief Access the collection of serialized data values ( of same type ) and
* sample info from the data reader , readcondition or querycondition .
*
* This call accesses the serialized data from the data reader , readcondition or
* querycondition and makes it available to the application . The serialized data
* is made available through \ ref ddsi_serdata structures . Returned samples are
* marked as READ .
*
* Return value provides information about the number of samples read , which will
* be < = maxs . Based on the count , the buffer will contain serialized data to be
* read only when valid_data bit in sample info structure is set .
* The buffer required for data values , could be allocated explicitly or can
* use the memory from data reader to prevent copy . In the latter case , buffer and
* sample_info should be returned back , once it is no longer using the data .
*
* @ param [ in ] reader_or_condition Reader , readcondition or querycondition entity .
* @ param [ out ] buf An array of pointers to \ ref ddsi_serdata structures that contain
* the serialized data . The pointers can be NULL .
* @ param [ in ] maxs Maximum number of samples to read .
* @ param [ out ] si Pointer to an array of \ ref dds_sample_info_t returned for each data value .
* @ param [ in ] mask Filter the data based on dds_sample_state_t | dds_view_state_t | dds_instance_state_t .
*
* @ returns A dds_return_t with the number of samples read or an error code .
*
* @ retval > = 0
* Number of samples read .
* @ retval DDS_RETCODE_ERROR
* An internal error has occurred .
* @ retval DDS_RETCODE_BAD_PARAMETER
* One of the given arguments is not valid .
* @ retval DDS_RETCODE_ILLEGAL_OPERATION
* The operation is invoked on an inappropriate object .
* @ retval DDS_RETCODE_ALREADY_DELETED
* The entity has already been deleted .
* @ retval DDS_RETCODE_PRECONDITION_NOT_MET
* The precondition for this operation is not met .
*/
DDS_EXPORT dds_return_t
dds_readcdr (
dds_entity_t reader_or_condition ,
struct ddsi_serdata * * buf ,
uint32_t maxs ,
dds_sample_info_t * si ,
uint32_t mask ) ;
2019-12-12 14:11:05 +01:00
/**
* @ brief Access the collection of serialized data values ( of same type ) and
* sample info from the data reader , readcondition or querycondition .
*
* This call accesses the serialized data from the data reader , readcondition or
* querycondition and makes it available to the application . The serialized data
* is made available through \ ref ddsi_serdata structures . Once read the data is
* removed from the reader and cannot be ' read ' or ' taken ' again .
*
* Return value provides information about the number of samples read , which will
* be < = maxs . Based on the count , the buffer will contain serialized data to be
* read only when valid_data bit in sample info structure is set .
* The buffer required for data values , could be allocated explicitly or can
* use the memory from data reader to prevent copy . In the latter case , buffer and
* sample_info should be returned back , once it is no longer using the data .
*
* @ param [ in ] reader_or_condition Reader , readcondition or querycondition entity .
* @ param [ out ] buf An array of pointers to \ ref ddsi_serdata structures that contain
* the serialized data . The pointers can be NULL .
* @ param [ in ] maxs Maximum number of samples to read .
* @ param [ out ] si Pointer to an array of \ ref dds_sample_info_t returned for each data value .
* @ param [ in ] mask Filter the data based on dds_sample_state_t | dds_view_state_t | dds_instance_state_t .
*
* @ returns A dds_return_t with the number of samples read or an error code .
*
* @ retval > = 0
* Number of samples read .
* @ retval DDS_RETCODE_ERROR
* An internal error has occurred .
* @ retval DDS_RETCODE_BAD_PARAMETER
* One of the given arguments is not valid .
* @ retval DDS_RETCODE_ILLEGAL_OPERATION
* The operation is invoked on an inappropriate object .
* @ retval DDS_RETCODE_ALREADY_DELETED
* The entity has already been deleted .
* @ retval DDS_RETCODE_PRECONDITION_NOT_MET
* The precondition for this operation is not met .
*/
2019-05-23 20:40:51 +02:00
DDS_EXPORT dds_return_t
2019-01-18 14:10:19 +01:00
dds_takecdr (
dds_entity_t reader_or_condition ,
struct ddsi_serdata * * buf ,
uint32_t maxs ,
dds_sample_info_t * si ,
uint32_t mask ) ;
/**
* @ brief Access the collection of data values ( of same type ) and sample info from the
* data reader , readcondition or querycondition but scoped by the given
* instance handle .
*
* This operation mplements the same functionality as dds_take , except that only data
* scoped to the provided instance handle is taken .
*
* @ param [ in ] reader_or_condition Reader , readcondition or querycondition entity .
* @ param [ out ] buf An array of pointers to samples into which data is read ( pointers can be NULL ) .
* @ param [ out ] si Pointer to an array of \ ref dds_sample_info_t returned for each data value .
* @ param [ in ] bufsz The size of buffer provided .
* @ param [ in ] maxs Maximum number of samples to read .
* @ param [ in ] handle Instance handle related to the samples to read .
*
* @ returns A dds_return_t with the number of samples read or an error code .
*
* @ retval > = 0
* Number of samples read .
* @ retval DDS_RETCODE_ERROR
* An internal error has occurred .
* @ retval DDS_RETCODE_BAD_PARAMETER
* One of the given arguments is not valid .
* @ retval DDS_RETCODE_ILLEGAL_OPERATION
* The operation is invoked on an inappropriate object .
* @ retval DDS_RETCODE_ALREADY_DELETED
* The entity has already been deleted .
* @ retval DDS_RETCODE_PRECONDITION_NOT_MET
* The instance handle has not been registered with this reader .
*/
DDS_EXPORT dds_return_t
dds_take_instance (
dds_entity_t reader_or_condition ,
void * * buf ,
dds_sample_info_t * si ,
size_t bufsz ,
uint32_t maxs ,
dds_instance_handle_t handle ) ;
/**
* @ brief Access loaned samples of data reader , readcondition or querycondition ,
* scoped by the given instance handle .
*
* This operation implements the same functionality as dds_take_wl , except that
* only data scoped to the provided instance handle is read .
*
* @ param [ in ] reader_or_condition Reader , readcondition or querycondition entity .
* @ param [ out ] buf An array of pointers to samples into which data is read ( pointers can be NULL ) .
* @ param [ out ] si Pointer to an array of \ ref dds_sample_info_t returned for each data value .
* @ param [ in ] maxs Maximum number of samples to read .
* @ param [ in ] handle Instance handle related to the samples to read .
*
* @ returns A dds_return_t with the number of samples read or an error code .
*
* @ retval > = 0
* Number of samples read .
* @ retval DDS_RETCODE_ERROR
* An internal error has occurred .
* @ retval DDS_RETCODE_BAD_PARAMETER
* One of the given arguments is not valid .
* @ retval DDS_RETCODE_ILLEGAL_OPERATION
* The operation is invoked on an inappropriate object .
* @ retval DDS_RETCODE_ALREADY_DELETED
* The entity has already been deleted .
* @ retval DDS_RETCODE_PRECONDITION_NOT_MET
* The instance handle has not been registered with this reader .
*/
DDS_EXPORT dds_return_t
dds_take_instance_wl (
dds_entity_t reader_or_condition ,
void * * buf ,
dds_sample_info_t * si ,
uint32_t maxs ,
dds_instance_handle_t handle ) ;
/**
* @ brief Take the collection of data values ( of same type ) and sample info from the
* data reader , readcondition or querycondition based on mask and scoped
* by the given instance handle .
*
* This operation implements the same functionality as dds_take_mask , except that only
* data scoped to the provided instance handle is read .
*
* @ param [ in ] reader_or_condition Reader , readcondition or querycondition entity .
* @ param [ out ] buf An array of pointers to samples into which data is read ( pointers can be NULL ) .
* @ param [ out ] si Pointer to an array of \ ref dds_sample_info_t returned for each data value .
* @ param [ in ] bufsz The size of buffer provided .
* @ param [ in ] maxs Maximum number of samples to read .
* @ param [ in ] handle Instance handle related to the samples to read .
* @ param [ in ] mask Filter the data based on dds_sample_state_t | dds_view_state_t | dds_instance_state_t .
*
* @ returns A dds_return_t with the number of samples read or an error code .
*
* @ retval > = 0
* Number of samples read .
* @ retval DDS_RETCODE_ERROR
* An internal error has occurred .
* @ retval DDS_RETCODE_BAD_PARAMETER
* One of the given arguments is not valid .
* @ retval DDS_RETCODE_ILLEGAL_OPERATION
* The operation is invoked on an inappropriate object .
* @ retval DDS_RETCODE_ALREADY_DELETED
* The entity has already been deleted .
* @ retval DDS_RETCODE_PRECONDITION_NOT_MET
* The instance handle has not been registered with this reader .
*/
DDS_EXPORT dds_return_t
dds_take_instance_mask (
dds_entity_t reader_or_condition ,
void * * buf ,
dds_sample_info_t * si ,
size_t bufsz ,
uint32_t maxs ,
dds_instance_handle_t handle ,
uint32_t mask ) ;
/**
* @ brief Access loaned samples of data reader , readcondition or querycondition based
* on mask and scoped by the given intance handle .
*
* This operation implements the same functionality as dds_take_mask_wl , except that
* only data scoped to the provided instance handle is read .
*
* @ param [ in ] reader_or_condition Reader , readcondition or querycondition entity .
* @ param [ out ] buf An array of pointers to samples into which data is read ( pointers can be NULL ) .
* @ param [ out ] si Pointer to an array of \ ref dds_sample_info_t returned for each data value .
* @ param [ in ] maxs Maximum number of samples to read .
* @ param [ in ] handle Instance handle related to the samples to read .
* @ param [ in ] mask Filter the data based on dds_sample_state_t | dds_view_state_t | dds_instance_state_t .
*
* @ returns A dds_return_t with the number of samples or an error code .
*
* @ retval > = 0
* Number of samples read .
* @ retval DDS_RETCODE_ERROR
* An internal error has occurred .
* @ retval DDS_RETCODE_BAD_PARAMETER
* One of the given arguments is not valid .
* @ retval DDS_RETCODE_ILLEGAL_OPERATION
* The operation is invoked on an inappropriate object
* @ retval DDS_RETCODE_ALREADY_DELETED
* The entity has already been deleted .
* @ retval DDS_RETCODE_PRECONDITION_NOT_MET
* The instance handle has not been registered with this reader .
*/
DDS_EXPORT dds_return_t
dds_take_instance_mask_wl (
dds_entity_t reader_or_condition ,
void * * buf ,
dds_sample_info_t * si ,
uint32_t maxs ,
dds_instance_handle_t handle ,
uint32_t mask ) ;
/*
The read / take next functions return a single sample . The returned sample
has a sample state of NOT_READ , a view state of ANY_VIEW_STATE and an
instance state of ANY_INSTANCE_STATE .
*/
/**
* @ brief Read , copy and remove the status set for the entity
*
* This operation copies the next , non - previously accessed
* data value and corresponding sample info and removes from
* the data reader . As an entity , only reader is accepted .
*
* @ param [ in ] reader The reader entity .
* @ param [ out ] buf An array of pointers to samples into which data is read ( pointers can be NULL ) .
* @ param [ out ] si The pointer to \ ref dds_sample_info_t returned for a data value .
*
* @ returns A dds_return_t indicating success or failure .
*
* @ retval DDS_RETCODE_OK
* The operation was successful .
* @ retval DDS_RETCODE_BAD_PARAMETER
* The entity parameter is not a valid parameter .
* @ retval DDS_RETCODE_ILLEGAL_OPERATION
* The operation is invoked on an inappropriate object .
* @ retval DDS_RETCODE_ALREADY_DELETED
* The entity has already been deleted .
*/
DDS_EXPORT dds_return_t
dds_take_next (
dds_entity_t reader ,
void * * buf ,
dds_sample_info_t * si ) ;
/**
* @ brief Read , copy and remove the status set for the entity
*
* This operation copies the next , non - previously accessed
* data value and corresponding sample info and removes from
* the data reader . As an entity , only reader is accepted .
*
* After dds_take_next_wl function is being called and the data has been handled ,
* dds_return_loan function must be called to possibly free memory .
*
* @ param [ in ] reader The reader entity .
* @ param [ out ] buf An array of pointers to samples into which data is read ( pointers can be NULL ) .
* @ param [ out ] si The pointer to \ ref dds_sample_info_t returned for a data value .
*
* @ returns A dds_return_t indicating success or failure .
*
* @ retval DDS_RETCODE_OK
* The operation was successful .
* @ retval DDS_RETCODE_BAD_PARAMETER
* The entity parameter is not a valid parameter .
* @ retval DDS_RETCODE_ILLEGAL_OPERATION
* The operation is invoked on an inappropriate object .
* @ retval DDS_RETCODE_ALREADY_DELETED
* The entity has already been deleted .
*/
DDS_EXPORT dds_return_t
dds_take_next_wl (
dds_entity_t reader ,
void * * buf ,
dds_sample_info_t * si ) ;
/**
* @ brief Read and copy the status set for the entity
*
* This operation copies the next , non - previously accessed
* data value and corresponding sample info . As an entity ,
* only reader is accepted .
*
* @ param [ in ] reader The reader entity .
* @ param [ out ] buf An array of pointers to samples into which data is read ( pointers can be NULL ) .
* @ param [ out ] si The pointer to \ ref dds_sample_info_t returned for a data value .
*
* @ returns A dds_return_t indicating success or failure .
*
* @ retval DDS_RETCODE_OK
* The operation was successful .
* @ retval DDS_RETCODE_BAD_PARAMETER
* The entity parameter is not a valid parameter .
* @ retval DDS_RETCODE_ILLEGAL_OPERATION
* The operation is invoked on an inappropriate object .
* @ retval DDS_RETCODE_ALREADY_DELETED
* The entity has already been deleted .
*/
DDS_EXPORT dds_return_t
dds_read_next (
dds_entity_t reader ,
void * * buf ,
dds_sample_info_t * si ) ;
/**
* @ brief Read and copy the status set for the loaned sample
*
* This operation copies the next , non - previously accessed
* data value and corresponding loaned sample info . As an entity ,
* only reader is accepted .
*
* After dds_read_next_wl function is being called and the data has been handled ,
* dds_return_loan function must be called to possibly free memory .
*
* @ param [ in ] reader The reader entity .
* @ param [ out ] buf An array of pointers to samples into which data is read ( pointers can be NULL ) .
* @ param [ out ] si The pointer to \ ref dds_sample_info_t returned for a data value .
*
* @ returns A dds_return_t indicating success or failure .
*
* @ retval DDS_RETCODE_OK
* The operation was successful .
* @ retval DDS_RETCODE_BAD_PARAMETER
* The entity parameter is not a valid parameter .
* @ retval DDS_RETCODE_ILLEGAL_OPERATION
* The operation is invoked on an inappropriate object .
* @ retval DDS_RETCODE_ALREADY_DELETED
* The entity has already been deleted .
*/
DDS_EXPORT dds_return_t
dds_read_next_wl (
dds_entity_t reader ,
void * * buf ,
dds_sample_info_t * si ) ;
/**
* @ brief Return loaned samples to data - reader or condition associated with a data - reader
*
* Used to release sample buffers returned by a read / take operation . When the application
* provides an empty buffer , memory is allocated and managed by DDS . By calling dds_return_loan ,
* the memory is released so that the buffer can be reused during a successive read / take operation .
* When a condition is provided , the reader to which the condition belongs is looked up .
*
2019-05-23 20:40:51 +02:00
* @ param [ in ] reader_or_condition Reader or condition that belongs to a reader .
2019-01-18 14:10:19 +01:00
* @ param [ in ] buf An array of ( pointers to ) samples .
* @ param [ in ] bufsz The number of ( pointers to ) samples stored in buf .
*
* @ returns A dds_return_t indicating success or failure
*/
/* TODO: Add list of possible return codes */
DDS_EXPORT dds_return_t
dds_return_loan (
dds_entity_t reader_or_condition ,
void * * buf ,
int32_t bufsz ) ;
/*
Instance handle < = > key value mapping .
Functions exactly as read w . r . t . treatment of data
parameter . On output , only key values set .
T x = { . . . } ;
T y ;
dds_instance_handle_t ih ;
ih = dds_lookup_instance ( e , & x ) ;
dds_instance_get_key ( e , ih , & y ) ;
*/
/**
* @ brief This operation takes a sample and returns an instance handle to be used for subsequent operations .
*
* @ param [ in ] entity Reader or Writer entity .
* @ param [ in ] data Sample with a key fields set .
*
* @ returns instance handle or DDS_HANDLE_NIL if instance could not be found from key .
*/
DDS_EXPORT dds_instance_handle_t
dds_lookup_instance ( dds_entity_t entity , const void * data ) ;
DDS_DEPRECATED_EXPORT dds_instance_handle_t
dds_instance_lookup ( dds_entity_t entity , const void * data ) ;
/**
* @ brief This operation takes an instance handle and return a key - value corresponding to it .
*
2019-07-16 13:09:06 +02:00
* @ param [ in ] entity Reader , writer , readcondition or querycondition entity .
2019-01-18 14:10:19 +01:00
* @ param [ in ] inst Instance handle .
* @ param [ out ] data pointer to an instance , to which the key ID corresponding to the instance handle will be
* returned , the sample in the instance should be ignored .
*
* @ returns A dds_return_t indicating success or failure .
*
* @ retval DDS_RETCODE_OK
* The operation was successful .
* @ retval DDS_RETCODE_BAD_PARAMETER
* One of the parameters was invalid or the topic does not exist .
* @ retval DDS_RETCODE_ERROR
* An internal error has occurred .
*/
/* TODO: Check return codes for completeness */
DDS_EXPORT dds_return_t
dds_instance_get_key (
dds_entity_t entity ,
dds_instance_handle_t inst ,
void * data ) ;
/**
* @ brief Begin coherent publishing or begin accessing a coherent set in a subscriber
*
* Invoking on a Writer or Reader behaves as if dds_begin_coherent was invoked on its parent
* Publisher or Subscriber respectively .
*
* @ param [ in ] entity The entity that is prepared for coherent access .
*
* @ returns A dds_return_t indicating success or failure .
*
* @ retval DDS_RETCODE_OK
* The operation was successful .
* @ retval DDS_RETCODE_ERROR
* An internal error has occurred .
* @ retval DDS_RETCODE_BAD_PARAMETER
* The provided entity is invalid or not supported .
*/
DDS_EXPORT dds_return_t
dds_begin_coherent ( dds_entity_t entity ) ;
/**
* @ brief End coherent publishing or end accessing a coherent set in a subscriber
*
* Invoking on a Writer or Reader behaves as if dds_end_coherent was invoked on its parent
* Publisher or Subscriber respectively .
*
* @ param [ in ] entity The entity on which coherent access is finished .
*
* @ returns A dds_return_t indicating success or failure .
*
* @ retval DDS_RETCODE_OK
* The operation was successful .
* @ retval DDS_RETCODE_BAD_PARAMETER
* The provided entity is invalid or not supported .
*/
DDS_EXPORT dds_return_t
dds_end_coherent ( dds_entity_t entity ) ;
/**
* @ brief Trigger DATA_AVAILABLE event on contained readers
*
* The DATA_AVAILABLE event is broadcast to all readers owned by this subscriber that currently
* have new data available . Any on_data_available listener callbacks attached to respective
* readers are invoked .
*
* @ param [ in ] subscriber A valid subscriber handle .
*
* @ returns A dds_return_t indicating success or failure .
*
* @ retval DDS_RETCODE_OK
* The operation was successful .
* @ retval DDS_RETCODE_BAD_PARAMETER
* The provided subscriber is invalid .
*/
DDS_EXPORT dds_return_t
dds_notify_readers ( dds_entity_t subscriber ) ;
/**
* @ brief Checks whether the entity has one of its enabled statuses triggered .
*
* @ param [ in ] entity Entity for which to check for triggered status .
*
* @ returns A dds_return_t indicating success or failure .
*
* @ retval DDS_RETCODE_OK
* The operation was successful .
* @ retval DDS_RETCODE_BAD_PARAMETER
* The entity parameter is not a valid parameter .
* @ retval DDS_RETCODE_ILLEGAL_OPERATION
* The operation is invoked on an inappropriate object .
* @ retval DDS_RETCODE_ALREADY_DELETED
* The entity has already been deleted .
*/
DDS_EXPORT dds_return_t
dds_triggered ( dds_entity_t entity ) ;
/**
* @ brief Get the topic
*
* This operation returns a topic ( handle ) when the function call is done
* with reader , writer , read condition or query condition . For instance , it
* will return the topic when it is used for creating the reader or writer .
* For the conditions , it returns the topic that is used for creating the reader
* which was used to create the condition .
*
* @ param [ in ] entity The entity .
*
* @ returns A dds_return_t indicating success or failure .
*
* @ retval DDS_RETCODE_OK
* The operation was successful .
* @ retval DDS_RETCODE_BAD_PARAMETER
* The entity parameter is not a valid parameter .
* @ retval DDS_RETCODE_ILLEGAL_OPERATION
* The operation is invoked on an inappropriate object .
* @ retval DDS_RETCODE_ALREADY_DELETED
* The entity has already been deleted .
*/
DDS_EXPORT dds_entity_t
dds_get_topic ( dds_entity_t entity ) ;
2019-06-02 21:11:50 +02:00
/**
* @ brief Get instance handles of the data readers matching a writer
*
* This operation fills the provided array with the instance handles
* of the data readers that match the writer . On successful output ,
* the number of entries of " rds " set is the minimum of the return
* value and the value of " nrds " .
*
* @ param [ in ] writer The writer .
* @ param [ in ] rds The array to be filled .
* @ param [ in ] nrds The size of the rds array , at most the first
* nrds entries will be filled . rds = NULL and nrds = 0
* is a valid way of determining the number of matched
* readers , but inefficient compared to relying on the
* matched publication status .
*
* @ returns A dds_return_t indicating the number of matched readers
* or failure . The return value may be larger than nrds
* if there are more matching readers than the array can
* hold .
*
* @ retval > = 0
* The number of matching readers .
* @ retval DDS_RETCODE_BAD_PARAMETER
* The entity parameter is not valid or rds = NULL and
* nrds > 0.
* @ retval DDS_RETCODE_ILLEGAL_OPERATION
* The operation is invoked on an inappropriate object .
*/
DDS_EXPORT dds_return_t
dds_get_matched_subscriptions (
dds_entity_t writer ,
dds_instance_handle_t * rds ,
size_t nrds ) ;
/**
* @ brief Get a description of a reader matched with the provided
* writer
*
* This operation looks up the reader instance handle in the set of
* readers matched with the specified writer , returning a freshly
* allocated sample of the DCPSSubscription built - in topic if found ,
* and NULL if not . The caller is responsible for freeing the
* memory allocated .
*
* This operation is similar to performing a read of the given
* instance handle on a reader of the DCPSSubscription built - in
* topic , but this operation additionally filters on whether the
* reader is matched by the provided writer .
*
* @ param [ in ] writer The writer .
* @ param [ in ] ih The instance handle of a reader .
*
* @ returns A newly allocated sample containing the information on the
* reader , or a NULL pointer for any kind of failure .
*
* @ retval ! = NULL
* The requested data
* @ retval NULL
* The writer is not valid or ih is not an instance handle
* of a matched reader .
*/
DDS_EXPORT dds_builtintopic_endpoint_t *
dds_get_matched_subscription_data (
dds_entity_t writer ,
dds_instance_handle_t ih ) ;
/**
* @ brief Get instance handles of the data writers matching a reader
*
* This operation fills the provided array with the instance handles
* of the data writers that match the reader . On successful output ,
* the number of entries of " wrs " set is the minimum of the return
* value and the value of " nwrs " .
*
* @ param [ in ] reader The reader .
* @ param [ in ] wrs The array to be filled .
* @ param [ in ] nwrs The size of the wrs array , at most the first
* nwrs entries will be filled . wrs = NULL and wrds = 0
* is a valid way of determining the number of matched
* readers , but inefficient compared to relying on the
* matched publication status .
*
* @ returns A dds_return_t indicating the number of matched writers
* or failure . The return value may be larger than nwrs
* if there are more matching writers than the array can
* hold .
*
* @ retval > = 0
* The number of matching writers .
* @ retval DDS_RETCODE_BAD_PARAMETER
* The entity parameter is not valid or wrs = NULL and
* nwrs > 0.
* @ retval DDS_RETCODE_ILLEGAL_OPERATION
* The operation is invoked on an inappropriate object .
*/
DDS_EXPORT dds_return_t
dds_get_matched_publications (
dds_entity_t reader ,
dds_instance_handle_t * wrs ,
size_t nwrs ) ;
/**
* @ brief Get a description of a writer matched with the provided
* reader
*
* This operation looks up the writer instance handle in the set of
* writers matched with the specified reader , returning a freshly
* allocated sample of the DCPSPublication built - in topic if found ,
* and NULL if not . The caller is responsible for freeing the
* memory allocated .
*
* This operation is similar to performing a read of the given
* instance handle on a reader of the DCPSPublication built - in
* topic , but this operation additionally filters on whether the
* writer is matched by the provided reader .
*
* @ param [ in ] reader The reader .
* @ param [ in ] ih The instance handle of a writer .
*
* @ returns A newly allocated sample containing the information on the
* writer , or a NULL pointer for any kind of failure .
*
* @ retval ! = NULL
* The requested data
* @ retval NULL
* The reader is not valid or ih is not an instance handle
* of a matched writer .
*/
DDS_EXPORT dds_builtintopic_endpoint_t *
dds_get_matched_publication_data (
dds_entity_t reader ,
dds_instance_handle_t ih ) ;
2019-10-09 10:28:19 +02:00
/**
* @ brief This operation manually asserts the liveliness of a writer
* or domain participant .
*
* This operation manually asserts the liveliness of a writer
* or domain participant . This is used in combination with the Liveliness
* QoS policy to indicate that the entity remains active . This operation need
* only be used if the liveliness kind in the QoS is either
* DDS_LIVELINESS_MANUAL_BY_PARTICIPANT or DDS_LIVELINESS_MANUAL_BY_TOPIC .
*
* @ param [ in ] entity A domain participant or writer
*
* @ returns A dds_return_t indicating success or failure .
*
* @ retval DDS_RETCODE_OK
* The operation was successful .
* @ retval DDS_RETCODE_ILLEGAL_OPERATION
* The operation is invoked on an inappropriate object .
*/
DDS_EXPORT dds_return_t
dds_assert_liveliness (
dds_entity_t entity ) ;
2020-02-28 16:49:09 +01:00
/**
* @ brief This operation allows making the domain ' s network stack
* temporarily deaf and / or mute . It is a support function for testing and ,
* other special uses and is subject to change .
*
* @ param [ in ] entity A domain entity or an entity bound to a domain , such
* as a participant , reader or writer .
* @ param [ in ] deaf Whether to network stack should pretend to be deaf and
* ignore any incoming packets .
* @ param [ in ] mute Whether to network stack should pretend to be mute and
* discard any outgoing packets where it normally would .
* pass them to the operating system kernel for transmission .
* @ param [ in ] reset_after Any value less than INFINITY will cause it to
* set deaf = mute = false after reset_after ns have passed .
* This is done by an event scheduled for the appropriate
* time and otherwise forgotten . These events are not
* affected by subsequent calls to this function .
*
* @ returns A dds_return_t indicating success or failure .
*
* @ retval DDS_RETCODE_OK
* The operation was successful .
* @ retval DDS_BAD_PARAMETER
* The entity parameter is not a valid parameter .
* @ retval DDS_RETCODE_ILLEGAL_OPERATION
* The operation is invoked on an inappropriate object .
*/
DDS_EXPORT dds_return_t
dds_domain_set_deafmute (
dds_entity_t entity ,
bool deaf ,
bool mute ,
dds_duration_t reset_after ) ;
2019-01-18 14:10:19 +01:00
# if defined (__cplusplus)
}
# endif
# endif /* DDS_H */
