Skip to main content

Structures

All structures used across the RIK API. Select a language tab to see the definition and field types for that language.

ReaderDefinition​

Configures reader connection parameters.

Namespace: RikCommon

#pragma pack(push, 1)
struct ReaderDefinition
{
    DeviceId DeviceId;
    ProtocolType ProtocolType = PROTOCOL_TYPE_INVALID;
    SerialPortSettings SerialPortSettings;
};
#pragma pack(pop)
FieldTypeDescription
DeviceIdDeviceIdUSB device identification (VID/PID/path/serial)
ProtocolTypeProtocolType (uint8_t)Communication protocol (default: PROTOCOL_TYPE_INVALID)
SerialPortSettingsSerialPortSettingsSerial port configuration (only for PROTOCOL_TYPE_SERIAL_BINARY)
ReaderDefinition readerDef;
readerDef.DeviceId.VendorId = 0x0C27;
readerDef.DeviceId.ProductId = 0x3BFA;
readerDef.ProtocolType = PROTOCOL_TYPE_FEATURE_REPORT;

auto handle = AbstractReader::CreateReaderInstance(readerDef, 3);

DeviceId​

USB device identification. Supports three connection strategies: VID/PID, VID/PID + serial number, or USB path.

Namespace: RikCommon

#pragma pack(push, 1)
struct DeviceId
{
    uint16_t VendorId;
    uint16_t ProductId;
    char UsbPath[512];
    char SerialNumber[256];
};
#pragma pack(pop)
FieldTypeDescription
VendorIduint16_tUSB Vendor ID (0x0C27 for rf IDEAS)
ProductIduint16_tUSB Product ID
UsbPathchar[512]Optional. Topological USB path for port-specific connection
SerialNumberchar[256]Optional. Distinguishes multiple readers with the same VID/PID
DeviceId id{};
id.VendorId = 0x0C27;
id.ProductId = 0x3BFA;
std::strncpy(id.SerialNumber, "ABC123", sizeof(id.SerialNumber) - 1);

Connection Strategies​

RIK selects the connection strategy based on which DeviceId fields are populated:

StrategyFields SetBehavior
VID/PIDVendorId + ProductIdOpens the first matching device. Non-deterministic when duplicates exist.
VID/PID + SerialVendorId + ProductId + SerialNumberFilters by USB serial number. VID/PID narrows the search. On newer rf IDEAS readers, the USB serial number matches the reader's ESN.
USB PathUsbPath (VID/PID ignored)Opens by physical port location. VID/PID and SerialNumber are ignored. Most deterministic.
note

When UsbPath is set, it takes full precedence -- the connection is made purely by topological port path and all other DeviceId fields are ignored. The path format is platform-specific:

  • Linux: "B-P" or "B-P.P.P" (e.g., "1-7", "1-7.2") -- bus number and port number(s).
  • Windows: Location path string (e.g., "PCIROOT(0)#PCI(1400)#USBROOT(0)#USB(7)").
  • macOS: Hexadecimal USB location ID (e.g., "0x14100000"); decimal format is also accepted.

See Connection Strategies for full examples in all languages.

SerialPortSettings​

Serial port communication configuration.

Namespace: RikCommon

#pragma pack(push, 1)
struct SerialPortSettings
{
    SerialPortBaudRate BaudRate;
    SerialPortParity Parity;
    SerialPortFlowControl FlowControl;
    char PortName[256];
    uint8_t ByteSize;
    SerialPortDataBits DataBits;
    SerialPortStopBits StopBits;
};
#pragma pack(pop)
FieldTypeDescription
BaudRateSerialPortBaudRate (uint32_t)Communication speed
ParitySerialPortParity (uint8_t)Parity bit configuration
FlowControlSerialPortFlowControl (uint8_t)Flow control mode
PortNamechar[256]Port name (e.g., "COM3", "/dev/ttyUSB0", "/dev/cu.usbserial-1410")
ByteSizeuint8_tByte size
DataBitsSerialPortDataBits (uint8_t)Number of data bits
StopBitsSerialPortStopBits (uint8_t)Number of stop bits
readerDef.SerialPortSettings.BaudRate = SERIAL_PORT_BAUD_9600;
readerDef.SerialPortSettings.Parity = SERIAL_PORT_PARITY_NONE;
std::strcpy(readerDef.SerialPortSettings.PortName, "COM3");

ReaderMetadataStruct​

Reader information retrieved from the device. Each field has a corresponding Has* presence flag.

tip

Always check Has* flags before reading the corresponding field. Fields without their Has* flag set may contain empty or stale data.

