Api documentation and tests

Cyclone DDS API - documentation and tests

Entity creation

Function	Documentation	Return codes	Remarks	Tests
dds_create_participant	unclear documentation on domain_id	missing PRECONDITION_NOT_MET and INCONSISTENT_POLICY	-	participant.c
dds_create_domain	ok	missing OUT_OF_RESOURCES	-	domain.c
dds_create_domain_with_rawconfig	ok	?	-	domain.c
dds_create_topic	ok	?	-	topic.c
dds_create_topic_generic	ok	-	-	tests missing
[deprecated] dds_create_topic_arbitrary	ok	-	replaced by: dds_create_topic_generic	-
dds_create_subscriber	ok	incomplete: dds_entity_lock	-	subscriber.c
dds_create_publisher	ok	incomplete: dds_entity_lock	-	publisher.c
dds_create_reader	ok	incomplete	-	reader.c
dds_create_reader_rhc	add use-case and/or link to create_rhc functions?	incomplete	-	tests missing
dds_create_writer	ok	incomplete	-	writer.c

Entity hierarchy

Function	Documentation	Return codes	Remarks	Tests
dds_get_parent	link to (generic) Listener and status information	missing PRECONDITION_NOT_MET	-	domain.c; entity_hierarchy.c
dds_get_publisher	allowed entity kind not mentioned, and missing link to generic dds entity relations documentation	missing: PRECONDITION_NOT_MET and ILLEGAL_OP	-	entity_hierarchy.c
dds_get_subscriber	see above	?	-	entity_hierarchy.c
dds_get_datareader	see above	?	-	entity_hierarchy.c
dds_get_participant	see above	?	-	entity_hierarchy.c
dds_get_children	see above	?	-	entity_hierarchy.c; entity_api.c
dds_get_mask	missing info on mask (described in dds_create_readcond)	?	-	querycondition.c; readcondition.c
dds_find_topic	n/a	n/a	replaced in topic discovery PR	-
dds_get_topic	ok	missing PRECONDITION_NOT_MET	-	entity_hierarchy.c

QoS

