DIN CWA 14050-16-2001 en 5264 Extensions for Financial Services (XFS) interface specification - Release 3 0 - Part 16 Application Programming Interface (API) Service Provider Inter.pdf

1、April 2001Extensions for Financial Services (XFS) interface specification Release 3.0 Part 16: Application Programming Interface (API) Service Provider Interface (SPI) Migration from Version 2.0(see CWA 13449) to Version 3.0 (this CWA) Programmers ReferenceCWA 14050-16Englische Fassung CWA 14050-16:

2、2000ICS 35.200; 35.240.15; 35.240.40Erweiterungen fr die Schnittstellenspezifikation fr Finanzdienst-leistungen (XFS) Version 3.0 Teil 16: Application Programming Interface (API) Service ProviderInterface (SPI) Migration von Version 2.0 (siehe CWA 13449) zuVersion 3.0 (dieses CWA) Programmierhandbuc

3、hNationales VorwortDieses CEN Workshop Agreement CWA 14050-16, das vom CEN/ISSS XFS Workshop erarbeitet wurde,wird ausschlielich in englischer Sprache zur Verfgung gestellt.CEN Workshop Agreements werden im Rahmen eines Konsortiums entwickelt. Sie unterscheiden sich vonEuropischen Normen dadurch, da

4、ss sie grundstzlich kein ffentliches Einspruchsverfahren durchlaufenund dass auch keine nationale Meinungsbildung stattfindet. Im Gegensatz zu Europischen Normen, dieden Konsens aller interessierten Kreise darstellen, haben CEN Workshop Agreements lediglich dieZustimmung der unmittelbar beteiligten

5、Mitglieder des Konsortiums gefunden.Fr den Inhalt sind ausschlielich die Mitglieder des Konsortiums verantwortlich (siehe ergnzendeHinweise im CWA-Vorwort). Weder das CEN-Zentralsekretariat, noch die CEN-Mitglieder haben den Inhaltauf eventuelle Fehler oder Widersprche zu Normen und Rechtsvorschrift

6、en geprft.Fortsetzung 27 Seiten CWA Beuth Verlag GmbH, 2001 .Jede Art der Vervielfltigung, auch auszugsweise, Ref. Nr. DIN CWA 14050-16:2001-04nur mit Genehmigung des Beuth Verlages gestattet. RW DIN CWA Preisgr. 04Alleinverkauf der Normen durch Beuth Verlag GmbH, 10772 Berlin Leerseite Rue de Stass

7、art, 36 B-1050 BruxellesTel : +32 2 550 08 11 Fax : +32 2 550 08 19EUROPEAN COMMITTEE FOR STANDARDIZATION COMIT EUROPEN DE NORMALISATION EUROPISCHES KOMITEE FR NORMUNG WORKSHOPCWA 14050-16AGREEMENTNovember 2000ICS 35.200; 35.240.15; 35.240.40Extensions for Financial Services (XFS) interface specific

8、ation -Release 3.0 - Part 16: Application Programming Interface (API) - ServiceProvider Interface (SPI) - Migration from Version 2.0 (see CWA 13449) toVersion 3.0 (this CWA) - Programmers Reference 2000 CEN All rights of exploitation in any form and by any means reserved world-wide forCEN National M

9、embersRef. No CWA 14050-16:2000 EThis CEN Workshop Agreement can in no way be held as being an official standardas developed by CEN National Members.Page 2CWA 14050-16:2000Table of ContentsForeword31. General.52. New Chapters 52.1 Vendor Dependent Mode 52.2 References 53. Changes to existing Chapter

10、s53.1 Configuration Information 53.2 Exclusive Service and Device Access . 93.3 Lock Policy for Independant Devices 93.4 Notification Mechanisms Registering for Events 104. Changes to Application Programming Interface (API) Functions.114.1 WFSExecute . 114.2 WFSAsyncExecute. 124.3 WFSGetInfo 134.4 W

11、FSAsyncGetInfo 144.5 WFSOpen 154.6 WFSAsyncOpen . 155. Changes to Service Provider Interface (SPI) Functions 155.1 WFPExecute . 155.2 WFPGetInfo 176. Changes to Configuration Functions 186.1 WFMCreateKey. 187. New Events 197.1 Lock Requested . 198. Changes to existing Events .198.1 Device Status Cha

12、nges . 198.2 Hardware and Software Errors .209. New Error Codes .2110. Changes to C Header files2210.1 XFSAPI.H. 2210.2 XFSCONF.H 27Page 3CWA 14050-16:2000ForewordThis CWA is revision 3.0 of the XFS interface specification.The move from an XFS 2.0 specification (CWA 13449) to a 3.0 specification has

13、 been prompted by a series offactors.Initially, there has been a technical imperative to extend the scope of the existing specification of the XFS Managerto include new devices, such as the Card Embossing Unit.Similarly, there has also been pressure, through implementation experience and the advance