Namespace: Rik

#pragma pack(push, 1)
struct ReaderMetadataStruct
{
    char Processor[512];                unsigned char HasProcessor;
    char HardwarePlatform[512];         unsigned char HasHardwarePlatform;
    char Product[512];                  unsigned char HasProduct;
    char PartNumber[512];               unsigned char HasPartNumber;
    char ProductLine[512];              unsigned char HasProductLine;
    int  ConfigurationCount;            unsigned char HasConfigurationCount;
    char SerialNumber[512];             unsigned char HasSerialNumber;
    char ESN[512];                      unsigned char HasESN;
    char InstalledHardware[512];        unsigned char HasInstalledHardware;
    char SupportedHardware[512];        unsigned char HasSupportedHardware;

    // Hardware capability flags
    unsigned char HwSupportedSamSe;
    unsigned char HwSupportedRfAms;
    unsigned char HwSupportedRf125;
    unsigned char HwSupportedRfLegic;
    unsigned char HwSupportedRfBle;
    unsigned char HwSupportedNxp;
    unsigned char HwSupportedRfHidBle;
    unsigned char HwSupportedFelica;
    unsigned char HwSupportedBeeper;
    unsigned char HwSupportedNano;
    unsigned char HwInstalledSamSe;
    unsigned char HwInstalledRfAms;
    unsigned char HwInstalledRf125;
    unsigned char HwInstalledRfLegic;
    unsigned char HwInstalledRfBle;
    unsigned char HwInstalledNxp;
    unsigned char HwInstalledRfHidBle;
    unsigned char HwInstalledFelica;
    unsigned char HasInstalledHardwareInfo;

    char FirmwareFilename[512];         unsigned char HasFirmwareFilename;
    char FirmwareVersion[512];          unsigned char HasFirmwareVersion;
    // Controller firmware versions
    char ControllerApplicationVersion[512]; unsigned char HasControllerApplicationVersion;
    char ControllerBootloaderVersion[512];  unsigned char HasControllerBootloaderVersion;
    char ControllerRadioVersion[512];       unsigned char HasControllerRadioVersion;
    // Radio firmware versions
    char RadioApplicationVersion[512];  unsigned char HasRadioApplicationVersion;
    char RadioBootloaderVersion[512];   unsigned char HasRadioBootloaderVersion;
    char RadioRadioVersion[512];        unsigned char HasRadioRadioVersion;
    // Bluetooth / Security modules
    char BluetoothVersion[512];         unsigned char HasBluetoothVersion;
    char HidSeSamVersion[512];          unsigned char HasHidSeSamVersion;
    char NxpSamVersion[512];            unsigned char HasNxpSamVersion;
    char FelicaSamVersion[512];         unsigned char HasFelicaSamVersion;

    // Protocol and advanced attributes
    unsigned char ProtocolType;
    unsigned char ReaderSupportsExtendedMode;

    struct {
        unsigned char ReverseAllBytesSupported;
        unsigned char AsciiExtendedSupported;
        unsigned char RoswellModeEnabled;
    } AdvancedAttributes;
};
#pragma pack(pop)
FieldTypeDescription
Processorchar[512]Processor identifier
PartNumberchar[512]Reader part number
SerialNumberchar[512]Reader serial number
ESNchar[512]Electronic Serial Number
ConfigurationCountintNumber of configuration slots
FirmwareVersionchar[512]Firmware version string
Has*unsigned charPresence flag for string/version fields (1 = present)
HwSupported*unsigned charHardware capability: whether the reader hardware supports this module
HwInstalled*unsigned charHardware capability: whether this module is installed
HasInstalledHardwareInfounsigned char1 if hardware capability fields are populated
ProtocolTypeunsigned charProtocol used by this reader connection
ReaderSupportsExtendedModeunsigned charRead-only hardware capability flag
AdvancedAttributesnested structRead-only hardware capabilities (see below)

AdvancedAttributes​

Read-only hardware capabilities derived from the reader's internal configuration. These fields are populated automatically and cannot be changed via SetReaderConfiguration.

FieldTypeDescription
ReverseAllBytesSupportedunsigned charReader hardware supports reverse-all-bytes mode
AsciiExtendedSupportedunsigned charReader hardware supports ASCII extended mode
RoswellModeEnabledunsigned charRoswell mode is enabled on the reader
auto metadata = app->GetMetadataStruct();

if (metadata.HasPartNumber)
    std::cout << "Part: " << metadata.PartNumber << std::endl;

if (metadata.HasFirmwareVersion)
    std::cout << "Firmware: " << metadata.FirmwareVersion << std::endl;

