(v13) RDR concepts

This page applies to Harlequin v13.1r0 and later; both Harlequin Core and Harlequin MultiRIP

A provider can register an entity (for example an API structure pointer or a block of ROM data) as an RDR identified by Class, Type and ID, with a particular priority; or identified by Namespace, Name and ID, with a particular priority. If multiple RDRs are registered with the same Class, Type and ID (or Namespace, Name and ID), only the highest priority is visible. RDRs can be de-registered and re-prioritized at any time, possibly revealing other registrations. Registrations of the same Class, Type, ID and priority, or Namespace, Name, ID and priority, operate a strict chronological ordering, with the last registration being visible.

A consumer can locate a particular RDR by Class, Type and ID, by Namespace, Name, and ID, or iterate through RDRs by Class and Type, or by Namespace and Name.

Names and Namespaces may be more or less convenient than Classes and Types depending on where the RDR is defined and registered, and how the knowledge of the RDR's existence is identified to the RIP. RDRs are either registered, deregistered and found by Class and Type, or by Namespace and Name. There is no mixing of the concepts; RDRs registered by Class and Type cannot be discovered or deregistered by Namespace and Name, and vice-versa.

A Class is a member of the RDR class enumeration defined in rdrapi.h, represented as a generic integer identifier value of type HqnIdent.

A Type is specific to the Class, but is represented as a generic integer identifier value of type HqnIdent. The range and interpretation of Types is specific to each Class, and is usually defined in a separate header file specific to the Class. Types of different Classes can use the same identifier values for different purposes, the interpretation of Type is defined by the Class.

A Namespace is a member of the RDR namespace enumeration defined in rdrapi.h, represented as a generic integer identifier value of type HqnIdent. Namespaces partition the use of Names for different purposes.

A Name is a string and length used to identify a particular set of RDRs. Names are partitioned into Namespaces, so the same Name can be used in different Namespaces to identify different sets of RDRs. Names passed to the API functions do not need to be zero terminated. The calling functions retain ownership over the memory used for the name in all cases, the name will be copied for storage if necessary.

An ID is a generic integer identifier of value HqnIdent. The ID identifiers a particular instance of a Class and Type or Namespace and Name. The significance of the ID depends on the Class and Type or Namespace and Name. In some combinations the ID is used as a version number for the RDR data; in other combinations the ID is not significant, and may be created on registration by the RDR system.

The Class and Namespace identifiers and most Type identifiers follow common conventions in the Harlequin RIP interfaces for the ranges of values that are used:

Values in the range 0x00000000 0x0000ffff are reserved for Global Graphics.
Values in the range 0xXXXX 0000 0xXXXX ffff are reserved for customer number

XXXX .

Values in the range 0xffff0000 0xffffffff are reserved for private use in closed environments (e.g., within a product that does not include other third-party components that may use RDR).