Function	Documentation	Return codes	Remarks	Tests
dds_get_qos, dds_set_qos	link to generic QoS information documentation	missing PRECONDITION_NOT_MET	-	entity_api.c
dds_create_qos, dds_delete_qos, dds_reset_qos, dds_copy_qos, dds_merge_qos, dds_qos_equal	ok	ok	-	qos.c
dds_qset_userdata	missing reference to generic documentation on QoS	ok (void)	-	qos.c; mpt/qos
dds_qset_topicdata	missing reference to generic documentation on QoS	ok (void)	-	qos.c
dds_qset_groupdata	missing reference to generic documentation on QoS	ok (void)	-	qos.c
dds_qset_durability	missing reference to generic documentation on QoS	ok (void)	-	qos.c
dds_qset_history	missing reference to generic documentation on QoS	ok (void)	-	qos.c; whc.c
dds_qset_resource_limits	missing reference to generic documentation on QoS	ok (void)	-	qos.c
dds_qset_presentation	missing reference to generic documentation on QoS	ok (void)	-	qos.c
dds_qset_lifespan	missing reference to generic documentation on QoS	ok (void)	-	qos.c; lifespan.c
dds_qset_deadline	missing reference to generic documentation on QoS	ok (void)	-	qos.c; deadline.c
dds_qset_latency_budget	missing reference to generic documentation on QoS	ok (void)	-	qos.c
dds_qset_ownership	missing reference to generic documentation on QoS	ok (void)	-	qos.c
dds_qset_ownership_strength	missing reference to generic documentation on QoS	ok (void)	-	qos.c
dds_qset_liveliness	missing reference to generic documentation on QoS	ok (void)	-	qos.c; liveliness.c
dds_qset_time_based_filter	missing reference to generic documentation on QoS	ok (void)	-	qos.c
dds_qset_partition	missing reference to generic documentation on QoS	ok (void)	-	qos.c; publisher.c; plist.c
dds_qset_partition1	missing reference to generic documentation on QoS	ok (void)	-	qos.c
dds_qset_reliability	missing reference to generic documentation on QoS	ok (void)	-	qos.c
dds_qset_transport_priority	missing reference to generic documentation on QoS	ok (void)	-	qos.c
dds_qset_destination_order	missing reference to generic documentation on QoS	ok (void)	-	qos.c
dds_qset_writer_data_lifecycle	missing reference to generic documentation on QoS	ok (void)	-	qos.c
dds_qset_reader_data_lifecycle	missing reference to generic documentation on QoS	ok (void)	-	qos.c
dds_qset_durability_service	missing reference to generic documentation on QoS	ok (void)	-	qos.c
dds_qset_ignorelocal	missing reference to generic documentation on QoS	ok (void)	-	qos.c
dds_qset_prop, dds_qunset_prop, dds_qset_bprop, dds_qunset_bprop	missing reference to generic documentation on QoS	ok (void)	-	qos.c
dds_qget_userdata	missing reference to generic documentation on QoS	ok	-	qos.c
dds_qget_topicdata	missing reference to generic documentation on QoS	ok	-	qos.c
dds_qget_groupdata	missing reference to generic documentation on QoS	ok	-	qos.c
dds_qget_durability	missing reference to generic documentation on QoS	ok	-	qos.c
dds_qget_history	missing reference to generic documentation on QoS	ok	-	qos.c; whc.c
dds_qget_resource_limits	missing reference to generic documentation on QoS	ok	-	qos.c
dds_qget_presentation	missing reference to generic documentation on QoS	ok	-	qos.c
dds_qget_lifespan	missing reference to generic documentation on QoS	ok	-	qos.c; lifespan.c
dds_qget_deadline	missing reference to generic documentation on QoS	ok	-	qos.c; deadline.c
dds_qget_latency_budget	missing reference to generic documentation on QoS	ok	-	qos.c
dds_qget_ownership	missing reference to generic documentation on QoS	ok	-	qos.c
dds_qget_ownership_strength	missing reference to generic documentation on QoS	ok	-	qos.c
dds_qget_liveliness	missing reference to generic documentation on QoS	ok	-	qos.c; liveliness.c
dds_qget_time_based_filter	missing reference to generic documentation on QoS	ok	-	qos.c
dds_qget_partition	missing reference to generic documentation on QoS	ok	-	qos.c; publisher.c; plist.c
dds_qget_reliability	missing reference to generic documentation on QoS	ok	-	qos.c
dds_qget_transport_priority	missing reference to generic documentation on QoS	ok	-	qos.c
dds_qget_destination_order	missing reference to generic documentation on QoS	ok	-	qos.c
dds_qget_writer_data_lifecycle	missing reference to generic documentation on QoS	ok	-	qos.c
dds_qget_reader_data_lifecycle	missing reference to generic documentation on QoS	ok	-	qos.c
dds_qget_durability_service	missing reference to generic documentation on QoS	ok	-	qos.c
dds_qget_ignorelocal	missing reference to generic documentation on QoS	ok	-	qos.c
dds_qget_propnames	missing reference to generic documentation on QoS	ok	-	qos.c
dds_qget_prop	missing reference to generic documentation on QoS	ok	-	qos.c
dds_qget_bpropnames	missing reference to generic documentation on QoS	ok	-	qos.c
dds_qget_bprop	missing reference to generic documentation on QoS	ok	-	qos.c

Topic filter

Function	Documentation	Return codes	Remarks	Tests
[deprecated] dds_set_topic_filter	n/a	n/a	-
[deprecated] dds_topic_set_filter	n/a	n/a	-
dds_set_topic_filter_and_arg	-	-	to be replaced	-
dds_set_topic_filter_extended	-	-	to be replaced	-
[deprecated] dds_get_topic_filter	n/a	n/a	-
[deprecated] dds_topic_get_filter	n/a	n/a	-
dds_get_topic_filter_and_arg	-	-	to be replaced	-
dds_get_topic_filter_extended	-	-	to be replaced	-

Instances

