The RDR API structure for version 20191120. More...

#include "rdrapi.h"

Data Fields
HqBool	valid
	Is this API initialized?

sw_rdr_result(*	register_rdr )(sw_rdr_class, sw_rdr_type, sw_rdr_id, void *, size_t, sw_rdr_priority)
	Register an RDR. More...

sw_rdr_result(*	register_id )(sw_rdr_class, sw_rdr_type, sw_rdr_id , void , size_t, sw_rdr_priority)
	Register an RDR and allocate it a unique ID. More...

sw_rdr_result(*	deregister )(sw_rdr_class, sw_rdr_type, sw_rdr_id, void *, size_t)
	Deregister an RDR. More...

sw_rdr_result(*	find )(sw_rdr_class, sw_rdr_type, sw_rdr_id, void *, size_t )
	Find an RDR given the Class, Type and ID. More...

sw_rdr_iterator (	find_type )(sw_rdr_class, sw_rdr_type)
	Find all RDRs of a specified Class and Type. More...

sw_rdr_result(*	find_named )(sw_rdr_namespace rdrspace, const char name, size_t namelen, sw_rdr_id rdrid, void pptr, size_t plength)
	Find a named RDR given the Namespace, Name, and ID. More...

sw_rdr_iterator (	find_named_name )(sw_rdr_namespace rdrspace, const char *name, size_t namelen)
	Find all Named RDRs of a specified Namespace and Name. More...

sw_rdr_result(*	next )(sw_rdr_iterator , sw_rdr_class , sw_rdr_type , sw_rdr_id , void *, size_t )
	Find an RDR by iteration. More...

sw_rdr_result(*	found )(sw_rdr_iterator *)
	Destroy an RDR iterator. More...

sw_rdr_result(*	restart )(sw_rdr_iterator *)
	Restart an RDR iterator. More...

sw_rdr_result(*	lock_next )(sw_rdr_iterator , sw_rdr_class , sw_rdr_type , sw_rdr_id , void *, size_t )
	Find an RDR by iteration and lock it to prevent deregistration. More...

sw_rdr_result(*	register_named )(sw_rdr_namespace rdrspace, const char name, size_t namelen, sw_rdr_id rdrid, void ptr, size_t length, sw_rdr_priority priority)
	Register a Named RDR. More...

sw_rdr_result(*	register_named_id )(sw_rdr_namespace rdrspace, const char name, size_t namelen, sw_rdr_id prdrid, void *ptr, size_t length, sw_rdr_priority priority)
	Register a Named RDR and allocate it a unique ID. More...

sw_rdr_result(*	deregister_named )(sw_rdr_namespace rdrspace, const char name, size_t namelen, sw_rdr_id rdrid, void ptr, size_t length)
	Deregister a Named RDR. More...

Detailed Description

The RDR API structure for version 20191120.

Field Documentation

◆ deregister

sw_rdr_result( * sw_rdr_api_20191120::deregister) (sw_rdr_class, sw_rdr_type, sw_rdr_id, void *, size_t)

Deregister an RDR.

This call deregisters an RDR of a particular Class, Type and ID. Any previously registered RDR of that Class, Type and ID will reappear.

Parameters

[in]	rdrclass	The Class of the RDR when registered.
[in]	rdrtype	The Type of the RDR when registered.
[in]	rdrid	The ID of the RDR within this Class and Type. If an ID was automatically allocated, it must be supplied to deregister the RDR.
[in]	ptr	A pointer to the start of the data. This must be the originally registered pointer.
[in]	length	The length of the data. This must be the originally registered length.

Return values

SW_RDR_SUCCESS	if the RDR was deregistered.
SW_RDR_ERROR_UNKNOWN	is returned if the RDR could not be found.
SW_RDR_ERROR_IN_USE	if the RDR is locked. This is informational - the RDR has been deregistered and cannot be found again. It will be discarded only when there are no remaining locks on it. It is not safe to dispose of the RDR contents if this error is returned, see below.

All parameters MUST match those specified during registration for the RDR to be deregistered.

Note that this prevents (or at least changes) discovery of a particular RDR - it does not withdraw access rights from Consumers that have already found the RDR - that must be achieved by some additional protocol such as an Event or Timeline.