14、 of the Microsofttechnology, to extend the functionality and capabilities of the existing devices covered by the specification.Finally, it is also clear that our customers and the market are asking for an update to a specification, which is nowover 2 years old. Increasing market acceptance and the n

15、eed to meet this demand is driving the Workshop towardsthis release.The clear direction of the CEN/ISSS XFS Workshop, therefore, is the delivery of a new Release 3.0 specificationbased on a C API. It will be delivered with the promise of the protection of technical investment for existingapplication

16、s and the design to safeguard future developments.The CEN/ISSS XFS Workshop gathers suppliers as well as banks and other financial service companies. A list ofcompanies participating in this Workshop and in support of this CWA is available from the CEN/ISSS Secretariat.This CWA was formally approved

17、 by the XFS Workshop meeting on 2000-10-18. The specification is continuouslyreviewed and commented in the CEN/ISSS Workshop on XFS. It is therefore expected that an update of thespecification will be published in due time as a CWA, superseding this revision 3.0.The CWA is published as a multi-part

18、document, consisting of:Part 1: Application Programming Interface (API) - Service Provider Interface (SPI); Programmers ReferencePart 2: Service Classes Definition; Programmers ReferencePart 3: Printer Device Class Interface - Programmers ReferencePart 4: Identification Card Device Class Interface -

19、 Programmers ReferencePart 5: Cash Dispenser Device Class Interface - Programmers ReferencePart 6: PIN Keypad Device Class Interface - Programmers ReferencePart 7: Check Reader/Scanner Device Class Interface - Programmers ReferencePart 8: Depository Device Class Interface - Programmers ReferencePart

20、 9: Text Terminal Unit Device Class Interface - Programmers ReferencePart 10: Sensors and Indicators Unit Device Class Interface - Programmers ReferencePart 11: Vendor Dependent Mode Device Class Interface - Programmers ReferencePart 12: Camera Device Class Interface - Programmers ReferencePart 13:

21、Alarm Device Class Interface - Programmers ReferencePart 14: Card Embossing Unit Class Interface - Programmers ReferencePart 15: Cash In Module Device Class Interface- Programmers ReferencePart 16: Application Programming Interface (API) - Service Provider Interface (SPI) - Migration from Version 2.

22、0(see CWA 13449) to Version 3.0 (this CWA) - Programmers ReferencePart 17: Printer Device Class Interface - Migration from Version 2.0 (see CWA 13449) to Version 3.0 (this CWA) -Programmers ReferencePart 18: Identification Card Device Class Interface - Migration from Version 2.0 (see CWA 13449) to V

23、ersion 3.0(this CWA) - Programmers ReferencePage 4CWA 14050-16:2000Part 19: Cash Dispenser Device Class Interface - Migration from Version 2.0 (see CWA 13449) to Version 3.0 (thisCWA) - Programmers ReferencePart 20: PIN Keypad Device Class Interface - Migration from Version 2.0 (see CWA 13449) to Ve

24、rsion 3.0 (thisCWA) - Programmers ReferencePart 21: Depository Device Class Interface - Migration from Version 2.0 (see CWA 13449) to Version 3.0 (thisCWA) - Programmers ReferencePart 22: Text Terminal Unit Device Class Interface - Migration from Version 2.0 (see CWA 13449) to Version 3.0(this CWA)

25、- Programmers ReferencePart 23: Sensors and Indicators Unit Device Class Interface - Migration from Version 2.0 (see CWA 13449) toVersion 3.0 (this CWA) - Programmers ReferencePart 24: Camera Device Class Interface - Migration from Version 2.0 (see CWA 13449) to Version 3.0 (this CWA)- Programmers R

26、eferencePart 25: Identification Card Device Class Interface - PC/SC Integration GuidelinesIn addition to these Programmers Reference specifications, the reader of this CWA is also referred to acomplementary document, called Release Notes. The Release Notes contain clarifications and explanations on

27、theCWA specifications, which are not requiring functional changes. The current version of the Release Notes isavailable online from http:/www.cenorm.be/isss/Workshop/XFS.The information in this document represents the Workshops current views on the issues discussed as of the date ofpublication. It i

28、s furnished for informational purposes only and is subject to change without notice. CEN/ISSSmakes no warranty, express or implied, with respect to this document.Page 5CWA 14050-16:20001. GeneralIn the Configuration Information chapter the reference to Windows 3.1 and Windows for Workgroups is remov

29、ed.The configuration information is now partly moved to HKEY_LOCAL_MACHINE and partly to HKEY_USERS.The hardware and software error events now return information about the physical service name and an action that isrequired to manage the error.2. New Chapters2.1 Vendor Dependent ModeXFS compliant ap

30、plications must comply with the following:Every XFS application should open a session with the VDM ServiceProvider passing a valid ApplId andthen register for all VDM entry and exit notices.Before opening any session with any other XFS Service Provider, check the status of theVDM Service Provider. I