Function	Documentation	Return codes	Remarks	Tests
dds_register_instance	limited description of data parameter (how is this parameter used?), link to generic documentation on instances	missing PRECONDITION_NOT_MET (from handle_pin)	-	register.c
dds_lookup_instance	ok	missing	-	not explicitly tests, but some coverage in other tests
[deprecated] dds_instance_lookup	n/a	n/a	replaced by: dds_lookup_instance	-
dds_instance_get_key	link to generic data (sample) doc	missing ILLEGAL_OPERATION and PRECONDITION_NOT_MET	-	instance_get_key.c
dds_unregister_instance, dds_unregister_instance_ih, dds_unregister_instance_ts, dds_unregister_instance_ih_ts	see dds_register_instance	missing PRECONDITION_NOT_MET	-	unregister.c
dds_writedispose, dds_writedispose_ts	see dds_register_instance remark on data parameter	-	-	dispose.c
dds_dispose , dds_dispose_ts , dds_dispose_ih, dds_dispose_ih_ts	ok	missing PRECONDITION_NOT_MET	-	dispose.c

Write

Function	Documentation	Return codes	Remarks	Tests
dds_write	needs a better description, e.g. of the data parameter and wrt source timestamp	missing	-	write.c
dds_write_flush	documentation missing, is this function still needed	missing	-	tests missing
dds_writecdr	link to docs on creating a serdata object	missing PRECONDITION_NOT_MET	-	cdr.c
dds_write_ts	see dds_write	missing	-	write.c
dds_write_set_batch	ok	missing	in dds_public_impl.h	tests missing, used in ddsperf/pubsub

Conditions

Function	Documentation	Return codes	Remarks	Tests
dds_create_readcondition	ok	?	-	readcondition.c
dds_create_querycondition	explain the filter (aka expression & parameters) of the (to be implemented) new querycondition implementation; update parameters when new querycondition is introduced	?	-	querycondition.c
dds_create_guardcondition	description is not clear	?		guardcondition.c
dds_set_guardcondition	ok	?	-	guardcondition.c
dds_read_guardcondition	ok	?	-	guardcondition.c
dds_take_guardcondition	ok	?	-	guardcondition.c

Waitset

Function	Documentation	Return codes	Remarks	Tests
dds_create_waitset	ok	?	-	waitset.c
dds_waitset_get_entities	ok	?	-	waitset.c
dds_waitset_attach	ok	?	-	waitset.c
dds_waitset_detach	ok	?	-	waitset.c
dds_waitset_set_trigger	ok	?	-	waitset.c
dds_waitset_wait	ok	?	-	waitset.c
dds_waitset_wait_until	ok	?	-	waitset.c

Read/take

Function	Documentation	Return codes	Remarks	Tests
dds_read	unclear description: valid_data wrt values written to buffer, buffer null values for loaned samples, bufsz vs maxs (mention dds_read_wl), text 'data values (of same type)'	ok	-	reader.c
dds_read_wl	refer to dds_read, identical operation with null ptrs in buffer	ok	-	reader.c
dds_read_mask	see dds_read	ok		reader.c
dds_read_mask_wl	see dds_read	ok		reader.c
dds_read_instance, dds_read_instance_wl, dds_read_instance_mask, dds_read_instance_mask_wl	link to docs on instance handles	ok	-	read_instance.c
dds_take	same issues as dds_read and unclear description of take vs read	ok	-	reader.c
dds_take_wl	mention difference with regular dds_take	ok	-	reader.c
dds_take_mask	see dds_take	ok	-	reader.c
dds_take_mask_wl	see dds_take	ok	-	reader.c
dds_readcdr	same issues as dds_read	ok	-	_tests missing _
dds_takecdr	same issues as dds_read	ok	-	cdr.c
dds_take_instance, dds_take_instance_wl, dds_take_instance_mask, dds_take_instance_mask_wl	link to docs on instance handles	ok	-	take_instance.c
dds_take_next, , dds_take_next_wl , dds_read_next dds_read_next_wl	describe definition of 'next' wrt multiple instances?	missing PRECONDITION_NOT_MET	-	reader_iterator.c
dds_return_loan	ok	incomplete	-	loan.c

Memory allocation and string functions