If the RDR has been locked by SwLockNextRDR(), it is deregistered but SW_RDR_ERROR_IN_USE is returned. This call can be repeated and will continue to return SW_RDR_ERROR_IN_USE for as long as the RDR is locked. Once unlocked it will automatically be discarded and this call will return SW_RDR_ERROR_UNKNOWN. See SwLockNextRDR() for more details of RDR locking.

Important: If the RDR refers to something that is to be discarded after deregistration it must NOT be discarded until SwDeregisterRDR() returns something other than SW_RDR_ERROR_IN_USE.

◆ deregister_named

sw_rdr_result( * sw_rdr_api_20191120::deregister_named) (sw_rdr_namespace rdrspace, const char *name, size_t namelen, sw_rdr_id rdrid, void *ptr, size_t length)

Deregister a Named RDR.

This call deregisters a Named RDR of a particular Namespace, Name and ID. Any previously registered RDR of that Namespace, Name and ID will reappear.

Parameters

[in]	rdrspace	The Namespace of the RDR when registered.
[in]	name	The Name of the RDR within this Namespace.
[in]	namelen	The length of the RDR name.
[in]	rdrid	The ID of the Named RDR within this Namespace and Name. If an ID was automatically allocated, it must be supplied to deregister the RDR.
[in]	ptr	A pointer to the start of the data. This must be the originally registered pointer.
[in]	length	The length of the data. This must be the originally registered length.

Return values

SW_RDR_SUCCESS	if the RDR was deregistered.
SW_RDR_ERROR_UNKNOWN	is returned if the RDR could not be found.
SW_RDR_ERROR_IN_USE	if the RDR is locked. This is informational - the RDR has been deregistered and cannot be found again. It will be discarded only when there are no remaining locks on it. It is not safe to dispose of the RDR contents if this error is returned, see below.

All parameters MUST match those specified during registration for the RDR to be deregistered.

Note that this prevents (or at least changes) discovery of a particular RDR - it does not withdraw access rights from Consumers that have already found the RDR - that must be achieved by some additional protocol such as an Event or Timeline.

If the RDR has been locked by SwLockNextRDR(), it is deregistered but SW_RDR_ERROR_IN_USE is returned. This call can be repeated and will continue to return SW_RDR_ERROR_IN_USE for as long as the RDR is locked. Once unlocked it will automatically be discarded and this call will return SW_RDR_ERROR_UNKNOWN. See SwLockNextRDR() for more details of RDR locking.

Important: If the RDR refers to something that is to be discarded after deregistration it must NOT be discarded until SwDeregisterNamedRDR() returns something other than SW_RDR_ERROR_IN_USE.

When the last RDR using a particular name is deregistered from a namespace, the name is removed from the iterable names in the namespace.

◆ find

sw_rdr_result( * sw_rdr_api_20191120::find) (sw_rdr_class, sw_rdr_type, sw_rdr_id, void **, size_t *)

Find an RDR given the Class, Type and ID.

This call allows the consumer to find a specific RDR.

Parameters

[in]	rdrclass	The Class of the RDR.
[in]	rdrtype	The Type of the RDR.
[in]	rdrid	The ID of the RDR.
[out]	pptr	A pointer to a pointer. If not NULL, this will be filled in with the pointer if the RDR is found.
[out]	plength	A pointer to a length. If not NULL, this will be filled in with the length if the RDR is found.

Return values

SW_RDR_SUCCESS	if the RDR was found;
SW_RDR_ERROR_UNKNOWN	is returned if no RDR of the specified Class, Type and ID was found.

eg:

result = SwFindRDR(myclass, mytype, myid, &ptr, &len);
if (result == SW_RDR_SUCCESS) {
  ...
}

◆ find_named

sw_rdr_result( * sw_rdr_api_20191120::find_named) (sw_rdr_namespace rdrspace, const char *name, size_t namelen, sw_rdr_id rdrid, void **pptr, size_t *plength)

Find a named RDR given the Namespace, Name, and ID.

Parameters

[in]	rdrspace	The Namespace of the RDR.
[in]	name	The Name of the RDR within this Namespace.
[in]	namelen	The length of the RDR name.
[in]	rdrid	The ID of the RDR.
[out]	pptr	A pointer to a pointer. If not NULL, this will be filled in with the pointer if the RDR is found.
[out]	plength	A pointer to a length. If not NULL, this will be filled in with the length if the RDR is found.

Return values

SW_RDR_SUCCESS	if the RDR was found;
SW_RDR_ERROR_UNKNOWN	is returned if no named RDR with the specified Namespace, Name, and ID was found.