31、f Vendor Dependent Mode is not “Inactive”, do not open a session.When getting a VDM entry notice, close all open sessions with all other XFS Service Providers as soon aspossible and issue an acknowledgement for the entry to VDM.When getting a VDM exit notice, acknowledge at once.When getting a VDM e

32、xited notice, re-open any required sessions with other XFS Service Providers.This is mandatory for self-service but optional for branch.2.2 References1. XFS Service Classes Definition, Programmers Reference Revision 3.00, October 18, 20003. Changes to existing Chapters3.1 Configuration InformationTh

33、e XFS Manager uses its configuration information to define the relationships among the applications and theservice providers. In particular, this information defines the mapping between the logical service interface presentedat the API (via logical service name) and the appropriate service provider

34、entry points.The configuration information also includes specific information about logical services and service providers, someof which is common to all solution providers; it may also include information about physical services, if any arepresent on the system, and vendor-specific information. The

35、 location of the information is transparent to bothapplications and service providers; they always store and retrieve it using the configuration functions provided bythe XFS Manager, as described in Section 7, for portability across Windows platforms.It is the responsibility of solution providers, a

36、nd the developers of each service provider, to implement theappropriate setup and management utilities, to create and manage the configuration information about the XFSsubsystem configuration and its service providers, using the configuration functions.These functions are used by service providers a

37、nd applications to write and retrieve the configuration informationfor a XFS subsystem, which is stored in a hierarchical structure called the Windows Registry. The structure and thefunctions are based on the Win32 Registry architecture and API functions, and are implemented in Windows NT/98and futu

38、re versions of Windows using the Registry and the associated functions.Page 6CWA 14050-16:2000Each node in the configuration registry is called a key, each having a name and (optionally) values. All valuesconsist of a name and data pair, both null-terminated character strings. There are two logical

39、groupings of XFSRegistry information; local PC dependent configuration information and user dependent configuration information.The local PC dependent configuration information is stored beneath the following Registry key.HKEY_LOCAL_MACHINEXFSSOFTWAREUser dependent configuration information is store

40、d in the HKEY_USERS section of the Registry.HKEY_USERSDefault orUser IDXFSWithin the local PC dependent configuration information are stored three XFS related keys;XFS_MANAGER Beneath this key are values and/or keys for information that the XFS Manager createsand uses.SERVICE_PROVIDERS Beneath this

41、key is a key for each XFS compliant service provider.PHYSICAL_SERVICES Beneath this key are physical attachment configuration information, defined bythe solution provider.Within the User dependent configuration information is stored the following LOGICAL_SERVICES key:LOGICAL_SERVICES Beneath this ke

42、y is defined a key for each XFS logical service (ie: thelpszLogicalName parameter of the WFSOpen, WFSAsyncOpen and WFPOpen functions)The configuration functions provide the capabilities to create, enumerate, open and delete keys, and to set, queryand delete values within each key. Vendor-provided co

43、nfiguration utility programs set up the registry structure andits contents, using these functions. Configured Registry values and keys define how the XFS subsystem, services andproviders are configured. These are used by the XFS Manager, applications and service providers. Note that vendor-specific

44、information may be added to any key in this structure, using optional values.Page 7CWA 14050-16:2000The figure below illustrates the full structure of the local PC dependent configuration information.HKEY_LOCAL_MACHINEXFSSOFTWAREXFS_MANAGER SERVICE_PROVIDERS PHYSICAL_SERVICESXFSInfo 1XFSInfo NSPInfo

45、 1SPInfo NPSInfo 1PSInfo NThe XFS_MANAGER key has the following optional values:TraceFile the name of the file containing trace data. If this value is not set in the configuration, trace data is written to the default file pathname C:XFSTRACE.LOG.ShareFilename the name of the memory mapped file used

46、 by the memory management functions of the XFS Manager.ShareFilesize the size of the memory mapped file used by the memory management functions of the XFS Manager.Some additional values could be also defined in the XFS SDK release notes. Please refer to the related document formore information.Benea

47、th the SERVICE_PROVIDERS key there are keys for each individual service providers, the keys are theservice provider names. Each of these keys has three mandatory values:dllname the name of the file containing the service provider DLLvendor_name the name of the supplier of this service providerversio

48、n the version number of this service providerThe PHYSICAL_SERVICES keys are fully vendor dependent.Page 8CWA 14050-16:2000The figure below illustrates the full structure of the User dependent configuration information.HKEY_USERSDefault orUser IDXFSLSInfo 1LSInfo NLOGICAL_SERVICESBeneath the LOGICAL_

49、SERVICES key there are keys for each individual service providers, the keys are the logicalservice names. Each of these keys has two mandatory values:class the service class of the logical service; (see the Service Class Definition Documentfor the standard values)provider the name of the service provider that provides the logical service(the key name of the corresponding service provider key)The User Id key is only applicable to the Windows Terminal Server platform. The User Id is the user nameassociated