Function	Documentation	Return codes	Remarks	Tests
dds_alloc, dds_realloc, dds_realloc_zero, dds_free	docs missing (add a reference to stdlib manual)	-	-	_tests missing _
dds_string_alloc, dds_string_dup, dds_string_free, dds_sample_free	missing	-	-	_tests missing _

Listener

Function	Documentation	Return codes	Remarks	Tests
dds_get_listener, dds_set_listener	link to (generic) Listener and status information	missing PRECONDITION_NOT_MET	-	entity_api.c
dds_create_listener	ok	ok	-	listener.c
dds_delete_listener, dds_reset_listener, dds_copy_listener, dds_merge_listener	ok	ok (void)	-	listener.c
dds_lset_, dds_lget_	ok	ok (void)	-	listener.c

Status

Function	Documentation	Return codes	Remarks	Tests
dds_read_status, dds_take_status, dds_get_status_changes, dds_get_status_mask, dds_set_status_mask	limited info on status: refer to a section in DDS spec	?	-	entity_status.c
[deprecated] dds_get_enabled_status	n/a	n/a	replaced by: dds_get_status_mask	-
[deprecated] dds_set_enabled_status	n/a	n/a	replaced by: dds_set_status_mask	-
dds_get_inconsistent_topic_status, dds_get_publication_matched_status, dds_get_liveliness_lost_status, dds_get_offered_deadline_missed_status, dds_get_offered_incompatible_qos_status, dds_get_subscription_matched_status, dds_get_liveliness_changed_status, dds_get_sample_rejected_status, dds_get_sample_lost_status, dds_get_requested_deadline_missed_status, dds_get_requested_incompatible_qos_status	missing reference to generic documentation on statusses	?	-	entity_status.c

Other functions

Function	Documentation	Return codes	Remarks	Tests
dds_enable	ok	incomplete	delayed entity enabling not implemented (open PR)	-
dds_delete	error handling not well described	?	-	entity_hierarchy.c
dds_get_instance_handle	missing info on instance handles	incomplete	-	entity_api.c
dds_get_guid	missing info on entity GUIDs	incomplete	?	entity_api.c
dds_get_domainid	mention internal/external domain id	?	-	domain.c; entity_hierarchy.c
dds_lookup_participant	ok	?	-	participant.c
dds_get_name	ok	incomplete (dds_entity_pin and BAD_PARAM missing)	-	topic.c
dds_get_type_name	ok	incomplete (dds_entity_pin and BAD_PARAM missing)	-	topic.c
dds_suspend, dds_resume	unclear text: .. collecting modifications to DDS writers ..	?	-	publisher.c
dds_wait_for_acks	what happens with new matched during waiting for acks?	?	-	publisher.c
dds_reader_wait_for_historical_data	missing definition of 'historical data'	incomplete	-	tests missing
dds_notify_readers	what is the use case for this function?	?	unsupported	-
dds_triggered	ok	?		entity_status.c
dds_get_matched_subscriptions	ok	?	-	_tests missing _
dds_get_matched_subscription_data	ok	?	-	_tests missing _
dds_get_matched_publications	ok	?		_tests missing _
dds_get_matched_publication_data	ok	?	-	_tests missing _
dds_assert_liveliness	ok	dds_entity_pin retcodes missing	-	liveliness.c
dds_domain_set_deafmute	ok	?	-	_tests missing _
dds_begin_coherent	n/a	n/a	unsupported	n/a
dds_end_coherent	n/a	n/a	unsupported	n/a

Semi-public API

Function	Documentation	Return codes	Remarks	Tests
dds_rhc_*	docs missing	?	-	rhc_torture test
dds_*_statistics	ok	?	used in ddsperf	_tests missing _
dds_reader_lock_samples	ok	?	used in the C++ api
dds_set_log_mask	docs missing	?	used in RMW	log.c
ddsi_serdata_init, ddsi_serdata_ref, ddsi_serdata_unref	docs missing	?	used in RMW	no specific tests, but covered in other tests (e.g. cdr.c)
ddsi_sertopic_init, ddsi_sertopic_unref, ddsi_sertopic_compute_serdata_basehash	docs missing	?	used in RMW	no specific tests, but covered in other tests
ddsi_iid_gen	docs missing	?	used in RMW	no specific tests, but covered in other tests