eg:

result = SwFindNamedRDR(mynamespace, CSTRING_AND_LENGTH("MyName"), myid, &ptr, &len);
if (result == SW_RDR_SUCCESS) {
  ...
}

◆ find_named_name

sw_rdr_iterator*( * sw_rdr_api_20191120::find_named_name) (sw_rdr_namespace rdrspace, const char *name, size_t namelen)

Find all Named RDRs of a specified Namespace and Name.

This call begins an iteration to find all RDRs of a specific typa and name.

Parameters

[in]	rdrspace	The Namespace of the RDR.
[in]	name	The Name of the RDR within this Namespace.
[in]	namelen	The length of the RDR name.

Returns: A pointer to a sw_rdr_iterator or NULL. If NULL, there was insufficient memory to create the iterator. Otherwise, this is passed (multiple times) to SwNextRDR(), and ultimately must be destroyed by calling SwFoundRDR().

It is permissible to create the iterator long in advance of calling SwNextRDR() to avoid the possibility of failing due to insufficient memory. Iterators can be restarted using SwRestartFindRDR() and hence multiple searches can be performed using the same iterator without having to call SwFoundRDR() and SwFindRDRbyName() again. e.g.,

iterator = SwFindNamedRDRbyName(mynamespace, CSTRING_AND_LENGTH("MyName"));
if (iterator) {
  while (SwNextRDR(iterator, 0, 0, &id, &ptr, &len) == SW_RDR_SUCCESS) {
    ...
  }
  SwFoundRDR(iterator);
}

When calling SwNextRDR(), the namespace will be reported through that function's Type output pointer.

◆ find_type

sw_rdr_iterator*( * sw_rdr_api_20191120::find_type) (sw_rdr_class, sw_rdr_type)

Find all RDRs of a specified Class and Type.

This call begins an iteration to find all RDRs of a specific type.

Parameters

[in]	rdrclass	The Class of the RDR.
[in]	rdrtype	The Type of the RDR.

Returns: A pointer to a sw_rdr_iterator or NULL. If NULL, there was insufficient memory to create the iterator. Otherwise, this is passed (multiple times) to SwNextRDR(), and ultimately must be destroyed by calling SwFoundRDR().

It is permissible to create the iterator long in advance of calling SwNextRDR() to avoid the possibility of failing due to insufficient memory. Iterators can be restarted using SwRestartFindRDR() and hence multiple searches can be performed using the same iterator without having to call SwFoundRDR() and SwFindRDRbyType() again. e.g.,

iterator = SwFindRDRbyType(myclass, mytype);
if (iterator) {
  while (SwNextRDR(iterator, 0, 0, &id, &ptr, &len) == SW_RDR_SUCCESS) {
    ...
  }
  SwFoundRDR(iterator);
}

◆ found

sw_rdr_result( * sw_rdr_api_20191120::found) (sw_rdr_iterator *)

Destroy an RDR iterator.

This call ends an iteration to find RDRs.

Parameters

[in] iterator The iterator to destroy. Passing in a NULL iterator is pointless but safe.

Return values

SW_RDR_SUCCESS	normally;
SW_RDR_ERROR_IN_USE	if the iterator cannot be destroyed because it is threaded;
SW_RDR_ERROR_SYNTAX	if the iterator is not recognised.

This automatically unlocks the RDR returned by a call to SwLockNextRDR().

◆ lock_next

sw_rdr_result( * sw_rdr_api_20191120::lock_next) (sw_rdr_iterator *, sw_rdr_class *, sw_rdr_type *, sw_rdr_id *, void **, size_t *)

Find an RDR by iteration and lock it to prevent deregistration.

All parameters and behavour as SwNextRDR(), except the returned RDR is locked and can not be deregistered. It is unlocked automatically when the iterator is next passed to SwNextRDR(), SwLockNextRDR(), SwFoundRDR() or SwRestartFindRDR().

If SwDeregisterRDR() or SwDeregisterNamedRDR() are called on a locked RDR it is deregistered at once to prevent further discovery but is only discarded once fully unlocked. Note that multiple seperate find operations could have locked the RDR many times, and all must unlock before the RDR is finally discarded.

Important: If the RDR refers to something that is to be discarded after deregistration it must NOT be discarded until SwDeregisterRDR() or SwDeregisterNamedRDR() returned something other than SW_RDR_ERROR_IN_USE.