// Hardware capabilities
if (metadata.HasInstalledHardwareInfo) {
    std::cout << "BLE supported: " << (int)metadata.HwSupportedRfBle << std::endl;
    std::cout << "Beeper supported: " << (int)metadata.HwSupportedBeeper << std::endl;
}

// Advanced attributes (read-only)
std::cout << "Reverse all bytes: "
          << (int)metadata.AdvancedAttributes.ReverseAllBytesSupported << std::endl;

CardData​

Represents credential data read from a card.

Namespace: Rik

class CardData
{
public:
    std::vector<uint8_t> Data;  // 32 bytes

    unsigned int GetBitCount() const;
    void SetBitCount(unsigned int bitCount);
    bool IsEmpty() const;
    std::string AsString();
};
MemberTypeDescription
Datastd::vector<uint8_t>Raw card data (32 bytes)
GetBitCount()unsigned intNumber of valid bits in the data
SetBitCount()voidSet the bit count
IsEmpty()boolReturns true if bit count is zero and all data bytes are zero
AsString()std::stringHex string representation of the data
note

Use IsEmpty() (C++/C#) or is_empty() (Python) to check whether card data was read. The method returns true when bit count is zero and all data bytes are zero, indicating no card is present.

8-byte reads truncate silently

When GetCardData is called with READ_8_BYTES / Read8Bytes, the buffer is still 32 bytes: bytes 0–7 hold data and bytes 8–31 are zero. GetBitCount() / BitCount / bit_count reports the full credential width, so a value greater than 64 means data was dropped. Prefer READ_32_BYTES / Read32Bytes. See GetCardDataSizeParameters.

LibraryInfo​

ABI-safe struct containing library build and version metadata.

Namespace: Rik

struct LibraryInfo
{
    char Name[256];
    char InternalName[256];
    char Comments[512];
    char CompanyName[256];
    char CompanyCopyright[512];
    char LicenseText[1024];
    char FileDescription[1024];
    char SemVer[256];
    char BuildVer[256];
    char VersionString[256];
    char BuildDate[256];
    char BuildPlatform[256];
    char BuildToolchain[256];
    // ... additional build metadata fields (28 total)
};
Key FieldsTypeDescription
Namechar[256]Library name
SemVerchar[256]Semantic version string
VersionStringchar[256]Full version string
BuildDatechar[256]Build date
BuildPlatformchar[256]Target platform
BuildToolchainchar[256]Compiler/toolchain used
LibraryInfo info;
auto result = AbstractReader::GetLibraryInfo(info);
if (!result.HasException) {
    std::cout << "Version: " << info.SemVer << std::endl;
}

LedConfiguration​

LED state configuration.

Namespace: Rik

#pragma pack(push, 1)
struct LedConfiguration
{
    LedColor Color;
    bool SoftwareControlEnabled;
};
#pragma pack(pop)
FieldTypeDescription
ColorLedColor (unsigned char)Current LED color
SoftwareControlEnabledboolWhether software LED control is active

RikResult​

C API error result struct. Returned by C API functions to communicate success or failure across the ABI boundary.

Namespace: Rik

#pragma pack(push, 1)
struct RikResult
{
    bool HasException;
    char ExceptionType[256];
    char Message[2048];
    char FileName[2048];
    int LineNumber;
    char FunctionName[256];

    bool HasProtocolException;
    char ProtocolExceptionType[256];
    char ProtocolMessage[2048];
    char ProtocolFileName[2048];
    int ProtocolLineNumber;
    char ProtocolFunctionName[256];
};
#pragma pack(pop)
FieldTypeDescription
HasExceptionbooltrue if an error occurred
ExceptionTypechar[256]Exception class name
Messagechar[2048]Error description
FileNamechar[2048]Source file where the error originated
LineNumberintSource line number
FunctionNamechar[256]Function name
HasProtocolExceptionbooltrue if a protocol-level error is also present
Protocol* fields(same types)Protocol-level error details (same layout)
RikResult result = Rik_Init(handle);
if (result.HasException) {
    std::cerr << "Error: " << result.Message << std::endl;
    if (result.HasProtocolException) {
        std::cerr << "Protocol: " << result.ProtocolMessage << std::endl;
    }
}

LuidResponseInformation​

Response data from a LUID query.

Namespace: Rik

struct LuidResponseInformation
{
    uint16_t Luid;
    uint16_t ApplicationVersionPackedBcd;
    uint32_t BootloaderVersionUnpackedBcd;
};
FieldTypeDescription
Luiduint16_tLogical Unit ID
ApplicationVersionPackedBcduint16_tApplication version in packed BCD
BootloaderVersionUnpackedBcduint32_tBootloader version in unpacked BCD

SupportedCardTypesResult​

Result of querying supported card types from a reader.

Namespace: Rik

struct SupportedCardTypesResult
{
    uint32_t Count;
    CardTypeInfo CardTypes[256];
};
FieldTypeDescription
Countuint32_tNumber of valid entries in CardTypes
CardTypesCardTypeInfo[256]Fixed-size array; only the first Count entries are valid

CardTypeInfo​

Describes a single card type supported by a reader. Packed size is 196 bytes (Pack = 1 / #pragma pack(1)).

Namespace: Rik (ABI struct; category/frequency types from RikCommon)

struct CardTypeInfo
{
    uint16_t Value;                          // offset 0
    char Name[128];                          // offset 2
    char EnumName[64];                       // offset 130
    RikCommon::CardCategory Category;        // offset 194
    RikCommon::CardFrequency Frequency;      // offset 195
};
FieldTypeOffsetSizeDescription
Valueuint16_t02Numeric card type identifier
Namechar[128]2128Human-readable card type name
EnumNamechar[64]13064Enumeration constant name
CategoryRikCommon::CardCategory1941Card category. See CardCategory.
FrequencyRikCommon::CardFrequency1951Card RF frequency. See CardFrequency.

ReaderConfigurationStruct​

Packed reader configuration (62 named fields across five blocks). C++ applications typically populate this via the ReaderConfiguration fluent builder. C# and Python use this struct directly with GetReaderConfiguration / SetReaderConfiguration.

Constants:

ConstantValueDescription
FAC_DIGIT_COUNT_MAX26Maximum value for FacDigitCount
ID_DIGIT_COUNT_MAX26Maximum value for IdDigitCount
PARITY_COUNT_MAX0x8E (142)Maximum value for TotalStripLeadingParityCount and TotalStripTrailingParityCount

Namespace: RikCommon

#pragma pack(push, 1)
struct ReaderConfigurationStruct
{
    // Block1
    uint8_t FacDigitCount;
    uint8_t IdDigitCount;
    uint8_t TotalStripLeadingParityCount;
    uint8_t TotalStripTrailingParityCount;
    uint8_t IdBitCount;
    uint8_t ExpectedBitCount;
    uint8_t IdAndFacDelimiter;
    uint8_t TerminationCharacter;
    uint8_t UseFixedLengthForFacAndId;
    uint8_t EnforceExpectedBitCount;
    uint8_t StripFacFromId;
    uint8_t SendFacAfterStrippingIt;
    uint8_t UseIdAndFacDelimiter;
    uint8_t DisableKeystrokeTerminationCharacter;
    uint8_t EnableContinuousRead;
    uint8_t DisableKeystroking;
    // Block2
    uint16_t LegacyBitStreamTimeOutMs;
    uint16_t DataHoldTimeMs;
    uint16_t LockOutTimeMs;
    uint16_t KeyPressTimeMs;
    uint16_t KeyReleaseTimeMs;
    uint8_t EnableIdExtendedPrecision;
    uint8_t UseLowercaseHex;
    uint8_t EnableProxProEmulation;
    uint8_t EnableHexadecimalId;
    uint8_t EnableHexadecimalFac;
    uint8_t UseIndividualIdAndFacNumberFormats;
    uint8_t UseNumericKeypad;
    uint8_t ReaderSupportsReverseAllBytes;
    uint8_t ReaderSupportsAsciiExtended;
    uint8_t ReaderSupportsExtendedMode;
    uint8_t EnableRoswellMode;
    // Block3
    uint8_t EnableRedLed;
    uint8_t EnableGreenLed;
    uint8_t EnableOemRelay;
    uint8_t EnableOemBeeper;
    uint8_t IsBootDevice;
    uint8_t UseLeadingCharacters;
    uint8_t EnabledSoftwareControlledLed;
    uint8_t UseHexadecimalForBothFacAndId;
    uint8_t InvertWiegandBits;
    uint8_t EnableBeepOnCardRead;
    uint8_t ReverseWiegandBits;
    uint8_t ReverseWiegandBytes;
    uint8_t UseDataInvert;
    uint8_t CardGoneCharacters[2];
    uint8_t LeadingCharacterCount;
    uint8_t TrailingCharacterCount;
    uint8_t LeadingTrailingCharacters[3];
    // Block4
    uint8_t UseIndividualIdAndFacFixedLengths;
    uint8_t UseFixedLengthFac;
    uint8_t UseFixedLengthId;
    uint8_t CfgRb3;
    uint8_t CfgRb4;
    uint8_t EnableFacExtendedPrecision;
    uint8_t AzertyKeyboardShift;
    uint8_t EnableExtendedMode;
    // Block5
    uint8_t DisableCardConfiguration;
    uint16_t CardType;
    uint8_t SetHighPriorityCardType;
    uint8_t JetMobileCompatibilityCharacter;
    uint8_t JetMobileCharacterCount;
};
#pragma pack(pop)
note

This struct uses #pragma pack(push, 1) (via PACKED_STRUCT_COMMON_EXPORT_BEGIN / END) — all fields are byte-aligned with no padding.

BlockFieldTypeDescription
Block1FacDigitCountuint8_tNumber of FAC digits to output. Range: [0, 26].
Block1IdDigitCountuint8_tNumber of ID digits to output. Range: [0, 26].
Block1TotalStripLeadingParityCountuint8_tLeading parity bits to strip. Range: [0, 0x8E / 142].
Block1TotalStripTrailingParityCountuint8_tTrailing parity bits to strip. Range: [0, 0x8E / 142].
Block1IdBitCountuint8_tNumber of ID bits.
Block1ExpectedBitCountuint8_tExpected total bit count from reader.
Block1IdAndFacDelimiteruint8_tASCII character used to separate FAC and ID output.
Block1TerminationCharacteruint8_tASCII character appended at end of keystroke output.
Block1UseFixedLengthForFacAndIduint8_t (0/1)Pad FAC and ID to fixed digit lengths.
Block1EnforceExpectedBitCountuint8_t (0/1)Reject cards not matching ExpectedBitCount.
Block1StripFacFromIduint8_t (0/1)Remove FAC portion from ID output.
Block1SendFacAfterStrippingItuint8_t (0/1)Re-emit FAC after stripping it from ID.
Block1UseIdAndFacDelimiteruint8_t (0/1)Insert IdAndFacDelimiter between FAC and ID.
Block1DisableKeystrokeTerminationCharacteruint8_t (0/1)Suppress the termination character in keystroke output.
Block1EnableContinuousReaduint8_t (0/1)Continuously report card presence.
Block1DisableKeystrokinguint8_t (0/1)Suppress all keystroke output.
Block2LegacyBitStreamTimeOutMsuint16_tLegacy bit-stream timeout in ms. Must be multiple of 4; range [0, 1020].
Block2DataHoldTimeMsuint16_tData hold time in ms. Must be multiple of 50; range [0, 12750].
Block2LockOutTimeMsuint16_tLock-out time in ms. Must be multiple of 50; range [0, 12750].
Block2KeyPressTimeMsuint16_tKey press duration in ms. Must be multiple of 4; range [0, 1020].
Block2KeyReleaseTimeMsuint16_tKey release duration in ms. Must be multiple of 4; range [0, 1020].
Block2EnableIdExtendedPrecisionuint8_t (0/1)Enable extended precision for ID output.
Block2UseLowercaseHexuint8_t (0/1)Use lowercase hex digits in hexadecimal output.
Block2EnableProxProEmulationuint8_t (0/1)Emulate ProxPro output format.
Block2EnableHexadecimalIduint8_t (0/1)Output ID in hexadecimal format.
Block2EnableHexadecimalFacuint8_t (0/1)Output FAC in hexadecimal format.
Block2UseIndividualIdAndFacNumberFormatsuint8_t (0/1)Apply separate number formats to ID and FAC independently.
Block2UseNumericKeypaduint8_t (0/1)Use numeric keypad scan codes for keystroke output.
Block2ReaderSupportsReverseAllBytesuint8_t (0/1)Device-reported. Indicates device capability; set by reader. Not compared in equality.
Block2ReaderSupportsAsciiExtendeduint8_t (0/1)Device-reported. Indicates device capability; set by reader. Not compared in equality.
Block2ReaderSupportsExtendedModeuint8_t (0/1)Device-reported. Indicates device capability; set by reader. Not compared in equality.
Block2EnableRoswellModeuint8_t (0/1)Device-preserved. Preserved by SetReaderConfiguration; not user-overridable.
Block3EnableRedLeduint8_t (0/1)Enable red LED.
Block3EnableGreenLeduint8_t (0/1)Enable green LED.
Block3EnableOemRelayuint8_t (0/1)Enable OEM relay output.
Block3EnableOemBeeperuint8_t (0/1)Enable OEM beeper.
Block3IsBootDeviceuint8_t (0/1)Device-reported. Indicates device is in boot mode; set by reader. Not compared in equality.
Block3UseLeadingCharactersuint8_t (0/1)Prepend leading characters to keystroke output.
Block3EnabledSoftwareControlledLeduint8_t (0/1)Enable software-controlled LED.
Block3UseHexadecimalForBothFacAndIduint8_t (0/1)Output both FAC and ID in hexadecimal.
Block3InvertWiegandBitsuint8_t (0/1)Invert Wiegand bit values.
Block3EnableBeepOnCardReaduint8_t (0/1)Beep when a card is read.
Block3ReverseWiegandBitsuint8_t (0/1)Reverse bit order in Wiegand data.
Block3ReverseWiegandBytesuint8_t (0/1)Reverse byte order in Wiegand data.
Block3UseDataInvertuint8_t (0/1)Invert all data bits.
Block3CardGoneCharactersuint8_t[2]Up to 2 characters sent when card is removed. Add via AddCardGoneCharacter().
Block3LeadingCharacterCountuint8_tNumber of leading characters currently set (0–3 combined with trailing).
Block3TrailingCharacterCountuint8_tNumber of trailing characters currently set (0–3 combined with leading).
Block3LeadingTrailingCharactersuint8_t[3]Combined leading then trailing characters. Add via AddLeadingCharacter() / AddTrailingCharacter().
Block4UseIndividualIdAndFacFixedLengthsuint8_t (0/1)Apply separate fixed lengths to ID and FAC.
Block4UseFixedLengthFacuint8_t (0/1)Pad FAC to fixed length.
Block4UseFixedLengthIduint8_t (0/1)Pad ID to fixed length.
Block4CfgRb3uint8_tOpaque firmware configuration byte. No public meaning.
Block4CfgRb4uint8_tOpaque firmware configuration byte. No public meaning.
Block4EnableFacExtendedPrecisionuint8_t (0/1)Enable extended precision for FAC output.
Block4AzertyKeyboardShiftuint8_t (0/1)Apply AZERTY keyboard shift mapping.
Block4EnableExtendedModeuint8_t (0/1)Enable extended configuration mode.
Block5DisableCardConfigurationuint8_t (0/1)Disable card-specific configuration.
Block5CardTypeuint16_tCard type identifier.
Block5SetHighPriorityCardTypeuint8_t (0/1)Treat CardType as high-priority.
Block5JetMobileCompatibilityCharacteruint8_tJetMobile compatibility character.
Block5JetMobileCharacterCountuint8_tJetMobile character count.

ExtendedConfiguration​

Packed extended field-separator configuration. Namespace: RikCommon.

Constants: EXTENDED_CONFIGURATION_SIZE = 128 (serialized ToVector / FromVector buffer size, not sizeof the in-memory struct), MAX_FIELD_ENTRIES = 31, MAX_SEPARATOR_ENTRIES = 31.

Namespace: RikCommon

#pragma pack(push, 1)
struct ExtendedConfiguration
{
    FieldSeparatorDataHeader Header;
    FieldEntry FieldEntries[MAX_FIELD_ENTRIES];
    SeparatorEntry SeparatorEntries[MAX_SEPARATOR_ENTRIES];
    ApplicationData AppData;
};
#pragma pack(pop)
note

This struct uses #pragma pack(push, 1) — all fields are byte-aligned with no padding.

FieldTypeDescription
HeaderFieldSeparatorDataHeaderHeader metadata
FieldEntriesFieldEntry[31]Up to MAX_FIELD_ENTRIES (31) field entries
SeparatorEntriesSeparatorEntry[31]Matching separator entries
AppDataApplicationDataApplication-specific data

C++ methods:

static ExtendedConfiguration FromVector(const std::vector<uint8_t>& data);
static std::vector<uint8_t> ToVector(const ExtendedConfiguration& extendedConfiguration);
bool operator==(const ExtendedConfiguration& other) const;
bool operator!=(const ExtendedConfiguration& other) const;

FieldSeparatorDataHeader​

Header for an ExtendedConfiguration.

Namespace: RikCommon

#pragma pack(push, 1)
struct FieldSeparatorDataHeader
{
    uint8_t FieldSeparatorStructureVersion;
    uint8_t HeaderSize;
    uint8_t FieldEntrySize;
    uint8_t FieldEntryCount;
    uint8_t SeparatorEntrySize;
    uint8_t SeparatorEntryCount;
    uint8_t MaxStorageSize;
};
#pragma pack(pop)
note

This struct uses #pragma pack(push, 1) — all fields are byte-aligned with no padding.

FieldTypeDescription
FieldSeparatorStructureVersionuint8_tStructure version. Validate() requires >= 1.
HeaderSizeuint8_tHeader size in bytes. Validate() requires == 4.
FieldEntrySizeuint8_tSize of each field entry. Validate() requires == 4.
FieldEntryCountuint8_tNumber of field entries. Validate() range [0, 31].
SeparatorEntrySizeuint8_tSize of each separator entry. Validate() requires == 2.
SeparatorEntryCountuint8_tNumber of separator entries. Validate() range [0, 31].
MaxStorageSizeuint8_tMaximum storage size. Validate() requires == 16.

C++ methods:

static FieldSeparatorDataHeader FromVector(const std::vector<uint8_t>& data);
static std::vector<uint8_t> ToVector(const FieldSeparatorDataHeader& header);
static void Validate(const FieldSeparatorDataHeader& header);
bool operator==(const FieldSeparatorDataHeader& other) const;
bool operator!=(const FieldSeparatorDataHeader& other) const;

FieldEntry​

One extended-configuration field. ConversionType uses DataConversionType.

Namespace: RikCommon

#pragma pack(push, 1)
struct FieldEntry
{
    uint8_t FieldValid;
    DataConversionType ConversionType;
    uint8_t FixedFieldOutputLength;
    uint8_t ReverseBits;
    uint8_t ReverseBytes;
    uint8_t FiveBMS;
    uint8_t InvertBits;
    uint8_t ReverseAllBytes;
    uint8_t UseHash;
    uint8_t HashKey;
    uint8_t StartingBitPosition;
    uint8_t BitCountOfField;
};
#pragma pack(pop)
note

This struct uses #pragma pack(push, 1) — all fields are byte-aligned with no padding.

FieldTypeDescription
FieldValiduint8_tWhether this entry is valid (0 or 1)
ConversionTypeDataConversionTypeOutput conversion. Validate() requires <= DataConversionType::OCTAL
FixedFieldOutputLengthuint8_tFixed output length. Validate() range [0, 31]
ReverseBitsuint8_tReverse bits (0 or 1)
ReverseBytesuint8_tReverse bytes (0 or 1)
FiveBMSuint8_tFive-bit encoding (0 or 1)
InvertBitsuint8_tInvert bits (0 or 1)
ReverseAllBytesuint8_tReverse all bytes (0 or 1)
UseHashuint8_tApply hash (0 or 1)
HashKeyuint8_tSelects HashKeyA (0) or HashKeyB (1)
StartingBitPositionuint8_tStarting bit of this field
BitCountOfFielduint8_tNumber of bits in this field

C++ methods:

static FieldEntry FromVector(const std::vector<uint8_t>& data);
static std::vector<uint8_t> ToVector(const FieldEntry& fieldEntry);
static void Validate(const FieldEntry& fieldEntry);
bool operator==(const FieldEntry& other) const;
bool operator!=(const FieldEntry& other) const;

SeparatorEntry​

One separator entry in an ExtendedConfiguration. Constant: MAX_SEPARATOR_CHARS_PER_ENTRY = 31.

Namespace: RikCommon

#pragma pack(push, 1)
struct SeparatorEntry
{
    uint8_t SeparatorValid;
    uint8_t CharacterSize;
    uint8_t VirtualCharacterCount;
    uint8_t ByteOffset;
    SeparatorCharacter SeparatorCharacters[MAX_SEPARATOR_CHARS_PER_ENTRY];
};
#pragma pack(pop)
note

This struct uses #pragma pack(push, 1) — all fields are byte-aligned with no padding.

FieldTypeDescription
SeparatorValiduint8_tWhether this entry is valid. Validate() range [0, 1]
CharacterSizeuint8_tBytes per character. Validate() range [1, 2]
VirtualCharacterCountuint8_tNumber of characters used. Validate() range [0, 31]
ByteOffsetuint8_tByte offset of this separator
SeparatorCharactersSeparatorCharacter[31]Character definitions

C++ methods:

static SeparatorEntry FromVector(const std::vector<uint8_t>& data);
static std::vector<uint8_t> ToVector(const SeparatorEntry& separatorEntry);
static void Validate(const SeparatorEntry& separatorEntry);
bool operator==(const SeparatorEntry& other) const;
bool operator!=(const SeparatorEntry& other) const;

SeparatorCharacter​

One USB keystroke in a SeparatorEntry. USBKeyScanCode is a raw HID scan code (not an enum). Validate() range for USBKeyScanCode is [0, 231].

Namespace: RikCommon

#pragma pack(push, 1)
struct SeparatorCharacter
{
    uint8_t USBKeyScanCode;
    uint8_t KeyModifier;
};
#pragma pack(pop)
note

This struct uses #pragma pack(push, 1) — all fields are byte-aligned with no padding.

FieldTypeDescription
USBKeyScanCodeuint8_tUSB HID scan code. Validate() range [0, 231]
KeyModifieruint8_tKey modifier byte

C++ methods:

static SeparatorCharacter FromVector(const std::vector<uint8_t>& data);
static std::vector<uint8_t> ToVector(const SeparatorCharacter& separatorCharacter, uint8_t charSize);
static void Validate(const SeparatorCharacter& separatorCharacter);
bool operator==(const SeparatorCharacter& other) const;
bool operator!=(const SeparatorCharacter& other) const;

ApplicationData​

Application-specific data at the end of ExtendedConfiguration. DefinitionType uses FieldDefinitionType.

note

C++ uses the name ApplicationData. C# and Python use the name ReaderData for the same three fields.

Namespace: RikCommon

#pragma pack(push, 1)
struct ApplicationData
{
    FieldDefinitionType DefinitionType;
    uint8_t EnhanceSecurityFlag;
    uint8_t FipsBitCount;
};
#pragma pack(pop)
note

This struct uses #pragma pack(push, 1) — all fields are byte-aligned with no padding.

FieldTypeDescription
DefinitionTypeFieldDefinitionTypeField definition. Validate() requires <= FIPS201_245_BIT
EnhanceSecurityFlaguint8_tEnhance-security flag. Validate() range [0, 1]
FipsBitCountuint8_tFIPS bit count

C++ methods:

static ApplicationData FromVector(const std::vector<uint8_t>& data);
static std::vector<uint8_t> ToVector(const ApplicationData& appData);
static void Validate(const ApplicationData& appData);
bool operator==(const ApplicationData& other) const;
bool operator!=(const ApplicationData& other) const;

HashData​

Two 16-byte AES keys used for hashing card ID data in extended mode, plus firmware security state. See SetReaderConfiguration for extended-mode usage. Constant: HASH_KEY_SIZE = 16.

Namespace: RikCommon

#pragma pack(push, 1)
struct HashData
{
    uint8_t HashKeyA[HASH_KEY_SIZE];
    uint8_t HashKeyB[HASH_KEY_SIZE];
    uint8_t EnhanceSecurityFirmwareState;

    static bool IsKeyEmpty(const uint8_t key[HASH_KEY_SIZE]);
};
#pragma pack(pop)
note

This struct uses #pragma pack(push, 1) — all fields are byte-aligned with no padding.

FieldTypeDescription
HashKeyAuint8_t[16]First 16-byte AES key
HashKeyBuint8_t[16]Second 16-byte AES key
EnhanceSecurityFirmwareStateuint8_tFirmware security state

IsKeyEmpty returns true if all 16 bytes of the provided key buffer are zero. It takes a raw 16-byte key array (e.g. hashData.HashKeyA or hashData.HashKeyB), not a HashData object.

RikCommon::HashData hd = /* ... */;
if (RikCommon::HashData::IsKeyEmpty(hd.HashKeyA)) {
    // HashKeyA is all zeros
}

BlobHeader​

Header for a smart-card configuration blob. Type uses BlobType.

Namespace: RikCommon

#pragma pack(push, 1)
struct BlobHeader
{
    BlobType Type;
    uint8_t ID;
    uint16_t DataLength;
    uint8_t BSV;
};
#pragma pack(pop)
note

This struct uses #pragma pack(push, 1) — all fields are byte-aligned with no padding.

FieldTypeDescription
TypeBlobTypeBlob payload type
IDuint8_tBlob identifier
DataLengthuint16_tLength of following data in bytes
BSVuint8_tBlob structure version

SmartCardConfigurationStruct​

Packed smart-card configuration: a BlobHeader plus a data buffer. Constant: MAX_BLOB_SIZE = 4 * 0xFE = 1016.

The C++ wrapper class SmartCardConfiguration exposes GetStruct(), SetConfiguration(), operator==, and operator!=.

Namespace: RikCommon

#pragma pack(push, 1)
struct SmartCardConfigurationStruct
{
    BlobHeader Header;
    uint8_t Data[MAX_BLOB_SIZE];
};
#pragma pack(pop)
note

This struct uses #pragma pack(push, 1) — all fields are byte-aligned with no padding.

FieldTypeDescription
HeaderBlobHeaderBlob type, ID, length, and version
Datauint8_t[1016]Blob payload (MAX_BLOB_SIZE)

See Also​