BALTECH SDK wrapper functions reference

§ brp_VHL_Setup()

brp_errcode brp_VHL_Setup ( brp_VHL_Setup_t  params)

This command creates a VHL file dynamically and transfers it to the reader's RAM.

The VHL file specifies the card-specific memory structure required to call brp_VHL_Read() or brp_VHL_Write(). You need to run VHL.Setup if you don't want to configure the readers with a static VHL file ( learn more).

To run brp_VHL_Format() , you cannot use a dynamic VHL file. In this case, you have to follow thestandard VHL implementation with a static VHL file.

What to specify

To describe the memory structure, provide a list of parameters depending on the card type (see optional fields in the Parameters table below). If you omit a parameter, the reader will use the default value. To fill in the parameter values, please refer to the card specification. For LEGIC or MIFARE cards, you can also analyze the card structure using BALTECH ID-engine Explorer.

Mixing dynamic and static VHL files

In principle, it is possible to mix dynamic VHL files and static VHL files (as part of the reader configuration for the VHL & Autoread). However, please note that the dynamic VHL file is lost as soon as you run brp_VHL_Read() or brp_VHL_Write() with a static VHL file. Thus, if you later want to run VHL.Read or VHL.Write with the dynamic VHL file again, you first need to rerun VHL.Setup to recreate the dynamic VHL file.

Parameters
[in]paramsStruct with the following fields:
  • protocol used to execute the command
  • ConsideredCardType (in) Type of card to consider. The default value is 0x00, i.e. the reader will use the card type detected by brp_VHL_Select(). To handle the card as a different type (e.g. handle a DESFire card as an inter-industry ISO 14443-4 card), set this value to the desired card type. Not all card types support all VHL commands. For details, see our overview ofsupported commands — The type of the selected card. Since there are no reliable identification standards amongst card manufacturers, we use a heuristic that examines the UID, its length, and other information as documented here. Due to the lack of standards, we cannot guarantee the card type is always identified correctly.
  • HasMifareKey (in)
  • MifareKey (in) Encryption key to access the card.
  • MifareHasAsKeyA (in)
  • MifareAsKeyA (in) If true , Key A is used to access the card. If false , Key B is used.
  • MifareHasMadId (in)
  • MifareMadId (in) 2-byte application ID (AID) that identifies the sectors to access. If specified, only the payload of that application will be accessed. If not specified, the payload of all sectors will be accessed. All sector trailer blocks and block 0 will be omitted, i.e. the following block order is used: 1,2,4,5,6,8, etc. (0,3,7, etc. are omitted).
  • DesfireHasAppId (in)
  • DesfireAppId (in) Application ID, ranging from 0 to 0x00FFFFFF (big-endian)
  • HasDesfireFileDesc (in)
  • DesfireFileDesc (in)
  • DesfireKey (in) Key with preceding crypto byte. Please refer to Device / CryptoKey SubKey for more details.
  • DesfireKey_len (in) Length of DesfireKey (in bytes).
  • LegicSegmentInfo (in) Either segment number or stamp, as defined in the LegicEnStamp parameter. By default, the first segment will be accessed using its segment number.
  • LegicSegmentInfo_len (in) Length of LegicSegmentInfo (in bytes).
  • LegicHasEnStamp (in)
  • LegicEnStamp (in) If true , LegicSegmentInfo contains a stamp, i.e. the identifier of the application. If false , it contains a segment number. This parameter will only be evaluated if LegicSegmentInfo has a length of 1. In this case, the reader can't distinguish between ID and stamp as a valid segment number always has length 1.
  • LegicHasAdrMode (in)
  • LegicAdrMode (in) Specifies the addressing mode. This parameter is only available on readers supporting LEGIC advant. LEGIC prime readers ignore it. To allow for backward compatibility with LEGIC prime readers, omitting this parameter will not result in the default value, but in the following behavior: VHL address 0 is mapped to protocol header address 25 , starting with the first data byte after the longest possible LEGIC prime stamp.
  • Iso15HasFirstBlock (in)
  • Iso15FirstBlock (in) First block of the application data Firmware versions 1100 2.07.00 and above also support a 16-bit length value. This is not explicitly documented.
  • Iso15HasBlockCount (in)
  • Iso15BlockCount (in) Number of blocks occupied by the application data Firmware versions 1100 2.07.00 and above also support a 16-bit length value. This is not explicitly documented.
  • Iso15HasOptionFlag (in)
  • Iso15OptionFlag (in) Option flag value for read/write operations
  • Iso15HasBlockSize (in)
  • Iso15BlockSize (in) Block size in bytes
  • Iso14SelectFileCmdListLen (in) Length of SelectFileCmdList (including the following "Length of SelectFileCmdList" field) in bytes
  • Iso14SelectFileCmdList (in)
  • Iso14SelectFileCmdList_len (in) Number of elements in Iso14SelectFileCmdList.
  • Iso14HasFileLen (in)
  • Iso14FileLen (in) File length in bytes
  • Iso14HasApduTimeout (in)
  • Iso14ApduTimeout (in) Timeout for APDU command execution in ms. The default value is 2500 ms. Keep in mind that this timeout may add up several times in the scope of a single read or write access as file selection usually requires multiple APDUs to be executed.