◆ next

sw_rdr_result( * sw_rdr_api_20191120::next) (sw_rdr_iterator *, sw_rdr_class *, sw_rdr_type *, sw_rdr_id *, void **, size_t *)

Find an RDR by iteration.

This call returns an RDR from the given iterator.

Parameters

[in]	iterator	The sw_rdr_iterator created by SwFindRDR*().
[out]	pclass	Optional pointer to an RDR class. If not NULL, this will be filled in with the class of the found RDR. If iterating named RDRs, the class will be RDR_CLASS_RDR.
[out]	ptype	Optional pointer to an RDR type. If not NULL, this will be filled in with the type of the found RDR. If iterating named RDRs, the namespace will be returned through this pointer.
[out]	pid	Optional pointer to an RDR id. If not NULL, this will be filled in with the Id of the found RDR.
[out]	pptr	Pointer to a pointer. If not NULL, this will be filled in with the ptr of the found RDR.
[out]	plength	Pointer to a length. If not NULL, this will be filled in with the length of the found RDR.

Return values

SW_RDR_SUCCESS	if an RDR was found;
SW_RDR_ERROR_UNKNOWN	if no further RDRs match;
SW_RDR_ERROR_SYNTAX	if the iterator is invalid.

Once the iteration is finished, the iterator must be destroyed by calling SwFoundRDR(), or reset using SwRestartFindRDR() if the iterator is to persist or be reused immediately.

Note that in a multithreaded system it is possible for an RDR to be deregistered after this call has returned but before the caller tries to use it. See SwLockNextRDR().

◆ register_id

sw_rdr_result( * sw_rdr_api_20191120::register_id) (sw_rdr_class, sw_rdr_type, sw_rdr_id *, void *, size_t, sw_rdr_priority)

Register an RDR and allocate it a unique ID.

This call registers an RDR as above, but also allocates it a new ID which has not been used within that Class and Type.

Parameters

[in]	rdrclass	The Class of the RDR.
[in]	rdrtype	The Type of the RDR.
[out]	prdrid	A pointer to an RDR ID, or NULL. An unused ID (within this Class and Type) will be allocated and returned if this pointer is not NULL. If no pointer is provided, an ID is still allocated but is not returned to the provider, so the RDR cannot be deregistered.
[in]	ptr	A pointer to the start of the data.
[in]	length	The length of the data.
[in]	priority	The priority of the registration - usually zero.

Return values

SW_RDR_SUCCESS	if the RDR was successfully registered.
SW_RDR_ERROR	is returned in the unlikely event of every ID already having been allocated.

Returns: One of the RDR_RESULT codes or an error greater than MON_CLASS_ERROR for a specific error.

◆ register_named

sw_rdr_result( * sw_rdr_api_20191120::register_named) (sw_rdr_namespace rdrspace, const char *name, size_t namelen, sw_rdr_id rdrid, void *ptr, size_t length, sw_rdr_priority priority)

Register a Named RDR.

This call registers an RDR of a particular Namespace, Name, and ID.

Parameters

[in]	rdrspace	The Namespace of the Named RDR. Named RDRs are subdivided into Namespaces, which are enumerated elsewhere.
[in]	name	The Name of the RDR within this Namespace.
[in]	namelen	The length of the RDR name.
[in]	rdrid	The ID of the RDR within this Namespace and Name.
[in]	ptr	A pointer to the start of the data. This pointer can be NULL. See below for special behaviour if length is also zero.
[in]	length	The length of the data. This length can be zero. If ptr is NOT NULL then this delivers a zero-length RDR. This may still be meaningful to the consumer. If the length is zero AND the ptr is NULL (and this RDR is the highest priority registration), then any existing RDR of this Namespace, Name, and ID is suppressed and therefore appears to the consumer to be unregistered. Deregistering this RDR will cause the previous registration to reappear.
[in]	priority	The priority of the registration - usually zero. Known defaults can be registered with a negative priority such as SW_RDR_DEFAULT. This ensures they are placed below any existing definition of the same Namespace:Name:ID combination (with a higher priority) - as though the default registration occured first. Similarly, a positive priority such as SW_RDR_OVERRIDE will remain the definitive registration until a registration at the same or higher priority is made.

Returns: SW_RDR_SUCCESS if the RDR was successfully registered. One of the RDR_RESULT codes otherwise.

