The Passport Reader system retains the backward compatibility with the older versions; the compiled programs run perfectly well even if the system is upgraded to a newer version.
The evolution of the system adds the necessity of changing the SDK by adding new functions, new parameters to functions, eventually changing the type of the return value or moving the deprecated functions into the compatibility section that may not be installed by default. In this way the users are pushed to use the newest version each time they compile their programs with the Passport Reader SDK, but there is also the possibility to compile the existing sources using the appropriate version.
What to do if you do not want to update your code?
- The old versions of the interface files are available on the install CD or please request them from the support team.
- Without updating the ActiveX interfaces (Delphi packages, C++ wrapper class files) the old methods will work well.
- Without updating the Java (
jpr.jar
, jpr.dll
) and .NET (prdotnet7.dll
) interfaces the old methods will work well.
As the
pkcs8 format for storing the private key does not contains enough information for matching against the proper public key (stored in a certificate), separate handling is not recommended. Therefore the
LoadCertificate() functions have been modified and a second argument is added that specifies the private key relating to the certificate. The
LoadPrivateKeyFile() function have been obsolete and deleted from the
SDK.
As it is possible to differentiate the CV (Card Verifiable) certificate from the "normal" certificates, from this version the same LoadCertFile() function is used for loading both types of certificate. The LoadCVCertFile()
function have been obsolete.
The two versions of the Passport Reader are
fully run-time compatible. The main changes between the two version branches is the usage of the
gxVARIANT
structures for internal data storage and the improved connection handling for RFID chips (see
pr_connectrfidcard(),
pr_disconnectrfidcard(),
ConnectRfidFile(),
pr.DisconnectRfidFile() function documentations).
By introducing the variant structures for data storage, the internal data handling system gets to a new level of flexibility that is required by the dynamically evolving
MRTD technology.
Compatibility issues concerning the low level programming languages (C):
- The
prDocument
and prIMAGE
structures are replaced with gxVARIANT
structures. - On data query the internal variant structures are referenced and they must be unreferenced at the end of using them to avoid memory leaks.
- Note:
- For high level programming languages, the source code compatibility is preserved as concerning this issue.
- Warning:
- In C++ programming language in case of using
gxIMAGE
structures returned by the GxImage() function, the reference number of the image data is automatically increased and must be dereferenced at the end of using it to avoid memory leakage (check the prapi03.cpp
sample program).
In the previous versions the
PR_DF_RFID_FACE+index
was used for getting the desired image, in the new implementation multiple document fields of the same type are identified using a unique identifier and an index. For getting the first RFID image only the
PR_DF_RFID_FACE
must be specified as parameter for the function. The
PR_DF_RFID_FACE+1
form is deprecated but for compatibility reasons the old form is converted implicitly.
The new version adds the framework for handling multiple RFID chips at the same time. For example if a VISA containing an RFID chip is added to an
MRTD, the two chips in the range must be distinguished and handled properly.
Two new functions were added for connecting and disconnecting the used RFID chip. For more information please check the Passport Reader Programmers Manual and the sample programs.
The two versions of the Passport Reader are
fully run-time compatible, but there are some changes in the type of the return values, and function parameters.
For C/C++ programs:
- The pr_getdevicelist (C) and GetDeviceList (C++) function doesn't have the calibrated parameter anymore because in case of a normal process it is unused and it might have given wrong results in some cases. Use the pr_iscalibrated (C) or IsCalibrated (C++) function after opening a device instead.
For C++ programs:
- Functions that returned classes now return pointers to the classes.
This modification was necessary because the creation of the empty classes had overridden the error codes and messages.
The following functions are affected: FieldImage, GetImage, GetOcr, GetMrz, GetBarcode, GetDocumentRect, Recognize, ResolveMrzText, ResolveRfidData, CompareFace, LoadDocument, GetDocumentRoot.
If you use any of these functions please don't forget to delete the returned class and free the allocated memory after finishing using it. Please pay extra attention in case of using the FieldImage function. Compilers might not warn you about the changing of the return type, and if it is left unchanged you might get empty images.
- The CaptureStart and CaptureStatus functions return the request id as return value instead of using referenced parameter.
For programs using ActiveX technology:
- The GetError method is hidden from now on. This means that the function will not appear after updating the Delphi packages or C++ classes of the
PrApi.ocx
. The GetErrorCode and GetErrorString methods can be used instead.