a3yGg4wX

1EUROPEAN COMMITTEE FOR STANDARDIZATION
2COMITÉ EUROPÉEN DE NORMALISATION EUROPÄISCHES KOMITEE FÜR NORMUNG CEN-CENELEC Management Centre: Avenue Marnix 17, B-1000 Brussels
3© 2015 CEN All rights of exploitation in any form and by any means reserved worldwide for CEN national Members. Ref. No.:CWA 16926-1:2015 E
4CEN
5WORKSHOP
6AGREEMENT
7CWA 16926-1
8August 2015
9ICS 35.240.15; 35.200; 35.240.40
10English version
11Extensions for Financial Services (XFS) interface specification
12Release 3.30 - Part 1: Application Programming Interface (API) -
13Service Provider Interface (SPI) - Programmer's Reference
14This CEN Workshop Agreement has been drafted and approved by a Workshop of representatives of interested parties, the constitution of which is indicated in the foreword of this Workshop Agreement. The formal process followed by the Workshop in the development of this Workshop Agreement has been endorsed by the National Members of CEN but neither the National Members of CEN nor the CEN-CENELEC Management Centre can be held accountable for the
15technical content of this CEN Workshop Agreement or possible conflicts with standards or legislation. This CEN Workshop Agreement can in no way be held as being an official standard developed by CEN and its Members. This CEN Workshop Agreement is publicly available as a reference document from the CEN Members National Standard Bodies. CEN members are the national standards bodies of Austria, Belgium, Bulgaria, Croatia, Cyprus, Czech Republic, Denmark, Estonia,
16Finland, Former Yugoslav Republic of Macedonia, France, Germany, Greece, Hungary, Iceland, Ireland, Italy, Latvia, Lithuania, Luxembourg, Malta, Netherlands, Norway, Poland, Portugal, Romania, Slovakia, Slovenia, Spain, Sweden, Switzerland, Turkey and United
17Kingdom.
18CWA 16926-1:2015 (E)
192
20Table of Contents
21European foreword ................................................................................................................... 6
221. Background to Release 3.30 ........................................................................................ 9
232. References ...................................................................................................................... 10
243. XFS (eXtensions for Financial Services) Overview.............................................. 11
253.1 Architecture ...................................................................................................................... 12
263.2 API and SPI Summary ....................................................................................................... 15
273.3 Device Classes ................................................................................................................. 16
283.4 Unicode Encoding Summary ............................................................................................ 17
294. Architectural and Implementation Issues............................................................... 18
304.1 The XFS Manager.............................................................................................................. 19
314.2 Service Providers ............................................................................................................. 20
324.2.1 Service Provider Functionality......................................................................................................................... 20
334.2.2 Service Provider “Packaging” .......................................................................................................................... 20
344.3 Asynchronous, Synchronous and Immediate Functions .................................................. 21
354.3.1 Asynchronous Functions ................................................................................................................................... 21
364.3.2 Synchronous Functions ..................................................................................................................................... 21
374.3.3 Immediate Functions.......................................................................................................................................... 22
384.4 Processing API Functions ................................................................................................ 23
394.5 Opening a Session............................................................................................................ 24
404.6 Closing a Session ............................................................................................................. 25
414.7 Configuration Information ................................................................................................ 26
424.8 Exclusive Service and Device Access .............................................................................. 30
434.8.1 Lock Policy for Independent Devices ............................................................................................................. 30
444.8.2 Compound Devices ............................................................................................................................................ 31
454.9 Timeout............................................................................................................................. 33
464.10 Function Status Return ..................................................................................................... 34
474.11 Notification Mechanisms - Registering for Events ............................................................ 35
484.12 Application Processes, Threads and Blocking Functions ................................................ 37
494.13 Vendor Dependent Mode .................................................................................................. 39
504.14 Memory Management........................................................................................................ 40
514.15 Command Synchronization .............................................................................................. 42
524.16 Binary Interface ................................................................................................................ 43
535. Application Programming Interface (API) Functions .......................................... 44
545.1 WFSCancelAsyncRequest ................................................................................................ 46
555.2 WFSCancelBlockingCall ................................................................................................... 47
565.3 WFSCleanUp..................................................................................................................... 48
575.4 WFSClose ......................................................................................................................... 49
585.5 WFSAsyncClose ............................................................................................................... 50
595.6 WFSCreateAppHandle ...................................................................................................... 51
60CWA 16926-1:2015 (E)
613
625.7 WFSDeregister.................................................................................................................. 52
635.8 WFSAsyncDeregister........................................................................................................ 53
645.9 WFSDestroyAppHandle .................................................................................................... 55
655.10 WFSExecute ..................................................................................................................... 56
665.11 WFSAsyncExecute ........................................................................................................... 58
675.12 WFSFreeResult ................................................................................................................. 60
685.13 WFSGetInfo....................................................................................................................... 61
695.14 WFSAsyncGetInfo............................................................................................................. 63
705.15 WFSIsBlocking ................................................................................................................. 65
715.16 WFSLock .......................................................................................................................... 66
725.17 WFSAsyncLock ................................................................................................................ 68
735.18 WFSOpen.......................................................................................................................... 70
745.19 WFSAsyncOpen................................................................................................................ 73
755.20 WFSRegister ..................................................................................................................... 76
765.21 WFSAsyncRegister ........................................................................................................... 77
775.22 WFSSetBlockingHook....................................................................................................... 79
785.23 WFSStartUp ...................................................................................................................... 80
795.24 WFSUnhookBlockingHook ............................................................................................... 82
805.25 WFSUnlock ....................................................................................................................... 83
815.26 WFSAsyncUnlock ............................................................................................................. 84
826. Service Provider Interface (SPI) Functions ............................................................ 85
836.1 WFPCancelAsyncRequest ................................................................................................ 86
846.2 WFPClose ......................................................................................................................... 87
856.3 WFPDeregister.................................................................................................................. 88
866.4 WFPExecute ..................................................................................................................... 90
876.5 WFPGetInfo....................................................................................................................... 92
886.6 WFPLock .......................................................................................................................... 94
896.7 WFPOpen.......................................................................................................................... 95
906.8 WFPRegister ..................................................................................................................... 98
916.9 WFPSetTraceLevel............................................................................................................ 99
926.10 WFPUnloadService ......................................................................................................... 100
936.11 WFPUnlock ..................................................................................................................... 101
947. Support Functions ...................................................................................................... 102
957.1 WFMAllocateBuffer ......................................................................................................... 102
967.2 WFMAllocateMore........................................................................................................... 103
977.3 WFMFreeBuffer ............................................................................................................... 104
987.4 WFMGetTraceLevel......................................................................................................... 105
997.5 WFMKillTimer ................................................................................................................. 106
1007.6 WFMOutputTraceData..................................................................................................... 107
1017.7 WFMReleaseDLL............................................................................................................. 108
102CWA 16926-1:2015 (E)
1034
1047.8 WFMSetTimer ................................................................................................................. 109
1057.9 WFMSetTraceLevel ......................................................................................................... 110
1068. Configuration Functions ........................................................................................... 112
1078.1 WFMCloseKey ................................................................................................................ 112
1088.2 WFMCreateKey ............................................................................................................... 113
1098.3 WFMDeleteKey................................................................................................................ 114
1108.4 WFMDeleteValue ............................................................................................................. 115
1118.5 WFMEnumKey ................................................................................................................ 116
1128.6 WFMEnumValue.............................................................................................................. 117
1138.7 WFMOpenKey ................................................................................................................. 118
1148.8 WFMQueryValue ............................................................................................................. 119
1158.9 WFMSetValue.................................................................................................................. 120
1169. Data Structures ............................................................................................................ 121
1179.1 WFSRESULT ................................................................................................................... 121
1189.2 WFSVERSION ................................................................................................................. 122
11910. Messages....................................................................................................................... 123
12010.1 Command Completions and Events ............................................................................... 123
12110.1.1 Command Completion Messages .................................................................................................................. 123
12210.1.2 Event Messages................................................................................................................................................. 123
12310.2 WFS_TIMER_EVENT ....................................................................................................... 124
12410.3 WFS_SYSE_DEVICE_STATUS ........................................................................................ 125
12510.4 WFS_SYSE_UNDELIVERABLE_MSG .............................................................................. 126
12610.5 WFS_SYSE_APP_DISCONNECT ..................................................................................... 127
12710.6 WFS_SYSE_HARDWARE_ERROR, WFS_SYSE_SOFTWARE_ERROR, WFS_SYSE_USER_ERROR and WFS_SYSE_FRAUD_ATTEMPT ............................................ 128
12810.7 WFS_SYSE_LOCK_REQUESTED.................................................................................... 130
12910.8 WFS_SYSE_VERSION_ERROR....................................................................................... 131
13011. Error Codes................................................................................................................... 132
13112. Appendix A - Planned Enhancements and Extensions .................................... 135
13212.1 Event and System Management...................................................................................... 136
13313. Appendix B - XFS Workshop Contacts ................................................................. 137
13414. Appendix C - ATM Devices Synchronization Flow............................................. 138
13514.1 Synchronized Media Ejection ......................................................................................... 138
13615. Appendix D – Win64 Migration Considerations .................................................. 139
13716. Appendix D - C-Header files ..................................................................................... 140
13816.1 XFSAPI.H ........................................................................................................................ 140
13916.2 XFSADMIN.H ................................................................................................................... 146
14016.3 XFSCONF.H .................................................................................................................... 147
141CWA 16926-1:2015 (E)
1425
14316.4 XFSSPI.H ........................................................................................................................ 149
144CWA 16926-1:2015 (E)
1456
146European foreword
147This CWA is revision 3.30 of the XFS interface specification.
148This CEN Workshop Agreement has been drafted and approved by a Workshop of representatives of interested parties on March 19th 2015, the constitution of which was supported by CEN following the public call for participation made on 1998-06-24. The specification is continuously reviewed and commented in the CEN/ISSS Workshop on XFS. It is therefore expected that an update of the specification will be published in due time as a CWA, superseding this revision 3.30.
149A list of the individuals and organizations which supported the technical consensus represented by the CEN Workshop Agreement is available from the CEN/XFS Secretariat. The CEN XFS Workshop gathered suppliers as well as banks and other financial service companies.
150The CWA is published as a multi-part document, consisting of:
151Part 1: Application Programming Interface (API) - Service Provider Interface (SPI) - Programmer's Reference
152Part 2: Service Classes Definition - Programmer's Reference
153Part 3: Printer and Scanning Device Class Interface - Programmer's Reference
154Part 4: Identification Card Device Class Interface - Programmer's Reference
155Part 5: Cash Dispenser Device Class Interface - Programmer's Reference
156Part 6: PIN Keypad Device Class Interface - Programmer's Reference
157Part 7: Check Reader/Scanner Device Class Interface - Programmer's Reference
158Part 8: Depository Device Class Interface - Programmer's Reference
159Part 9: Text Terminal Unit Device Class Interface - Programmer's Reference
160Part 10: Sensors and Indicators Unit Device Class Interface - Programmer's Reference
161Part 11: Vendor Dependent Mode Device Class Interface - Programmer's Reference
162Part 12: Camera Device Class Interface - Programmer's Reference
163Part 13: Alarm Device Class Interface - Programmer's Reference
164Part 14: Card Embossing Unit Device Class Interface - Programmer's Reference
165Part 15: Cash-In Module Device Class Interface - Programmer's Reference
166Part 16: Card Dispenser Device Class Interface - Programmer's Reference
167Part 17: Barcode Reader Device Class Interface - Programmer's Reference
168Part 18: Item Processing Module Device Class Interface- Programmer's Reference
169Parts 19 - 28: Reserved for future use.
170Parts 29 through 47 constitute an optional addendum to this CWA. They define the integration between the SNMP standard and the set of status and statistical information exported by the Service Providers.
171Part 29: XFS MIB Architecture and SNMP Extensions - Programmer’s Reference
172Part 30: XFS MIB Device Specific Definitions - Printer Device Class
173Part 31: XFS MIB Device Specific Definitions - Identification Card Device Class
174Part 32: XFS MIB Device Specific Definitions - Cash Dispenser Device Class
175Part 33: XFS MIB Device Specific Definitions - PIN Keypad Device Class
176Part 34: XFS MIB Device Specific Definitions - Check Reader/Scanner Device Class
177Part 35: XFS MIB Device Specific Definitions - Depository Device Class
178Part 36: XFS MIB Device Specific Definitions - Text Terminal Unit Device Class
179Part 37: XFS MIB Device Specific Definitions - Sensors and Indicators Unit Device Class
180Part 38: XFS MIB Device Specific Definitions - Camera Device Class
181CWA 16926-1:2015 (E)
1827
183Part 39: XFS MIB Device Specific Definitions - Alarm Device Class
184Part 40: XFS MIB Device Specific Definitions - Card Embossing Unit Class
185Part 41: XFS MIB Device Specific Definitions - Cash-In Module Device Class
186Part 42: Reserved for future use.
187Part 43: XFS MIB Device Specific Definitions - Vendor Dependent Mode Device Class
188Part 44: XFS MIB Application Management
189Part 45: XFS MIB Device Specific Definitions - Card Dispenser Device Class
190Part 46: XFS MIB Device Specific Definitions - Barcode Reader Device Class
191Part 47: XFS MIB Device Specific Definitions - Item Processing Module Device Class
192Parts 48 - 60 are reserved for future use.
193Part 61: Application Programming Interface (API) - Migration from Version 3.20 (CWA 16374) to Version 3.30 (this CWA) - Service Provider Interface (SPI) - Programmer's Reference
194Part 62: Printer and Scanning Device Class Interface - Migration from Version 3.20 (CWA 16374) to Version 3.30 (this CWA) - Programmer's Reference
195Part 63: Identification Card Device Class Interface - Migration from Version 3.20 (CWA 16374) to Version 3.30 (this CWA) - Programmer's Reference
196Part 64: Cash Dispenser Device Class Interface - Migration from Version 3.20 (CWA 16374) to Version 3.30 (this CWA) - Programmer's Reference
197Part 65: PIN Keypad Device Class Interface - Migration from Version 3.20 (CWA 16374) to Version 3.30 (this CWA) - Programmer's Reference
198Part 66: Check Reader/Scanner Device Class Interface - Migration from Version 3.20 (CWA 16374) to Version 3.30 (this CWA) - Programmer's Reference
199Part 67: Depository Device Class Interface - Migration from Version 3.20 (CWA 16374) to Version 3.30 (this CWA) - Programmer's Reference
200Part 68: Text Terminal Unit Device Class Interface - Migration from Version 3.20 (CWA 16374) to Version 3.30 (this CWA) - Programmer's Reference
201Part 69: Sensors and Indicators Unit Device Class Interface - Migration from Version 3.20 (CWA 16374) to Version 3.30 (this CWA) - Programmer's Reference
202Part 70: Vendor Dependent Mode Device Class Interface - Migration from Version 3.20 (CWA 16374) to Version 3.30 (this CWA) - Programmer's Reference
203Part 71: Camera Device Class Interface - Migration from Version 3.20 (CWA 16374) to Version 3.30 (this CWA) - Programmer's Reference
204Part 72: Alarm Device Class Interface - Migration from Version 3.20 (CWA 16374) to Version 3.30 (this CWA) - Programmer's Reference
205Part 73: Card Embossing Unit Device Class Interface - Migration from Version 3.20 (CWA 16374) to Version 3.30 (this CWA) - Programmer's Reference
206Part 74: Cash-In Module Device Class Interface - Migration from Version 3.20 (CWA 16374) to Version 3.30 (this CWA) - Programmer's Reference
207Part 75: Card Dispenser Device Class Interface - Migration from Version 3.20 (CWA 16374) to Version 3.30 (this CWA) - Programmer's Reference
208Part 76: Barcode Reader Device Class Interface - Migration from Version 3.20 (CWA 16374) to Version 3.30 (this CWA) - Programmer's Reference
209Part 77: Item Processing Module Device Class Interface - Migration from Version 3.20 (CWA 16374) to Version 3.30 (this CWA) - Programmer's Reference
210In addition to these Programmer's Reference specifications, the reader of this CWA is also referred to a complementary document, called Release Notes. The Release Notes contain clarifications and explanations on the CWA specifications, which are not requiring functional changes. The current version of the Release Notes is available online from http://www.cen.eu/work/areas/ict/ebusiness/pages/ws-xfs.aspx.
211CWA 16926-1:2015 (E)
2128
213The information in this document represents the Workshop's current views on the issues discussed as of the date of publication. It is furnished for informational purposes only and is subject to change without notice. CEN makes no warranty, express or implied, with respect to this document.
214The formal process followed by the Workshop in the development of the CEN Workshop Agreement has been endorsed by the National Members of CEN but neither the National Members of CEN nor the CEN-CENELEC Management Centre can be held accountable for the technical content of the CEN Workshop Agreement or possible conflict with standards or legislation. This CEN Workshop Agreement can in no way be held as being an official standard developed by CEN and its members.
215The final review/endorsement round for this CWA was started on 2015-01-16 and was successfully closed on 2015-03-19. The final text of this CWA was submitted to CEN for publication on 2015-06-19.The specification is continuously reviewed and commented in the CEN Workshop on XFS. It is therefore expected that an update of the specification will be published in due time as a CWA, superseding this revision 3.30.
216Attention is drawn to the possibility that some of the elements of this document may be the subject of patent rights. CEN [and/or CENELEC] shall not be held responsible for identifying any or all such patent rights.
217According to the CEN-CENELEC Internal Regulations, the national standards organizations of the following countries are bound to implement this European Standard: Austria, Belgium, Bulgaria, Croatia, Cyprus, Czech Republic, Denmark, Estonia, Finland, Former Yugoslav Republic of Macedonia, France, Germany, Greece, Hungary, Iceland, Ireland, Italy, Latvia, Lithuania, Luxembourg, Malta, Netherlands, Norway, Poland, Portugal, Romania, Slovakia, Slovenia, Spain, Sweden, Switzerland, Turkey and the United Kingdom.
218Comments or suggestions from the users of the CEN Workshop Agreement are welcome and should be addressed to the CEN-CENELEC Management Centre.
219Revision History:
2203.00
221October 18, 2000
222Initial release.
2233.10
224November 29, 2007
225For a description of changes from version 3.00 to version 3.10 see the API 3.10 Migration document.
2263.20
227March 2, 2011
228For a description of changes from version 3.10 to version 3.20 see the API 3.20 Migration document.
2293.30
230March 19, 2015
231For a description of changes from version 3.20 to version 3.30 see the API 3.30 Migration document.
232CWA 16926-1:2015 (E)
2339
2341. Background to Release 3.30
235The CEN/XFS Workshop aims to promote a clear and unambiguous specification defining a multi-vendor software interface to financial peripheral devices. The XFS (eXtensions for Financial Services) specifications are developed within the CEN (European Committee for Standardization/Information Society Standardization System) Workshop environment. CEN Workshops aim to arrive at a European consensus on an issue that can be published as a CEN Workshop Agreement (CWA).
236The CEN/XFS Workshop encourages the participation of both banks and vendors in the deliberations required to create an industry standard. The CEN/XFS Workshop achieves its goals by focused sub-groups working electronically and meeting quarterly.
237Release 3.30 of the XFS specification is based on a C API and is delivered with the continued promise for the protection of technical investment for existing applications. This release of the specification extends the functionality and capabilities of the existing devices covered by the specification, but it does not include any new device classes. Notable enhancements include:
238• Enhanced reporting of Shutter Jammed Status and a new Shutter Status event for CDM, CIM and IPM.
239• Addition of a Synchronize command for all device classes, in order to allow synchronized action where necessary.
240• Directional Guidance Light support.
241• Addition of a CIM Deplete Command.
242• Support for EMV Intelligent Contactless Readers.
243• Support in PIN for Encrypting Touch Screen.
244• PIN Authentication functionality.
245• New PIN Encryption Protocols added for Chinese market.
246• PIN TR34 standard supported.
247CWA 16926-1:2015 (E)
24810
2492. References
2501. XFS Service Classes Definition, Programmer’s Reference Revision 3.30
2512. The Unicode Standard, Version 5.0, released on 9 November 2006. ISBN 0321480910
252CWA 16926-1:2015 (E)
25311
2543. XFS (eXtensions for Financial Services) Overview
255A key element of the Extensions for Financial Services is the definition of a set of APIs, a corresponding set of SPIs, and supporting services, providing access to financial services for Windows-based applications. The definition of the functionality of the services, of the architecture, and of the API and SPI sets, is outlined in this section, and described in detail in Sections 5 through 10.
256The specification defines a standard set of interfaces such that, for example, an application that uses the API set to communicate with a particular Service Provider can work with a Service Provider of another conformant vendor, without any changes.
257Although the Extensions for Financial Services define a general architecture for access to Service Providers from Windows-based applications, the initial focus of the CEN/XFS Workshop has been on providing access to peripheral devices that are unique to financial institutions. Since these devices are often complex, difficult to manage and proprietary, the development of a standardized interface to them from Windows-based applications and Windows operating systems can offer financial institutions and their solution providers immediate enhancements to productivity and flexibility.
258CWA 16926-1:2015 (E)
25912
2603.1 Architecture
261The architecture of the Extensions for Financial Services (XFS) system is shown below.
262Figure 2.1 - Extensions for Financial Services Architecture
263The applications communicate with Service Providers, via the Extensions for Financial Services Manager, using the API set. Most of these APIs can be invoked either "synchronously" (the Manager causes the application to wait until the API's function is completed) or "asynchronously" (the application regains control immediately, while the function is performed in parallel).
264The common deliverable in all implementations of this Extensions for Financial Services specification is the Extensions for Financial Services Manager, which maps the specified API to the corresponding SPI, then routes this request to the appropriate Service Provider. Multiple implementations of the XFS Manager exist from different vendors. For the definition of the binary interface, see section 4.16.
265The Manager uses the configuration information to route the API call (made to a "logical service" or a "logical device") to the proper Service Provider entry point (which is always local, even though the device or service that is the final target may be remote). Note that even though the API calls may be either synchronous or asynchronous, the SPI calls are always asynchronous.
266The developers of financial services to be used via XFS and the manufacturers of financial peripherals will be responsible for the development and distribution of Service Providers for their services and devices. A setup routine for each device or service will also be necessary to define the appropriate configuration information. This information will allow an application to request capability and status information about the devices and services available at any point in time.
267The primary functions of the Service Providers are to:
268• Translate generic (e.g. forms-based) service requests to service-specific commands.
269• Route the requests to either a local service or device, or to one on a remote system, effectively defining a peer-to-peer interface among Service Providers.
270• Arbitrate access by multiple applications to a single service or device, providing exclusive access when requested.
271• Manage the hardware interfaces to services or devices.
272• Manage the asynchronous nature of the services and devices in an appropriate manner, always presenting this capability to the XFS Manager and the applications via Windows messages.
273The system design supports solution of complex problems, often not addressed by current systems, by providing for maximum flexibility in all its capabilities:
274CWA 16926-1:2015 (E)
27513
276• Multiple Service Providers, developed by multiple vendors, can coexist in a single system and in a network. This is ensured by a standard messaging/data interface and a standard binary interface for the XFS Manager.
277• The service class definition is based on the logical functionalities of the service, with no assumption being made as to the physical configuration. A physical device that includes multiple distinct physical capabilities (referred to as a "compound device" in this specification) is treated as several logical services; the Service Provider resolves any conflicts. Note also that a logical service may include multiple physical devices (for example, a cash dispenser consisting of a note dispenser and coin dispenser).
278• Similarly, a physical device may be shared between two or more users (e.g. tellers), and the physical device synchronization is managed at the Service Provider level.
279• The API definition and associated services provide time-out functionality to allow applications to avoid deadlock of the type that can occur if two applications try to get exclusive access to multiple services at the same time.
280• The architecture is designed to provide a framework for future development of network and system monitoring, measurement, and management.
281Note that Figure 2.1 is a high level view of the architecture and, in particular, it makes no distinction between Service Providers and the services they manage. This specification focuses on Service Providers rather than on services, because the way a Service Provider communicates with a service is a vendor-specific internal design issue that applications and the XFS Manager are unaware of. In fact, there are many different ways that Service Providers can make services available to applications. Hence, this specification refers primarily to the Service Providers, since these are the modules with which the XFS Manager communicates. There are occasional references to 'service' where this is appropriate.
282Example Figure 2.2 below shows an XFS system supporting a set of financial peripherals. Note that in this framework the XFS Manager interfaces directly with a set of Service Providers that interface directly with the physical devices. Thus, the Service Providers are shown as implementing the Service Provider, service, and device driver functions, although these are more likely to be two or more separate layers. Many other configurations are possible.
283WorkStation 1WorkStation 2ApplicationWOSA/XFS APIWOSA/XFS SPIWOSA/XFS ManagerConfigurationInformationPassbook Printer Service ProviderVendor XPassbook Printer Service ProviderVendor YPassbook Printer Service ProviderVendor YMagnetic Card Reader Service ProviderVendor YPassbook PrinterVendor XPassbook PrinterVendor YMagneticCard ReaderVendor YWorkStation 3Passbook Printer Service ProviderVendor XPassbook PrinterVendor XApplicationWOSA/XFS APIWOSA/XFS SPIWOSA/XFS ManagerConfigurationInformationApplicationWOSA/XFS APIWOSA/XFS SPIWOSA/XFS ManagerConfigurationInformation
284Figure 2.2 - An XFS architecture example for a branch office banking system.
285It should also be noted that one vendor's Service Providers are not necessarily compatible with another vendor's, as
286CWA 16926-1:2015 (E)
28714
288shown in Figure 2.2. If one application has to access the same service class as implemented by different vendors, a Service Provider is installed for each vendor.
289CWA 16926-1:2015 (E)
29015
2913.2 API and SPI Summary
292Sections 5 through 8 of this document present the interfaces that allow a financial application to communicate in a standard fashion with financial services and devices. The functions are at a sufficiently high level to allow for seamless redirection to other parts of the underlying operating system. A printer, for example, might rely on a set of services provided by the operating system, but in order to handle the unique characteristics of a financial printer and application, the Service Provider would pre-process the command, then redirect the derived commands to the operating system's printing services. In other implementations, the printer might be supported entirely by XFS service mechanisms, and not use the operating system printing services in any way.
293The API is structured as sets of:
294• Basic functions, such as StartUp/CleanUp, Open/Close, Lock/Unlock, and Execute, that are common to all the Extensions for Financial Services device/service classes,
295• Administration functions, such as device initialization, reset, suspend or resume, used for managing devices and services, and
296• Specific commands, used to request information about a service/device, and to initiate device/service-specific functions; these are sent to devices and services as parameters of the GetInfo and Execute basic functions. These service-specific commands are specified in a set of separate specifications, one for each service class.
297To the maximum extent possible, the syntax of specific commands that are used with multiple device/service classes is kept consistent across all devices. A primary objective is to standardize function codes and structures for the widest possible variety of devices.
298The SPI is kept as similar as possible to the API. Some commands are processed exclusively by the XFS Manager, and so are not in the SPI, and there are minor differences in the specific parameters passed at the two interface levels.
299A typical scenario showing the usage of the APIs is shown below. This example illustrates the functions used to print a form.
300• StartUp (connects the application to the XFS Manager, including version negotiation)
301• Open (establishes a session between the application and the Service Provider)
302• Register (specifies the messages that the application should receive from the Service Provider)
303• Lock (obtains exclusive access to the service by the application)
304• multiple Execute functions, passing one or more specific commands:
305• Print_Form
306• etc.
307• Unlock (releases exclusive access to the service by the application)
308• Deregister (specifies that the application should no longer receive messages from the Service Provider)
309• Close (ends the session between the application and the Service Provider)
310• CleanUp (disconnects the application from the XFS Manager)
311Note that within a session (defined by Open and Close), an application may at any time change the classes of messages it wishes to receive from the Service Provider (using Register), and may either Lock the service only for specified periods (typically for each transaction), or for the entire session. Also, note that several of the commands are optional, depending on how the device is being managed and shared (i.e. Lock/Unlock, Register/Deregister).
312CWA 16926-1:2015 (E)
31316
3143.3 Device Classes
315The classes of devices that belong to the version 3.30 of the Extensions for Financial Services are described in the separate Service Class Definition Document.
316CWA 16926-1:2015 (E)
31717
3183.4 Unicode Encoding Summary
319If an XFS form or media file is UNICODE encoded then, consistent with the UNICODE standard [Ref. 2], the file must start with a Unicode Byte Order Mark (BOM) and the UTF-16 encoded data that follows must be in the byte order indicated by the BOM. The two-byte BOM prefix in a text file indicates a Little Endian (0xFFFE) or Big Endian (0xFEFF) notation. On a Windows operating system the byte order encoding is Little Endian.
320If command parameter data is UNICODE encoded then this data will be UTF-16 encoded and the byte order must be Little Endian. UNICODE command parameter will not start with a BOM.
321CWA 16926-1:2015 (E)
32218
3234. Architectural and Implementation Issues
324The remainder of this document provides the technical specifications for the CEN eXtensions for Financial Services (referred to hereafter as “XFS” for brevity).
325In this specification, the functions of the XFS Application Programming Interface (API) and Service Provider Interface (SPI) are always described in terms of providing a standardized, portable interface for applications to gain access to Service Providers. This architecture allows Service Providers to deliver an open-ended set of capabilities to financial applications based on the Microsoft Windows operating systems, including access to peripheral devices unique to financial institutions. Since the first priority of the CEN members for XFS implementations has been to provide this peripheral device access capability, the examples used relate primarily to device control and physical input/output.
326The key elements of the Extensions for Financial Services are the API definition and the corresponding SPI definition, used by the XFS Manager to communicate with the Service Providers, together with the set of supporting services provided by the XFS Manager. These elements are combined in an XFS implementation, providing access to financial devices and services for Windows-based applications.
327The specification defines a standard set of interfaces in order to provide multi-vendor interoperability: if an application uses the API to communicate successfully with a Service Provider, it should work with another conformant Service Provider of the same type, developed by another vendor, without any changes. To work with more than one hardware implementation of a device, an application must retrieve the device capability information - this will allow the application to successfully interact with different variants of the same hardware device. Applications that use the vendor specific fields of XFS commands may not be able to interact successfully with another vendor’s conformant Service Provider. Applications should isolate vendor specific access to devices in order to maximize consistent device control across multiple device Service Provider implementations. Any Service Provider that conforms to the SPI definition can work with a range of conformant applications.
328As new versions of the XFS device classes are developed and released, changes to the device class interface specifications are inevitable. Application exposure to these changes is controlled via the version negotiation process described later in this specification. Applications need to be updated to support new releases of XFS, but to minimize the migration effort it is recommended that they should be developed in such a way that they can handle additional error codes and new output literal values being added to existing commands within future versions of XFS in a graceful manner. In addition, applications must release the memory for all events received, this includes events that the application may be unaware at development time, i.e. the minimum processing for any XFS event must be the release of the memory associated with the event.
329For clarity, three prefixes are used in naming the function interfaces in XFS:
330Function type: Prefix
331Functions called by
332Functions provided by
333• API functions: WFS...
334• Applications
335• XFS Manager (and typically passed through to WFP functions)
336• SPI functions: WFP...
337• XFS Manager
338• Service Providers
339• Support/Configuration functions: WFM...
340• Service Providers
341• Applications
342• XFS Manager
343CWA 16926-1:2015 (E)
34419
3454.1 The XFS Manager
346The XFS Manager provides overall management of the XFS subsystem. The XFS Manager is responsible for mapping the API (WFS...) functions to SPI (WFP...) functions, and calling the appropriate vendor-specific Service Providers. Note that the calls are always to a local Service Provider.
347The XFS Manager determines which Service Provider to call using the logical name parameter of the WFSOpen or WFSAsyncOpen function. The logical name is the key providing access to the configuration information that defines the Service Class (e.g. printer, cash dispenser, etc.), the Service Type (e.g. receipt printer, journal printer, etc.) and the Service Provider (DLL file name), as well as additional information. The logical name must be unique at least within each workstation. See Sections 4.7 and 8 for discussions of configuration information access and management.
348The XFS Manager also provides the Support Functions (WFM...) defined in Section 7 and the Configuration Functions (also WFM...) defined in Section 8.
349Before an application is allowed to utilize any of the services managed by the XFS subsystem, it must first identify itself to the subsystem. This is accomplished using the WFSStartUp function. An application is only required to perform this function once, regardless of the number of XFS services it utilizes, so this function would typically be called during application initialization. Similarly, the complementary function, WFSCleanUp, is typically called during application shutdown. If an application exits or is shut down without issuing the WFSCleanUp function, the XFS Manager does the cleanup automatically, including the closing of any sessions with Service Providers the application has left open.
350The XFS Manager’s binary interface is described in section 4.16.
351CWA 16926-1:2015 (E)
35220
3534.2 Service Providers
354Each XFS service, for each vendor, is accessed via a service-specific module called a Service Provider. For example, vendor A's journal printer is accessed via vendor A's journal printer Service Provider, and vendor B's receipt printer is accessed via vendor B's receipt printer Service Provider.
355The following sections describe the functionality and packaging of Service Providers.
3564.2.1 Service Provider Functionality
357The primary functions of XFS Service Providers, working in conjunction with their respective services and/or device drivers, are as follows. Note that how these functions are implemented is left to the Service Provider developer.
358• Route the requests to the device or service, which may be on a remote workstation. Service Providers may communicate with remote services in a variety of ways, such as NetBIOS, named pipes, RPC (Remote Procedure Calls), Windows Sockets, proprietary network programming interfaces, etc.
359• Translate the generic requests to resource specific commands. Note that this involves translation not just to service-specific commands, but to the commands native to the resource being used. For example, the commands would not be translated to "Receipt Printer Service" commands, but to "Brand X, Model Y Receipt Printer" commands. For example, a driver may implement device-specific translation tables or processes itself, or utilize standard operating system device interfaces (such as the Windows GDI), if they exist for the particular peripheral.
360• Arbitrate access to the resource by multiple applications. Note that when a physical device includes multiple peripherals (for example, a receipt and journal printer in a single unit), this may also include arbitration of the sub-devices.
361• Manage the interface to the resource. When physical devices are being controlled, this includes managing the hardware interface to the device. For example, the Service Providers may use standard operating system device drivers, vendor-written proprietary device drivers, etc.
362• Manage the asynchronous nature of the services in a consistent manner with respect to the applications. The asynchronous nature of the SPI must always be presented back to the XFS Manager and the applications in the form of Windows messages.
363• Error recovery. In some kinds of software failures, such as an application crash, the Service Provider loses connection with the application. In this situation, the Service Provider is responsible for an “orderly” shutdown of the session with that application. In particular, the Service Provider generates a system event (see Section 4.11) indicating that the connection was lost, and if any requests from the application were outstanding, it generates a system event for each completion that would normally have generated a completion message to the application.
3644.2.2 Service Provider “Packaging”
365XFS Service Providers can be “packaged” into DLLs in a variety of ways:
366• One Service Provider per DLL; for example, a vendor might produce a journal printer DLL, a receipt printer DLL, a cash dispenser DLL, etc.
367• Multiple Service Providers per DLL; for example a vendor might produce a DLL which contains the Service Providers for all XFS-compliant printers.
368• All Service Providers for a specific vendor in a single DLL.
369CWA 16926-1:2015 (E)
37021
3714.3 Asynchronous, Synchronous and Immediate Functions
372Windows and XFS are built on an event-driven, asynchronous model. However, the XFS design allows an application using its interfaces to behave in either an asynchronous or synchronous manner. Thus the API supports two versions of each of the appropriate functions (e.g. an application can request to lock a service using either the asynchronous WFSAsyncLock function or the synchronous WFSLock function).
373Each XFS API function operates in one of three synchronization modes: asynchronous, synchronous or immediate. These are described in the following sections.
374Note that the SPI is purely an asynchronous interface, so all SPI functions are either asynchronous or immediate; there are no synchronous SPI functions.
375See Sections 5 and 6 for a summary of the API and SPI functions and their synchronization modes.
3764.3.1 Asynchronous Functions
377Asynchronous mode is used for operations which may take an indeterminate amount of time to complete. Performing an operation in an asynchronous, as opposed to a synchronous, mode allows the application to operate in Windows' native event-driven, message-based manner. The processing of an asynchronous request (e.g. WFSAsyncExecute) is as follows:
378• The application calls the XFS Manager.
379• The XFS Manager generates a sequence number, the RequestID, assigns it to the request, and calls the Service Provider.
380• The Service Provider schedules the request for deferred processing and immediately returns to the XFS Manager.
381• The XFS Manager returns the RequestID to the application, with a status indicating that the request has been initiated and is being processed.
382• At some point, the Service Provider processes the deferred request.
383• On completion, the Service Provider posts a completion message to the window handle specified by the application in its original call. For flexibility, an application using asynchronous functions can specify a different window for each request. The message contains a pointer to a WFSRESULT data structure defining the results of the request, including the RequestID, the status code and the other relevant data.
3844.3.2 Synchronous Functions
385Synchronous mode is also used when an operation can take an indeterminate amount of time to complete, but the application wishes to handle the function in a sequential manner. The XFS Manager does not return control to the application until the operation has completed, thus synchronous functions are referred to as blocking. Each synchronous call made by an application is translated by the XFS Manager into its asynchronous SPI counterpart before being passed to the Service Provider.
386If a blocking operation is not completed immediately in a Windows 3.x system, the XFS Manager executes a Windows message loop on behalf of the calling thread, thereby keeping the Windows system running. See Section 4.12 for a more detailed discussion of process, threads and message loops. In Windows NT, the calling application thread is blocked on request completion. A thread may have only one blocking XFS call outstanding at any one time. See Section 4.12 for additional discussion of the management of synchronous functions, including replacement of the default message loop.
387The processing of a synchronous request (e.g. WFSExecute) is as follows:
388• The application calls the XFS Manager.
389• The XFS Manager translates the request into an asynchronous SPI, generates a RequestID to track the request, provides its own window handle to receive the completion message, and calls the Service Provider DLL.
390• The Service Provider schedules the request for deferred processing and immediately returns to the XFS Manager.
391• The XFS Manager simulates synchronous processing as described above and in Section 4.12.
392• At some point, the Service Provider processes the deferred request.
393• On completion, the Service Provider posts a completion message to the window handle specified by the XFS Manager. The message contains a pointer to a WFSRESULT data structure defining the results of the request, including the RequestID, the status code and the other relevant data.
394• The XFS Manager unpacks the information from the completion message into the appropriate parameters, and
395CWA 16926-1:2015 (E)
39622
397returns them to the application, unblocking the original application request.
3984.3.3 Immediate Functions
399These are API functions that are not either asynchronous or synchronous. Typically, immediate APIs are those which do not communicate with a service or a physical device (or use the network in any other way) and are thus guaranteed to complete immediately, whether successfully or not. They are handled in two ways:
400• Processed entirely by the XFS Manager, which returns immediately to the application. Examples include WFSStartUp, and WFSSetBlockingHook.
401• Passed by the XFS Manager to the Service Provider as an immediate SPI. The Service Provider processes the request and immediately returns to the XFS Manager, which returns immediately to the application. Examples include WFSCancelAsyncRequest and WFMSetTraceLevel.
402CWA 16926-1:2015 (E)
40323
4044.4 Processing API Functions
405When an application calls an XFS API function one of the following processing scenarios takes place. Note that this classification is distinct from the API synchronization modes discussed above. See Section 6 for the mapping of API functions to SPI functions.
406• The function is converted by the XFS Manager directly into the corresponding SPI function (e.g. WFSAsyncRegister).
407• The XFS Manager performs some preprocessing and then converts the function into the corresponding SPI function (e.g. WFSAsyncExecute).
408• The XFS Manager performs some preprocessing and then translates the API function to a different SPI function, which it passes to the Service Provider. Most of the synchronous API functions (e.g. WFSLock) are of this type, since they are translated to their asynchronous SPI equivalents.
409• The XFS Manager performs some preprocessing and then translates the API function to multiple SPI functions, which it passes to the Service Provider (e.g. WFSOpen).
410• The function is completely processed inside the XFS Manager (e.g. WFSIsBlocking, WFSSetBlockingHook).
411Service Providers (and sometimes applications) call the XFS Manager for the support functions defined in Section 7 and for the configuration functions defined in Section 8.
412CWA 16926-1:2015 (E)
41324
4144.5 Opening a Session
415Once a connection between an application and the XFS Manager has successfully been negotiated (via WFSStartUp), the application establishes a virtual session with a Service Provider by issuing a WFSOpen (or WFSAsyncOpen) request. Opens are directed towards “logical services” as defined in the XFS configuration. A service handle (hService) is assigned to the session, and is used in all the calls to the service in the lifetime of the session.
416Note that applications may optionally choose to explicitly manage the concept of “application identity” when they need to use interdependent compound devices (see Section 4.8.2). This is achieved by using the WFSCreateAppHandle function to get an application handle (hApp), which is unique within the system. This function can be called multiple times to obtain multiple unique handles. An application handle parameter is then used in the WFSOpen function, directing the Service Provider to bind the specified application handle to the session being initiated. This allows a single application process (potentially multi-threaded) to act as multiple applications to the XFS subsystem, to allow effective use of interdependent compound devices. An example of a case in which this could be useful is an application using the Multiple Document Interface (MDI); the application could associate an application handle with each MDI child window. See Section 4.8.2 for additional discussion of the use of application handles with compound devices. Note that neither service nor application handles may be shared among two or more applications.
417The actions performed by the XFS Manager on an open are as follows:
418• Retrieves the configuration information defining the specified logical service, in order to determine the DLL name of the Service Provider. The logical service name is the key to the configuration information.
419• Loads the DLL containing the requested Service Provider, if it is not already loaded.
420• Performs pre-processing and translation as necessary, depending on whether the synchronous or asynchronous open API has been issued.
421• Generates a unique service handle (hService) that identifies the session with the Service Provider that is being established, to be passed back to the application as a parameter.
422• Calls the Service Provider's WFPOpen function, passing the parameters needed.
423The Service Provider does the following:
424• Performs version negotiation, using the parameters specifying the SPI version requested by the XFS Manager, and the service-specific interface version requested by the application.
425• Retrieves the configuration information.
426• Asynchronously establishes a session with the service specified in the configuration on the specified workstation, if necessary, relying on the transport facilities provided.
427• Upon completion of the request, posts a completion message (WFS_OPEN_COMPLETE), which goes to the application for a WFSAsyncOpen call, and to the XFS Manager for a WFSOpen call.
428Note that even if the service is locked by another application, the open function succeeds, as defined in Section 4.8, “Exclusive Service and Device Access.”
429An application programmer has at least two obvious choices as to when to perform the WFSOpen (and the complementary WFSClose) of the services it utilizes:
430• Open the services during application initialization, keep them open, and close them during application shutdown.
431• Perform the open each time the service is required, utilize it, and immediately close it.
432Each technique has its own advantages. For example, while the first example might provide better performance, the second might be easier to program. In any case, upon a successful completion of an open, the XFS subsystem returns a service handle which must be used for all subsequent communication with the service.
433Note that an application must perform an open for each logical service that it wishes to utilize, even if the services are of the same type. For example, if an application wishes to utilize two separate receipt printers, it must open two separate logical services.
434Furthermore, an application may need to open multiple logical services, even when a set of devices are housed in a single device. For example, consider a compound printer which includes both a receipt and a journal printer. If the application requires access to both the receipt and journal printer functions, it must open both a receipt logical service and a journal logical service.
435CWA 16926-1:2015 (E)
43625
4374.6 Closing a Session
438When an application no longer requires the use of a particular service, it issues a WFSClose or WFSAsyncClose request. The XFS subsystem then closes that session as follows:
439• The XFS Manager calls the Service Provider's WFPClose function.
440• The Service Provider schedules the request for deferred processing, and returns immediately to the XFS Manager. Note that at this point the service handle, hService, is no longer valid.
441• At some point, the Service Provider processes the deferred close request, communicating with the service as necessary to accomplish the request.
442• Requests that were issued by the application before the close are executed.
443• If the calling application has the service locked under the same hService, the Service Provider unlocks it automatically (following the standard lock policy as defined in Section 4.8).
444• The service cleans up its administrative information (removes WFSRegister entries etc.).
445If the XFS subsystem loses connection to an application, it closes the session as described above, and:
446• An “application disconnect” event (SYSTEM_EVENT class) is generated.
447• Since messages can no longer be posted to the application, any command completion and event notification messages from this service for the application are converted to “undeliverable message” events (SYSTEM_EVENT class).
448Note that it is required that some applications have registered for system events, or these events are effectively not reported.
449When a Service Provider receives a Close request for a session, its behavior may vary as follows,
450• When the session has no outstanding requests the Service Provider will complete the Close request (even if it is executing a command from another session or has outstanding deferred requests from another session).
451• When the session that issues the close request has an outstanding request then the Service Provider will defer the Close until all outstanding requests are complete.
452CWA 16926-1:2015 (E)
45326
4544.7 Configuration Information
455The XFS Manager uses its configuration information to define the relationships among the applications and the Service Providers. In particular, this information defines the mapping between the logical service interface presented at the API (via logical service name) and the appropriate Service Provider entry points.
456The configuration information also includes specific information about logical services and Service Providers, some of which is common to all solution providers; it may also include information about physical services, if any are present on the system, and vendor-specific information. The location of the information is transparent to both applications and Service Providers; they always store and retrieve it using the configuration functions provided by the XFS Manager, as described in Section 8, for portability across Windows platforms.
457It is the responsibility of solution providers, and the developers of each Service Provider, to implement the appropriate setup and management utilities, to create and manage the configuration information about the XFS subsystem configuration and its Service Providers, using the configuration functions.
458These functions are used by Service Providers and applications to write and retrieve the configuration information for an XFS subsystem, which is stored in a hierarchical structure called the Windows Registry. The structure and the functions are based on the Win32/Win64 Registry architecture and API functions, and are implemented in Windows NT/98 and future versions of Windows using the Registry and the associated functions.
459Each node in the configuration registry is called a key, each having a name and (optionally) values. All values consist of a name and data pair, both null-terminated character strings. There are two logical groupings of XFS Registry information; local PC dependent configuration information and user dependent configuration information.
460The local PC dependent configuration information is stored beneath the following Registry key.
461HKEY_LOCAL_MACHINEXFSSOFTWARE
462User dependent configuration information is stored in the HKEY_USERS section of the Registry.
463HKEY_USERSDefault orUser IDXFS
464CWA 16926-1:2015 (E)
46527
466Within the local PC dependent configuration information are stored the following XFS related keys;
467• XFS_MANAGER - Beneath this key are values and/or keys for information that the XFS Manager creates and uses.
468• SERVICE_PROVIDERS - Beneath this key is a key for each XFS compliant Service Provider.
469• PHYSICAL_SERVICES - Beneath this key are physical attachment configuration information, defined by the solution provider.
470• MANAGEMENT_PROVIDERS - Reserved for XFS SNMP Management. Beneath this key is a key for each XFS SNMP Managed Service.
471Within the user dependent configuration information is stored the following LOGICAL_SERVICES key:
472• LOGICAL_SERVICES - Beneath this key is defined a key for each XFS logical service (i.e.: the lpszLogicalName parameter of the WFSOpen, WFSAsyncOpen and WFPOpen functions).
473The configuration functions provide the capabilities to create, enumerate, open and delete keys, and to set, query and delete values within each key. Vendor-provided configuration utility programs set up the registry structure and its contents, using these functions. Configured Registry values and keys define how the XFS subsystem, services and providers are configured. These are used by the XFS Manager, applications and Service Providers. Note that vendor-specific information may be added to any key in this structure, using optional values.
474The figure below illustrates the full structure of the local PC dependent configuration information.
475HKEY_LOCAL_MACHINEXFSSOFTWAREXFS_MANAGERSERVICE_PROVIDERSPHYSICAL_SERVICESXFS Info 1XFS Info NSPInfo 1SPInfo NPSInfo 1PSInfo NMANAGEMENT_PROVIDERSMPInfo 1MPInfo N
476The XFS_MANAGER key has the following optional values:
477• 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 path\name C:\XFSTRACE.LOG.
478• ShareFilename the name of the memory mapped file used by the memory management functions of the XFS Manager.
479• ShareFilesize the size of the memory mapped file used by the memory management functions of the XFS Manager.
480• ShareMapAddr the address of the beginning of the XFS Manager Shared Memory. Care should be taken when using this value to control the load address of shared memory. When used, the address chosen should be consistently accessed across all XFS processes. A value of zero will result in the shared memory allocation being dynamic.
481Some additional values may also be defined in the implementation of the XFS Manager. Please refer to the related document for more information.
482CWA 16926-1:2015 (E)
48328
484Beneath the SERVICE_PROVIDERS key there are keys for each individual Service Providers, the keys are the Service Provider names. Each of these keys has three mandatory values:
485• dllname
486The name of the file containing the Service Provider DLL.
487• vendor_name
488The name of the supplier of this Service Provider.
489• version
490The version number of this Service Provider. This version number is a vendor specific Service Provider implementation version; it has no relation to the version of the standard.
491The PHYSICAL_SERVICES keys are fully vendor dependent.
492Beneath the MANAGEMENT_PROVIDERS key there are keys for each XFS SNMP Managed Service, the keys are the managed service names. The structure of these keys is defined within the XFS MIB Architecture specification.
493The figure below illustrates the full structure of the user dependent configuration information.
494HKEY_USERSDefault orUser IDXFSLSInfo 1LSInfo NLOGICAL_SERVICES
495Beneath the LOGICAL_SERVICES keys there are keys for each individual Service Provider the keys are the logical service names: Each of these keys have two mandatory values:
496• class the service class of the logical service; (see the Service Class Definition Document for the standard values)
497• provider the name of the Service Provider that provides the logical service (the key name of the corresponding Service Provider key)
498The ‘User Id’ key is only applicable to the Windows Terminal Server platform. The ‘User Id’ is the user name associated with the session in which the application is executing.
499An example of the content of the configuration information for is shown below. See Section 8 for the definitions of the configuration functions.
500CWA 16926-1:2015 (E)
50129
502[HKEY_USERS\.DEFAULT\XFS\LOGICAL_SERVICES\MyCurrencyDispenser]
503"class"="CDM"
504"provider"="CDM"
505[HKEY_USERS\.DEFAULT\XFS\LOGICAL_SERVICES\MyCardReader]
506"class"="IDC"
507"provider"="IDC"
508[HKEY_USERS\.DEFAULT\XFS\LOGICAL_SERVICES\MyJournalPrinter]
509"class"="PTR"
510"provider"="JPTR"
511[HKEY_USERS\.DEFAULT\XFS\LOGICAL_SERVICES\MyPassbookPrinter]
512"class"="PTR"
513"provider"="PPTR"
514[HKEY_USERS\.DEFAULT\XFS\LOGICAL_SERVICES\MyPinpad]
515"class"="PIN"
516"provider"="PIN"
517[HKEY_USERS\.DEFAULT\XFS\LOGICAL_SERVICES\MyReceiptPrinter]
518"class"="PTR"
519"provider"="RPTR"
520[HKEY_USERS\.DEFAULT\XFS\LOGICAL_SERVICES\MyStatementPrinter]
521"class"="PTR"
522"provider"="SPTR"
523[HKEY_LOCAL_MACHINE\SOFTWARE\XFS\SERVICE_PROVIDERS\CDM]
524"dllname"="C:\ Program Files \ABCTech\XFS PRODUCT\XFS CDM Service Provider\ABCTech_9827SP.dll"
525"vendor_name"="ABCTech Corporation"
526"version"="1.0.0"
527[HKEY_LOCAL_MACHINE\SOFTWARE\XFS\SERVICE_PROVIDERS\IDC]
528"dllname"="C:\Program Files\ABCTech\XFS PRODUCT\XFS IDC Service Provider\ABCTech_1212SP.dll"
529"vendor_name"="ABCTech Corporation"
530"version"="1.0.1"
531[HKEY_LOCAL_MACHINE\SOFTWARE\XFS\SERVICE_PROVIDERS\JPTR]
532"vendor_name"="ABCTech Corporation"
533"dllname"="C:\Program Files\ABCTech\XFS PRODUCT\XFS PTR Service Provider\ABCTech_9001SP.dll"
534"version"="1.2.4"
535[HKEY_LOCAL_MACHINE\SOFTWARE\XFS\SERVICE_PROVIDERS\PIN]
536"dllname"="C:\Program Files\ABCTech\XFS PRODUCT\XFS PIN Service Provider\ABCTech_1234SP.DLL"
537"vendor_name"="ABCTech Corporation"
538"version"="1.34.8"
539[HKEY_LOCAL_MACHINE\SOFTWARE\XFS\SERVICE_PROVIDERS\PPTR]
540"dllname"="C:\Program Files\ABCTech\XFS PRODUCT\XFS PTR Service Provider\ABCTech_2411SP.dll"
541"vendor_name"="ABCTech Corporation"
542"version"="1.2.3"
543[HKEY_LOCAL_MACHINE\SOFTWARE\XFS\SERVICE_PROVIDERS\RPTR]
544"dllname"="C:\Program Files\ABCTech\XFS PRODUCT\XFS PTR Service Provider\ABCTech_1028SP.dll"
545"vendor_name"="ABCTech Corporation"
546"version"="1.9.4"
547[HKEY_LOCAL_MACHINE\SOFTWARE\XFS\SERVICE_PROVIDERS\SPTR]
548"dllname"="C:\Program Files\ABCTech\XFS PRODUCT\XFS PTR Service Provider\ABCTech_1028SP.dll"
549"vendor_name"="ABCTech Corporation"
550"version"="1.9.4"
551Notes:
5521) In the above example the receipt and statement printer services are all implemented through a single physical printer and Service Provider DLL. The Service Provider determines which type of service the application has requested by the vendor specific configuration information.
553CWA 16926-1:2015 (E)
55430
5554.8 Exclusive Service and Device Access
556This section describes how application access to services and devices is handled by XFS subsystems, using the lock facility. It discusses the meaning of timers within the context of a lock request and issues that arise when multiple applications have issued lock requests. It also describes how requests that were submitted to the Service Provider prior to a lock request are managed. Furthermore, it describes how compound devices (physical devices that include two or more logical devices, such as a passbook printer that also includes a magnetic stripe reader) are handled.
557Typically, an application requires exclusive access to a particular service when it is about to utilize it, particularly in combination with other services. For example, an application may need to use a PIN pad, magnetic stripe reader, receipt printer and journal printer to complete a transaction. The application must be guaranteed that it has access to all the devices before starting on the transaction, and that no other application will be able to use them until the transaction is complete and it has explicitly released them. This is accomplished by using the WFSLock (or WFSAsyncLock) function and the complementary WFSUnlock function.
558An application should act in a cooperative manner when locking a service, by keeping it locked for the minimum time period that it requires exclusive access to the service. Typically, this means locking a set of services, performing a series of requests to the services to complete a transaction, and immediately unlocking the services.
559However, an application which has obtained a lock on a device will be informed via the WFS_SYSE_LOCK_REQUESTED system event whenever another application requests a lock on the device (i.e. potentially multiple lock request events will occur - one for each request by another application). Therefore an alternative strategy is for the application to register for system events and unlock the device only when it receives the event notification that another application has requested a lock on the device.
560Applications must use appropriate techniques to avoid deadlock when locking multiple services, typically by making use of the timeout parameter in the lock functions.
561Also, note that there are cases in which exclusive access is not a requirement, so that it is not always required that an application lock a service before issuing execute operations to it.
562The lock policy describes the rules that services use in managing lock requests. In the description of this policy, XFS requests are categorized into three types:
563• Non-deferred: Requests that can be processed completely by a service as soon as they arrive (e.g. WFPOpen, WFPRegister and most WFPGetInfo calls.
564• Deferred: Requests which may not be able to be processed completely as soon as they arrive, typically because they require hardware and/or operator interaction (e.g. WFPExecute and some WFPGetInfo calls).
565• Lock: WFPLock calls.
566The lock policy is described first for independent devices, i.e. logical services that correspond to devices whose operation is not interdependent with any other (even though they may be housed in the same physical enclosure). The following section describes the special requirements involved in managing compound interdependent devices.
5674.8.1 Lock Policy for Independent Devices
568The following describes how the categories of requests are handled, in each of the lock states of a service. Note that although the description refers to queues and other implied implementation characteristics, this is only for convenience; no particular implementation techniques are required.
569Service state: UNLOCKED
570• Non-deferred requests are processed on arrival.
571• Deferred requests are placed in the deferred queue and processed FIFO.
572• When a WFPLock request arrives:
573• The lock request is placed in the lock queue.
574• The service state changes to LOCK_PENDING.
575CWA 16926-1:2015 (E)
57631
577Service state: LOCK_PENDING
578• All requests in the deferred queue that arrived before the pending lock request are processed FIFO; after all are processed, the lock queue is processed. Note that depending on the nature of the service/device, lock requests may be granted FIFO or in some other order, e.g. when an operator takes an action such as pressing a station button.
579• When a lock request has been granted:
580• The service state changes to LOCKED.
581• Any other pending lock requests from the same “owner” are also granted. (The owner is the same if it comes from the same workstation and has the same application and service handles.)
582Service state: LOCKED
583• Arriving requests (except lock requests) are handled as follows:
584• Non-deferred requests are processed on arrival.
585• Deferred requests that are not WFPExecute requests are placed in the deferred queue.
586• WFPExecute requests from the owner of the lock are placed in the deferred queue.
587• WFPExecute requests that are not from the owner of the lock are rejected (with error code WFS_ERR_LOCKED).
588• WFPUnlock and WFPClose requests from the owner of the lock are placed in the deferred queue. (Note that a close request to a locked service is treated as an unlock followed by a close.)
589• WFPUnlock and WFPClose requests that are not from the owner of the lock are treated as non-deferred requests, i.e. processed on arrival.
590• The deferred queue is processed FIFO.
591• When a WFPLock request arrives:
592• If it is from the owner of the lock, it is granted.
593• If it is not from the owner of the lock, it is placed in the lock queue, a WFS_SYSE_LOCK_REQUESTED event is posted to the owner of the lock.
594• When a WFPUnlock or WFPClose request is processed from the deferred queue, or the connection between the service and the owner of the lock is lost:
595• If the lock queue is not empty, the service state changes to LOCK_PENDING.
596• If the lock queue is empty, the service state changes to UNLOCKED.
597Note that most requests include a timeout parameter which must be managed appropriately, i.e. when the specified time expires, the request is rejected with the error code WFS_ERR_TIMEOUT. The timeout parameter is particularly important with the WFSLock request, since it allows applications to set a maximum time to wait for a lock to be granted, to allow prevention of deadlock situations when requesting locks of multiple devices.
5984.8.2 Compound Devices
599Compound devices are very common in the financial services industry. For the purposes of this discussion, there are three types of compound devices:
600• Two or more separate logical devices that share a physical housing (or perhaps some other attribute), but function completely independently of one another.
601• Two or more distinct logical devices that are functionally interdependent in some way, such as a journal printer and passbook printer that use the same print head mechanism.
602• Two or more logical devices that are simply different logical views of a single physical device, such as a single printer that is managed as two separate logical devices, a document printer and a passbook printer.
603The first of these types has no special significance from the XFS point of view. Each of the devices is managed as a separate logical and physical device, and the system configuration issues (e.g. making sure that devices that are packaged together are assigned to the same workstation) are left to application utilities outside the scope of this
604CWA 16926-1:2015 (E)
60532
606specification.
607The latter two types are treated identically in an XFS system. When any one of a set of interdependent logical devices that forms a compound device is locked, all the other logical devices in that compound device are also implicitly locked on behalf of the requesting application. (The specific policy is described below.) If the same application (see the discussion of “application identity” below and in Section 4.5) explicitly requests a lock of another of these logical devices, the lock is granted. In order to allow the application to “know” that the devices are part of a compound device, and therefore interdependent, the WFSLock function returns an array of service handles, defining the set of other devices within the compound device that are now explicitly locked by the application. This allows the application to manage its use of these devices accordingly. Normally, it must use them in a strictly sequential manner to avoid any possible conflicts, but if it has some special knowledge of how the devices are related, it may be able to multiplex requests in some ways.
608Note that an application can also determine whether a device is compound by using the device capabilities query function of WFSGetInfo.
609There are many different ways in which programmers can make use of multiple threads and/or processes in financial applications. Each XFS service can be controlled from its own thread; all services can be controlled from a single thread, with other threads/processes used for other application functions; several identical threads can handle all open services as needed; etc. In some of these models, the “user” of a service could be considered to be the process as a whole; in other models, the “user” is a single thread. The XFS design allows for both models by providing the programmer the capability to explicitly control the “identity” of an application. The programmer can make all the threads in a process appear to a Service Provider as one “application,” identify each thread as a different “application,” or create some hybrid of these approaches, allowing interdependent compound devices to be managed correctly no matter what application architecture is used.
610In order to allow this flexibility in application architecture, the “identity” of an application can optionally be managed explicitly using the concept of application handles. An application handle (hApp) is created using the WFSCreateAppHandle function, and is guaranteed unique within the system. The WFSOpen function takes an optional application handle parameter which is bound to the service handle (hService) returned by the open function. This approach allows applications that use interdependent compound devices to be implemented with any combination of single or multiple processes and/or threads, by explicitly managing an appropriate set of application handles. If this facility is not used (indicated by the application using the value WFS_DEFAULT_HAPP for the hApp parameter in WFSOpen), the XFS subsystem automatically treats each process as having a single, unique application handle. See Section 4.5 for additional discussion of this topic.
611The lock policy for interdependent compound devices uses the same rules as for independent devices, with some additional constraints. In order to synchronize access via multiple logical services to a single physical device, or to interdependent devices, the service manages a single lock queue and a single deferred queue for the set of related logical services. The additional constraints are:
612Service state: LOCK_PENDING
613• When a lock request has been granted to one of a set of related logical services:
614• All the other related services in the set change to a “reserved” state in which they are treated as being in the LOCKED state for requests not from the owner.
615• Any lock request from the owner for one of the reserved services is granted on arrival.
616• Lock requests that are not from the owner of the reserved devices are placed in the lock queue.
617Service state: LOCKED
618• Any lock request from the owner for one of the reserved services is granted on arrival.
619• Lock requests that are not from the owner of the reserved devices are placed in the lock queue.
620• Note that if a WFPUnlock or WFPClose request is processed for the service, and any other logical service that is related to this service is in the LOCKED state, then the service state is set to “reserved,” not UNLOCKED.
621• Note also, that if a WFPUnlock or WFPClose request is processed for the service, and the other logical services that are related to this service are in the “reserved” state, then all these services change to the UNLOCKED state.
622CWA 16926-1:2015 (E)
62333
6244.9 Timeout
625There are two fundamentally different time domains in a system, each having a different implication on the concept of timeout:
626• “user time” = real time; timeout here says simply “this job is taking too long” as defined by the application and/or the user (indicated by a WFS_ERR_TIMEOUT error code).
627• “service time” = the time taken by the service request within the service; typically, the physical device operation (indicated by WFS_ERR_DEV_NOT_READY or WFS_ERR_HARDWARE_ERROR error code).
628In XFS systems, the service manages the latter, without needing any input from the application, since it “knows” the characteristics of the device, and can generate a timeout event if the device takes too long, even if the application timeout value (if any) has not been exceeded. Therefore, the timeout value provided in the API is treated by the Service Provider as user/real time. If the time is exceeded, the Service Provider cancels the request and returns a timeout event to the application. An application can also specify that a request should wait until completion, no matter how long the request takes, by specifying the special value WFS_INDEFINITE_WAIT.
629CWA 16926-1:2015 (E)
63034
6314.10 Function Status Return
632When an XFS API or SPI function call completes, it returns a value that either defines the completion status, or in the case of asynchronous functions, the status of the initial processing of the request. When an asynchronous function completes, the completion message includes the final status of the request. The return value of most functions is a “result handle,” hResult, of type HRESULT. hResult values are defined to be WFS_SUCCESS (zero) for success; other values indicate the specific error that occurred, as defined in each function specification.
633The XFS Manager and the Service Providers return status from a function call, in the form of an hResult result handle, in two manners:
634• By returning an hResult value as the function return.
635• By posting a completion message to the window specified in the request. The message contains a pointer to a structure that includes the hResult.
636The mechanism depends on the category of function being processed, as follows:
637• Immediate API The XFS Manager processes the request, and immediately returns a result handle. In some cases, the XFS Manager calls the Service Provider to process the request, then returns the result handle from the Service Provider to the application.
638• Asynchronous API Since the processing is performed in a number of steps, as described earlier, return status is generated at a number of levels:
639• The Service Provider performs any validations which can be processed immediately.
640• If an error is detected, the Service Provider returns the hResult to the XFS Manager, which immediately returns it to the application.
641• Otherwise, the request is scheduled and an hResult of WFS_SUCCESS is immediately returned to the XFS Manager, which immediately returns it to the application. This informs the application that the request has been accepted and is being processed.
642• Upon completion of the deferred request, a completion message is posted to the application's window. This message points to the structure that includes the hResult indicating the completion status of the request.
643Synchronous API
644• Since a synchronous API call is translated by the XFS Manager to an asynchronous SPI, the Service Provider behaves the same as in asynchronous API processing. Specifically, the Service Provider performs any validations which can be processed immediately.
645• If an error is detected, the Service Provider returns the hResult to the XFS Manager, which immediately returns it to the application.
646• Otherwise, the request is scheduled and an hResult of WFS_SUCCESS is immediately returned to the XFS Manager, indicating that the request has been accepted and is being processed.
647• Upon completion of the deferred request, a completion message is posted to the XFS Manager window. The XFS Manager retrieves the hResult from the structure pointed to by the message and returns it to the application.
648CWA 16926-1:2015 (E)
64935
6504.11 Notification Mechanisms - Registering for Events
651The WFSRegister and WFSDeregister functions (and their asynchronous counterparts) are used to register and deregister the window procedures which are to receive Windows messages when particular unsolicited, asynchronous events occur, either during request processing or at other times. In other words, they are used to enable or disable the reception of event notifications. By providing notifications of this type to applications, the requirement to poll for status is removed, and a simple method for implementing "monitoring" applications is provided. Each WFSRegister call specifies a service handle (hService), one or more event classes, and an application window handle (hWnd) which is to receive all the messages of the specified class(es). The corresponding SPI functions, WFPRegister and WFPDeregister, implement the API functions.
652There are four classes of events:
653• SERVICE_EVENTS
654• USER_EVENTS
655• SYSTEM_EVENTS
656• EXECUTE_EVENTS
657For the first three of these event classes, if a class is being monitored and an event occurs in that class, a message is broadcast to every hWnd registered for that class, containing the service handle of the session that the event is sent to. The exception to this is the WFS_SYSE_LOCK_REQUESTED system event, this event is posted only to the application which owns the lock on the device. The events are generated when:
658• The service status changes (SERVICE_EVENTS), e.g. a printer is suspended or is no longer available.
659• The service needs an operation from the user to take place (USER_EVENTS), e.g. a device needs “abnormal” attention, such as adding paper or toner to a printer.
660• A system event occurs (SYSTEM_EVENTS), e.g. a hardware error occurs, a version negotiation fails, the network is no longer available or there is no more disk space.
661The EXECUTE_EVENTS class is different from the other three. These are events which occur as a normal part of processing a WFSExecute command and they are always sent before the completion of the command. Examples include the need to interact with the user or operator to request an action such as inserting a passbook into a printer, “swiping” a magnetic stripe card, etc. A message generated by one of these events is sent only to the application that issued the WFSExecute that caused the event, even though other applications are registered for EXECUTE_EVENTS. In this case an application is defined as all window handles associated with the hService through a WFSRegister call requesting EXECUTE_EVENTS. Note that an application must explicitly register for these events; if it has not, and such an event occurs, the event is not deliverable and the WFSExecute completes normally.
662The logic of WFSRegister is cumulative: for a given service the number of notification messages sent may be increased by specifying additional event classes. Since the XFS Manager does not keep track of what events the application is registered for and the logic of the register/deregister mechanism is cumulative, the Service Providers are responsible for implementing the logic of this process.
663An application requests registration for more than one event class in a single call by using a logical ‘OR’:
664hr = WFSRegister( hService,USER_EVENTS|SERVICE_EVENTS,hWnd );
665Note that services always monitor their resources, regardless of whether any application has registered for event monitoring or not. Issuing WFSRegister simply causes a service to send notifications to the Service Provider, which, in turn, sends notifications to one or more applications.
666To communicate to the XFS Manager that it no longer wishes to receive messages in one or more event classes, an application can cancel any previous registration using the WFSDeregister function. The logic of WFSRegister and WFSDeregister is symmetric: the application can deregister one or more classes of events monitored for each window, by properly specifying them in the parameter list. To deregister completely (e.g. every event class for every window), an application uses NULL event class and window handle values in the parameter list.
667Although the WFSDeregister takes effect immediately, it is possible that messages may be waiting in the application's message queue. A robust application must therefore be prepared to receive event messages even after deregistration.
668CWA 16926-1:2015 (E)
66936
670Note that an event notification message always passes the information describing the event to an application by pointing to a WFSRESULT data structure. After the application has used the data in the structure, it must free the memory that the Service Provider allocated for the WFSRESULT data structure, using the WFSFreeResult function. The hResult field of the WFSRESULT structure is not used unless the event is a command completion event or explicitly defined in this specification.
671CWA 16926-1:2015 (E)
67237
6734.12 Application Processes, Threads and Blocking Functions
674An application process contains one or more threads of execution. The XFS interface is designed to work in both the single-threaded versions of the Windows operating systems (Windows 3.1 and Windows for Workgroups) and in the multi-threaded versions of Windows (Windows NT and future versions of Windows). All references to threads in this document refer to actual threads in multi-threaded Windows environments. In single-threaded environments, “thread” is synonymous with “process.”
675Within the XFS Manager, a blocking (synchronous) function is handled as follows: The XFS Manager initiates the operation, and then enters a loop in which it dispatches any Windows messages (thus yielding the processor to other applications as necessary) and checks for the completion of the operation. When the operation completes, or WFSCancelBlockingCall is invoked, the blocking operation completes with an appropriate result.
676When a Windows message is received for a thread for which a blocking operation is in progress, the thread is not permitted to issue any XFS calls during the processing of the message, other than the two specific functions provided to assist the programmer in this situation:
677• WFSIsBlocking determines whether or not a blocking call is in progress.
678• WFSCancelBlockingCall cancels a blocking call in progress.
679Any other XFS function called when a blocking call is in progress fails with the error WFS_ERR_OP_IN_PROGRESS. This restriction applies to requests for both blocking and non-blocking operations.
680Although this mechanism is sufficient for simple applications, it cannot support those applications which require more complex message processing while blocked for a synchronous call, such as processing messages relating to MDI (multiple document interface) events, accelerator key translations, and modeless dialogs. For such applications, the XFS API includes the function WFSSetBlockingHook, which allows the programmer to define a special routine which will be called instead of the default message dispatch routine described above. This function gives an application the ability to execute its own routine at blocking time in place of the default routine. It is not intended as a mechanism for performing general application functions while blocked; it is still true that the only XFS functions that may be called from a blocking routine are WFSIsBlocking and WFSCancelBlockingCall. The asynchronous versions of the XFS functions must be used to allow an application to continue processing while an operation is in progress.
681This mechanism is provided to allow a Windows 3.x or Windows for Workgroups application to make blocking calls without blocking the rest of the system. Under Windows NT and future multi-threaded, preemptive versions of Windows, the default blocking action is to suspend the calling application's thread until the request completes. This is because the system is not blocked by a single application waiting for an operation to complete, and hence not calling PeekMessage or GetMessage, which are required in the non-preemptive systems in order to cause the application to yield control.
682Therefore, if a single-threaded application is targeted at both single- and multi-threaded environments, and relies on this functionality, it should install a specific blocking hook by calling WFSSetBlockingHook, even if the default hook would suffice. This maximizes the portability of applications that depend on the blocking hook behavior. Programmers who are constrained to use blocking mode - for example, as part of an existing application which is being ported - should be aware of the semantics of blocking operations.
683In the XFS implementation in a single-threaded environment, the blocking function operates as follows. When an application requests a blocking XFS API function, the XFS Manager initiates the requested function and then enters a loop which is equivalent to the following pseudo-code:
684for(;;) {
685/* flush messages for good user response */
686DefaultBlockingHook();
687/* check for WFSCancelBlockingCall() */
688if( operation_cancelled() )
689break;
690/* check to see if operation completed */
691if( operation_complete() )
692break; /* normal completion */
693}
694CWA 16926-1:2015 (E)
69538
696The DefaultBlockingHook routine is equivalent to:
697BOOL DefaultBlockingHook(void) {
698MSG msg;
699BOOL ret;
700/* Wait for the next message */
701ret = GetMessage(&msg, NULL, 0, 0);
702if( (int) ret != -1 ) {
703TranslateMessage(&msg);
704DispatchMessage(&msg);
705}
706/* FALSE if we got a WM_QUIT message */
707return( ret );
708}
709In a multi-threaded environment, the developer of a multi-threaded application must be aware that it is the responsibility of the application, not the XFS Manager, to synchronize access to a service by multiple threads. Failure to synchronize calls to a service leads to unpredictable results; for example, if two threads "simultaneously" issue WFSExecute requests to send data to the same service, there is no guarantee as to the order in which the data is sent. This is true in general; the application is responsible for coordinating access by multiple threads to any object (e.g. other forms of I/O, such as file I/O), using appropriate synchronization mechanisms. The XFS Manager can not, and will not, address these issues. The possible consequences of failing to observe these rules are beyond the scope of this specification.
710In order to allow maximum flexibility in the design and implementation of applications, especially in multi-threaded environments, the concept of "application identity" can optionally be managed explicitly by the application developer using the concept of application handles. See Sections 4.5 and 4.8.2 for additional discussion of this concept.
711CWA 16926-1:2015 (E)
71239
7134.13 Vendor Dependent Mode
714XFS compliant applications must comply with the following:
715• Every XFS application should open a session with the VDM Service Provider passing a valid Application ID and then register for all VDM entry and exit notices.
716• Before opening any session with any other XFS Service Provider, check the status of the VDM Service Provider. If Vendor Dependent Mode is not “Inactive”, do not open a session.
717• When getting a VDM entry notice, close all open sessions with all other XFS Service Providers as soon as possible and issue an acknowledgement for the entry to VDM.
718• When getting a VDM exit notice, acknowledge at once.
719• When getting a VDM exited notice, re-open any required sessions with other XFS Service Providers.
720This is mandatory for self-service but optional for branch.
721CWA 16926-1:2015 (E)
72240
7234.14 Memory Management
724XFS specifies a protocol for dynamic allocation and release of memory. The general strategy is that the Service Providers allocate memory as they need it, and the applications specify when it can be released. This is implemented using a standard structure (WFSRESULT, defined in Section 9.1) that is always used to pass information to the applications from the services.
725Most Service Provider function calls are asynchronous, and return their results via a completion message, which contains a pointer to a WFSRESULT structure, containing the function return status (hResult) and optional data. The Service Provider allocates the memory for this structure, using the memory management framework described below. The deallocation of the structure is done as follows:
726• Asynchronous API functions The application receives the structure from the Service Provider via a completion message, and is responsible for deallocation.
727• Synchronous WFSExecute, WFSGetInfo and WFSLock API functions The XFS Manager passes through the WFSRESULT structure to the application as a returned parameter, and the application is then responsible for deallocation, just as for asynchronous calls.
728• All other synchronous API functions The XFS Manager unpacks the required information from the WFSRESULT structure into returned parameters to the application, deallocates the structure, and returns to the application.
729Four functions are provided by the XFS Manager to implement this protocol: WFMAllocateBuffer, WFMAllocateMore, WFMFreeBuffer, and WFSFreeResult. Using these functions, two widely applicable allocation policies are supported:
730• A linear allocation policy
731• A linked allocation policy
732Linear allocation can be used for any flat or contiguously allocated data structure. Such structures are returned in a single block of allocated memory by the WFMAllocateBuffer function.
733Linked allocation can be used as an efficient way of managing complex data structures, permitting the Service Provider some flexibility while allowing the application to release the entire structure with a single call. In cases in which the Service Provider does not know a priori the size of the result data set, it makes an initial estimate, and uses WFMAllocateBuffer. If the Service Provider later determines that more space is required by the data, new memory is requested using the function WFMAllocateMore, and is automatically linked to the originally allocated block. The new memory block returned by WFMAllocateMore is, in general, not contiguous with the root block, and the user of this function should behave in all circumstances as if it is not.
734The Service Provider is free to choose whatever allocation granularity is most convenient. This is completely transparent to the application or XFS Manager, which frees the entire WFSRESULT structure with a single WFSFreeResult call (the XFS Manager can also use this call as an indication that it can clean up any other objects associated with the request). Applications must be sure always to free a returned WFSRESULT structure. Note that a WFSRESULT structure may be returned even if the Service Provider has returned an error; if no WFSRESULT is returned, the pointer to the structure is NULL. A Service Provider may use also this facility for its "private" memory management requirements; it then uses the WFMFreeBuffer support function to free the allocated memory.
735NOTE:
736Applications and Service Providers must use the facilities provided by the XFS Manager for XFS-related memory allocation and deallocation, in order to avoid memory management conflicts among the applications, the XFS Manager and the Service Providers.
737CWA 16926-1:2015 (E)
73841
739The following example illustrates how a Service Provider dynamically allocates a WFSRESULT buffer structure and an additional data buffer. Note that WFMAllocateMore automatically links these, allowing the application to free both structures with a single call.
740WFSRESULT * lpResultBuffer;
741// Service Provider allocates a WFSResult buffer structure
742result = WFMAllocateBuffer(sizeof(WFSRESULT), ulMemFlags, &lpResultBuffer);
743•
744•
745•
746// Service Provider allocates additional memory
747hr = WFMAllocateMore(evenMoreMemory, lpResultBuffer, &lpResultBuffer->lpBuffer);
748•
749•
750•
751Once the application has retrieved all the information it needs from the WFSRESULT buffer and any associated structures, it must free the memory, which requires only a single call:
752•
753•
754•
755// application deallocates the structure when it is finished with it
756hr = WFSFreeResult(lpResultBuffer); // frees both the result buffer and // any additional buffers
757NOTE:
758When an application invokes an asynchronous or immediate (i.e. non-blocking) function which takes a pointer to a memory object as an argument, it is the responsibility of the Service Provider to ensure that it no longer needs access to the object before returning control to the application. This allows the application to release (deallocate) the memory object immediately upon the return from the call.
759CWA 16926-1:2015 (E)
76042
7614.15 Command Synchronization
762When the Service Provider supports command synchronization, the application can synchronize a command with another action (e.g. another command, screen change, etc.). For example, if both a receipt printer Service Provider and a card reader Service Provider support command synchronization for media ejection, the application can call synchronization preparation commands to both Service Providers and then the application can synchronize the media ejections (a receipt and a card) by calling the actual eject commands at the same time. For sample flows of command synchronization, see chapter 14.
763CWA 16926-1:2015 (E)
76443
7654.16 Binary Interface
766All applications and Service Providers should be fully compliant with the exported WFS and WFP interfaces in order to be compliant with any vendor’s implementation of the XFS Manager. The CEN XFS SDK provides a reference XFS Manager and matching LIB files which are compliant with the interface defined below.
767The following table lists the XFS Manager’s API functions and their DLL locations, together with their fixed ordinal values.
768DLL and Ordinal Number
769API Call
770MSXFS
771XFS_SUPP
772XFS_CONF
773WFMAllocateBuffer
7741
7754
776WFMAllocateMore
7772
7785
779WFMFreeBuffer
7803
7816
782WFMGetTraceLevel
7834
784WFMKillTimer
7855
7867
787WFMOutputTraceData
7887
7899
790WFMReleaseDLL
7918
792WFMSetTimer
7939
79410
795WFMSetTraceLevel
79610
79711
798WFSAsyncClose
79911
800WFSAsyncDeregister
80112
802WFSAsyncExecute
80313
804WFSAsyncGetInfo
80514
806WFSAsyncLock
80715
808WFSAsyncOpen
80916
810WFSAsyncRegister
81117
812WFSAsyncUnlock
81318
814WFSCancelAsyncRequest
81519
816WFSCancelBlockingCall
81720
818WFSCleanUp
81921
820WFSClose
82122
822WFSCreateAppHandle
82323
824WFSDeregister
82524
826WFSDestroyAppHandle
82725
828WFSExecute
82926
830WFSFreeResult
83127
832WFSGetInfo
83328
834WFSIsBlocking
83530
836WFSLock
83731
838WFSOpen
83932
840WFSRegister
84133
842WFSSetBlockingHook
84334
844WFSStartUp
84535
846WFSUnhookBlockingHook
84736
848WFSUnlock
84937
850WFMCloseKey
8514
852WFMCreateKey
8535
854WFMDeleteKey
8556
856WFMDeleteValue
8577
858WFMEnumKey
8598
860WFMEnumValue
8619
862WFMOpenKey
86310
864WFMQueryValue
86511
866WFMSetValue
86712
868CWA 16926-1:2015 (E)
86944
8705. Application Programming Interface (API) Functions
871The functions defined by the XFS API are divided into:
872• Basic functions that are common to all classes of financial services.
873• Administration functions, used for the special purpose of administering services.
874• Service-specific commands that are peculiar to a single service class or a group of them and that are sent to services using basic functions (WFSExecute, WFSAsyncExecute, WFSGetInfo, WFSAsyncGetInfo).
875The benefit of grouping functions that are common to all services is evident: programmers can immediately focus on those operations that are common through all services and thus can easily build a high level model of interaction with the Service Providers.
876The basic functions are defined in this section, in alphabetical order, except that the asynchronous version of each command is described immediately following the synchronous version. For example, WFSAsyncExecute is placed immediately following WFSExecute. The table on the next page lists all the basic functions. This set of basic functions may be expanded in future releases of this specification, if new functions are determined to be useful for all Service Providers.
877The administration functions have not yet been fully defined; they are outlined in Appendix A. - Planned Enhancements and Extensions.
878The service-specific commands are defined in separate specifications-one for each service class. In addition, the XFS SNMP MIB architecture specification defines a number of category codes that are common across all service classes.
879CWA 16926-1:2015 (E)
88045
881The table below summarizes the XFS API functions, and the sections in which they are defined.
882Section
883Function
884Mode
885Description
8865.1
887WFSCancelAsyncRequest
888Immediate
889Cancel an outstanding asynchronous request
8905.2
891WFSCancelBlockingCall
892Immediate
893Cancel an outstanding blocking operation
8945.3
895WFSCleanUp
896Synchronous
897Terminate a connection between an application and the XFS Manager
8985.4
899WFSClose
900Synchronous
901Close a session between an application and a Service Provider
9025.5
903WFSAsyncClose
904Asynchronous
905The asynchronous version of WFSClose
9065.6
907WFSCreateAppHandle
908Immediate
909Create a new application handle to be used in a subsequent WFSOpen call
9105.7
911WFSDeregister
912Synchronous
913Disable monitoring of a class of events by an application
9145.8
915WFSAsyncDeregister
916Asynchronous
917The asynchronous version of WFSDeregister
9185.9
919WFSDestroyAppHandle
920Immediate
921Destroy the specified application handle
9225.10
923WFSExecute
924Synchronous
925Send service-specific commands to a Service Provider
9265.11
927WFSAsyncExecute
928Asynchronous
929The asynchronous version of WFSExecute
9305.12
931WFSFreeResult
932Immediate
933Request the XFS Manager to free a result buffer
9345.13
935WFSGetInfo
936Synchronous
937Retrieve service-specific information from a Service Provider
9385.14
939WFSAsyncGetInfo
940Asynchronous
941The asynchronous version of WFSGetInfo
9425.15
943WFSIsBlocking
944Immediate
945Determine if a blocking call is in progress
9465.16
947WFSLock
948Synchronous
949Establish exclusive control by an application of a service
9505.17
951WFSAsyncLock
952Asynchronous
953The asynchronous version of WFSLock
9545.18
955WFSOpen
956Synchronous
957Open a session between an application and a Service Provider
9585.19
959WFSAsyncOpen
960Asynchronous
961The asynchronous version of WFSOpen
9625.20
963WFSRegister
964Synchronous
965Enable monitoring of a class of events by an application
9665.21
967WFSAsyncRegister
968Asynchronous
969The asynchronous version of WFSRegister
9705.22
971WFSSetBlockingHook
972Immediate
973Install an application-specific blocking routine
9745.23
975WFSStartUp
976Immediate
977Initiate a connection between an application and the XFS Manager
9785.24
979WFSUnhookBlockingHook
980Immediate
981Restore the default blocking routine
9825.25
983WFSUnlock
984Synchronous
985Release exclusive control by an application of a service
9865.26
987WFSAsyncUnlock
988Asynchronous
989The asynchronous version of WFSUnlock
990CWA 16926-1:2015 (E)
99146
9925.1 WFSCancelAsyncRequest
993HRESULT WFSCancelAsyncRequest( hService, RequestID )
994Cancels the specified (or every) asynchronous request being performed on the specified service, before its (their) completion.
995Parameters HSERVICE hService
996Handle to the service as returned by WFSOpen or WFSAsyncOpen.
997REQUESTID RequestID
998The request identifier for the request to be canceled, as returned by the original function call (NULL to cancel all).
999Mode Immediate
1000Comments If the RequestID parameter is set to NULL, the command will cancel all asynchronous requests that are in progress using the specified hService.
1001A previously initiated asynchronous request is canceled prior to completion by issuing the WFSCancelAsyncRequest function, specifying the request identifier returned by the asynchronous function. This function is immediate with respect to its calling application, but the cancellation process is inherently asynchronous. On completion, the specified request (or all requests) will have finished, with a completion message indicating a status of WFS_ERR_CANCELED, unless the cancel request was received by the service after the request had completed. Thus, WFSCancelAsyncRequest is not guaranteed to stop all asynchronous commands: normal completion messages may still be posted after the cancel. A robust application that uses asynchronous commands should be designed to accept these messages even after a cancel is issued.
1002The cancellation applies not only to the XFS Manager level, but also to the Service Provider level. The request is passed through the SPI, and the Service Provider normally then also cancels any physical I/O or other device operation in progress, in the appropriate manner for the device or service.
1003Error Codes If the function return is not WFS_SUCCESS, it is one of the following error conditions:
1004WFS_ERR_CONNECTION_LOST
1005The connection to the service is lost.
1006WFS_ERR_INTERNAL_ERROR
1007An internal inconsistency or other unexpected error occurred in the XFS subsystem.
1008WFS_ERR_INVALID_HSERVICE
1009The hService parameter is not a valid service handle.
1010WFS_ERR_INVALID_REQ_ID
1011The RequestID parameter does not correspond to an outstanding request on the service.
1012WFS_ERR_NOT_STARTED
1013The application has not previously performed a successful WFSStartUp.
1014WFS_ERR_OP_IN_PROGRESS
1015A blocking operation is in progress on the thread; only WFSCancelBlockingCall and WFSIsBlocking are permitted at this time.
1016See Also WFSAsyncExecute
1017CWA 16926-1:2015 (E)
101847
10195.2 WFSCancelBlockingCall
1020HRESULT WFSCancelBlockingCall( dwThreadID )
1021Cancels a blocking operation for the specified thread, if one is in progress.
1022Parameters DWORD dwThreadID
1023Identifies the thread for which the blocking operation is to be canceled; a NULL value indicates the calling thread.
1024Mode Immediate
1025Comments This function is used to cancel a blocking call (synchronous request) that is in progress. Since a thread may have only one blocking call in progress at any time, WFSIsBlocking and WFSCancelBlockingCall are the only XFS functions allowed with respect to a thread when it has a blocking call in progress.
1026The application that issued the blocking call receives a WFS_ERR_CANCELED return code if the operation is successfully canceled.
1027The cancellation applies not only to the XFS Manager level, but also to the Service Provider level. The request is passed through the SPI, and the Service Provider normally then also cancels any physical I/O or other device operation in progress, in the appropriate manner for the device or service.
1028Note: the cancel request is accepted and is honored as soon as all Windows messages have been removed from the message queue (i.e. GetMessage returns no more messages). Refer to WFSSetBlockingHook for more information.
1029Error Codes If the function return is not WFS_SUCCESS, it is the following error condition:
1030WFS_ERR_CONNECTION_LOST
1031The connection to the service is lost.
1032WFS_ERR_INTERNAL_ERROR
1033An internal inconsistency or other unexpected error occurred in the XFS subsystem.
1034WFS_ERR_NO_BLOCKING_CALL
1035There is no outstanding blocking call for the specified thread.
1036WFS_ERR_NO_SUCH_THREAD
1037The specified thread does not exist.
1038WFS_ERR_NOT_STARTED
1039The application has not previously performed a successful WFSStartUp.
1040See Also WFSSetBlockingHook, WFSIsBlocking, WFSCancelAsyncRequest
1041CWA 16926-1:2015 (E)
104248
10435.3 WFSCleanUp
1044HRESULT WFSCleanUp( )
1045Disconnects an application from the XFS Manager.
1046Parameters None
1047Mode Synchronous
1048Comments The WFSCleanUp call indicates disconnection of an XFS application from the XFS Manager. This function, for example, frees resources allocated to the specific application. WFSCleanUp applies to all threads of a multi-threaded application. If WFSClose has not been issued for one or more Service Providers, then the XFS Manager will automatically issue the close(s). Once the WFSCleanUp has been performed, subsequent attempts to issue any XFS function other than WFSStartUp will fail.
1049Error Codes If the function return is not WFS_SUCCESS, it is one of the following error conditions:
1050WFS_ERR_INTERNAL_ERROR
1051An internal inconsistency or other unexpected error occurred in the XFS subsystem.
1052WFS_ERR_NOT_STARTED
1053The application has not previously performed a successful WFSStartUp.
1054WFS_ERR_OP_IN_PROGRESS
1055A blocking operation is in progress on the thread; only WFSCancelBlockingCall and WFSIsBlocking are permitted at this time.
1056See Also WFSStartUp
1057CWA 16926-1:2015 (E)
105849
10595.4 WFSClose
1060HRESULT WFSClose( hService )
1061Terminates a session (a series of service requests initiated with the WFSOpen or WFSAsyncOpen function) between the application and the specified service. The synchronous version of WFSAsyncClose.
1062Parameters HSERVICE hService
1063The service handle returned by WFSOpen or WFSAsyncOpen. Matches the close request to the open request, allowing an application to have multiple sessions open simultaneously with a single Service Provider.
1064Mode Synchronous
1065Comments WFSClose directs the service to free all resources associated with the series of requests made using the hService parameter since the WFSOpen that returned it. If there is a blocking call in progress the close fails. If the service is locked, the close automatically unlocks it. If no WFSDeregister has been issued, it is automatically performed.
1066Error Codes If the function return is not WFS_SUCCESS, it is one of the following error conditions. Any service-specific errors that can be returned are defined in the specifications for each service class.
1067WFS_ERR_CANCELED
1068The request was canceled by WFSCancelBlockingCall.
1069WFS_ERR_CONNECTION_LOST
1070The connection to the service is lost.
1071WFS_ERR_INTERNAL_ERROR
1072An internal inconsistency or other unexpected error occurred in the XFS subsystem.
1073WFS_ERR_INVALID_HSERVICE
1074The hService parameter is not a valid service handle.
1075WFS_ERR_NOT_STARTED
1076The application has not previously performed a successful WFSStartUp.
1077WFS_ERR_OP_IN_PROGRESS
1078A blocking operation is in progress on the thread; only WFSCancelBlockingCall and WFSIsBlocking are permitted at this time.
1079See Also WFSAsyncClose, WFSOpen, WFSDeregister
1080CWA 16926-1:2015 (E)
108150
10825.5 WFSAsyncClose
1083HRESULT WFSAsyncClose( hService, hWnd, lpRequestID )
1084Terminates a session (a series of service requests initiated with the WFSOpen or WFSAsyncOpen function) between the application and the specified service. The asynchronous version of WFSClose.
1085Parameters HSERVICE hService
1086The service handle returned by WFSOpen or WFSAsyncOpen. Matches the close request to the open request, allowing an application to maintain several "open sessions" simultaneously.
1087HWND hWnd
1088The window handle which is to receive the completion message for this request.
1089LPREQUESTID lpRequestID
1090Pointer to the request identifier for this request (returned parameter).
1091Mode Asynchronous
1092Comments See WFSClose.
1093The application must call WFSFreeResult to deallocate the WFSRESULT data structure which is pointed to by the completion message. Note that a WFSRESULT structure may be returned even if the function completes with an error; see Section 4.14.
1094Messages WFS_CLOSE_COMPLETE
1095Error Codes If the function return is not WFS_SUCCESS, it is one of the following error conditions, indicating that the asynchronous operation was not initiated:
1096WFS_ERR_CONNECTION_LOST
1097The connection to the service is lost.
1098WFS_ERR_INTERNAL_ERROR
1099An internal inconsistency or other unexpected error occurred in the XFS subsystem.
1100WFS_ERR_INVALID_HSERVICE
1101The hService parameter is not a valid service handle.
1102WFS_ERR_INVALID_HWND
1103The hWnd parameter is not a valid window handle.
1104WFS_ERR_INVALID_POINTER
1105A pointer parameter does not point to accessible memory.
1106WFS_ERR_NOT_STARTED
1107The application has not previously performed a successful WFSStartUp.
1108WFS_ERR_OP_IN_PROGRESS
1109A blocking operation is in progress on the thread; only WFSCancelBlockingCall and WFSIsBlocking are permitted at this time.
1110The following error condition can be returned via the asynchronous command completion message, as the hResult from the WFSRESULT structure.
1111WFS_ERR_CANCELED
1112The request was canceled by WFSCancelAsyncRequest.
1113WFS_ERR_INTERNAL_ERROR
1114An internal inconsistency or other unexpected error occurred in the XFS subsystem.
1115See Also WFSOpen, WFSDeregister
1116CWA 16926-1:2015 (E)
111751
11185.6 WFSCreateAppHandle
1119HRESULT WFSCreateAppHandle( lphApp )
1120Requests a new, unique application handle value.
1121Parameters LPHAPP lphApp
1122A pointer to the application handle to be created (returned parameter).
1123Mode Immediate
1124Comments This function is used by an application to request a unique (within a single system) application handle from the XFS Manager (to be used in subsequent WFSOpen/WFSAsyncOpen calls). Note that an application may call this function multiple times in order to create multiple “application identities” for itself with respect to the XFS subsystem. See Sections 4.5 and 4.8.2 for additional discussion.
1125Error Codes If the function return is not WFS_SUCCESS, it is the following error condition.
1126WFS_ERR_INTERNAL_ERROR
1127An internal inconsistency or other unexpected error occurred in the XFS subsystem.
1128WFS_ERR_INVALID_POINTER
1129A pointer parameter does not point to accessible memory.
1130WFS_ERR_NOT_STARTED
1131The application has not previously performed a successful WFSStartUp.
1132See Also WFSDestroyAppHandle, WFSOpen, WFSAsyncOpen
1133CWA 16926-1:2015 (E)
113452
11355.7 WFSDeregister
1136HRESULT WFSDeregister( hService, dwEventClass, hWndReg )
1137Discontinues monitoring of the specified message class(es) (or all classes) from the specified hService, by the specified hWndReg (or all the calling application's hWnd's). The synchronous version of WFSAsyncDeregister.
1138Parameters HSERVICE hService
1139Service handle returned by WFSOpen or WFSAsyncOpen. If this value is NULL, and dwEventClass is SYSTEM_EVENTS, the XFS manager deregisters the application for those system events generated by the Manager itself.
1140DWORD dwEventClass
1141The class(es) of messages from which the application is deregistering. Specified as a bit mask that can be a logical OR of the values for multiple classes. A NULL value requests that all message classes be deregistered from the specified window for this hService.
1142HWND hWndReg
1143The window which has been previously registered to receive notification messages, and is now to be deregistered. A NULL value requests that all the application's windows be deregistered from the specified message class(es) for this hService.
1144Mode Synchronous
1145Comments The functions of a WFSDeregister request are performed automatically if a WFSClose is issued without a previous WFSDeregister.
1146See section 4.11 for a description of the classes of events that may be monitored.
1147Error Codes If the function return is not WFS_SUCCESS, it is one of the following error conditions:
1148WFS_ERR_CANCELED
1149The request was canceled by WFSCancelBlockingCall.
1150WFS_ERR_CONNECTION_LOST
1151The connection to the service is lost.
1152WFS_ERR_INTERNAL_ERROR
1153An internal inconsistency or other unexpected error occurred in the XFS subsystem.
1154WFS_ERR_INVALID_EVENT_CLASS
1155The dwEventClass parameter specifies one or more event classes not supported by the service.
1156WFS_ERR_INVALID_HSERVICE
1157The hService parameter is not a valid service handle.
1158WFS_ERR_INVALID_HWNDREG
1159The hWndReg parameter is not a valid window handle.
1160WFS_ERR_NOT_REGISTERED
1161The specified hWndReg window was not registered to receive messages for any event classes.
1162WFS_ERR_NOT_STARTED
1163The application has not previously performed a successful WFSStartUp.
1164WFS_ERR_OP_IN_PROGRESS
1165A blocking operation is in progress on the thread; only WFSCancelBlockingCall and WFSIsBlocking are permitted at this time.
1166See Also WFSRegister, WFSClose
1167CWA 16926-1:2015 (E)
116853
11695.8 WFSAsyncDeregister
1170HRESULT WFSAsyncDeregister( hService, dwEventClass, hWndReg, hWnd, lpRequestID )
1171Discontinues monitoring of the specified message class(es) (or all classes) from the specified hService, by the specified hWndReg (or all the calling application's hWnd's). The asynchronous version of WFSDeregister.
1172Parameters HSERVICE hService
1173Service handle returned by WFSOpen or WFSAsyncOpen. If this value is NULL, and dwEventClass is SYSTEM_EVENTS, the XFS manager deregisters the application for those system events generated by the Manager itself.
1174DWORD dwEventClass
1175The class(es) of events from which the application is deregistering. Specified as a bit mask that can be a logical OR of the values for multiple classes. A NULL value requests that all event classes be deregistered from the specified window for this hService.
1176HWND hWndReg
1177The window which has been previously registered to receive notification messages, and is now to be deregistered. A NULL value requests that all the application's windows be deregistered from the specified message class(es) for this hService.
1178HWND hWnd
1179The window handle which is to receive the completion message for this request.
1180LPREQUESTID lpRequestID
1181Pointer to the request identifier for this request (returned parameter).
1182Mode Asynchronous
1183Comments See WFSDeregister.
1184The application must call WFSFreeResult to deallocate the WFSRESULT data structure which is pointed to by the completion message. Note that a WFSRESULT structure may be returned even if the function completes with an error; see Section 4.14.
1185Messages WFS_DEREGISTER_COMPLETE
1186Error Codes If the function return is not WFS_SUCCESS, it is one of the following error conditions, indicating that the asynchronous operation was not initiated:
1187WFS_ERR_CONNECTION_LOST
1188The connection to the service is lost.
1189WFS_ERR_INTERNAL_ERROR
1190An internal inconsistency or other unexpected error occurred in the XFS subsystem.
1191WFS_ERR_INVALID_EVENT_CLASS
1192The dwEventClass parameter specifies one or more event classes not supported by the service.
1193WFS_ERR_INVALID_HSERVICE
1194The hService parameter is not a valid service handle.
1195WFS_ERR_INVALID_HWND
1196The hWnd parameter is not a valid window handle.
1197WFS_ERR_INVALID_HWNDREG
1198The hWndReg parameter is not a valid window handle.
1199WFS_ERR_INVALID_POINTER
1200A pointer parameter does not point to accessible memory.
1201WFS_ERR_NOT_REGISTERED
1202The specified hWndReg window was not registered to receive messages for any event classes.
1203WFS_ERR_NOT_STARTED
1204The application has not previously performed a successful WFSStartUp.
1205CWA 16926-1:2015 (E)
120654
1207WFS_ERR_OP_IN_PROGRESS
1208A blocking operation is in progress on the thread; only WFSCancelBlockingCall and WFSIsBlocking are permitted at this time.
1209The following error conditions are returned via the asynchronous command completion message, as the hResult from the WFSRESULT structure. Any service-specific errors that can be returned are defined in the specifications for each service class.
1210WFS_ERR_CANCELED
1211The request was canceled by WFSCancelAsyncRequest.
1212WFS_ERR_INTERNAL_ERROR
1213An internal inconsistency or other unexpected error occurred in the XFS subsystem.
1214See Also WFSRegister, WFSClose
1215CWA 16926-1:2015 (E)
121655
12175.9 WFSDestroyAppHandle
1218HRESULT WFSDestroyAppHandle( hApp )
1219Makes the specified application handle invalid.
1220Parameters HAPP hApp
1221The application handle to be made invalid.
1222Mode Immediate
1223Comments This function is used by an application to indicate to the XFS Manager that it will no longer use the specified application handle (from a previous WFSCreateAppHandle call). See WFSCreateAppHandle and Sections 4.5 and 4.8.2 for additional discussion.
1224Error Codes If the function return is not WFS_SUCCESS, it is one of the following error conditions.
1225WFS_ERR_INTERNAL_ERROR
1226An internal inconsistency or other unexpected error occurred in the XFS subsystem.
1227WFS_ERR_NOT_STARTED
1228The application has not previously performed a successful WFSStartUp.
1229WFS_ERR_INVALID_APP_HANDLE
1230The specified application handle is not valid, i.e. was not created by a preceding create call.
1231See Also WFSCreateAppHandle
1232CWA 16926-1:2015 (E)
123356
12345.10 WFSExecute
1235HRESULT WFSExecute ( hService, dwCommand, lpCmdData, dwTimeOut, lppResult )
1236Sends a service-specific command to a Service Provider. The synchronous version of WFSAsyncExecute.
1237Parameters HSERVICE hService
1238Handle to the service as returned by WFSOpen or WFSAsyncOpen.
1239DWORD dwCommand
1240Command to be executed by the Service Provider.
1241LPVOID lpCmdData
1242Pointer to a command data structure to be passed to the Service Provider.
1243DWORD dwTimeOut
1244Number of milliseconds to wait for completion (WFS_INDEFINITE_WAIT to specify a request that will wait until completion).
1245LPWFSRESULT * lppResult
1246Pointer to the pointer to the result data structure used to return the results of the execution. The Service Provider allocates the memory for this structure.
1247Mode Synchronous
1248Comments This function is used to execute service-specific commands. Each class of service includes a unique set of commands for the given class of device or service; they are defined in the service-specific command specifications. Each Service Provider developer is responsible for recognizing the complete set of commands for a given class, even if the Service Provider doesn't support them all. Each command, for each service class, defines a command data structure and/or a result data structure. See the separate specifications for each service class for more discussion of these issues, and the definitions of the service-specific commands and associated data structures.
1249The application must call WFSFreeResult to deallocate the WFSRESULT data structure returned by this function. Note that a WFSRESULT structure may be returned even if the function completes with an error; see Section 4.14.
1250Error Codes If the function return is not WFS_SUCCESS, it is one of the following error conditions. Any service-specific errors that can be returned are defined in the specifications for each service class.
1251WFS_ERR_CANCELED
1252The request was canceled by WFSCancelBlockingCall.
1253WFS_ERR_CONNECTION_LOST
1254The connection to the service is lost.
1255WFS_ERR_DEV_NOT_READY
1256The function required device access, and the device was not ready or timed out.
1257WFS_ERR_HARDWARE_ERROR
1258The function required device access, and an error occurred on the device.
1259WFS_ERR_INTERNAL_ERROR
1260An internal inconsistency or other unexpected error occurred in the XFS subsystem.
1261WFS_ERR_INVALID_COMMAND
1262The dwCommand issued is not supported by this service class.
1263WFS_ERR_INVALID_DATA
1264The data structure passed as input parameter contains invalid data.
1265WFS_ERR_INVALID_POINTER
1266A pointer parameter does not point to accessible memory.
1267WFS_ERR_INVALID_HSERVICE
1268The hService parameter is not a valid service handle.
1269WFS_ERR_LOCKED
1270The service is locked under a different hService.
1271CWA 16926-1:2015 (E)
127257
1273WFS_ERR_NOT_STARTED
1274The application has not previously performed a successful WFSStartUp.
1275WFS_ERR_OP_IN_PROGRESS
1276A blocking operation is in progress on the thread; only WFSCancelBlockingCall and WFSIsBlocking are permitted at this time.
1277WFS_ERR_SOFTWARE_ERROR
1278The function required access to configuration information, and an error occurred on the software.
1279WFS_ERR_TIMEOUT
1280The timeout interval expired.
1281WFS_ERR_UNSUPP_COMMAND
1282The dwCommand issued, although valid for this service class, is not supported by this Service Provider or device.
1283WFS_ERR_USER_ERROR
1284A user is preventing proper operation of the device.
1285WFS_ERR_UNSUPP_DATA
1286The data structure passed as an input parameter although valid for this service class, is not supported by this Service Provider or device.
1287WFS_ERR_FRAUD_ATTEMPT
1288Some devices are capable of identifying a malicious physical attack which attempts to defraud valuable information or media. In these cases, this error code is returned to indicate the user is attempting a fraudulent act on the device.
1289WFS_ERR_SEQUENCE_ERROR
1290The requested operation is not valid at this time or in the devices current state.
1291WFS_ERR_AUTH_REQUIRED
1292The requested operation cannot be performed because it requires authentication.
1293See Also WFSAsyncExecute
1294CWA 16926-1:2015 (E)
129558
12965.11 WFSAsyncExecute
1297HRESULT WFSAsyncExecute( hService, dwCommand, lpCmdData, dwTimeOut, hWnd, lpRequestID )
1298Sends a service-specific command to a Service Provider. The asynchronous version of WFSExecute.
1299Parameters HSERVICE hService
1300Handle to the Service Provider as returned by WFSOpen or WFSAsyncOpen.
1301DWORD dwCommand
1302Command to be executed by the Service Provider.
1303LPVOID lpCmdData
1304Pointer to the data structure to be passed to the Service Provider.
1305DWORD dwTimeOut
1306Number of milliseconds to wait for completion (WFS_INDEFINITE_WAIT to specify a request that will wait until completion).
1307HWND hWnd
1308The window handle which is to receive the completion message for this request.
1309LPREQUESTID lpRequestID
1310Pointer to the request identifier for this request (returned parameter).
1311Mode Asynchronous
1312Comments See WFSExecute.
1313The application must call WFSFreeResult to deallocate the WFSRESULT data structure which is pointed to by the completion message. Note that a WFSRESULT structure may be returned even if the function completes with an error; see Section 4.14.
1314Messages WFS_EXECUTE_COMPLETE WFS_EXECUTE_EVENT
1315Error Codes If the function return is not WFS_SUCCESS, it is one of the following error conditions, indicating that the asynchronous operation was not initiated:
1316WFS_ERR_CONNECTION_LOST
1317The connection to the service is lost.
1318WFS_ERR_INTERNAL_ERROR
1319An internal inconsistency or other unexpected error occurred in the XFS subsystem.
1320WFS_ERR_INVALID_COMMAND
1321The dwCommand issued is not supported by this service class.
1322WFS_ERR_INVALID_HSERVICE
1323The hService parameter is not a valid service handle.
1324WFS_ERR_INVALID_HWND
1325The hWnd parameter is not a valid window handle.
1326WFS_ERR_INVALID_POINTER
1327A pointer parameter does not point to accessible memory.
1328WFS_ERR_NOT_STARTED
1329The application has not previously performed a successful WFSStartUp.
1330WFS_ERR_OP_IN_PROGRESS
1331A blocking operation is in progress on the thread; only WFSCancelBlockingCall and WFSIsBlocking are permitted at this time.
1332WFS_ERR_UNSUPP_COMMAND
1333The dwCommand issued, although valid for this service class, is not supported by this Service Provider or device.
1334CWA 16926-1:2015 (E)
133559
1336The following error conditions are returned via the asynchronous command completion message, as the hResult from the WFSRESULT structure. Any service-specific errors that can be returned are defined in the specifications for each service class.
1337WFS_ERR_CANCELED
1338The request was canceled by WFSCancelAsyncRequest.
1339WFS_ERR_DEV_NOT_READY
1340The function required device access, and the device was not ready or timed out.
1341WFS_ERR_HARDWARE_ERROR
1342The function required device access, and an error occurred on the device.
1343WFS_ERR_INTERNAL_ERROR
1344An internal inconsistency or other unexpected error occurred in the XFS subsystem.
1345WFS_ERR_INVALID_DATA
1346The data structure passed as input parameter contains invalid data.
1347WFS_ERR_LOCKED
1348The service is locked under a different hService.
1349WFS_ERR_SOFTWARE_ERROR
1350The function required access to configuration information, and an error occurred on the software.
1351WFS_ERR_TIMEOUT
1352The timeout interval expired.
1353WFS_ERR_UNSUPP_COMMAND
1354The dwCommand issued, although valid for this service class, is not supported by this Service Provider or device.
1355WFS_ERR_USER_ERROR
1356A user is preventing proper operation of the device.
1357WFS_ERR_UNSUPP_DATA
1358The data structure passed as an input parameter although valid for this service class, is not supported by this Service Provider or device.
1359WFS_ERR_FRAUD_ATTEMPT
1360Some devices are capable of identifying a malicious physical attack which attempts to defraud valuable information or media. In these cases, this error code is returned to indicate the user is attempting a fraudulent act on the device.
1361WFS_ERR_SEQUENCE_ERROR
1362The requested operation is not valid at this time or in the devices current state.
1363WFS_ERR_AUTH_REQUIRED
1364The requested operation cannot be performed because it requires authentication.
1365See Also WFSCancelAsyncRequest, WFSExecute
1366CWA 16926-1:2015 (E)
136760
13685.12 WFSFreeResult
1369HRESULT WFSFreeResult ( lpResult )
1370Notifies the XFS Manager that a memory buffer (or linked list of buffers) that was dynamically allocated by a Service Provider is to be freed.
1371Parameters LPWFSRESULT lpResult
1372Pointer to a WFSRESULT data structure.
1373Mode Immediate
1374Comments The XFS Service Providers may allocate memory to send data to an application. This function is used by the application to deallocate the memory, and the application must call it when it no longer needs access to the memory. When the applications calls WFSFreeResult, all memory allocated by the Service Provider for this result is deallocated. See Section 4.14.
1375Error Codes If the function return is not WFS_SUCCESS, it is one of the following error conditions:
1376WFS_ERR_INTERNAL_ERROR
1377An internal inconsistency or other unexpected error occurred in the XFS subsystem.
1378WFS_ERR_INVALID_RESULT
1379The lpResult parameter is not a pointer to an allocated WFSRESULT structure.
1380WFS_ERR_NOT_STARTED
1381The application has not previously performed a successful WFSStartUp.
1382See Also WFSExecute, WFSAsyncExecute, WFSGetInfo, WFSAsyncGetInfo
1383CWA 16926-1:2015 (E)
138461
13855.13 WFSGetInfo
1386HRESULT WFSGetInfo( hService, dwCategory, lpQueryDetails, dwTimeOut, lppResult )
1387Retrieves information from the specified Service Provider. The synchronous version of WFSAsyncGetInfo.
1388Parameters HSERVICE hService
1389Handle to the Service Provider as returned by WFSOpen or WFSAsyncOpen.
1390DWORD dwCategory
1391Specifies the category of the query (e.g. for a printer, WFS_INF_PTR_STATUS to request status or WFS_INF_PTR_CAPABILITIES to request capabilities). The available categories depend on the service class, the Service Provider and the service. The information requested can be either static or dynamic, e.g. basic service capabilities (static) or current service status (dynamic).
1392LPVOID lpQueryDetails
1393Pointer to the data structure to be passed to the Service Provider, containing further details to make the query more precise, e.g. a form name. Many queries have no input parameters, in which case this pointer is NULL.
1394DWORD dwTimeOut
1395Number of milliseconds to wait for completion (WFS_INDEFINITE_WAIT to specify a request that will wait until completion).
1396LPWFSRESULT * lppResult
1397Pointer to the pointer to the data structure to be filled with the result of the execution. The Service Provider allocates the memory for the structure.
1398Mode Synchronous
1399Comments The XFS Manager passes the request to the Service Provider, and since the information may be stored remotely, the function cannot be immediate. Note that many requests can be satisfied by the Service Provider and will therefore complete immediately.
1400The definitions of the dwCategory and lpQueryDetails parameters are provided in the service-specific command sections of this specification. Note that these information retrieval functions are separate from the other service-specific commands, since those commands can be executed only via WFSExecute or WFSAsyncExecute, which require that the service be either locked by the application issuing the command, or unlocked. The GetInfo functions, however, can be used even when a service is locked by another application.
1401The application must call WFSFreeResult to deallocate the WFSRESULT data structure which is returned by this function. Note that a WFSRESULT structure may be returned even if the function completes with an error; see Section 4.14.
1402Error Codes If the function return is not WFS_SUCCESS, it is one of the following error conditions. Any service-specific errors that can be returned are defined in the specifications for each service class.
1403WFS_ERR_CANCELED
1404The request was canceled by WFSCancelBlockingCall.
1405WFS_ERR_CONNECTION_LOST
1406The connection to the service is lost.
1407WFS_ERR_DEV_NOT_READY
1408The function required device access, and the device was not ready or timed out.
1409WFS_ERR_HARDWARE_ERROR
1410The function required device access, and an error occurred on the device.
1411WFS_ERR_INTERNAL_ERROR
1412An internal inconsistency or other unexpected error occurred in the XFS subsystem.
1413WFS_ERR_INVALID_CATEGORY
1414The dwCategory issued is not supported by this service class.
1415CWA 16926-1:2015 (E)
141662
1417WFS_ERR_INVALID_DATA
1418The data structure passed as input parameter contains invalid data.
1419WFS_ERR_INVALID_HSERVICE
1420The hService parameter is not a valid service handle.
1421WFS_ERR_INVALID_POINTER
1422A pointer parameter does not point to accessible memory.
1423WFS_ERR_NOT_STARTED
1424The application has not previously performed a successful WFSStartUp.
1425WFS_ERR_OP_IN_PROGRESS
1426A blocking operation is in progress on the thread; only WFSCancelBlockingCall and WFSIsBlocking are permitted at this time.
1427WFS_ERR_SOFTWARE_ERROR
1428The function required access to configuration information, and an error occurred on the software.
1429WFS_ERR_TIMEOUT
1430The timeout interval expired.
1431WFS_ERR_UNSUPP_CATEGORY
1432The dwCategory issued, although valid for this service class, is not supported by this Service Provider.
1433WFS_ERR_USER_ERROR
1434A user is preventing proper operation of the device.
1435WFS_ERR_UNSUPP_DATA
1436The data structure passed as an input parameter although valid for this service class, is not supported by this Service Provider or device.
1437See Also WFSAsyncGetInfo
1438CWA 16926-1:2015 (E)
143963
14405.14 WFSAsyncGetInfo
1441HRESULT WFSAsyncGetInfo( hService, dwCategory, lpQueryDetails, dwTimeOut, hWnd, lpRequestID )
1442Retrieves information from the specified Service Provider. The asynchronous version of WFSGetInfo.
1443Parameters HSERVICE hService
1444Handle to the Service Provider as returned by WFSOpen or WFSAsyncOpen.
1445DWORD dwCategory
1446See WFSGetInfo.
1447LPVOID lpQueryDetails
1448See WFSGetInfo.
1449DWORD dwTimeOut
1450Number of milliseconds to wait for completion (WFS_INDEFINITE_WAIT to specify a request that will wait until completion).
1451HWND hWnd
1452The window handle which is to receive the completion message for this request.
1453LPREQUESTID lpRequestID
1454The request identifier for this request (returned parameter).
1455Mode Asynchronous
1456Comments See WFSGetInfo.
1457The only difference in the asynchronous version of the function is that the results (query details) returned to the application (in the WFSRESULT data structure) are pointed to by the WFS_GETINFO_COMPLETE message sent to the specified hWnd.
1458The application must call WFSFreeResult to deallocate the WFSRESULT data structure which is pointed to by the completion message. Note that a WFSRESULT structure may be returned even if the function completes with an error; see Section 4.14.
1459Messages WFS_GETINFO_COMPLETE
1460Error Codes If the function return is not WFS_SUCCESS, it is one of the following error conditions, indicating that the asynchronous operation was not initiated:
1461WFS_ERR_CONNECTION_LOST
1462The connection to the service is lost.
1463WFS_ERR_INTERNAL_ERROR
1464An internal inconsistency or other unexpected error occurred in the XFS subsystem.
1465WFS_ERR_INVALID_CATEGORY
1466The dwCategory issued is not supported by this service class.
1467WFS_ERR_INVALID_HSERVICE
1468The hService parameter is not a valid service handle.
1469WFS_ERR_INVALID_HWND
1470The hWnd parameter is not a valid window handle.
1471WFS_ERR_INVALID_POINTER
1472A pointer parameter does not point to accessible memory.
1473WFS_ERR_NOT_STARTED
1474The application has not previously performed a successful WFSStartUp.
1475WFS_ERR_OP_IN_PROGRESS
1476A blocking operation is in progress on the thread; only WFSCancelBlockingCall and WFSIsBlocking are permitted at this time.
1477CWA 16926-1:2015 (E)
147864
1479WFS_ERR_UNSUPP_CATEGORY
1480The dwCategory issued, although valid for this service class, is not supported by this Service Provider.
1481The following error conditions are returned via the asynchronous command completion message, as the hResult from the WFSRESULT structure. Any service-specific errors that can be returned are defined in the specifications for each service class.
1482WFS_ERR_CANCELED
1483The request was canceled by WFSCancelAsyncRequest.
1484WFS_ERR_DEV_NOT_READY
1485The function required device access, and the device was not ready or timed out.
1486WFS_ERR_HARDWARE_ERROR
1487The function required device access, and an error occurred on the device.
1488WFS_ERR_INTERNAL_ERROR
1489An internal inconsistency or other unexpected error occurred in the XFS subsystem.
1490WFS_ERR_INVALID_DATA
1491The data structure passed as input parameter contains invalid data.
1492WFS_ERR_SOFTWARE_ERROR
1493The function required access to configuration information, and an error occurred on the software.
1494WFS_ERR_TIMEOUT
1495The timeout interval expired.
1496WFS_ERR_USER_ERROR
1497A user is preventing proper operation of the device.
1498WFS_ERR_UNSUPP_DATA
1499The data structure passed as an input parameter although valid for this service class, is not supported by this Service Provider or device.
1500See Also WFSGetInfo, WFSCancelAsyncRequest
1501CWA 16926-1:2015 (E)
150265
15035.15 WFSIsBlocking
1504BOOL WFSIsBlocking( )
1505Determines whether a thread has a blocking operation in progress.
1506Parameters None
1507Return Value The return value is TRUE if a blocking operation is in progress and FALSE otherwise.
1508Mode Immediate
1509Comments Although a call issued on a synchronous (blocking) function appears to an application as though it blocks, the XFS Manager in fact relinquishes control of the processor to allow other Windows processes to run. Thus it is possible for an application that issues a blocking call to be re-entered, depending on the messages it receives. Since the XFS Manager prohibits more than one outstanding blocking call per thread, an application's message processing routines need a way to determine whether they have been re-entered while the application is waiting for an outstanding blocking call to complete. The WFSIsBlocking function provides this function, allowing an application to detect whether a blocking operation is already in progress, before it issues another XFS request.
1510Note that if another XFS call is issued in this situation, the XFS Manager returns with a WFS_ERR_OP_IN_PROGRESS error code. See Section 4.12 for additional discussion.
1511See Also WFSCancelBlockingCall
1512CWA 16926-1:2015 (E)
151366
15145.16 WFSLock
1515HRESULT WFSLock( hService, dwTimeOut, lppResult)
1516Establishes exclusive control by the calling application over the specified service. The synchronous version of WFSAsyncLock.
1517Parameters HSERVICE hService
1518Service Provider handle as returned by WFSOpen or WFSAsyncOpen.
1519DWORD dwTimeOut
1520Number of milliseconds to wait for completion (WFS_INDEFINITE_WAIT to specify a request that will wait until completion).
1521LPWFSRESULT *lppResult
1522Pointer to the pointer to a WFSRESULT data structure (see Comments). The Service Provider allocates the memory for this structure.
1523Mode Synchronous
1524Comments A Service Provider can support a "shared" session, in which multiple applications' data are mixed in the service's I/O stream. More typically, a session is exclusive at any point in time; all I/O is for a single application. To define an exclusive use of the Service Provider, a lock function (synchronous or asynchronous) must be used. See Section 4.8 for more discussion of the lock concepts and policy.
1525The time to complete will depend on whether there is another application that has acquired exclusive access to the service. Note that trying to lock several services at the same time can lead to a deadlock. The timeout capability is provided in the API to allow applications to prevent this.
1526lppResult is a pointer to a pointer to a WFSRESULT data structure containing a null-terminated array of service handles (hService values), specifying any other services that are already locked by the application (i.e. under the same hApp), only if those services are part of a compound device that includes the service being locked, and are interdependent with it. The returned pointer is NULL if there are no such "associated" services locked. See Section 4.8.2 for more discussion of this subject.
1527The application must call WFSFreeResult to deallocate the WFSRESULT data structure, if there is one. Note that a WFSRESULT structure may be returned even if the function completes with an error; see Section 4.14.
1528Error Codes If the function return is not WFS_SUCCESS, it is one of the following error conditions.
1529WFS_ERR_CANCELED
1530The request was canceled by WFSCancelBlockingCall.
1531WFS_ERR_CONNECTION_LOST
1532The connection to the service is lost.
1533WFS_ERR_INTERNAL_ERROR
1534An internal inconsistency or other unexpected error occurred in the XFS subsystem.
1535WFS_ERR_INVALID_HSERVICE
1536The hService parameter is not a valid service handle.
1537WFS_ERR_INVALID_POINTER
1538A pointer parameter does not point to accessible memory.
1539WFS_ERR_NOT_STARTED
1540The application has not previously performed a successful WFSStartUp.
1541WFS_ERR_OP_IN_PROGRESS
1542A blocking operation is in progress on the thread; only WFSCancelBlockingCall and WFSIsBlocking are permitted at this time.
1543WFS_ERR_TIMEOUT
1544The timeout interval expired.
1545CWA 16926-1:2015 (E)
154667
1547See Also WFSAsyncLock, WFSUnlock, WFSCancelBlockingCall
1548CWA 16926-1:2015 (E)
154968
15505.17 WFSAsyncLock
1551HRESULT WFSAsyncLock( hService, dwTimeOut, hWnd, lpRequestID )
1552Establishes exclusive control by the calling application over the specified service. The asynchronous version of WFSLock.
1553Parameters HSERVICE hService
1554Handle to the Service Provider as returned by WFSOpen or WFSAsyncOpen.
1555DWORD dwTimeOut
1556Number of milliseconds to wait for completion (WFS_INDEFINITE_WAIT to specify a request that will wait until completion).
1557HWND hWnd
1558The window handle which is to receive the completion message for this request.
1559LPREQUESTID lpRequestID
1560Pointer to the request identifier for this request (returned parameter).
1561Mode Asynchronous
1562Comments See WFSLock and Section 4.8.2. In particular, note that if other services are locked as a result of this call (i.e. because the service specified is part of a compound device), the handles of these services are returned in the WFSRESULT data structure pointed to by the completion message.
1563The application must call WFSFreeResult to deallocate the WFSRESULT data structure. Note that a WFSRESULT structure may be returned even if the function completes with an error; see Section 4.14.
1564Messages WFS_LOCK_COMPLETE
1565Error Codes If the function return is not WFS_SUCCESS, it is one of the following error conditions, indicating that the asynchronous operation was not initiated:
1566WFS_ERR_CONNECTION_LOST
1567The connection to the service is lost.
1568WFS_ERR_INTERNAL_ERROR
1569An internal inconsistency or other unexpected error occurred in the XFS subsystem.
1570WFS_ERR_INVALID_HSERVICE
1571The hService parameter is not a valid service handle.
1572WFS_ERR_INVALID_HWND
1573The hWnd parameter is not a valid window handle.
1574WFS_ERR_INVALID_POINTER
1575A pointer parameter does not point to accessible memory.
1576WFS_ERR_NOT_STARTED
1577The application has not previously performed a successful WFSStartUp.
1578WFS_ERR_OP_IN_PROGRESS
1579A blocking operation is in progress on the thread; only WFSCancelBlockingCall and WFSIsBlocking are permitted at this time.
1580The following error conditions are returned via the asynchronous command completion message, as the hResult from the WFSRESULT structure.
1581WFS_ERR_CANCELED
1582The request was canceled by WFSCancelAsyncRequest.
1583WFS_ERR_INTERNAL_ERROR
1584An internal inconsistency or other unexpected error occurred in the XFS subsystem.
1585WFS_ERR_TIMEOUT
1586The timeout interval expired.
1587CWA 16926-1:2015 (E)
158869
1589See Also WFSLock, WFSUnlock, WFSCancelAsyncRequest
1590CWA 16926-1:2015 (E)
159170
15925.18 WFSOpen
1593HRESULT WFSOpen( lpszLogicalName, hApp, lpszAppID, dwTraceLevel, dwTimeOut, dwSrvcVersionsRequired, lpSrvcVersion, lpSPIVersion, lphService )
1594Initiates a session (a series of service requests terminated with the WFSClose function) between the application and the specified service. This does not necessarily mean that the hardware is opened. This command will return with WFS_SUCCESS even if the hardware is inoperable, offline or powered off. The status of the device can be requested through a WFSGetInfo command.
1595The synchronous version of WFSAsyncOpen.
1596Parameters LPSTR lpszLogicalName
1597Points to a null-terminated string containing the pre-defined logical name of a service. It is a high level name such as "SYSJOURNAL1", "PASSBOOKPTR3" or "CASHDISP02," that is used by the XFS Manager and the Service Provider solely as a key to obtain the specific configuration information they need.
1598HAPP hApp
1599The application handle to be associated with the session being opened. If this parameter is equal to WFS_DEFAULT_HAPP, the session is associated with the calling process as a whole (i.e. the calling process, not some subset of its threads, is the owner of the session and its hService). See WFSCreateAppHandle and Sections 4.5 and 4.8.2 for details.
1600LPSTR lpszAppID
1601Points to a null-terminated string containing the application ID; the pointer may be NULL if the ID is not used. This ID may be used by services in a variety of ways; e.g. it is included in the SYSTEM_EVENT message for undeliverable events, to aid in finding system problems
1602DWORD dwTraceLevel
1603See WFMSetTraceLevel. NULL turns off all tracing.
1604DWORD dwTimeOut
1605Number of milliseconds to wait for completion (WFS_INDEFINITE_WAIT to specify a request that will wait until completion).
1606DWORD dwSrvcVersionsRequired
1607Specifies the range of versions of the service-specific interface that the application can support. (See Comments.) The low-order word indicates the highest version of the interface the application can support; the high-order word indicates the lowest version of the interface the application can support. In each word, the low-order byte specifies the major version number and the high-order byte specifies the minor version number (i.e. the numbers before and after the decimal). Note: in order to allow intermediate minor revisions (e.g. between 1.10 and 1.20), the minor version number should always be expressed as two decimal digits, i.e. 1.10, 1.11, 1.20, etc.
1608LPWFSVERSION lpSrvcVersion
1609Pointer to the data structure that is to receive version support information and other details about the service-specific interface implementation (returned parameter).
1610LPWFSVERSION lpSPIVersion
1611Pointer to the data structure that is to receive version support information and (optionally) other details about the SPI implementation of the Service Provider being opened (returned parameter). This pointer may be NULL if the application is not interested in receiving this information. See WFPOpen.
1612LPHSERVICE lphService
1613Pointer to the service handle that the XFS Manager assigns to the service on a successful open; the application uses this handle for communication with the Service Provider for the remainder of the session (returned parameter). If a process opens the same service twice, the XFS Manager generates and returns different hService values.
1614Mode Synchronous
1615CWA 16926-1:2015 (E)
161671
1617Comments This function is used by an application to initiate a session with a service; the session is terminated by WFSClose. After WFSStartUp, an application must use this function (or the asynchronous version) to access a service. The request is made in terms of a logical service name (lpLogicalName) which is mapped by the XFS Manager to a Service Provider. The XFS Manager loads the Service Provider, if necessary, and returns a logical service handle to the application which is used during the session to refer to the service.
1618In order to support future XFS implementations with maximum flexibility, two version negotiations take place in WFSOpen processing. An application specifies in the dwSrvcVersionsRequired parameter the range of versions of the service-specific interface (as defined by the events and error codes within this specification and in the separate XFS specifications for specific classes of devices, such as banking printers and cash dispensers) that it can support. If the range of versions specified by the application overlaps the range of versions that the Service Provider’s implementation can support, the call succeeds. Otherwise the call fails. (The other negotiation that takes place during the open process is between the XFS Manager and the Service Provider regarding the SPI level. See WFPOpen for details.)
1619Information describing the actual Service Provider implementation is returned in the WFSVERSION data structure (defined in Section 9.2 ). In particular, it returns the version the Service Provider expects the application to use (the highest common version), as well as the lowest and highest versions it is capable of. If the call fails, WFSVERSION is still returned, to help with analysis of the failure.
1620The version numbers refer to the complete interface specification: the service-specific WFSExecute and WFSGetInfo commands, parameters, data structures, error codes, and messages. If there are any changes to these, the version number should be changed.
1621This version negotiation allows an XFS application and a Service Provider to operate successfully if there is any overlap in their versions. The following chart gives examples of how WFSOpen works in conjunction with different application and Service Provider versions:
1622dwSrvcVersions-Required (Version required by Application):
1623lpSrvcVersion.wLowVerion lpSrvcVersion.wHighVersion (Service Provider versions):
1624Return status from WFSOpen:
1625lpSrvcVersion .wVersion (Result):
16260x00010001 (1.00)
16270x0001 0x0001 (1.00)
1628WFS_SUCCESS
16290x0001 (use 1.00)
16300x00010A02 (1.00 - 2.10)
16310x0001 0x0001 (1.00)
1632WFS_SUCCESS
16330x0001 (use 1.00)
16340x0B010B01 (1.11)
16350x0001 0x0002 (1.00 - 2.00)
1636WFS_SUCCESS
16370x0B01 (use 1.11)
16380x0B020003 (2.11 - 3.00)
16390x0001 0x1402 (1.00 - 2.20)
1640WFS_SUCCESS
16410x1402 (use 2.20)
16420x00010001 (1.00)
16430x1402 0x0003 (2.20 - 3.00)
1644WFS_ERR_SRVC_VERS_TOO_LOW
16450x0000 (fails)
16460x0B010003 (1.11 - 3.00)
16470x0001 0x0001 (1.00)
1648WFS_ERR_SRVC_VERS_TOO_HIGH
16490x0000 (fails)
1650Note that a version negotiation error also generates a system event (see Section 10.8).
1651If a valid Service Provider is available, the Open command will not complete until the Service Provider and all its dependencies are running. That is, if an out of process executable is required by this Service Provider, this executable should be running and fully initialized before completion of the Open command. The starting and stopping of external dependent processes is not defined as the responsibility of the Service Provider, but the latter has to be aware of and respond correctly to the Open command according to external dependent process state. In addition, if the specified timeout period expires before dependent external processes have correctly initialized, the Service Provider must complete and return WFS_ERR_TIMEOUT as expected.
1652Error Codes If the function return is not WFS_SUCCESS, it is one of the following error conditions.
1653WFS_ERR_CANCELED
1654The request was canceled by WFSCancelBlockingCall.
1655WFS_ERR_CONNECTION_LOST
1656The connection to the service is lost.
1657WFS_ERR_INTERNAL_ERROR
1658An internal inconsistency or other unexpected error occurred in the XFS subsystem.
1659CWA 16926-1:2015 (E)
166072
1661WFS_ERR_INVALID_APP_HANDLE
1662The specified application handle is not valid, i.e. was not created by a preceding create call.
1663WFS_ERR_INVALID_POINTER
1664A pointer parameter does not point to accessible memory.
1665WFS_ERR_INVALID_SERVPROV
1666The file containing the Service Provider is invalid or corrupted.
1667WFS_ERR_INVALID_TRACELEVEL
1668The dwTraceLevel parameter does not correspond to a valid trace level or set of levels.
1669WFS_ERR_NO_SERVPROV
1670The file containing the Service Provider does not exist.
1671WFS_ERR_NOT_STARTED
1672The application has not previously performed a successful WFSStartUp.
1673WFS_ERR_OP_IN_PROGRESS
1674A blocking operation is in progress on the thread; only WFSCancelBlockingCall and WFSIsBlocking are permitted at this time.
1675WFS_ERR_SERVICE_NOT_FOUND
1676The logical name is not a valid Service Provider name.
1677WFS_ERR_SOFTWARE_ERROR
1678The function required access to configuration information, and an error occurred on the software.
1679WFS_ERR_SPI_VER_TOO_HIGH
1680The range of versions of XFS SPI support requested by the XFS Manager is higher than any supported by the Service Provider for the logical service being opened.
1681WFS_ERR_SPI_VER_TOO_LOW
1682The range of versions of XFS SPI support requested by the XFS Manager is lower than any supported by the Service Provider for the logical service being opened.
1683WFS_ERR_SRVC_VER_TOO_HIGH
1684The range of versions of the service-specific interface support requested by the application (in the dwSrvcVersionsRequired parameter of this call) is higher than any supported by the Service Provider for the logical service being opened.
1685WFS_ERR_SRVC_VER_TOO_LOW
1686The range of versions of the service-specific interface support requested by the application (in the dwSrvcVersionsRequired parameter of this call) is lower than any supported by the Service Provider for the logical service being opened.
1687WFS_ERR_TIMEOUT
1688The timeout interval expired.
1689WFS_ERR_VERSION_ERROR_IN_SRVC
1690Within the service, a version mismatch of two modules occurred.
1691See Also WFSAsyncOpen, WFSClose, WFSCreateAppHandle
1692CWA 16926-1:2015 (E)
169373
16945.19 WFSAsyncOpen
1695HRESULT WFSAsyncOpen( lpszLogicalName, hApp, lpszAppID, dwTraceLevel, dwTimeOut, lphService, hWnd, dwSrvcVersionsRequired, lpSrvcVersion, lpSPIVersion, lpRequestID )
1696Initiates a session (a series of service requests terminated with the WFSClose or WFSAsyncClose function) between the application and the specified service. This does not necessarily mean that the hardware is opened. This command will return with WFS_SUCCESS even if the hardware is inoperable, offline or powered off. The status of the device can be requested through a WFSGetInfo command.
1697The asynchronous version of WFSOpen.
1698Parameters LPSTR lpszLogicalName
1699See WFSOpen.
1700HAPP hApp
1701The application handle to be associated with the session being opened. See WFSOpen, WFSCreateAppHandle and Sections 4.5 and 4.8.2 for details.
1702LPSTR lpszAppID
1703Points to a null-terminated string containing the application ID. See WFSOpen.
1704DWORD dwTraceLevel
1705See WFMSetTraceLevel. NULL turns off all tracing.
1706DWORD dwTimeOut
1707Number of milliseconds to wait for completion (WFS_INDEFINITE_WAIT to specify a request that will wait until completion).
1708LPHSERVICE lphService
1709Pointer to the service handle (returned parameter).
1710HWND hWnd
1711The window handle which is to receive the completion message for this request.
1712DWORD dwSrvcVersionsRequired
1713See WFSOpen.
1714LPWFSVERSION lpSrvcVersion
1715See WFSOpen (returned parameter).
1716LPWFSVERSION lpSPIVersion
1717See WFSOpen (returned parameter).
1718LPREQUESTID lpRequestID
1719Pointer to the request identifier for this request (returned parameter).
1720Mode Asynchronous
1721Comments See WFSOpen.
1722The application must call WFSFreeResult to deallocate the WFSRESULT data structure which is pointed to by the completion message. Note that a WFSRESULT structure may be returned even if the function completes with an error; see Section 4.14.
1723Messages WFS_OPEN_COMPLETE
1724Error Codes If the function return is not WFS_SUCCESS, it is one of the following error conditions, indicating that the asynchronous operation was not initiated:
1725WFS_ERR_CONNECTION_LOST
1726The connection to the service is lost.
1727WFS_ERR_INTERNAL_ERROR
1728An internal inconsistency or other unexpected error occurred in the XFS subsystem.
1729CWA 16926-1:2015 (E)
173074
1731WFS_ERR_INVALID_APP_HANDLE
1732The specified application handle is not valid, i.e. was not created by a preceding create call.
1733WFS_ERR_INVALID_HWND
1734The hWnd parameter is not a valid window handle.
1735WFS_ERR_INVALID_POINTER
1736A pointer parameter does not point to accessible memory.
1737WFS_ERR_INVALID_SERVPROV
1738The file containing the Service Provider is invalid or corrupted.
1739WFS_ERR_INVALID_TRACELEVEL
1740The dwTraceLevel parameter does not correspond to a valid trace level or set of levels.
1741WFS_ERR_NO_SERVPROV
1742The file containing the Service Provider does not exist.
1743WFS_ERR_NOT_STARTED
1744The application has not previously performed a successful WFSStartUp.
1745WFS_ERR_OP_IN_PROGRESS
1746A blocking operation is in progress on the thread; only WFSCancelBlockingCall and WFSIsBlocking are permitted at this time.
1747WFS_ERR_SERVICE_NOT_FOUND
1748The logical name is not a valid Service Provider name.
1749WFS_ERR_SPI_VER_TOO_HIGH
1750The range of versions of XFS SPI support requested by the XFS Manager is higher than any supported by the Service Provider for the logical service being opened.
1751WFS_ERR_SPI_VER_TOO_LOW
1752The range of versions of XFS SPI support requested by the XFS Manager is lower than any supported by the Service Provider for the logical service being opened.
1753WFS_ERR_SRVC_VER_TOO_HIGH
1754The range of versions of the service-specific interface support requested by the application (in the dwSrvcVersionsRequired parameter of this call) is higher than any supported by the Service Provider for the logical service being opened.
1755WFS_ERR_SRVC_VER_TOO_LOW
1756The range of versions of the service-specific interface support requested by the application (in the dwSrvcVersionsRequired parameter of this call) is lower than any supported by the Service Provider for the logical service being opened.
1757WFS_ERR_VERSION_ERROR_IN_SRVC
1758Within the service, a version mismatch of two modules occurred.
1759The following error conditions are returned via the asynchronous command completion message, as the hResult from the WFSRESULT structure. Any service-specific errors that can be returned are defined in the specifications for each service class.
1760WFS_ERR_CANCELED
1761The request was canceled by WFSCancelAsyncRequest.
1762WFS_ERR_DEV_NOT_READY
1763The function required device access, and the device was not ready timed out.
1764WFS_ERR_INTERNAL_ERROR
1765An internal inconsistency or other unexpected error occurred in the XFS subsystem.
1766WFS_ERR_HARDWARE_ERROR
1767The function required device access, and an error occurred on the device.
1768WFS_ERR_SOFTWARE_ERROR
1769The function required access to configuration information, and an error occurred on the software.
1770WFS_ERR_TIMEOUT
1771The timeout interval expired.
1772CWA 16926-1:2015 (E)
177375
1774WFS_ERR_VERSION_ERROR_IN_SRVC
1775Within the service, a version mismatch of two modules occurred.
1776See Also WFSOpen, WFSClose, WFSCreateAppHandle, WFSCancelAsyncRequest, WFMSetTraceLevel
1777CWA 16926-1:2015 (E)
177876
17795.20 WFSRegister
1780HRESULT WFSRegister( hService, dwEventClass, hWndReg )
1781Enables event monitoring for the specified service by the specified window; all messages of the specified class(es) are sent to the window specified in the hWndReg parameter. The synchronous version of WFSAsyncRegister.
1782Parameters HSERVICE hService
1783Handle to the Service Provider as returned by WFSOpen or WFSAsyncOpen. If this value is NULL, and dwEventClass is SYSTEM_EVENTS, the XFS manager registers the application for those system events generated by the Manager itself.
1784DWORD dwEventClass
1785The class(es) of events for which the application is registering. Specified as a set of bit masks that are logically ORed together into this parameter.
1786HWND hWndReg
1787The window handle which is to be registered to receive the specified messages.
1788Mode Synchronous
1789Comments Issuing a WFSRegister for a service enables event monitoring on that service. WFSRegister calls can be cumulative for the same window. For example, to receive notification for both system and user events, the application can call WFSRegister with both SYSTEM_EVENTS and USER_EVENTS, as follows:
1790hr = WFSRegister(hPassbook1, SYSTEM_EVENTS | USER_EVENTS, hWndReg1);
1791or call them in two phases:
1792hr = WFSRegister( hPassbook1, SYSTEM_EVENTS, hWndReg1);
1793. . . . . . . .
1794hr = WFSRegister( hPassbook1, USER_EVENTS, hWndReg1);
1795To cancel notifications use WFSDeregister.
1796Note that the Service Provider always monitors the service, regardless of whether an application has registered for event monitoring. Issuing WFSRegister simply causes the Service Provider to post messages to the application in addition to handling the messages itself. See the discussion in Section 4.11.
1797Error Codes If the function return is not WFS_SUCCESS, it is one of the following error conditions.
1798WFS_ERR_CANCELED
1799The request was canceled by WFSCancelBlockingCall.
1800WFS_ERR_CONNECTION_LOST
1801The connection to the service is lost.
1802WFS_ERR_INTERNAL_ERROR
1803An internal inconsistency or other unexpected error occurred in the XFS subsystem.
1804WFS_ERR_INVALID_EVENT_CLASS
1805The dwEventClass parameter specifies one or more event classes not supported by the service.
1806WFS_ERR_INVALID_HSERVICE
1807The hService parameter is not a valid service handle.
1808WFS_ERR_INVALID_HWNDREG
1809The hWndReg parameter is not a valid window handle.
1810WFS_ERR_NOT_STARTED
1811The application has not previously performed a successful WFSStartUp.
1812WFS_ERR_OP_IN_PROGRESS
1813A blocking operation is in progress on the thread; only WFSCancelBlockingCall and WFSIsBlocking are permitted at this time.
1814See Also WFSAsyncRegister, WFSDeregister, WFSAsyncDeregister
1815CWA 16926-1:2015 (E)
181677
18175.21 WFSAsyncRegister
1818HRESULT WFSAsyncRegister( hService, dwEventClass, hWndReg, hWnd, lpRequestID )
1819Enables event monitoring for the specified service by the specified window; all messages of the specified class(es) are sent to the window specified in the hWndReg parameter. The asynchronous version of WFSRegister.
1820Parameters HSERVICE hService
1821Handle to the Service Provider as returned by WFSOpen or WFSAsyncOpen. If this value is NULL, and dwEventClass is SYSTEM_EVENTS, the XFS manager registers the application for those system events generated by the Manager itself.
1822DWORD dwEventClass
1823See WFSRegister.
1824HWND hWndReg
1825The window handle which is to be registered to receive the specified messages.
1826HWND hWnd
1827The window handle which is to receive the completion message for this request.
1828LPREQUESTID lpRequestID
1829Pointer to the request identifier for this request (returned parameter).
1830Mode Asynchronous
1831Comments See WFSRegister.
1832The application must call WFSFreeResult to deallocate the WFSRESULT data structure pointed to by the completion message. Note that a WFSRESULT structure may be returned even if the function completes with an error; see Section 4.11.
1833Messages WFS_REGISTER_COMPLETE
1834Error Codes If the function return is not WFS_SUCCESS, it is one of the following error conditions, indicating that the asynchronous operation was not initiated:
1835WFS_ERR_CONNECTION_LOST
1836The connection to the service is lost.
1837WFS_ERR_INTERNAL_ERROR
1838An internal inconsistency or other unexpected error occurred in the XFS subsystem.
1839WFS_ERR_INVALID_EVENT_CLASS
1840The dwEventClass parameter specifies one or more event classes not supported by the service.
1841WFS_ERR_INVALID_HSERVICE
1842The hService parameter is not a valid service handle.
1843WFS_ERR_INVALID_HWND
1844The hWnd parameter is not a valid window handle.
1845WFS_ERR_INVALID_HWNDREG
1846The hWndReg parameter is not a valid window handle.
1847WFS_ERR_NOT_STARTED
1848The application has not previously performed a successful WFSStartUp.
1849WFS_ERR_OP_IN_PROGRESS
1850A blocking operation is in progress on the thread; only WFSCancelBlockingCall and WFSIsBlocking are permitted at this time.
1851CWA 16926-1:2015 (E)
185278
1853The following error conditions can be returned via the asynchronous command completion message, as the hResult from the WFSRESULT structure.
1854WFS_ERR_CANCELED
1855The request was canceled by WFSCancelAsyncRequest.
1856WFS_ERR_INTERNAL_ERROR
1857An internal inconsistency or other unexpected error occurred in the XFS subsystem.
1858See Also WFSRegister, WFSDeregister, WFSAsyncDeregister
1859CWA 16926-1:2015 (E)
186079
18615.22 WFSSetBlockingHook
1862HRESULT WFSSetBlockingHook( lpBlockFunc, lppPrevFunc )
1863Establishes an application-specific blocking routine.
1864Parameters XFSBLOCKINGHOOK lpBlockFunc
1865Pointer to the procedure instance address of the blocking routine to be installed.
1866LPXFSBLOCKINGHOOK lppPrevFunc
1867Returned pointer to a pointer to the procedure instance of the previously installed blocking routine.
1868Mode Immediate
1869Comments When this function is successfully issued by an application, it returns a pointer to the previously installed blocking routine. The application may save this pointer so that it can be restored if desired. If such “nesting” is not required, the application can discard this value and simply use the WFSUnhookBlockingHook function to restore the default routine at any time.
1870See Section 4.12 for a complete discussion.
1871Error Codes If the function return is not WFS_SUCCESS, it is one of the following error conditions:
1872WFS_ERR_INTERNAL_ERROR
1873An internal inconsistency or other unexpected error occurred in the XFS subsystem.
1874WFS_ERR_NOT_STARTED
1875The application has not previously performed a successful WFSStartUp.
1876WFS_ERR_OP_IN_PROGRESS
1877A blocking operation is in progress on the thread; only WFSCancelBlockingCall and WFSIsBlocking are permitted at this time.
1878WFS_ERR_INVALID_POINTER
1879A pointer parameter does not point to accessible memory.
1880See Also WFSUnhookBlockingHook, WFSCancelBlockingCall, WFSIsBlocking
1881CWA 16926-1:2015 (E)
188280
18835.23 WFSStartUp
1884HRESULT WFSStartUp( dwVersionsRequired, lpWFSVersion )
1885Establishes a connection between an application and the XFS Manager.
1886Parameters DWORD dwVersionsRequired
1887Specifies the range of versions of the XFS Manager that the application can support. The low-order word indicates the highest version of the XFS Manager the application can support; the high-order word indicates the lowest version of the XFS Manager the application can support. In each word, the low-order byte specifies the major version number and the high-order byte specifies the minor version number (i.e. the numbers before and after the decimal). Note: in order to allow intermediate minor revisions (e.g. between 1.10 and 1.20), the minor version number should always be expressed as two decimal digits, i.e. 1.10, 1.11, 1.20, etc.
1888LPWFSVERSION lpWFSVersion
1889Pointer to the data structure that is to receive version support information and other details about the current XFS implementation (returned parameter).
1890Mode Immediate
1891Comments This function is used by an application to register itself with the XFS Manager and specify the version(s) of the XFS API specification it can use, and returns information on the specific XFS implementation. It must be the first XFS API function called by an application. An application may only issue further XFS functions after a successful WFSStartUp has completed.
1892In order to support future XFS implementations with maximum flexibility, a version negotiation process takes place in WFSStartUp. An application specifies in the dwVersionsRequired parameter the range of versions of the XFS API specification which it can support. If the range of versions specified by the application overlaps the range of versions that the current implementation of XFS Manager can support, the call succeeds. Otherwise the call fails.
1893Information describing the actual XFS implementation is returned by the XFS Manager in the WFSVERSION data structure (defined in Section 9.2). In particular, it returns the version it expects the application to use (the highest common version), as well as the lowest and highest versions it is capable of. If the call fails, WFSVERSION is still returned, to help with analysis of the failure.
1894The version numbers refer to the API specification, specifically functions, parameters, data structures, error codes, and messages. If there are any changes to these, the version number should be changed.
1895This version negotiation allows an XFS application and the XFS Manager to operate successfully if there is any overlap in their versions. The following chart gives examples of how WFSStartUp works in conjunction with different application and XFS Manager versions:
1896dwVersionsRequired (Versions required by Application):
1897lpWFSVersion.wLowVersion lpWFSVersion.wHighVersion (XFS Manager versions):
1898Return status from WFSStartUp:
1899lpWFSVersion .wVersion (Result):
19000x00010001 (1.00)
19010x0001 (1.00)
1902WFS_SUCCESS
19030x0001 (use 1.00)
19040x00010A02 (1.00 - 2.10)
19050x0001 0x0001 (1.00)
1906WFS_SUCCESS
19070x0001 (use 1.00)
19080x0B010B01 (1.11)
19090x0001 0x0002 (1.00 - 2.00)
1910WFS_SUCCESS
19110x0B01 (use 1.11)
19120x0B020003 (2.11 - 3.00)
19130x0001 0x1402 (1.00 - 2.20)
1914WFS_SUCCESS
19150x1402 (use 2.20)
19160x00010001 (1.00)
19170x1402 0x0003 (2.20 - 3.00)
1918WFS_ERR_API_VER_TOO_LOW
19190x0000 (fails)
19200x0B010003 (1.11 - 3.00)
19210x0001 0x0001 (1.00)
1922WFS_ERR_API_VER_TOO_HIGH
19230x0000 (fails)
1924Note that a version negotiation error also generates a system event (see Section 10.8).
1925After making its last XFS call, an application must call WFSCleanUp to allow the XFS Manager to release any resources allocated for the application.
1926CWA 16926-1:2015 (E)
192781
1928Error Codes The return value indicates whether the application was registered successfully (i.e. the XFS Manager can support requests from the application). If the function was successful, the returned value is WFS_SUCCESS; if not, it is one of the following error conditions:
1929WFS_ERR_ALREADY_STARTED
1930A WFSStartUp has already been issued by the application, without an intervening WFSCleanUp.
1931WFS_ERR_API_VER_TOO_HIGH
1932The range of versions of XFS API support requested by the application is higher than any supported by this particular XFS implementation.
1933WFS_ERR_API_VER_TOO_LOW
1934The range of versions of XFS API support requested by the application is lower than any supported by this particular XFS implementation.
1935WFS_ERR_INTERNAL_ERROR
1936An internal inconsistency or other unexpected error occurred in the XFS subsystem.
1937WFS_ERR_INVALID_POINTER
1938A pointer parameter does not point to accessible memory.
1939See Also WFSCleanUp
1940CWA 16926-1:2015 (E)
194182
19425.24 WFSUnhookBlockingHook
1943HRESULT WFSUnhookBlockingHook( )
1944Removes any previous blocking hook that had been installed and reinstalls the default blocking mechanism.
1945Parameters None.
1946Mode Immediate
1947Comments The function will always install the default routine, not the previous routine. If an application wishes to nest blocking hook routines - i.e. to establish a temporary blocking call and then revert to the previous mechanism - it must save and restore the value returned by the WFSSetBlockingHook function. See Section 4.12.
1948Error Codes If the function return is not WFS_SUCCESS, it is one of the following error conditions:
1949WFS_ERR_INTERNAL_ERROR
1950An internal inconsistency or other unexpected error occurred in the XFS subsystem.
1951WFS_ERR_NOT_STARTED
1952The application has not previously performed a successful WFSStartUp.
1953WFS_ERR_OP_IN_PROGRESS
1954A blocking operation is in progress on the thread; only WFSCancelBlockingCall and WFSIsBlocking are permitted at this time.
1955See Also WFSSetBlockingHook
1956CWA 16926-1:2015 (E)
195783
19585.25 WFSUnlock
1959HRESULT WFSUnlock( hService )
1960Releases a service that has been locked by a previous WFSLock or WFSAsyncLock function. The synchronous version of WFSAsyncUnlock.
1961Parameters HSERVICE hService
1962Handle to the Service Provider as returned by WFSOpen or WFSAsyncOpen.
1963Mode Synchronous
1964Comments See Section 4.8.
1965Error Codes If the function return is not WFS_SUCCESS, it is one of the following error conditions:
1966WFS_ERR_CANCELED
1967The request was canceled by WFSCancelBlockingCall.
1968WFS_ERR_CONNECTION_LOST
1969The connection to the service is lost.
1970WFS_ERR_INTERNAL_ERROR
1971An internal inconsistency or other unexpected error occurred in the XFS subsystem.
1972WFS_ERR_INVALID_HSERVICE
1973The hService parameter is not a valid service handle.
1974WFS_ERR_NOT_LOCKED
1975The application requesting a service be unlocked had not previously performed a successful WFSLock or WFSAsyncLock.
1976WFS_ERR_NOT_STARTED
1977The application has not previously performed a successful WFSStartUp.
1978WFS_ERR_OP_IN_PROGRESS
1979A blocking operation is in progress on the thread; only WFSCancelBlockingCall and WFSIsBlocking are permitted at this time.
1980See Also WFSAsyncUnlock, WFSLock, WFSAsyncLock
1981CWA 16926-1:2015 (E)
198284
19835.26 WFSAsyncUnlock
1984HRESULT WFSAsyncUnlock( hService, hWnd, lpRequestID )
1985Releases a service that has been locked by a previous WFSLock or WFSAsyncLock function. The asynchronous version of WFSUnlock.
1986Parameters HSERVICE hService
1987Handle to the Service Provider as returned by WFSOpen or WFSAsyncOpen.
1988HWND hWnd
1989The window handle which is to receive the completion message for this request.
1990LPREQUESTID lpRequestID
1991Pointer to the request identifier for this request (returned parameter).
1992Mode Asynchronous
1993Comments See WFSUnlock and Section 4.8.
1994The application must call WFSFreeResult to deallocate the WFSRESULT data structure which is pointed to by the completion message. Note that a WFSRESULT structure may be returned even if the function completes with an error; see Section 4.14.
1995Messages WFS_UNLOCK_COMPLETE
1996Error Codes If the function return is not WFS_SUCCESS, it is one of the following error conditions, indicating that the asynchronous operation was not initiated:
1997WFS_ERR_CONNECTION_LOST
1998The connection to the service is lost.
1999WFS_ERR_INTERNAL_ERROR
2000An internal inconsistency or other unexpected error occurred in the XFS subsystem.
2001WFS_ERR_INVALID_HSERVICE
2002The hService parameter is not a valid service handle.
2003WFS_ERR_INVALID_HWND
2004The hWnd parameter is not a valid window handle.
2005WFS_ERR_INVALID_POINTER
2006A pointer parameter does not point to accessible memory.
2007WFS_ERR_NOT_STARTED
2008The application has not previously performed a successful WFSStartUp.
2009WFS_ERR_OP_IN_PROGRESS
2010A blocking operation is in progress on the thread; only WFSCancelBlockingCall and WFSIsBlocking are permitted at this time.
2011The following error conditions are returned via the asynchronous command completion message, as the hResult from the WFSRESULT structure:
2012WFS_ERR_CANCELED
2013The request was canceled by WFSCancelAsyncRequest.
2014WFS_ERR_INTERNAL_ERROR
2015An internal inconsistency or other unexpected error occurred in the XFS subsystem.
2016WFS_ERR_NOT_LOCKED
2017The application requesting a service be unlocked had not previously performed a successful WFSLock or WFSAsyncLock.
2018See Also WFSUnlock, WFSLock, WFSAsyncLock
2019CWA 16926-1:2015 (E)
202085
20216. Service Provider Interface (SPI) Functions
2022The Service Provider functions are described in the following sections, in alphabetical order. The table below shows the SPI functions, the sections in which they are defined, their modes, and the API functions they implement. The asynchronous SPI functions behavior is influenced by whether the function is Deferred or Non-deferred [see section 4.8 Exclusive Service and Device Access]. An asynchronous non-deferred function (for example WFPRegister) can be processed completely by the service as soon as it is received. An asynchronous deferred function (for example WFPExecute) cannot be processed completely as soon as it arrives, because it may require hardware and/or operator interaction.
2023Section
2024XFS SPI
2025Mode
2026XFS API
2027Mode
20286.1
2029WFPCancelAsyncRequest
2030Immediate
2031WFSCancelAsyncRequest
2032Immediate
20336.1
2034WFPCancelAsyncRequest
2035Immediate
2036WFSCancelBlockingCall
2037Immediate
2038(none)
2039-
2040WFSCleanUp
2041Synchronous
20426.2
2043WFPClose
2044Asynchronous
2045WFSClose
2046Synchronous
20476.2
2048WFPClose
2049Asynchronous
2050WFSAsyncClose
2051Asynchronous
2052(none)
2053-
2054WFSCreateAppHandle
2055Immediate
20566.3
2057WFPDeregister
2058Asynchronous
2059WFSDeregister
2060Synchronous
20616.3
2062WFPDeregister
2063Asynchronous
2064WFSAsyncDeregister
2065Asynchronous
2066(none)
2067-
2068WFSDestroyAppHandle
2069Immediate
20706.4
2071WFPExecute
2072Asynchronous
2073WFSExecute
2074Synchronous
20756.4
2076WFPExecute
2077Asynchronous
2078WFSAsyncExecute
2079Asynchronous
2080(none)
2081-
2082WFSFreeResult
2083Immediate
20846.5
2085WFPGetInfo
2086Asynchronous
2087WFSGetInfo
2088Synchronous
20896.5
2090WFPGetInfo
2091Asynchronous
2092WFSAsyncGetInfo
2093Asynchronous
2094(none)
2095-
2096WFSIsBlocking
2097Immediate
20986.6
2099WFPLock
2100Asynchronous
2101WFSLock
2102Synchronous
21036.6
2104WFPLock
2105Asynchronous
2106WFSAsyncLock
2107Asynchronous
21086.7
2109WFPOpen
2110Asynchronous
2111WFSOpen
2112Synchronous
21136.7
2114WFPOpen
2115Asynchronous
2116WFSAsyncOpen
2117Asynchronous
21186.8
2119WFPRegister
2120Asynchronous
2121WFSRegister
2122Synchronous
21236.8
2124WFPRegister
2125Asynchronous
2126WFSAsyncRegister
2127Asynchronous
2128(none)
2129-
2130WFSSetBlockingHook
2131Immediate
21326.9
2133WFPSetTraceLevel
2134Immediate
2135(none)
2136-
2137(none)
2138-
2139WFSStartUp
2140Immediate
2141(none)
2142-
2143WFSUnhookBlockingHook
2144Immediate
21456.10
2146WFPUnloadService
21476.11
2148WFPUnlock
2149Asynchronous
2150WFSUnlock
2151Synchronous.
21526.11
2153WFPUnlock
2154Asynchronous
2155WFSAsyncUnlock
2156Asynchronous
2157Note that in this section device drivers and devices are mentioned frequently, instead of Service Providers and services. This is due primarily to the fact that access to financial peripheral devices is the first category of financial services being addressed by the BSVC. However, note that in the future other financial services will be part of the Extensions to Financial Services, and will also use these interfaces, with additions as necessary. See Appendix A for more on this subject.
2158CWA 16926-1:2015 (E)
215986
21606.1 WFPCancelAsyncRequest
2161HRESULT WFPCancelAsyncRequest( hService, RequestID )
2162Cancels the specified (or every) asynchronous request being performed on the specified Service Provider, before its (their) completion.
2163Parameters HSERVICE hService
2164Handle to the Service Provider.
2165REQUESTID RequestID
2166The request identifier (NULL to cancel all requests for the specified hService).
2167Mode Immediate. Although the cancellation process itself is asynchronous, the completion message(s) are associated with the original request, not the cancel request (even if they indicate a WFS_ERR_CANCELED status).
2168Comments If the RequestID parameter is set to NULL, the command will cancel all asynchronous requests on the specified service that are in progress on behalf of the calling application.
2169A previously initiated asynchronous request is canceled prior to completion by issuing the WFSCancelAsyncRequest function, specifying the request identifier returned by the asynchronous function. This function is immediate with respect to its calling application, but the cancellation process is inherently asynchronous. On completion, the specified request (or all the requests) will have finished, with a completion message indicating a status of WFS_ERR_CANCELED, unless the cancel request was made after the request had completed.
2170The cancellation applies to the Service Provider level. The request is passed through the SPI, and the Service Provider normally then also cancels any physical I/O or other device operation in progress, in the appropriate manner for the device or service.
2171Error Codes If the function return is not WFS_SUCCESS, it is one of the following error conditions:
2172WFS_ERR_CONNECTION_LOST
2173The connection to the service is lost.
2174WFS_ERR_INTERNAL_ERROR
2175An internal inconsistency or other unexpected error occurred in the XFS subsystem.
2176WFS_ERR_INVALID_HSERVICE
2177The hService parameter is not a valid service handle.
2178WFS_ERR_INVALID_REQ_ID
2179The RequestID parameter does not correspond to an outstanding request on the service.
2180CWA 16926-1:2015 (E)
218187
21826.2 WFPClose
2183HRESULT WFPClose( hService, hWnd, ReqID )
2184Terminates a session (a series of service requests initiated with the WFPOpen SPI function) between the XFS Manager and the specified Service Provider.
2185Parameters HSERVICE hService
2186Handle to the Service Provider.
2187HWND hWnd
2188The window handle which is to receive the completion message for this request.
2189REQUESTID ReqID
2190Request identification number.
2191Mode Asynchronous
2192Comments WFPClose directs the service to free all resources associated with the series of requests made using the hService parameter. If the service is locked by the application, the close automatically unlocks it. If no WFPDeregister has been issued, it is automatically performed.
2193See WFPOpen and Section 4.6 for further discussion.
2194Messages WFS_CLOSE_COMPLETE
2195Error Codes If the function return is not WFS_SUCCESS, it is one of the following error conditions, indicating that the asynchronous operation was not initiated. The service-specific errors that can be returned are defined in the specifications for each service class.
2196WFS_ERR_CONNECTION_LOST
2197The connection to the service is lost.
2198WFS_ERR_INTERNAL_ERROR
2199An internal inconsistency or other unexpected error occurred in the XFS subsystem.
2200WFS_ERR_INVALID_HSERVICE
2201The hService parameter is not a valid service handle.
2202WFS_ERR_INVALID_HWND
2203The hWnd parameter is not a valid window handle.
2204The following error conditions are returned via the asynchronous command completion message, as the hResult from the WFSRESULT structure. Any service-specific errors that can be returned are defined in the specifications for each service class.
2205WFS_ERR_CANCELED
2206The request was canceled by WFSCancelAsyncRequest.
2207WFS_ERR_INTERNAL_ERROR
2208An internal inconsistency or other unexpected error occurred in the XFS subsystem.
2209CWA 16926-1:2015 (E)
221088
22116.3 WFPDeregister
2212HRESULT WFPDeregister( hService, dwEventClass, hWndReg, hWnd, ReqID )
2213Discontinues monitoring of the specified message class(es) from the specified Service Provider, by the specified hWndReg (or all hWnd's).
2214Parameters HSERVICE hService
2215Handle to the Service Provider
2216DWORD dwEventClass
2217The class(es) of messages from which the application is deregistering. Specified as a set of bit masks that can be logically ORed together. A NULL value requests that all message classes be deregistered from the specified window for this Service Provider.
2218HWND hWndReg
2219The window to which notification messages are posted. A NULL value requests that all the application's windows be deregistered from the specified message class(es) for this hService.
2220HWND hWnd
2221The window handle which is to receive the completion message for this request.
2222REQUESTID ReqID
2223Request identification number.
2224Mode Asynchronous
2225Comments WFPDeregister does not stop asynchronous command completion messages from being posted; a robust application should be designed to accept these messages even after a deregister is issued.
2226A WFPDeregister os performed automatically if a WFPClose is issued without a previous WFPDeregister.
2227To deregister all messages for all hWnds, the call supplies NULL values for both the dwEventClass and hWnd parameters.
2228See the WFPRegister function for a description of the types of events that may be monitored.
2229Messages WFS_DEREGISTER_COMPLETE
2230Error Codes If the function return is not WFS_SUCCESS, it is one of the following error conditions, indicating that the asynchronous operation was not initiated. Any service-specific errors that can be returned are defined in the specifications for each service class.
2231WFS_ERR_CONNECTION_LOST
2232The connection to the service is lost.
2233WFS_ERR_INTERNAL_ERROR
2234An internal inconsistency or other unexpected error occurred in the XFS subsystem.
2235WFS_ERR_INVALID_EVENT_CLASS
2236The dwEventClass parameter specifies one or more event classes not supported by the service.
2237WFS_ERR_INVALID_HSERVICE
2238The hService parameter is not a valid service handle.
2239WFS_ERR_INVALID_HWND
2240The hWnd parameter is not a valid window handle.
2241WFS_ERR_INVALID_HWNDREG
2242The hWndReg parameter is not a valid window handle.
2243WFS_ERR_NOT_REGISTERED
2244The specified hWndReg window was not registered to receive messages for any event classes.
2245The following error condition is returned via the asynchronous command completion message, as the hResult from the WFSRESULT structure. Any service-specific errors that can be returned are defined in the specifications for each service class.
2246CWA 16926-1:2015 (E)
224789
2248WFS_ERR_CANCELED
2249The request was canceled by WFSCancelAsyncRequest.
2250CWA 16926-1:2015 (E)
225190
22526.4 WFPExecute
2253HRESULT WFPExecute( hService, dwCommand, lpCmdData, dwTimeOut, hWnd, ReqID )
2254Sends asynchronous service class specific commands to a Service Provider.
2255Parameters HSERVICE hService
2256Handle to the Service Provider.
2257DWORD dwCommand
2258Command to be executed.
2259LPVOID lpCmdData
2260Pointer to the data structure to be passed.
2261DWORD dwTimeOut
2262Number of milliseconds to wait for completion (WFS_INDEFINITE_WAIT to specify a request that will wait until completion).
2263HWND hWnd
2264The window handle which is to receive the completion message for this request.
2265REQUESTID ReqID
2266Request identification number.
2267Mode Asynchronous
2268Comments See WFSExecute.
2269Messages WFS_EXECUTE_COMPLETE
2270Error Codes If the function return is not WFS_SUCCESS, it is one of the following error conditions, indicating that the asynchronous operation was not initiated. Any service-specific errors that can be returned are defined in the specifications for each service class.
2271WFS_ERR_CONNECTION_LOST
2272The connection to the service is lost.
2273WFS_ERR_INTERNAL_ERROR
2274An internal inconsistency or other unexpected error occurred in the XFS subsystem.
2275WFS_ERR_INVALID_COMMAND
2276The dwCommand issued is not supported by this service class.
2277WFS_ERR_INVALID_HSERVICE
2278The hService parameter is not a valid service handle.
2279WFS_ERR_INVALID_HWND
2280The hWnd parameter is not a valid window handle.
2281WFS_ERR_INVALID_POINTER
2282A pointer parameter does not point to accessible memory.
2283WFS_ERR_UNSUPP_COMMAND
2284The dwCommand issued, although valid for this service class, is not supported by this Service Provider.
2285The following error conditions are returned via the asynchronous command completion message, as the hResult from the WFSRESULT structure. Any service-specific errors that can be returned are defined in the specifications for each service class.
2286WFS_ERR_CANCELED
2287The request was canceled by WFSCancelAsyncRequest.
2288WFS_ERR_DEV_NOT_READY
2289The function required device access, and the device was not ready or timed out.
2290CWA 16926-1:2015 (E)
229191
2292WFS_ERR_HARDWARE_ERROR
2293The function required device access, and an error occurred on the device.
2294WFS_ERR_INVALID_DATA
2295The data structure passed as input parameter contains invalid data.
2296WFS_ERR_INTERNAL_ERROR
2297An internal inconsistency or other unexpected error occurred in the XFS subsystem.
2298WFS_ERR_LOCKED
2299The service is locked under a different hService.
2300WFS_ERR_SOFTWARE_ERROR
2301The function required access to configuration information, and an error occurred on the software.
2302WFS_ERR_TIMEOUT
2303The timeout interval expired.
2304WFS_ERR_USER_ERROR
2305A user is preventing proper operation of the device.
2306WFS_ERR_UNSUPP_DATA
2307The data structure passed as an input parameter although valid for this service class, is not supported by this Service Provider or device.
2308WFS_ERR_FRAUD_ATTEMPT
2309Some devices are capable of identifying a malicious physical attack which attempts to defraud valuable information or media. In these cases, this error code is returned to indicate the user is attempting a fraudulent act on the device.
2310CWA 16926-1:2015 (E)
231192
23126.5 WFPGetInfo
2313HRESULT WFPGetInfo( hService, dwCategory, lpQueryDetails, dwTimeOut, hWnd, ReqID )
2314Retrieves various kinds of information from the specified Service Provider.
2315Parameters HSERVICE hService
2316Handle to the Service Provider.
2317DWORD dwCategory
2318Specifies the category of the query (e.g. for a printer, WFS_INF_PTR_STATUS to request status or WFS_INF_PTR_CAPABILITIES to request capabilities). The available categories depend on the service class, the Service Provider and the service. The information requested can be either static or dynamic, e.g. basic service capabilities (static) or current service status (dynamic).
2319LPVOID lpQueryDetails
2320Pointer to the data structure to be passed to the Service Provider, containing further details to make the query more precise, e.g. a form name. (Many queries have no input parameters, in which case this pointer is NULL.)
2321DWORD dwTimeOut
2322Number of milliseconds to wait for completion (WFS_INDEFINITE_WAIT to specify a request that will wait until completion).
2323HWND hWnd
2324The window handle which is to receive the completion message for this request.
2325REQUESTID ReqID
2326Request identification number.
2327Mode Asynchronous
2328Comments The XFS Manager retrieves the information requested from the Service Provider itself, and, since the information can be stored remotely, the function cannot be guaranteed to complete immediately. Note that, typically, requests for generic and class specific categories can complete immediately. See WFSGetInfo for additional discussion.
2329The specifications for the information structures for each service class can be found in the specifications for the service-specific commands.
2330Messages WFS_GETINFO_COMPLETE
2331Error Codes If the function return is not WFS_SUCCESS, it is one of the following error conditions, indicating that the asynchronous operation was not initiated. Any service-specific errors that can be returned are defined in the specifications for each service class.
2332WFS_ERR_CONNECTION_LOST
2333The connection to the service is lost.
2334WFS_ERR_INTERNAL_ERROR
2335An internal inconsistency or other unexpected error occurred in the XFS subsystem.
2336WFS_ERR_INVALID_CATEGORY
2337The dwCategory issued is not supported by this service class.
2338WFS_ERR_INVALID_HSERVICE
2339The hService parameter is not a valid service handle.
2340WFS_ERR_INVALID_HWND
2341The hWnd parameter is not a valid window handle.
2342WFS_ERR_INVALID_POINTER
2343A pointer parameter does not point to accessible memory.
2344WFS_ERR_UNSUPP_CATEGORY
2345The dwCategory issued, although valid for this service class, is not supported by this Service Provider.
2346CWA 16926-1:2015 (E)
234793
2348The following error conditions are returned via the asynchronous command completion message, as the hResult from the WFSRESULT structure. Any service-specific errors that can be returned are defined in the specifications for each service class.
2349WFS_ERR_CANCELED
2350The request was canceled by WFSCancelAsyncRequest.
2351WFS_ERR_DEV_NOT_READY
2352The function required device access, and the device was not ready or timed out.
2353WFS_ERR_HARDWARE_ERROR
2354The function required device access, and an error occurred on the device.
2355WFS_ERR_INTERNAL_ERROR
2356An internal inconsistency or other unexpected error occurred in the XFS subsystem.
2357WFS_ERR_INVALID_DATA
2358The data structure passed as input parameter contains invalid data.
2359WFS_ERR_SOFTWARE_ERROR
2360The function required access to configuration information, and an error occurred on the software.
2361WFS_ERR_TIMEOUT
2362The timeout interval expired.
2363WFS_ERR_USER_ERROR
2364A user is preventing proper operation of the device.
2365WFS_ERR_UNSUPP_DATA
2366The data structure passed as an input parameter although valid for this service class, is not supported by this Service Provider or device.
2367CWA 16926-1:2015 (E)
236894
23696.6 WFPLock
2370HRESULT WFPLock( hService, dwTimeOut, hWnd, ReqID )
2371Establishes exclusive control by the calling application over the specified service.
2372Parameters HSERVICE hService
2373Handle to the Service Provider.
2374DWORD dwTimeOut
2375Number of milliseconds to wait for completion (WFS_INDEFINITE_WAIT to specify a request that will wait until completion).
2376HWND hWnd
2377The window handle which is to receive the completion message for this request.
2378REQUESTID ReqID
2379Request identification number.
2380Mode Asynchronous
2381Comments See WFSLock.
2382Messages WFS_LOCK_COMPLETE
2383Error Codes If the function return is not WFS_SUCCESS, it is one of the following error conditions, indicating that the asynchronous operation was not initiated. Any service-specific errors that can be returned are defined in the specifications for each service class.
2384WFS_ERR_CONNECTION_LOST
2385The connection to the service is lost.
2386WFS_ERR_INTERNAL_ERROR
2387An internal inconsistency or other unexpected error occurred in the XFS subsystem.
2388WFS_ERR_INVALID_HSERVICE
2389The hService parameter is not a valid service handle.
2390WFS_ERR_INVALID_HWND
2391The hWnd parameter is not a valid window handle.
2392The following error conditions are returned via the asynchronous command completion message, as the hResult from the WFSRESULT structure. Any service-specific errors that can be returned are defined in the specifications for each service class.
2393WFS_ERR_CANCELED
2394The request was canceled by WFSCancelAsyncRequest.
2395WFS_ERR_DEV_NOT_READY
2396The function required device access, and the device was not ready or timed out.
2397WFS_ERR_HARDWARE_ERROR
2398The function required device access, and an error occurred on the device.
2399WFS_ERR_INTERNAL_ERROR
2400An internal inconsistency or other unexpected error occurred in the XFS subsystem.
2401WFS_ERR_SOFTWARE_ERROR
2402The function required access to configuration information, and an error occurred on the software.
2403WFS_ERR_TIMEOUT
2404The timeout interval expired.
2405CWA 16926-1:2015 (E)
240695
24076.7 WFPOpen
2408HRESULT WFPOpen( hService, lpszLogicalName, hApp, lpszAppID, dwTraceLevel, dwTimeOut, hWnd, ReqID, hProvider, dwSPIVersionsRequired, lpSPIVersion, dwSrvcVersionsRequired, lpSrvcVersion )
2409Establishes a connection between the XFS Manager and the Service Provider that supports the specified service, and initiates a session (a series of service requests terminated with the WFPClose function).
2410Parameters HSERVICE hService
2411The service handle to be associated with the session being opened.
2412LPSTR lpszLogicalName
2413Points to a null-terminated string containing the pre-defined logical name of a service. It is a high level name such as "SYSJOURNAL1," "PASSBOOKPTR3" or "ATM02," that is used by the XFS Manager and the Service Provider as a key to obtain the specific configuration information they need.
2414HAPP hApp
2415The application handle to be associated with the session being opened. See WFSCreateAppHandle and Sections 4.5 and 4.8.2 for details.
2416LPSTR lpszAppID
2417Pointer to a null terminated string containing the application ID; the pointer may be NULL if the ID is not used.
2418DWORD dwTraceLevel
2419See WFPSetTraceLevel.
2420DWORD dwTimeOut
2421Number of milliseconds to wait for completion (WFS_INDEFINITE_WAIT to specify a request that will wait until completion).
2422HWND hWnd
2423The window handle which is to receive the completion message for this request.
2424REQUESTID ReqID
2425Request identification number.
2426HPROVIDER hProvider
2427Service Provider handle supplied by the XFS Manager - used by the Service Provider to identify itself when calling the WFMReleaseDLL function.
2428DWORD dwSPIVersionsRequired
2429Specifies the range of XFS SPI versions that the XFS Manager can support. (See Comments.) The low-order word indicates the highest version the XFS Manager can support; the high-order word indicates the lowest version the XFS Manager can support. In each word, the low-order byte specifies the major version number and the high-order byte specifies the minor version number (i.e. the numbers before and after the decimal). Note: in order to allow intermediate minor revisions (e.g. between 1.10 and 1.20), the minor version number should always be expressed as two decimal digits, i.e. 1.10, 1.11, 1.20, etc.
2430LPWFSVERSION lpSPIVersion
2431Pointer to the data structure that is to receive SPI version support information and (optionally) other details about the SPI implementation (returned parameter).
2432DWORD dwSrvcVersionsRequired
2433Service-specific interface versions required; see dwSPIVersionsRequired above, and WFSOpen.
2434LPWFSVERSION lpSrvcVersion
2435Pointer to the service-specific interface implementation information; see lpSPIVersion above, and WFSOpen (returned parameter).
2436Mode Asynchronous
2437CWA 16926-1:2015 (E)
243896
2439Comments This function establishes the connection between the XFS Manager and the Service Provider, including version negotiation and passing of implementation information, and initiates a session between the application and the service. This call is made by the XFS Manager each time any application issues a WFSOpen or WFSAsyncOpen call to the specified service (immediately after loading the Service Provider DLL, if it is not already loaded).
2440In order to support future XFS implementations with maximum flexibility, two version negotiations take place in WFPOpen. In the first, the XFS Manager specifies in the dwSPIVersionsRequired parameter the range of versions of the XFS SPI specification which it can support. If the range of versions specified by the XFS Manager overlaps the range of versions that the Service Provider can support, the call succeeds. Otherwise the call fails.
2441The WFSVERSION data structure (described in Section 9.2) is used by the Service Provider to return the version of SPI support it expects the XFS Manager to use (the highest common version), as well as the lowest and highest versions it is capable of. In addition, this structure is used optionally by the XFS Manager to specify other information about the Service Provider implementation. If the call fails, WFSVERSION is still returned, to help with analysis of the failure.
2442The version numbers refer to the SPI specification, specifically functions, parameters, data structures, error codes, and messages. If there are any changes to these, the version number should be changed.
2443This version negotiation allows the XFS Manager and a Service Provider to operate successfully if there is any overlap in their versions. The following chart gives examples of how WFPOpen works in conjunction with different XFS Manager and Service Provider versions:
2444dwSPIVersions-Required (Versions required by XFS Manager):
2445lpSPIVersion.wLowVersion lpSPIVersion.wHighVersion (Service Provider versions):
2446Return status from WFPOpen:
2447lpSPIVersions .wVersion (Result):
24480x00010001 (1.00)
24490x0001 0x0001 (1.00)
2450WFS_SUCCESS
24510x0001 (use 1.00)
24520x00010A02 (1.00 - 2.10)
24530x0001 0x0001 (1.00)
2454WFS_SUCCESS
24550x0001 (use 1.00)
24560x0B010B01 (1.11)
24570x0001 0x0002 (1.00 - 2.00)
2458WFS_SUCCESS
24590x0B01 (use 1.11)
24600x0B020003 (2.11 - 3.00)
24610x0001 0x1402 (1.00 - 2.20)
2462WFS_SUCCESS
24630x1402 (use 2.20)
24640x00010001 (1.00)
24650x1402 0x0003 (2.20 - 3.00)
2466WFS_ERR_SPI_VER_TOO_LOW
24670x0000 (fails)
24680x0B010003 (1.11 - 3.00)
24690x0001 0x0001 (1.00)
2470WFS_ERR_SPI_VER_TOO_HIGH
24710x0000 (fails)
2472The second negotiation is in relation to the service-specific interface, between the application program and the Service Provider. The following chart gives examples of how WFPOpen works in conjunction with different application and Service Provider versions. See WFSOpen, Section 5.19, for details.
2473dwSrvcVersions-Required (Versions required by the application):
2474lpSrvcVersion.wLowVersion lpSrvcVersion.wHighVersion (Service Provider versions):
2475Return status from WFPOpen:
2476lpSrvcVersions .wVersion (Result):
24770x00010001 (1.00)
24780x0001 0x0001 (1.00)
2479WFS_SUCCESS
24800x0001 (use 1.00)
24810x00010A02 (1.00 - 2.10)
24820x0001 0x0001 (1.00)
2483WFS_SUCCESS
24840x0001 (use 1.00)
24850x0B010B01 (1.11)
24860x0001 0x0002 (1.00 - 2.00)
2487WFS_SUCCESS
24880x0B01 (use 1.11)
24890x0B020003 (2.11 - 3.00)
24900x0001 0x1402 (1.00 - 2.20)
2491WFS_SUCCESS
24920x1402 (use 2.20)
24930x00010001 (1.00)
24940x1402 0x0003 (2.20 - 3.00)
2495WFS_ERR_SRVC_VER_TOO_LOW
24960x0000 (fails)
24970x0B010003 (1.11 - 3.00)
24980x0001 0x0001 (1.00)
2499WFS_ERR_SRVC_VER_TOO_HIGH
25000x0000 (fails)
2501Note that a version negotiation error also generates a system event (see Section 10.8).
2502Also, see WFSStartUp, Section 5.23.
2503CWA 16926-1:2015 (E)
250497
2505Messages WFS_OPEN_COMPLETE
2506Error Codes If the function return is not WFS_SUCCESS, it is one of the following error conditions, indicating that the asynchronous operation was not initiated. Any service-specific errors that can be returned are defined in the specifications for each service class.
2507WFS_ERR_CONNECTION_LOST
2508The connection to the service is lost.
2509WFS_ERR_INTERNAL_ERROR
2510An internal inconsistency or other unexpected error occurred in the XFS subsystem.
2511WFS_ERR_INVALID_HSERVICE
2512The hService parameter is not a valid service handle.
2513WFS_ERR_INVALID_HWND
2514The hWnd parameter is not a valid window handle.
2515WFS_ERR_INVALID_POINTER
2516A pointer parameter does not point to accessible memory.
2517WFS_ERR_INVALID_TRACELEVEL
2518The dwTraceLevel parameter does not correspond to a valid trace level or set of levels.
2519WFS_ERR_SPI_VER_TOO_HIGH
2520The range of versions of XFS SPI support requested by the XFS Manager is higher than any supported by this particular Service Provider.
2521WFS_ERR_SPI_VER_TOO_LOW
2522The range of versions of XFS SPI support requested by the XFS Manager is lower than any supported by this particular Service Provider.
2523WFS_ERR_SRVC_VER_TOO_HIGH
2524The range of versions of the service-specific interface support requested by the application is higher than any supported by the Service Provider for the logical service being opened.
2525WFS_ERR_SRVC_VER_TOO_LOW
2526The range of versions of the service-specific interface support requested by the application is lower than any supported by the Service Provider for the logical service being opened.
2527WFS_ERR_VERSION_ERROR_IN_SRVC
2528Within the service, a version mismatch of two modules occurred.
2529The following error conditions are returned via the asynchronous command completion message, as the hResult from the WFSRESULT structure. The service-specific errors that can be returned are defined in the specifications for each service class.
2530WFS_ERR_CANCELED
2531The request was canceled by WFSCancelAsyncRequest.
2532WFS_ERR_INTERNAL_ERROR
2533An internal inconsistency or other unexpected error occurred in the XFS subsystem.
2534WFS_ERR_TIMEOUT
2535The timeout interval expired.
2536WFS_ERR_VERSION_ERROR_IN_SRVC
2537Within the service, a version mismatch of two modules occurred.
2538CWA 16926-1:2015 (E)
253998
25406.8 WFPRegister
2541HRESULT WFPRegister( hService, dwEventClass, hWndReg, hWnd, ReqID )
2542Enables event monitoring for the specified service by the specified hWndReg; all events of the specified class(es) generate messages to the hWndReg.
2543Parameters HSERVICE hService
2544Handle to the Service Provider.
2545DWORD dwEventClass
2546The class(es) of events for which the application is registering. Specified as a set of bit masks that can be logically ORed together.
2547HWND hWndReg
2548The window handle which is to be registered to receive the specified messages.
2549HWND hWnd
2550The window handle which is to receive the completion message for this request.
2551REQUESTID ReqID
2552Request identification number.
2553Mode Asynchronous
2554Comments WFPDeregister is used to cancel notifications. See WFSRegister.
2555Messages WFS_REGISTER_COMPLETE
2556Error Codes If the function return is not WFS_SUCCESS, it is one of the following error conditions, indicating that the asynchronous operation was not initiated. Any service-specific errors that can be returned are defined in the specifications for each service class.
2557WFS_ERR_CONNECTION_LOST
2558The connection to the service is lost.
2559WFS_ERR_INTERNAL_ERROR
2560An internal inconsistency or other unexpected error occurred in the XFS subsystem.
2561WFS_ERR_INVALID_EVENT_CLASS
2562The dwEventClass parameter specifies one or more event classes not supported by the service.
2563WFS_ERR_INVALID_HSERVICE
2564The hService parameter is not a valid service handle.
2565WFS_ERR_INVALID_HWND
2566The hWnd parameter is not a valid window handle.
2567WFS_ERR_INVALID_HWNDREG
2568The hWndReg parameter is not a valid window handle.
2569The following error conditions are returned via the asynchronous command completion message, as the hResult from the WFSRESULT structure. Any service-specific errors that can be returned are defined in the specifications for each service class.
2570WFS_ERR_CANCELED
2571The request was canceled by WFSCancelAsyncRequest.
2572WFS_ERR_INTERNAL_ERROR
2573An internal inconsistency or other unexpected error occurred in the XFS subsystem.
2574CWA 16926-1:2015 (E)
257599
25766.9 WFPSetTraceLevel
2577HRESULT WFPSetTraceLevel( hService, dwTraceLevel )
2578Sets the specified trace level(s) at run time, in and/or below the Service Provider. See WFMSetTraceLevel.
2579Parameters HSERVICE hService
2580Handle to the Service Provider.
2581DWORD dwTraceLevel
2582The level(s) of tracing being requested. See below.
2583Mode Immediate
2584Comments Issuing WFPSetTraceLevel for a service enables tracing on that service at various levels. The predefined trace levels that can be used in this function, with their meanings to the Service Provider, are as follows (see WFMSetTraceLevel for the API and support function trace levels):
2585WFS_TRACE_SPI 0x00000004
2586Trace all the SPI calls to the Service Provider, and notification and event messages generated by the Service Provider, that are associated with the specified hService.
2587WFS_TRACE_ALL_SPI 0x00000008
2588Trace all SPI, notification and event activity of the Service Provider (the hService parameter is not relevant to this trace level).
2589Other standard trace levels may be defined in the future, and a range of trace level values (the high order 16 bits of this parameter) is reserved for use by individual Service Providers. Example of other functions that may be traced include network messages, interactions between the Service Provider and service, and device interface interaction.
2590Trace level values can be ORed together in a single dwTraceLevel parameter to request more than one kind of tracing be started. A NULL value stops all tracing in the Service Provider.
2591If more than one process may be using the trace facility, this function should always be preceded with the WFMGetTraceLevel function. This value returned by this function is ORed together with the new trace level(s), and the resulting value is used with WFMSetTraceLevel, thus adding the new trace level(s) to whatever the existing trace level(s) had been,
2592This function has the highest priority to the Service Provider; it activates the trace as soon as possible.
2593WFPOpen also includes an option to set these trace levels, to allow the open process itself to be traced.
2594Error Codes If the function return is not WFS_SUCCESS, it is one of the following error conditions:
2595WFS_ERR_CONNECTION_LOST
2596The connection to the service is lost.
2597WFS_ERR_INTERNAL_ERROR
2598An internal inconsistency or other unexpected error occurred in the XFS subsystem.
2599WFS_ERR_INVALID_HSERVICE
2600The hService parameter is not a valid service handle.
2601WFS_ERR_INVALID_TRACELEVEL
2602The dwTraceLevel parameter does not correspond to a valid trace level or set of levels.
2603WFS_ERR_NOT_STARTED
2604The application has not previously performed a successful WFSStartUp.
2605WFS_ERR_OP_IN_PROGRESS
2606A blocking operation is in progress on the thread; only WFSCancelBlockingCall and WFSIsBlocking are permitted at this time.
2607See Also WFMGetTraceLevel, WFSOpen, WFSAsyncOpen
2608CWA 16926-1:2015 (E)
2609100
26106.10 WFPUnloadService
2611HRESULT WFPUnloadService( )
2612Asks the called Service Provider whether it is OK for the XFS Manager to unload the Service Provider’s DLL.
2613Parameters None
2614Mode Immediate
2615Comments This function is issued after the XFS Manager has received a WFMReleaseDLL request from the Service Provider or during the processing of the WFSCleanUp command. The Service Provider returns WFS_SUCCESS only if it has fully “cleaned up,” i.e. has freed any resources it has allocated, has no separate threads running, etc. If this is not true, it returns the error below, and initiates or continues the clean up process.
2616Error Codes If the function return is not WFS_SUCCESS, it is one of the following error conditions:
2617WFS_ERR_NOT_OK_TO_UNLOAD
2618The XFS Manager may not unload the Service Provider DLL at this time. It will repeat this request to the Service Provider until the return is WFS_SUCCESS, or until a new session is started by an application with this Service Provider.
2619CWA 16926-1:2015 (E)
2620101
26216.11 WFPUnlock
2622HRESULT WFPUnlock( hService, hWnd, ReqID )
2623Releases a service that has been locked by a previous WFPLock function.
2624Parameters HSERVICE hService
2625Handle to the Service Provider
2626HWND hWnd
2627The window handle which is to receive the completion message for this request.
2628REQUESTID ReqID
2629Request identification number.
2630Mode Asynchronous
2631Comments See WFPLock, WFSLock, WFSUnlock and Section 4.9.
2632Messages WFS_UNLOCK_COMPLETE
2633Error Codes If the function return is not WFS_SUCCESS, it is one of the following error conditions, indicating that the asynchronous operation was not initiated. Any service-specific errors that can be returned are defined in the specifications for each service class.
2634WFS_ERR_CONNECTION_LOST
2635The connection to the service is lost.
2636WFS_ERR_INTERNAL_ERROR
2637An internal inconsistency or other unexpected error occurred in the XFS subsystem.
2638WFS_ERR_INVALID_HSERVICE
2639The hService parameter is not a valid service handle.
2640WFS_ERR_INVALID_HWND
2641The hWnd parameter is not a valid window handle.
2642The following error conditions are returned via the asynchronous command completion message, as the hResult from the WFSRESULT structure. Any service-specific errors that can be returned are defined in the specifications for each service class.
2643WFS_ERR_CANCELED
2644The request was canceled by WFSCancelAsyncRequest.
2645WFS_ERR_INTERNAL_ERROR
2646An internal inconsistency or other unexpected error occurred in the XFS subsystem.
2647WFS_ERR_NOT_LOCKED
2648The service to be unlocked is not locked under the calling hService.
2649CWA 16926-1:2015 (E)
2650102
26517. Support Functions
2652Support functions are services of the XFS Manager used by Service Providers and applications. All the functions are immediate, since they are completely processed inside the XFS Manager, or use only immediate functions of the Service Providers.
26537.1 WFMAllocateBuffer
2654HRESULT WFMAllocateBuffer( ulSize, ulFlags, lppvData )
2655Allocates a memory buffer for the Service Provider in which to return results.
2656Parameters ULONG ulSize
2657Size (in bytes) of the memory to be allocated.
2658ULONG ulFlags
2659Flags, see comments below.
2660LPVOID *lppvData
2661Address of the variable in which the XFS Manager will place the pointer to the allocated memory.
2662Comments A Service Provider must use this call when creating data structures for the XFS Manager or an application to use, and may use it when allocating memory for its own private use. The flags can be ORed together, and specify:
2663WFS_MEM_SHARE Allocates shareable memory.
2664WFS_MEM_ZEROINIT Initializes memory contents to zero (not required in Win32 or Win64).
2665The application, XFS Manager or Service Provider then must, in turn, use the WFSFreeResult or WFMFreeBuffer functions to deallocate the memory.
2666Error Codes If the function return is not WFS_SUCCESS, it is one of the following error conditions:
2667WFS_ERR_INVALID_POINTER
2668A pointer parameter does not point to accessible memory.
2669WFS_ERR_OUT_OF_MEMORY
2670There is not enough memory available to satisfy the request.
2671See Also WFMAllocateMore, WFMFreeBuffer, WFSFreeResult and Section 4.14.
2672CWA 16926-1:2015 (E)
2673103
26747.2 WFMAllocateMore
2675HRESULT WFMAllocateMore( ulSize, lpvOriginal, lppvData )
2676Allocates a memory buffer, linking it to a previously allocated one.
2677Parameters ULONG ulSize
2678Size (in bytes) of the memory to be allocated
2679LPVOID lpvOriginal
2680Address of the original buffer to which the newly allocated buffer should be linked
2681LPVOID *lppvData
2682Address of the variable in which the XFS Manager will place the pointer to the newly allocated memory.
2683Comments This function allocates an additional memory buffer and link it to one previously allocated by WFMAllocateBuffer. The returned buffer has the same properties as the previous buffer (i.e. the WFS_MEM_SHARE and WFS_MEM_ZEROINIT flags) and it can be freed only by freeing the original buffer (using WFMFreeBuffer or WFSFreeResult).
2684Error Codes If the function return is not WFS_SUCCESS, it is one of the following error conditions:
2685WFS_ERR_INVALID_ADDRESS
2686The lpvOriginal parameter does not point to a previously allocated buffer.
2687WFS_ERR_INVALID_POINTER
2688A pointer parameter does not point to accessible memory.
2689WFS_ERR_OUT_OF_MEMORY
2690There is not enough memory available to satisfy the request.
2691See Also WFMAllocateBuffer, WFMFreeBuffer, WFSFreeResult and Section 4.14.
2692CWA 16926-1:2015 (E)
2693104
26947.3 WFMFreeBuffer
2695HRESULT WFMFreeBuffer( lpvData )
2696Releases the memory buffer(s) allocated by WFMAllocateBuffer and WFMAllocateMore.
2697Parameters LPVOID lpvData
2698Address of the memory buffer to free.
2699Comments See WFMAllocateBuffer and WFSFreeResult. This function frees a set of one or more linked buffers, as does the WFSFreeResult API function, except that it is used by Service Providers to free memory that they have allocated for "private" use, via the WFMAllocateBuffer and WFMAllocateMore functions.
2700Error Codes If the function return is not WFS_SUCCESS, it is one of the following error conditions:
2701WFS_ERR_INVALID_BUFFER
2702The lpvData parameter is not a pointer to an allocated buffer structure.
2703WFS_ERR_INVALID_POINTER
2704A pointer parameter does not point to accessible memory.
2705See Also WFMAllocateBuffer, WFMAllocateMore, WFSFreeResult and Section 4.14.
2706CWA 16926-1:2015 (E)
2707105
27087.4 WFMGetTraceLevel
2709HRESULT WFMGetTraceLevel( hService, lpdwTraceLevel )
2710Returns the trace level associated with the specified hService (at run time). See WFMSetTraceLevel.
2711Parameters HSERVICE hService
2712Handle to the Service Provider as returned by WFSOpen or WFSAsyncOpen.
2713LPDWORD lpdwTraceLevel
2714Pointer to the value defining the current trace level (returned parameter).
2715Mode Immediate
2716Comments This function returns the current tracing levels in the XFS Manager and the Service Provider specified by hService. See WFMSetTraceLevel.
2717Error Codes If the function return is not WFS_SUCCESS, it is one of the following error conditions:
2718WFS_ERR_INVALID_HSERVICE
2719The hService parameter is not a valid service handle.
2720WFS_ERR_INVALID_POINTER
2721A pointer parameter does not point to accessible memory.
2722WFS_ERR_NOT_STARTED
2723The application has not previously performed a successful WFSStartUp.
2724WFS_ERR_OP_IN_PROGRESS
2725A blocking operation is in progress on the thread; only WFSCancelBlockingCall and WFSIsBlocking are permitted at this time.
2726See Also WFMSetTraceLevel, WFSOpen, WFSAsyncOpen
2727CWA 16926-1:2015 (E)
2728106
27297.5 WFMKillTimer
2730HRESULT WFMKillTimer(wTimerID )
2731Cancels the timer identified by the wTimerID parameter. Any pending WFS_TIMER_EVENT message associated with the timer is removed from the message queue.
2732Parameters WORD wTimerID
2733ID of the timer to be canceled.
2734Comments See WFMSetTimer.
2735Error Codes If the function return is not WFS_SUCCESS, it is the following error condition:
2736WFS_ERR_INVALID_TIMER
2737The wTimerID parameter does not correspond to a currently active timer.
2738CWA 16926-1:2015 (E)
2739107
27407.6 WFMOutputTraceData
2741HRESULT WFMOutputTraceData( lpszData )
2742Requests the XFS Manager to output the specified data to the current trace destination.
2743Parameters LPSTR lpszData
2744Pointer to a null-terminated string containing the trace data.
2745Comments Normally used by a Service Provider that has been requested via WFMSetTraceLevel to trace its operation. The XFS Manager adds standard header information (timestamp, etc.) to the data before writing it to the trace stream. Note that the XFS Manager also writes data to the trace stream if the appropriate trace level(s) have been requested.
2746Error Codes If the function return is not WFS_SUCCESS, it is the following error condition:
2747WFS_ERR_INVALID_POINTER
2748A pointer parameter does not point to accessible memory.
2749CWA 16926-1:2015 (E)
2750108
27517.7 WFMReleaseDLL
2752HRESULT WFMReleaseDLL( hProvider )
2753Notifies the XFS Manager that the Service Provider is available to be unloaded from memory.
2754Parameters HPROVIDER hProvider
2755Handle to the Service Provider, obtained from the XFS Manager in the WFPOpen call.
2756Comments This function initiates the process in which the Service Provider is unloaded from memory by the XFS Manager. However, note that the Manager must issue the WFPUnloadService function to the Service Provider before it actually unloads the Service Provider DLL. The recommended procedure is as follows:
2757• The Service Provider finishes processing the WFPClose for its last open session
2758• The Service Provider does appropriate cleanup (deallocating memory, killing separate threads, etc.)
2759• The Service Provider posts the WFS_CLOSE_COMPLETE message for the final close
2760• The Service Provider calls WFMReleaseDLL, and after the return from this call, does nothing other than return from the procedure that called WFMReleaseDLL
2761• The XFS Manager calls WFPUnloadService, verifying that the Service Provider is in fact still ready to be unloaded
2762• If the Service Provider says OK, the XFS Manager unloads the Service Provider DLL
2763Error Codes If the function return is not WFS_SUCCESS, it is the following error condition:
2764WFS_ERR_INVALID_HPROVIDER
2765The hProvider parameter is not a valid provider handle.
2766CWA 16926-1:2015 (E)
2767109
27687.8 WFMSetTimer
2769HRESULT WFMSetTimer( hWnd, lpContext, dwTimeVal, lpwTimerID )
2770Starts a system timer.
2771Parameters HWND hWnd
2772The window to which the requested timer message is to be posted.
2773LPVOID lpContext
2774Context pointer supplied by the Service Provider requesting the timer; may be NULL.
2775DWORD dwTimeVal
2776Timer value (in milliseconds).
2777LPWORD lpwTimerID
2778Pointer to the timer identifier (returned parameter).
2779Comments The WFMSetTimer function requests the XFS Manager to start a system timer with the specified time value; when that time interval expires, the XFS Manager posts a WFS_TIMER_EVENT message to the specified hWnd, containing the wTimerID value and the lpContext pointer.
2780Error Codes If the function return is not WFS_SUCCESS, it is one of the following error conditions:
2781WFS_ERR_INVALID_HWND
2782The hWnd parameter is not a valid window handle.
2783WFS_ERR_INVALID_POINTER
2784A pointer parameter does not point to accessible memory.
2785CWA 16926-1:2015 (E)
2786110
27877.9 WFMSetTraceLevel
2788HRESULT WFMSetTraceLevel( hService, dwTraceLevel )
2789Sets the specified trace level(s) at run time; to be used for debugging and testing purposes.
2790Parameters HSERVICE hService
2791Handle to the Service Provider as returned by WFSOpen or WFSAsyncOpen.
2792DWORD dwTraceLevel
2793The level(s) of tracing being requested. See below.
2794Mode Immediate
2795Comments Issuing WFMSetTraceLevel for a service enables tracing on that service at various levels. Five standard trace levels are predefined:
2796WFS_TRACE_API 0x00000001
2797Trace all input and output parameters of all API function calls using the specified hService.
2798WFS_TRACE_ALL_API 0x00000002
2799Trace all input and output parameters of all API function calls associated with the Service Provider identified by the specified hService, not just the ones associated with the specified hService.
2800WFS_TRACE_SPI 0x00000004
2801Trace all input and output parameters of all SPI function calls associated with the specified hService, as well as all notification and event messages generated by the Service Provider for the hService.
2802WFS_TRACE_ALL_SPI 0x00000008
2803As for WFS_TRACE_ALL_API, but trace all SPI, notification and event activity on the Service Provider, not just that associated with the specified hService.
2804WFS_TRACE_MGR 0x00000010
2805Trace the support functions (WFMxxxxx) of the XFS Manager.
2806Other standard trace levels may be defined in the future, and a range of trace level values (the high order 16 bits of this parameter) is reserved for use by individual Service Providers. Examples of other functions that may be traced include network messages, interactions between the Service Provider and service, and device interface interaction.
2807Trace level values can be ORed together in a single dwTraceLevel parameter to request more than one kind of tracing be started. A NULL value stops all tracing.
2808If more than one process may be using the trace facility, this function should always be preceded with a call to the WFMGetTraceLevel function. This value returned by this function is ORed together with the new trace level(s), and the resulting value is used with WFMSetTraceLevel, thus adding the new trace level(s) to whatever the existing trace level(s) had been,
2809This function has the highest priority to the XFS Manager and the Service Provider; they activate the trace as soon as possible. Note that the XFS Manager performs all the traces defined above, other than the completion and event messages posted by the Service Providers.
2810WFSOpen and WFSAsyncOpen also include an option to set these trace levels, to allow the open process itself to be traced.
2811Error Codes If the function return is not WFS_SUCCESS, it is one of the following error conditions:
2812WFS_ERR_INVALID_HSERVICE
2813The hService parameter is not a valid service handle.
2814WFS_ERR_INVALID_TRACELEVEL
2815The dwTraceLevel parameter does not correspond to a valid trace level or set of levels.
2816CWA 16926-1:2015 (E)
2817111
2818WFS_ERR_NOT_STARTED
2819The application has not previously performed a successful WFSStartUp.
2820WFS_ERR_OP_IN_PROGRESS
2821A blocking operation is in progress on the thread; only WFSCancelBlockingCall and WFSIsBlocking are permitted at this time.
2822See Also WFMGetTraceLevel, WFPSetTraceLevel, WFSOpen, WFSAsyncOpen
2823CWA 16926-1:2015 (E)
2824112
28258. Configuration Functions
2826See Section 4.7 for the overall discussion of configuration information and how it is stored within the Windows Registry.
28278.1 WFMCloseKey
2828HRESULT WFMCloseKey ( hKey )
2829Closes the specified key.
2830Parameters HKEY hKey
2831Handle to the currently open key that is to be closed.
2832Comments The hKey handle can not be used after it has been closed, because it will no longer be valid. Note that it is not valid to close the XFS root key (passing one of the pre-defined handles as the value for the hKey parameter).
2833Error Codes If the function return is not WFS_SUCCESS, it is the following error condition:
2834WFS_ERR_CFG_INVALID_HKEY
2835The specified hKey parameter does not correspond to a currently open key, or it is the XFS root.
2836CWA 16926-1:2015 (E)
2837113
28388.2 WFMCreateKey
2839HRESULT WFMCreateKey ( hKey, lpszSubKey, phkResult, lpdwDisposition )
2840Creates a new key, or if the specified key exists, opens it.
2841The first use of hKey by a process sets the migration mode for that process. The use of this function is an application decision: the XFS Manager must not automatically migrate the registry values at load time.
2842Be aware that when the WFMCreateKey is used for the first time and the hKey parameter is set to WFS_CFG_HKEY_XFS_ROOT then the existing registry structure will be migrated from HKEY_CLASSES_ROOT to HKEY_LOCAL_MACHINE. If either of the new values WFS_CFG_MACHINE_XFS_ROOT or WFS_CFG_USER_DEFAULT_XFS_ROOT are used then no migration will take place for this process. The assumption is that any process using the new key values will be doing its own migration. The reason migration does not always take place is that some applications will require access to both the old and new key roots so that they can migrate their non-CEN keys and values.
2843Parameters HKEY hKey
2844Handle to a currently open key, or one of the predefined handles.
2845The key opened or created by this function is a subkey of the key identified by this parameter.
2846LPSTR lpszSubKey
2847Pointer to a null-terminated string containing the name of the key to be created or opened.
2848PHKEY phkResult
2849Pointer to a variable that receives the handle of the created or opened key.
2850LPDWORD lpdwDisposition
2851Pointer to a variable that receives one of the disposition values: WFS_CFG_CREATED_NEW_KEY WFS_CFG_OPENED_EXISTING_KEY
2852Comments If this function creates a new key, it has no values. The WFMSetValue function is used to create values.
2853Error Codes If the function return is not WFS_SUCCESS, it is one of the following error conditions:
2854WFS_ERR_CFG_INVALID_HKEY
2855The specified hKey parameter does not correspond to a currently open key.
2856WFS_ERR_INVALID_POINTER
2857A pointer parameter does not point to accessible memory.
2858CWA 16926-1:2015 (E)
2859114
28608.3 WFMDeleteKey
2861HRESULT WFMDeleteKey ( hKey, lpszSubKey )
2862Deletes the specified key. This function cannot delete a key that has subkeys.
2863Parameters HKEY hKey
2864Handle to a currently open key, or one of the predefined handles.
2865The key specified by the lpszSubKey parameter must be a subkey of the key identified by this parameter.
2866LPSTR lpszSubKey
2867Pointer to a null-terminated string specifying the name of the key to be deleted.
2868Comments If this function succeeds, the specified key is removed from the configuration information. The entire key, including all its values, is removed.
2869Error Codes If the function return is not WFS_SUCCESS, it is one of the following error conditions.
2870WFS_ERR_CFG_INVALID_HKEY
2871The specified hKey parameter does not correspond to a currently open key.
2872WFS_ERR_CFG_INVALID_SUBKEY
2873The key specified by lpszSubKey does not exist.
2874WFS_ERR_CFG_KEY_NOT_EMPTY
2875The specified key has subkeys and cannot be deleted. The subkeys must be deleted first.
2876WFS_ERR_INVALID_POINTER
2877A pointer parameter does not point to accessible memory.
2878CWA 16926-1:2015 (E)
2879115
28808.4 WFMDeleteValue
2881HRESULT WFMDeleteValue ( hKey, lpszValue )
2882Deletes the specified value (both name and data).
2883Parameters HKEY hKey
2884Handle to a currently open key, or one of the predefined handles.
2885LPSTR lpszValue
2886Pointer to a null-terminated string specifying the name of the value to be deleted.
2887Comments The specified value is removed from the specified open key. The WFMSetValue function is used to create or modify values.
2888Error Codes If the function return is not WFS_SUCCESS, it is one of the following error conditions.
2889WFS_ERR_CFG_INVALID_HKEY
2890The specified hKey parameter does not correspond to a currently open key.
2891WFS_ERR_CFG_INVALID_VALUE
2892The specified value does not exist within the specified open key.
2893WFS_ERR_INVALID_POINTER
2894A pointer parameter does not point to accessible memory.
2895CWA 16926-1:2015 (E)
2896116
28978.5 WFMEnumKey
2898HRESULT WFMEnumKey ( hKey, iSubKey, lpszName, lpcchName, lpftLastWrite )
2899Enumerates the subkeys of the specified open key. Retrieves information about one subkey each time it is called.
2900Parameters HKEY hKey
2901Handle to a currently open key, or one of the predefined handles.
2902The keys enumerated by this function are subkeys of the key identified by this parameter.
2903DWORD iSubKey
2904The index of the subkey to retrieve. This parameter should be zero for the first call to this function, then incremented for each subsequent call, in order to enumerate all the subkeys of the specified open key.
2905Because subkeys are not ordered, any new subkey will have an arbitrary index. This means that the function may return subkeys in any order.
2906LPSTR lpszName
2907Pointer to a buffer that receives the name of the subkey, including the terminating null character.
2908LPDWORD lpcchName
2909Pointer to a variable that specifies the size, in characters, of the buffer specified by the lpszName parameter, including the terminating null character. When the function returns, this variable contains the number of characters actually stored in the buffer, not including the terminating null character.
2910PFILETIME lpftLastWrite
2911Pointer to a variable that receives the time the enumerated subkey was last written to, in the form of a FILETIME structure (see Microsoft Win32 Programmer's Reference, Vol. 5):
2912typedef struct _FILETIME { DWORD dwLowDateTime; DWORD dwHighDateTime; } FILETIME;
2913Comments While a program is using this function iteratively, it should not call any other configuration functions that would change the key being enumerated.
2914Error Codes If the function return is not WFS_SUCCESS, it is one of the following error conditions.
2915WFS_ERR_CFG_INVALID_HKEY
2916The specified hKey parameter does not correspond to a currently open key.
2917WFS_ERR_CFG_NO_MORE_ITEMS
2918There are no more subkeys to be returned (the iSubKey parameter is greater than the index of the last subkey).
2919WFS_ERR_CFG_NAME_TOO_LONG
2920The length of the name to be returned exceeds the length of the buffer.
2921WFS_ERR_INVALID_POINTER
2922A pointer parameter does not point to accessible memory.
2923CWA 16926-1:2015 (E)
2924117
29258.6 WFMEnumValue
2926HRESULT WFMEnumValue ( hKey, iValue, lpszValue, lpcchValue, lpszData, lpcchData )
2927Enumerates the values of the specified open key. Retrieves the name and data for one value each time it is called.
2928Parameters HKEY hKey
2929Handle to a currently open key, or one of the predefined handles.
2930The value enumerated by this function is a value of the key identified by this parameter.
2931DWORD iValue
2932The index of the value to retrieve. This parameter should be zero for the first call to this function, then incremented for each subsequent call, in order to enumerate all the values of the specified open key.
2933Because values are not ordered, any new value will have an arbitrary index. This means that the function may return values in any order.
2934LPSTR lpszValue
2935Pointer to a buffer that receives the name of the value, including the terminating null character.
2936LPDWORD lpcchValue
2937Pointer to a variable that specifies the size, in characters, of the buffer pointed to by the lpszValue parameter. This size should include the terminating null character. When the function returns, this variable contains the the number of characters actually stored in the buffer, not including the terminating null character.
2938LPSTR lpszData
2939Pointer to a buffer that receives the data for the value entry, including the terminating null character. This parameter can be NULL, if the data is not required.
2940LPDWORD lpcchData
2941Pointer to a variable that specifies the size, in characters, of the buffer pointed to by the lpszData parameter, including the terminating null character. When the function returns, this variable contains the the number of characters actually stored in the buffer, not including the terminating null character. Ignored if lpszData is NULL.
2942Comments While a program is using this function iteratively, it should not call any other configuration functions that would change the key being queried.
2943Error Codes If the function return is not WFS_SUCCESS, it is one of the following error conditions.
2944WFS_ERR_CFG_INVALID_HKEY
2945The specified hKey parameter does not correspond to a currently open key.
2946WFS_ERR_CFG_NO_MORE_ITEMS
2947There are no more values to be returned (the iValue parameter is greater than the index of the last value).
2948WFS_ERR_CFG_NAME_TOO_LONG
2949The length of the name to be returned exceeds the length of the buffer.
2950WFS_ERR_CFG_VALUE_TOO_LONG
2951The length of the value to be returned exceeds the length of the buffer.
2952WFS_ERR_INVALID_POINTER
2953A pointer parameter does not point to accessible memory.
2954CWA 16926-1:2015 (E)
2955118
29568.7 WFMOpenKey
2957HRESULT WFMOpenKey ( hKey, lpszSubKey, phkResult )
2958Opens the specified key.
2959Parameters HKEY hKey
2960Handle to a currently open key, or one of the predefined handles.
2961The key opened by this function is a subkey of the key identified by this parameter.
2962LPSTR lpszSubKey
2963Pointer to a null-terminated string containing the name of the key to be opened. If this parameter is NULL, or points to an empty string, the function opens another handle to the key identified by the hKey parameter (and does not close any previously opened handles).
2964PHKEY phkResult
2965Pointer to a variable that receives the handle of the opened key.
2966Comments In contrast with the WFMCreateKey function, this function does not create the specified key if it does not exist.
2967Error Codes If the function return is not WFS_SUCCESS, it is one of the following error conditions.
2968WFS_ERR_CFG_INVALID_HKEY
2969The specified hKey parameter does not correspond to a currently open key.
2970WFS_ERR_CFG_INVALID_SUBKEY
2971The key specified by lpszSubKey does not exist.
2972WFS_ERR_INVALID_POINTER
2973A pointer parameter does not point to accessible memory.
2974CWA 16926-1:2015 (E)
2975119
29768.8 WFMQueryValue
2977HRESULT WFMQueryValue ( hKey, lpszValueName, lpszData, lpcchData )
2978Retrieves the data for the value with the specified name, within the specified open key.
2979Parameters HKEY hKey
2980Handle to a currently open key, or one of the predefined handles.
2981The value data returned is within the key identified by this parameter.
2982LPSTR lpszValueName
2983Pointer to a null-terminated string containing the name of the value being queried.
2984LPSTR lpszData
2985Pointer to a buffer that receives the data for the value entry, including the terminating null character.
2986LPDWORD lpcchData
2987Pointer to a variable that specifies the size, in characters, of the buffer pointed to by the lpszData parameter, including the terminating null character. When the function returns, this variable contains the number of characters actually stored in the buffer, not including the terminating null character.
2988Comments None.
2989Error Codes If the function return is not WFS_SUCCESS, it is one of the following error conditions.
2990WFS_ERR_CFG_INVALID_HKEY
2991The specified hKey parameter does not correspond to a currently open key.
2992WFS_ERR_CFG_INVALID_NAME
2993The value specified by the lpszValueName parameter does not exist in the specified key.
2994WFS_ERR_CFG_VALUE_TOO_LONG
2995The length of the value to be returned exceeds the length of the buffer.
2996WFS_ERR_INVALID_POINTER
2997A pointer parameter does not point to accessible memory.
2998CWA 16926-1:2015 (E)
2999120
30008.9 WFMSetValue
3001HRESULT WFMSetValue ( hKey, lpszValueName, lpszData, cchData )
3002Stores data in the specified value of the specified key. If the value does not exist, it is created.
3003Parameters HKEY hKey
3004Handle to a currently open key, or one of the predefined handles.
3005The value set or created is within the key identified by this parameter.
3006LPSTR lpszValueName
3007Pointer to a null-terminated string containing the name of the value being set. If a value with this name does not already exist in the specified key, it is added to the key.
3008LPSTR lpszData
3009Pointer to a buffer containing the data (a null-terminated character string) to be stored with the specified value name.
3010DWORD cchData
3011The size, in characters, of the string pointed to by the lpszData parameter, including the terminating null character.
3012Comments Value lengths are limited by available memory. Long values (more than 2048 bytes) should be stored as files with the filenames stored in the configuration information.
3013Error Codes If the function return is not WFS_SUCCESS, it is one of the following error conditions.
3014WFS_ERR_CFG_INVALID_HKEY
3015The specified hKey parameter does not correspond to a currently open key.
3016WFS_ERR_INVALID_POINTER
3017A pointer parameter does not point to accessible memory.
3018CWA 16926-1:2015 (E)
3019121
30209. Data Structures
30219.1 WFSRESULT
3022This structure has three functions:
3023• It is the parameter which returns the results of the synchronous WFSLock, WFSExecute and WFSGetInfo commands.
3024• It is pointed to by all command completion messages, and delivers completion status (as a result handle) and results data (if any) for all asynchronous API and SPI calls.
3025• It is pointed to by all event notification messages to deliver their contents.
3026Note that even though in many cases one or more members of this structure are not used, the adoption of a single, standard structure for request results simplifies the implementation and maintenance of applications, Service Providers and the XFS Manager itself.
3027typedef struct _wfs_result {
3028REQUESTID RequestID;
3029HSERVICE hService;
3030TIMESTAMP tsTimestamp;
3031HRESULT hResult;
3032union {
3033DWORD dwCommandCode;
3034DWORD dwEventID;
3035} u;
3036LPVOID lpBuffer;
3037} WFSRESULT, *LPWFSRESULT;
3038The members of this structure are:
3039Field Description
3040RequestID Request ID of the completed command; not used for event notifications other than Execute events.
3041hService Service handle identifying the session that created the result, i.e. the service handle of the session that the event is sent to.
3042tsTimestamp Time the event occurred (local time, in a Win32/Win64 SYSTEMTIME structure).
3043hResult Result handle (note that for synchronous WFSExecute and WFSGetInfo commands, this value is identical to the synchronous function return value).
3044u.dwCommandCode WFSExecute “command” code or WFSGetInfo “category” code; not used for other command completions.
3045u.dwEventID ID of the event (for unsolicited events).
3046lpBuffer Pointer to the results of the command (if any) or the contents of the event notification.
3047CWA 16926-1:2015 (E)
3048122
30499.2 WFSVERSION
3050This structure is used to return version information from WFSStartUp, WFSOpen and WFPOpen.
3051typedef struct _wfsversion {
3052WORD wVersion;
3053WORD wLowVersion;
3054WORD wHighVersion;
3055char szDescription[WFSDDESCRIPTION_LEN+1];
3056char szSystemStatus[WFSDSYSSTATUS_LEN+1];
3057} WFSVERSION, *LPWFSVERSION;
3058The members of this structure are (note that this structure is used to report version information for three distinct XFS interfaces: API, SPI, and the service-specific interface):
3059Element Usage
3060wVersion The version number to be used.
3061wLowVersion The lowest version number that the called DLL can support.
3062wHighVersion The highest version number that the called DLL can support.
3063szDescription A null-terminated ASCII string into which the called DLL copies a description of the implementation. The text (up to 256 characters in length) may contain any characters: the most likely use that an application will make of this is to display it (possibly truncated) in a status message.
3064szSystemStatus A null-terminated ASCII string into which the called DLL copies relevant status or configuration information. Not to be considered as an extension of the szDescription field. Used only if the information might be useful to the user or support staff.
3065CWA 16926-1:2015 (E)
3066123
306710. Messages
3068This section defines the Windows messages used in the XFS subsystem.
306910.1 Command Completions and Events
3070The following messages are sent to indicate:
3071• the completion of an asynchronous command, or
3072• the occurrence of an unsolicited event (execute, service, user, or system events).
3073All these messages have the same definition: wParam: not used lParam: points to a WFSRESULT data structure
3074WFS_<message_name>
3075wParam; /* not used */
3076lParam = LPWFSRESULT lpWFSResult;
307710.1.1 Command Completion Messages
3078WFS_OPEN_COMPLETE
3079WFS_CLOSE_COMPLETE
3080WFS_LOCK_COMPLETE
3081WFS_UNLOCK_COMPLETE
3082WFS_REGISTER_COMPLETE
3083WFS_DEREGISTER_COMPLETE
3084WFS_GETINFO_COMPLETE
3085WFS_EXECUTE_COMPLETE
308610.1.2 Event Messages
3087WFS_EXECUTE_EVENT
3088WFS_SERVICE_EVENT
3089WFS_USER_EVENT
3090WFS_SYSTEM_EVENT
3091The hService parameter of the WFSRESULT structure, in the above event messages, contains the service handle of the session that the event is sent to.
3092CWA 16926-1:2015 (E)
3093124
309410.2 WFS_TIMER_EVENT
3095The timer event message has the following format (see WFMSetTimer, WFMKillTimer):
3096WFS_TIMER_EVENT
3097wParam = wTimerID; /* timer ID returned by the WFMSetTimer function */
3098lParam = lpContext; /* context pointer supplied by the Service Provider */
3099/* that requested the timer; may be NULL */
3100CWA 16926-1:2015 (E)
3101125
310210.3 WFS_SYSE_DEVICE_STATUS
3103Status changes of logical services (which typically reflect changes in physical devices) are reported as system events. This is in addition to being reported by the WFS_INF_xxx_STATUS query of the WFSGetInfo or WFSAsyncGetInfo functions. The WFSRESULT data structure (defined in Section 9.1) is utilized as follows:
3104Field Description
3105RequestID (not used)
3106hService Service handle identifying the session that created the result, i.e. the service handle of the session that the event is sent to.
3107tsTimestamp Time the status change occurred (local time, in a Win32/Win64 SYSTEMTIME structure).
3108hResult (not used)
3109u.dwEventID = WFS_SYSE_DEVICE_STATUS
3110lpBuffer Pointer to a WFSDEVSTATUS structure:
3111typedef struct _wfs_devstatus {
3112LPSTR lpszPhysicalName;
3113LPSTR lpszWorkstationName;
3114DWORD dwState;
3115} WFSDEVSTATUS, *LPWFSDEVSTATUS;
3116The members of this structure are:
3117Field Description
3118lpszPhysicalName Pointer to the physical service name of the service that changed its state.
3119lpszWorkstationName Pointer to the name of the workstation in which the logical service name is defined.
3120dwState Specifies the new state of the physical device managed by the service as one of the following:
3121Value Meaning
3122WFS_STAT_DEVONLINE The device is online (i.e. powered on and operable).
3123WFS_STAT_DEVOFFLINE The device is offline (e.g. the operator has taken the device offline by turning a switch).
3124WFS_STAT_DEVPOWEROFF The device is powered off or physically not connected.
3125WFS_STAT_DEVNODEVICE There is no device intended to be there; e.g. this type of self service machine does not contain such a device or it is internally not configured.
3126WFS_STAT_DEVHWERROR The device is inoperable due to a hardware error.
3127WFS_STAT_DEVUSERERROR The device is inoperable because a person is preventing proper device operation.
3128WFS_STAT_DEVFRAUDATTEMPT Some devices are capable of identifying a malicious physical attack which attempts to defraud valuable information or media. In this circumstance, this status code is returned to indicate the device is inoperable because a person attempted a fraudulent act on the device.
3129WFS_STAT_DEVPOTENTIALFRAUD The device has detected a potential fraud attempt and is capable of remaining in service. In this case the application should make the decision as to whether to take the device offline.
3130CWA 16926-1:2015 (E)
3131126
313210.4 WFS_SYSE_UNDELIVERABLE_MSG
3133If a command completion or event message cannot be delivered, it is reported as a system event. The WFSRESULT data structure (defined in Section 9.1) is utilized as follows:
3134Field Description
3135RequestID (not used)
3136hService Service handle identifying the session that the event is sent to.
3137tsTimestamp Time the event occurred (local time, in a Win32/Win64 SYSTEMTIME structure).
3138hResult (not used)
3139u.dwEventID = WFS_SYSE_UNDELIVERABLE_MSG
3140lpBuffer Pointer to a WFSUNDEVMSG structure:
3141typedef struct _wfs_undevmsg {
3142LPSTR lpszLogicalName;
3143LPSTR lpszWorkstationName;
3144LPSTR lpszAppID;
3145DWORD dwSize;
3146LPBYTE lpbDescription;
3147DWORD dwMsg;
3148LPWFSRESULT lpWFSResult;
3149} WFSUNDEVMSG, *LPWFSUNDEVMSG;
3150The members of this structure are:
3151Field Description
3152lpszLogicalName Pointer to the logical service name of the service that generated the original undeliverable message.
3153lpszWorkstationName Pointer to the name of the workstation in which the logical service name is defined.
3154lpszAppID Pointer to the application ID associated with the session that generated the original message.
3155dwSize The size in bytes of the following description.
3156lpbDescription Pointer to a vendor-specific description of the reason why the message could not be delivered.
3157dwMsg The message identifier of the original message.
3158lpWFSResult Pointer to the WFSRESULT structure of the original message (which has the lpBuffer parameter set to NULL). This structure includes the hService of the session where the message could not be delivered.
3159CWA 16926-1:2015 (E)
3160127
316110.5 WFS_SYSE_APP_DISCONNECT
3162If the XFS subsystem loses connection to an application, it closes the session (see Section 4.6) and generates this system event. The WFSRESULT data structure (defined in Section 9.1) is utilized as follows:
3163Field Description
3164RequestID (not used)
3165hService Service handle identifying the session that the event is sent to.
3166tsTimestamp Time the event occurred (local time, in a Win32/Win64 SYSTEMTIME structure).
3167hResult (not used)
3168u.dwEventID = WFS_SYSE_APP_DISCONNECT
3169lpBuffer Pointer to a WFSAPPDISC structure:
3170typedef struct _wfs_appdisc {
3171LPSTR lpszLogicalName;
3172LPSTR lpszWorkstationName;
3173LPSTR lpszAppID;
3174} WFSAPPDISC, *LPWFSAPPDISC;
3175The members of this structure are:
3176Field Description
3177lpszLogicalName Pointer to the logical service name of the service that the application was connected to.
3178lpszWorkstationName Pointer to the name of the workstation in which the logical service name is defined.
3179lpszAppID Pointer to the application ID associated with the session that generated the event.
3180CWA 16926-1:2015 (E)
3181128
318210.6 WFS_SYSE_HARDWARE_ERROR, WFS_SYSE_SOFTWARE_ERROR, WFS_SYSE_USER_ERROR and WFS_SYSE_FRAUD_ATTEMPT
3183Hardware and software errors are reported as system events. In most cases, this is in addition to being reported via the WFS_ERR_HARDWARE_ERROR (or device class specific error code), the WFS_ERR_SOFTWARE_ERROR or WFS_ERR_USER_ERROR error code that is returned as the command completion.
3184In order to supply the maximum information, these events should be sent as soon as an error is detected. In particular, if an error is detected during the processing of an execute command, then the event should be sent before the command completion event.
3185The WFSRESULT data structure (defined in Section 9.1), is utilized as follows:
3186Field Description
3187RequestID Request ID of the request being processed when the error occurred, zero if no request was being processed when the error occurred.
3188hService Service handle identifying the session that the event is sent to.
3189tsTimestamp Time the error occurred (local time, in a Win32/Win64 SYSTEMTIME structure).
3190hResult Result handle of the request being processed when the error occurred, zero if no request was being processed.
3191u.dwEventID The ID of the error.
3192Value Meaning
3193WFS_SYSE_HARDWARE_ERROR The error is a hardware error
3194WFS_SYSE_SOFTWARE_ERROR The error is a software error
3195WFS_SYSE_USER_ERROR The error is a user error
3196WFS_SYSE_FRAUD_ATTEMPT Some devices are capable of identifying a malicious physical attack which attempts to defraud valuable information or media. In this circumstance, this error event is returned to indicate a fraud attempt has occurred.
3197lpBuffer Pointer to a WFSHWERROR structure:
3198typedef struct _wfs_hwerror {
3199LPSTR lpszLogicalName;
3200LPSTR lpszPhysicalName;
3201LPSTR lpszWorkstationName;
3202LPSTR lpszAppID;
3203DWORD dwAction;
3204DWORD dwSize;
3205LPBYTE lpbDescription;
3206} WFSHWERROR, *LPWFSHWERROR;
3207The members of this structure are:
3208Field Description
3209lpszLogicalName Pointer to the logical service name of the service that generated the error
3210lpszPhysicalName Pointer to the physical service name of the service that generated the error
3211lpszWorkstationName Pointer to the name of the workstation in which the logical service name is defined (if any)
3212lpszAppID Pointer to the application ID associated with the session that generated the error (if any)
3213dwAction The action required to manage the error. Possible values are:
3214Value Meaning
3215WFS_ERR_ACT_NOACTION No action required or error was autorecovered.
3216WFS_ERR_ACT_RESET Reset device to attempt recovery.
3217WFS_ERR_ACT_SWERROR A software error occurred. Contact software vendor.
3218WFS_ERR_ACT_CONFIG A configuration error occurred. Check configuration.
3219WFS_ERR_ACT_HWCLEAR Recovery is not possible. A manual intervention for clearing the device is required. This value is only used for hardware errors. This value is
3220CWA 16926-1:2015 (E)
3221129
3222typically returned when a hardware error has occurred which requires banking personnel specific maintenance, e.g. ‘replace paper’, or ‘remove cards from retain bin’.
3223WFS_ERR_ACT_HWMAINT Recovery is not possible. A technical maintenance intervention is required. This value is only used for hardware errors and fraud attempts. This value is typically returned when a hardware error or fraud attempt has occurred which requires field engineer specific maintenance activity.
3224WFS_ERR_ACT_SUSPEND Device will attempt auto recovery and will advise any further action required via a Device Status Event.
3225dwSize The size in bytes of the following description
3226lpbDescription Pointer to a vendor-specific description of the error.
3227Note:
3228The following table describes what dwAction may be returned for the various Hardware, Software, User Error and Fraud Attempt Events:
3229Generated on Hardware Event?
3230Generated on Software Event?
3231Generated on User Event?
3232Generated on Fraud Event?
3233_NOACTION
3234Yes
3235Yes
3236Yes
3237Yes
3238_RESET
3239Yes
3240Yes
3241Yes
3242No
3243_SWERROR
3244No
3245Yes
3246No
3247No
3248_CONFIG
3249Yes
3250Yes
3251No
3252No
3253_HWCLEAR
3254Yes
3255No
3256No
3257No
3258_HWMAINT
3259Yes
3260No
3261No
3262Yes
3263_SUSPEND
3264No
3265No
3266Yes
3267No
3268CWA 16926-1:2015 (E)
3269130
327010.7 WFS_SYSE_LOCK_REQUESTED
3271The Lock requested system event is sent to any application which currently has a device locked whenever a request for a lock on the same device is received from another application or service handle. Note that this event is generated each time another application requests a lock on the same device. This system event differs from other system events in that it is only posted to the owner of the lock; it is NOT posted to any other application.
3272Field Description
3273RequestID (not used)
3274hService Service handle identifying the device and session which has obtained the lock.
3275tsTimestamp Time the status change occurred (local time, in a Win32/Win64 SYSTEMTIME structure).
3276hResult (not used)
3277u.dwEventID = WFS_SYSE_LOCK_REQUESTED
3278lpBuffer (not used)
3279CWA 16926-1:2015 (E)
3280131
328110.8 WFS_SYSE_VERSION_ERROR
3282Failures in version negotiation are reported as system events. This is in addition to being reported by the version error code returned by the WFSStartUp or WFSOpen functions. The WFSRESULT data structure (defined in Section 9.1) is utilized as follows:
3283Field Description
3284RequestID (not used)
3285hService (not used)
3286tsTimestamp Time the error occurred (local time, in a Win32/Win64 SYSTEMTIME structure).
3287hResult The version error code (e.g. WFS_ERR_SPI_VER_TOO_HIGH).
3288u.dwEventID = WFS_SYSE_VERSION_ERROR
3289lpBuffer Pointer to a WFSVRSNERROR structure:
3290typedef struct _wfs_vrsnerror {
3291LPSTR lpszLogicalName;
3292LPSTR lpszWorkstationName;
3293LPSTR lpszAppID;
3294DWORD dwSize;
3295LPBYTE lpbDescription;
3296LPWFSVERSION lpWFSVersion;
3297} WFSVRSNERROR, *LPWFSVRSNERROR
3298The members of this structure are:
3299Field Description
3300lpszLogicalName Pointer to the logical service name of the service being opened (NULL if WFSStartUp).
3301lpszWorkstationName Pointer to the name of the workstation in which the application made the WFSStartUp or WFSOpen request.
3302lpszAppID Pointer to the application ID from the open request that failed (NULL if WFSStartUp).
3303dwSize The size in bytes of the following description.
3304lpbDescription Pointer to a vendor-specific description of the version negotiation failure.
3305lpWFSVersion Pointer to the WFSVERSION structure reporting the results of the version negotiation.
3306CWA 16926-1:2015 (E)
3307132
330811. Error Codes
3309The following are the error codes that can be returned from a call to an XFS API or SPI function, either as a function return or in a result structure pointed to by a completion message. Errors from service-specific commands are defined in the specifications for each service class.
3310WFS_ERR_ALREADY_STARTED
3311A WFSStartUp has already been issued by the application, without an intervening WFSCleanUp.
3312WFS_ERR_API_VER_TOO_HIGH
3313The range of versions of XFS API support requested by the application is higher than any supported by this particular XFS Manager implementation.
3314WFS_ERR_API_VER_TOO_LOW
3315The range of versions of XFS API support requested by the application is lower than any supported by this particular XFS Manager implementation.
3316WFS_ERR_CANCELED
3317The request was canceled by WFSCancelAsyncRequest or WFSCancelBlockingCall.
3318WFS_ERR_CFG_INVALID_HKEY
3319The specified hKey parameter does not correspond to a currently open key.
3320WFS_ERR_CFG_INVALID_NAME
3321The value specified by the lpszValueName parameter does not exist in the specified key.
3322WFS_ERR_CFG_INVALID_SUBKEY
3323The key specified by lpszSubKey does not exist.
3324WFS_ERR_CFG_INVALID_VALUE
3325The specified value does not exist within the specified open key.
3326WFS_ERR_CFG_KEY_NOT_EMPTY
3327The specified key has subkeys and cannot be deleted. The subkeys must be deleted first.
3328WFS_ERR_CFG_NAME_TOO_LONG
3329The length of the name to be returned exceeds the length of the buffer.
3330WFS_ERR_CFG_NO_MORE_ITEMS
3331There are no more subkeys to be returned (the iSubKey parameter is greater than the index of the last subkey).
3332WFS_ERR_CFG_VALUE_TOO_LONG
3333The length of the value to be returned exceeds the length of the buffer.
3334WFS_ERR_CONNECTION_LOST
3335The connection to the service is lost.
3336WFS_ERR_DEV_NOT_READY
3337The function required device access, and the device was not ready or timed out.
3338WFS_ERR_HARDWARE_ERROR
3339The function required device access, and an error occurred on the device.
3340WFS_ERR_INTERNAL_ERROR
3341An internal inconsistency or other unexpected error occurred in the XFS subsystem.
3342WFS_ERR_INVALID_ADDRESS
3343The lpvOriginal parameter does not point to a previously allocated buffer.
3344WFS_ERR_INVALID_APP_HANDLE
3345The specified application handle is not valid, i.e. was not created by a preceding create call.
3346WFS_ERR_INVALID_BUFFER
3347The lpvData parameter is not a pointer to an allocated buffer structure.
3348WFS_ERR_INVALID_CATEGORY
3349The dwCategory issued is not supported by this service class.
3350CWA 16926-1:2015 (E)
3351133
3352WFS_ERR_INVALID_COMMAND
3353The dwCommand issued is not supported by this service class.
3354WFS_ERR_INVALID_EVENT_CLASS
3355The dwEventClass parameter specifies one or more event classes not supported by the service.
3356WFS_ERR_INVALID_HSERVICE
3357The hService parameter is not a valid service handle.
3358WFS_ERR_INVALID_HPROVIDER
3359The hProvider parameter is not a valid provider handle.
3360WFS_ERR_INVALID_HWND
3361The hWnd parameter is not a valid window handle.
3362WFS_ERR_INVALID_HWNDREG
3363The hWndReg parameter is not a valid window handle.
3364WFS_ERR_INVALID_POINTER
3365A pointer parameter does not point to accessible memory.
3366WFS_ERR_INVALID_DATA
3367The data structure passed as input parameter contains invalid data.
3368WFS_ERR_INVALID_REQ_ID
3369The RequestID parameter does not correspond to an outstanding request on the service.
3370WFS_ERR_INVALID_RESULT
3371The lpResult parameter is not a pointer to an allocated WFSRESULT structure.
3372WFS_ERR_INVALID_SERVPROV
3373The file containing the Service Provider is invalid or corrupted.
3374WFS_ERR_INVALID_TIMER
3375The hWnd and wTimerID parameters do not correspond to a currently active timer.
3376WFS_ERR_INVALID_TRACELEVEL
3377The dwTraceLevel parameter does not correspond to a valid trace level or set of levels.
3378WFS_ERR_LOCKED
3379The service is locked under a different hService.
3380WFS_ERR_NO_BLOCKING_CALL
3381There is no outstanding blocking call for the specified thread.
3382WFS_ERR_NO_SERVPROV
3383The file containing the Service Provider does not exist.
3384WFS_ERR_NO_SUCH_THREAD
3385The specified thread does not exist.
3386WFS_ERR_NO_TIMER
3387The timer could not be created.
3388WFS_ERR_NOT_LOCKED
3389The application requesting a service be unlocked had not previously performed a successful WFSLock or WFSAsyncLock.
3390WFS_ERR_NOT_OK_TO_UNLOAD
3391The XFS Manager may not unload the Service Provider DLL.
3392WFS_ERR_NOT_STARTED
3393The application has not previously performed a successful WFSStartUp.
3394WFS_ERR_NOT_REGISTERED
3395The specified hWndReg window was not registered to receive messages for any event classes.
3396WFS_ERR_OP_IN_PROGRESS
3397A blocking operation is in progress on the thread; only WFSCancelBlockingCall and WFSIsBlocking are permitted at this time.
3398WFS_ERR_OUT_OF_MEMORY
3399There is not enough memory available to satisfy the request.
3400CWA 16926-1:2015 (E)
3401134
3402WFS_ERR_SERVICE_NOT_FOUND
3403The logical name is not a valid Service Provider name.
3404WFS_ERR_SOFTWARE_ERROR
3405The function required access to configuration information, and an error occurred on the software.
3406WFS_ERR_SPI_VER_TOO_HIGH
3407The range of versions of XFS SPI support requested by the XFS Manager is higher than any supported by the Service Provider for the logical service being opened.
3408WFS_ERR_SPI_VER_TOO_LOW
3409The range of versions of XFS SPI support requested by the XFS Manager is lower than any supported by the Service Provider for the logical service being opened.
3410WFS_ERR_SRVC_VER_TOO_HIGH
3411The range of versions of the service-specific interface support requested by the application is higher than any supported by the Service Provider for the logical service being opened.
3412WFS_ERR_SRVC_VER_TOO_LOW
3413The range of versions of the service-specific interface support requested by the application is lower than any supported by the Service Provider for the logical service being opened.
3414WFS_ERR_TIMEOUT
3415The timeout interval expired.
3416WFS_ERR_UNSUPP_CATEGORY
3417The dwCategory issued, although valid for this service class, is not supported by this Service Provider.
3418WFS_ERR_UNSUPP_COMMAND
3419The dwCommand issued, although valid for this service class, is not supported by this Service Provider or device.
3420WFS_ERR_UNSUPP_DATA
3421The data structure passed as an input parameter although valid for this service class is not supported by this Service Provider or device.
3422WFS_ERR_USER_ERROR
3423A user is preventing proper operation of the device.
3424WFS_ERR_VERSION_ERROR_IN_SRVC
3425Within the service, a version mismatch of two modules occurred.
3426WFS_ERR_FRAUD_ATTEMPT
3427Some devices are capable of identifying a malicious physical attack which attempts to defraud valuable information or media. In these cases, this error code is returned to indicate the user is attempting a fraudulent act on the device.
3428WFS_ERR_SEQUENCE_ERROR
3429The requested operation is not valid at this time or in the devices current state.
3430WFS_ERR_AUTH_REQUIRED
3431The requested operation cannot be performed because it requires authentication.
3432CWA 16926-1:2015 (E)
3433135
343412. Appendix A - Planned Enhancements and Extensions
3435This section describes functions and facilities that are not fully defined in this version of the Extensions for Financial Services specification; modifications and complete definitions will be supplied in later versions. Vendor and user input is encouraged on these functions and facilities, as well as suggestions as to additional functionality.
3436XFS currently includes specifications for access to the key classes of financial peripherals for attended and self-service environments. These existing specifications will be extended and enhanced based on vendor and user experience with them. The Service Class Definition Document lists the classes of devices or services that, together with others that customers and vendors request, will be evaluated for inclusion in future versions of this specification.
3437Also to be considered for future versions of XFS are other types of services, such as financial transaction messaging and management, as well as related services for financial networks such as network and systems management and security. As with the current specification, all these capabilities will be specified for access from the familiar, consistent Microsoft Windows user interface and programming environments. Another portion of the XFS API set will deal with administration issues.
3438CWA 16926-1:2015 (E)
3439136
344012.1 Event and System Management
3441The XFS subsystem will need additional facilities for managing exception conditions (i.e. those that are not anticipated in the error codes, events, etc., that are defined in this specification). One general facility for this is the system event capability, as described in Sections 4.11 and 10. This will utilize a combination of one or more functions provided by the XFS Manager and other methods for applications, the XFS Manager, Service Providers, and services to report exception conditions in special circumstances (e.g. when the XFS Manager is not available). Such conditions would presumably be monitored by a system management agent responsible for logging and reporting them via a network management facility.
3442CWA 16926-1:2015 (E)
3443137
344413. Appendix B - XFS Workshop Contacts
3445Please submit comments and questions to
3446xfs-helpdesk@cenorm.be
3447Or contact
3448Luc Van den Berghe
3449CEN Workshop Manager
3450Rue de Stassart 36
3451B-1050 Brussels
3452Luc.vandenberghe@cenorm.be
3453Tel: + 32 2 55 00 957
3454CWA 16926-1:2015 (E)
3455138
345614. Appendix C - ATM Devices Synchronization Flow
3457The following section describes the flow of a synchronization use case using WFS_CMD_XXX_SYNCHRONIZE_COMMAND. This application flow is provided as a guideline only.
345814.1 Synchronized Media Ejection
3459The following table describes the flow of a transaction where the receipt ejection is synchronized with the card ejection during the transaction. Both Service Providers and the devices support the synchronization in this example.
3460Step
3461Application/XFS Commands
3462Service Providers / Devices
3463The next step is to eject the receipt and the card at the end of the transaction. The application would like to synchronize the receipt ejection with the card ejection.
34641.
3465Informs the PTR class Service Provider that the subsequent command is the “eject receipt” and that this command needs to be executed without delay for synchronization purposes.
3466WFS_CMD_PTR_SYNCHRONIZE_COMMAND (dwCommand: WFS_CMD_PTR_CONTROL_MEDIA) (specifying WFS_PTR_CTRLEJECT as its parameter)
3467PTR class Service Provider sends a synchronization command to the receipt printer device for the receipt ejection.
34682.
3469Informs the IDC class Service Provider that the subsequent command is the “eject card” and that this command needs to be executed without delay for synchronization purposes.
3470WFS_CMD_IDC_SYNCHRONIZE_COMMAND (dwCommand: WFS_CMD_IDC_EJECT_CARD) (specifying WFS_IDC_EXITPOSITION as its parameter)
3471IDC class Service Provider sends a synchronization command to the card reader device for the card ejection.
34723.
3473WFS_CMD_PTR_SYNCHRONIZE_COMMAND completion event.
3474WFS_CMD_IDC_SYNCHRONIZE_COMMAND completion event.
34754.
3476The application executes the following commands at the same time.
3477- Initiates via a WFSAsyncExecute WFS_CMD_PTR_CONTROL_MEDIA.
3478- Initiates via a WFSAsyncExecute WFS_CMD_IDC_EJECT_CARD.
3479(The parameters are the same as specified in the WFS_CMD_XXX_SYNCHRONIZATION_COMMANDs)
3480The following actions are performed at the same time.
3481- The receipt is ejected.
3482- The card is ejected.
34835.
3484WFS_CMD_PTR_CONTROL_MEDIA completion event.
3485WFS_CMD_IDC_EJECT_CARD completion event.
3486CWA 16926-1:2015 (E)
3487139
348815. Appendix D – Win64 Migration Considerations
3489Users must ensure that when porting their XFS applications to the Win64 environment that care is taken to update their existing code correctly in order to avoid issues. Microsoft state that porting 32-bit applications to 64-bit will be easier than it was porting 16-bit applications to 32-bit Windows, but care must still be taken in certain areas.
3490On 64 bit operating systems it is possible to run either a complete 32 bit XFS software stack, or a complete 64 bit software stack. Where a native 64 bit application is being run a 64 bit XFS Manager must be used. A sample XFS Manager is supplied with the XFS SDK, however this is a 32 bit XFS Manager only.
3491By far the biggest change when migrating C code is the change in pointer size from 32 to 64 bits. As the XFS architecture makes extensive use of pointers this change may have a significant impact on native XFS applications that currently run on Win32 environments. The following are some considerations for developers with regard to the XFS architecture:
34921. As it is impossible for a 64-bit process to load a 32-bit DLL directly it is recommended that the entire software stack from the the application to the Service Providers should be native 64-bit where possible. While this is the most ideal solution it is not mandatory but a recommendation, as feasibly some dependencies could run out of process to the application and/or the Service Providers. The XFS Manager that is used will always need to be 64-bit for a 64-bit application.
34932. All declarations, use and storage of pointers should be checked. In C code memory addresses are often stored as a ULONG value, because on 32-bit Windows an address, a pointer, and a ULONG are all 32 bits. On 64-bit Windows a ULONG is also 32 bits long, but all pointers are 64-bit values. Functions such as the C sizeof() method will also need to be checked as the value that they return for the size of a pointer will be 8 bytes rather than 4 bytes. C style casts will also need to be scrutinized as potentially they may cast a pointer to a 32 bit value.
34943. In order to prepare for the possibilityof future porting to 64-bit code, developers should consider using the latest Windows header files that contain the portable pointer precision type ULONG_PTR. This data type can be used in current 32-bit code to store pointer values instead of a ULONG. The ULONG_PTR data type is a portable value that is 32 bits when compiled with a 32-bit compiler and 64 bits when compiled with a 64-bit compiler, thus ensuring good compatibility when compiled in either environment.
34954. If running a 32 bit application on a 64 bit operating system then the operating system may manage the precise location of the XFS registry locations in 32 bit compatible areas of the registry.
3496CWA 16926-1:2015 (E)
3497140
349816. Appendix D - C-Header files
349916.1 XFSAPI.H
3500/************************************************************************
3501* *
3502* xfsapi.h XFS - API functions, types, and definitions *
3503* *
3504* Version 3.30 (March 19 2015) *
3505* *
3506************************************************************************/
3507#ifndef __inc_xfsapi__h
3508#define __inc_xfsapi__h
3509#ifdef __cplusplus
3510extern "C" {
3511#endif
3512#include <windows.h>
3513/* be aware of alignment */
3514#pragma pack(push,1)
3515/****** Common *********************************************************/
3516typedef unsigned short USHORT;
3517typedef char CHAR;
3518typedef short SHORT;
3519typedef unsigned long ULONG;
3520typedef unsigned char UCHAR;
3521typedef SHORT * LPSHORT;
3522typedef LPVOID * LPLPVOID;
3523typedef ULONG * LPULONG;
3524typedef USHORT * LPUSHORT;
3525typedef HANDLE HPROVIDER;
3526typedef ULONG REQUESTID;
3527typedef REQUESTID * LPREQUESTID;
3528typedef HANDLE HAPP;
3529typedef HAPP * LPHAPP;
3530typedef USHORT HSERVICE;
3531typedef HSERVICE * LPHSERVICE;
3532typedef LONG HRESULT;
3533typedef HRESULT * LPHRESULT;
3534typedef BOOL (WINAPI * XFSBLOCKINGHOOK)(VOID);
3535typedef XFSBLOCKINGHOOK * LPXFSBLOCKINGHOOK;
3536/****** String lengths **************************************************/
3537#define WFSDDESCRIPTION_LEN 256
3538#define WFSDSYSSTATUS_LEN 256
3539/****** Values of WFSDEVSTATUS.fwState **********************************/
3540#define WFS_STAT_DEVONLINE (0)
3541#define WFS_STAT_DEVOFFLINE (1)
3542#define WFS_STAT_DEVPOWEROFF (2)
3543#define WFS_STAT_DEVNODEVICE (3)
3544#define WFS_STAT_DEVHWERROR (4)
3545#define WFS_STAT_DEVUSERERROR (5)
3546#define WFS_STAT_DEVBUSY (6)
3547#define WFS_STAT_DEVFRAUDATTEMPT (7)
3548CWA 16926-1:2015 (E)
3549141
3550#define WFS_STAT_DEVPOTENTIALFRAUD (8)
3551/****** Value of WFS_DEFAULT_HAPP ***************************************/
3552#define WFS_DEFAULT_HAPP (0)
3553/****** Data Structures *************************************************/
3554typedef struct _wfs_result
3555{
3556REQUESTID RequestID;
3557HSERVICE hService;
3558SYSTEMTIME tsTimestamp;
3559HRESULT hResult;
3560union {
3561DWORD dwCommandCode;
3562DWORD dwEventID;
3563} u;
3564LPVOID lpBuffer;
3565} WFSRESULT, * LPWFSRESULT;
3566typedef struct _wfsversion
3567{
3568WORD wVersion;
3569WORD wLowVersion;
3570WORD wHighVersion;
3571CHAR szDescription[WFSDDESCRIPTION_LEN+1];
3572CHAR szSystemStatus[WFSDSYSSTATUS_LEN+1];
3573} WFSVERSION, * LPWFSVERSION;
3574/****** Message Structures **********************************************/
3575typedef struct _wfs_devstatus
3576{
3577LPSTR lpszPhysicalName;
3578LPSTR lpszWorkstationName;
3579DWORD dwState;
3580} WFSDEVSTATUS, * LPWFSDEVSTATUS;
3581typedef struct _wfs_undevmsg
3582{
3583LPSTR lpszLogicalName;
3584LPSTR lpszWorkstationName;
3585LPSTR lpszAppID;
3586DWORD dwSize;
3587LPBYTE lpbDescription;
3588DWORD dwMsg;
3589LPWFSRESULT lpWFSResult;
3590} WFSUNDEVMSG, * LPWFSUNDEVMSG;
3591typedef struct _wfs_appdisc
3592{
3593LPSTR lpszLogicalName;
3594LPSTR lpszWorkstationName;
3595LPSTR lpszAppID;
3596} WFSAPPDISC, * LPWFSAPPDISC;
3597typedef struct _wfs_hwerror
3598{
3599LPSTR lpszLogicalName;
3600LPSTR lpszPhysicalName;
3601LPSTR lpszWorkstationName;
3602LPSTR lpszAppID;
3603DWORD dwAction;
3604DWORD dwSize;
3605LPBYTE lpbDescription;
3606} WFSHWERROR, * LPWFSHWERROR;
3607typedef struct _wfs_vrsnerror
3608{
3609LPSTR lpszLogicalName;
3610CWA 16926-1:2015 (E)
3611142
3612LPSTR lpszWorkstationName;
3613LPSTR lpszAppID;
3614DWORD dwSize;
3615LPBYTE lpbDescription;
3616LPWFSVERSION lpWFSVersion;
3617} WFSVRSNERROR, * LPWFSVRSNERROR;
3618/****** Error codes ******************************************************/
3619#define WFS_SUCCESS (0)
3620#define WFS_ERR_ALREADY_STARTED (-1)
3621#define WFS_ERR_API_VER_TOO_HIGH (-2)
3622#define WFS_ERR_API_VER_TOO_LOW (-3)
3623#define WFS_ERR_CANCELED (-4)
3624#define WFS_ERR_CFG_INVALID_HKEY (-5)
3625#define WFS_ERR_CFG_INVALID_NAME (-6)
3626#define WFS_ERR_CFG_INVALID_SUBKEY (-7)
3627#define WFS_ERR_CFG_INVALID_VALUE (-8)
3628#define WFS_ERR_CFG_KEY_NOT_EMPTY (-9)
3629#define WFS_ERR_CFG_NAME_TOO_LONG (-10)
3630#define WFS_ERR_CFG_NO_MORE_ITEMS (-11)
3631#define WFS_ERR_CFG_VALUE_TOO_LONG (-12)
3632#define WFS_ERR_DEV_NOT_READY (-13)
3633#define WFS_ERR_HARDWARE_ERROR (-14)
3634#define WFS_ERR_INTERNAL_ERROR (-15)
3635#define WFS_ERR_INVALID_ADDRESS (-16)
3636#define WFS_ERR_INVALID_APP_HANDLE (-17)
3637#define WFS_ERR_INVALID_BUFFER (-18)
3638#define WFS_ERR_INVALID_CATEGORY (-19)
3639#define WFS_ERR_INVALID_COMMAND (-20)
3640#define WFS_ERR_INVALID_EVENT_CLASS (-21)
3641#define WFS_ERR_INVALID_HSERVICE (-22)
3642#define WFS_ERR_INVALID_HPROVIDER (-23)
3643#define WFS_ERR_INVALID_HWND (-24)
3644#define WFS_ERR_INVALID_HWNDREG (-25)
3645#define WFS_ERR_INVALID_POINTER (-26)
3646#define WFS_ERR_INVALID_REQ_ID (-27)
3647#define WFS_ERR_INVALID_RESULT (-28)
3648#define WFS_ERR_INVALID_SERVPROV (-29)
3649#define WFS_ERR_INVALID_TIMER (-30)
3650#define WFS_ERR_INVALID_TRACELEVEL (-31)
3651#define WFS_ERR_LOCKED (-32)
3652#define WFS_ERR_NO_BLOCKING_CALL (-33)
3653#define WFS_ERR_NO_SERVPROV (-34)
3654#define WFS_ERR_NO_SUCH_THREAD (-35)
3655#define WFS_ERR_NO_TIMER (-36)
3656#define WFS_ERR_NOT_LOCKED (-37)
3657#define WFS_ERR_NOT_OK_TO_UNLOAD (-38)
3658#define WFS_ERR_NOT_STARTED (-39)
3659#define WFS_ERR_NOT_REGISTERED (-40)
3660#define WFS_ERR_OP_IN_PROGRESS (-41)
3661#define WFS_ERR_OUT_OF_MEMORY (-42)
3662#define WFS_ERR_SERVICE_NOT_FOUND (-43)
3663#define WFS_ERR_SPI_VER_TOO_HIGH (-44)
3664#define WFS_ERR_SPI_VER_TOO_LOW (-45)
3665#define WFS_ERR_SRVC_VER_TOO_HIGH (-46)
3666#define WFS_ERR_SRVC_VER_TOO_LOW (-47)
3667#define WFS_ERR_TIMEOUT (-48)
3668#define WFS_ERR_UNSUPP_CATEGORY (-49)
3669#define WFS_ERR_UNSUPP_COMMAND (-50)
3670#define WFS_ERR_VERSION_ERROR_IN_SRVC (-51)
3671#define WFS_ERR_INVALID_DATA (-52)
3672#define WFS_ERR_SOFTWARE_ERROR (-53)
3673#define WFS_ERR_CONNECTION_LOST (-54)
3674#define WFS_ERR_USER_ERROR (-55)
3675#define WFS_ERR_UNSUPP_DATA (-56)
3676#define WFS_ERR_FRAUD_ATTEMPT (-57)
3677#define WFS_ERR_SEQUENCE_ERROR (-58)
3678#define WFS_ERR_AUTH_REQUIRED (-59)
3679CWA 16926-1:2015 (E)
3680143
3681#define WFS_INDEFINITE_WAIT 0
3682/****** Messages ********************************************************/
3683/* Message-No = (WM_USER + No) */
3684#define WFS_OPEN_COMPLETE (WM_USER + 1)
3685#define WFS_CLOSE_COMPLETE (WM_USER + 2)
3686#define WFS_LOCK_COMPLETE (WM_USER + 3)
3687#define WFS_UNLOCK_COMPLETE (WM_USER + 4)
3688#define WFS_REGISTER_COMPLETE (WM_USER + 5)
3689#define WFS_DEREGISTER_COMPLETE (WM_USER + 6)
3690#define WFS_GETINFO_COMPLETE (WM_USER + 7)
3691#define WFS_EXECUTE_COMPLETE (WM_USER + 8)
3692#define WFS_EXECUTE_EVENT (WM_USER + 20)
3693#define WFS_SERVICE_EVENT (WM_USER + 21)
3694#define WFS_USER_EVENT (WM_USER + 22)
3695#define WFS_SYSTEM_EVENT (WM_USER + 23)
3696#define WFS_TIMER_EVENT (WM_USER + 100)
3697/****** Event Classes ***************************************************/
3698#define SERVICE_EVENTS (1)
3699#define USER_EVENTS (2)
3700#define SYSTEM_EVENTS (4)
3701#define EXECUTE_EVENTS (8)
3702/****** System Event IDs ************************************************/
3703#define WFS_SYSE_UNDELIVERABLE_MSG (1)
3704#define WFS_SYSE_HARDWARE_ERROR (2)
3705#define WFS_SYSE_VERSION_ERROR (3)
3706#define WFS_SYSE_DEVICE_STATUS (4)
3707#define WFS_SYSE_APP_DISCONNECT (5)
3708#define WFS_SYSE_SOFTWARE_ERROR (6)
3709#define WFS_SYSE_USER_ERROR (7)
3710#define WFS_SYSE_LOCK_REQUESTED (8)
3711#define WFS_SYSE_FRAUD_ATTEMPT (9)
3712/****** XFS Trace Level ********************************************/
3713#define WFS_TRACE_API (0x00000001)
3714#define WFS_TRACE_ALL_API (0x00000002)
3715#define WFS_TRACE_SPI (0x00000004)
3716#define WFS_TRACE_ALL_SPI (0x00000008)
3717#define WFS_TRACE_MGR (0x00000010)
3718/****** XFS Error Actions ********************************************/
3719#define WFS_ERR_ACT_NOACTION (0x0000)
3720#define WFS_ERR_ACT_RESET (0x0001)
3721#define WFS_ERR_ACT_SWERROR (0x0002)
3722#define WFS_ERR_ACT_CONFIG (0x0004)
3723#define WFS_ERR_ACT_HWCLEAR (0x0008)
3724#define WFS_ERR_ACT_HWMAINT (0x0010)
3725#define WFS_ERR_ACT_SUSPEND (0x0020)
3726/****** XFS SNMP MIB Category Codes **********************************/
3727/* NOTE: To support the XFS SNMP MIB, the WFSGet[Async]Info category codes between 60000 and 60999 are reserved.*/
3728/****** API functions ***************************************************/
3729HRESULT extern WINAPI WFSCancelAsyncRequest ( HSERVICE hService, REQUESTID RequestID);
3730CWA 16926-1:2015 (E)
3731144
3732HRESULT extern WINAPI WFSCancelBlockingCall ( DWORD dwThreadID);
3733HRESULT extern WINAPI WFSCleanUp ();
3734HRESULT extern WINAPI WFSClose ( HSERVICE hService);
3735HRESULT extern WINAPI WFSAsyncClose ( HSERVICE hService, HWND hWnd, LPREQUESTID lpRequestID);
3736HRESULT extern WINAPI WFSCreateAppHandle ( LPHAPP lphApp);
3737HRESULT extern WINAPI WFSDeregister ( HSERVICE hService, DWORD dwEventClass, HWND hWndReg);
3738HRESULT extern WINAPI WFSAsyncDeregister ( HSERVICE hService, DWORD dwEventClass, HWND hWndReg, HWND hWnd, LPREQUESTID lpRequestID);
3739HRESULT extern WINAPI WFSDestroyAppHandle ( HAPP hApp);
3740HRESULT extern WINAPI WFSExecute ( HSERVICE hService, DWORD dwCommand, LPVOID lpCmdData, DWORD dwTimeOut, LPWFSRESULT * lppResult);
3741HRESULT extern WINAPI WFSAsyncExecute ( HSERVICE hService, DWORD dwCommand, LPVOID lpCmdData, DWORD dwTimeOut, HWND hWnd, LPREQUESTID lpRequestID);
3742HRESULT extern WINAPI WFSFreeResult ( LPWFSRESULT lpResult);
3743HRESULT extern WINAPI WFSGetInfo ( HSERVICE hService, DWORD dwCategory, LPVOID lpQueryDetails, DWORD dwTimeOut, LPWFSRESULT * lppResult);
3744HRESULT extern WINAPI WFSAsyncGetInfo ( HSERVICE hService, DWORD dwCategory, LPVOID lpQueryDetails, DWORD dwTimeOut, HWND hWnd, LPREQUESTID lpRequestID);
3745BOOL extern WINAPI WFSIsBlocking ();
3746HRESULT extern WINAPI WFSLock ( HSERVICE hService, DWORD dwTimeOut, LPWFSRESULT * lppResult);
3747HRESULT extern WINAPI WFSAsyncLock ( HSERVICE hService, DWORD dwTimeOut, HWND hWnd, LPREQUESTID lpRequestID);
3748HRESULT extern WINAPI WFSOpen ( LPSTR lpszLogicalName, HAPP hApp, LPSTR lpszAppID, DWORD dwTraceLevel, DWORD dwTimeOut, DWORD dwSrvcVersionsRequired, LPWFSVERSION lpSrvcVersion, LPWFSVERSION lpSPIVersion, LPHSERVICE lphService);
3749HRESULT extern WINAPI WFSAsyncOpen ( LPSTR lpszLogicalName, HAPP hApp, LPSTR lpszAppID, DWORD dwTraceLevel, DWORD dwTimeOut, LPHSERVICE lphService, HWND hWnd, DWORD dwSrvcVersionsRequired, LPWFSVERSION lpSrvcVersion, LPWFSVERSION lpSPIVersion, LPREQUESTID lpRequestID);
3750HRESULT extern WINAPI WFSRegister ( HSERVICE hService, DWORD dwEventClass, HWND hWndReg);
3751HRESULT extern WINAPI WFSAsyncRegister ( HSERVICE hService, DWORD dwEventClass, HWND hWndReg, HWND hWnd, LPREQUESTID lpRequestID);
3752HRESULT extern WINAPI WFSSetBlockingHook ( XFSBLOCKINGHOOK lpBlockFunc, LPXFSBLOCKINGHOOK lppPrevFunc);
3753HRESULT extern WINAPI WFSStartUp ( DWORD dwVersionsRequired, LPWFSVERSION lpWFSVersion);
3754HRESULT extern WINAPI WFSUnhookBlockingHook ();
3755HRESULT extern WINAPI WFSUnlock ( HSERVICE hService);
3756HRESULT extern WINAPI WFSAsyncUnlock ( HSERVICE hService, HWND hWnd, LPREQUESTID lpRequestID);
3757HRESULT extern WINAPI WFMSetTraceLevel ( HSERVICE hService, DWORD dwTraceLevel);
3758CWA 16926-1:2015 (E)
3759145
3760/* restore alignment */
3761#pragma pack(pop)
3762#ifdef __cplusplus
3763} /*extern "C"*/
3764#endif
3765#endif /* __inc_xfsapi__h */
3766CWA 16926-1:2015 (E)
3767146
376816.2 XFSADMIN.H
3769/******************************************************************************
3770* *
3771* xfsadmin.h XFS-Administration and Support functions *
3772* *
3773* Version 3.30 (March 19 2015) *
3774* *
3775******************************************************************************/
3776#ifndef __INC_XFSADMIN__H
3777#define __INC_XFSADMIN__H
3778#ifdef __cplusplus
3779extern "C" {
3780#endif
3781#include <xfsapi.h>
3782/* be aware of alignment */
3783#pragma pack(push,1)
3784/* values of ulFlags used for WFMAllocateBuffer */
3785#define WFS_MEM_SHARE 0x00000001
3786#define WFS_MEM_ZEROINIT 0x00000002
3787/****** Support Functions ****************************************************/
3788HRESULT extern WINAPI WFMAllocateBuffer( ULONG ulSize, ULONG ulFlags, LPVOID * lppvData);
3789HRESULT extern WINAPI WFMAllocateMore( ULONG ulSize, LPVOID lpvOriginal, LPVOID * lppvData);
3790HRESULT extern WINAPI WFMFreeBuffer( LPVOID lpvData);
3791HRESULT extern WINAPI WFMGetTraceLevel ( HSERVICE hService, LPDWORD lpdwTraceLevel);
3792HRESULT extern WINAPI WFMKillTimer( WORD wTimerID);
3793HRESULT extern WINAPI WFMOutputTraceData ( LPSTR lpszData);
3794HRESULT extern WINAPI WFMReleaseDLL ( HPROVIDER hProvider);
3795HRESULT extern WINAPI WFMSetTimer ( HWND hWnd, LPVOID lpContext, DWORD dwTimeVal, LPWORD lpwTimerID);
3796/* restore alignment */
3797#pragma pack(pop)
3798#ifdef __cplusplus
3799} /*extern "C"*/
3800#endif
3801#endif /* __INC_XFSADMIN__H */
3802CWA 16926-1:2015 (E)
3803147
380416.3 XFSCONF.H
3805/******************************************************************************
3806* *
3807* xfsconf.h XFS - definitions for the Configuration functions *
3808* *
3809* Version 3.30 (March 19 2015) *
3810* *
3811******************************************************************************/
3812#ifndef __INC_XFSCONF__H
3813#define __INC_XFSCONF__H
3814#ifdef __cplusplus
3815extern "C" {
3816#endif
3817/******* Common **************************************************************/
3818#include <xfsapi.h>
3819/* be aware of alignment */
3820#pragma pack(push,1)
3821// following HKEY and PHKEY are already defined in WINREG.H
3822// so definition has been removed
3823// typedef HANDLE HKEY;
3824// typedef HANDLE * PHKEY;
3825/******* Value of hKey *******************************************************/
3826#define WFS_CFG_HKEY_XFS_ROOT ((HKEY)1)
3827#define WFS_CFG_HKEY_MACHINE_XFS_ROOT ((HKEY)2)
3828#define WFS_CFG_HKEY_USER_DEFAULT_XFS_ROOT ((HKEY)3)
3829/******* Values of lpdwDisposition *******************************************/
3830#define WFS_CFG_CREATED_NEW_KEY (0)
3831#define WFS_CFG_OPENED_EXISTING_KEY (1)
3832/******* Configuration Functions *********************************************/
3833HRESULT extern WINAPI WFMCloseKey ( HKEY hKey);
3834HRESULT extern WINAPI WFMCreateKey ( HKEY hKey, LPSTR lpszSubKey, PHKEY phkResult, LPDWORD lpdwDisposition);
3835HRESULT extern WINAPI WFMDeleteKey ( HKEY hKey, LPSTR lpszSubKey);
3836HRESULT extern WINAPI WFMDeleteValue ( HKEY hKey, LPSTR lpszValue );
3837HRESULT extern WINAPI WFMEnumKey ( HKEY hKey, DWORD iSubKey, LPSTR lpszName, LPDWORD lpcchName, PFILETIME lpftLastWrite);
3838HRESULT extern WINAPI WFMEnumValue ( HKEY hKey, DWORD iValue, LPSTR lpszValue, LPDWORD lpcchValue, LPSTR lpszData, LPDWORD lpcchData);
3839HRESULT extern WINAPI WFMOpenKey ( HKEY hKey, LPSTR lpszSubKey, PHKEY phkResult);
3840HRESULT extern WINAPI WFMQueryValue ( HKEY hKey, LPSTR lpszValueName, LPSTR lpszData, LPDWORD lpcchData);
3841HRESULT extern WINAPI WFMSetValue ( HKEY hKey, LPSTR lpszValueName, LPSTR lpszData, DWORD cchData);
3842/* restore alignment */
3843#pragma pack(pop)
3844#ifdef __cplusplus
3845} /*extern "C"*/
3846#endif
3847CWA 16926-1:2015 (E)
3848148
3849#endif /* __INC_XFSCONF__H */
3850CWA 16926-1:2015 (E)
3851149
385216.4 XFSSPI.H
3853/******************************************************************************
3854* *
3855* xfsspi.h XFS - SPI functions, types, and definitions *
3856* *
3857* Version 3.30 (March 19 2015) *
3858* *
3859******************************************************************************/
3860#ifndef __inc_xfsspi__h
3861#define __inc_xfsspi__h
3862#ifdef __cplusplus
3863extern "C" {
3864#endif
3865#include <xfsapi.h>
3866typedef HANDLE HPROVIDER;
3867#include <xfsconf.h>
3868#include <xfsadmin.h>
3869/* be aware of alignment */
3870#pragma pack(push,1)
3871/****** SPI functions ********************************************************/
3872HRESULT extern WINAPI WFPCancelAsyncRequest ( HSERVICE hService, REQUESTID RequestID);
3873HRESULT extern WINAPI WFPClose ( HSERVICE hService, HWND hWnd, REQUESTID ReqID);
3874HRESULT extern WINAPI WFPDeregister ( HSERVICE hService, DWORD dwEventClass, HWND hWndReg, HWND hWnd, REQUESTID ReqID);
3875HRESULT extern WINAPI WFPExecute ( HSERVICE hService, DWORD dwCommand, LPVOID lpCmdData, DWORD dwTimeOut, HWND hWnd, REQUESTID ReqID);
3876HRESULT extern WINAPI WFPGetInfo ( HSERVICE hService, DWORD dwCategory, LPVOID lpQueryDetails, DWORD dwTimeOut, HWND hWnd, REQUESTID ReqID);
3877HRESULT extern WINAPI WFPLock ( HSERVICE hService, DWORD dwTimeOut, HWND hWnd, REQUESTID ReqID);
3878HRESULT extern WINAPI WFPOpen ( HSERVICE hService, LPSTR lpszLogicalName, HAPP hApp, LPSTR lpszAppID, DWORD dwTraceLevel, DWORD dwTimeOut, HWND hWnd, REQUESTID ReqID, HPROVIDER hProvider, DWORD dwSPIVersionsRequired, LPWFSVERSION lpSPIVersion, DWORD dwSrvcVersionsRequired, LPWFSVERSION lpSrvcVersion);
3879HRESULT extern WINAPI WFPRegister ( HSERVICE hService, DWORD dwEventClass, HWND hWndReg, HWND hWnd, REQUESTID ReqID);
3880HRESULT extern WINAPI WFPSetTraceLevel ( HSERVICE hService, DWORD dwTraceLevel);
3881HRESULT extern WINAPI WFPUnloadService ( );
3882HRESULT extern WINAPI WFPUnlock ( HSERVICE hService, HWND hWnd, REQUESTID ReqID);
3883/* restore alignment */
3884#pragma pack(pop)
3885#ifdef __cplusplus
3886} /*extern "C"*/
3887#endif
3888#endif /* __inc_xfsspi__h */