|
Harlequin RIP SDK
|
|
|
|
Harlequin RIP SDK
|
|
The RDR API structure for version 20110201. 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_iterator *(* | find_class )(sw_rdr_class) |
| Find all RDRs of a specified Class. More... | |
| sw_rdr_iterator *(* | find_all )(void) |
| Find all RDRs. 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... | |
The RDR API structure for version 20110201.
| sw_rdr_result( * sw_rdr_api_20110201::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.
| [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. |
| 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.
| sw_rdr_result( * sw_rdr_api_20110201::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.
| [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. |
| 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:
| sw_rdr_iterator*( * sw_rdr_api_20110201::find_all) (void) |
Find all RDRs.
This call begins an iteration to find all RDRs.
| sw_rdr_iterator*( * sw_rdr_api_20110201::find_class) (sw_rdr_class) |
Find all RDRs of a specified Class.
This call begins an iteration to find all RDRs of a specific class.
| [in] | rdrclass | The Class of the RDR. |
| sw_rdr_iterator*( * sw_rdr_api_20110201::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.
| [in] | rdrclass | The Class of the RDR. |
| [in] | rdrtype | The Type of the RDR. |
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.,
| sw_rdr_result( * sw_rdr_api_20110201::found) (sw_rdr_iterator *) |
Destroy an RDR iterator.
This call ends an iteration to find RDRs.
| [in] | iterator | The iterator to destroy. Passing in a NULL iterator is pointless but safe. |
| 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().
| sw_rdr_result( * sw_rdr_api_20110201::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.
| sw_rdr_result( * sw_rdr_api_20110201::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.
| [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. |
| 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().
| sw_rdr_result( * sw_rdr_api_20110201::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.
| [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. |
| 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. |
| sw_rdr_result( * sw_rdr_api_20110201::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.
| [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. |
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.
| sw_rdr_result( * sw_rdr_api_20110201::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.
| [in] | iterator | The iterator to restart. |
| 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().