Reregistering an existing RDR (with the same parameters including ptr and length) does not produce multiple RDRs - it simply ensures that this RDR definition supersedes any of the same priority.

If there are any named RDRs registered in a namespace, the names in it can be iterated by using SwFindRDRbyType(), using Class RDR_CLASS_RDR and the namespace as the iteration Type.

◆ register_named_id

sw_rdr_result( * sw_rdr_api_20191120::register_named_id) (sw_rdr_namespace rdrspace, const char *name, size_t namelen, sw_rdr_id *prdrid, void *ptr, size_t length, sw_rdr_priority priority)

Register a Named RDR and allocate it a unique ID.

This call registers an RDR as above, but also allocates it a new ID which has not been used within that Namespace and Name.

Parameters

[in]	rdrspace	The Namespace of the RDR.
[in]	name	The Name of the RDR within this Namespace.
[in]	namelen	The length of the RDR name.
[out]	prdrid	A pointer to an RDR ID, or NULL. An unused ID (within this Namespace and Name) will be allocated and returned if this pointer is not NULL. If no pointer is provided, an ID is still allocated but is not returned to the provider, so the RDR cannot be deregistered.
[in]	ptr	A pointer to the start of the data.
[in]	length	The length of the data.
[in]	priority	The priority of the registration - usually zero.

Return values

SW_RDR_SUCCESS	if the RDR was successfully registered.
SW_RDR_ERROR	is returned in the unlikely event of every ID already having been allocated.

◆ register_rdr

sw_rdr_result( * sw_rdr_api_20191120::register_rdr) (sw_rdr_class, sw_rdr_type, sw_rdr_id, void *, size_t, sw_rdr_priority)

Register an RDR.

This call registers an RDR of a particular Class, Type and ID.

Parameters

[in]	rdrclass	The Class of the RDR, as enumerated above.
[in]	rdrtype	The Type of the RDR. RDR Classes are subdivided into Types, which are enumerated elsewhere.
[in]	rdrid	The ID of the RDR within this Class and Type.
[in]	ptr	A pointer to the start of the data. This pointer can be NULL. See below for special behaviour if length is also zero.
[in]	length	The length of the data. This length can be zero. If ptr is NOT NULL then this delivers a zero-length RDR. This may still be meaningful to the consumer. If the length is zero AND the ptr is NULL (and this RDR is the highest priority registration), then any existing RDR of this Class, Type and ID is suppressed and therefore appears to the consumer to be unregistered. Deregistering this RDR will cause the previous registration to reappear.
[in]	priority	The priority of the registration - usually zero. Known defaults can be registered with a negative priority such as SW_RDR_DEFAULT. This ensures they are placed below any existing definition of the same Class:Type:ID combination (with a higher priority) - as though the default registration occured first. Similarly, a positive priority such as SW_RDR_OVERRIDE will remain the definitive registration until a registration at the same or higher priority is made.

Returns: SW_RDR_SUCCESS if the RDR was successfully registered. One of the RDR_RESULT codes or an error greater than MON_CLASS_ERROR otherwise.

Reregistering an existing RDR (with the same parameters including ptr and length) does not produce multiple RDRs - it simply ensures that this RDR definition supersedes any of the same priority.

◆ restart

sw_rdr_result( * sw_rdr_api_20191120::restart) (sw_rdr_iterator *)

Restart an RDR iterator.

This call restarts the find process by returning the iterator to its initial state. It can be called instead of SwFoundRDR() to reuse a persistent iterator. Note that ultimately it is still necessary to call SwFoundRDR() to destroy the iterator. It can be called before SwNextRDR() has exhausted its results.

Parameters

[in] iterator The iterator to restart.

Return values

SW_RDR_SUCCESS	normally;
SW_RDR_ERROR_IN_USE	if the iterator cannot be restarted because it is threaded;
SW_RDR_ERROR_SYNTAX	if the iterator is not recognised.

This automatically unlocks the RDR returned by a call to SwLockNextRDR().

The documentation for this struct was generated from the following file:

lib/interface/rdrapi.h

Data Fields

Detailed Description

Field Documentation

◆ deregister

◆ deregister_named

◆ find

◆ find_named

◆ find_named_name

◆ find_type

◆ found

◆ lock_next

◆ next

◆ register_id

◆ register_named

◆ register_named_id

◆ register_rdr

◆ restart