Harlequin RIP SDK
sw_rdr_api_20191120 Struct Reference

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]rdrclassThe Class of the RDR when registered.
[in]rdrtypeThe Type of the RDR when registered.
[in]rdridThe ID of the RDR within this Class and Type. If an ID was automatically allocated, it must be supplied to deregister the RDR.
[in]ptrA pointer to the start of the data. This must be the originally registered pointer.
[in]lengthThe length of the data. This must be the originally registered length.
Return values
SW_RDR_SUCCESSif the RDR was deregistered.
SW_RDR_ERROR_UNKNOWNis returned if the RDR could not be found.
SW_RDR_ERROR_IN_USEif 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]rdrspaceThe Namespace of the RDR when registered.
[in]nameThe Name of the RDR within this Namespace.
[in]namelenThe length of the RDR name.
[in]rdridThe 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]ptrA pointer to the start of the data. This must be the originally registered pointer.
[in]lengthThe length of the data. This must be the originally registered length.
Return values
SW_RDR_SUCCESSif the RDR was deregistered.
SW_RDR_ERROR_UNKNOWNis returned if the RDR could not be found.
SW_RDR_ERROR_IN_USEif 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]rdrclassThe Class of the RDR.
[in]rdrtypeThe Type of the RDR.
[in]rdridThe ID of the RDR.
[out]pptrA pointer to a pointer. If not NULL, this will be filled in with the pointer if the RDR is found.
[out]plengthA pointer to a length. If not NULL, this will be filled in with the length if the RDR is found.
Return values
SW_RDR_SUCCESSif the RDR was found;
SW_RDR_ERROR_UNKNOWNis 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) {
...
}
sw_rdr_result SwFindRDR(sw_rdr_class rdrclass, sw_rdr_type rdrtype, sw_rdr_id rdrid, void **pptr, size_t *plength)
Find an RDR given the Class, Type and ID.
@ SW_RDR_SUCCESS
Definition: rdrapi.h:617

◆ 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]rdrspaceThe Namespace of the RDR.
[in]nameThe Name of the RDR within this Namespace.
[in]namelenThe length of the RDR name.
[in]rdridThe ID of the RDR.
[out]pptrA pointer to a pointer. If not NULL, this will be filled in with the pointer if the RDR is found.
[out]plengthA pointer to a length. If not NULL, this will be filled in with the length if the RDR is found.
Return values
SW_RDR_SUCCESSif the RDR was found;
SW_RDR_ERROR_UNKNOWNis 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) {
...
}
sw_rdr_result SwFindNamedRDR(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.
#define CSTRING_AND_LENGTH(s1_)
Definition: std.h:156

◆ 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]rdrspaceThe Namespace of the RDR.
[in]nameThe Name of the RDR within this Namespace.
[in]namelenThe 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);
}
sw_rdr_result SwNextRDR(sw_rdr_iterator *iterator, sw_rdr_class *pclass, sw_rdr_type *ptype, sw_rdr_id *pid, void **pptr, size_t *plength)
Find an RDR by iteration.
sw_rdr_result SwFoundRDR(sw_rdr_iterator *iterator)
Destroy an RDR iterator.
sw_rdr_iterator * SwFindNamedRDRbyName(sw_rdr_namespace rdrspace, const char *name, size_t namelen)
Find all Named RDRs of a specified Namespace and Name.

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]rdrclassThe Class of the RDR.
[in]rdrtypeThe 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);
}
sw_rdr_iterator * SwFindRDRbyType(sw_rdr_class rdrclass, sw_rdr_type rdrtype)
Find all RDRs of a specified Class and Type.

◆ 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]iteratorThe iterator to destroy. Passing in a NULL iterator is pointless but safe.
Return values
SW_RDR_SUCCESSnormally;
SW_RDR_ERROR_IN_USEif the iterator cannot be destroyed because it is threaded;
SW_RDR_ERROR_SYNTAXif 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]iteratorThe sw_rdr_iterator created by SwFindRDR*().
[out]pclassOptional 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]ptypeOptional 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]pidOptional pointer to an RDR id. If not NULL, this will be filled in with the Id of the found RDR.
[out]pptrPointer to a pointer. If not NULL, this will be filled in with the ptr of the found RDR.
[out]plengthPointer to a length. If not NULL, this will be filled in with the length of the found RDR.
Return values
SW_RDR_SUCCESSif an RDR was found;
SW_RDR_ERROR_UNKNOWNif no further RDRs match;
SW_RDR_ERROR_SYNTAXif 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]rdrclassThe Class of the RDR.
[in]rdrtypeThe Type of the RDR.
[out]prdridA 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]ptrA pointer to the start of the data.
[in]lengthThe length of the data.
[in]priorityThe priority of the registration - usually zero.
Return values
SW_RDR_SUCCESSif the RDR was successfully registered.
SW_RDR_ERRORis 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]rdrspaceThe Namespace of the Named RDR. Named RDRs are subdivided into Namespaces, which are enumerated elsewhere.
[in]nameThe Name of the RDR within this Namespace.
[in]namelenThe length of the RDR name.
[in]rdridThe ID of the RDR within this Namespace and Name.
[in]ptrA pointer to the start of the data. This pointer can be NULL. See below for special behaviour if length is also zero.
[in]lengthThe 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]priorityThe 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]rdrspaceThe Namespace of the RDR.
[in]nameThe Name of the RDR within this Namespace.
[in]namelenThe length of the RDR name.
[out]prdridA 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]ptrA pointer to the start of the data.
[in]lengthThe length of the data.
[in]priorityThe priority of the registration - usually zero.
Return values
SW_RDR_SUCCESSif the RDR was successfully registered.
SW_RDR_ERRORis 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]rdrclassThe Class of the RDR, as enumerated above.
[in]rdrtypeThe Type of the RDR. RDR Classes are subdivided into Types, which are enumerated elsewhere.
[in]rdridThe ID of the RDR within this Class and Type.
[in]ptrA pointer to the start of the data. This pointer can be NULL. See below for special behaviour if length is also zero.
[in]lengthThe 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]priorityThe 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]iteratorThe iterator to restart.
Return values
SW_RDR_SUCCESSnormally;
SW_RDR_ERROR_IN_USEif the iterator cannot be restarted because it is threaded;
SW_RDR_ERROR_SYNTAXif 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: