Application Programming Interface (API)/Service Provider Interface (SPI)

WOSA

(Windowsä Open Services Architecture)

Extensions for Financial Services

A Client-Server Architecture for
Financial Enterprise Computing under Microsoft® Windows

Application Programming Interface (API)

Service Provider Interface (SPI)

–––––––––––––––––––

Programmer’s Reference

Revision 2.00

November 11, 1996

Developed by the members of the Banking Solutions Vendor Council


Table of Contents

1. Introduction
1.1 Background

1.2 Strategies

2. WOSA Extensions for Financial Services Overview
2.1 Architecture

2.2 API and SPI Summary

2.3 Device Classes

3. Architectural and Implementation Issues
3.1 The XFS Manager
3.2 Service Providers
3.2.1 Service Provider Functionality

3.2.2 Service Provider “Packaging”

3.3 Asynchronous, Synchronous and Immediate Functions
3.3.1 Asynchronous Functions

3.3.2 Synchronous Functions

3.3.3 Immediate Functions

3.4 Processing API Functions

3.5 Opening a session

3.6 Closing a Session

3.7 Configuration Information

3.8 Exclusive Service and Device Access
3.8.1 Lock Policy for Independent Devices

3.8.2 Compound Devices

3.9 Timeout

3.10 Function Status Return

3.11 Notification Mechanisms — Registering for Events

3.12 Application Processes, Threads and Blocking Functions

3.13 Memory Management

4. Application Programming Interface (API) Functions
4.1 WFSCancelAsyncRequest

4.2 WFSCancelBlockingCall

4.3 WFSCleanUp

4.4 WFSClose

4.5 WFSAsyncClose

4.6 WFSCreateAppHandle

4.7 WFSDeregister

4.8 WFSAsyncDeregister

4.9 WFSDestroyAppHandle

4.10 WFSExecute

4.11 WFSAsyncExecute

4.12 WFSFreeResult

4.13 WFSGetInfo

4.14 WFSAsyncGetInfo

4.15 WFSIsBlocking

4.16 WFSLock

4.17 WFSAsyncLock

4.18 WFSOpen

4.19 WFSAsyncOpen

4.20 WFSRegister

4.21 WFSAsyncRegister

4.22 WFSSetBlockingHook

4.23 WFSStartUp

4.24 WFSUnhookBlockingHook

4.25 WFSUnlock

4.26 WFSAsyncUnlock

5. Service Provider Interface (SPI) Functions
5.1 WFPCancelAsyncRequest

5.2 WFPClose

5.3 WFPDeregister

5.4 WFPExecute

5.5 WFPGetInfo

5.6 WFPLock

5.7 WFPOpen

5.8 WFPRegister

5.9 WFPSetTraceLevel

5.10 WFPUnloadService

5.11 WFPUnlock

6. Support Functions
6.1 WFMAllocateBuffer

6.2 WFMAllocateMore

6.3 WFMFreeBuffer

6.4 WFMGetTraceLevel

6.5 WFMKillTimer

6.6 WFMOutputTraceData

6.7 WFMReleaseDLL

6.8 WFMSetTimer

6.9 WFMSetTraceLevel

7. Configuration Functions
7.1 WFMCloseKey

7.2 WFMCreateKey

7.3 WFMDeleteKey

7.4 WFMDeleteValue

7.5 WFMEnumKey

7.6 WFMEnumValue

7.7 WFMOpenKey

7.8 WFMQueryValue

7.9 WFMSetValue

8. Data Structures
8.1 WFSRESULT

8.2 WFSVERSION

9. Messages
9.1 Command Completions and Events

9.1.1 Command Completion Messages

9.1.2 Event Messages

9.2 Timer Events

9.3 Device Status Changes

9.4 Undeliverable Messages

9.5 Application Disconnect

9.6 Hardware and Software Errors

9.7 Version Negotiation Failures

10. Error Codes

11. Appendix A - Planned Enhancements and Extensions
11.1 Event and System Management

12. Appendix B - Banking Solutions Vendor Council Contacts

13. Appendix C - Other WOSA Specifications and Information

14. Appendix D - C-Header files
14.1 XFSAPI.H

14.2 XFSADMIN.H

14.3 XFSCONF.H

14.4 XFSSPI.H


1. Introduction

This is revision 2.0 of the API/SPI specification for the Windows Open Services Architecture, Extensions for Financial Services (WOSA/XFS). The other relevant specifications are the service class specifications. These specifications are part of the Software Development Kit (SDK), which supplies the components and tools to allow the implementation of compliant applications and services. These specifications are distributed to the financial services community for continuing review and comment, to allow them to provide input to the ongoing enhancement of WOSA/XFS.

Release 2.0 extends the scope of WOSA/XFS to include both the self service/ATM environment as well as the branch environment. The new specification now fully supports cameras, deposit units, identification cards, PIN pads, sensors and indicator units, text terminals, cash dispenser modules and a wide variety of printing mechanisms.

The members of the Banking Solutions Vendor Council encourage banks and other financial service companies world-wide, as well as other technology suppliers, to get updated information on the status of the project, and to submit comments, questions and requests for the specification and SDK. This may be done via one of the council members or via the Microsoft web site :

www.microsoft.com/industry/bank.

The Banking Solutions Vendor Council is accepting applications for affiliate membership; interested parties should contact one of the council members or send email to bsvc@microsoft.com.


1.1 Background

The Banking Solutions Vendor Council, an organization of leading vendors of information technology to the financial services industry, was formally announced at the American Bankers Association National Operations and Automation Conference (NOAC) in Denver on May 18, 1992. Revision 1.0 of this specification was released at NOAC in New Orleans on May 24, 1993.

The current charter members of the Banking Solutions Vendor Council are:

  • Digital Equipment Corporation
  • Ing. C. Olivetti & C. S.p.A.
  • ICL Plc
  • Siemens Nixdorf Informationssysteme AG
  • Microsoft Corporation
  • Retail Management Solutions
  • NCR Corporation
  • Unisys Corporation
  • Nexus Software Incorporated

The Banking Solutions Vendor Council has held many multi-vendor development meetings, in addition to numerous additional hours invested in defining this specification for the WOSA Extensions for Financial Services.


1.2 Strategies

The following key strategies have been adopted by the Banking Solutions Vendor Council to implement the objectives defined above:

  • Use the Microsoft® Windows™ operating systems family as the strategic platform for client-server computing.

  • Adopt the Windows Open Service Architecture (WOSA) family of open interfaces and associated services for the integration of Windows and Windows-based applications into enterprise computing solutions.

  • Utilize existing WOSA elements wherever possible, defining new elements, or extensions to existing elements, only when no suitable candidate(s) exist in the evolving WOSA family that meet the needs of financial services computing. In all cases, existing formal or de facto standards will be utilized to the maximum degree possible.

  • Enhance WOSA with the Extensions for Financial Services to meet the special requirements of financial applications for access to services and devices.

  • Maintain the highest possible level of compatibility of both the API and SPI specifications as the Extensions for Financial Services evolve to include new and enhanced capabilities.

WOSA comprises a family of stable, open-ended interfaces for enterprise computing environments that hides system complexities from users and application developers. WOSA allows the integration of Windows and Windows-based applications seamlessly with all the services and enterprise capabilities that application developers and users need. It includes such interfaces as:

  • Open Database Connectivity (ODBC) for standard access to databases,

  • Messaging Application Programming Interface (MAPI) for standard access to messaging services, and

  • communications support, including Windows SNA, RPC, and Sockets.

Each of the elements of WOSA includes a set of Application Program Interfaces (APIs) and Service Provider Interfaces (SPIs), with associated supporting software. The architecture of WOSA is shown below:

For additional information on WOSA, see the WOSA Backgrounder (Microsoft part number 098-34801).

The Extensions for Financial Services extend WOSA by defining a Windows-based client-server architecture for financial applications. The extensions (as with the other elements of WOSA) include a set of APIs and SPIs common to multiple financial applications.

The WOSA Extensions for Financial Services are planned to include specifications for access to financial peripherals (such as passbook/journal/receipt printers, magnetic card readers/writers, PIN pads, etc.), financial transaction messaging and management, as well as related services for financial networks such as network and systems management and security. All these capabilities are specified for access from the familiar, consistent Microsoft Windows user interface and programming environments. Whenever possible, the capabilities will be incorporated into the family of standard WOSA elements, and will utilize existing formal and de facto standards.


2. WOSA Extensions for Financial Services Overview

A 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.

The 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.

The specification is intended to be usable within all implementations and versions of the Windows operating systems, from Windows version 3.1, Windows for Workgroups version 3.1 and the initial versions of Windows NT, and onwards. It thus provides for both 16 and 32 bit operating environments (operating under the Win32s subsystem in 16 bit environments).

Although the WOSA Extensions for Financial Services define a general architecture for access to service providers from Windows-based applications, the initial focus of the Banking Solutions Vendor Council 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.


2.1 Architecture

The architecture of the WOSA Extensions for Financial Services (WOSA/XFS) system is shown below.

Figure 2.1 — WOSA Extensions for Financial Services Architecture

The applications communicate with service providers, via the WOSA 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).

The common deliverable in all implementations of this WOSA Extensions for Financial Services specification is the WOSA Extensions for Financial Services Manager, which maps the specified API to the corresponding SPI, then routes this request to the appropriate service provider. The 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.

The 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.

The primary functions of the service providers are to:

  • Translate generic (e.g., forms-based) service requests to service-specific commands.

  • 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.

  • Arbitrate access by multiple applications to a single service or device, providing exclusive access when requested.

  • Manage the hardware interfaces to services or devices.

  • 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.

The system design supports solution of complex problems, often not addressed by current systems, by providing for maximum flexibility in all its capabilities:

  • Multiple service providers, developed by multiple vendors, can coexist in a single system and in a network.

  • 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).

  • 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.

  • 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.

  • The architecture is designed to provide a framework for future development of network and system monitoring, measurement, and management.

Note 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.

Example

Figure 2.2 below shows a WOSA/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.

Figure 2.2 — A WOSA/XFS architecture example for a branch office banking system

It should also be noted that one vendor's service providers are not necessarily compatible with another vendor's, as shown 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.


2.2 API and SPI Summary

Sections 5 through 7 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 preprocess the command, then redirect the derived commands to the operating system's printing services. In other implementations, the printer might be supported entirely by WOSA/XFS service mechanisms, and not use the operating system printing services in any way.

The API is structured as sets of:

· Basic functions, such as StartUp/CleanUp, Open/Close, Lock/Unlock, and Execute, that are common to all the WOSA Extensions for Financial Services device/service classes,

· Administration functions, such as device initialization, reset, suspend or resume, used for managing devices and services, and

· 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.

To 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.

The 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.

A typical scenario showing the usage of the APIs is shown below. This example illustrates the functions used to print a form.

· StartUp (connects the application to the XFS Manager, including version negotiation)

· Open (establishes a session between the application and the service provider)

· Register (specifies the messages that the application should receive from the service provider)

· Lock (obtains exclusive access to the service by the application)

  • multiple Execute functions, passing one or more specific commands:

    ú Print_Form

    ú etc.

· Unlock (releases exclusive access to the service by the application)

· Deregister (specifies that the application should no longer receive messages from the service provider)

· Close (ends the session between the application and the service provider)

· CleanUp (disconnects the application from the XFS Manager)

Note 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).


2.3 Device Classes

The classes of devices that belong to the second version of the WOSA Extensions for Financial Services are described in the separate Service Class Definition Document.


3. Architectural and Implementation Issues

The remainder of this document provides the technical specifications for the Windows Open Services Architecture (WOSA) Extensions for Financial Services (referred to hereafter as “WOSA/XFS” for brevity).

In this specification, the functions of the WOSA/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 BSVC members for WOSA/XFS implementations will be to provide this peripheral device access capability, the examples used relate primarily to device control and physical input/output.

The 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 a WOSA/XFS implementation, providing access to financial devices and services for Windows-based applications.

The 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. Similarly, any service provider that conforms to the SPI definition can work with a range of conformant applications.

The specification is intended to be usable within all implementations and versions of the Windows operating systems, beginning with versions 3.1 of Windows, Windows for Workgroups, and Windows NT, and all future versions of these operating systems. In the 16 bit operating systems (Windows 3.x, Windows for Workgroups 3.x) the elements of an XFS subsystem (applications, XFS Manager, and service providers) will be 32 bit modules, implemented using the Win32s API. The specification thus provides for the development and deployment of 32 bit applications on both 16 and 32 bit operating systems, and the WOSA/XFS software development kit will include versions of the XFS Manager and associated programming aids that will allow development of applications and service providers for both environments.

For clarity, three prefixes are used in naming the function interfaces in WOSA/XFS:

Function type: Prefix Functions called by Functions provided by
  • API functions: WFS...
    (WOSA Financial Services)
 · Applications
  • XFS Manager (and typically passed through to WFP functions)
  • SPI functions: WFP...
    (WOSA Financial Services Providers)
 · XFS Manager
  • Service providers
  • Support/Configuration functions: WFM...
    (WOSA Financial Services Manager)
 · Service providers
· Applications
  • XFS Manager


3.1 The XFS Manager

The XFS Manager provides overall management of the WOSA/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.

The 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 3.7 and 7 for discussions of configuration information access and management.

The XFS Manager also provides the Support Functions (WFM...) defined in Section 6 and the Configuration Functions (also WFM...) defined in Section 7.

Before an application is allowed to utilize any of the services managed by the WOSA/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 WOSA/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.


3.2 Service Providers

Each WOSA/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.

The following sections describe the functionality and packaging of service providers.


3.2.1 Service Provider Functionality

The primary functions of WOSA/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.

  • 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.

  • 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.

  • 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.

  • 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.

  • 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, as in other WOSA components such as the Windows Sockets or Windows SNA APIs.

  • 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 3.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.


3.2.2 Service Provider “Packaging”

WOSA/XFS service providers can be “packaged” into DLLs in a variety of ways:

  • One service provider per DLL; for example, a vendor might produce a journal printer DLL, a receipt printer DLL, a cash dispenser DLL, etc.

  • Multiple service providers per DLL; for example a vendor might produce a DLL which contains the service providers for all XFS-compliant printers.

  • All service providers for a specific vendor in a single DLL.


3.3 Asynchronous, Synchronous and Immediate Functions

Windows and WOSA/XFS are built on an event-driven, asynchronous model. However, the WOSA/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).

Each WOSA/XFS API function operates in one of three synchronization modes: asynchronous, synchronous or immediate. These are described in the following sections.

Note that the SPI is purely an asynchronous interface, so all SPI functions are either asynchronous or immediate; there are no synchronous SPI functions.

See Sections 4 and 5 for a summary of the API and SPI functions and their synchronization modes.


3.3.1 Asynchronous Functions

Asynchronous 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:

  • The application calls the XFS Manager.

  • The XFS Manager generates a sequence number, the RequestID, assigns it to the request, and calls the service provider.

  • The service provider schedules the request for deferred processing and immediately returns to the XFS Manager.

  • The XFS Manager returns the RequestID to the application, with a status indicating that the request has been initiated and is being processed.

  • At some point, the service provider processes the deferred request.

  • 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.


3.3.2 Synchronous Functions

Synchronous 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.

If 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 3.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 WOSA/XFS call outstanding at any one time. See Section 3.12 for additional discussion of the management of synchronous functions, including replacement of the default message loop.

The processing of a synchronous request (e.g., WFSExecute) is as follows:

  • The application calls the XFS Manager.

  • 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.

  • The service provider schedules the request for deferred processing and immediately returns to the XFS Manager.

  • The XFS Manager simulates synchronous processing as described above and in Section 3.12.

  • At some point, the service provider processes the deferred request.

  • 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.

  • The XFS Manager unpacks the information from the completion message into the appropriate parameters, and returns them to the application, unblocking the original application request.


3.3.3 Immediate Functions

These 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:

  • Processed entirely by the XFS Manager, which returns immediately to the application. Examples include WFSStartUp, and WFSSetBlockingHook.

  • 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.


3.4 Processing API Functions

When an application calls a WOSA/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 5 for the mapping of API functions to SPI functions.

· The function is converted by the XFS Manager directly into the corresponding SPI function (e.g., WFSAsyncRegister).

· The XFS Manager performs some preprocessing and then converts the function into the corresponding SPI function (e.g., WFSAsyncExecute).

· 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.

· 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).

· The function is completely processed inside the XFS Manager (e.g., WFSIsBlocking, WFSSetBlockingHook).

Service providers (and sometimes applications) call the XFS Manager for the support functions defined in Section 6 and for the configuration functions defined in Section 7.


3.5 Opening a session

Once 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 WOSA/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.

Note that applications may optionally choose to explicitly manage the concept of “application identity” when they need to use interdependent compound devices (see Section 3.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 WOSA/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 3.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.

The actions performed by the XFS Manager on an open are as follows:
  • 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.

  • Loads the DLL containing the requested service provider, if it is not already loaded.

  • Performs pre-processing and translation as necessary, depending on whether the synchronous or asynchronous open API has been issued.

  • 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.

  • Calls the service provider's WFPOpen function, passing the parameters needed.

The service provider does the following:

  • 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.
  • Retrieves the configuration information.

  • Asynchronously establishes a session with the service specified in the configuration on the specified workstation, if necessary, relying on the transport facilities provided.

  • 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.

Note that even if the service is locked by another application, the open function succeeds, as defined in Section 3.8, “Exclusive Service and Device Access.”

An application programmer has at least two obvious choices as to when to perform the WFSOpen (and the complementary WFSClose) of the services it utilizes:

  • Open the services during application initialization, keep them open, and close them during application shutdown.

  • Perform the open each time the service is required, utilize it, and immediately close it.

Each 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 WOSA/XFS subsystem returns a service handle which must be used for all subsequent communication with the service.

Note 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.

Furthermore, 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.


3.6 Closing a Session

When an application no longer requires the use of a particular service, it issues a WFSClose or WFSAsyncClose request. The WOSA/XFS subsystem then closes that session as follows:

  • The XFS Manager calls the service provider's WFPClose function.

  • 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.

  • At some point, the service provider processes the deferred close request, communicating with the service as necessary to accomplish the request.

  • Requests that were issued by the application before the close are executed.

  • 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 3.8).

  • The service cleans up its administrative information (removes WFSRegister entries etc.).

If the WOSA/XFS subsystem loses connection to an application, it closes the session as described above, and:

  • An “application disconnect” event (SYSTEM_EVENT class) is generated.

  • 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).

Note that it is required that some application have registered for system events, or these events are effectively not reported.


3.7 Configuration Information

The 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.

The 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 7, for portability across Windows platforms.

It 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.

These functions are used by service providers and applications to write and retrieve the configuration information for a WOSA/XFS subsystem, which is stored in a hierarchical structure called the XFS configuration registry. The structure and the functions are based on the Win32 Registry architecture and API functions, and are implemented in Windows NT and future versions of Windows using the Registry and the associated functions. For Win32s-based implementations on Windows 3.1 and Windows for Workgroups, a subset of the functionality described here will be available; the SDK will define this subset.

Each 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. The structure is as follows:

(1) The top level is the root node for the WOSA/XFS subsystem. Its key name is WOSA/XFS_ROOT (it is a subkey of HKEY_CLASSES_ROOT in the Win32 Registry).

(2) The second level contains at least three keys: XFS_MANAGER, LOGICAL_SERVICES, and SERVICE_PROVIDERS. Other keys (e.g., PHYSICAL_SERVICES) may be defined and used as required.

(3) Below the XFS_MANAGER key there are values and/or keys for information that the XFS Manager creates and uses.

(4) Below the LOGICAL_SERVICES key there is a key for each logical service defined for the system on which the registry resides; the key names are the logical service names (the lpszLogicalName parameter of the WFSOpen, WFSAsyncOpen and WFPOpen functions). Since there is only one registry per workstation, this enforces the requirement that logical service names are unique within at least the workstation.

(5) Below the SERVICE_PROVIDERS key there is a key for each service provider defined for the system.

The 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. The third level contains the values and keys that 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.

The figure below illustrates the structure of the configuration registry:

The XFS Manager key has the following optional values:

  • TraceFile the name of the file containing trace data. If this value is not set in the configuration, trace data is written to the default file path\name C:\XFSTRACE.LOG.

  • ShareFilename the name of the memory mapped file used by the memory management functions of the XFS Manager.

  • ShareFilesize the size of the memory mapped file used by the memory management functions of the XFS Manager.

Some additional values could be also defined in the WOSA/XFS SDK release notes. Please refer to the related document for more information.

Every logical service key has three mandatory values:

  • class the service class of the logical service; (see the Service Class Definition Document for the standard values)

  • type the service type of the logical service; the standard values for service type
    are defined in the WOSA/XFS software development kit SDK

  • provider the name of the service provider that provides the logical service
    (the key name of the corresponding service provider key)

A service provider key also has three mandatory values:

  • dllname the name of the file containing the service provider DLL

  • vendor_name the name of the supplier of this service provider

  • version the version number of this service provider

An example of the content of the configuration information for an actual system is shown below. See Section 7 for the definitions of the configuration functions.

WOSA/XFS Registry Root

Second Level Keys

Third Level Keys (or values)

Values

WOSA/XFS_ROOT

XFS_MANAGER

TraceFile=<path-name>\<trace-file- name>

ShareFilename=<path-name>\ <share-file-name>

ShareFilesize=<file size in bytes>

LOGICAL_SERVICES

Passbook1

class=PTR

type=PASSBOOK

provider=Passbook_Receipt

operator_station=1

input_paper_source=upper

< other optional values >

Receipt1

class=PTR

type=RECEIPT

provider=Passbook_Receipt

< optional values >

Journal1

class=PTR

type=JOURNAL

provider=Journal

< optional values >

ATSafe1

class=CDM

type=ATSAFE

provider=Cash_Dispenser

< optional values >

< other srvcs >

SERVICE_PROVIDERS

Cash_Dispenser

dllname=CASHDISP.DLL

vendor_name=Big Bank , Inc.

version=3.50

< optional values >

Passbook_Receipt

dllname=RPPRNTR.DLL

vendor_name=Code “R Us, Ltd.

version=1.30

< optional values >

Journal

dllname=JOURNAL.DLL

vendor_name=Nobugs Systems

version=2.01

< optional values >

< other prvdrs >

< other keys >


3.8 Exclusive Service and Device Access

This section describes how application access to services and devices is handled by WOSA/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.

Typically, 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.

An 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.

Applications must use appropriate techniques to avoid deadlock when locking multiple services, typically by making use of the timeout parameter in the lock functions.

Also, 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.

The 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:

  • Non-deferred: Requests that can be processed completely by a service as soon as they arrive (e.g., WFPOpen, WFPRegister and most WFPGetInfo calls.

  • 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).

  • Lock: WFPLock calls.

The 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.


3.8.1 Lock Policy for Independent Devices

The 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.

Service state: UNLOCKED

  • Non-deferred requests are processed on arrival.

  • Deferred requests are placed in the deferred queue and processed FIFO.

  • When a WFPLock request arrives:
    • The lock request is placed in the lock queue.

    • The service state changes to LOCK_PENDING.

Service state: LOCK_PENDING

  • All requests in the deferred queue that arrived before the pending lock request are processed FIFO; after all are processed, the 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.

  • When a lock request has been granted:
    • The service state changes to LOCKED.

    • 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.)

Service state: LOCKED

  • Arriving requests (except lock requests) are handled as follows:
    • Non-deferred requests are processed on arrival.

    • Deferred requests that are not WFPExecute requests are placed in the deferred queue.

    • WFPExecute requests from the owner of the lock are placed in the deferred queue.

    • WFPExecute requests that are not from the owner of the lock are rejected (with error code WFS_ERR_LOCKED).

    • 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.)

    • WFPUnlock and WFPClose requests that are not from the owner of the lock are treated as non-deferred requests, i.e., processed on arrival.

  • The deferred queue is processed FIFO.

  • When a WFPLock request arrives:
    • If it is from the owner of the lock, it is granted.

    • If it is not from the owner of the lock, it is placed in the lock queue.

  • 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:
    • If the lock queue is not empty, the service state changes to LOCK_PENDING.

    • If the lock queue is empty, the service state changes to UNLOCKED.

Note 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.


3.8.2 Compound Devices

Compound devices are very common in the financial services industry. For the purposes of this discussion, there are three types of compound devices:

  • Two or more separate logical devices that share a physical housing (or perhaps some other attribute), but function completely independently of one another

  • 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

  • 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

The 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 specification.

The 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 3.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.

Note that an application can also determine whether a device is compound by using the device capabilities query function of WFSGetInfo.

There are many different ways in which programmers can make use of multiple threads and/or processes in financial applications. Each WOSA/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 WOSA/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.

In 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 3.5 for additional discussion of this topic.

The 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:

Service state: LOCK_PENDING

  • When a lock request has been granted to one of a set of related logical services:
    • 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.

    • Any lock request from the owner for one of the reserved services is granted on arrival.

    • Lock requests that are not from the owner of the reserved devices are placed in the lock queue.

Service state: LOCKED

  • Any lock request from the owner for one of the reserved services is granted on arrival.

  • Lock requests that are not from the owner of the reserved devices are placed in the lock queue.

  • 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.

  • 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.


3.9 Timeout

There are two fundamentally different time domains in a system, each having a different implication on the concept of timeout:

  • “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)

  • “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)

In WOSA/XFS systems, the service manages the latter, without needing any input from the application, since it “knows” the charactistics 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.


3.10 Function Status Return

When a WOSA/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.

The XFS Manager and the service providers return status from a function call, in the form of an hResult result handle, in two manners:

  • By returning an hResult value as the function return.

  • By posting a completion message to the window specified in the request. The message contains a pointer to a structure that includes the hResult.

The mechanism depends on the category of function being processed, as follows:

  • 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.

  • Asynchronous API

    Since the processing is performed in a number of steps, as described earlier, return status is generated at a number of levels:

    • The service provider performs any validations which can be processed immediately.

    • If an error is detected, the service provider returns the hResult to the XFS Manager, which immediately returns it to the application.

    • 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.

    • 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.

  • Synchronous API
    • 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.

    • If an error is detected, the service provider returns the hResult to the XFS Manager, which immediately returns it to the application.

    • 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.

    • 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.


3.11 Notification Mechanisms — Registering for Events

The 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.

There are four classes of events:

  • SERVICE_EVENTS

  • USER_EVENTS

  • SYSTEM_EVENTS

  • EXECUTE_EVENTS

For 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, specifying the service identified by the hService handle. The events are generated when:

  • the service status changes (SERVICE_EVENTS), e.g., a printer is suspended or is no longer available.

  • 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.

  • 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.

The EXECUTE_EVENTS class is different from the other three. These are events which occur as a normal part of processing an WFSExecute 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 mag 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. 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.

The 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.

An application requests registration for more than one event class in a single call by using a logical ‘OR’:
hr = WFSRegister( hService,USER_EVENTS|SERVICE_EVENTS,hWnd );

Note 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.

To 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.

Although 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.

Note 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.


3.12 Application Processes, Threads and Blocking Functions

An application process contains one or more threads of execution. The WOSA/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.”

Within 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.

When a Windows message is received for a thread for which a blocking operation is in progress, the thread is not permitted to issue any WOSA/XFS calls during the processing of the message, other than the two specific functions provided to assist the programmer in this situation:

· WFSIsBlocking determines whether or not a blocking call is in progress.

· WFSCancelBlockingCall cancels a blocking call in progress.

Any other WOSA/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.

Although 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 WOSA/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 WOSA/XFS functions that may be called from a blocking routine are WFSIsBlocking and WFSCancelBlockingCall. The asynchronous versions of the WOSA/XFS functions must be used to allow an application to continue processing while an operation is in progress.

This 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.

Therefore, 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.

In the WOSA/XFS implementation in a single-threaded environment, the blocking function operates as follows. When an application requests a blocking WOSA/XFS API function, the XFS Manager initiates the requested function and then enters a loop which is equivalent to the following pseudocode:
for(;;) {
 /* flush messages for good user response */
 DefaultBlockingHook();
 /* check for WFSCancelBlockingCall() */
 if( operation_cancelled() )
  break;
 /* check to see if operation completed */
 if( operation_complete() )
  break;   /* normal completion */
}

The DefaultBlockingHook routine is equivalent to:
BOOL DefaultBlockingHook(void) {
 MSG msg;
 BOOL ret;
 /* Wait for the next message */

ret = GetMessage(&msg, NULL, 0, 0);

 if( (int) ret != -1 ) {
  TranslateMessage(&msg);
  DispatchMessage(&msg);
 }
 /* FALSE if we got a WM_QUIT message */
 return( ret );
}

In 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.

In 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 3.5 and 3.8.2 for additional discussion of this concept.


3.13 Memory Management

WOSA/XFS 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 8.1) that is always used to pass information to the applications from the services.

Most 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:

  • Asynchronous API functions
    The application receives the structure from the service provider via a completion message, and is responsible for deallocation.

  • 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.

  • 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.

Four 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:

  • a linear allocation policy

  • a linked allocation policy

Linear 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.

Linked 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.

The 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.

NOTE:

Applications 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.

The 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.

WFSRESULT * lpResultBuffer;

// service provider allocates a WFSResult buffer structure

result = WFMAllocateBuffer(sizeof(WFSRESULT), ulMemFlags, &lpResultBuffer);
·
·
·
// service provider allocates additional memory

hr = WFMAllocateMore(evenMoreMemory, lpResultBuffer, &lpResultBuffer->lpBuffer);
·
·
·

Once 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:

// application deallocates the structure when it is finished with it

hr = WFSFreeResult(lpResultBuffer); // frees both the result buffer and              // any additional buffers

NOTE:

When 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.


4. Application Programming Interface (API) Functions

The functions defined by the WOSA/XFS API are divided into:

· Basic functions that are common to all classes of financial services.

· Administration functions, used for the special purpose of administering services.

· 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).

The 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.

The 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.

The administration functions have not yet been fully defined; they are outlined in Appendix A.2 - Planned Enhancements and Extensions.

The service-specific commands are defined in separate specifications–one for each service class.

The table below summarizes the WOSA/XFS API functions, and the sections in which they are defined.

Section Function Mode Description
WFSCancelAsyncRequest Immediate Cancel an outstanding asynchronous request
WFSCancelBlockingCall Immediate Cancel an outstanding blocking operation
4.3 WFSCleanUp Synchronous Terminate a connection between an application
and the XFS Manager
WFSClose Synchronous Close a session between an application and a service provider
WFSAsyncClose Asynchronous The asynchronous version of WFSClose
WFSCreateAppHandle Immediate Create a new application handle to be used in a subsequent WFSOpen call
WFSDeregister Synchronous Disable monitoring of a class of events by an application
WFSAsyncDeregister Asynchronous The asynchronous version of WFSDeregister
WFSDestroyAppHandle Immediate Destroy the specified application handle
WFSExecute Synchronous Send service-specific commands to a service provider
WFSAsyncExecute Asynchronous The asynchronous version of WFSExecute
WFSFreeResult Immediate Request the XFS Manager to free a result buffer
WFSGetInfo Synchronous Retrieve service-specific information from a service provider
WFSAsyncGetInfo Asynchronous The asynchronous version of WFSGetInfo
WFSIsBlocking Immediate Determine if a blocking call is in progress
WFSLock Synchronous Establish exclusive control by an application of a service
WFSAsyncLock Asynchronous The asynchronous version of WFSLock
WFSOpen Synchronous Open a session between an application and a service provider
WFSAsyncOpen Asynchronous The asynchronous version of WFSOpen
WFSRegister Synchronous Enable monitoring of a class of events by an application
WFSAsyncRegister Asynchronous The asynchronous version of WFSRegister
WFSSetBlockingHook Immediate Install an application-specific blocking routine
WFSStartUp Immediate Initiate a connection between an application and the XFS Manager
WFSUnhookBlockingHook Immediate Restore the default blocking routine
WFSUnlock Synchronous Release exclusive control by an application of a service
WFSAsyncUnlock Asynchronous The asynchronous version of WFSUnlock


4.1 WFSCancelAsyncRequest

HRESULT WFSCancelAsyncRequest( hService, RequestID )

Cancels the specified (or every) asynchronous request being performed on the specified service, before its (their) completion.

Parameters HSERVICE hService

Handle to the service as returned by WFSOpen or WFSAsyncOpen.

REQUESTID RequestID

The request identifier for the request to be canceled, as returned by the original function call (NULL to cancel all).

Mode Immediate

Comments If the RequestID parameter is set to NULL, the command will cancel all asynchronous requests that are in progress using the specified hService.

A 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.

The 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.

Error Codes If the function return is not WFS_SUCCESS, it is one of the following error conditions:

WFS_ERR_CONNECTION_LOST
The connection to the service is lost.
WFS_ERR_INTERNAL_ERROR
An internal inconsistency or other unexpected error occurred in the WOSA/XFS subsystem.
WFS_ERR_INVALID_HSERVICE
The hService parameter is not a valid service handle.
WFS_ERR_INVALID_REQ_ID
The RequestID parameter does not correspond to an outstanding request on the service.
WFS_ERR_NOT_STARTED
The application has not previously performed a successful WFSStartUp.
WFS_ERR_OP_IN_PROGRESS
A blocking operation is in progress on the thread; only WFSCancelBlockingCall and WFSIsBlocking are permitted at this time.

See also WFSAsyncExecute


4.2 WFSCancelBlockingCall

HRESULT WFSCancelBlockingCall( dwThreadID )

Cancels a blocking operation for the specified thread, if one is in progress.

Parameters DWORD dwThreadID

Identifies the thread for which the blocking operation is to be canceled; a NULL value indicates the calling thread.

Mode Immediate

Comments 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 WOSA/XFS functions allowed with respect to a thread when it has a blocking call in progress.

The application that issued the blocking call receives a WFS_ERR_CANCELED return code if the operation is successfully canceled.

The 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.

Note: 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.

Error Codes If the function return is not WFS_SUCCESS, it is the following error condition:

WFS_ERR_CONNECTION_LOST
The connection to the service is lost.
WFS_ERR_INTERNAL_ERROR
An internal inconsistency or other unexpected error occurred in the WOSA/XFS subsystem.
WFS_ERR_NO_BLOCKING_CALL
There is no outstanding blocking call for the specified thread.
WFS_ERR_NO_SUCH_THREAD
The specified thread does not exist.
WFS_ERR_NOT_STARTED
The application has not previously performed a successful WFSStartUp.

See also WFSSetBlockingHook, WFSIsBlocking, WFSCancelAsyncRequest


4.3 WFSCleanUp

HRESULT WFSCleanUp( )

Disconnects an application from the XFS Manager.

Parameters None

Mode Synchronous

Comments The WFSCleanUp call indicates disconnection of a WOSA/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 WOSA/XFS function other than WFSStartUp will fail.

Error Codes If the function return is not WFS_SUCCESS, it is one of the following error conditions:

WFS_ERR_INTERNAL_ERROR
An internal inconsistency or other unexpected error occurred in the WOSA/XFS subsystem.
WFS_ERR_NOT_STARTED
The application has not previously performed a successful WFSStartUp.
WFS_ERR_OP_IN_PROGRESS
A blocking operation is in progress on the thread; only WFSCancelBlockingCall and WFSIsBlocking are permitted at this time.

See also WFSStartUp


4.4 WFSClose

HRESULT WFSClose( hService )

Terminates 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.

Parameters HSERVICE hService

The 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.

Mode Synchronous

Comments 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.

Error 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.

WFS_ERR_CANCELED
The request was canceled by WFSCancelBlockingCall.
WFS_ERR_CONNECTION_LOST
The connection to the service is lost.
WFS_ERR_INTERNAL_ERROR
An internal inconsistency or other unexpected error occurred in the WOSA/XFS subsystem.
WFS_ERR_INVALID_HSERVICE
The hService parameter is not a valid service handle.
WFS_ERR_NOT_STARTED
The application has not previously performed a successful WFSStartUp.
WFS_ERR_OP_IN_PROGRESS
A blocking operation is in progress on the thread; only WFSCancelBlockingCall and WFSIsBlocking are permitted at this time.

See also WFSAsyncClose, WFSOpen, WFSDeregister


4.5 WFSAsyncClose

HRESULT WFSAsyncClose( hService, hWnd, lpRequestID )

Terminates 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.

Parameters HSERVICE hService

The service handle returned by WFSOpen or WFSAsyncOpen. Matches the close request to the open request, allowing an application to maintain several "open sessions" simultaneously.

HWND hWnd

The window handle which is to receive the completion message for this request.

LPREQUESTID lpRequestID

Pointer to the request identifier for this request (returned parameter).

Mode Asynchronous

Comments See WFSClose.

The 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 3.13.

Messages WFS_CLOSE_COMPLETE

Error 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:

WFS_ERR_CONNECTION_LOST
The connection to the service is lost.
WFS_ERR_INTERNAL_ERROR
An internal inconsistency or other unexpected error occurred in the WOSA/XFS subsystem.
WFS_ERR_INVALID_HSERVICE
The hService parameter is not a valid service handle.
WFS_ERR_INVALID_HWND
The hWnd parameter is not a valid window handle.
WFS_ERR_INVALID_POINTER
A pointer parameter does not point to accessible memory.
WFS_ERR_NOT_STARTED
The application has not previously performed a successful WFSStartUp.
WFS_ERR_OP_IN_PROGRESS
A blocking operation is in progress on the thread; only WFSCancelBlockingCall and WFSIsBlocking are permitted at this time.

The following error condition can be returned via the asynchronous command completion message, as the hResult from the WFSRESULT structure.

WFS_ERR_CANCELED
The request was canceled by WFSCancelAsyncRequest.
WFS_ERR_INTERNAL_ERROR
An internal inconsistency or other unexpected error occurred in the WOSA/XFS subsystem.

See also WFSOpen, WFSDeregister


4.6 WFSCreateAppHandle

HRESULT WFSCreateAppHandle( lphApp )

Requests a new, unique application handle value.

Parameters LPHAPP lphApp

A pointer to the application handle to be created (returned parameter).

Mode Immediate

Comments 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 WOSA/XFS subsystem. See Sections 3.5 and 3.8.2 for additional discussion.

Error Codes If the function return is not WFS_SUCCESS, it is the following error condition.

WFS_ERR_INTERNAL_ERROR
An internal inconsistency or other unexpected error occurred in the WOSA/XFS subsystem.
WFS_ERR_INVALID_POINTER
A pointer parameter does not point to accessible memory.
WFS_ERR_NOT_STARTED
The application has not previously performed a successful WFSStartUp.

See also WFSDestroyAppHandle, WFSOpen, WFSAsyncOpen


4.7 WFSDeregister

HRESULT WFSDeregister( hService, dwEventClass, hWndReg )

Discontinues 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.

Parameters HSERVICE hService

Service 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.

DWORD dwEventClass

The 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.

HWND hWndReg

The 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.

Mode Synchronous

Comments The functions of a WFSDeregister request are performed automatically if a WFSClose is issued without a previous WFSDeregister.

See section 3.11 for a description of the classes of events that may be monitored.

Error Codes If the function return is not WFS_SUCCESS, it is one of the following error conditions:

WFS_ERR_CANCELED
The request was canceled by WFSCancelBlockingCall.
WFS_ERR_CONNECTION_LOST
The connection to the service is lost.
WFS_ERR_INTERNAL_ERROR
An internal inconsistency or other unexpected error occurred in the WOSA/XFS subsystem.
WFS_ERR_INVALID_EVENT_CLASS
The dwEventClass parameter specifies one or more event classes not supported by the service.
WFS_ERR_INVALID_HSERVICE
The hService parameter is not a valid service handle.
WFS_ERR_INVALID_HWNDREG
The hWndReg parameter is not a valid window handle.
WFS_ERR_NOT_REGISTERED
The specified hWndReg window was not registered to receive messages for any event classes.
WFS_ERR_NOT_STARTED
The application has not previously performed a successful WFSStartUp.
WFS_ERR_OP_IN_PROGRESS
A blocking operation is in progress on the thread; only WFSCancelBlockingCall and WFSIsBlocking are permitted at this time.

See also WFSRegister, WFSClose


4.8 WFSAsyncDeregister

HRESULT WFSAsyncDeregister( hService, dwEventClass, hWndReg, hWnd, lpRequestID )

Discontinues 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.

Parameters HSERVICE hService

Service 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.

DWORD dwEventClass

The 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.

HWND hWndReg

The 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.

HWND hWnd

The window handle which is to receive the completion message for this request.

LPREQUESTID lpRequestID

Pointer to the request identifier for this request (returned parameter).

Mode Asynchronous

Comments See WFSDeregister.

The 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 3.13.

Messages WFS_DEREGISTER_COMPLETE

Error 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:

WFS_ERR_CONNECTION_LOST
The connection to the service is lost.
WFS_ERR_INTERNAL_ERROR
An internal inconsistency or other unexpected error occurred in the WOSA/XFS subsystem.
WFS_ERR_INVALID_EVENT_CLASS
The dwEventClass parameter specifies one or more event classes not supported by the service.
WFS_ERR_INVALID_HSERVICE
The hService parameter is not a valid service handle.
WFS_ERR_INVALID_HWND
The hWnd parameter is not a valid window handle.
WFS_ERR_INVALID_HWNDREG
The hWndReg parameter is not a valid window handle.
WFS_ERR_INVALID_POINTER
A pointer parameter does not point to accessible memory.
WFS_ERR_NOT_REGISTERED
The specified hWndReg window was not registered to receive messages for any event classes.
WFS_ERR_NOT_STARTED
The application has not previously performed a successful WFSStartUp.
WFS_ERR_OP_IN_PROGRESS
A blocking operation is in progress on the thread; only WFSCancelBlockingCall and WFSIsBlocking are permitted at this time.

The 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.

WFS_ERR_CANCELED
The request was canceled by WFSCancelAsyncRequest.
WFS_ERR_INTERNAL_ERROR
An internal inconsistency or other unexpected error occurred in the WOSA/XFS subsystem.

See also WFSRegister, WFSClose


4.9 WFSDestroyAppHandle

HRESULT WFSDestroyAppHandle( hApp )

Makes the specified application handle invalid.

Parameters HAPP hApp

The application handle to be made invalid.

Mode Immediate

Comments 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 3.5 and 3.8.2 for additional discussion.

Error Codes If the function return is not WFS_SUCCESS, it is one of the following error conditions.

WFS_ERR_INTERNAL_ERROR
An internal inconsistency or other unexpected error occurred in the WOSA/XFS subsystem.
WFS_ERR_NOT_STARTED
The application has not previously performed a successful WFSStartUp.
WFS_ERR_INVALID_APP_HANDLE
The specified application handle is not valid, i.e., was not created by a preceding create call.

See also WFSCreateAppHandle


4.10 WFSExecute

HRESULT WFSExecute ( hService, dwCommand, lpCmdData, dwTimeOut, lppResult )

Sends a service-specific command to a service provider. The synchronous version of WFSAsyncExecute.

Parameters HSERVICE hService

Handle to the service as returned by WFSOpen or WFSAsyncOpen.

DWORD dwCommand

Command to be executed by the service provider.

LPVOID lpCmdData

Pointer to a command data structure to be passed to the service provider.

DWORD dwTimeOut

Number of milliseconds to wait for completion (WFS_INDEFINITE_WAIT to specify a request that will wait until completion).

LPWFSRESULT * lppResult

Pointer 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.

Mode Synchronous

Comments This function is used to execute service-specific commands. Each class of service includes a unique set of commands for the given type 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.

The 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 3.13.

Error 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.

WFS_ERR_CANCELED
The request was canceled by WFSCancelBlockingCall.
WFS_ERR_CONNECTION_LOST
The connection to the service is lost.
WFS_ERR_DEV_NOT_READY
The function required device access, and the device was not ready or timed out.
WFS_ERR_HARDWARE_ERROR
The function required device access, and an error occured on the device.
WFS_ERR_INTERNAL_ERROR
An internal inconsistency or other unexpected error occurred in the WOSA/XFS subsystem.
WFS_ERR_INVALID_COMMAND
The dwCommand issued is not supported by this service class.
WFS_ERR_INVALID_DATA
The data structure passed as input parameter contains invalid data.
WFS_ERR_INVALID_POINTER
A pointer parameter does not point to accessible memory.
WFS_ERR_INVALID_HSERVICE
The hService parameter is not a valid service handle.
WFS_ERR_LOCKED
The service is locked under a different hService.
WFS_ERR_NOT_STARTED
The application has not previously performed a successful WFSStartUp.
WFS_ERR_OP_IN_PROGRESS
A blocking operation is in progress on the thread; only WFSCancelBlockingCall and WFSIsBlocking are permitted at this time.
WFS_ERR_SOFTWARE_ERROR
The function required access to configuration information, and an error occured on the software.
WFS_ERR_TIMEOUT
The timeout interval expired.
WFS_ERR_UNSUPP_COMMAND
The dwCommand issued, although valid for this service class, is not supported by this service provider or device.

See Also WFSAsyncExecute


4.11 WFSAsyncExecute

HRESULT WFSAsyncExecute( hService, dwCommand, lpCmdData, dwTimeOut, hWnd, lpRequestID )

Sends a service-specific command to a service provider. The asynchronous version of WFSExecute.

Parameters HSERVICE hService

Handle to the service provider as returned by WFSOpen or WFSAsyncOpen.

DWORD dwCommand

Command to be executed by the service provider.

LPVOID lpCmdData

Pointer to the data structure to be passed to the service provider.

DWORD dwTimeOut

Number of milliseconds to wait for completion (WFS_INDEFINITE_WAIT to specify a request that will wait until completion).

HWND hWnd

The window handle which is to receive the completion message for this request.

LPREQUESTID lpRequestID

Pointer to the request identifier for this request (returned parameter).

Mode Asynchronous

Comments See WFSExecute.

The 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 3.13.

Messages WFS_EXECUTE_COMPLETE
WFS_EXECUTE_EVENT

Error 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:

WFS_ERR_CONNECTION_LOST
The connection to the service is lost.
WFS_ERR_INTERNAL_ERROR
An internal inconsistency or other unexpected error occurred in the WOSA/XFS subsystem.
WFS_ERR_INVALID_COMMAND
The dwCommand issued is not supported by this service class.
WFS_ERR_INVALID_HSERVICE
The hService parameter is not a valid service handle.
WFS_ERR_INVALID_HWND
The hWnd parameter is not a valid window handle.
WFS_ERR_INVALID_POINTER
A pointer parameter does not point to accessible memory.
WFS_ERR_NOT_STARTED
The application has not previously performed a successful WFSStartUp.
WFS_ERR_OP_IN_PROGRESS
A blocking operation is in progress on the thread; only WFSCancelBlockingCall and WFSIsBlocking are permitted at this time.
WFS_ERR_UNSUPP_COMMAND
The dwCommand issued, although valid for this service class, is not supported by this service provider or device.

The 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.

WFS_ERR_CANCELED
The request was canceled by WFSCancelAsyncRequest.
WFS_ERR_DEV_NOT_READY
The function required device access, and the device was not ready or timed out.
WFS_ERR_HARDWARE_ERROR
The function required device access, and an error occured on the device.
WFS_ERR_INTERNAL_ERROR
An internal inconsistency or other unexpected error occurred in the WOSA/XFS subsystem.
WFS_ERR_INVALID_DATA
The data structure passed as input parameter contains invalid data.
WFS_ERR_LOCKED
The service is locked under a different hService.
WFS_ERR_SOFTWARE_ERROR
The function required access to configuration information, and an error occured on the software.
WFS_ERR_TIMEOUT
The timeout interval expired.
WFS_ERR_UNSUPP_COMMAND
The dwCommand issued, although valid for this service class, is not supported by this service provider or device.

See Also WFSCancelAsyncRequest, WFSExecute


4.12 WFSFreeResult

HRESULT WFSFreeResult ( lpResult )

Notifies the XFS Manager that a memory buffer (or linked list of buffers) that was dynamically allocated by a service provider is to be freed.

Parameters LPWFSRESULT lpResult

Pointer to a WFSRESULT data structure.

Mode Immediate

Comments The WOSA/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 3.13.

Error Codes If the function return is not WFS_SUCCESS, it is one of the following error conditions:

WFS_ERR_INTERNAL_ERROR
An internal inconsistency or other unexpected error occurred in the WOSA/XFS subsystem.
WFS_ERR_INVALID_RESULT
The lpResult parameter is not a pointer to an allocated WFSRESULT structure.
WFS_ERR_NOT_STARTED
The application has not previously performed a successful WFSStartUp.

See Also WFSExecute, WFSAsyncExecute, WFSGetInfo, WFSAsyncGetInfo


4.13 WFSGetInfo

HRESULT WFSGetInfo( hService, dwCategory, lpQueryDetails, dwTimeOut, lppResult )

Retrieves information from the specified service provider. The synchronous version of WFSAsyncGetInfo.

Parameters HSERVICE hService

Handle to the service provider as returned by WFSOpen or WFSAsyncOpen.

DWORD dwCategory

Specifies 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).

LPVOID lpQueryDetails

Pointer 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.)

DWORD dwTimeOut

Number of milliseconds to wait for completion (WFS_INDEFINITE_WAIT to specify a request that will wait until completion).

LPWFSRESULT * lppResult

Pointer 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.

Mode Synchronous

Comments 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.

The 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.

The 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 3.13.

Error 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.

WFS_ERR_CANCELED
The request was canceled by WFSCancelBlockingCall.
WFS_ERR_CONNECTION_LOST
The connection to the service is lost.
WFS_ERR_DEV_NOT_READY
The function required device access, and the device was not ready or timed out.
WFS_ERR_HARDWARE_ERROR
The function required device access, and an error occured on the device.
WFS_ERR_INTERNAL_ERROR
An internal inconsistency or other unexpected error occurred in the WOSA/XFS subsystem.
WFS_ERR_INVALID_CATEGORY
The dwCategory issued is not supported by this service class.
WFS_ERR_INVALID_DATA
The data structure passed as input parameter contains invalid data.
WFS_ERR_INVALID_HSERVICE
The hService parameter is not a valid service handle.
WFS_ERR_INVALID_POINTER
A pointer parameter does not point to accessible memory.
WFS_ERR_NOT_STARTED
The application has not previously performed a successful WFSStartUp.
WFS_ERR_OP_IN_PROGRESS
A blocking operation is in progress on the thread; only WFSCancelBlockingCall and WFSIsBlocking are permitted at this time.
WFS_ERR_SOFTWARE_ERROR
The function required access to configuration information, and an error occured on the software.
WFS_ERR_TIMEOUT
The timeout interval expired.
WFS_ERR_UNSUPP_CATEGORY
The dwCategory issued, although valid for this service class, is not supported by this service provider.

See Also WFSAsyncGetInfo


4.14 WFSAsyncGetInfo

HRESULT WFSAsyncGetInfo( hService, dwCategory, lpQueryDetails, dwTimeOut, hWnd, lpRequestID )

Retrieves information from the specified service provider. The asynchronous version of WFSGetInfo.

Parameters HSERVICE hService

Handle to the service provider as returned by WFSOpen or WFSAsyncOpen.

DWORD dwCategory

See WFSGetInfo.

LPVOID lpQueryDetails

See WFSGetInfo.

DWORD dwTimeOut

Number of milliseconds to wait for completion (WFS_INDEFINITE_WAIT to specify a request that will wait until completion).

HWND hWnd

The window handle which is to receive the completion message for this request.

LPREQUESTID lpRequestID

The request identifier for this request (returned parameter).

Mode Asynchronous

Comments See WFSGetInfo. The 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.

The 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 3.13.

Messages WFS_GETINFO_COMPLETE

Error 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:

WFS_ERR_CONNECTION_LOST
The connection to the service is lost.
WFS_ERR_INTERNAL_ERROR
An internal inconsistency or other unexpected error occurred in the WOSA/XFS subsystem.
WFS_ERR_INVALID_CATEGORY
The dwCategory issued is not supported by this service class.
WFS_ERR_INVALID_HSERVICE
The hService parameter is not a valid service handle.
WFS_ERR_INVALID_HWND
The hWnd parameter is not a valid window handle.
WFS_ERR_INVALID_POINTER
A pointer parameter does not point to accessible memory.
WFS_ERR_NOT_STARTED
The application has not previously performed a successful WFSStartUp.
WFS_ERR_OP_IN_PROGRESS
A blocking operation is in progress on the thread; only WFSCancelBlockingCall and WFSIsBlocking are permitted at this time.
WFS_ERR_UNSUPP_CATEGORY
The dwCategory issued, although valid for this service class, is not supported by this service provider.

The 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.

WFS_ERR_CANCELED
The request was canceled by WFSCancelAsyncRequest.
WFS_ERR_DEV_NOT_READY
The function required device access, and the device was not ready or timed out.
WFS_ERR_HARDWARE_ERROR
The function required device access, and an error occured on the device.
WFS_ERR_INTERNAL_ERROR
An internal inconsistency or other unexpected error occurred in the WOSA/XFS subsystem.
WFS_ERR_INVALID_DATA
The data structure passed as input parameter contains invalid data..
WFS_ERR_SOFTWARE_ERROR
The function required access to configuration information, and an error occured on the software.
WFS_ERR_TIMEOUT
The timeout interval expired.

See also WFSGetInfo, WFSCancelAsyncRequest


4.15 WFSIsBlocking

BOOL WFSIsBlocking( )

Determines whether a thread has a blocking operation in progress.

Parameters None

Return Value The return value is TRUE if a blocking operation is in progress and FALSE otherwise.

Mode Immediate

Comments 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 WOSA/XFS request.

Note that if another WOSA/XFS call is issued in this situation, the XFS Manager returns with a WFS_ERR_OP_IN_PROGRESS error code. See Section 3.12 for additional discussion.

See also WFSCancelBlockingCall


4.16 WFSLock

HRESULT WFSLock( hService, dwTimeOut , lppResult)

Establishes exclusive control by the calling application over the specified service. The synchronous version of WFSAsyncLock.

Parameters HSERVICE hService

Service provider handle as returned by WFSOpen or WFSAsyncOpen.

DWORD dwTimeOut

Number of milliseconds to wait for completion (WFS_INDEFINITE_WAIT to specify a request that will wait until completion).

LPWFSRESULT * lppResult

Pointer to the pointer to a WFSRESULT data structure (see Comments). The service provider allocates the memory for this structure.

Mode Synchronous

Comments 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 3.8 for more discussion of the lock concepts and policy.

The 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.

lppResult 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 3.8.2 for more discussion of this subject.

The 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 3.13.

Error Codes If the function return is not WFS_SUCCESS, it is one of the following error conditions.

WFS_ERR_CANCELED
The request was canceled by WFSCancelBlockingCall.
WFS_ERR_CONNECTION_LOST
The connection to the service is lost.
WFS_ERR_INTERNAL_ERROR
An internal inconsistency or other unexpected error occurred in the WOSA/XFS subsystem.
WFS_ERR_INVALID_HSERVICE
The hService parameter is not a valid service handle.
WFS_ERR_INVALID_POINTER
A pointer parameter does not point to accessible memory.
WFS_ERR_NOT_STARTED
The application has not previously performed a successful WFSStartUp.
WFS_ERR_OP_IN_PROGRESS
A blocking operation is in progress on the thread; only WFSCancelBlockingCall and WFSIsBlocking are permitted at this time.
WFS_ERR_TIMEOUT
The timeout interval expired.

See also WFSAsyncLock, WFSUnlock, WFSCancelBlockingCall


4.17 WFSAsyncLock

HRESULT WFSAsyncLock( hService, dwTimeOut, hWnd, lpRequestID )

Establishes exclusive control by the calling application over the specified service. The asynchronous version of WFSLock.

Parameters HSERVICE hService

Handle to the service provider as returned by WFSOpen or WFSAsyncOpen.

DWORD dwTimeOut

Number of milliseconds to wait for completion (WFS_INDEFINITE_WAIT to specify a request that will wait until completion).

HWND hWnd

The window handle which is to receive the completion message for this request.

LPREQUESTID lpRequestID

Pointer to the request identifier for this request (returned parameter).

Mode Asynchronous

Comments See WFSLock and Section 3.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.

The 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 3.13.

Messages WFS_LOCK_COMPLETE

Error 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:

WFS_ERR_CONNECTION_LOST
The connection to the service is lost.
WFS_ERR_INTERNAL_ERROR
An internal inconsistency or other unexpected error occurred in the WOSA/XFS subsystem.
WFS_ERR_INVALID_HSERVICE
The hService parameter is not a valid service handle.
WFS_ERR_INVALID_HWND
The hWnd parameter is not a valid window handle.
WFS_ERR_INVALID_POINTER
A pointer parameter does not point to accessible memory.
WFS_ERR_NOT_STARTED
The application has not previously performed a successful WFSStartUp.
WFS_ERR_OP_IN_PROGRESS
A blocking operation is in progress on the thread; only WFSCancelBlockingCall and WFSIsBlocking are permitted at this time.

The following error conditions are returned via the asynchronous command completion message, as the hResult from the WFSRESULT structure.

WFS_ERR_CANCELED
The request was canceled by WFSCancelAsyncRequest.
WFS_ERR_INTERNAL_ERROR
An internal inconsistency or other unexpected error occurred in the WOSA/XFS subsystem.
WFS_ERR_TIMEOUT
The timeout interval expired.

See also WFSLock, WFSUnlock, WFSCancelAsyncRequest


4.18 WFSOpen

HRESULT WFSOpen( lpszLogicalName, hApp, lpszAppID, dwTraceLevel, dwTimeOut, dwSrvcVersionsRequired, lpSrvcVersion, lpSPIVersion, lphService )

Initiates a session (a series of service requests terminated with the WFSClose function) between the application and the specified service. The synchronous version of WFSAsyncOpen.

Parameters LPSTR lpszLogicalName

Points 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.

HAPP hApp

The 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 3.5 and 3.8.2 for details.

LPSTR lpszAppID

Points 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

DWORD dwTraceLevel

See WFMSetTraceLevel. NULL turns off all tracing.

DWORD dwTimeOut

Number of milliseconds to wait for completion (WFS_INDEFINITE_WAIT to specify a request that will wait until completion).

DWORD dwSrvcVersionsRequired

Specifies 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.

LPWFSVERSION lpSrvcVersion

Pointer to the data structure that is to receive version support information and other details about the service-specific interface implementation (returned parameter).

LPWFSVERSION lpSPIVersion

Pointer 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.

LPHSERVICE lphService

Pointer 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.

Mode Synchronous

Comments 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.

In order to support future WOSA/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 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.)

Information describing the actual service provider implementation is returned in the WFSVERSION data structure (defined in Section 8.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.

The 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.

This version negotiation allows a WOSA/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:

Application version(s) | Service Provider version(s) | Return status from WFSOpen | Result
1.00 | 1.00 | WFS_SUCCESS | use 1.00
1.00 - 2.10 | 1.00 | WFS_SUCCESS | use 1.00
1.11 | 1.00 - 2.00 | WFS_SUCCESS | use 1.11
2.11 - 3.00 | 1.00 - 2.20 | WFS_SUCCESS | use 2.20
1.00 | 2.20 - 3.00 | WFS_ERR_SRVC_VERS_TOO_LOW | fails
1.11 - 3.00 | 1.00 | WFS_ERR_SRVC_VERS_TOO_HIGH | fails

Note that a version negotiation error also generates a system event (see Section 9.7).

Error Codes If the function return is not WFS_SUCCESS, it is one of the following error conditions.

WFS_ERR_CANCELED
The request was canceled by WFSCancelBlockingCall.
WFS_ERR_CONNECTION_LOST
The connection to the service is lost.
WFS_ERR_DEV_NOT_READY
The function required device access, and the device was not ready or timed out.
WFS_ERR_HARDWARE_ERROR
The function required device access, and an error occured on the device.
WFS_ERR_INTERNAL_ERROR
An internal inconsistency or other unexpected error occurred in the WOSA/XFS subsystem.
WFS_ERR_INVALID_APP_HANDLE
The specified application handle is not valid, i.e., was not created by a preceding create call.
WFS_ERR_INVALID_POINTER
A pointer parameter does not point to accessible memory.
WFS_ERR_INVALID_SERVPROV
The file containing the service provider is invalid or corrupted.
WFS_ERR_INVALID_TRACELEVEL
The dwTraceLevel parameter does not correspond to a valid trace level or set of levels.
WFS_ERR_NO_SERVPROV
The file containing the service provider does not exist.
WFS_ERR_NOT_STARTED
The application has not previously performed a successful WFSStartUp.
WFS_ERR_OP_IN_PROGRESS
A blocking operation is in progress on the thread; only WFSCancelBlockingCall and WFSIsBlocking are permitted at this time.
WFS_ERR_SERVICE_NOT_FOUND
The logical name is not a valid service provider name.
WFS_ERR_SOFTWARE_ERROR
The function required access to configuration information, and an error occured on the software.
WFS_ERR_SPI_VER_TOO_HIGH
The range of versions of WOSA/XFS SPI support requested by the XFS Manager is higher than any supported by the service provider for the logical service being opened.
WFS_ERR_SPI_VER_TOO_LOW
The range of versions of WOSA/XFS SPI support requested by the a XFS Manager is lower than any supported by the service provider for the logical service being opened.
WFS_ERR_SRVC_VER_TOO_HIGH
The 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.
WFS_ERR_SRVC_VER_TOO_LOW
The 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.
WFS_ERR_TIMEOUT
The timeout interval expired.
WFS_ERR_VERSION_ERROR_IN_SRVC
Within the service, a version mismatch of two modules occurred.

See also WFSAsyncOpen, WFSClose, WFSCreateAppHandle


4.19 WFSAsyncOpen

HRESULT WFSAsyncOpen( lpszLogicalName, hApp, lpszAppID, dwTraceLevel, dwTimeOut, lphService, hWnd, dwSrvcVersionsRequired, lpSrvcVersion, lpSPIVersion, lpRequestID )

Initiates a session (a series of service requests terminated with the WFSClose or WFSAsyncClose function) between the application and the specified service. The asynchronous version of WFSOpen.

Parameters LPSTR lpszLogicalName

See WFSOpen.

HAPP hApp

The application handle to be associated with the session being opened.
See WFSOpen, WFSCreateAppHandle and Sections 3.5 and 3.8.2 for details.

LPSTR lpszAppID

Points to a null-terminated string containing the application ID. See WFSOpen.

DWORD dwTraceLevel

See WFMSetTraceLevel. NULL turns off all tracing.

DWORD dwTimeOut

Number of milliseconds to wait for completion (WFS_INDEFINITE_WAIT to specify a request that will wait until completion).

LPHSERVICE lphService

Pointer to the service handle (returned parameter).

HWND hWnd

The window handle which is to receive the completion message for this request.

DWORD dwSrvcVersionsRequired

See WFSOpen.

LPWFSVERSION lpSrvcVersion

See WFSOpen (returned parameter).

LPWFSVERSION lpSPIVersion

See WFSOpen (returned parameter).

LPREQUESTID lpRequestID

Pointer to the request identifier for this request (returned parameter).

Mode Asynchronous

Comments See WFSOpen.

The 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 3.13.

Messages WFS_OPEN_COMPLETE

Error 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:

WFS_ERR_CONNECTION_LOST
The connection to the service is lost.
WFS_ERR_INTERNAL_ERROR
An internal inconsistency or other unexpected error occurred in the WOSA/XFS subsystem.
WFS_ERR_INVALID_APP_HANDLE
The specified application handle is not valid, i.e., was not created by a preceding create call.
WFS_ERR_INVALID_HWND
The hWnd parameter is not a valid window handle.
WFS_ERR_INVALID_POINTER
A pointer parameter does not point to accessible memory.
WFS_ERR_INVALID_SERVPROV
The file containing the service provider is invalid or corrupted.
WFS_ERR_INVALID_TRACELEVEL
The dwTraceLevel parameter does not correspond to a valid trace level or set of levels.
WFS_ERR_NO_SERVPROV
The file containing the service provider does not exist.
WFS_ERR_NOT_STARTED
The application has not previously performed a successful WFSStartUp.
WFS_ERR_OP_IN_PROGRESS
A blocking operation is in progress on the thread; only WFSCancelBlockingCall and WFSIsBlocking are permitted at this time.
WFS_ERR_SERVICE_NOT_FOUND
The logical name is not a valid service provider name.
WFS_ERR_SPI_VER_TOO_HIGH
The range of versions of WOSA/XFS SPI support requested by the XFS Manager is higher than any supported by the service provider for the logical service being opened.
WFS_ERR_SPI_VER_TOO_LOW
The range of versions of WOSA/XFS SPI support requested by the a XFS Manager is lower than any supported by the service provider for the logical service being opened.
WFS_ERR_SRVC_VER_TOO_HIGH
The 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.
WFS_ERR_SRVC_VER_TOO_LOW
The 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.
WFS_ERR_VERSION_ERROR_IN_SRVC
Within the service, a version mismatch of two modules occurred.

The 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.

WFS_ERR_CANCELED
The request was canceled by WFSCancelAsyncRequest.
WFS_ERR_DEV_NOT_READY
The function required device access, and the device was not ready timed out.
WFS_ERR_INTERNAL_ERROR
An internal inconsistency or other unexpected error occurred in the WOSA/XFS subsystem.
WFS_ERR_HARDWARE_ERROR
The function required device access, and an error occured on the device.
WFS_ERR_SOFTWARE_ERROR
The function required access to configuration information, and an error occured on the software.
WFS_ERR_TIMEOUT
The timeout interval expired.
WFS_ERR_VERSION_ERROR_IN_SRVC
Within the service, a version mismatch of two modules occurred.

See also WFSOpen, WFSClose, WFSCreateAppHandle, WFSCancelAsyncRequest, WFMSetTraceLevel


4.20 WFSRegister

HRESULT WFSRegister( hService, dwEventClass, hWndReg )

Enables 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.

Parameters HSERVICE hService

Handle 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.

DWORD dwEventClass

The 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.

HWND hWndReg

The window handle which is to be registered to receive the specified messages.

Mode Synchronous

Comments 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:

hr = WFSRegister(hPassbook1, SYSTEM_EVENTS | USER_EVENTS, hWndReg1);

or call them in two phases:

 hr = WFSRegister( hPassbook1, SYSTEM_EVENTS, hWndReg1);
 . . . . . . . .
 . . . . . . . .

hr = WFSRegister( hPassbook1, USER_EVENTS, hWndReg1);

To cancel notifications use WFSDeregister.

Note 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 3.11.

Error Codes If the function return is not WFS_SUCCESS, it is one of the following error conditions.

WFS_ERR_CANCELED
The request was canceled by WFSCancelBlockingCall.
WFS_ERR_CONNECTION_LOST
The connection to the service is lost.
WFS_ERR_INTERNAL_ERROR
An internal inconsistency or other unexpected error occurred in the WOSA/XFS subsystem.
WFS_ERR_INVALID_EVENT_CLASS
The dwEventClass parameter specifies one or more event classes not supported by the service.
WFS_ERR_INVALID_HSERVICE
The hService parameter is not a valid service handle.
WFS_ERR_INVALID_HWNDREG
The hWndReg parameter is not a valid window handle.
WFS_ERR_NOT_STARTED
The application has not previously performed a successful WFSStartUp.
WFS_ERR_OP_IN_PROGRESS
A blocking operation is in progress on the thread; only WFSCancelBlockingCall and WFSIsBlocking are permitted at this time.

See also WFSAsyncRegister, WFSDeregister, WFSAsyncDeregister


4.21 WFSAsyncRegister

HRESULT WFSAsyncRegister( hService, dwEventClass, hWndReg, hWnd, lpRequestID )

Enables 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.

Parameters HSERVICE hService

Handle 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.

DWORD dwEventClass

See WFSRegister.

HWND hWndReg

The window handle which is to be registered to receive the specified messages.

HWND hWnd

The window handle which is to receive the completion message for this request.

LPREQUESTID lpRequestID

Pointer to the request identifier for this request (returned parameter).

Mode Asynchronous

Comments See WFSRegister.

The 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 3.13.

Messages WFS_REGISTER_COMPLETE

Error 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:

WFS_ERR_CONNECTION_LOST
The connection to the service is lost.
WFS_ERR_INTERNAL_ERROR
An internal inconsistency or other unexpected error occurred in the WOSA/XFS subsystem.
WFS_ERR_INVALID_EVENT_CLASS
The dwEventClass parameter specifies one or more event classes not supported by the service.
WFS_ERR_INVALID_HSERVICE
The hService parameter is not a valid service handle.
WFS_ERR_INVALID_HWND
The hWnd parameter is not a valid window handle.
WFS_ERR_INVALID_HWNDREG
The hWndReg parameter is not a valid window handle.
WFS_ERR_NOT_STARTED
The application has not previously performed a successful WFSStartUp.
WFS_ERR_OP_IN_PROGRESS
A blocking operation is in progress on the thread; only WFSCancelBlockingCall and WFSIsBlocking are permitted at this time.

The following error conditions can be returned via the asynchronous command completion message, as the hResult from the WFSRESULT structure.

WFS_ERR_CANCELED
The request was canceled by WFSCancelAsyncRequest.
WFS_ERR_INTERNAL_ERROR
An internal inconsistency or other unexpected error occurred in the WOSA/XFS subsystem.

See also WFSRegister, WFSDeregister, WFSAsyncDeregister


4.22 WFSSetBlockingHook

HRESULT WFSSetBlockingHook( lpBlockFunc, lppPrevFunc )

Establishes an application-specific blocking routine.

Parameters XFSBLOCKINGHOOK lpBlockFunc

Pointer to the procedure instance address of the blocking routine to be installed.

LPXFSBLOCKINGHOOK lppPrevFunc

Returned pointer to a pointer to the procedure instance of the previously installed blocking routine.

Mode Immediate

Comments 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.

See Section 3.12 for a complete discussion.

Error Codes If the function return is not WFS_SUCCESS, it is one of the following error conditions:

WFS_ERR_INTERNAL_ERROR
An internal inconsistency or other unexpected error occurred in the WOSA/XFS subsystem.
WFS_ERR_NOT_STARTED
The application has not previously performed a successful WFSStartUp.
WFS_ERR_OP_IN_PROGRESS
A blocking operation is in progress on the thread; only WFSCancelBlockingCall and WFSIsBlocking are permitted at this time.
WFS_ERR_INVALID_POINTER
A pointer parameter does not point to accessible memory.

See also WFSUnhookBlockingHook, WFSCancelBlockingCall, WFSIsBlocking


4.23 WFSStartUp

HRESULT WFSStartUp( dwVersionsRequired, lpWFSVersion )

Establishes a connection between an application and the XFS Manager.

Parameters DWORD dwVersionsRequired

Specifies 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.

LPWFSVERSION lpWFSVersion

Pointer to the data structure that is to receive version support information and other details about the current WOSA/XFS implementation (returned parameter).

Mode Immediate

Comments This function is used by an application to register itself with the XFS Manager and specify the version(s) of the WOSA/XFS API specification it can use, and returns information on the specific WOSA/XFS implementation. It must be the first WOSA/XFS API function called by an application. An application may only issue further WOSA/XFS functions after a successful WFSStartUp has completed.

In order to support future WOSA/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 WOSA/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.

Information describing the actual WOSA/XFS implementation is returned by the XFS Manager in the WFSVERSION data structure (defined in Section 8.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.

The 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.

This version negotiation allows a WOSA/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:

Application versions | XFS Manager versions | Return status from WFSStartUp | Result
1.00 | 1.00 | WFS_SUCCESS | use 1.00
1.00 - 2.10 | 1.00 | WFS_SUCCESS | use 1.00
1.11 | 1.00 - 2.00 | WFS_SUCCESS | use 1.11
2.11 - 3.00 | 1.00 - 2.20 | WFS_SUCCESS | use 2.20
1.00 | 2.20 - 3.00 | WFS_ERR_API_VERS_TOO_LOW | fails
1.11 - 3.00 | 1.00 | WFS_ERR_API_VERS_TOO_HIGH | fails

Note that a version negotiation error also generates a system event (see Section 9.7).

After making its last WOSA/XFS call, an application must call WFSCleanUp to allow the XFS Manager to release any resources allocated for the application.

Error 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:

WFS_ERR_ALREADY_STARTED
A WFSStartUp has already been issued by the application, without an intervening WFSCleanUp.
WFS_ERR_API_VER_TOO_HIGH
The range of versions of WOSA/XFS API support requested by the application is higher than any supported by this particular WOSA/XFS implementation.
WFS_ERR_API_VER_TOO_LOW
The range of versions of WOSA/XFS API support requested by the application is lower than any supported by this particular WOSA/XFS implementation.
WFS_ERR_INTERNAL_ERROR
An internal inconsistency or other unexpected error occurred in the WOSA/XFS subsystem.
WFS_ERR_INVALID_POINTER
A pointer parameter does not point to accessible memory.

See also WFSCleanUp


4.24 WFSUnhookBlockingHook

HRESULT WFSUnhookBlockingHook( )

Removes any previous blocking hook that had been installed and reinstalls the default blocking mechanism.

Parameters None.

Mode Immediate

Comments 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 3.12.

Error Codes If the function return is not WFS_SUCCESS, it is one of the following error conditions:

WFS_ERR_INTERNAL_ERROR
An internal inconsistency or other unexpected error occurred in the WOSA/XFS subsystem.
WFS_ERR_NOT_STARTED
The application has not previously performed a successful WFSStartUp.
WFS_ERR_OP_IN_PROGRESS
A blocking operation is in progress on the thread; only WFSCancelBlockingCall and WFSIsBlocking are permitted at this time.

See also WFSSetBlockingHook


4.25 WFSUnlock

HRESULT WFSUnlock( hService )

Releases a service that has been locked by a previous WFSLock or WFSAsyncLock function. The synchronous version of WFSAsyncUnlock.

Parameters HSERVICE hService

Handle to the service provider as returned by WFSOpen or WFSAsyncOpen.

Mode Synchronous

Comments See Section 3.8.

Error Codes If the function return is not WFS_SUCCESS, it is one of the following error conditions:

WFS_ERR_CANCELED
The request was canceled by WFSCancelBlockingCall.
WFS_ERR_CONNECTION_LOST
The connection to the service is lost.
WFS_ERR_INTERNAL_ERROR
An internal inconsistency or other unexpected error occurred in the WOSA/XFS subsystem.
WFS_ERR_INVALID_HSERVICE
The hService parameter is not a valid service handle.
WFS_ERR_NOT_LOCKED
The application requesting a service be unlocked had not previously performed a successful WFSLock or WFSAsyncLock.
WFS_ERR_NOT_STARTED
The application has not previously performed a successful WFSStartUp.
WFS_ERR_OP_IN_PROGRESS
A blocking operation is in progress on the thread; only WFSCancelBlockingCall and WFSIsBlocking are permitted at this time.

See also WFSAsyncUnlock, WFSLock, WFSAsyncLock


4.26 WFSAsyncUnlock

HRESULT WFSAsyncUnlock( hService, hWnd, lpRequestID )

Releases a service that has been locked by a previous WFSLock or WFSAsyncLock function. The asynchronous version of WFSUnlock.

Parameters HSERVICE hService

Handle to the service provider as returned by WFSOpen or WFSAsyncOpen.

HWND hWnd

The window handle which is to receive the completion message for this request.

LPREQUESTID lpRequestID

Pointer to the request identifier for this request (returned parameter).

Mode Aynchronous

Comments See WFSUnlock and Section 3.8.

The 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 3.13.

Messages WFS_UNLOCK_COMPLETE

Error 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:

WFS_ERR_CONNECTION_LOST
The connection to the service is lost.
WFS_ERR_INTERNAL_ERROR
An internal inconsistency or other unexpected error occurred in the WOSA/XFS subsystem.
WFS_ERR_INVALID_HSERVICE
The hService parameter is not a valid service handle.
WFS_ERR_INVALID_HWND
The hWnd parameter is not a valid window handle.
WFS_ERR_INVALID_POINTER
A pointer parameter does not point to accessible memory.
WFS_ERR_NOT_STARTED
The application has not previously performed a successful WFSStartUp.
WFS_ERR_OP_IN_PROGRESS
A blocking operation is in progress on the thread; only WFSCancelBlockingCall and WFSIsBlocking are permitted at this time.

The following error conditions are returned via the asynchronous command completion message, as the hResult from the WFSRESULT structure:

WFS_ERR_CANCELED
The request was canceled by WFSCancelAsyncRequest.
WFS_ERR_INTERNAL_ERROR
An internal inconsistency or other unexpected error occurred in the WOSA/XFS subsystem.
WFS_ERR_NOT_LOCKED
The application requesting a service be unlocked had not previously performed a successful WFSLock or WFSAsyncLock.

See also WFSUnlock, WFSLock, WFSAsyncLock


5. Service Provider Interface (SPI) Functions

The 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.

Section | WOSA/XFS SPI | Mode | WOSA/XFS API | Mode
5.1 | WFPCancelAsyncRequest | Immediate | WFSCancelAsyncRequest | Immediate
5.1 | WFPCancelAsyncRequest | Immediate | WFSCancelBlockingCall | Immediate
 | (none) | - | WFSCleanUp | Synchronous
5.2 | WFPClose | Asynchronous | WFSClose | Synchronous
5.2 | WFPClose | Asynchronous | WFSAsyncClose | Asynchronous
 | (none) | - | WFSCreateAppHandle | Immediate
5.3 | WFPDeregister | Asynchronous | WFSDeregister | Synchronous
5.3 | WFPDeregister | Asynchronous | WFSAsyncDeregister | Asynchronous
 | (none) | - | WFSDestroyAppHandle | Immediate
5.4 | WFPExecute | Asynchronous | WFSExecute | Synchronous
5.4 | WFPExecute | Asynchronous | WFSAsyncExecute | Asynchronous
 | (none) | - | WFSFreeResult | Immediate
5.5 | WFPGetInfo | Asynchronous | WFSGetInfo | Synchronous
5.5 | WFPGetInfo | Asynchronous | WFSAsyncGetInfo | Asynchronous
 | (none) | - | WFSIsBlocking | Immediate
5.6 | WFPLock | Asynchronous | WFSLock | Synchronous
5.6 | WFPLock | Asynchronous | WFSAsyncLock | Asynchronous
5.7 | WFPOpen | Asynchronous | WFSOpen | Synchronous
5.7 | WFPOpen | Asynchronous | WFSAsyncOpen | Asynchronous
5.8 | WFPRegister | Asynchronous | WFSRegister | Synchronous
5.8 | WFPRegister | Asynchronous | WFSAsyncRegister | Asynchronous
 | (none) | - | WFSSetBlockingHook | Immediate
5.9 | WFPSetTraceLevel | Immediate | (none) | -
 | (none) | - | WFSStartUp | Immediate
 | (none) | - | WFSUnhookBlockingHook | Immediate
5.10 | WFPUnloadService |  |  |
5.11 | WFPUnlock | Asynchronous | WFSUnlock | Synchronous.
5.11 | WFPUnlock | Asynchronous | WFSAsyncUnlock | Asynchronous

Note 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 WOSA Extensions to Financial Services, and will also use these interfaces, with additions as necessary. See Appendix A for more on this subject.


5.1 WFPCancelAsyncRequest

HRESULT WFPCancelAsyncRequest( hService, RequestID )

Cancels the specified (or every) asynchronous request being performed on the specified service provider, before its (their) completion.

Parameters HSERVICE hService

Handle to the service provider.

REQUESTID RequestID

The request identifier (NULL to cancel all requests for the specified hService).

Mode 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).

Comments 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.

A 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.

The 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.

Error Codes If the function return is not WFS_SUCCESS, it is one of the following error conditions:

WFS_ERR_CONNECTION_LOST
The connection to the service is lost.
WFS_ERR_INTERNAL_ERROR
An internal inconsistency or other unexpected error occurred in the WOSA/XFS subsystem.
WFS_ERR_INVALID_HSERVICE
The hService parameter is not a valid service handle.
WFS_ERR_INVALID_REQ_ID
The RequestID parameter does not correspond to an outstanding request on the service.


5.2 WFPClose

HRESULT WFPClose( hService, hWnd, ReqID )

Terminates a session (a series of service requests initiated with the WFPOpen SPI function) between the XFS Manager and the specified service provider.

Parameters HSERVICE hService

Handle to the service provider.

HWND hWnd

The window handle which is to receive the completion message for this request.

REQUESTID ReqID

Request identification number.

Mode Asynchronous

Comments 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.

See WFPOpen and Section 3.6 for further discussion.

Messages WFS_CLOSE_COMPLETE

Error 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.

WFS_ERR_CONNECTION_LOST
The connection to the service is lost.
WFS_ERR_INTERNAL_ERROR
An internal inconsistency or other unexpected error occurred in the WOSA/XFS subsystem.
WFS_ERR_INVALID_HSERVICE
The hService parameter is not a valid service handle.
WFS_ERR_INVALID_HWND
The hWnd parameter is not a valid window handle.

The 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.

WFS_ERR_CANCELED
The request was canceled by WFSCancelAsyncRequest.
WFS_ERR_INTERNAL_ERROR
An internal inconsistency or other unexpected error occurred in the WOSA/XFS subsystem.


5.3 WFPDeregister

HRESULT WFPDeregister( hService, dwEventClass, hWndReg, hWnd, ReqID )

Discontinues monitoring of the specified message class(es) from the specified service provider, by the specified hWndReg (or all hWnd's).

Parameters HSERVICE hService

Handle to the service provider

DWORD dwEventClass

The 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.

HWND hWndReg

The 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.

HWND hWnd

The window handle which is to receive the completion message for this request.

REQUESTID ReqID

Request identification number.

Mode Asynchronous

Comments 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.

A WFPDeregister os performed automatically if a WFPClose is issued without a previous WFPDeregister.

To deregister all messages for all hWnds, the call supplies NULL values for both the dwEventClass and hWnd parameters.

See the WFPRegister function for a description of the types of events that may be monitored.

Messages WFS_DEREGISTER_COMPLETE

Error 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.

WFS_ERR_CONNECTION_LOST
The connection to the service is lost.
WFS_ERR_INTERNAL_ERROR
An internal inconsistency or other unexpected error occurred in the WOSA/XFS subsystem.
WFS_ERR_INVALID_EVENT_CLASS
The dwEventClass parameter specifies one or more event classes not supported by the service.
WFS_ERR_INVALID_HSERVICE
The hService parameter is not a valid service handle.
WFS_ERR_INVALID_HWND
The hWnd parameter is not a valid window handle.
WFS_ERR_INVALID_HWNDREG
The hWndReg parameter is not a valid window handle.
WFS_ERR_NOT_REGISTERED
The specified hWndReg window was not registered to receive messages for any event classes.

The 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.

WFS_ERR_CANCELED
The request was canceled by WFSCancelAsyncRequest.


5.4 WFPExecute

HRESULT WFPExecute( hService, dwCommand, lpCmdData, dwTimeOut, hWnd, ReqID )

Sends asynchronous service class specific commands to a service provider.

Parameters HSERVICE hService

Handle to the service provider.

DWORD dwCommand

Command to be executed.

LPVOID lpCmdData

Pointer to the data structure to be passed.

DWORD dwTimeOut

Number of milliseconds to wait for completion (WFS_INDEFINITE_WAIT to specify a request that will wait until completion).

HWND hWnd

The window handle which is to receive the completion message for this request.

REQUESTID ReqID

Request identification number.

Mode Asynchronous

Comments See WFSExecute.

Messages WFS_EXECUTE_COMPLETE

Error 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.

WFS_ERR_CONNECTION_LOST
The connection to the service is lost.
WFS_ERR_INTERNAL_ERROR
An internal inconsistency or other unexpected error occurred in the WOSA/XFS subsystem.
WFS_ERR_INVALID_COMMAND
The dwCommand issued is not supported by this service class.
WFS_ERR_INVALID_HSERVICE
The hService parameter is not a valid service handle.
WFS_ERR_INVALID_HWND
The hWnd parameter is not a valid window handle.
WFS_ERR_INVALID_POINTER
A pointer parameter does not point to accessible memory.
WFS_ERR_UNSUPP_COMMAND
The dwCommand issued, although valid for this service class, is not supported by this service provider.

The 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.

WFS_ERR_CANCELED
The request was canceled by WFSCancelAsyncRequest.
WFS_ERR_DEV_NOT_READY
The function required device access, and the device was not ready or timed out.
WFS_ERR_HARDWARE_ERROR
The function required device access, and an error occured on the device.
WFS_ERR_INVALID_DATA
The data structure passed as input parameter contains invalid data..
WFS_ERR_INTERNAL_ERROR
An internal inconsistency or other unexpected error occurred in the WOSA/XFS subsystem.
WFS_ERR_LOCKED
The service is locked under a different hService.
WFS_ERR_SOFTWARE_ERROR
The function required access to configuration information, and an error occured on the software.
WFS_ERR_TIMEOUT
The timeout interval expired.


5.5 WFPGetInfo

HRESULT WFPGetInfo( hService, dwCategory, lpQueryDetails, dwTimeOut, hWnd, ReqID )

Retrieves various kinds of information from the specified service provider.

Parameters HSERVICE hService

Handle to the service provider.

DWORD dwCategory

Specifies 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).

LPVOID lpQueryDetails

Pointer 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.)

DWORD dwTimeOut

Number of milliseconds to wait for completion (WFS_INDEFINITE_WAIT to specify a request that will wait until completion).

HWND hWnd

The window handle which is to receive the completion message for this request.

REQUESTID ReqID

Request identification number.

Mode Asynchronous

Comments 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.

The specifications for the information structures for each service class can be found in the specifications for the service-specific commmands.

Messages WFS_GETINFO_COMPLETE

Error 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.

WFS_ERR_CONNECTION_LOST
The connection to the service is lost.
WFS_ERR_INTERNAL_ERROR
An internal inconsistency or other unexpected error occurred in the WOSA/XFS subsystem.
WFS_ERR_INVALID_CATEGORY
The dwCategory issued is not supported by this service class.
WFS_ERR_INVALID_HSERVICE
The hService parameter is not a valid service handle.
WFS_ERR_INVALID_HWND
The hWnd parameter is not a valid window handle.
WFS_ERR_INVALID_POINTER
A pointer parameter does not point to accessible memory.
WFS_ERR_UNSUPP_CATEGORY
The dwCategory issued, although valid for this service class, is not supported by this service provider.

The 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.

WFS_ERR_CANCELED
The request was canceled by WFSCancelAsyncRequest.
WFS_ERR_DEV_NOT_READY
The function required device access, and the device was not ready or timed out.
WFS_ERR_HARDWARE_ERROR
The function required device access, and an error occured on the device.
WFS_ERR_INTERNAL_ERROR
An internal inconsistency or other unexpected error occurred in the WOSA/XFS subsystem.
WFS_ERR_INVALID_DATA
The data structure passed as input parameter contains invalid data..
WFS_ERR_SOFTWARE_ERROR
The function required access to configuration information, and an error occured on the software.
WFS_ERR_TIMEOUT
The timeout interval expired.


5.6 WFPLock

HRESULT WFPLock( hService, dwTimeOut, hWnd, ReqID )

Establishes exclusive control by the calling application over the specified service.

Parameters HSERVICE hService

Handle to the service provider.

DWORD dwTimeOut

Number of milliseconds to wait for completion (WFS_INDEFINITE_WAIT to specify a request that will wait until completion).

HWND hWnd

The window handle which is to receive the completion message for this request.

REQUESTID ReqID

Request identification number.

Mode Asynchronous

Comments See WFSLock.

Messages WFS_LOCK_COMPLETE

Error 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.

WFS_ERR_CONNECTION_LOST
The connection to the service is lost.
WFS_ERR_INTERNAL_ERROR
An internal inconsistency or other unexpected error occurred in the WOSA/XFS subsystem.
WFS_ERR_INVALID_HSERVICE
The hService parameter is not a valid service handle.
WFS_ERR_INVALID_HWND
The hWnd parameter is not a valid window handle.

The 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.

WFS_ERR_CANCELED
The request was canceled by WFSCancelAsyncRequest.
WFS_ERR_DEV_NOT_READY
The function required device access, and the device was not ready or timed out.
WFS_ERR_HARDWARE_ERROR
The function required device access, and an error occured on the device.
WFS_ERR_INTERNAL_ERROR
An internal inconsistency or other unexpected error occurred in the WOSA/XFS subsystem.
WFS_ERR_SOFTWARE_ERROR
The function required access to configuration information, and an error occured on the software.
WFS_ERR_TIMEOUT
The timeout interval expired.


5.7 WFPOpen

HRESULT WFPOpen( hService, lpszLogicalName, hApp, lpszAppID, dwTraceLevel, dwTimeOut, hWnd, ReqID, hProvider, dwSPIVersionsRequired, lpSPIVersion, dwSrvcVersionsRequired, lpSrvcVersion )

Establishes 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).

Parameters HSERVICE hService

The service handle to be associated with the session being opened..

LPSTR lpszLogicalName

Points 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.

HAPP hApp

The application handle to be associated with the session being opened.
See WFSCreateAppHandle and Sections 3.5 and 3.8.2 for details.

LPSTR lpszAppID

Pointer to a null terminated string containing the application ID; the pointer may be NULL if the ID is not used.

DWORD dwTraceLevel

See WFPSetTraceLevel.

DWORD dwTimeOut

Number of milliseconds to wait for completion (WFS_INDEFINITE_WAIT to specify a request that will wait until completion).

HWND hWnd

The window handle which is to receive the completion message for this request.

REQUESTID ReqID

Request identification number.

HPROVIDER hProvider

Service provider handle supplied by the XFS Manager – used by the service provider to identify itself when calling the WFMReleaseDLL function.

DWORD dwSPIVersionsRequired

Specifies the range of WOSA/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.

LPWFSVERSION lpSPIVersion

Pointer to the data structure that is to receive SPI version support information and (optionally) other details about the SPI implementation (returned parameter).

DWORD dwSrvcVersionsRequired

Service-specific interface versions required; see dwSPIVersionsRequired above, and WFSOpen.

LPWFSVERSION lpSrvcVersion

Pointer to the service-specific interface implementation information; see lpSPIVersion above, and WFSOpen (returned parameter).

Mode Asynchronous

Comments 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).

In order to support future WOSA/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 WOSA/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.

The WFSVERSION data structure (described in Section 8.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.

The 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.

This 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:

XFS Manager versions | Service Provider versions | Return status from WFPOpen | Result
1.00 | 1.00 | WFS_SUCCESS | use 1.00
1.00 - 2.10 | 1.00 | WFS_SUCCESS | use 1.00
1.11 | 1.00 - 2.00 | WFS_SUCCESS | use 1.11
2.11 - 3.00 | 1.00 - 2.20 | WFS_SUCCESS | use 2.20
1.00 | 2.20 - 3.00 | WFS_ERR_SPI_VER_TOO_LOW | fails
1.11 - 3.00 | 1.00 | WFS_ERR_SPI_VER_TOO_HIGH | fails

The second negotiation is is in relation to the service-specific interface, between the application program and the service provider. See WFSOpen, Section 4.19, for details.

Note that a version negotiation error also generates a system event (see Section 9.7).

Also, see WFSStartUp, Section 4.24.

Messages WFS_OPEN_COMPLETE

Error 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.

WFS_ERR_CONNECTION_LOST
The connection to the service is lost.
WFS_ERR_INTERNAL_ERROR
An internal inconsistency or other unexpected error occurred in the WOSA/XFS subsystem.
WFS_ERR_INVALID_HSERVICE
The hService parameter is not a valid service handle.
WFS_ERR_INVALID_HWND
The hWnd parameter is not a valid window handle.
WFS_ERR_INVALID_POINTER
A pointer parameter does not point to accessible memory.
WFS_ERR_INVALID_TRACELEVEL
The dwTraceLevel parameter does not correspond to a valid trace level or set of levels.
WFS_ERR_SPI_VER_TOO_HIGH
The range of versions of WOSA/XFS SPI support requested by the XFS Manager is higher than any supported by this particular service provider.
WFS_ERR_SPI_VER_TOO_LOW
The range of versions of WOSA/XFS SPI support requested by the XFS Manager is lower than any supported by this particular service provider.
WFS_ERR_SRVC_VER_TOO_HIGH
The 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.
WFS_ERR_SRVC_VER_TOO_LOW
The 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.
WFS_ERR_VERSION_ERROR_IN_SRVC
Within the service, a version mismatch of two modules occurred.

The 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.

WFS_ERR_CANCELED
The request was canceled by WFSCancelAsyncRequest.
WFS_ERR_INTERNAL_ERROR
An internal inconsistency or other unexpected error occurred in the WOSA/XFS subsystem.
WFS_ERR_TIMEOUT
The timeout interval expired.
WFS_ERR_VERSION_ERROR_IN_SRVC
Within the service, a version mismatch of two modules occurred.


5.8 WFPRegister

HRESULT WFPRegister( hService, dwEventClass, hWndReg, hWnd, ReqID )

Enables event monitoring for the specified service by the specified hWndReg; all events of the specified class(es) generate messages to the hWndReg.

Parameters HSERVICE hService

Handle to the service provider.

DWORD dwEventClass

The class(es) of events for which the application is registering. Specified as a set of bit masks that can be logically ORed together.

HWND hWndReg

The window handle which is to be registered to receive the specified messages.

HWND hWnd

The window handle which is to receive the completion message for this request.

REQUESTID ReqID

Request identification number.

Mode Asynchronous

Comments WFPDeregister is used to cancel notifications. See WFSRegister.

Messages WFS_REGISTER_COMPLETE

Error 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.

WFS_ERR_CONNECTION_LOST
The connection to the service is lost.
WFS_ERR_INTERNAL_ERROR
An internal inconsistency or other unexpected error occurred in the WOSA/XFS subsystem.
WFS_ERR_INVALID_EVENT_CLASS
The dwEventClass parameter specifies one or more event classes not supported by the service.
WFS_ERR_INVALID_HSERVICE
The hService parameter is not a valid service handle.
WFS_ERR_INVALID_HWND
The hWnd parameter is not a valid window handle.
WFS_ERR_INVALID_HWNDREG
The hWndReg parameter is not a valid window handle.

The 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.

WFS_ERR_CANCELED
The request was canceled by WFSCancelAsyncRequest.
WFS_ERR_INTERNAL_ERROR
An internal inconsistency or other unexpected error occurred in the WOSA/XFS subsystem.


5.9 WFPSetTraceLevel

HRESULT WFPSetTraceLevel( hService, dwTraceLevel )

Sets the specified trace level(s) at run time, in and/or below the service provider. See WFMSetTraceLevel.

Parameters HSERVICE hService

Handle to the service provider.

DWORD dwTraceLevel

The level(s) of tracing being requested. See below.

Mode Immediate

Comments 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):

 WFS_TRACE_SPI 0x00000004

Trace 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.

 WFS_TRACE_ALL_SPI 0x00000008

Trace all SPI, notification and event activity of the service provider (the hService parameter is not relevant to this trace level).

Other 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.

Trace 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.

If 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,

This function has the highest priority to the service provider; it activates the trace as soon as possible.

WFPOpen also includes an option to set these trace levels, to allow the open process itself to be traced.

Error Codes If the function return is not WFS_SUCCESS, it is one of the following error conditions:

WFS_ERR_CONNECTION_LOST
The connection to the service is lost.
WFS_ERR_INTERNAL_ERROR
An internal inconsistency or other unexpected error occurred in the WOSA/XFS subsystem.
WFS_ERR_INVALID_HSERVICE
The hService parameter is not a valid service handle.
WFS_ERR_INVALID_TRACELEVEL
The dwTraceLevel parameter does not correspond to a valid trace level or set of levels.
WFS_ERR_NOT_STARTED
The application has not previously performed a successful WFSStartUp.
WFS_ERR_OP_IN_PROGRESS
A blocking operation is in progress on the thread; only WFSCancelBlockingCall and WFSIsBlocking are permitted at this time.

See Also WFMGetTraceLevel, WFSOpen, WFSAsyncOpen


5.10 WFPUnloadService

HRESULT WFPUnloadService( )

Asks the called service provider whether it is OK for the XFS Manager to unload the service provider’s DLL.

Parameters None

Mode Immediate

Comments 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.

Error Codes If the function return is not WFS_SUCCESS, it is one of the following error conditions:

WFS_ERR_NOT_OK_TO_UNLOAD
The 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.


5.11 WFPUnlock

HRESULT WFPUnlock( hService, hWnd, ReqID )

Releases a service that has been locked by a previous WFPLock function.

Parameters HSERVICE hService

Handle to the service provider

HWND hWnd

The window handle which is to receive the completion message for this request.

REQUESTID ReqID

Request identification number.

Mode Asynchronous

Comments See WFPLock, WFSLock, WFSUnlock and Section 3.9.

Messages WFS_UNLOCK_COMPLETE

Error 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.

WFS_ERR_CONNECTION_LOST
The connection to the service is lost.
WFS_ERR_INTERNAL_ERROR
An internal inconsistency or other unexpected error occurred in the WOSA/XFS subsystem.
WFS_ERR_INVALID_HSERVICE
The hService parameter is not a valid service handle.
WFS_ERR_INVALID_HWND
The hWnd parameter is not a valid window handle.

The 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.

WFS_ERR_CANCELED
The request was canceled by WFSCancelAsyncRequest.
WFS_ERR_INTERNAL_ERROR
An internal inconsistency or other unexpected error occurred in the WOSA/XFS subsystem.
WFS_ERR_NOT_LOCKED
The service to be unlocked is not locked under the calling hService.


6. Support Functions

Support 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.


6.1 WFMAllocateBuffer

HRESULT WFMAllocateBuffer( ulSize, ulFlags, lppvData )

Allocates a memory buffer for the service provider in which to return results.

Parameters ULONG ulSize

Size (in bytes) of the memory to be allocated.

ULONG ulFlags

Flags, see comments below.

LPVOID * lppvData

Address of the variable in which the XFS Manager will place the pointer to the allocated memory.

Comments 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:

WFS_MEM_SHARE Allocates shareable memory.

WFS_MEM_ZEROINIT Initializes memory contents to zero (not required in 32 bit Windows).

The application, XFS Manager or service provider then must, in turn, use the WFSFreeResult or WFMFreeBuffer functions to deallocate the memory.

Error Codes If the function return is not WFS_SUCCESS, it is one of the following error conditions:

WFS_ERR_INVALID_POINTER
A pointer parameter does not point to accessible memory.
WFS_ERR_OUT_OF_MEMORY
There is not enough memory available to satisfy the request.

See also WFMAllocateMore, WFMFreeBuffer, WFSFreeResult and Section 3.13.


6.2 WFMAllocateMore

HRESULT WFMAllocateMore( ulSize, lpvOriginal, lppvData )

Allocates a memory buffer, linking it to an previously allocated one.

Parameters ULONG ulSize

Size (in bytes) of the memory to be allocated

LPVOID lpvOriginal

Address of the original buffer to which the newly allocated buffer should be linked

LPVOID * lppvData

Address of the variable in which the XFS Manager will place the pointer to the newly allocated memory.

Comments 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).

Error Codes If the function return is not WFS_SUCCESS, it is one of the following error conditions:

WFS_ERR_INVALID_ADDRESS
The lpvOriginal parameter does not point to a previously allocated buffer.
WFS_ERR_INVALID_POINTER
A pointer parameter does not point to accessible memory.
WFS_ERR_OUT_OF_MEMORY
There is not enough memory available to satisfy the request.

See also WFMAllocateBuffer, WFMFreeBuffer, WFSFreeResult and Section 3.13.


6.3 WFMFreeBuffer

HRESULT WFMFreeBuffer( lpvData )

Releases the memory buffer(s) allocated by WFMAllocateBuffer and WFMAllocateMore.

Parameters LPVOID lpvData

Address of the memory buffer to free.

Comments 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.

Error Codes If the function return is not WFS_SUCCESS, it is one of the following error conditions:

WFS_ERR_INVALID_BUFFER
The lpvData parameter is not a pointer to an allocated buffer structure.
WFS_ERR_INVALID_POINTER
A pointer parameter does not point to accessible memory.

See also WFMAllocateBuffer, WFMAllocateMore, WFSFreeResult and Section 3.13.


6.4 WFMGetTraceLevel

HRESULT WFMGetTraceLevel( hService, lpdwTraceLevel )

Returns the trace level associated with the specified hService (at run time). See WFMSetTraceLevel.

Parameters HSERVICE hService

Handle to the service provider as returned by WFSOpen or WFSAsyncOpen.

LPDWORD lpdwTraceLevel

Pointer to the value defining the current trace level (returned parameter).

Mode Immediate

Comments This function returns the current tracing levels in the XFS Manager and the service provider specified by hService. See WFMSetTraceLevel.

Error Codes If the function return is not WFS_SUCCESS, it is one of the following error conditions:

WFS_ERR_INVALID_HSERVICE
The hService parameter is not a valid service handle.
WFS_ERR_INVALID_POINTER
A pointer parameter does not point to accessible memory.
WFS_ERR_NOT_STARTED
The application has not previously performed a successful WFSStartUp.
WFS_ERR_OP_IN_PROGRESS
A blocking operation is in progress on the thread; only WFSCancelBlockingCall and WFSIsBlocking are permitted at this time.

See Also WFMSetTraceLevel, WFSOpen, WFSAsyncOpen


6.5 WFMKillTimer

HRESULT WFMKillTimer(wTimerID )

Cancels the timer identified by the wTimerID parameter. Any pending WFS_TIMER_EVENT message associated with the timer is removed from the message queue.

Parameters WORD wTimerID

ID of the timer to be canceled.

Comments See WFMSetTimer.

Error Codes If the function return is not WFS_SUCCESS, it is the following error condition:

WFS_ERR_INVALID TIMER
The usTimerID parameter does not correspond to a currently active timer.


6.6 WFMOutputTraceData

HRESULT WFMOutputTraceData( lpszData )

Requests the XFS Manager to output the specified data to the current trace destination.

Parameters LPSTR lpszData

Pointer to a null-terminated string containing the trace data.

Comments 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.

Error Codes If the function return is not WFS_SUCCESS, it is the following error condition:

WFS_ERR_INVALID_POINTER
A pointer parameter does not point to accessible memory.


6.7 WFMReleaseDLL

HRESULT WFMReleaseDLL( hProvider )

Notifies the XFS Manager that the service provider is available to be unloaded from memory.

Parameters HPROVIDER hProvider

Handle to the service provider, obtained from the XFS Manager in the WFPOpen call.

Comments 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:

  • The service provider finishes processing the WFPClose for its last open session

  • The SP does appropriate cleanup (deallocating memory, killing separate threads, etc.)

  • The SP posts the WFS_CLOSE_COMPLETE message for the final close

  • The SP calls WFMReleaseDLL, and after the return from this call, does nothing other than return from the procedure that called WFMReleaseDLL

  • The XFS Manager calls WFPUnloadService, verifying that the SP is in fact still ready to be unloaded

  • If the SP says OK, the XFS Manager unloads the SP DLL

Error Codes If the function return is not WFS_SUCCESS, it is the following error condition:

WFS_ERR_INVALID_HPROVIDER
The hProvider parameter is not a valid provider handle.


6.8 WFMSetTimer

HRESULT WFMSetTimer( hWnd, lpContext, dwTimeVal, lpwTimerID )

Starts a system timer.

Parameters HWND hWnd

The window to which the requested timer message is to be posted.

LPVOID lpContext

Context pointer supplied by the service provider requesting the timer; may be NULL.

DWORD dwTimeVal

Timer value (in milliseconds).

LPWORD lpwTimerID

Pointer to the timer identifier (returned parameter).

Comments 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.

Error Codes If the function return is not WFS_SUCCESS, it is one of the following error conditions:

WFS_ERR_INVALID_HWND
The hWnd parameter is not a valid window handle.
WFS_ERR_INVALID_POINTER
A pointer parameter does not point to accessible memory.


6.9 WFMSetTraceLevel

HRESULT WFMSetTraceLevel( hService, dwTraceLevel )

Sets the specified trace level(s) at run time; to be used for debugging and testing purposes.

Parameters HSERVICE hService

Handle to the service provider as returned by WFSOpen or WFSAsyncOpen.

DWORD dwTraceLevel

The level(s) of tracing being requested. See below.

Mode Immediate

Comments Issuing WFMSetTraceLevel for a service enables tracing on that service at various levels. Five standard trace levels are predefined:

 WFS_TRACE_API 0x00000001

Trace all input and output parameters of all API function calls using the specified hService.

 WFS_TRACE_ALL_API 0x00000002

Trace 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.

 WFS_TRACE_SPI 0x00000004

Trace 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.

 WFS_TRACE_ALL_SPI 0x00000008

As 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.

 WFS_TRACE_MGR 0x00000010

Trace the support functions (WFMxxxxx) of the XFS Manager.

Other 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.

Trace 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.

If 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,

This 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.

WFSOpen and WFSAsyncOpen also include an option to set these trace levels, to allow the open process itself to be traced.

Error Codes If the function return is not WFS_SUCCESS, it is one of the following error conditions:

WFS_ERR_INVALID_HSERVICE
The hService parameter is not a valid service handle.
WFS_ERR_INVALID_TRACELEVEL
The dwTraceLevel parameter does not correspond to a valid trace level or set of levels.
WFS_ERR_NOT_STARTED
The application has not previously performed a successful WFSStartUp.
WFS_ERR_OP_IN_PROGRESS
A blocking operation is in progress on the thread; only WFSCancelBlockingCall and WFSIsBlocking are permitted at this time.

See Also WFMGetTraceLevel, WFPSetTraceLevel, WFSOpen, WFSAsyncOpen


7. Configuration Functions

See Section 3.7 for the overall discussion of configuration information. The configuration functions are used by service providers and applications to write and retrieve the configuration information for a WOSA/XFS subsystem, which is stored in a hierarchical structure called the XFS configuration registry. The structure and the functions are based on the Win32 Registry architecture and API functions, and are implemented in Windows NT and future versions of Windows using the Registry and the associated functions. For Win32s-based implementations on Windows 3.1 and Windows for Workgroups, a subset of the functionality described here will be available; see the SDK for the definition of this subset.

The logical structure of the configuration information is shown below.

The XFS Manager key has the following optional values:

  • TraceFile the name of the file containing trace data. If this value is not set in the configuration, trace data is written to the default file path\name C:\XFSTRACE.LOG.

  • ShareFilename the name of the memory mapped file used by the memory management functions of the XFS Manager.

  • ShareFilesize the size of the memory mapped file used by the memory management functions of the XFS Manager.

Some additional values could be also defined in the WOSA/XFS SDK release notes. Please refer to the related document for more information.

A logical service key has three mandatory values:

  • class the service class of the logical service. The standard values are described in the Service Class Definition Document and in the service class include files.

  • type the service type of the logical service; the standard values are in the SDK

  • provider the name of the service provider that provides the logical service
    (the key name of the corresponding service provider key)

A service provider key also has three mandatory values:

  • dllname the name of the file containing the service provider DLL

  • vendor_name the name of the supplier of this service provider

  • version the version number of this service provider
WOSA/XFS Registry Root Second Level Keys Third Level Keys Values
WOSA/XFS_ROOT

XFS_MANAGER

TraceFile=<path-name>\<trace-file- name>

ShareFilename=<path-name>\ <share-file-name>

ShareFilesize=<file size in bytes>

LOGICAL_SERVICES

<Logical Service Name>

class=<service class>

type=<service type>

provider=<provider name>

< optional values >

SERVICE_PROVIDERS

<Provider Name>

dllname=< DLL name>

vendor_name=<vendor name>

version=<version>

< optional values >

< other keys >


7.1 WFMCloseKey

HRESULT WFMCloseKey ( hKey )

Closes the specified key.

Parameters HKEY hKey

Handle to the currently open key that is to be closed.

Comments 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 WFS_CFG_HKEY_XFS_ROOT as value for hkey parameter).

Error Codes If the function return is not WFS_SUCCESS, it is the following error condition:

WFS_ERR_CFG_INVALID_HKEY
The specified hKey parameter does not correspond to a currently open key, or it is the XFS root.


7.2 WFMCreateKey

HRESULT WFMCreateKey ( hKey, lpszSubKey, phkResult, lpdwDisposition )

Creates a new key, or if the specified key exists, opens it.

Parameters HKEY hKey

Handle to a currently open key, or the predefined handle value:
WFS_CFG_HKEY_XFS_ROOT
The key opened or created by this function is a subkey of the key identified by this parameter.

LPSTR lpszSubKey

Pointer to a null-terminated string containing the name of the key to be created or opened.

PHKEY phkResult

Pointer to a variable that receives the handle of the created or opened key.

LPDWORD lpdwDisposition

Pointer to a variable that receives one of the disposition values:
WFS_CFG_CREATED_NEW_KEY
WFS_CFG_OPENED_EXISTING_KEY

Comments If this function creates a new key, it has no values. The WFMSetValue function is used to create values.

Error Codes If the function return is not WFS_SUCCESS, it is one of the following error conditions:

WFS_ERR_CFG_INVALID_HKEY
The specified hKey parameter does not correspond to a currently open key.
WFS_ERR_INVALID_POINTER
A pointer parameter does not point to accessible memory.


7.3 WFMDeleteKey

HRESULT WFMDeleteKey ( hKey, lpszSubKey )

Deletes the specified key. This function cannot delete a key that has subkeys.

Parameters HKEY hKey

Handle to a currently open key, or the predefined handle value:
WFS_CFG_HKEY_XFS_ROOT
The key specified by the lpszSubKey parameter must be a subkey of the key identified by this parameter.

LPSTR lpszSubKey

Pointer to a null-terminated string specifying the name of the key to be deleted.

Comments If this function succeeds, the specified key is removed from the configuration information. The entire key, including all its values, is removed.

Error Codes If the function return is not WFS_SUCCESS, it is one of the following error conditions.

WFS_ERR_CFG_INVALID_HKEY
The specified hKey parameter does not correspond to a currently open key.
WFS_ERR_CFG_INVALID_SUBKEY
The key specified by lpszSubKey does not exist.
WFS_ERR_CFG_KEY_NOT_EMPTY
The specified key has subkeys and cannot be deleted. The subkeys must be deleted first.
WFS_ERR_INVALID_POINTER
A pointer parameter does not point to accessible memory.


7.4 WFMDeleteValue

HRESULT WFMDeleteValue ( hKey, lpszValue )

Deletes the specified value (both name and data).

Parameters HKEY hKey

Handle to a currently open key, or the predefined handle value:
WFS_CFG_HKEY_XFS_ROOT

LPSTR lpszValue

Pointer to a null-terminated string specifying the name of the value to be deleted.

Comments The specified value is removed from the specified open key. The WFMSetValue function is used to create or modify values.

Error Codes If the function return is not WFS_SUCCESS, it is one of the following error conditions.

WFS_ERR_CFG_INVALID_HKEY
The specified hKey parameter does not correspond to a currently open key.
WFS_ERR_CFG_INVALID_VALUE
The specified value does not exist within the specified open key.
WFS_ERR_INVALID_POINTER
A pointer parameter does not point to accessible memory.


7.5 WFMEnumKey

HRESULT WFMEnumKey ( hKey, iSubKey, lpszName, lpcchName, lpftLastWrite )

Enumerates the subkeys of the specified open key. Retrieves information about one subkey each time it is called.

Parameters HKEY hKey

Handle to a currently open key, or the predefined handle value:
WFS_CFG_HKEY_XFS_ROOT
The keys enumerated by this function are subkeys of the key identified by this parameter.

DWORD iSubKey

The 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.

Because subkeys are not ordered, any new subkey will have an arbitrary index. This means that the function may return subkeys in any order.

LPSTR lpszName

Pointer to a buffer that receives the name of the subkey, including the terminating null character.

LPDWORD lpcchName

Pointer 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 the number of characters actually stored in the buffer, not including the terminating null character.

PFILETIME lpftLastWrite

Pointer 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):
typedef struct _FILETIME {
 DWORD  dwLowDateTime;
 DWORD  dwHighDateTime;
} FILETIME;

Comments While a program is using this function iteratively, it should not call any other configuration functions that would change the key being enumerated.

Error Codes If the function return is not WFS_SUCCESS, it is one of the following error conditions.

WFS_ERR_CFG_INVALID_HKEY
The specified hKey parameter does not correspond to a currently open key.
WFS_ERR_CFG_NO_MORE_ITEMS
There are no more subkeys to be returned (the iSubKey parameter is greater than the index of the last subkey).
WFS_ERR_CFG_NAME_TOO_LONG
The length of the name to be returned exceeds the length of the buffer.
WFS_ERR_INVALID_POINTER
A pointer parameter does not point to accessible memory.


7.6 WFMEnumValue

HRESULT WFMEnumValue ( hKey, iValue, lpszValue, lpcchValue, lpszData, lpcchData )

Enumerates the values of the specified open key. Retrieves the name and data for one value each time it is called.

Parameters HKEY hKey

Handle to a currently open key, or the predefined handle value:
WFS_CFG_HKEY_XFS_ROOT
The value enumerated by this function is a value of the key identified by this parameter.

DWORD iValue

The 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.

Because values are not ordered, any new value will have an arbitrary index. This means that the function may return values in any order.

LPSTR lpszValue

Pointer to a buffer that receives the name of the value, including the terminating null character.

LPDWORD lpcchValue

Pointer 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.

LPSTR lpszData

Pointer 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.

LPDWORD lpcchData

Pointer 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.

Comments While a program is using this function iteratively, it should not call any other configuration functions that would change the key being queried.

Error Codes If the function return is not WFS_SUCCESS, it is one of the following error conditions.

WFS_ERR_CFG_INVALID_HKEY
The specified hKey parameter does not correspond to a currently open key.
WFS_ERR_CFG_NO_MORE_ITEMS
There are no more values to be returned (the iValue parameter is greater than the index of the last value).
WFS_ERR_CFG_NAME_TOO_LONG
The length of the name to be returned exceeds the length of the buffer.
WFS_ERR_CFG_VALUE_TOO_LONG
The length of the value to be returned exceeds the length of the buffer.
WFS_ERR_INVALID_POINTER
A pointer parameter does not point to accessible memory.


7.7 WFMOpenKey

HRESULT WFMOpenKey ( hKey, lpszSubKey, phkResult )

Opens the specified key.

Parameters HKEY hKey

Handle to a currently open key, or the predefined handle value:
WFS_CFG_HKEY_XFS_ROOT
The key opened by this function is a subkey of the key identified by this parameter.

LPSTR lpszSubKey

Pointer 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).

PHKEY phkResult

Pointer to a variable that receives the handle of the opened key.

Comments In contrast with the WFMCreateKey function, this function does not create the specified key if it does not exist.

Error Codes If the function return is not WFS_SUCCESS, it is one of the following error conditions.

WFS_ERR_CFG_INVALID_HKEY
The specified hKey parameter does not correspond to a currently open key.
WFS_ERR_CFG_INVALID_SUBKEY
The key specified by lpszSubKey does not exist.
WFS_ERR_INVALID_POINTER
A pointer parameter does not point to accessible memory.


7.8 WFMQueryValue

HRESULT WFMQueryValue ( hKey, lpszValueName, lpszData, lpcchData )

Retrieves the data for the value with the specified name, within the specified open key.

Parameters HKEY hKey

Handle to a currently open key, or the predefined handle value:
WFS_CFG_HKEY_XFS_ROOT
The value data returned is within the key identified by this parameter.

LPSTR lpszValueName

Pointer to a null-terminated string containing the name of the value being queried.

LPSTR lpszData

Pointer to a buffer that receives the data for the value entry, including the terminating null character.

LPDWORD lpcchData

Pointer 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.

Comments

Error Codes If the function return is not WFS_SUCCESS, it is one of the following error conditions.

WFS_ERR_CFG_INVALID_HKEY
The specified hKey parameter does not correspond to a currently open key.
WFS_ERR_CFG_INVALID_NAME
The value specified by the lpszValueName parameter does not exist in the specified key.
WFS_ERR_CFG_VALUE_TOO_LONG
The length of the value to be returned exceeds the length of the buffer.
WFS_ERR_INVALID_POINTER
A pointer parameter does not point to accessible memory.


7.9 WFMSetValue

HRESULT WFMSetValue ( hKey, lpszValueName, lpszData, cchData )

Stores data in the specified value of the specified key. If the value does not exist, it is created.

Parameters HKEY hKey

Handle to a currently open key, or the predefined handle value:
WFS_CFG_HKEY_XFS_ROOT
The value set or created is within the key identified by this parameter.

LPSTR lpszValueName

Pointer 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.

LPSTR lpszData

Pointer to a buffer containing the data (a null-terminated character string) to be stored with the specified value name.

DWORD cchData

The size, in characters, of the string pointed to by the lpszData parameter, including the terminating null character.

Comments 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.

Error Codes If the function return is not WFS_SUCCESS, it is one of the following error conditions.

WFS_ERR_CFG_INVALID_HKEY
The specified hKey parameter does not correspond to a currently open key.
WFS_ERR_INVALID_POINTER
A pointer parameter does not point to accessible memory.


8. Data Structures


8.1 WFSRESULT

This structure has three functions:

  • It is the parameter which returns the results of the synchronous WFSLock, WFSExecute and WFSGetInfo commands.

  • 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.

  • It is pointed to by all event notification messages to deliver their contents.

Note 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.

typedef struct _wfs_result {
 REQUESTID RequestID;
 HSERVICE hService;
 TIMESTAMP tsTimestamp;
 HRESULT hResult;
 union {
  DWORD  dwCommandCode;
  DWORD  dwEventID;
 } u;
 LPVOID  lpBuffer;
} WFSRESULT, * LPWFSRESULT;

The members of this structure are:

Field Description

RequestID Request ID of the completed command; not used for event notifications other than Execute events

hService Service handle identifying the session that created the result

tsTimestamp Time the event occurred (local time, in a Win32 SYSTEMTIME structure)

hResult Result handle (note that for synchronous WFSExecute and WFSGetInfo commands, this value is identical to the synchronous function return value)

u.dwCommandCode WFSExecute “command” code or WFSGetInfo “category” code; not used for other command completions

u.dwEventID ID of the event (for unsolicited events)

lpBuffer Pointer to the results of the command (if any) or the contents of the event notification


8.2 WFSVERSION

This structure is used to return version information from WFSStartUp, WFSOpen and WFPOpen.

typedef  struct _wfsversion {
 WORD   wVersion;
 WORD   wLowVersion;
 WORD   wHighVersion;
 char   szDescription[WFSDDESCRIPTION_LEN+1];
 char   szSystemStatus[WFSDSYSSTATUS_LEN+1];
} WFSVERSION, *LPWFSVERSION;

The members of this structure are (note that this structure is used to report version information for three distinct WOSA/XFS interfaces: API, SPI, and the service-specific interface):

Element Usage

wVersion The version number to be used.

wLowVersion The lowest version number that the called DLL can support.

wHighVersion The highest version number that the called DLL can support.

szDescription 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.

szSystemStatus 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.


9. Messages

This section defines the Windows messages used in the WOSA/XFS subsystem.


9.1 Command Completions and Events

The following messages are sent to indicate:

  • the completion of an asynchronous command, or

  • the occurrence of an unsolicited event (execute, service, user, or system events).

All these messages have the same definition:
wParam: not used
lParam: points to a WFSRESULT data structure

WFS_<message_name>
wParam;   /*  not used  */
lParam = LPWFSRESULT lpWFSResult;


9.1.1 Command Completion Messages

WFS_OPEN_COMPLETE

WFS_CLOSE_COMPLETE

WFS_LOCK_COMPLETE

WFS_UNLOCK_COMPLETE

WFS_REGISTER_COMPLETE

WFS_DEREGISTER_COMPLETE

WFS_GETINFO_COMPLETE

WFS_EXECUTE_COMPLETE


9.1.2 Event Messages

WFS_EXECUTE_EVENT

WFS_SERVICE_EVENT

WFS_USER_EVENT

WFS_SYSTEM_EVENT


9.2 Timer Events

The timer event message has the following format (see WFMSetTimer, WFMKillTimer):

WFS_TIMER_EVENT
wParam  =  wTimerID; /* timer ID returned by the WFMSetTimer function */
lParam  =  lpContext; /* context pointer supplied by the service provider */
       /* that requested the timer; may be NULL */


9.3 Device Status Changes

Status 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 8.1) is utilized as follows:

Field Description

RequestID (not used)

hService Service handle identifying the session that created the result

tsTimestamp Time the status change occurred (local time, in a Win32 SYSTEMTIME structure)

hResult (not used)

u.dwEventID = WFS_SYSE_DEVICE_STATUS

lpBuffer Pointer to a WFSDEVSTATUS structure:

typedef struct wfs_devstatus {
 LPSTR   lpszPhysicalName;
 LPSTR   lpszWorkstationName;
 DWORD   dwState;
} WFSDEVSTATUS, * LPWFSDEVSTATUS;

The members of this structure are:

Field Description

lpszPhysicalName Pointer to the physical service name of the service that changed its state.

lpszWorkstationName Pointer to the name of the workstation in which the logical service name is defined.

dwState Specifies the new state of the physical device managed by the service as one of the following:

Value Meaning

WFS_STAT_DEVONLINE The device is online (i.e., powered on and operable).

WFS_STAT_DEVOFFLINE The device is offline (e.g., the operator has taken the device offline).

WFS_STAT_DEVPOWEROFF The device is powered off.

WFS_STAT_DEVNODEVICE There is no device connected.

WFS_STAT_DEVHWERROR The device is inoperable due to a hardware error.

WFS_STAT_DEVUSERERROR The device is inoperable because a person is preventing proper device operation.


9.4 Undeliverable Messages

If a command completion or event message cannot be delivered, it is reported as a system event. The WFSRESULT data structure (defined in Section 8.1) is utilized as follows:

Field Description

RequestID (not used)

hService Service handle identifying the session associated with the completion or event

tsTimestamp Time the event occurred (local time, in a Win32 SYSTEMTIME structure)

hResult (not used)

u.dwEventID = WFS_SYSE_UNDELIVERABLE_MSG

lpBuffer Pointer to a WFSUNDEVMSG structure:

typedef struct _wfs_undevmsg {
 LPSTR   lpszLogicalName;
 LPSTR   lpszWorkstationName;
 LPSTR   lpszAppID;
 DWORD   dwSize;
 LPBYTE   lpbDescription;
 DWORD   dwMsg;
 LPWFSRESULT lpWFSResult;
} WFSUNDEVMSG, * LPWFSUNDEVMSG;

The members of this structure are:

Field Description

lpszLogicalName Pointer to the logical service name of the service that generated the original undeliverable message

lpszWorkstationName Pointer to the the name of the workstation in which the logical service name is defined

lpszAppID Pointer to the the application ID associated with the session that generated the original message

dwSize The size in bytes of the following description

lpbDescription Pointer to a vendor-specific description of the reason why the message could not be delivered

dwMsg The message identifier of the original message

lpWFSResult Pointer to the WFSRESULT structure of the original message (which has the lpBuffer parameter set to NULL)


9.5 Application Disconnect

If the WOSA/XFS subsystem loses connection to an application, it closes the session (see Section 3.6) and generates this system event. The WFSRESULT data structure (defined in Section 8.1) is utilized as follows:

Field Description

RequestID (not used)

hService Service handle identifying the session associated with the event

tsTimestamp Time the event occurred (local time, in a Win32 SYSTEMTIME structure)

hResult (not used)

u.dwEventID = WFS_SYSE_APP_DISCONNECT

lpBuffer Pointer to a WFSAPPDISC structure:

typedef struct _wfs_appdisc {
 LPSTR   lpszLogicalName;
 LPSTR   lpszWorkstationName;
 LPSTR   lpszAppID;
} WFSAPPDISC, * LPWFSAPPDISC;

The members of this structure are:

Field Description

lpszLogicalName Pointer to the logical service name of the service that the application was connected to

lpszWorkstationName Pointer to the the name of the workstation in which the logical service name is defined

lpszAppID Pointer to the the application ID associated with the session that generated the event


9.6 Hardware and Software Errors

Hardware 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 the WFS_ERR_SOFTWARE_ERROR error code that is returned when a hardware or software error occurs in the course of executing a function. The WFSRESULT data structure (defined in Section 8.1), is utilized as follows:

Field Description

RequestID Request ID of the request being processed when the error occurred (if any)

hService Service handle identifying the session associated with the error (if any)

tsTimestamp Time the error occurred (local time, in a Win32 SYSTEMTIME structure)

hResult Result handle of the request being processed when the error occurred (if any)

u.dwEventID The ID of the error

Value Meaning

WFS_SYSE_HARDWARE_ERROR The error is a hardware error

WFS_SYSE_SOFTWARE_ERROR Th error is a software error

lpBuffer Pointer to a WFSHWERROR structure:

typedef struct _wfs_hwerror {
 LPSTR   lpszLogicalName;
 LPSTR   lpszWorkstationName;
 LPSTR   lpszAppID;
 DWORD   dwSize;
 LPBYTE   lpbDescription;
} WFSHWERROR, * LPWFSHWERROR;

The members of this structure are:

Field Description

lpszLogicalName Pointer to the logical service name of the service that generated the error (if any)

lpszWorkstationName Pointer to the the name of the workstation in which the logical service name is defined (if any)

lpszAppID Pointer to the application ID associated with the session that generated the error (if any)

dwSize The size in bytes of the following description

lpbDescription Pointer to a vendor-specific description of the error


9.7 Version Negotiation Failures

Failures 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 8.1) is utilized as follows:

Field Description

RequestID (not used)

hService (not used)

tsTimestamp Time the error occurred (local time, in a Win32 SYSTEMTIME structure)

hResult The version error code (e.g., WFS_ERR_SPI_VER_TOO_HIGH)

u.dwEventID = WFS_SYSE_VERSION_ERROR

lpBuffer Pointer to a WFSVRSNERROR structure:

typedef struct _wfs_vrsnerror {
 LPSTR   lpszLogicalName;
 LPSTR   lpszWorkstationName;
 LPSTR   lpszAppID;
 DWORD   dwSize;
 LPBYTE   lpbDescription;
 LPWFSVERSION lpWFSVersion;
} WFSVRSNERROR, * LPWFSVRSNERROR

The members of this structure are:

Field Description

lpszLogicalName Pointer to the logical service name of the service being opened (NULL if WFSStartUp)

lpszWorkstationName Pointer to the name of the workstation in which the application made the WFSStartUp or WFSOpen request

lpszAppID Pointer to the application ID from the open request that failed (NULL if WFSStartUp)

dwSize The size in bytes of the following description

lpbDescription Pointer to a vendor-specific description of the version negotiation failure

lpWFSVersion Pointer to the WFSVERSION structure reporting the results of the version negotiation


10. Error Codes

The following are the error codes that can be returned from a call to a WOSA/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.

WFS_ERR_ALREADY_STARTED

A WFSStartUp has already been issued by the application, without an intervening WFSCleanUp.

WFS_ERR_API_VER_TOO_HIGH

The range of versions of WOSA/XFS API support requested by the application is higher than any supported by this particular XFS Manager implementation.

WFS_ERR_API_VER_TOO_LOW

The range of versions of WOSA/XFS API support requested by the application is lower than any supported by this particular XFS Manager implementation.

WFS_ERR_CANCELED

The request was canceled by WFSCancelAsyncRequest or WFSCancelBlockingCall.

WFS_ERR_CFG_INVALID_HKEY

The specified hKey parameter does not correspond to a currently open key.

WFS_ERR_CFG_INVALID_NAME

The value specified by the lpszValueName parameter does not exist in the specified key.

WFS_ERR_CFG_INVALID_SUBKEY

The key specified by lpszSubKey does not exist.

WFS_ERR_CFG_INVALID_VALUE

The specified value does not exist within the specified open key.

WFS_ERR_CFG_KEY_NOT_EMPTY

The specified key has subkeys and cannot be deleted. The subkeys must be deleted first.

WFS_ERR_CFG_NAME_TOO_LONG

The length of the name to be returned exceeds the length of the buffer.

WFS_ERR_CFG_NO_MORE_ITEMS

There are no more subkeys to be returned (the iSubKey parameter is greater than the index of the last subkey).

WFS_ERR_CFG_VALUE_TOO_LONG

The length of the value to be returned exceeds the length of the buffer.

WFS_ERR_CONNECTION_LOST

The connection to the service is lost.

WFS_ERR_DEV_NOT_READY

The function required device access, and the device was not ready or timed out.

WFS_ERR_HARDWARE_ERROR

The function required device access, and an error occured on the device.

WFS_ERR_SOFTWARE_ERROR

The function required access to configuration information, and an error occured on the software.

WFS_ERR_INTERNAL_ERROR

An internal inconsistency or other unexpected error occurred in the WOSA/XFS subsystem.

WFS_ERR_INVALID_ADDRESS

The lpvOriginal parameter does not point to a previously allocated buffer.

WFS_ERR_INVALID_APP_HANDLE

The specified application handle is not valid, i.e., was not created by a preceding create call.

WFS_ERR_INVALID_BUFFER

The lpvData parameter is not a pointer to an allocated buffer structure.

WFS_ERR_INVALID_CATEGORY

The dwCategory issued is not supported by this service class.

WFS_ERR_INVALID_COMMAND

The dwCommand issued is not supported by this service class.

WFS_ERR_INVALID_EVENT_CLASS

The dwEventClass parameter specifies one or more event classes not supported by the service.

WFS_ERR_INVALID_HSERVICE

The hService parameter is not a valid service handle.

WFS_ERR_INVALID_HPROVIDER

The hProvider parameter is not a valid provider handle.

WFS_ERR_INVALID_HWND

The hWnd parameter is not a valid window handle.

WFS_ERR_INVALID_HWNDREG

The hWndReg parameter is not a valid window handle.

WFS_ERR_INVALID_POINTER

A pointer parameter does not point to accessible memory.

WFS_ERR_INVALID_DATA

The data structure passed as input parameter contains invalid data..

WFS_ERR_INVALID_REQ_ID

The RequestID parameter does not correspond to an outstanding request on the service.

WFS_ERR_INVALID_RESULT

The lpResult parameter is not a pointer to an allocated WFSRESULT structure.

WFS_ERR_INVALID_SERVPROV

The file containing the service provider is invalid or corrupted.

WFS_ERR_INVALID_TIMER

The hWnd and usTimerID parameters do not correspond to a currently active timer.

WFS_ERR_INVALID_TRACELEVEL

The dwTraceLevel parameter does not correspond to a valid trace level or set of levels.

WFS_ERR_LOCKED

The service is locked under a different hService.

WFS_ERR_NO_BLOCKING_CALL

There is no outstanding blocking call for the specified thread.

WFS_ERR_NO_SERVPROV

The file containing the service provider does not exist.

WFS_ERR_NO_SUCH_THREAD

The specified thread does not exist.

WFS_ERR_NO_TIMER

The timer could not be created.

WFS_ERR_NOT_LOCKED

The application requesting a service be unlocked had not previously performed a successful WFSLock or WFSAsyncLock.

WFS_ERR_NOT_OK_TO_UNLOAD

The XFS Manager may not unload the service provider DLL.

WFS_ERR_NOT_STARTED

The application has not previously performed a successful WFSStartUp.

WFS_ERR_NOT_REGISTERED

The specified hWndReg window was not registered to receive messages for any event classes.

WFS_ERR_OP_IN_PROGRESS

A blocking operation is in progress on the thread; only WFSCancelBlockingCall and WFSIsBlocking are permitted at this time.

WFS_ERR_OUT_OF_MEMORY

There is not enough memory available to satisfy the request.

WFS_ERR_SERVICE_NOT_FOUND

The logical name is not a valid service provider name.

WFS_ERR_SPI_VER_TOO_HIGH

The range of versions of WOSA/XFS SPI support requested by the XFS Manager is higher than any supported by the service provider for the logical service being opened.

WFS_ERR_SPI_VER_TOO_LOW

The range of versions of WOSA/XFS SPI support requested by the XFS Manager is lower than any supported by the service provider for the logical service being opened.

WFS_ERR_SRVC_VER_TOO_HIGH

The 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.

WFS_ERR_SRVC_VER_TOO_LOW

The 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.

WFS_ERR_TIMEOUT

The timeout interval expired.

WFS_ERR_UNSUPP_CATEGORY

The dwCategory issued, although valid for this service class, is not supported by this service provider.

WFS_ERR_UNSUPP_COMMAND

The dwCommand issued, although valid for this service class, is not supported by this service provider or device.

WFS_ERR_VERSION_ERROR_IN_SRVC

Within the service, a version mismatch of two modules occurred.


11. Appendix A - Planned Enhancements and Extensions

This section describes functions and facilities that are not fully defined in this version of the WOSA 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.

WOSA/XFS 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.

Also to be considered for future versions of WOSA/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. Whenever possible, the capabilities will be incorporated into the family of standard WOSA elements, and will utilize existing formal and de facto standards.

Another portion of the WOSA WOSA/XFS API set will deal with administration issues.


11.1 Event and System Management

The WOSA/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 3.11 and 9. 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.


12. Appendix B - Banking Solutions Vendor Council Contacts

Please submit comments and questions on the WOSA Extensions for Financial Services to any of the BSVC members or to:

Email: bsvc@microsoft.com

Fax (Europe): +49 6172 661 160 Attn: Ashley Steele

Mail: Banking Solutions Vendor Council Banking Solutions Vendor Council

Attn: John Michael Gross Attn: Ashley Steele

Microsoft Corporation Microsoft GmbH

One Microsoft Way 1/1174 Siemensstraße 21

Redmond, WA 98052 D 61352 Bad Homburg

USA Germany

Error reports maybe sent per email to: bsvchelp@microsoft.com

Updated versions of this specification, when released, may also be requested from these contacts.


13. Appendix C - Other WOSA Specifications and Information

The Windows Open Services Architecture and the individual WOSA elements each have one or more specifications or other documents either available or under development, and in most cases, an associated Software Development Kit (SDK). The WOSA specifications or other documents that may be requested include the ones listed below.

· WOSA Corporate Backgrounder [Microsoft part number 098-53420]

· WOSA Extensions for Financial Services [this document]

· Windows SNA API Specifications:

[all are included in the SDK for SNA Server for Windows NT, or orderable as part number 211-074-027]

· Windows LUA (RUI and SLI)

· Windows APPC

· Windows CPI-C

· Windows HLLAPI

· Windows CSV

· Windows Sockets Specification

· Windows RPC (Remote Procedure Call) Specification [included in the Windows NT SDK]

· ODBC (Open Database Connectivity) Specification [available as a set of Microsoft Press books]

· MAPI (Messaging API) Specification

· License Service API Specification

· Windows Telephony API Specification

· WOSA Extensions for Real Time Market Data Specification

Most of these documents are available in the Microsoft developer services sections on the Microsoft's Internet Informations Server www.microsoft.com, and via Internet ftp download from Microsoft's ftp server ftp.microsoft.com. They are all included in the Microsoft Developer Network (MSDN) products: the Development Platform (MSDN Level II subscription) and the Development Library (MSDN Level I subscription). The Development Platform is a set of CD-ROM disks, updated at least quarterly, that contains all Microsoft SDKs, DDKs and operating systems. This offering includes the MSDN Development Library, which is also available separately, and contains all the documentation for the development platform (but no code), as well as a wide variety of other technical reference material on developing software for the Windows operating systems, including sample code.


14. Appendix D - C-Header files


14.1 XFSAPI.H
/************************************************************************
*                                                                       *
* xfsapi.h      WOSA/XFS - API functions, types, and definitions        *
*                                                                       *
*               Version 2.00  --  11/11/96                              *
*                                                                       *
************************************************************************/

#ifndef __inc_xfsapi__h
#define __inc_xfsapi__h

#ifdef __cplusplus
extern "C" {
#endif

/*   be aware of alignment   */
#pragma pack(push,1)

/****** Common *********************************************************/

#include <windows.h>

typedef unsigned short USHORT;
typedef char CHAR;
typedef short SHORT;
typedef unsigned long ULONG;
typedef unsigned char UCHAR;
typedef SHORT * LPSHORT;
typedef LPVOID * LPLPVOID;
typedef ULONG * LPULONG;
typedef USHORT * LPUSHORT;

typedef ULONG REQUESTID;
typedef REQUESTID * LPREQUESTID;

typedef HANDLE HAPP;
typedef HAPP * LPHAPP;

typedef SYSTEMTIME TIMESTAMP;

typedef USHORT HSERVICE;
typedef HSERVICE * LPHSERVICE;

typedef LONG HRESULT;
typedef HRESULT * LPHRESULT;

typedef BOOL (WINAPI * XFSBLOCKINGHOOK)(VOID);
typedef XFSBLOCKINGHOOK * LPXFSBLOCKINGHOOK;

/****** String lengths **************************************************/

#define WFSDDESCRIPTION_LEN                     256
#define WFSDSYSSTATUS_LEN                       256

/****** Values of WFSDEVSTATUS.fwState **********************************/

#define WFS_STAT_DEVONLINE                      (0)
#define WFS_STAT_DEVOFFLINE                     (1)
#define WFS_STAT_DEVPOWEROFF                    (2)
#define WFS_STAT_DEVNODEVICE                    (3)
#define WFS_STAT_DEVHWERROR                     (4)
#define WFS_STAT_DEVUSERERROR                   (5)
#define WFS_STAT_DEVBUSY                        (6)

/****** Value of WFS_DEFAULT_HAPP ***************************************/

#define WFS_DEFAULT_HAPP                        (0)

/****** Data Structures *************************************************/

typedef struct _wfs_result
{
    REQUESTID       RequestID;
    HSERVICE        hService;
    TIMESTAMP       tsTimestamp;
    HRESULT         hResult;
    union {
        DWORD       dwCommandCode;
        DWORD       dwEventID;
    } u;
    LPVOID          lpBuffer;
} WFSRESULT, * LPWFSRESULT;

typedef struct _wfsversion
{
    WORD            wVersion;
    WORD            wLowVersion;
    WORD            wHighVersion;
    CHAR            szDescription[WFSDDESCRIPTION_LEN+1];
    CHAR            szSystemStatus[WFSDSYSSTATUS_LEN+1];
} WFSVERSION, * LPWFSVERSION;

/****** Message Structures **********************************************/

typedef struct _wfs_devstatus
{
    LPSTR           lpszPhysicalName;
    LPSTR           lpszWorkstationName;
    DWORD           dwState;
} WFSDEVSTATUS, * LPWFSDEVSTATUS;

typedef struct _wfs_undevmsg
{
    LPSTR           lpszLogicalName;
    LPSTR           lpszWorkstationName;
    LPSTR           lpszAppID;
    DWORD           dwSize;
    LPBYTE          lpbDescription;
    DWORD           dwMsg;
    LPWFSRESULT     lpWFSResult;
} WFSUNDEVMSG, * LPWFSUNDEVMSG;

typedef struct _wfs_appdisc
{
    LPSTR           lpszLogicalName;
    LPSTR           lpszWorkstationName;
    LPSTR           lpszAppID;
} WFSAPPDISC, * LPWFSAPPDISC;

typedef struct _wfs_hwerror
{
    LPSTR           lpszLogicalName;
    LPSTR           lpszWorkstationName;
    LPSTR           lpszAppID;
    DWORD           dwSize;
    LPBYTE          lpbDescription;
} WFSHWERROR, * LPWFSHWERROR;

typedef struct _wfs_vrsnerror
{
    LPSTR           lpszLogicalName;
    LPSTR           lpszWorkstationName;
    LPSTR           lpszAppID;
    DWORD           dwSize;
    LPBYTE          lpbDescription;
    LPWFSVERSION    lpWFSVersion;
} WFSVRSNERROR, * LPWFSVRSNERROR;

/****** Error codes ******************************************************/

#define WFS_SUCCESS                             (0)
#define WFS_ERR_ALREADY_STARTED                 (-1)
#define WFS_ERR_API_VER_TOO_HIGH                (-2)
#define WFS_ERR_API_VER_TOO_LOW                 (-3)
#define WFS_ERR_CANCELED                        (-4)
#define WFS_ERR_CFG_INVALID_HKEY                (-5)
#define WFS_ERR_CFG_INVALID_NAME                (-6)
#define WFS_ERR_CFG_INVALID_SUBKEY              (-7)
#define WFS_ERR_CFG_INVALID_VALUE               (-8)
#define WFS_ERR_CFG_KEY_NOT_EMPTY               (-9)
#define WFS_ERR_CFG_NAME_TOO_LONG               (-10)
#define WFS_ERR_CFG_NO_MORE_ITEMS               (-11)
#define WFS_ERR_CFG_VALUE_TOO_LONG              (-12)
#define WFS_ERR_DEV_NOT_READY                   (-13)
#define WFS_ERR_HARDWARE_ERROR                  (-14)
#define WFS_ERR_INTERNAL_ERROR                  (-15)
#define WFS_ERR_INVALID_ADDRESS                 (-16)
#define WFS_ERR_INVALID_APP_HANDLE              (-17)
#define WFS_ERR_INVALID_BUFFER                  (-18)
#define WFS_ERR_INVALID_CATEGORY                (-19)
#define WFS_ERR_INVALID_COMMAND                 (-20)
#define WFS_ERR_INVALID_EVENT_CLASS             (-21)
#define WFS_ERR_INVALID_HSERVICE                (-22)
#define WFS_ERR_INVALID_HPROVIDER               (-23)
#define WFS_ERR_INVALID_HWND                    (-24)
#define WFS_ERR_INVALID_HWNDREG                 (-25)
#define WFS_ERR_INVALID_POINTER                 (-26)
#define WFS_ERR_INVALID_REQ_ID                  (-27)
#define WFS_ERR_INVALID_RESULT                  (-28)
#define WFS_ERR_INVALID_SERVPROV                (-29)
#define WFS_ERR_INVALID_TIMER                   (-30)
#define WFS_ERR_INVALID_TRACELEVEL              (-31)
#define WFS_ERR_LOCKED                          (-32)
#define WFS_ERR_NO_BLOCKING_CALL                (-33)
#define WFS_ERR_NO_SERVPROV                     (-34)
#define WFS_ERR_NO_SUCH_THREAD                  (-35)
#define WFS_ERR_NO_TIMER                        (-36)
#define WFS_ERR_NOT_LOCKED                      (-37)
#define WFS_ERR_NOT_OK_TO_UNLOAD                (-38)
#define WFS_ERR_NOT_STARTED                     (-39)
#define WFS_ERR_NOT_REGISTERED                  (-40)
#define WFS_ERR_OP_IN_PROGRESS                  (-41)
#define WFS_ERR_OUT_OF_MEMORY                   (-42)
#define WFS_ERR_SERVICE_NOT_FOUND               (-43)
#define WFS_ERR_SPI_VER_TOO_HIGH                (-44)
#define WFS_ERR_SPI_VER_TOO_LOW                 (-45)
#define WFS_ERR_SRVC_VER_TOO_HIGH               (-46)
#define WFS_ERR_SRVC_VER_TOO_LOW                (-47)
#define WFS_ERR_TIMEOUT                         (-48)
#define WFS_ERR_UNSUPP_CATEGORY                 (-49)
#define WFS_ERR_UNSUPP_COMMAND                  (-50)
#define WFS_ERR_VERSION_ERROR_IN_SRVC           (-51)
#define WFS_ERR_INVALID_DATA                    (-52)
#define WFS_ERR_SOFTWARE_ERROR                  (-53)
#define WFS_ERR_CONNECTION_LOST                 (-54)

#define WFS_INDEFINITE_WAIT                     0

/****** Messages ********************************************************/

/* Message-No = (WM_USER + No) */

#define WFS_OPEN_COMPLETE                       (WM_USER + 1)
#define WFS_CLOSE_COMPLETE                      (WM_USER + 2)
#define WFS_LOCK_COMPLETE                       (WM_USER + 3)
#define WFS_UNLOCK_COMPLETE                     (WM_USER + 4)
#define WFS_REGISTER_COMPLETE                   (WM_USER + 5)
#define WFS_DEREGISTER_COMPLETE                 (WM_USER + 6)
#define WFS_GETINFO_COMPLETE                    (WM_USER + 7)
#define WFS_EXECUTE_COMPLETE                    (WM_USER + 8)

#define WFS_EXECUTE_EVENT                       (WM_USER + 20)
#define WFS_SERVICE_EVENT                       (WM_USER + 21)
#define WFS_USER_EVENT                          (WM_USER + 22)
#define WFS_SYSTEM_EVENT                        (WM_USER + 23)

#define WFS_TIMER_EVENT                         (WM_USER + 100)

/****** Event Classes ***************************************************/

#define SERVICE_EVENTS                          (1)
#define USER_EVENTS                             (2)
#define SYSTEM_EVENTS                           (4)
#define EXECUTE_EVENTS                          (8)

/****** System Event IDs ************************************************/

#define WFS_SYSE_UNDELIVERABLE_MSG              (1)
#define WFS_SYSE_HARDWARE_ERROR                 (2)
#define WFS_SYSE_VERSION_ERROR                  (3)
#define WFS_SYSE_DEVICE_STATUS                  (4)
#define WFS_SYSE_APP_DISCONNECT                 (5)

/****** WOSA/XFS Trace Level ********************************************/

#define WFS_TRACE_API                           0x00000001
#define WFS_TRACE_ALL_API                       0x00000002
#define WFS_TRACE_SPI                           0x00000004
#define WFS_TRACE_ALL_SPI                       0x00000008
#define WFS_TRACE_MGR                           0x00000010

/****** API functions ***************************************************/

HRESULT extern WINAPI WFSCancelAsyncRequest ( HSERVICE hService, REQUESTID RequestID);

HRESULT extern WINAPI WFSCancelBlockingCall ( DWORD dwThreadID);

HRESULT extern WINAPI WFSCleanUp ();

HRESULT extern WINAPI WFSClose ( HSERVICE hService);

HRESULT extern WINAPI WFSAsyncClose ( HSERVICE hService, HWND hWnd, LPREQUESTID lpRequestID);

HRESULT extern WINAPI WFSCreateAppHandle ( LPHAPP lphApp);

HRESULT extern WINAPI WFSDeregister ( HSERVICE hService, DWORD dwEventClass, HWND hWndReg);

HRESULT extern WINAPI WFSAsyncDeregister ( HSERVICE hService, DWORD dwEventClass, HWND hWndReg, HWND hWnd, LPREQUESTID lpRequestID);

HRESULT extern WINAPI WFSDestroyAppHandle ( HAPP hApp);

HRESULT extern WINAPI WFSExecute ( HSERVICE hService, DWORD dwCommand, LPVOID lpCmdData, DWORD dwTimeOut, LPWFSRESULT * lppResult);

HRESULT extern WINAPI WFSAsyncExecute ( HSERVICE hService, DWORD dwCommand, LPVOID lpCmdData, DWORD dwTimeOut, HWND hWnd, LPREQUESTID lpRequestID);

HRESULT extern WINAPI WFSFreeResult ( LPWFSRESULT lpResult);

HRESULT extern WINAPI WFSGetInfo ( HSERVICE hService, DWORD dwCategory, LPVOID lpQueryDetails, DWORD dwTimeOut, LPWFSRESULT * lppResult);

HRESULT extern WINAPI WFSAsyncGetInfo ( HSERVICE hService, DWORD dwCategory, LPVOID lpQueryDetails, DWORD dwTimeOut, HWND hWnd, LPREQUESTID lpRequestID);

BOOL extern WINAPI WFSIsBlocking ();

HRESULT extern WINAPI WFSLock ( HSERVICE hService, DWORD dwTimeOut , LPWFSRESULT * lppResult);

HRESULT extern WINAPI WFSAsyncLock ( HSERVICE hService, DWORD dwTimeOut, HWND hWnd,  LPREQUESTID lpRequestID);

HRESULT extern WINAPI WFSOpen ( LPSTR lpszLogicalName, HAPP hApp, LPSTR lpszAppID, DWORD dwTraceLevel, DWORD dwTimeOut, DWORD dwSrvcVersionsRequired, LPWFSVERSION lpSrvcVersion, LPWFSVERSION lpSPIVersion, LPHSERVICE lphService);

HRESULT 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);

HRESULT extern WINAPI WFSRegister ( HSERVICE hService, DWORD dwEventClass, HWND hWndReg);

HRESULT extern WINAPI WFSAsyncRegister ( HSERVICE hService, DWORD dwEventClass, HWND hWndReg, HWND hWnd, LPREQUESTID lpRequestID);

HRESULT extern WINAPI WFSSetBlockingHook ( XFSBLOCKINGHOOK lpBlockFunc, LPXFSBLOCKINGHOOK lppPrevFunc);

HRESULT extern WINAPI WFSStartUp ( DWORD dwVersionsRequired, LPWFSVERSION lpWFSVersion);

HRESULT extern WINAPI WFSUnhookBlockingHook ();

HRESULT extern WINAPI WFSUnlock ( HSERVICE hService);

HRESULT extern WINAPI WFSAsyncUnlock ( HSERVICE hService, HWND hWnd, LPREQUESTID lpRequestID);

HRESULT extern WINAPI WFMSetTraceLevel ( HSERVICE hService, DWORD dwTraceLevel);

/*   restore alignment   */
#pragma pack(pop)

#ifdef __cplusplus
}       /*extern "C"*/
#endif

#endif  /* __inc_xfsapi__h */


14.2 XFSADMIN.H
/******************************************************************************
*                                                                             *
* xfsadmin.h    WOSA/XFS-Administration and Support functions                 *
*                                                                             *
*               Version 2.00  --  11/11/96                                    *
*                                                                             *
******************************************************************************/

#ifndef __INC_XFSADMIN__H
#define __INC_XFSADMIN__H

#ifdef __cplusplus
extern "C" {
#endif

#include    <xfsapi.h>

/*   be aware of alignment   */
#pragma pack(push,1)

/* values of ulFlags used for WFMAllocateBuffer */

#define WFS_MEM_SHARE                        0x00000001
#define WFS_MEM_ZEROINIT                    0x00000002

/****** Support Functions ****************************************************/

HRESULT extern WINAPI WFMAllocateBuffer( ULONG ulSize, ULONG ulFlags, LPVOID * lppvData);

HRESULT extern WINAPI WFMAllocateMore( ULONG ulSize, LPVOID lpvOriginal, LPVOID * lppvData);

HRESULT extern WINAPI WFMFreeBuffer( LPVOID lpvData);

HRESULT extern WINAPI WFMGetTraceLevel ( HSERVICE hService, LPDWORD lpdwTraceLevel);

HRESULT extern WINAPI WFMKillTimer( WORD wTimerID);

HRESULT extern WINAPI WFMOutputTraceData ( LPSTR lpszData);

HRESULT extern WINAPI WFMReleaseDLL ( HPROVIDER hProvider);

HRESULT extern WINAPI WFMSetTimer ( HWND hWnd, LPVOID lpContext, DWORD dwTimeVal, LPWORD lpwTimerID);

/*   restore alignment   */
#pragma pack(pop)

#ifdef __cplusplus
}       /*extern "C"*/
#endif

#endif    /* __INC_XFSADMIN__H */


14.3 XFSCONF.H
/******************************************************************************
*                                                                             *
* xfsconf.h     WOSA/XFS - definitions for the Configuration functions        *
*                                                                             *
*               Version 2.00  --  11/11/96                                    *
*                                                                             *
******************************************************************************/

#ifndef __INC_XFSCONF__H
#define __INC_XFSCONF__H

#ifdef __cplusplus
extern "C" {
#endif

/******* Common **************************************************************/

#include    <xfsapi.h>

/*   be aware of alignment   */
#pragma pack(push,1)

// following HKEY and PHKEY are already defined in WINREG.H
// so definition has been removed
// typedef HANDLE  HKEY;
// typedef HANDLE * PHKEY;

/******* Value of hKey *******************************************************/
#define     WFS_CFG_HKEY_XFS_ROOT               ((HKEY)1)

/******* Values of lpdwDisposition *******************************************/
#define     WFS_CFG_CREATED_NEW_KEY             (0)
#define     WFS_CFG_OPENED_EXISTING_KEY         (1)

/******* Configuration Functions *********************************************/
HRESULT extern  WINAPI  WFMCloseKey ( HKEY hKey);

HRESULT extern  WINAPI  WFMCreateKey ( HKEY hKey, LPSTR lpszSubKey, PHKEY phkResult, LPDWORD lpdwDisposition);

HRESULT extern  WINAPI  WFMDeleteKey ( HKEY hKey, LPSTR lpszSubKey);

HRESULT extern  WINAPI  WFMDeleteValue ( HKEY hKey, LPSTR lpszValue );

HRESULT extern  WINAPI  WFMEnumKey ( HKEY hKey, DWORD iSubKey, LPSTR lpszName, LPDWORD lpcchName, PFILETIME lpftLastWrite);

HRESULT extern  WINAPI  WFMEnumValue ( HKEY hKey, DWORD iValue, LPSTR lpszValue, LPDWORD lpcchValue, LPSTR lpszData, LPDWORD lpcchData);

HRESULT extern  WINAPI  WFMOpenKey ( HKEY hKey, LPSTR lpszSubKey, PHKEY phkResult);

HRESULT extern  WINAPI  WFMQueryValue ( HKEY hKey, LPSTR lpszValueName, LPSTR lpszData, LPDWORD lpcchData);

HRESULT extern  WINAPI  WFMSetValue ( HKEY hKey, LPSTR lpszValueName, LPSTR lpszData, DWORD cchData);

/*   restore alignment   */
#pragma pack(pop)

#ifdef __cplusplus
}       /*extern "C"*/
#endif

#endif  /* __INC_XFSCONF__H */


14.4 XFSSPI.H
/******************************************************************************
*                                                                             *
* xfsspi.h      WOSA/XFS - SPI functions, types, and definitions              *
*                                                                             *
*               Version 2.00  --  11/11/96                                    *
*                                                                             *
******************************************************************************/

#ifndef __inc_xfsspi__h
#define __inc_xfsspi__h

#ifdef __cplusplus
extern "C" {
#endif

#include <xfsapi.h>

typedef HANDLE HPROVIDER;

#include <xfsconf.h>
#include <xfsadmin.h>

/*   be aware of alignment   */
#pragma pack(push,1)

/****** SPI functions ********************************************************/

HRESULT extern WINAPI WFPCancelAsyncRequest ( HSERVICE hService, REQUESTID RequestID);

HRESULT extern WINAPI WFPClose ( HSERVICE hService, HWND hWnd, REQUESTID ReqID);

HRESULT extern WINAPI WFPDeregister ( HSERVICE hService, DWORD dwEventClass, HWND hWndReg, HWND hWnd, REQUESTID ReqID);

HRESULT extern WINAPI WFPExecute ( HSERVICE hService, DWORD dwCommand, LPVOID lpCmdData, DWORD dwTimeOut, HWND hWnd, REQUESTID ReqID);

HRESULT extern WINAPI WFPGetInfo ( HSERVICE hService, DWORD dwCategory, LPVOID lpQueryDetails, DWORD dwTimeOut, HWND hWnd, REQUESTID ReqID);

HRESULT extern WINAPI WFPLock ( HSERVICE hService, DWORD dwTimeOut, HWND hWnd, REQUESTID ReqID);

HRESULT 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);

HRESULT extern WINAPI WFPRegister ( HSERVICE hService,  DWORD dwEventClass, HWND hWndReg, HWND hWnd, REQUESTID ReqID);

HRESULT extern WINAPI WFPSetTraceLevel ( HSERVICE hService, DWORD dwTraceLevel);

HRESULT extern WINAPI WFPUnloadService (  );

HRESULT extern WINAPI WFPUnlock ( HSERVICE hService, HWND hWnd, REQUESTID );

/*   restore alignment   */
#pragma pack(pop)

#ifdef __cplusplus
}    /*extern "C"*/
#endif

#endif  /* __inc_xfsspi__h */


WOSA

(Windowsä Open Services Architecture)

Extensions for Financial Services

A Client-Server Architecture for
Financial Enterprise Computing under Microsoft® Windows

Service Classes Definition

–––––––––––––––––––––––––––––––––––

Programmer’s Reference

Revision 2.00

November 11, 1996

Developed by the members of the Banking Solutions Vendor Council


Table of Contents

1. Introduction

2. Service Classes

2.1. Printers

2.2. Identification Card Units

2.3. Cash Dispensers

2.4. Personal Identification Number Keypads (PIN Pads)

2.5. Check Readers and Scanners

2.6. Depository Unit

2.7. Text Terminal Unit

2.8. Sensors and Indicators Units

2.9. Vendor Dependent Mode

2.10. Cameras

3. Planned Enhancements and Extensions


1. Introduction

This is revision 2.0 of the API/SPI specification for the Windows Open Services Architecture, Extensions for Financial Services (WOSA/XFS). The other relevant specifications are the service class specifications. These specifications are part of the Software Development Kit (SDK), which supplies the components and tools to allow the implementation of compliant applications and services. These specifications are distributed to the financial services community for continuing review and comment, to allow them to provide input to the ongoing enhancement of WOSA/XFS.

Release 2.0 extends the scope of WOSA/XFS to include both the self service/ATM environment as well as the branch environment. The new specification now fully supports cameras, deposit units, identification cards, PIN pads, sensors and indicator units, text terminals, cash dispenser modules and a wide variety of printing mechanisms.

The members of the Banking Solutions Vendor Council encourage banks and other financial service companies world-wide, as well as other technology suppliers, to get updated information on the status of the project, and to submit comments, questions and requests for the specification and SDK. This may be done via one of the council members or via the Microsoft web site :

www.microsoft.com/industry/bank.

The Banking Solutions Vendor Council is accepting applications for affiliate membership; interested parties should contact one of the council members or send email to bsvc@microsoft.com.

The Banking Solutions Vendor Council, an organisation of leading vendors of information technology to the financial services industry, was formally announced at the American Bankers Association National Operations and Automation Conference (NOAC) in Denver on May 18, 1992.

Revision 1.11 of the WOSA/XFS specifications was released on February 3, 1995. It includes the programmer’s reference specifications for the Application Programming Interface (API) and Service Provider Interface (SPI) and five service classes specifications: printers, magnetic stripe readers/writers, PIN pads, cash dispensers and check readers.

In October 1995, the BSVC established the self-service workgroup (SSWG) to define self-service specific enhancements to existing WOSA/XFS service class specifications and to develop new self-service specific WOSA/XFS service class specifications.

A new WOSA/XFS service class needs to be defined with a unique name in the configuration information and with a unique service identifier in its header file(s).

Rather than updating the API/SPI specifications each time a new service class is defined, the SSWG established that a new document should be developed that aggregates the unique values needed to define a service class. This document serves that purpose.

All explicit references to device or service classes have then been expurgated from revision 2.00 of the API/SPI specifications and replaced with references to this document.


2. Service Classes

The following classes of services have been defined for the second version of the WOSA Extensions for Financial Services to include the data and methods needed for the support of self-service, unattended, operations:

  • Printers

  • Identification Card Units

  • Cash Dispensers

  • Personal Identification Number Keypads (PIN pads)

  • Depository Units

  • Text Terminal Units

  • Sensors and Indicators Units

  • Vendor Dependent Mode

  • Cameras

The following sections detail for each of the service classes defined for this version of the WOSA Extensions for Financial Services:

  • the standard values to be used as class attribute in the configuration information;

  • the unique number assigned to each service class;

  • the types of devices defined and supported by the service class specifications.

The table below summarises the unique attributes of each service class:

Service Class Class Name Class Identifier
Printers
PTR
 1
Identification Card Units
IDC
 2
Cash Dispensers
CDM
 3
PIN pads
PIN
 4
Check Readers and Scanners
CHK
 5
Depository Units
DEP
 6
Text Terminal Units
TTU
 7
Sensors and Indicators Units
SIU
 8
Vendor Dependent Mode
VDM
 9
Cameras
CAM
 10


2.1. Printers

Class Name PTR

Class Identifier WFS_SERVICE_CLASS_PTR = 1

The WOSA/XFS printer service defines and supports four types of banking printers through a common interface:

· Receipt Printer

The receipt printer is used to print cut sheet documents. It may or may not require insert or eject operations, and often includes an operator identification device, e.g., Teller A and Teller B lights, for shared operation.

· Journal Printer

The journal is a continuous form device used to record a hardcopy audit trail of transactions, and for certain report printing requirements.

· Passbook Printer

The passbook device is physically and functionally the most complex printer. The WOSA/XFS definition supports automatic positioning of the book, as well as read/write capability for an optional integrated magnetic stripe. The implementation also manages the book geometry - i.e. the margins and centrefolds - presenting the simplest possible application interface while delivering the full range of functionality.

· Document Printer

Document printing is similar to receipt printing -- a set of fields are positioned on an inserted sheet of paper -- but the focus is on full-size forms. It should be noted that the WOSA/XFS environment only implements the printing of text fields from the application. The electronic printing of the form image itself is not supported; but can be delivered as an added-value extension by the vendor.

Additional hardware components, like scanners, stripe readers, OCR readers, and stamps, normally attached directly to the printer are also controlled through this interface.


2.2. Identification Card Units

Class Name IDC

Class Identifier WFS_SERVICE_CLASS_IDC = 2

The WOSA/XFS Identification Card service allows for the operation of the following categories of units:

  • motor driven card reader/writer

  • pull through card reader (writing facilities only partially included)

  • dip reader

  • contactless chip card readers
The following tracks/chips and the corresponding international standards are taken into account:
Track 1 ISO 7811

Track 2 ISO 7811

Track 3 ISO 7811 / ISO 4909

Chip (contacted) ISO 7816

Chip (contactless) ISO 10536.

National standards like Transac for France or Watermark for Sweden are not considered, but can be easily included via a forms mechanism.

In addition to the pure reading of the tracks mentioned above, security boxes can be used via this service to check the data of writable tracks for manipulation. These boxes (such as CIM or MM) are sensor-equipped devices that are able to check some other information on the card and compare it with the track data.


2.3. Cash Dispensers

Class Name CDM

Class Identifier WFS_SERVICE_CLASS_CDM = 3

The WOSA/XFS Cash Dispenser service definition applies to both Automated Teller Safes (ATS) and Automated Teller Machines (ATM).

The components of an Automated Teller Safe are a cash (bills) dispenser, a transport unit, an output unit, and in some cases it also contains a coin dispenser and an alert unit.

An Automated Teller Machine contains the modules for cash dispensing plus additional modules such as magnetic card reader/writer, PIN pad, terminal, etc. The modules used for cash dispensing are essentially the same as those contained in the ATS: a bill/coupon/document dispenser, a transport module, an output module, and a coin dispenser, if available. Therefore, the cash dispensing functionality of the ATS and of the ATM is included in a single service class definition, referred to in WOSA/XFS specifications as “CDM” (cash dispenser module).

The implementation of the individual commands is device dependent (ATS or ATM). This is described in the documentation of each function.


2.4. Personal Identification Number Keypads (PIN Pads)

Class Name PIN

Class Identifier WFS_SERVICE_CLASS_PIN = 4

The WOSA/XFS PIN pad service defines the general interface for the following functions:

  • Administration of encryption devices

  • Loading of encryption keys

  • Encryption / decryption

  • Entering Personal Identification Numbers (PINs)

  • PIN verification

  • PIN block generation (encrypted PIN)

  • Clear text data handling

  • Function key handling

  • PIN presentation to chip card

If the PIN Pad device has local display capability, display handling should be handled using the Text Terminal Unit (TTU) interface.

The current revision of the service class specification does not claim to adhere to any security standards, any security standards supported will be vendor dependent.

Important Notes:

  • The current revision of the service class specification does not define key management procedures; key management is vendor-specific.

  • Key space management is customer-specific, and is therefore handled by vendor-specific mechanisms.

  • Only numeric PIN pads are handled in the current revision of the service class specifications.


2.5. Check Readers and Scanners

Class Name CHK

Class Identifier WFS_SERVICE_CLASS_CHK = 5

This service class is currently defined only for attended branch service.

The WOSA/XFS check reader service defines the general interface for the following functions:

  • Reading encoded fields on a check, using Magnetic Ink Character Recognition (MICR) or Optical Character Recognition (OCR), or both;

  • Encoding fields on a check, using MICR or OCR fonts, or both;

  • Endorsing checks on either side, or both sides;

  • Acquiring an image of either side of the check, or both sides;

  • Sorting a check into one of several pockets.

This allows handling of devices with a range of features, from small hand-held read-only devices through which checks are manually swiped one at a time, to much larger tabletop devices which automatically feed checks by the batch past a reader, an encoder, an endorser, an optional image scanner, to be sorted into one of several pockets. The high end device of this class usually found in bank branches share many capabilities with the still larger devices usually found only in a bank’s central data processing, known as high-speed reader/sorters, but the latter are not specifically addressed in the current revision of the specifications.

Typical fields found encoded on a check include the bank ID number and the account number. Part of the processing done by the bank is to also encode the amount on the check, usually done by having an operator enter the hand-written or typewritten face amount on a numeric keypad, or by courtesy amount readers.


2.6. Depository Unit

Class Name DEP

Class Identifier WFS_SERVICE_CLASS_DEP = 6

The WOSA/XFS depository service defines and supports two types of depository modules through a common interface:

  • Envelope depository for the deposit of media in envelopes;

  • Night Safe depository for the deposit of bags containing bulk media.

An envelope depository accepts media, prints on the media and deposits the media into a holding container or bin. Some envelope depositories offer the capability to dispense an envelope to the customer at the start of a transaction. The customer takes this envelope, fills in the deposit media, possibly inscribes it and puts it into the deposit slot. The envelope is then accepted, printed and transported into a deposit container.

The envelope dispense mechanism may be part of the envelope depository device mechanism with the same entry/exit slot or it may be a separate mechanism with separate entry/exit slot.

Envelopes dispensed and not taken by the customer can be retracted back into the device. When the dispenser is a separate mechanism the envelope is retracted back into the dispenser container. When the dispenser is a common mechanism the envelope is retracted into the depository container.

A night safe depository normally only logs the deposit of a bag and does not print on the media.


2.7. Text Terminal Unit

Class Name TTU

Class Identifier WFS_SERVICE_CLASS_TTU = 7

The WOSA/XFS Text Terminal service defines the functions provided by a generic Text Terminal Unit (TTU).

A Text Terminal Unit is a text i/o device, which applies both to ATM operator panels and to displays incorporated in devices such as PIN pads and printers. This service allows for the following categories of functions:

  • Forms oriented input and output

  • Direct display output

  • Keyboard input

  • LED settings and control


2.8. Sensors and Indicators Units

Class Name SIU

Class Identifier WFS_SERVICE_CLASS_SIU = 8

The WOSA/XFS sensors and indicators service allows for the operation of the following categories of ports:

  • Door sensors, such as cabinet, safe or vandal shield doors;

  • Alarm sensors, such as tamper, seismic or heat sensors;

  • Generic sensors, such as proximity or ambient light sensors;

  • Key switch sensors, such as the ATM operator switch;

  • Lamp/sign indicators, such as fascia light or audio indicators;

  • Auxiliary indicators.

In self-service devices, the sensors and indicators unit is capable of dealing with external sensors, such as door switches, locks, alarms and proximity sensors, as well as external indicators, such as turning on lamps or heating.


2.9. Vendor Dependent Mode

Class Name VDM

Class Identifier WFS_SERVICE_CLASS_VDM = 9

In all device classes there needs to be some method of going into a vendor specific mode to allow for capabilities which go beyond the scope of the current WOSA/XFS specifications. A typical usage of such a mode might be to handle some configuration or diagnostic type of function or perhaps perform some 'off-line' testing of the device. These functions are normally available on self-service devices in a mode traditionally referred to as Maintenance Mode or Supervisor Mode and usually require operator intervention. It is those vendor-specific functions not covered by (and not required to be covered by) WOSA/XFS Service Providers that will be available once the device is in Vendor-Dependent mode.

The Vendor Dependent Mode service provides the mechanism for switching to and from Vendor Dependent Mode. The VDM Service Provider can be seen as the central point through which all Enter and Exit VDM requests are synchronised.

Entry into, or exit from, Vendor Dependent Mode can be initiated either by an application or by the VDM Service Provider itself. If initiated by an application, then this application needs to issue the appropriate command to request entry or exit. If initiated by the VDM Service Provider i.e. some vendor dependent switch, then these request commands are in-appropriate and not issued.

Once the entry request has been made, all registered applications will be notified of the entry request by an event message. These applications must attempt to close all open sessions with WOSA/XFS Service Providers as soon as possible and then issue an acknowledgement command to the VDM Service Provider when ready. Once all applications have acknowledged, the VDM Service Provider will issue event messages to these applications to indicate that the System is in Vendor Dependent Mode.

Similarly, once the exit request has been made all registered applications will be notified of the exit request by an event message. These applications must then issue an acknowledgement command to the VDM Service Provider immediately. Once all applications have acknowledged, the VDM Service Provider will issue event messages to these applications to indicate that the System has exited from Vendor Dependent Mode.

Thus, WOSA/XFS compliant applications that do not need the system to be in Vendor Dependent Mode, must comply with the following:

- Every WOSA/XFS application should open a session with the VDM ServiceProvider passing a valid ApplId and then register for all VDM entry and exit notices.

- Before opening any session with any other WOSA/XFS Service Provider, check the status of the VDM Service Provider. If Vendor Dependent Mode is not “Inactive”, do not open a session.

- When getting a VDM entry notice, close all open sessions with all other WOSA/XFS Service Providers as soon as possible and issue an acknowledgement for the entry to VDM.

- When getting a VDM exit notice, acknowledge at once.

- When getting a VDM exited notice, re-open any required sessions with other WOSA/XFS Service Providers.


2.10. Cameras

Class Name CAM

Class Identifier WFS_SERVICE_CLASS_CAM = 10

The WOSA/XFS camera service defines the functions provided by banking camera systems.

Banking camera systems usually consist of a recorder, a video mixer and one or more cameras. If there are several cameras, each camera focuses a special place within the self-service area (e.g. the room, the customer or the cash tray). If there is only one camera that can switches to take photos from different positions, it is presented by the service providers as a set of cameras, one for each of its possible positions. By using the video mixer it can be decided, which of the cameras should take the next photo. Furthermore data can be given to be inserted in the photo (e.g. date, time or bankcode).


3. Planned Enhancements and Extensions

This section describes functions and facilities that are not fully defined in this version of the WOSA 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.

WOSA/XFS currently includes specifications for access to the key classes of financial peripherals, as listed above. These existing specifications will be extended and enhanced based on vendor and user experience with them. The following classes of devices or services, and others that customers and vendors request, may be evaluated for inclusion in future versions of this specification:

  • Cash acceptance devices (bills and coins)

  • Card embossing devices

  • Hologram readers

  • Point-to-point audio/video-conferencing

  • Biometrics authentication hardware, e.g. signature capture devices, fingerprint capture devices, ...

  • Dispensers for various items, including traveller checks, chequebooks, ...

Also to be considered for future versions of WOSA/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. Whenever possible, the capabilities will be incorporated into the family of standard WOSA elements, and will utilise existing formal and de facto standards.

Please submit comments and questions on the WOSA Extensions for Financial Services to any of the Banking Solutions Vendor Council members, or to:

Email: bsvc@microsoft.com

Fax (Europe): +49 6172 661 160 Attn: Ashley Steele

Mail: Banking Solutions Vendor Council Banking Solutions Vendor Council

Attn: John Michael Gross Attn: Ashley Steele

Microsoft Corporation Microsoft GmbH

One Microsoft Way 1/1174 Siemensstraße 21

Redmond, WA 98052 D 61352 Bad Homburg

USA Germany

Error reports maybe sent per email to: bsvchelp@microsoft.com

Updated versions of this specification, when released, may also be requested from these contacts.


WOSA

(Windowsä Open Services Architecture)

Extensions for Financial Services

A Client-Server Architecture for
Financial Enterprise Computing under Microsoft® Windows

Printer Device Class Interface

–––––––––––––––––––––––––––––––––––

Programmer’s Reference

Revision 2.00

November 11, 1996

Developed by the members of the Banking Solutions Vendor Council


Table of Contents

1. Introduction
1.1 WOSA/XFS Service-Specific Programming

2. Banking Printers

3. Banking Printer Types

4. Forms Model

5. Command Overview

6. Info Commands
6.1 WFS_INF_PTR_STATUS

6.2 WFS_INF_PTR_CAPABILITIES

6.3 WFS_INF_PTR_FORM_LIST

6.4 WFS_INF_PTR_MEDIA_LIST

6.5 WFS_INF_PTR_QUERY_FORM

6.6 WFS_INF_PTR_QUERY_MEDIA

6.7 WFS_INF_PTR_QUERY_FIELD

7. Execute Commands
7.1 WFS_CMD_PTR_CONTROL_MEDIA

7.2 WFS_CMD_PTR_PRINT_FORM

7.3 WFS_CMD_PTR_READ_FORM

7.4 WFS_CMD_PTR_RAW_DATA

7.5 WFS_CMD_PTR_MEDIA_EXTENTS

7.6 WFS_CMD_PTR_RESET_COUNT

7.7 WFS_CMD_PTR_READ_IMAGE

8. Events
8.1 WFS_EXEE_PTR_NOMEDIA

8.2 WFS_EXEE_PTR_MEDIAINSERTED

8.3 WFS_EXEE_PTR_FIELDERROR

8.4 WFS_EXEE_PTR_FIELDWARNING

8.5 WFS_USRE_PTR_RETRACTBINTHRESHOLD

8.6 WFS_SRVE_PTR_MEDIATAKEN

8.7 WFS_USRE_PTR_PAPERTHRESHOLD

8.8 WFS_USRE_PTR_TONERTHRESHOLD

8.9 WFS_SRVE_PTR_MEDIAINSERTED

9. Form, Field and Media Definitions
9.1 Definition Syntax

9.2 Form and Media Measurements

9.3 Form Definition

9.4 Field Definition

9.5 Frame Definition

9.6 Media Definition

10. C-Header File


1.1 WOSA/XFS Service-Specific Programming

The service classes are defined by their service-specific commands and the associated data structures, error codes, messages, etc. These commands are used to request functions that are specific to one or more classes of service providers, but not all of them, and therefore are not included in the common API for basic or administration functions.

When a service-specific command is common among two or more classes of service providers, the syntax of the command is as similar as possible across all services, since a major objective of the WOSA Extensions for Financial Services is to standardize command codes and structures for the broadest variety of services. For example, using the WFSExecute function, the commands to read data from various services are as similar as possible to each other in their syntax and data structures.

In general, the specific command set for a service class is defined as the union of the sets of specific capabilities likely to be provided by the developers of the services of that class; thus any particular device will normally support only a subset of the command set defined for the class.

There are three cases in which a service provider may receive a service-specific command that it does not support:

  • The requested capability is defined for the class of service providers by the WOSA/XFS specification, the particular vendor implementation of that service does not support it, and the unsupported capability is not considered to be fundamental to the service. In this case, the service provider returns a successful completion, but does no operation. An example would be a request from an application to turn on a control indicator on a passbook printer; the service provider recognizes the command, but since the passbook printer it is managing does not include that indicator, the service provider does no operation and returns a successful completion to the application.

  • The requested capability is defined for the class of service providers by the WOSA/XFS specification, the particular vendor implementation of that service does not support it, and the unsupported capability is considered to be fundamental to the service. In this case, a WFS_ERR_UNSUPP_COMMAND error is returned to the calling application. An example would be a request from an application to a cash dispenser to dispense coins; the service provider recognizes the command but, since the cash dispenser it is managing dispenses only notes, returns this error.

  • The requested capability is not defined for the class of service providers by the WOSA/XFS specification. In this case, a WFS_ERR_INVALID_COMMAND error is returned to the calling application.

This design allows implementation of applications that can be used with a range of services that provide differing subsets of the functionalities that are defined for their service class. Applications may use the WFSGetInfo and WFSAsyncGetInfo commands to inquire about the capabilities of the service they are about to use, and modify their behavior accordingly, or they may use functions and then deal with WFS_ERR_UNSUPP_COMMAND error returns to make decisions as to how to use the service.


2. Banking Printers

This specification describes the functionality of the services provided by banking printers under WOSA/XFS, focusing on three areas:

  • application programming for printing

  • print document definition

  • integration with the Windows architecture

These descriptions include definitions of the service-specific commands that can be issued, using the WFSAsyncExecute, WFSExecute, WFSGetInfo and WFSAsyncGetInfo functions.

The requirements for printing in banking applications are significantly different from those of the conventional PC environment, and the WOSA/XFS support delivers the foundation for financial application printing, including:

· Controlled access to shared printers

The banking printers can be shared between workstations, and the WOSA/XFS layer provides the ability for the application to manage ownership of a print device. This allows an application to identify the operator granted control of the printer, and to insure that a teller printing multiple documents is not interrupted by work for other applications.

· Application controlled printing

In the banking environment, it is necessary for the application to receive positive feedback on the availability of print devices, and the success or failure of individual print operations. The WOSA/XFS printer support provides a standard mechanism for application retrieval of this status information.

· Management of printing peripherals

Distributed banking networks require the ability to track the availability and failure of printing peripherals on a branch and system-wide basis. Through the WOSA/XFS WFSRegister function, monitoring programs can collect error alerts from the banking printers.

· Vendor independent API and document definition

All of the WOSA/XFS peripheral implementations are designed around a standardized family of APIs to allow application code portability across vendor hardware platforms. With printers, it is also recognized that banks invest a significant amount of resource in the authoring of print documents. The WOSA/XFS printer service class is implemented around a forms model which also standardizes the basic document definition. This extends the investment protection provided by WOSA/XFS compliant systems to include this additional part of the application development.

· Windows printing integration

It is possible for a banking printer to offer printing capabilities that can be accessed by non-banking specific applications, such as general office productivity packages. This would not, for example, be true for a receipt printer, but it could be the case for a device with document printing capabilities. A vendor may choose an XFS implementation that allows both types of applications (WOSA/XFS and Windows applications using the Windows printing subsystem) to share the printing devices. The vendor should specify any impact this approach has on XFS subsystem operation, such as error reporting.

Full implementation of the above features depends on the individual vendor-supplied service providers. This specification outlines the functionality and requirements for applications using the WOSA/XFS printer services, and for the development of those services.


3. Banking Printer Types

The WOSA/XFS printer service defines and supports four types of banking printers through a common interface:

· Receipt Printer

The receipt printer is used to print cut sheet documents. It may or may not require insert or eject operations, and often includes an operator identification device, e.g., Teller A and Teller B lights, for shared operation.

· Journal Printer

The journal is a continuous form device used to record a hardcopy audit trail of transactions, and for certain report printing requirements.

· Passbook Printer

The passbook device is physically and functionally the most complex printer. The WOSA/XFS definition supports automatic positioning of the book, as well as read/write capability for an optional integrated magnetic stripe. The implementation also manages the book geometry - i.e. the margins and centerfolds - presenting the simplest possible application interface while delivering the full range of functionality.

· Document Printer

Document printing is similar to receipt printing -- a set of fields are positioned on an inserted sheet of paper -- but the focus is on full-size forms. It should be noted that the WOSA/XFS environment only implements the printing of text fields from the application. The electronic printing of the form image itself is not supported; but can be delivered as an added-value extension by the vendor.

Additional hardware components, like scanners, stripe readers, OCR readers, and stamps, normally attached directly to the printer are also controlled through this interface.


4. Forms Model

The WOSA/XFS printing class functionality is based on a “forms” model for printing. Banking documents are represented as a series of text and/or graphic fields output from the application, and positioned on the document by the WOSA/XFS printing system.

The form is an object which includes the positioning and presentation information for each of the fields in the document. The application selects a form, and supplies only the field data and the control parameters to fully define the print document.

The form objects are owned and managed by the WOSA/XFS printing service. To optimize maintainability of the system, the application can query the service for the list of fields required to print a given form. Through this mechanism, it is not necessary to duplicate the field contents of forms in application authoring data. The figure below outlines the printing process from the application's view.

The WOSA/XFS implementation recognizes that the form object must be supported by job-specific data to fully address printing requirements. As an example, a form defining a passbook print line will need to have its origin defined externally in order to be reused for different passbook lines. These job specific parameters are supplied on the call to the WFSExecute: WFS_CMD_PTR_PRINT_FORM command.

In some cases, the application wants to print a block of data without considering it as a series of separate fields. One example is a line of journal data, fully formatted by the application. This can be handled by defining a one field form, or by use of the WFSExecute: WFS_CMD_PTR_RAW_DATA command.

The document definition under WOSA/XFS printing is standardized to provide portability across vendor implementations. The standard has been defined at the source language level for the document definition, allowing vendor differences at the runtime level to manage implementation specific dependencies, providing several areas where vendors can provide value-added extensions. As an example, a vendor providing a graphical form definition tool can produce the field definition object format directly. The WOSA/XFS requirements for portability are:

  • A vendor must be able to export print format in the standardized field definition source format for portability to other systems.

  • A vendor must be able to import document formats produced on other systems in the standardized field definition source format.

  • A vendor can extend the field definition source language, but any verbs included in the standard must be implemented strictly as defined by the standard. Import and export facilities must be tolerant of source language extensions, reporting but ignoring the exceptions.

The document definition also recognizes that unique hardware restrictions may require tuning of field positioning from one vendor's platform to another. To enhance portability, the WOSA/XFS document format has specifically been defined to allow a single reference adjustment for all fields to avoid forcing the customer to reposition each field.


5. Command Overview

The basic operation of the print devices is managed using the WFSGetInfo/WFSAsyncGetInfo and WFSExecute/WFSAsyncExecute functions, with two primary commands:
WFS_INF_PTR_QUERY_FORM
This command retrieves the form header information, and the list of fields. It is performed using WFSGetInfo, which means that it can be performed even when the service is locked by another user.

WFS_CMD_PTR_PRINT_FORM
This command is performed using WFSExecute, and includes as parameter data the name of the form to select and the required field data values.

This approach combines in the most efficient manner the four logical steps required to print a form:

  • Selecting a document form object

  • Querying the service for the list of fields

  • Supplying the data for each field

  • Issuing the print command

By using a WFSGetInfo command for retrieval of the list of field names, rather than WFSExecute (which is blocked when the service is locked by another application), it is possible for an application to assemble the required set of fields for a form before locking the service. This minimizes the time that each application request ties up the service. Using WFSGetInfo, it is also possible to query the attributes of a particular field. This command is generally not required for most applications.

The combination of form selection, field value presentation, and the print action into an atomic command -- the WFSExecute: WFS_CMD_PTR_PRINT_FORM command -- makes it possible to express a complete print operation with one API call. This implementation allows an application to perform a print operation without locking and subsequently unlocking the service (although locking may still be desirable for other reasons). To do multiple print operations without allowing other applications to intersperse their print requests, it is still necessary to use the lock functions. Where these multiple print functions represent a series of passbook lines (using the INDEX capability in the field definition), the WFSExecute: WFS_CMD_PTR_PRINT_FORM command provides support for management of the print line number. Note that if a form contains a tabular field (i.e., one with a non-zero INDEX value), and data is not supplied for some of the lines in the “table,” then those lines are left blank.

Finally, for printers with the capability to read from a passbook (OCR, MICR and/or magnetic stripe), the data is read with the WFSExecute: WFS_CMD_PTR_READ_FORM command. The data is written using the WFSExecute: WFS_CMD_PTR_PRINT_FORM command. Since these devices are usable only for passbook operations, they are not defined as separate logical devices.


6. Info Commands


6.1 WFS_INF_PTR_STATUS

Description This command is used to request status information for the device.

Input Param None.

Output Param LPWFSPTRSTATUS lpStatus;

typedef struct _wfs_ptr_status
 {
 WORD  fwDevice;
 WORD  fwMedia;
 WORD  fwPaper;
 WORD  fwToner;
 WORD  fwInk;
 WORD  fwLamp;
 WORD  fwRetractBin;
 USHORT  usRetractCount;
 USHORT  usMediaOnStacker;
 LPSTR  lpszExtra;
 } WFSPTRSTATUS, * LPWFSPTRSTATUS;

fwDevice
Specifies the state of the print device as one of the following flags:

Value Meaning

WFS_PTR_DEVONLINE The device is online.

WFS_PTR_DEVOFFLINE The device is offline.

WFS_PTR_DEVPOWEROFF The device is powered off.

WFS_PTR_DEVBUSY The device is busy processing a request.

WFS_PTR_DEVNODEVICE There is no device connected.

WFS_PTR_DEVUSERERROR The device is present but a person is preventing proper device operation. The application should suspend the device from service until the service provider generates a device state change event indicating the condition of the device has changed, e.g., the error is removed (WFS_PTR_DEVONLINE) or a permanent error condition has occurred (WFS_PTR_DEVHWERROR).

WFS_PTR_DEVHWERROR The device is inoperable due to a hardware error.

fwMedia
Specifies the state of the print media (i.e., the paper: passbook, single sheet, roll, etc.) as one of the following flags:

Value Meaning

WFS_PTR_MEDIAPRESENT Media is inserted in the device.

WFS_PTR_MEDIANOTPRESENT Media is not inserted in the device.

WFS_PTR_MEDIAJAMMED Media is jammed in the device.

WFS_PTR_MEDIAUNKNOWN The state of the print media cannot be determined with the device in its current state.

WFS_PTR_MEDIANOTSUPP The capability to report the state of the print media is not supported by the device.

WFS_PTR_MEDIAENTERING Media is at the entry/exit slot of the device.

fwPaper
Specifies the state of the paper supply as one of the following flags:

Value Meaning

WFS_PTR_PAPERFULL The paper supply is full.

WFS_PTR_PAPERLOW The paper supply is low.

WFS_PTR_PAPEROUT The paper supply is empty.

WFS_PTR_PAPERNOTSUPP Capability not supported by device.

WFS_PTR_PAPERUNKNOWN Capability cannot be determined with device in its current state.

fwToner
Specifies the state of the print device as one of the following flags:

Value Meaning

WFS_PTR_TONERFULL The toner supply is full.

WFS_PTR_TONERLOW The toner supply is low.

WFS_PTR_TONEROUT The toner supply is empty.

WFS_PTR_TONERNOTSUPP Capability not supported by device.

WFS_PTR_TONERUNKNOWN Capability cannot be determined with device in its current state.

fwInk

Specifies the status of the stamping ink in the printer as one of:

Value Meaning

WFS_PTR_INKFULL Ink supply in device is full.

WFS_PTR_INKLOW Ink supply in device is low.

WFS_PTR_INKOUT Ink supply in device is empty.

WFS_PTR_INKNOTSUPP Capability not supported by device.

WFS_PTR_INKUNKNOWN Capability cannot be determined with device in its current state.

fwLamp

Specifies the status of the printer imaging lamp as one of:

Value Meaning

WFS_PTR_LAMPOK The lamp is OK.

WFS_PTR_LAMPFADING The lamp should be changed.

WFS_PTR_LAMPINOP The lamp is inoperable.

WFS_PTR_LAMPNOTSUPP Capability not supported by device.

WFS_PTR_LAMPUNKNOWN Capability cannot be determined with device in its current state.

fwRetractBin
Specifies the state of the printer retract bin as one of the following flags:

Value Meaning

WFS_PTR_RETRACTBINOK The retract bin of the printer is not full.

WFS_PTR_RETRACTBINFULL The retract bin of the printer is full.

WFS_PTR_RETRACTNOTSUPP The printer does not support retract capability.

WFS_PTR_RETRACTUNKNOWN Capability cannot be determined with device in its current state.

WFS_PTR_RETRACTBINHIGH The retract bin of the printer is high.

usRetractCount
The number of media retracted; applicable only to printers with retract capability. This value is persistent: it is reset to zero by the WFS_CMD_PTR_RESET_COUNT command.

usMediaOnStacker
The number of media on stacker; applicable only to printers with stacking capability.

lpszExtra
Pointer to a list of vendor-specific, or any other extended, information. The information is returned as a series of “key=value” strings so that it is easily extensible by service providers. Each string is null-terminated, with the final string terminating with two null characters.

Error Codes There are no additional error codes generated by this command.

Comments Applications which require or expect specific information to be present in the lpszExtra parameter may not be device or vendor-independent.


6.2 WFS_INF_PTR_CAPABILITIES

Description This command is used to request device capability information.

Input Param None.

Output Param LPWFSPTRCAPS lpCaps;

typedef struct _wfs_ptr_caps
 {
 WORD  wClass;
 WORD  fwType;
 BOOL  bCompound;
 WORD  wResolution;
 WORD  fwReadForm;
 WORD   fwWriteForm;
 WORD  fwExtents;
 WORD  fwControl;
 USHORT  usMaxRetract;
 USHORT  usMaxMediaOnStacker;
 BOOL  bAcceptMedia;
 LPSTR  lpszExtra;
 } WFSPTRCAPS, * LPWFSPTRCAPS;

wClass
Specifies the logical service class, value is:
WFS_SERVICE_CLASS_PTR

fwType
Specifies the type(s) of the physical device driven by the logical service, as a combination of the following flags:

Value Meaning

WFS_PTR_TYPERECEIPT Device is a receipt printer.

WFS_PTR_TYPEPASSBOOK Device is a passbook printer.

WFS_PTR_TYPEJOURNAL Device is a journal printer.

WFS_PTR_TYPEDOCUMENT Device is a document printer.

bCompound
Specifies whether the logical device is part of a compound physical device and is either TRUE or FALSE.

wResolution
Specifies at which resolution(s) the physical device can print. Used by the application to select the level of print quality desired (e.g., as in Word for Windows); does not imply any absolute level of resolution, only relative. Specified as a combination of the following flags:

Value Meaning

WFS_PTR_RESLOW Can print with low resolution.

WFS_PTR_RESMED Can print with medium resolution.

WFS_PTR_RESHIGH Can print with high resolution.

WFS_PTR_RESVERYHIGH Can print with very high resolution.

fwReadForm
Specifies whether the device can read data from media, as a combination of the following flags:

Value Meaning

WFS_PTR_READOCR Device has OCR capability.

WFS_PTR_READMICR Device has MICR capability.

WFS_PTR_READMSF Device has MSF capability.

WFS_PTR_READBARCODE Device has Barcode capability.

WFS_PTR_READPAGEMARK Device has Page Mark capability.

WFS_PTR_READIMAGE Device has imaging capability.

fwWriteForm
Specifies whether the device can write data to the media, as a combination of the following flags:

Value Meaning

WFS_PTR_WRITETEXT Device has Text capability.

WFS_PTR_WRITEGRAPHICS Device has Graphics capability.

WFS_PTR_WRITEOCR Device has OCR capability.

WFS_PTR_WRITEMICR Device has MICR capability.

WFS_PTR_WRITEMSF Device has MSF capability.

WFS_PTR_WRITEBARCODE Device has Barcode capability.

WFS_PTR_WRITESTAMP Device has stamping capability.

fwExtents
Specifies whether the device is able to measure the inserted media, as a combination of the following flags:

Value Meaning

WFS_PTR_EXTHORIZONTAL Device has horizontal size detection capability.

WFS_PTR_EXTVERTICAL Device has vertical size detection capability.

fwControl
Specifies the manner in which media can be controlled, as a combination of the following bit flags:

Value Meaning

WFS_PTR_CTRLEJECT Device can eject media.

WFS_PTR_CTRLPERFORATE Device can perforate media.

WFS_PTR_CTRLCUT Device can cut media.

WFS_PTR_CTRLSKIP Device can skip to mark.

WFS_PTR_CTRLFLUSH Device can be sent data that is buffered internally, and flushed to the printer on request.

WFS_PTR_CTRLRETRACT Device can retract media

WFS_PTR_CTRLSTACK Device can stack media items before ejecting as a bundle.

WFS_PTR_CTRLPARTIALCUT Device can partially cut the media.

WFS_PTR_CTRLALARM Device can ring a bell, beep or otherwise sound an audible alarm.

WFS_PTR_CTRLATPFORWARD Capability to turn one page forward.

WFS_PTR_CTRLATPBACKWARD Capability to turn one page backward.

WFS_PTR_CTRLTURNMEDIA Device can turn inserted media.

usMaxRetract
Specifies the maximum number of media items that the retract bin can hold (zero if not available).

usMaxMediaOnStacker
Specifies the maximum number of media items that the stacker can hold (zero if this capability is not available).

bAcceptMedia
Specifies whether the device is able to accept media while no execute command is running that is waiting explicitly for media to be inserted. Its value is either TRUE or FALSE.

lpszExtra
Points to a list of vendor-specific, or any other extended, information. The information is returned as a series of “key=value” strings so that it is easily extensible by service providers. Each string is null-terminated, with the final string terminating with two null characters.

Error Codes There are no additional error codes generated by this command.

Comments Applications which require or expect specific information to be present in the lpszExtra parameter may not be device or vendor-independent.


6.3 WFS_INF_PTR_FORM_LIST

Description This command is used to retrieve the list of forms available on the device.

Input Param None.

Output Param LPSTR lpszFormList;

lpszFormList
Pointer to a list of null-terminated form names, with the final name terminating with two null characters.

Error Codes There are no additional error codes generated by this command.

Comments None.


6.4 WFS_INF_PTR_MEDIA_LIST

Description This command is used to retrieve the list of media definitions available on the device.

Input Param None.

Output Param LPSTR lpszMediaList;

lpszMediaList
Pointer to a list of null-terminated media names, with the final name terminating with two null characters.

Error Codes There are no additional error codes generated by this command.

Comments None.


6.5 WFS_INF_PTR_QUERY_FORM

Description This command is used to retrieve details of the definition of a specified form.

Input Param LPSTR lpszFormName;

lpszFormName
Points to the null-terminated form name on which to retrieve details.

Output Param LPWFSFRMHEADER lpHeader;

typedef struct _wfs_frm_header
 {
 LPSTR lpszFormName;
 WORD wBase;
 WORD wUnitX;
 WORD wUnitY;
 WORD wWidth;
 WORD wHeight;
 WORD wAlignment;
 WORD wOrientation;
 WORD wOffsetX;
 WORD wOffsetY;
 WORD wVersionMajor;
 WORD wVersionMinor;
 LPSTR lpszUserPrompt;
 LPSTR lpszFields;
 } WFSFRMHEADER, * LPWFSFRMHEADER;

lpszFormName
Specifies the null-terminated name of the form.

wBase
Specifies the base unit of measurement of the form and can be one of the following:

Value Meaning

WFS_FRM_INCH The base unit is inches.

WFS_FRM_MM The base unit is millimeters.

WFS_FRM_ROWCOLUMN The base unit is rows and columns.

wUnitX
Specifies the horizontal resolution of the base units as a fraction of the wBase value. For example, a value of 16 applied to the base unit WFS_FRM_INCH means that the base horizontal resolution is 1/16".

wUnitY
Specifies the vertical resolution of the base units as a fraction of the wBase value. For example, a value of 10 applied to the base unit WFS_FRM_MM means that the base vertical resolution is 0.1 mm.

wWidth
Specifies the width of the form in terms of the base horizontal resolution.

wHeight
Specifies the height of the form in terms of the base vertical resolution.

wAlignment
Specifies the relative alignment of the form on the media and can be one of the following:

Value Meaning

WFS_FRM_TOPLEFT The form is aligned relative to the top and left edges of the media.

WFS_FRM_TOPRIGHT The form is aligned relative to the top and right edges of the media.

WFS_FRM_BOTTOMLEFT The form is aligned relative to the bottom and left edges of the media.

WFS_FRM_BOTTOMRIGHT The form is aligned relative to the bottom and right edges of the media.

wOrientation
Specifies the orientation of the form and can be one of the following:

Value Meaning

WFS_FRM_PORTRAIT The orientation of the form is portrait.

WFS_FRM_LANDSCAPE The orientation of the form is landscape.

wOffsetX
Specifies the horizontal offset of the position of the top-left corner of the form, relative to the left or right edge specified by wAlignment. This value is specified in terms of the base horizontal resolution and is always positive.

wOffsetY
Specifies the vertical offset of the position of the top-left corner of the form, relative to the top or bottom edge specified by wAlignment. This value is specified in terms of the base vertical resolution and is always positive.

wVersionMajor
Specifies the major version of the form.

wVersionMinor
Specifies the minor version of the form.

lpszUserPrompt
Pointer to a null-terminated user prompt string.

lpszFields
Pointer to a list of null-terminated field names, with the final name terminating with two null characters.

Error Codes The following additional error codes can be generated by this command:

Value Meaning

WFS_ERR_PTR_FORMNOTFOUND The specified form cannot be found.

WFS_ERR_PTR_FORMINVALID The specified form is invalid.

Comments None.


6.6 WFS_INF_PTR_QUERY_MEDIA

Description This command is used to retrieve details of the definition of a specified media.

Input Param LPSTR lpszMediaName;

lpszMediaName
Pointer to the null-terminated media name about which to retrieve details.

Output Param LPWFSFRMMEDIA lpMedia;

typedef struct _wfs_frm_media
 {
 WORD  fwMediaType;
 WORD  wBase;
 WORD  wUnitX;
 WORD  wUnitY;
 WORD  wSizeWidth;
 WORD  wSizeHeight;
 WORD  wPageCount;
 WORD  wLineCount;
 WORD  wPrintAreaX;
 WORD  wPrintAreaY;
 WORD  wPrintAreaWidth;
 WORD  wPrintAreaHeight;
 WORD  wRestrictedAreaX;
 WORD  wRestrictedAreaY;
 WORD  wRestrictedAreaWidth;
 WORD  wRestrictedAreaHeight;
 WORD  wStagger;
 WORD  wFoldType;
 } WFSFRMMEDIA, * LPWFSFRMMEDIA;

fwMediaType
Specifies the type of media as one of the following flags:

Value Meaning

WFS_FRM_MEDIAGENERIC Generic media, i.e., single sheet.

WFS_FRM_MEDIAMULTIPART Multipart media.

WFS_FRM_MEDIAPASSBOOK Passbook media.

wBase
Specifies the base unit of measurement of the form and can be one of the following:

Value Meaning

WFS_FRM_INCH The base unit is inches.

WFS_FRM_MM The base unit is millimeters.

WFS_FRM_ROWCOLUMN The base unit is rows and columns.

wUnitX
Specifies the horizontal resolution of the base units as a fraction of the wBase value. For example, a value of 16 applied to the base unit WFS_FRM_INCH means that the base horizontal resolution is 1/16".

wUnitY
Specifies the vertical resolution of the base units as a fraction of the wBase value. For example, a value of 10 applied to the base unit WFS_FRM_MM means that the base vertical resolution is 0.1 mm.

wSizeWidth
Specifies the width of the media in terms of the base horizontal resolution.

wSizeHeight
Specifies the height of the media in terms of the base vertical resolution.

wPageCount
Specifies the number of pages in a media of type WFS_FRM_MEDIAPASSBOOK.

wLineCount
Specifies the number of lines on a page for a media of type WFS_FRM_MEDIAPASSBOOK.

wPrintAreaX
Specifies the horizontal offset of the printable area relative to the top left corner of the media in terms of the base horizontal resolution.

wPrintAreaY
Specifies the vertical offset of the printable area relative to the top left corner of the media in terms of the base vertical resolution.

wPrintAreaWidth
Specifies the printable area width of the media in terms of the base horizontal resolution.

wPrintAreaHeight
Specifies the printable area height of the media in terms of the base vertical resolution.

wRestrictedAreaX
Specifies the horizontal offset of the restricted area relative to the top left corner of the media in terms of the base horizontal resolution.

wRestrictedAreaY
Specifies the vertical offset of the restricted area relative to the top left corner of the media in terms of the base vertical resolution.

wRestrictedAreaWidth
Specifies the restricted area width of the media in terms of the base horizontal resolution.

wRestrictedAreaHeight
Specifies the restricted area height of the media in terms of the base vertical resolution.

wStagger
Specifies the staggering from the top in terms of the base vertical resolution for a media of type WFS_FRM_MEDIAPASSBOOK.

wFoldType
Specified the type of fold (vertical, horizontal or none) for a media of type WFS_FRM_MEDIAPASSBOOK.

Value Meaning

WFS_FRM_FOLDNONE Passbook has no fold.

WFS_FRM_FOLDHORIZONTAL Passbook has a horizontal fold.

WFS_FRM_FOLDVERTICAL Passbook has a vertical fold.

Error Codes The following additional error codes can be generated by this command:

Value Meaning

WFS_ERR_PTR_MEDIANOTFOUND The specified media definition cannot be found.

WFS_ERR_PTR_MEDIAINVALID The specified media definition is invalid.

Comments None.


6.7 WFS_INF_PTR_QUERY_FIELD

Description This command is used to retrieve details of the definition of a single or all fields on a specified form.

Input Param LPWFSPTRQUERYFIELD lpQueryField;

typedef struct _wfs_ptr_query_field
 {
 LPSTR    lpszFormName;
 LPSTR    lpszFieldName;
 } WFSPTRQUERYFIELD, * LPWFSPTRQUERYFIELD;

lpszFormName
Pointer to the null-terminated form name.

lpszFieldName
Pointer to the null-terminated name of the field about which to retrieve details. If this value is NULL, then retrieve details for all fields on the form.

Output Param LPWFSFRMFIELD * lppFields;

lppFields
Pointer to a null-terminated array of pointers to field definition structures:

typedef struct _wfs_frm_field
 {
 LPSTR  lpszFieldName;
 WORD  wIndexCount;
 WORD  fwType;
 WORD  fwClass;
 WORD  fwAccess;
 WORD  fwOverflow;
 LPSTR  lpszInitialValue;
 LPSTR  lpszFormat;
 } WFSFRMFIELD, * LPWFSFRMFIELD;

lpszFieldName
Pointer to the null-terminated field name.

wIndexCount
Specifies the number of entries for an index field. A value of zero indicates that this field is not an index field. Index fields are typically used to present information in a tabular fashion.

fwType
Specifies the type of field and can be one of the following:

Value Meaning

WFS_FRM_FIELDTEXT A text field.

WFS_FRM_FIELDMICR A Magnetic Ink Character Recognition field.

WFS_FRM_FIELDOCR An Optical Character Recognition field.

WFS_FRM_FIELDMSF A Magnetic Stripe Facility field.

WFS_FRM_FIELDBARCODE A Barcode field.

WFS_FRM_FIELDGRAPHIC A Graphic field

WFS_FRM_FIELDPAGEMARK A Page Mark field

fwClass
Specifies the class of the field and can be one of the following:

Value Meaning

WFS_FRM_CLASSSTATIC The field data cannot be set by the application.

WFS_FRM_CLASSOPTIONAL The field data can be set by the application.

WFS_FRM_CLASSREQUIRED The field data must be set by the application.

fwAccess
Specifies whether the field is to be used for input, output, or both and can be a combination of the following bit-flags:

Value Meaning

WFS_FRM_ACCESSREAD The field is used for input.

WFS_FRM_ACCESSWRITE The field is used for ouput.

fwOverflow
Specifies how an overflow of field data should be handled and can be one of the following:

Value Meaning

WFS_FRM_OVFTERMINATE Return an error and terminate printing of the form.

WFS_FRM_OVFTRUNCATE Truncate the field data to fit in the field.

WFS_FRM_OVFBESTFIT Fit the text in the field.

WFS_FRM_OVFOVERWRITE Print the field data beyond the extents of the field boundary.

WFS_FRM_OVFWORDWRAP If the field can hold more than one line the text is wrapped around.

lpszInitialValue
The initial value of the field. When the form is printed (using WFS_CMD_PTR_PRINT_FORM), this value will be used if another value is not provided.

lpszFormat
Format string as defined in the form for this field.

Error Codes The following additional error codes can be generated by this command:

Value Meaning

WFS_ERR_PTR_FORMNOTFOUND The specified form cannot be found.

WFS_ERR_PTR_FORMINVALID The specified form is invalid.

WFS_ERR_PTR_FIELDNOTFOUND The specified field cannot be found.

WFS_ERR_PTR_FIELDINVALID The specified field is invalid.

Comments None.


7. Execute Commands


7.1 WFS_CMD_PTR_CONTROL_MEDIA

Description This command is used to control a form drawn in by the device (e.g. after reading or in case of termination of an application request).

If an eject operation is specified, it completes when the media is moved to the exit slot. A service event is generated when the media has been taken by the user.

Input Param LPDWORD lpdwMediaControl;

lpdwMediaControl
Pointer to a value which specifies the manner in which the media should be handled, as a combination of the following bit-flags:

Value Meaning

WFS_PTR_CTRLFLUSH Flush any data to the printer that has not yet been printed from previous WFS_CMD_PTR_PRINT_FORM commands.

WFS_PTR_CTRLEJECT Flush data as above, then eject the media.

WFS_PTR_CTRLPERFORATE Flush data as above, then perforate the media.

WFS_PTR_CTRLCUT Flush data as above, then cut the media. For printers which have the ability to stack multiple cut sheets and deliver them as a single bundle to the customer, cut causes the media to be stacked and eject causes the bundle to be moved to the exit slot.

WFS_PTR_CTRLSKIP Flush data as above, then skip the media to mark.

WFS_PTR_CTRLRETRACT Flush data as above, then retract the media.

WFS_PTR_CTRLSTACK Flush data as above, then move the media item on the internal stacker.

WFS_PTR_CTRLPARTIALCUT Flush the data as above, then partially cut the media.

WFS_PTR_CTRLALARM Caused the printer to ring a bell, beep, or otherwise sound an audible alarm.

WFS_PTR_CTRLATPFORWARD Flush the data as above, then turn one page forward.

WFS_PTR_CTRLATPBACKWARD Flush the data as above, then turn one page backward.

WFS_PTR_CTRLTURNMEDIA Flush the data as above, then turn inserted media.

WFS_PTR_CTRLSTAMP Flush the data as above, then stamp on inserted media.

Output Param None.

Error Codes The following additional error codes can be generated by this command:

Value Meaning

WFS_ERR_PTR_NOMEDIAPRESENT No form is present in the device.

WFS_ERR_PTR_FLUSHFAIL The device was not able to flush data.

WFS_ERR_PTR_RETRACTBINFULL The retract bin is full. No more media can be retracted. The current media is still in the device.

WFS_ERR_PTR_STACKERFULL The internal stacker is full. No more media can be moved to the stacker.

WFS_ERR_PTR_PAGETURNFAIL The device was not able to turn the page.

WFS_ERR_PTR_MEDIATURNFAIL The device was not able to turn the inserted media.

Events The following additional events can be generated by this command:

Value Meaning

WFS_USRE_PTR_RETRACTBINFULL The retract bin is full; operator intervention is required. Note that this event is sent only once, at the point at which the bin becomes full.

WFS_SRVE_PTR_MEDIATAKEN The media has been taken by the user.

Comments None.


7.2 WFS_CMD_PTR_PRINT_FORM

Description This command is used to print a form by merging the supplied variable field data with the defined form and field data specified in the form. If no media is present, the device waits for the period of time specified by the dwTimeOut parameter in the WFSExecute call for media to be inserted.

Input Param LPWFSPTRPRINTFORM lpPrintForm;

typedef struct _wfs_ptr_print_form
 {
 LPSTR  lpszFormName;
 LPSTR  lpszMediaName;
 WORD  wAlignment
 WORD  wOffsetX;
 WORD  wOffsetY;
 WORD  wResolution;
 DWORD  dwMediaControl;
 LPSTR  lpszFields;
 } WFSPTRPRINTFORM, * LPWFSPTRPRINTFORM;

lpszFormName
Pointer to the null-terminated form name.

lpszMediaName
Pointer to the null-terminated media name.

wAlignment
Specifies the alignment of the form on the physical medium, as one of these values:

Value Meaning

WFS_PTR_ALNUSEFORMDEFN Use the alignment specified in the form definition.

WFS_PTR_ALNTOPLEFT Align form to top left of physical medium.

WFS_PTR_ALNTOPRIGHT Align form to top right of physical medium.

WFS_PTR_ALNBOTTOMLEFT Align form to bottom left of physical medium.

WFS_PTR_ALNBOTTOMRIGHT Align form to bottom right of physical medium.

wOffsetX
Specifies the horizontal offset of the form, relative to the horizontal alignment specified in wAlignment, in horizontal resolution units (from form definition); always a positive number (i.e., if aligned to the right side of the medium, means offset the form to the left). A value of WFS_PTR_OFFSETUSEFORMDEFN indicates that the xoffset value from the form definition should be used.

wOffsetY
Specifies the vertical offset of the form, relative to the vertical alignment specified in wAlignment, in vertical resolution units (from form definition); always a positive number
(i.e., if aligned to the bottom of the medium, means offset the form upward). A value of WFS_PTR_OFFSETUSEFORMDEFN indicates that the yoffset value from the form definition should be used.

wResolution
Specifies the resolution in which to print the form. Possible values are:

Value Meaning

WFS_PTR_RESLOW Print form with low resolution.

WFS_PTR_RESMED Print form with medium resolution.

WFS_PTR_RESHIGH Print form with high resolution.

WFS_PTR_RESVERYHIGH Print form with very high resolution.

dwMediaControl
Specifies the manner in which the media should be handled, as a combination of the flags described under WFS_CMD_PTR_CONTROL_MEDIA. A NULL value of this parameter means to do none of these actions, as when printing multiple forms on a single page.

lpszFields
Pointer to a series of "<FieldName>=<FieldValue>" strings, where each string is null-terminated with the final string terminating with two null characters. If the field is an index field, then the syntax of the string is instead "<FieldName>[<index>]=<FieldValue>", where <index> specifies the zero-based element of the index field.

Output Param None.

Error Codes The following additional error codes can be generated by this command:

Value Meaning

WFS_ERR_PTR_FORMNOTFOUND The specified form definition cannot be found.

WFS_ERR_PTR_FORMINVALID The specified form definition is invalid.

WFS_ERR_PTR_MEDIANOTFOUND The specified media definition cannot be found.

WFS_ERR_PTR_MEDIAINVALID The specified media definition is invalid.

WFS_ERR_PTR_MEDIASKEWED The media skew exceeded the limit in the form definition.

WFS_ERR_PTR_MEDIAOVERFLOW The form overflowed the media.

WFS_ERR_PTR_FIELDSPECFAILURE The syntax of the lpszFields member is invalid.

WFS_ERR_PTR_FIELDERROR An error occurred while processing a field, causing termination of the print request. An execute event WFS_EXEE_PTR_FIELDERROR is posted with the details.

Events The following additional events can be generated by this command:

Value Meaning

WFS_EXEE_PTR_NOMEDIA No media is present in the device.

WFS_EXEE_PTR_FIELDERROR A fatal error occured while processing a field.

WFS_EXEE_PTR_FIELDWARNING A non-fatal error occured while processing a field.

WFS_EXEE_PTR_MEDIAINSERTED Media has been inserted into the device.

Comments All error codes (except WFS_ERR_PTR_NOMEDIAPRESENT) and events listed under the WFS_CMD_PTR_CONTROL_MEDIA command description can also occur on this command.

An invalid field name is treated as a WFS_EXEE_PTR_FIELDWARNING event with WFS_PTR_FIELDNOTFOUND status. A WFS_EXEE_PTR_FIELDWARNING event is returned with WFS_PTR_FIELDOVERFLOW status if the data overflows the field, and the field definition OVERFLOW value is TRUNCATE, BESTFIT, OVERWRITE or WORDWRAP. Other field-related problems generate a field error return and event.


7.3 WFS_CMD_PTR_READ_FORM

Description This command is used to read data from input fields on the specified form. If no media is present, the device waits for the period of time specified by the dwTimeOut parameter in the WFSExecute call for media to be inserted.

Input Param LPWFSPTRREADFORM lpReadForm;

typedef struct _wfs_ptr_read_form
 {
 LPSTR  lpszFormName;
 LPSTR  lpszFieldNames;
 LPSTR  lpszMediaName;
 DWORD  dwMediaControl;
 } WFSPTRREADFORM, * LPWFSPTRREADFORM;

lpszFormName
Pointer to the null-terminated name of the form.

lpszFieldNames
Pointer to a list of null-terminated field names from which to read input data, with the final name terminating with two null characters. If this value is NULL, then read data from all input fields on the form.

lpszMediaName
Pointer to the null-terminated media name.

dwMediaControl
Specifies the manner in which the media should be handled and can be a combination of the bit flags described under WFS_CMD_PTR_CONTROL_MEDIA.

Output Param LPSTR lpszFields;

lpszFields
Pointer to a series of "<FieldName>=<FieldValue>" strings, where each string is null-terminated with the final string terminating with two null characters. If the field is an index field, then the syntax of the string is instead "<FieldName>[<index>]=<FieldValue>", where <index> specifies the zero-based element of the index field.

Error Codes The following additional error codes can be generated by this command:

Value Meaning

WFS_ERR_PTR_READNOTSUPPORTED The device has no read capability.

WFS_ERR_PTR_FORMNOTFOUND The specified form cannot be found.

WFS_ERR_PTR_FORMINVALID The specified form definition is invalid.

WFS_ERR_PTR_MEDIANOTFOUND The specified media definition cannot be found.

WFS_ERR_PTR_MEDIAINVALID The specified media definition is invalid.

WFS_ERR_PTR_MEDIASKEWED The media skew exceeded the limit in the form definition.

WFS_ERR_PTR_FIELDSPECFAILURE The syntax of the lpszFieldNames member is invalid.

WFS_ERR_PTR_FIELDERROR An error occurred while processing a field, causing termination of the print request. An execute event WFS_EXEE_PTR_FIELDERROR is posted with the details.

Events The following additional events can be generated by this command:

Value Meaning

WFS_EXEE_PTR_NOMEDIA No media is present in the device.

WFS_EXEE_PTR_FIELDERROR A fatal error occured while processing a field.

WFS_EXEE_PTR_FIELDWARNING A non-fatal error occured while processing a field.

WFS_EXEE_PTR_MEDIAINSERTED Media has been inserted into the device.

Comments All error codes (except WFS_ERR_PTR_NOMEDIAPRESENT) and events listed under the WFS_CMD_PTR_CONTROL_MEDIA command description can also occur on this command.


7.4 WFS_CMD_PTR_RAW_DATA

Description This command is used to send raw data (a byte string of device dependent data) to the physical device.

Input Param LPWFSPTRRAWDATA lpRawData;

typedef struct _wfs_ptr_raw_data
 {
 WORD  wInputData;
 ULONG  ulSize;
 LPBYTE  lpbData;
 } WFSPTRRAWDATA, * LPWFSPTRRAWDATA;

wInputData
Specifies that input data from the device is expected in response to sending the raw data (i.e., the data contains a command requesting data). Possible values are:

Value Meaning

WFS_PTR_NOINPUTDATA No input data is expected.

WFS_PTR_INPUTDATA Input data is expected.

ulSize
Specifies the size of the byte string passed to the device.

lpbData
Points to the byte string holding the device dependent data.

Output Param LPWFSPTRRAWDATAIN lpRawDataIn;
[used only if wInputData is set to WFS_PTR_INPUTDATA]

typedef struct _wfs_ptr_raw_data_in
 {
 ULONG  ulSize;
 LPBYTE  lpbData;
 } WFSPTRRAWDATAIN, * LPWFSPTRRAWDATAIN;

ulSize
Specifies the size of the byte string received from the device.

lpbData
Points to the byte string received from the device.

Error Codes There are no additional error codes generated by this command.

Events There are no additional events generated by this command.

Comments Applications which send raw data to a device will typically not be device or vendor independent. Problems with the use of this command include:

1. The data sent to the device can include commands that change the state of the device in unpredictable ways (in particular, in ways that the service provider may not be aware of).

2. Usage of this command will not be portable.

3. This command violates the XFS forms model that is the basis of XFS printer access.

Thus usage of this command should be avoided whenever possible. If it is used, the usage should be carefully isolated from all other XFS access to the service by at least the WFSLock and WFSUnlock commands.


7.5 WFS_CMD_PTR_MEDIA_EXTENTS

Description This command is used to get the extents of the media inserted in the physical device. The input parameter specifies the base unit and fractions in which the media extent values will be returned. If no media is present, the device waits for the period of time specified by the dwTimeOut parameter in the WFSExecute call for media to be inserted.

Input Param LPWFSPTRMEDIAUNIT lpMediaUnit;

typedef struct _wfs_ptr_media_unit
 {
 WORD   wBase;
 WORD   wUnitX;
 WORD   wUnitY;
 } WFSPTRMEDIAUNIT, * LPWFSPTRMEDIAUNIT;

wBase
Specifies the base unit of measurement of the media and can be one of the following:

Value Meaning

WFS_FRM_INCH The base unit is inches.

WFS_FRM_MM The base unit is millimeters.

WFS_FRM_ROWCOLUMN The base unit is rows and columns.

wUnitX
Specifies the horizontal resolution of the base units as a fraction of the wBase value. For example, a value of 16 applied to the base unit WFS_FRM_INCH means that the base horizontal resolution is 1/16".

wUnitY
Specifies the vertical resolution of the base units as a fraction of the wBase value. For example, a value of 10 applied to the base unit WFS_FRM_MM means that the base vertical resolution is 0.1 mm.

Output Param LPWFSPTRMEDIAEXT lpMediaExt;

typedef struct _wfs_ptr_media_ext
 {
 ULONG  ulSizeX;
 ULONG  ulSizeY;
 } WFSPTRMEDIAEXT, * LPWFSPTRMEDIAEXT;

ulSizeX
Specifies the width of the media in terms of the base horizontal resolution.

ulSizeY
Specifies the height of the media in terms of the base vertical resolution.

Error Codes The following additional error codes can be generated by this command:

Value Meaning

WFS_ERR_PTR_EXTENTNOTSUPPORTED The device cannot report extent(s).

Events The following additional events can be generated by this command:

Value Meaning

WFS_EXEE_PTR_NOMEDIA No media is present in the device.

WFS_EXEE_PTR_MEDIAINSERTED Media has been inserted into the device.

Comments None.


7.6 WFS_CMD_PTR_RESET_COUNT

Description This function resets the present value for number of media items retracted to zero. The function is possible only for printers with retract capability.

The number of media items retracted is controlled by the service and can be requested before resetting via the info command WFS_INF_PTR_STATUS.

Input Param None.

Output Param None.

Error Codes There are no additional error codes generated by this command.

Events There are no additional events generated by this command.

Comments None.


7.7 WFS_CMD_PTR_READ_IMAGE

Description This function returns image data from the current media. If no media is present, the device waits for the period of time specified by the dwTimeOut parameter in the WFSExecute call for media to be inserted.

Input Param None.

Output Param LPWFSPTRIMAGE lpImage;

 typedef struct _wfs_ptr_image
  {
  WORD wImageType;
  ULONG ulSize;
  LPBYTE lpImage;
  } WFSPTRIMAGE, * LPWFSPTRIMAGE;

wImageType
Specifies the format of the image returned by this command as one of the following flags:

Value Meaning

WFS_PTR_IMAGETIF The returned image is in TIF format.

WFS_PTR_IMAGEMTF The returned image is in MTF format.

WFS_PTR_IMAGEBMP The returned image is in BMP format.

ulSize
Count of bytes of image data.

lpImage
Points to the image data.

Error Code There are no additional error codes generated by this command.

Events The following additional events can be generated by this command:

Value Meaning

WFS_EXEE_PTR_NOMEDIA No media is present in the device.

WFS_EXEE_PTR_MEDIAINSERTED Media has been inserted into the device.

Comments None.


8. Events


8.1 WFS_EXEE_PTR_NOMEDIA

Description This event specifies that the physical media must be inserted into the device in order for the execute command to proceed.

Event Param LPSTR lpszUserPrompt;

lpszUserPrompt
Pointer to a null-terminated user prompt string from the form definition.

Comments The application may use the lpszUserPrompt in any manner it sees fit, for example it might display the string to the operator, along with a message that the media should be inserted.


8.2 WFS_EXEE_PTR_MEDIAINSERTED

Description This event specifies that the physical media has been inserted into the device.

Event Param None.

Comments The application may use this event to, for example, remove a message box from the screen telling the user to insert a form.


8.3 WFS_EXEE_PTR_FIELDERROR

Description This event specifies that a fatal error has occurred while processing a field.

Event Param LPWFSPTRFIELDFAIL lpFieldFail;

typedef struct _wfs_ptr_field_failure
 {
 LPSTR   lpszFormName;
 LPSTR   lpszFieldName;
 WORD   wFailure;
 } WFSPTRFIELDFAIL, * LPWFSPTRFIELDFAIL;

lpszFormName
Points to the null-terminated form name.

lpszFieldName
Points to the null-terminated field name.

wFailure
Specifies the type of failure and can be one of the following:

Value Meaning

WFS_PTR_FIELDREQUIRED The specified field must be supplied by the application.

WFS_PTR_FIELDSTATICOVWR The specified field is static and thus cannot be overwritten by the application.

WFS_PTR_FIELDOVERFLOW The value supplied for the specified fields is too long.

WFS_PTR_FIELDNOTFOUND The specified field does not exist.

WFS_PTR_FIELDNOTREAD The specified field is not an input field.

WFS_PTR_FIELDNOTWRITE An attempt was made to write to an input field.

WFS_PTR_FIELDHWERROR The specified field uses special hardware (e.g., OCR) and an error occurred.

WFS_PTR_FIELDTYPENOTSUPPORTED The form field type is not supported with device.

WFS_PTR_FIELDGRAPHIC The specified graphic image could not be printed.

Comments None.


8.4 WFS_EXEE_PTR_FIELDWARNING

Description This event is used to specify that a non-fatal error has occurred while processing a field.

Event Param LPWFSPTRFIELDFAIL lpFieldFail;
as defined in the section describing WFS_EXEE_PTR_FIELDERROR.

Comments None.


8.5 WFS_USRE_PTR_RETRACTBINTHRESHOLD

Description This event specifies that the retract bin holding the retracted media is full.

Event Param LPWORD lpwRetractBinThreshold;

lpwRetractBinThreshold
Specified as one of the following flags:

Value Meaning

WFS_PTR_RETRACTBINFULL The retract bin of the printer is full.

WFS_PTR_RETRACTBINHIGH The retract bin of the printer is high.

Comments None.


8.6 WFS_SRVE_PTR_MEDIATAKEN

Description This event is sent when the media is taken from the exit slot following the completion of a successful eject operation.

Event Param None.

Comments Note that since this event occurs after the completion of a function that includes a media eject, it is not an execute event.


8.7 WFS_USRE_PTR_PAPERTHRESHOLD

Description This user event is used to specify that the state of the paper reached a threshold.

Event Param LPWORD lpwPaperThreshold;

Specified as one of the following flags:

Value Meaning

WFS_PTR_PAPERLOW The paper in the printer is low.

WFS_PTR_PAPEROUT The paper in the printer is out.

Comments None.


8.8 WFS_USRE_PTR_TONERTHRESHOLD

Description This user event is used to specify that the state of the toner (or ink) reached a threshold.

Event Param LPWORD lpwTonerThreshold;

Specified as one of the following flags:

Value Meaning

WFS_PTR_TONERLOW The toner (or ink) in the printer is low.

WFS_PTR_TONEROUT The toner (or ink) in the printer is out.

Comments None.


8.9 WFS_SRVE_PTR_MEDIAINSERTED

Description This event specifies that the physical media has been inserted into the device without any read or print execute command being executed. This event is only generated when media is entered in an unsolicited manner.

Event Param None.

Comments None.


9. Form, Field and Media Definitions

This section outlines the format of the definitions of forms, the fields within them, and the media on which they are printed.


9.1 Definition Syntax

The syntactic rules for form, field and media definitions are as follows:

  • White space space, tab

  • Line continuation backslash (\)

  • Line termination CR, LF, CR/LF; line termination ends a “keyword section” (a keyword and its
    value[s])

  • Keywords must be all upper case

  • Names (field/media/font names) any case; case is preserved; service providers are case
    sensitive

  • Strings all strings must be enclosed in double quote characters (");
    standard C escape sequences are allowed.

  • Comments start with two forward slashes (//), end at line termination

Other notes:

  • The values of a keyword are separated by commas.

  • If a keyword is present, all its values must be specified; default values are used only if the keyword is absent.

  • Values that are character strings are marked with asterisks in the definitions below, and must be quoted as specified above.


9.2 Form and Media Measurements

The UNIT keyword sections of the form and media definitions specify the base horizontal and vertical resolution
as follows:

  • the base value specifies the base unit of measurement

  • the x and y values specify the horizontal and vertical resolution as fractions of the base value (e.g., an x value of 10 and a base value of MM means that the base horizontal resolution is 0.1mm).

The base resolutions thus defined by the UNIT keyword section of the form definition are used as the units of the form definition keyword sections:

  • SIZE (width and height values)

  • ALIGNMENT (xoffset and yoffset values)

and of the field definition keyword sections:

  • POSITION (x and y values)

  • SIZE (width and height values)

  • INDEX (xoffset and yoffset values)

The base resolutions thus defined by the UNIT keyword section of the media definition are used as the units of the media definition keyword sections:

  • SIZE (width and height values)

  • PRINTAREA (x, y, width and height values)

  • RESTRICTED (x, y, width and height values)


9.3 Form Definition
XFSFORM |  | formname* |
BEGIN |  |  |
(required) | UNIT | base, | Base resolution unit for form definition MM INCH ROWCOLUMN
 |  | x, | Horizontal base unit fraction
 |  | y | Vertical base unit fraction
(required) | SIZE | width, | Width of form
 |  | height | Height of form
 | ALIGNMENT | alignment, | Alignment of the form on the physical medium: TOPLEFT (default) TOPRIGHT BOTTOMLEFT BOTTOMRIGHT This option allows the positioning of a form onto a physical page relative to any combination of the edges of the physical medium, to support the variations in how devices sense the edge of page for positioning purposes.
 |  | xoffset, | Horizontal offset relative to the horizontal alignment specified by alignment. Always specified as a positive value (i.e., if aligned to the right side of the medium, means offset the form to the left). (default = 0)
 |  | yoffset | Vertical offset relative to the vertical alignment specified by alignment. Always specified as a positive value (i.e., if aligned to the bottom of the medium, means offset the form upward). (default = 0)
 | ORIENTATION | type | Orientation of form: PORTRAIT (default) LANDSCAPE
 | SKEW | skewfactor | Maximum skew factor in degrees (default = 0)
 | VERSION | major, | Major version number
 |  | minor, | Minor version number
 |  | date*, | Creation/modification date
 |  | author* | Author of form
(required) | LANGUAGE | languageID | Language used in this form – a 16 bit value (LANGID) which is a combination of a primary (10 bits) and a secondary (6 bits) language ID (This is the standard language ID in the Win32 API; standard macros support construction and decomposition of this composite ID)
 | COPYRIGHT | copyright* | Copyright entry
 | TITLE | title* | Title of form
 | COMMENT | comment* | Comment section
 | USERPROMPT | prompt* | Prompt string for user interaction
 | [ XFSFIELD | fieldname* | One field definition (as defined in the next section) for each field in the form
 | BEGIN . . . END ] |  |
 | [ XFSFRAME | framename* | One frame definition (as defined in the next section) for each frame in the form
 | BEGIN . . . END ] |  |
END |  |  |


9.4 Field Definition
XFSFIELD | fieldname*
BEGIN
(required) | POSITION | x, | Horizontal position (relative to left side of form)
y | Vertical position (relative to top of form)
FOLLOWS fieldname* Print this field directly following the field with the name <fieldname>; positioning information is ignored. See the description of WFS_CMD_PTR_PRINT_FORM.

If FOLLOWS is omitted then fields are printed in the order that they appear in the form definition.
SIDE side Side of form where field is positioned:
FRONT (default)
BACK
(required) | SIZE | width, | Field width
height | Field height
INDEX | repeatcount, | Count how often this field is repeated in the form, INDEX fields are fixed length. (default is no index field)
xoffset, | Horizontal offset for next field
yoffset | Vertical offset for next field
TYPE fieldtype Type of field:
TEXT (default)
MICR
OCR
MSF
BARCODE

GRAPHIC

PAGEMARK
SCALING scalingtype Information on how to size the GRAPHIC within the field:

BESTFIT (default) scale to size indicated

ASIS render at native size

MAINTAINASPECT scale as close as possible to size indicated while maintaining the aspect ratio and not losing graphic information.

SCALING is only relevant for GRAPHIC field types.
BARCODE hriposition Position of the HRI (Human Readable Interpretation) characters:

NONE (default)

ABOVE

BELOW

BOTH

The type of barcode to print is defined in the FONT field.
CLASS class Field class
OPTIONAL (default)
STATIC
REQUIRED
ACCESS access Access rights of field
WRITE (default)
READ
READWRITE
OVERFLOW overflow Action on field overflow:
TERMINATE (default)
TRUNCATE
BESTFIT (the service provider fits the data
into the field as well as it can)
OVERWRITE (a contiguous write)
WORDWRAP
STYLE style Display attributes as a combination of the following, ORed together using the "|" operator:
NORMAL (default)
BOLD
ITALIC
UNDER (single underline)
DOUBLEUNDER (double underline)
DOUBLE (double width)
TRIPLE (triple width)

QUADRUPLE (quadruple width)

STRIKETHROUGH

ROTATE90 (rotate +90 degrees clockwise)

ROTATE270 (rotate +270 degrees clockwise)

UPSIDEDOWN (upside down)

PROPORTIONAL (proportional spacing)

DOUBLEHIGH

TRIPLEHIGH

QUADRUPLEHIGH

CONDENSED

SUPERSCRIPT

SUBSCRIPT

OVERSCORE

LETTERQUALITY

NEARLETTERQUALITY

DOUBLESTRIKE

OPAQUE (If omitted then default attribute is transparent)

Some of these Styles may be mutually exclusive, or may combine to provide unexpected results.
CASE case Convert field contents to
NOCHANGE (default)
UPPER
LOWER
HORIZONTAL justify Horizontal alignment of field contents
LEFT (default)
RIGHT
CENTER
JUSTIFY
VERTICAL justify Vertical alignment of field contents
BOTTOM (default)
CENTER
TOP
COLOR color Color name
BLACK (default)
WHITE
GRAY
RED
BLUE
GREEN
YELLOW
LANGUAGE languageID Language used in this field – a 16 bit value (LANGID) which is a combination of a primary (10 bits) and a secondary (6 bits) language ID (This is the standard language ID in the Win32 API; standard macros support construction and decomposition of this composite ID)

If unspecified defaults to form definition LANGUAGE specification.
Font FONT fontname* Font name: This attribute is interpreted by the service provider. In some cases it may indicate printer resident fonts, and in others it may indicate the name of a downloadable font. For BARCODE fields it represents the barcode font name.

In some cases this predefines the following parameters:
Definition | POINTSIZE | pointsize | Point size
Information | CPI | cpi | Characters per inch
LPI | lpi | Lines per inch
FORMAT | formatstring* | This is an application defined input field describing how the application should format the data. This may be interpreted by the service provider.
INITIALVALUE value* Initial value, for GRAPHIC type fields, this value may contain the filename of the graphic image. The type of this graphic will be determined by the file extension (e.g. BMP for Windows Bitmap). Graphic file name may be full or partial path.

For example “C:\BSVC\BSVCLOGO.BMP” illustrates use of full path name.

A file name specification of “LOGO.BMP” illustrates partial path name. In this instance file is obtained from current directory.
END

The following diagrams illustrate the positioning and sizing of text fields on a form, and, in particular, the vertical alignment of text within a field using VERTICAL=TOP and VERTICAL=BOTTOM values in the field definition.

VERTICAL=TOP the upper boundary of the character drawing box (shown below) is positioned vertically to the upper field boundary.

VERTICAL=BOTTOM the baseline of the character drawing box (shown below)
is positioned vertically to the lower field boundary.

Definition of the character drawing box:

When more than one line of text is to be printed in a field, and the definition includes VERTICAL=BOTTOM, the vertical position of the first line is calculated using the specified (or implied) LPI value.


9.5 Frame Definition
XFSFRAME |  | framename* |
BEGIN |  |  |
(required) | POSITION | x, | Horizontal position of top left corner of the frame (relative to left side of form)
 |  | y | Vertical position of top left corner of the frame (relative to top of form)
 | FRAMES | fieldname* | Frames the field with the name <fieldname>, positioning information is ignored. The frame surrounds the complete field, not just the printed data. If the field is repeated, the frame surrounds the first and last fields that are printed.
 | SIDE | side | Side of form where this frame is positionned: FRONT (default) BACK
(required) | SIZE | width, | Frame width in base horizontal units for the form
 |  | height | Frame height in base vertical units for the form
 | REPEATONX | repeatcount, | Count how often this frame is repeated horizontally in the form.
 |  | xoffset | Horizontal offset for next frame in base horizontal units.
 | REPEATONY | repeatcount, | Count how often this frame is repeated vertically in the form.
 |  | yoffset | Vertical offset for next frame in base vertical units.
 | TYPE | frametype | Type of frame: RECTANGLE (default) ROUNDED_CORNER ELLIPSE
 | CLASS | class | Frame class: STATIC (default) OPTIONAL (The frame is printed only if its name appears in the list of field names given as parameter to the WFSExecute command. In this case, the name of the frame must be different from all the names of the fields.)
 | OVERFLOW | overflow | Action on frame overflowing the form: TERMINATE (default) TRUNCATE BESTFIT (the service provider fits the frame into the media as well as it can)
 | STYLE | style | Frame line attributes: SINGLE_THIN (default) DOUBLE_THIN SINGLE_THICK DOUBLE_THICK DOTTED
 | COLOR | color | Color name for frame lines: BLACK (default) WHITE GRAY RED BLUE GREEN YELLOW
 | FILLCOLOR | color | Color name for interior of frame: BLACK WHITE (default) GRAY RED BLUE GREEN YELLOW
 | FILLSTYLE | style | Style for filling the interior of frame: NONE (default) SOLID Solid color BDIAGONAL Downward hatch (left to right) at 45 degrees CROSS Horizontal and vertical crosshatch DIAGCROSS Crosshatch at 45 degrees FDIAGONAL Upward hatch (left to right) at 45 degrees HORIZONTAL Horizontal hatch VERTICAL Vertical hatch
frame title | TITLE | fieldname* | Uses the field with the name <fieldname> as the title of the frame. Positioning information of the field is ignored.
definition | HORIZONTAL | justify | Horizontal alignment of the frame title: LEFT (default) CENTER RIGHT
information | VERTICAL | justify | Vertical alignment of the frame title: TOP (default) BOTTOM
END |  |  |

The XFSFRAME definition provides a means for framing a XFSFIELD text field. The basic concept of a XFSFRAME definition and corresponding XFSFIELD definition is illustrated as follows:

When the XFSFRAME frames a field, its positioning and size information are ignored. Instead, service providers should position the top left corner of the frame one horizontal base unit to the left and one vertical base unit to the top of the top left corner of the field. Similarly, service providers should size the frame so that it bottom right corner is one base unit below and to the right to the field. For instance, if the form units are ROWCOLUMN, and a XFSFRAME “A” is said to FRAME the XFSFIELD “B” which is positioned at row 1, column 1 with a size of 1 row and 20 columns, the frame will be drawn from row 0, column 0 to row 3, column 22.

The horizontal and vertical positioning of a frame title override the position of the named XFSFIELD. For instance, if a XFSFRAME “A” is said to have the XFSFIELD “B” as its title, with the default horizontal and vertical title justification, it is just as if XFSFIELD “B” had been positioned at the top left corner of the frame. Note that the SIZE information for the title field still is meaningful: it gives the starting and/or ending positions of the frame lines.

The SIDE attributes of the XFSFRAME and the XFSFIELDs it refers to must agree.

The width of the lines and the interval between the lines of doubled frames are vendor specific. Whether the lines are drawn using graphics printing or using pseudo-graphic is vendor specific. However, service provider are responsible for rendering intersecting frames.

Depending on the printer technology, framing of fields can substantially slow down the print process.

Support of framing by a service provider or the device it controls is not mandatory to be WOSA/XFS compliant.

Sample 1: Simple framing
XFSFORM "Multiple Balances" | When printed with the following field list:
BEGIN | Account[0]=0123456789123001
UNIT INCH, 16, 16 | Account[1]=0123456789123002
SIZE 91, 64 | Account[2]=0123456789123003
VERSION 1, 0, "13/09/96", "WOSA/XFS" | Balance[0]=$17465.12
LANGUAGE 0x0409 | Balance[1] =$2458.23
XFSFIELD "Account Title" | Balance[2]=$6542.78
BEGIN | Will print:
POSITION 15, 4 | Account | Balance
SIZE 30, 4 | 0123456789123001 | $17465.12
CLASS STATIC | 0123456789123002 | $2458.23
HORIZONTAL CENTER | 0123456789123003 | $6542.78
INITIALVALUE "Account" |
END |
XFSFIELD "Balance Title" | When printed with the following field list:
BEGIN | Account[0]=0123456789123001
POSITION 45, 4 | Balance[0]=$17465.12
SIZE 30, 4 | Will print:
CLASS STATIC |
HORIZONTAL CENTER | Account | Balance
INITIALVALUE "Balance" | 0123456789123001 | $17465.12
END |
XFSFIELD "Account" |
BEGIN |
POSITION 15, 8 |
SIZE 30, 4 |
INDEX 10, 0, 3 |
END //"Account" |
XFSFIELD "Balance" |
BEGIN |
POSITION 45, 8 |
SIZE 30, 4 |
INDEX 10, 0, 3 |
HORIZONTAL RIGHT |
END //"Balance" |
XFSFRAME "Account Title" |
BEGIN |
POSITION 15, 4 |
FRAMES "Account Title" |
SIZE 30, 4 |
STYLE DOUBLE_THIN |
END |
XFSFRAME "Balance Title" |
BEGIN |
POSITION 45, 4 |
FRAMES "Balance Title" |
SIZE 30, 4 |
STYLE DOUBLE_THIN |
END |
XFSFRAME "Account" |
BEGIN |
POSITION 15, 8 |
FRAMES "Account" |
SIZE 30, 34 |
STYLE DOUBLE_THIN |
END |
XFSFRAME "Balance" |
BEGIN |
POSITION 45, 8 |
FRAMES "Balance" |
SIZE 30, 34 |
STYLE DOUBLE_THIN |
END |
END |
Sample 2: Framing with title
XFSFORM "Bank Details" | When printed with the following field list:
BEGIN | Owner = Mr/Mrs Jean Leroy
UNIT INCH, 16, 16 | 21560 Hagerty Road
SIZE 121, 64 | Troy, MI.
VERSION 1, 0, "13/09/96", "WOSA/XFS Editor" |
LANGUAGE 0x0409 | will print:
XFSFIELD "Owner Frame Title" |
BEGIN |
POSITION 24, 9 |
SIZE 27, 3 | Mr/Mrs Jean Leroy
CLASS STATIC | 21560 Hagerty Road
HORIZONTAL CENTER | Troy, MI.
VERTICAL CENTER |
INITIALVALUE "Account Owner" |
END |
XFSFIELD "Owner" |
BEGIN |
POSITION 20, 11 |
SIZE 35, 9 |
CLASS REQUIRED |
VERTICAL TOP |
END //"Owner" |
XFSFRAME "Owner Frame" |
BEGIN |
POSITION 19, 10 |
FRAMES "Owner" |
SIZE 37, 11 |
TITLE "Owner Frame Title" |
HORIZONTAL CENTER |
END |
END |
Sample 3: Framing with filled interior
XFSFORM "Bank Details" | When printed with the following field list:
BEGIN | Owner = Mr/Mrs Jean Leroy
UNIT INCH, 16, 16 | 21560 Hagerty Road
SIZE 121, 64 | Troy, MI.
VERSION 1, 0, "13/09/96", "WOSA/XFS Editor" |
LANGUAGE 0x0409 | will print:
XFSFIELD "Owner" |
BEGIN |
POSITION 20, 11 |
SIZE 35, 9 |
CLASS REQUIRED | Mr/Mrs Jean Leroy
VERTICAL TOP | 21560 Hagerty Road
END | Troy, MI.
XFSFRAME "Owner Frame" |
BEGIN |
POSITION 19, 10 |
FRAMES "Owner" |
SIZE 37, 11 |
FILLCOLOR GRAY |
FILLSTYLE CROSS |
END |
END |
Sample 4: Repeated Framing
XFSFORM "Smart Account Number" | When printed with the following field list:
BEGIN | Account Number[0]=0
UNIT INCH, 16, 16 | Account Number[1]=1
SIZE 121, 64 | Account Number[2]=2
VERSION 1, 0, "13/09/96", "WOSA/XFS Editor" | Account Number[3]=3
LANGUAGE 0x0409 | Account Number[4]=4
XFSFIELD "Account Number" | Account Number[5]=5
BEGIN | Account Number[6]=6
POSITION 20, 8 | Account Number[7]=7
SIZE 4, 4 | Account Number[8]=8
INDEX 12, 4, 0 | Account Number[9]=9
HORIZONTAL CENTER | Account Number[10]=0
VERTICAL CENTER | Account Number[11]=1
END |
XFSFRAME "A/N Frame" |
BEGIN |
POSITION 20, 8 | will print
SIZE 4, 4 |
REPEATONX 12, 4 | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 0 | 1
END |
END |


9.6 Media Definition

The media definition determines those characteristics that result from the combination of a particular media type together with a particular vendor's printer. The aim is to make it easy to move forms between different vendors' printers which might have different constraints on how they handle a specific media type. It is the service provider's responsibility to ensure that the form definition does not specify the printing of any fields that conflict with the media definition. An example of such a conflict might be that the form definition asks for a field to be printed in an area that the media definition defines as an unprintable area.

The media definition is also intended to provide the capability of defining media types that are specific to the financial industry. An example is a passbook as shown below.

XFSMEDIA |  | medianame* |
BEGIN |  |  |
 | TYPE | type | Predefined media types are: GENERIC (default) MULTIPART PASSBOOK
(required) | UNIT | base, x, y, | Base resolution unit for media definition MM INCH ROWCOLUMN Horizontal base unit fraction Vertical base unit fraction
(required) | SIZE | width, | Width of physical media
 |  | height | Height of physical media (0 = unlimited, i.e, roll paper)
 | PRINTAREA | x, | Printable area relative
 |  | y, | to top left corner
 |  | width, | of physical media
 |  | height | (default = physical size of media)
 | RESTRICTED | x, | Restricted area relative to
 |  | y, | to top left corner
 |  | width, | of physical media
 |  | height | (default = no restricted area)
 | FOLD | fold | Type of passbook HORIZONTAL VERTICAL
 | STAGGERING | staggering | Staggering of passbook from top (default = 0)
 | PAGE | count | Number of pages in passbook (default = 0)
 | LINES | count | Number of printable lines (default = 0)
END |  |  |


10. C-Header File

/******************************************************************************
*                                                                             *
* xfsptr.h    WOSA/XFS - Banking Printer (PTR) definitions                    *
*               (receipt, journal, passbook and document printer)             *
*                                                                             *
*             Version 2.00  (11/11/96)                                        *
*                                                                             *
******************************************************************************/

#ifndef __INC_XFSPTR__H
#define __INC_XFSPTR__H

#ifdef __cplusplus
extern "C" {
#endif

#include <xfsapi.h>

/*   be aware of alignment   */
#pragma pack(push,1)

/* value of WFSPTRCAPS.wClass */

#define    WFS_SERVICE_CLASS_PTR            (1)
#define    WFS_SERVICE_CLASS_VERSION_PTR    (0x0002) /* Version 2.00 */
#define    WFS_SERVICE_CLASS_NAME_PTR       "PTR"

#define    PTR_SERVICE_OFFSET               (WFS_SERVICE_CLASS_PTR * 100)

/* PTR Info Commands */

#define    WFS_INF_PTR_STATUS               (PTR_SERVICE_OFFSET + 1)
#define    WFS_INF_PTR_CAPABILITIES         (PTR_SERVICE_OFFSET + 2)
#define    WFS_INF_PTR_FORM_LIST            (PTR_SERVICE_OFFSET + 3)
#define    WFS_INF_PTR_MEDIA_LIST           (PTR_SERVICE_OFFSET + 4)
#define    WFS_INF_PTR_QUERY_FORM           (PTR_SERVICE_OFFSET + 5)
#define    WFS_INF_PTR_QUERY_MEDIA          (PTR_SERVICE_OFFSET + 6)
#define    WFS_INF_PTR_QUERY_FIELD          (PTR_SERVICE_OFFSET + 7)

/* PTR Execute Commands */

#define    WFS_CMD_PTR_CONTROL_MEDIA        (PTR_SERVICE_OFFSET + 1)
#define    WFS_CMD_PTR_PRINT_FORM           (PTR_SERVICE_OFFSET + 2)
#define    WFS_CMD_PTR_READ_FORM            (PTR_SERVICE_OFFSET + 3)
#define    WFS_CMD_PTR_RAW_DATA             (PTR_SERVICE_OFFSET + 4)
#define    WFS_CMD_PTR_MEDIA_EXTENTS        (PTR_SERVICE_OFFSET + 5)
#define    WFS_CMD_PTR_RESET_COUNT          (PTR_SERVICE_OFFSET + 6)
#define    WFS_CMD_PTR_READ_IMAGE           (PTR_SERVICE_OFFSET + 7)

/* PTR Messages */

#define    WFS_EXEE_PTR_NOMEDIA             (PTR_SERVICE_OFFSET + 1)
#define    WFS_EXEE_PTR_MEDIAINSERTED       (PTR_SERVICE_OFFSET + 2)
#define    WFS_EXEE_PTR_FIELDERROR          (PTR_SERVICE_OFFSET + 3)
#define    WFS_EXEE_PTR_FIELDWARNING        (PTR_SERVICE_OFFSET + 4)
#define    WFS_USRE_PTR_RETRACTBINTHRESHOLD (PTR_SERVICE_OFFSET + 5)
#define    WFS_SRVE_PTR_MEDIATAKEN          (PTR_SERVICE_OFFSET + 6)
#define    WFS_USRE_PTR_PAPERTHRESHOLD      (PTR_SERVICE_OFFSET + 7)
#define    WFS_USRE_PTR_TONERTHRESHOLD      (PTR_SERVICE_OFFSET + 8)
#define    WFS_SRVE_PTR_MEDIAINSERTED       (PTR_SERVICE_OFFSET + 9)

/* values of WFSPTRSTATUS.fwDevice */

#define    WFS_PTR_DEVONLINE                WFS_STAT_DEVONLINE
#define    WFS_PTR_DEVOFFLINE               WFS_STAT_DEVOFFLINE
#define    WFS_PTR_DEVPOWEROFF              WFS_STAT_DEVPOWEROFF
#define    WFS_PTR_DEVBUSY                  WFS_STAT_DEVBUSY
#define    WFS_PTR_DEVNODEVICE              WFS_STAT_DEVNODEVICE
#define    WFS_PTR_DEVHWERROR               WFS_STAT_DEVHWERROR
#define    WFS_PTR_DEVUSERERROR             WFS_STAT_DEVUSERERROR

/* values of WFSPTRSTATUS.fwMedia */

#define    WFS_PTR_MEDIAPRESENT             (0)
#define    WFS_PTR_MEDIANOTPRESENT          (1)
#define    WFS_PTR_MEDIAJAMMED              (2)
#define    WFS_PTR_MEDIANOTSUPP             (3)
#define    WFS_PTR_MEDIAUNKNOWN             (4)
#define    WFS_PTR_MEDIAENTERING            (5)

/* values of WFSPTRSTATUS.fwPaper */

#define    WFS_PTR_PAPERFULL                (0)
#define    WFS_PTR_PAPERLOW                 (1)
#define    WFS_PTR_PAPEROUT                 (2)
#define    WFS_PTR_PAPERNOTSUPP             (3)
#define    WFS_PTR_PAPERUNKNOWN             (4)

/* values of WFSPTRSTATUS.fwToner */

#define    WFS_PTR_TONERFULL                (0)
#define    WFS_PTR_TONERLOW                 (1)
#define    WFS_PTR_TONEROUT                 (2)
#define    WFS_PTR_TONERNOTSUPP             (3)
#define    WFS_PTR_TONERUNKNOWN             (4)

/* values of WFSPTRSTATUS.fwInk */

#define    WFS_PTR_INKFULL                  (0)
#define    WFS_PTR_INKLOW                   (1)
#define    WFS_PTR_INKOUT                   (2)
#define    WFS_PTR_INKNOTSUPP               (3)
#define    WFS_PTR_INKUNKNOWN               (4)

/* values of WFSPTRSTATUS.fwLamp */

#define    WFS_PTR_LAMPOK                   (0)
#define    WFS_PTR_LAMPFADING               (1)
#define    WFS_PTR_LAMPINOP                 (2)
#define    WFS_PTR_LAMPNOTSUPP              (3)
#define    WFS_PTR_LAMPUNKNOWN              (4)

/* values of WFSPTRSTATUS.fwRetractBin */

#define    WFS_PTR_RETRACTBINOK             (0)
#define    WFS_PTR_RETRACTBINFULL           (1)
#define    WFS_PTR_RETRACTNOTSUPP           (2)
#define    WFS_PTR_RETRACTUNKNOWN           (3)
#define    WFS_PTR_RETRACTBINHIGH           (4)

/* values of WFSPTRCAPS.fwType */

#define    WFS_PTR_TYPERECEIPT              0x0001
#define    WFS_PTR_TYPEPASSBOOK             0x0002
#define    WFS_PTR_TYPEJOURNAL              0x0004
#define    WFS_PTR_TYPEDOCUMENT             0x0008

/* values of WFSPTRCAPS.wResolution, WFSPTRPRINTFORM.wResolution */

#define    WFS_PTR_RESLOW                   0x0001
#define    WFS_PTR_RESMED                   0x0002
#define    WFS_PTR_RESHIGH                  0x0004
#define    WFS_PTR_RESVERYHIGH              0x0008

/* values of WFSPTRCAPS.fwReadForm */

#define    WFS_PTR_READOCR                  0x0001
#define    WFS_PTR_READMICR                 0x0002
#define    WFS_PTR_READMSF                  0x0004
#define    WFS_PTR_READBARCODE              0x0008
#define    WFS_PTR_READPAGEMARK             0x0010
#define    WFS_PTR_READIMAGE                0x0020

/* values of WFSPTRCAPS.fwWriteForm */

#define    WFS_PTR_WRITETEXT                0x0001
#define    WFS_PTR_WRITEGRAPHICS            0x0002
#define    WFS_PTR_WRITEOCR                 0x0004
#define    WFS_PTR_WRITEMICR                0x0008
#define    WFS_PTR_WRITEMSF                 0x0010
#define    WFS_PTR_WRITEBARCODE             0x0020
#define    WFS_PTR_WRITESTAMP               0x0040

/* values of WFSPTRCAPS.fwExtents */

#define    WFS_PTR_EXTHORIZONTAL            0x0001
#define    WFS_PTR_EXTVERTICAL              0x0002

/* values of WFSPTRCAPS.fwControl, dwMediaControl */

#define    WFS_PTR_CTRLEJECT                0x0001
#define    WFS_PTR_CTRLPERFORATE            0x0002
#define    WFS_PTR_CTRLCUT                  0x0004
#define    WFS_PTR_CTRLSKIP                 0x0008
#define    WFS_PTR_CTRLFLUSH                0x0010
#define    WFS_PTR_CTRLRETRACT              0x0020
#define    WFS_PTR_CTRLSTACK                0x0040
#define    WFS_PTR_CTRLPARTIALCUT           0x0080
#define    WFS_PTR_CTRLALARM                0x0100
#define    WFS_PTR_CTRLATPFORWARD           0x0200
#define    WFS_PTR_CTRLATPBACKWARD          0x0400
#define    WFS_PTR_CTRLTURNMEDIA            0x0800
#define    WFS_PTR_CTRLSTAMP                0x1000

/* values of WFSFRMHEADER.wBase, WFSFRMMEDIA.wBase, WFSPTRMEDIAUNIT.wBase */

#define    WFS_FRM_INCH                     (0)
#define    WFS_FRM_MM                       (1)
#define    WFS_FRM_ROWCOLUMN                (2)

/* values of WFSFRMHEADER.wAlignment */

#define    WFS_FRM_TOPLEFT                  (0)
#define    WFS_FRM_TOPRIGHT                 (1)
#define    WFS_FRM_BOTTOMLEFT               (2)
#define    WFS_FRM_BOTTOMRIGHT              (3)

/* values of WFSFRMHEADER.wOrientation */

#define    WFS_FRM_PORTRAIT                 (0)
#define    WFS_FRM_LANDSCAPE                (1)

/* values of WFSFRMMEDIA.fwMediaType */
#define    WFS_FRM_MEDIAGENERIC             (0)
#define    WFS_FRM_MEDIAPASSBOOK            (1)
#define    WFS_FRM_MEDIAMULTIPART           (2)

/* values of WFSFRMMEDIA.fwFoldType */
#define    WFS_FRM_FOLDNONE                 (0)
#define    WFS_FRM_FOLDHORIZONTAL           (1)
#define    WFS_FRM_FOLDVERTICAL             (2)

/* values of WFSFRMFIELD.fwType */

#define    WFS_FRM_FIELDTEXT                (0)
#define    WFS_FRM_FIELDMICR                (1)
#define    WFS_FRM_FIELDOCR                 (2)
#define    WFS_FRM_FIELDMSF                 (3)
#define    WFS_FRM_FIELDBARCODE             (4)
#define    WFS_FRM_FIELDGRAPHIC             (5)
#define    WFS_FRM_FIELDPAGEMARK            (6)

/* values of WFSFRMFIELD.fwClass */

#define    WFS_FRM_CLASSSTATIC              (0)
#define    WFS_FRM_CLASSOPTIONAL            (1)
#define    WFS_FRM_CLASSREQUIRED            (2)

/* values of WFSFRMFIELD.fwAccess */

#define    WFS_FRM_ACCESSREAD               0x0001
#define    WFS_FRM_ACCESSWRITE              0x0002

/* values of WFSFRMFIELD.fwOverflow */

#define    WFS_FRM_OVFTERMINATE             (0)
#define    WFS_FRM_OVFTRUNCATE              (1)
#define    WFS_FRM_OVFBESTFIT               (2)
#define    WFS_FRM_OVFOVERWRITE             (3)
#define    WFS_FRM_OVFWORDWRAP              (4)

/* values of WFSPTRFIELDFAIL.wFailure */

#define    WFS_PTR_FIELDREQUIRED            (0)
#define    WFS_PTR_FIELDSTATICOVWR          (1)
#define    WFS_PTR_FIELDOVERFLOW            (2)
#define    WFS_PTR_FIELDNOTFOUND            (3)
#define    WFS_PTR_FIELDNOTREAD             (4)
#define    WFS_PTR_FIELDNOTWRITE            (5)
#define    WFS_PTR_FIELDHWERROR             (6)
#define    WFS_PTR_FIELDTYPENOTSUPPORTED    (7)
#define    WFS_PTR_FIELDGRAPHIC             (8)

/* values of WFSPTRPRINTFORM.wAlignment */

#define    WFS_PTR_ALNUSEFORMDEFN           (0)
#define    WFS_PTR_ALNTOPLEFT               (1)
#define    WFS_PTR_ALNTOPRIGHT              (2)
#define    WFS_PTR_ALNBOTTOMLEFT            (3)
#define    WFS_PTR_ALNBOTTOMRIGHT           (4)

/* values of WFSPTRPRINTFORM.wOffsetX and WFSPTRPRINTFORM.wOffsetY */
#define    WFS_PTR_OFFSETUSEFORMDEFN        0xffff

/* values of WFSPTRRAWDATA.wInputData */

#define    WFS_PTR_NOINPUTDATA              (0)
#define    WFS_PTR_INPUTDATA                (1)

/* values of WFSPTRIMAGE.wImageType */

#define    WFS_PTR_IMAGETIF                 (1)
#define    WFS_PTR_IMAGEMTF                 (2)
#define    WFS_PTR_IMAGEBMP                 (3)

/* WOSA/XFS PTR Errors */

#define    WFS_ERR_PTR_FORMNOTFOUND         (-(PTR_SERVICE_OFFSET + 0))
#define    WFS_ERR_PTR_FIELDNOTFOUND        (-(PTR_SERVICE_OFFSET + 1))
#define    WFS_ERR_PTR_NOMEDIAPRESENT       (-(PTR_SERVICE_OFFSET + 2))
#define    WFS_ERR_PTR_READNOTSUPPORTED     (-(PTR_SERVICE_OFFSET + 3))
#define    WFS_ERR_PTR_FLUSHFAIL            (-(PTR_SERVICE_OFFSET + 4))
#define    WFS_ERR_PTR_MEDIAOVERFLOW        (-(PTR_SERVICE_OFFSET + 5))
#define    WFS_ERR_PTR_FIELDSPECFAILURE     (-(PTR_SERVICE_OFFSET + 6))
#define    WFS_ERR_PTR_FIELDERROR           (-(PTR_SERVICE_OFFSET + 7))
#define    WFS_ERR_PTR_MEDIANOTFOUND        (-(PTR_SERVICE_OFFSET + 8))
#define    WFS_ERR_PTR_EXTENTNOTSUPPORTED   (-(PTR_SERVICE_OFFSET + 9))
#define    WFS_ERR_PTR_MEDIAINVALID         (-(PTR_SERVICE_OFFSET + 10))
#define    WFS_ERR_PTR_FORMINVALID          (-(PTR_SERVICE_OFFSET + 11))
#define    WFS_ERR_PTR_FIELDINVALID         (-(PTR_SERVICE_OFFSET + 12))
#define    WFS_ERR_PTR_MEDIASKEWED          (-(PTR_SERVICE_OFFSET + 13))
#define    WFS_ERR_PTR_RETRACTBINFULL       (-(PTR_SERVICE_OFFSET + 14))
#define    WFS_ERR_PTR_STACKERFULL          (-(PTR_SERVICE_OFFSET + 15))
#define    WFS_ERR_PTR_PAGETURNFAIL         (-(PTR_SERVICE_OFFSET + 16))
#define    WFS_ERR_PTR_MEDIATURNFAIL        (-(PTR_SERVICE_OFFSET + 17))

/*=================================================================*/
/* PTR Info Command Structures and variables */
/*=================================================================*/

typedef struct _wfs_ptr_status
{
    WORD            fwDevice;
    WORD            fwMedia;
    WORD            fwPaper;
    WORD            fwToner;
    WORD            fwInk;
    WORD            fwLamp;
    WORD            fwRetractBin;
    USHORT          usRetractCount;
    USHORT          usMediaOnStacker;
    LPSTR           lpszExtra;
} WFSPTRSTATUS, * LPWFSPTRSTATUS;

typedef struct _wfs_ptr_caps
{
    WORD            wClass;
    WORD            fwType;
    BOOL            bCompound;
    WORD            wResolution;
    WORD            fwReadForm;
    WORD            fwWriteForm;
    WORD            fwExtents;
    WORD            fwControl;
    USHORT          usMaxRetract;
    USHORT          usMaxMediaOnStacker;
    BOOL            bAcceptMedia;
    LPSTR           lpszExtra;
} WFSPTRCAPS, * LPWFSPTRCAPS;

typedef struct _wfs_frm_header
{
    LPSTR           lpszFormName;
    WORD            wBase;
    WORD            wUnitX;
    WORD            wUnitY;
    WORD            wWidth;
    WORD            wHeight;
    WORD            wAlignment;
    WORD            wOrientation;
    WORD            wOffsetX;
    WORD            wOffsetY;
    WORD            wVersionMajor;
    WORD            wVersionMinor;
    LPSTR           lpszUserPrompt;
    LPSTR           lpszFields;
} WFSFRMHEADER, * LPWFSFRMHEADER;

typedef struct _wfs_frm_media
{
    WORD            fwMediaType;
    WORD            wBase;
    WORD            wUnitX;
    WORD            wUnitY;
    WORD            wSizeWidth;
    WORD            wSizeHeight;
    WORD            wPageCount;
    WORD            wLineCount;
    WORD            wPrintAreaX;
    WORD            wPrintAreaY;
    WORD            wPrintAreaWidth;
    WORD            wPrintAreaHeight;
    WORD            wRestrictedAreaX;
    WORD            wRestrictedAreaY;
    WORD            wRestrictedAreaWidth;
    WORD            wRestrictedAreaHeight;
    WORD            wStagger;
    WORD            wFoldType;
} WFSFRMMEDIA, * LPWFSFRMMEDIA;

typedef struct _wfs_ptr_query_field
{
    LPSTR           lpszFormName;
    LPSTR           lpszFieldName;
} WFSPTRQUERYFIELD, * LPWFSPTRQUERYFIELD;

typedef struct _wfs_frm_field
{
    LPSTR           lpszFieldName;
    WORD            wIndexCount;
    WORD            fwType;
    WORD            fwClass;
    WORD            fwAccess;
    WORD            fwOverflow;
    LPSTR           lpszInitialValue;
    LPSTR           lpszFormat;
} WFSFRMFIELD, * LPWFSFRMFIELD;

/*=================================================================*/
/* PTR Execute Command Structures */
/*=================================================================*/

typedef struct _wfs_ptr_print_form
{
    LPSTR           lpszFormName;
    LPSTR           lpszMediaName;
    WORD            wAlignment;
    WORD            wOffsetX;
    WORD            wOffsetY;
    WORD            wResolution;
    DWORD           dwMediaControl;
    LPSTR           lpszFields;
} WFSPTRPRINTFORM, * LPWFSPTRPRINTFORM;

typedef struct _wfs_ptr_read_form
{
    LPSTR           lpszFormName;
    LPSTR           lpszFieldNames;
    LPSTR           lpszMediaName;
    DWORD           dwMediaControl;
} WFSPTRREADFORM, * LPWFSPTRREADFORM;

typedef struct _wfs_ptr_raw_data
{
    WORD            wInputData;
    ULONG           ulSize;
    LPBYTE          lpbData;
} WFSPTRRAWDATA, * LPWFSPTRRAWDATA;

typedef struct _wfs_ptr_raw_data_in
{
    ULONG           ulSize;
    LPBYTE          lpbData;
} WFSPTRRAWDATAIN, * LPWFSPTRRAWDATAIN;

typedef struct _wfs_ptr_media_unit
{
    WORD            wBase;
    WORD            wUnitX;
    WORD            wUnitY;
} WFSPTRMEDIAUNIT, * LPWFSPTRMEDIAUNIT;

typedef struct _wfs_ptr_media_ext
{
    ULONG           ulSizeX;
    ULONG           ulSizeY;
} WFSPTRMEDIAEXT, * LPWFSPTRMEDIAEXT;

typedef struct _wfs_ptr_image
{
    WORD           wImageType;
    ULONG          ulSize;
    LPBYTE         lpImage;
} WFSPTRIMAGE, * LPWFSPTRIMAGE;

/*=================================================================*/
/* PTR Message Structures */
/*=================================================================*/

typedef struct _wfs_ptr_field_failure
{
    LPSTR           lpszFormName;
    LPSTR           lpszFieldName;
    WORD            wFailure;
} WFSPTRFIELDFAIL, * LPWFSPTRFIELDFAIL;

/*   restore alignment   */
#pragma pack(pop)

#ifdef __cplusplus
}       /*extern "C"*/

#endif

#endif /* __INC_XFSPTR__H */


WOSA

(Windowsä Open Services Architecture)

Extensions for Financial Services

A Client-Server Architecture for Financial Enterprise Computing under Microsoft® Windows

Identification Card Device Class Interface

–––––––––––––––––––––––––––––––––––

Programmer’s Reference

Revision 2.00

November 11, 1996

Developed by the members of the Banking Solutions Vendor Council


Table of Contents

1. Introduction

1.1 WOSA/XFS Service-Specific Programming

2. Identification Card Readers and Writers

3. Info Commands

3.1 WFS_INF_IDC_STATUS

3.2 WFS_INF_IDC_CAPABILITIES

3.3 WFS_INF_IDC_FORM_LIST

3.4 WFS_INF_IDC_QUERY_FORM

4. Execute Commands

4.1 WFS_CMD_IDC_READ_TRACK

4.2 WFS_CMD_IDC_WRITE_TRACK

4.3 WFS_CMD_IDC_EJECT_CARD

4.4 WFS_CMD_IDC_RETAIN_CARD

4.5 WFS_CMD_IDC_RESET_COUNT

4.6 WFS_CMD_IDC_SETKEY

4.7 WFS_CMD_IDC_READ_RAW_DATA

4.8 WFS_CMD_IDC_WRITE_RAW_DATA

4.9 WFS_CMD_IDC_CHIP_IO

5. Events

5.1 WFS_EXEE_IDC_INVALIDTRACKDATA

5.2 WFS_EXEE_IDC_MEDIAINSERTED

5.3 WFS_SRVE_IDC_MEDIAREMOVED

5.4 WFS_EXEE_IDC_INVALIDMEDIA

5.5 WFS_SRVE_IDC_CARDACTION

5.6 WFS_USRE_IDC_RETAINBINTHRESHOLD

6. Form Description

7. C-Header file


1.1 WOSA/XFS Service-Specific Programming

The service classes are defined by their service-specific commands and the associated data structures, error codes, messages, etc. These commands are used to request functions that are specific to one or more classes of service providers, but not all of them, and therefore are not included in the common API for basic or administration functions.

When a service-specific command is common among two or more classes of service providers, the syntax of the command is as similar as possible across all services, since a major objective of the WOSA Extensions for Financial Services is to standardize command codes and structures for the broadest variety of services. For example, using the WFSExecute function, the commands to read data from various services are as similar as possible to each other in their syntax and data structures.

In general, the specific command set for a service class is defined as the union of the specific capabilities likely to be provided by the developers of the services of that class; thus any particular device will normally support only a subset of the defined command set.

There are three cases in which a service provider may receive a service-specific command that it does not support:

  • The requested capability is defined for the class of service providers by the WOSA/XFS specification, the particular vendor implementation of that service does not support it, and the unsupported capability is not considered to be fundamental to the service. In this case, the service provider returns a successful completion, but does no operation. An example would be a request from an application to turn on a control indicator on a passbook printer; the service provider recognizes the command, but since the passbook printer it is managing does not include that indicator, the service provider does no operation and returns a successful completion to the application.

  • The requested capability is defined for the class of service providers by the WOSA/XFS specification, the particular vendor implementation of that service does not support it, and the unsupported capability is considered to be fundamental to the service. In this case, a WFS_ERR_UNSUPP_COMMAND error is returned to the calling application. An example would be a request from an application to a cash dispenser to dispense coins; the service provider recognizes the command but, since the cash dispenser it is managing dispenses only notes, returns this error.

  • The requested capability is not defined for the class of service providers by the WOSA/XFS specification. In this case, a WFS_ERR_INVALID_COMMAND error is returned to the calling application.

This design allows implementation of applications that can be used with a range of services that provide differing subsets of the functionalities that are defined for their service class. Applications may use the WFSGetInfo and WFSAsyncGetInfo commands to inquire about the capabilities of the service they are about to use, and modify their behavior accordingly, or they may use functions and then deal with WFS_ERR_UNSUPP_COMMAND error returns to make decisions as to how to use the service.


2. Identification Card Readers and Writers

This section describes the functions provided by a generic identification card reader/writer service (IDC). These descriptions include definitions of the service-specific commands that can be issued, using the WFSAsyncExecute, WFSExecute, WFSGetInfo and WFSAsyncGetInfo functions.

This service allows for the operation of the following categories of units:

  • motor driven card reader/writer

  • pull through card reader (writing facilities only partially included)

  • dip reader

  • contactless chip card readers
The following tracks/chips and the corresponding international standards are taken into account in this document:
Track 1 ISO 7811

Track 2 ISO 7811

Track 3 ISO 7811 / ISO 4909

Chip (contacted) ISO 7816

Chip (contactless) ISO 10536.

National standards like Transac for France or Watermark for Sweden are not considered, but can be easily included via the forms mechanism (see Section 6, Form Definition).

In addition to the pure reading of the tracks mentioned above, security boxes can be used via this service to check the data of writable tracks for manipulation. These boxes (such as CIM or MM) are sensor-equipped devices that are able to check some other information on the card and compare it with the track data.


3. Info Commands


3.1 WFS_INF_IDC_STATUS

Description This command reports the full range of information available, including the information that is provided either by the service provider or, if present, by any of the security modules. In addition to that, the number of cards retained is transmitted for motor driven card reader/writer (for devices of the other categories this number is always set to zero).

Input Param None.

Output Param LPWFSIDCSTATUS lpStatus;

typedef struct _wfs_idc_status
 {
 WORD   fwDevice;
 WORD   fwMedia;
 WORD   fwRetainBin;
 WORD   fwSecurity;
 USHORT   usCards;
 LPSTR   lpszExtra;
 } WFSIDCSTATUS, * LPWFSIDCSTATUS;

fwDevice
Specifies the state of the ID card device as one of the following flags:

Value Meaning

WFS_IDC_DEVONLINE The device is present, powered on and online (i.e., operational, not busy processing a request and not in an error state).

WFS_IDC_DEVOFFLINE The device is present and powered on, but offline (not operational–e.g., an operator has switched it offline).

WFS_IDC_DEVPOWEROFF The device is present but powered off.

WFS_IDC_DEVBUSY The device is present and is busy processing an Execute request.

WFS_IDC_DEVNODEVICE There is no device connected.

WFS_IDC_DEVUSERERROR The device is present but a person is preventing proper device operation. The application should suspend the device operation or remove the device from service until the service provider generates a device state change event indicating the condition of the device has changed e.g.the error is removed (WFS_IDC_DEVONLINE) or a permanent error condition has occurred (WFS_IDC_DEVHWERROR).

WFS_IDC_DEVHWERROR The device is present but inoperable due to a hardware fault that prevents it from being used.

fwMedia
Specifies the state of the ID card unit as one of the following flags:

Value Meaning

WFS_IDC_MEDIAPRESENT Media is present in the device, not in the entering position and not jammed.

WFS_IDC_MEDIANOTPRESENT Media is not present in the device and not at the entering position.

WFS_IDC_MEDIAJAMMED Media is jammed in the device; operator intervention is required.

WFS_IDC_MEDIANOTSUPP Capability to report media position is not supported by the device (e.g., a typical swipe reader).

WFS_IDC_MEDIAUNKNOWN The media state cannot be determined with the device in its current state (e.g., the value of fwDevice is WFS_IDC_DEVNODEVICE, WFS_IDC_DEVPOWEROFF, WFS_IDC_DEVOFFLINE, or WFS_IDC_DEVHWERROR).

WFS_IDC_MEDIAENTERING Media is at the entry/exit slot of a motorized device.

fwRetainBin
Specifies the state of the ID card unit retain bin as one of the following flags:

Value Meaning

WFS_IDC_RETAINBINOK The retain bin of the ID card unit is not full.

WFS_IDC_RETAINBINFULL The retain bin of the ID card unit is full.

WFS_IDC_RETAINBINHIGH The retain bin of the ID card unit is nearly full.

WFS_IDC_RETAINNOTSUPP The ID card unit does not support retain capability.

fwSecurity
Specifies the state of the security unit as one of the following flags:

Value Meaning

WFS_IDC_SECOPEN The security module is open and ready to process cards.

WFS_IDC_SECNOTREADY The security module is not ready to process cards.

WFS_IDC_SECNOTSUPP No security module is available.

usCards
The number of cards retained; applicable only to motor driven ID card units. This value is persistent (i.e., it survives power failures, opens, and closes): it is reset to zero by the WFS_CMS_IDC_RESET_COUNT command.

lpszExtra
Points to a list of vendor-specific, or any other extended, information. The information is returned as a series of "key=value" strings so that it is easily extensible by service providers. Each string is null-terminated, with the final string terminating with two null characters.

Error Codes There are no additional error codes generated by this command.

Comments Applications which require or expect specific information to be present in the lpszExtra parameter may not be device or vendor-independent.


3.2 WFS_INF_IDC_CAPABILITIES

Description This command is used to retrieve the capabilities of the ID card unit.

Input Param None.

Output Param LPWFSIDCCAPS lpCaps;

typedef struct _wfs_idc_caps
 {
 WORD   wClass;
 WORD   fwType;
 BOOL   bCompound;
 WORD   fwReadTracks;
 WORD   fwWriteTracks;
 WORD   fwChipProtocols;
 USHORT   usCards;
 WORD   fwSecType;
 WORD   fwPowerOnOption;
 WORD   fwPowerOffOption;
 LPSTR   lpszExtra;
 } WFSIDCCAPS, * LPWFSIDCCAPS;

wClass
Specifies the logical service class; value is WFS_SERVICE_CLASS_IDC

fwType
Specifies the type of the ID card unit as one of the following flags:

Value Meaning

WFS_IDC_TYPEMOTOR The ID card unit is a motor driven card unit.

WFS_IDC_TYPESWIPE The ID card unit is a swipe (pull-through) card unit .

WFS_IDC_TYPEDIP The ID card unit is a dip card unit.

WFS_IDC_TYPECONTACTLESS The ID card unit is a contactless card unit, i.e. no insertion of the card is required.

bCompound
Specifies whether the logical device is part of a compound physical device and is either TRUE or FALSE.

fwReadTracks
Specifies the tracks that can be read by the ID card unit as a combination of the following flags:

Value Meaning

WFS_IDC_NOTSUPP The ID card unit can not access any track.

WFS_IDC_TRACK1 The ID card unit can access track 1.

WFS_IDC_TRACK2 The ID card unit can access track 2.

WFS_IDC_TRACK3 The ID card unit can access track 3.

fwWriteTracks
Specifies the tracks that can be written by the ID card unit (as a combination of the flags specified in the description of fwReadTracks).

fwChipProtocols
Specifies the chip card protocols that are supported by the service provider as a combination of the following flags:

Value Meaning

WFS_IDC_NOTSUPP The ID card unit can not handle chip cards.

WFS_IDC_CHIPT0 The ID card unit can handle the T=0 protocol.

WFS_IDC_CHIPT1 The ID card unit can handle the T=1 protocol.

WFS_IDC_CHIPT2 The ID card unit can handle the T=2 protocol.

WFS_IDC_CHIPT3 The ID card unit can handle the T=3 protocol.

WFS_IDC_CHIPT4 The ID card unit can handle the T=4 protocol.

WFS_IDC_CHIPT5 The ID card unit can handle the T=5 protocol.

WFS_IDC_CHIPT6 The ID card unit can handle the T=6 protocol.

WFS_IDC_CHIPT7 The ID card unit can handle the T=7 protocol.

WFS_IDC_CHIPT8 The ID card unit can handle the T=8 protocol.

WFS_IDC_CHIPT9 The ID card unit can handle the T=9 protocol.

WFS_IDC_CHIPT10 The ID card unit can handle the T=10 protocol.

WFS_IDC_CHIPT11 The ID card unit can handle the T=11 protocol.

WFS_IDC_CHIPT12 The ID card unit can handle the T=12 protocol.

WFS_IDC_CHIPT13 The ID card unit can handle the T=13 protocol.

WFS_IDC_CHIPT14 The ID card unit can handle the T=14 protocol.

WFS_IDC_CHIPT15 The ID card unit can handle the T=15 protocol.

usCards
Specifies the maximum numbers of cards that the retain bin can hold (zero if not available).

fwSecType
Specifies the type of security module used as one of the following flags:

Value Meaning

WFS_IDC_SECNOTSUPP Device has no security module.

WFS_IDC_SECMMBOX Security module of device is MMBox.

WFS_IDC_SECCIM86 Security module of device is CIM86.

fwPowerOnOption
Specifies the power-on capabilities of the device hardware, as one of the following flags; applicable only to motor driven ID card units.

Value Meaning

WFS_IDC_NOACTION No power on actions are supported by the device

WFS_IDC_EJECT The card will be ejected on power-on (or off, see fwPowerOffOption below).

WFS_IDC_RETAIN The card will be retained on power-on (off).

WFS_IDC_EJECTTHENRETAIN The card will be ejected for a specified time on power-on (off), then retained if not taken. The time for which the card is ejected is vendor dependent.

WFS_IDC_READPOSITION The card will be moved into the read position on power-on (off).

fwPowerOffOption
Specifies the power-off capabilities of the device hardware, as one of the flags specified for fwPowerOnOption; applicable only to motor driven ID card units.

lpszExtra
Points to a list of vendor-specific, or any other extended information. The information is returned as a series of "key=value" strings so that it is easily extensible by service providers. Each string is null-terminated, with the final string terminating with two null characters.

Error Codes There are no additional error codes generated by this command.

Comments Applications which require or expect specific information to be present in the lpszExtra parameter may not be device or vendor-independent.


3.3 WFS_INF_IDC_FORM_LIST

Description This command is used to retrieve the list of forms available on the device.

Input Param None.

Output Param LPSTR lpszFormList;

lpszFormList
Pointer to a list of null-terminated form names, with the final name terminating with two null characters.

Error Codes There are no additional error codes generated by this command.

Comments None.


3.4 WFS_INF_IDC_QUERY_FORM

Description This command is used to retrieve details of the definition of a specified form.

Input Param LPSTR lpszFormName;

lpszFormName
Points to the null-terminated form name on which to retrieve details.

Output Param LPWFSIDCFORM lpForm;

typedef struct _wfs_idc_form
 {
  LPSTR  lpszFormName;
  char  cFieldSeparatorTrack1;
  char  cFieldSeparatorTrack2;
  char  cFieldSeparatorTrack3;
  WORD  fwAction;
  LPSTR  lpszTracks;
  BOOL  bSecure;
  LPSTR  lpszTrack1Fields;
  LPSTR  lpszTrack2Fields;
  LPSTR  lpszTrack3Fields;
 } WFSIDCFORM, * LPWFSIDCFORM;

lpszFormName
Specifies the null-terminated name of the form.

cFieldSeparatorTrack1
Specifies the value of the field separator of Track 1.

cFieldSeparatorTrack2
Specifies the value of the field separator of Track 2.

cFieldSeparatorTrack3
Specifies the value of the field separator of Track 3.

fwAction
is a flag word that specifies the form action; can be one of the following:

Value Meaning

WFS_IDC_ACTIONREAD The form reads the card.

WFS_IDC_ACTIONWRITE The form writes the card.

lpszTracks
Specifies the read algorithm or the track to write.

bSecure
Specifies whether or not to do a security check.

lpszTrack1Fields
Pointer to a list of null-terminated field names of Track 1, with the final name terminating with two null characters.

lpszTrack2Fields
Pointer to a list of null-terminated field names of Track 2, with the final name terminating with two null characters.

lpszTrack3Fields
Pointer to a list of null-terminated field names of Track 3, with the final name terminating with two null characters.

Error Codes The following additional error codes can be generated by this command:

Value Meaning

WFS_ERR_IDC_FORMNOTFOUND The specified form cannot be found.

WFS_ERR_IDC_FORMINVALID The specified form is invalid.

Comments None.


4. Execute Commands


4.1 WFS_CMD_IDC_READ_TRACK

Description For motor driven card readers, the ID card unit checks whether a card has been inserted. If so, the tracks are read immediately as described in the form specified by the lpFormsName parameter.

If no card has been inserted, and for all other categories of card readers, the ID card unit waits for the period of time specified in the WFSExecute call for a card to be either inserted or pulled through. Again the next step is reading the tracks specified in the form (see Section 6, Form Definition, for a more detailed description of the forms mechanism). In addition to that, the results of a security check via a security module (i.e., MM, CIM86) are specified and added to the track data.

Input Param LPSTR lpstrFormName;

lpstrFormName
Points to the name of the form that defines the behavior for the reading of tracks (see Section 6, Form Definition)

Output Param LPSTR lpstrTrackData;

lpstrTrackData
Points to the data read successfully from the selected tracks (and value of security module if available).

Error Codes The following additional error codes can be generated by this command:

Value Meaning

WFS_ERR_IDC_MEDIAJAM The card is jammed. Operator intervention is required.

WFS_ERR_IDC_SHUTTERFAIL The open of the shutter failed due to manipulation or hardware error. Operator intervention is required

WFS_ERR_IDC_INVALIDDATA The read operation specified by the forms definition could not be completed successfully due to invalid track data. This is returned if all tracks in an ‘or’ (|) operation cannot be read or if any track in an ‘and’ (&) operation cannot be read. lpstrTrackData points to data from the successfully read tracks (if any). One execute event (WFS_EXEE_IDC_INVALIDTRACKDATA) is generated for each specified track which could not be read successfully. See the form description for the rules defining how tracks are specified.

WFS_ERR_IDC_NOMEDIA No card was inserted within the specified time. For motor driven devices, the read is disabled; i.e., a card can not be inserted after a timeout.

WFS_ERR_IDC_INVALIDMEDIA No track found; card may have been inserted or pulled through the wrong way.

WFS_ERR_IDC_FORMNOTFOUND The specified form can not be found.

WFS_ERR_IDC_FORMINVALID The specified form definition is invalid (e.g., syntax error).

WFS_ERR_IDC_SECURITYFAIL The security module failed reading the cards security sign.

Events The following additional events can be generated by this command:

Value Meaning

WFS_EXEE_IDC_INVALIDTRACKDATA One event is generated for each blank track (no data) or invalid track (either data error reading the track or the data does not conform to the specified form definition).

WFS_EXEE_IDC_MEDIAINSERTED This event is generated when a card is detected in the device, giving early warning of card entry to an application, allowing it to remove a user prompt and/or do other processing while the card is being read.

WFS_SRVE_IDC_MEDIAREMOVED This event is generated when a card is removed before completion of a read operation.

WFS_EXEE_IDC_INVALIDMEDIA The user is attempting to insert the media in the wrong orientation. The card has not been accepted into the device. The device is still ready to accept a card inserted in the correct orientation.

Comments The track data is preceded by the keyword for the track, separated by a ‘:’. The field data is always preceded by the corresponding keyword, separated by a ‘=’. The fields are separated by 0x00. The data of the different tracks is separated by an additional 0x00. The end of the buffer is marked by another additional 0x00 (see example below). Data encoding is defined in Section 6, Form Definition.

Example of lpstrTrackData:
TRACK2:ALL=47..\0\0TRACK3:MII=59\0PAN=500..\0\0\0


4.2 WFS_CMD_IDC_WRITE_TRACK

Description For motor-driven card readers, the ID card unit checks whether a card has been inserted. If so, the data is written to the track as described in the form specified by the lpstrFormName parameter, and the other parameters.

If no card has been inserted, and for all other categories of devices, the ID card unit waits for the period of time specified in the WFSExecute call for a card to be either inserted or pulled through. The next step is writing the data defined by the form and the parameters to the respective track (see Section 6, Form Definition, for a more detailed description of the forms mechanism).

This procedure is followed by data verification.

Input Param LPWFSIDCWRITETRACK lpWriteTrack;

struct _wfs_idc_write_track
 {
 LPSTR   lpstrFormName;
 LPSTR   lpstrTrackData;
 } WFSIDCWRITETRACK, * LPWFSIDCWRITETRACK;

lpstrFormName
Points to the name of the form to be used.

lpstrTrackData
Points to the data to be used in the form.

Output Param None.

Error Codes The following additional error codes can be generated by this command:

Value Meaning

WFS_ERR_IDC_MEDIAJAM The card is jammed. Operator intervention is required.

WFS_ERR_IDC_SHUTTERFAIL The open of the shutter failed due to manipulation or hardware error. Operator intervention is required

WFS_ERR_IDC_NOMEDIA The card was removed before completion of the write operation.

WFS_ERR_IDC_INVALIDDATA An error occurred while writing the track.

WFS_ERR_IDC_DATASYNTAX The syntax of the data pointed to by lpstrTrackData is in error, or does not conform to the form definition.

WFS_ERR_IDC_INVALIDMEDIA No track found; card may have been inserted or pulled through the wrong way.

WFS_ERR_IDC_FORMNOTFOUND The specified form can not be found.

WFS_ERR_IDC_FORMINVALID The specified form definition is invalid (e.g., syntax error).

Events The following additional events can be generated by this command:

Value Meaning

WFS_EXEE_IDC_MEDIAINSERTED This event is generated when a card is detected in the device, giving early warning of card entry to an application, allowing it to remove a user prompt and/or do other processing while the card is being written.

WFS_SRVE_IDC_MEDIAREMOVED This event is generated when a card is removed before completion of a write operation.

Comments The field data is always preceded by the corresponding keyword, separated by an ‘=’. Fields are separated by 0x00. The end of the buffer is marked with an additional 0x00. (See the example below and Section 6, Form Definition.) This is a fundamental capability of an ID card unit; thus if a write request is received by a device with no write capability, the WFS_ERR_UNSUPP_COMMAND error is returned.

Example of lpstrTrackData:
RETRYCOUNT=3\0DATE=3132\0..\0\0


4.3 WFS_CMD_IDC_EJECT_CARD

Description The card is driven to the exit slot from where the user can remove it; applicable only to motor driven card readers. After successful completion of this command, a service event message is generated to inform the application when the card is taken. The card remains in position for withdrawal until either it is taken or the application sends a WFS_CMD_IDC_RETAIN command to retain the card internally.

Input Param None.

Output Param None.

Error Codes The following additional error codes can be generated by this command:

Value Meaning

WFS_ERR_IDC_MEDIAJAM The card is jammed. Operator intervention is required.

WFS_ERR_IDC_SHUTTERFAIL The open of the shutter failed due to manipulation or hardware error. Operator intervention is required.

WFS_ERR_IDC_NOMEDIA No card is present.

WFS_ERR_IDC_MEDIARETAINED The card has been retained during attempts to eject it. The device is clear and can be used.

Events The following additional events can be generated by this command:

Value Meaning

WFS_SRVE_IDC_MEDIAREMOVED The card has been taken by the user.

Comments This is a fundamental capability of an ID card unit; thus if an eject request is received by a device with no eject capability, the WFS_ERR_UNSUPP_COMMAND error is returned.


4.4 WFS_CMD_IDC_RETAIN_CARD

Description The card is removed from its present position (card inserted into device, card entering, unknown position) and stored in the retain bin; applicable to motor-driven card readers only. The ID card unit sends an event, if the storage capacity of the retain bin is reached. If the storage capacity has already been reached, and the command cannot be executed, an error is returned and the card remains in its present position.

If the execution of this command is performed without errors, the total number of cards retained includes the current card. If, however, an error occurs during the execution, the total number of cards retained does not include the current card.

Input Param None.

Output Param LPWFSIDCRETAINCARD lpRetainCard;

typedef struct _wfs_idc_retain_card
 {
 USHORT  usCount;
 WORD  fwPosition;
 } WFSIDCRETAINCARD, * LPWFSIDCRETAINCARD;

usCount
Total number of ID cards retained up to and including this operation, since the last WFS_CMD_IDC_RESET_COUNT command was executed.

fwPosition
Position of card; only relevant if card could not be retained. Possible positions:

Value Meaning

WFS_IDC_MEDIAUNKNOWN The position of the card can not be determined with the device in its current state.

WFS_IDC_MEDIAPRESENT The card is present in the reader.

WFS_IDC_MEDIAENTERING The card is in the entering position (shutter).

Error Codes The following additional error codes can be generated by this command:

Value Meaning

WFS_ERR_IDC_MEDIAJAM The card is jammed. Operator intervention is required.

WFS_ERR_IDC_NOMEDIA No card has been inserted. The fwPosition parameter has the value WFS_IDC_MEDIAUNKNOWN.

WFS_ERR_IDC_RETAINBINFULL The retain bin is full; no more cards can be retained. The current card is still in the device.

Events The following additional events can be generated by this command:

Value Meaning

WFS_USRE_IDC_RETAINBINTHRESHOLD The retain bin reached a threshold value.

Comments This is a fundamental capability of an ID card unit; thus if a retain request is received by a device with no retain capability, the WFS_ERR_UNSUPP_COMMAND error is returned.


4.5 WFS_CMD_IDC_RESET_COUNT

Description This function resets the present value for number of cards retained to zero. The function is possible for motor-driven card readers only.

The number of cards retained is controlled by the service and can be requested before resetting via the WFS_INF_IDC_STATUS.

Input Param None.

Output Param None.

Error Codes There are no additional error codes generated by this command.

Events There are no additional events generated by this command.

Comments This is a fundamental capability of an ID card unit; thus if this request is received by a device with no retain capability, the WFS_ERR_UNSUPP_COMMAND error is returned.


4.6 WFS_CMD_IDC_SETKEY

Description This command is used for setting the DES key that is necessary for operating a CIM86 module. The command must be executed before the first read command is issued to the card reader.

Input Param LPWFSIDCSETKEY lpSetkey;

typedef struct _wfs_idc_setkey
 {
 USHORT  usKeyLen;
 LPBYTE  lpbKeyValue;
 } WFSIDCSETKEY, *LPWFSIDCSETKEY;

usKeyLen

Specifies the length of the following key value.

lpbKeyValue

Pointer to a byte array containing the CIM86 DES key. This key is supplied by the vendor of the CIM86 module.

Output Param None.

Error Codes There are no additional error codes generated by this command.

Events There are no additional events generated by this command.

Comments None.


4.7 WFS_CMD_IDC_READ_RAW_DATA

Description For motor driven card readers, the ID card unit checks whether a card has been inserted. If so, all specified tracks are read immediately. If reading the chip is requested, the chip will be contacted and reset and the ATR (Answer To Reset) data will be read. When this command completes the chip will be in contacted position. This command can also be used for an explicit reset of a previously contacted chip.

If no card has been inserted, and for all other categories of card readers, the ID card unit waits for the period of time specified in the WFSExecute call for a card to be either inserted or pulled through. The next step is trying to read all tracks specified.

Magnetic stripe track data is converted from its 5 or 7 bit character form to 8 bit ASCII form. The parity bit from each 5 or 7 bit magnetic stripe character is discarded. Start and end sentinel characters are not returned to the application. Field separator characters are returned to the application, and are also converted to 8 bit ASCII form.

In addition to that, a security check via a security module (i.e., MM, CIM86) can be requested.

Input Param LPWORD lpwReadData;

lpwReadData
Specifies which data should be read as a combination of the following flags:

Value Meaning

WFS_IDC_TRACK1 Track 1 of the magnetic stripe will be read.

WFS_IDC_TRACK2 Track 2 of the magnetic stripe will be read.

WFS_IDC_TRACK3 Track 3 of the magnetic stripe will be read.

WFS_IDC_CHIP The chip will be read.

WFS_IDC_SECURITY A security check will be performed.

Output Param LPWFSIDCCARDDATA *lppCardData;

Pointer to a null-terminated array of pointers to card data structures:

struct _wfs_idc_card_data
 {
 WORD   wDataSource;
 WORD   wStatus;
 ULONG   ulDataLength;
 LPBYTE   lpbData;
 } WFSIDCCARDDATA, * LPWFSIDCCARDDATA;

wDataSource

Specifies the source of the card data as one of the following flags:

Value Meaning

WFS_IDC_TRACK1 lpbData contains data read from track 1.

WFS_IDC_TRACK2 lpbData contains data read from track 2.

WFS_IDC_TRACK3 lpbData contains data read from track 3.

WFS_IDC_CHIP lpbData contains ATR data read from the chip.

WFS_IDC_SECURITY lpbData contains the value returned by the security module.

wStatus

Status of reading the card data. Possible values are:

Value Meaning

WFS_IDC_DATAOK The data is ok.

WFS_IDC_DATAMISSING The track/chip is blank.

WFS_IDC_DATAINVALID The data contained on the track/chip is invalid.

WFS_IDC_DATATOOLONG The data contained on the track/chip is too long.

WFS_IDC_DATATOOSHORT The data contained on the track/chip is too short.

WFS_IDC_DATASRCNOTSUPP The data source to read from is not supported by the service provider.

WFS_IDC_DATASRCMISSING The data source to read from is missing on the card.

ulDataLength

Specifies the length of the following field lpbData.

lpbData

Points to the data read from the track/chip or the value returned by the security module.

Error Codes The following additional error codes can be generated by this command:

Value Meaning

WFS_ERR_IDC_MEDIAJAM The card is jammed. Operator intervention is required.

WFS_ERR_IDC_SHUTTERFAIL The open of the shutter failed due to manipulation or hardware error. Operator intervention is required

WFS_ERR_IDC_NOMEDIA The card was removed before completion of the read action.

WFS_ERR_IDC_INVALIDMEDIA No track or chip found; card may have been inserted or pulled through the wrong way.

Events The following additional events can be generated by this command:

Value Meaning

WFS_EXEE_IDC_MEDIAINSERTED This event is generated when a card is detected in the device, giving early warning of card entry to an application, allowing it to remove a user prompt and/or do other processing while the card is being read.

WFS_SRVE_IDC_MEDIAREMOVED This event is generated when a card is removed before completion of a read operation.

WFS_EXEE_IDC_INVALIDMEDIA The user is attempting to insert the media in the wrong orientation. The card has not been accepted into the device. The device is still ready to accept a card inserted in the correct orientation.

Comments None.


4.8 WFS_CMD_IDC_WRITE_RAW_DATA

Description For motor-driven card readers, the ID card unit checks whether a card has been inserted. If so, the data is written to the tracks.

If no card has been inserted, and for all other categories of devices, the ID card unit waits for the period of time specified in the WFSExecute call for a card to be either inserted or pulled through. The next step is writing the data to the respective tracks.

The application must pass the magnetic stripe data in ASCII without any sentinels. The data will be converted by the service provider.

This procedure is followed by data verification.

Input Param LPWFSIDCCARDDATA *lppCardData;
Pointer to a null-terminated array of pointers to card data structures:

struct _wfs_idc_card_data
 {
 WORD   wDataSource;
 WORD   wStatus;
 ULONG   ulDataLength;
 LPBYTE   lpbData;
 } WFSIDCCARDDATA, * LPWFSIDCCARDDATA;

wDataSource

Specifies the source of the card data as one of the following flags:

Value Meaning

WFS_IDC_TRACK1 lpbData contains data to be written to track 1.

WFS_IDC_TRACK2 lpbData contains data to be written to track 2.

WFS_IDC_TRACK3 lpbData contains data to be written to track 3.

wStatus
This parameter is ignored by this command.

ulDataLength

Specifies the length of the following field lpbData.

lpbData

Points to the data to be written to the track.

Output Param None.

Error Codes The following additional error codes can be generated by this command:

Value Meaning

WFS_ERR_IDC_MEDIAJAM The card is jammed. Operator intervention is required.

WFS_ERR_IDC_SHUTTERFAIL The open of the shutter failed due to manipulation or hardware error. Operator intervention is required

WFS_ERR_IDC_NOMEDIA The card was removed before completion of the write action.

WFS_ERR_IDC_INVALIDMEDIA No track found; card may have been inserted or pulled through the wrong way.

Events The following additional events can be generated by this command:

Value Meaning

WFS_EXEE_IDC_MEDIAINSERTED This event is generated when a card is detected in the device, giving early warning of card entry to an application, allowing it to remove a user prompt and/or do other processing while the card is being written.

WFS_SRVE_IDC_MEDIAREMOVED This event is generated when a card is removed before completion of a write operation.

WFS_EXEE_IDC_INVALIDMEDIA The user is attempting to insert the media in the wrong orientation. The card has not been accepted into the device. The device is still ready to accept a card inserted in the correct orientation.

Comments This is a fundamental capability of an ID card unit; thus if a write request is received by a device with no write capability, the WFS_ERR_UNSUPP_COMMAND error is returned.


4.9 WFS_CMD_IDC_CHIP_IO

Description This command is used to communicate with the chip. Transparent data is sent from the application to the chip and the response of the chip is returned transparently to the application.

The ATR of the chip must be obtained before issuing this command by issuing a Read Command.

Input Param LPWFSIDCCHIPIO lpChipIoIn;

struct _wfs_idc_chip_io
 {
 WORD   wChipProtocol;
 ULONG   ulChipDataLength;
 LPBYTE   lpbChipData;
 } WFSIDCCHIPIO, * LPWFSIDCCHIPIO;

wChipProtocol

Identifies the protocol that is used to communicate with the chip. Possible values are those described in WFS_INF_IDC_CAPABILITIES.

ulChipDataLength

Specifies the length of the following field lpbChipData.

lpbChipData

Points to the data sent to the chip.

Output Param LPWFSIDCCHIPIO lpChipIoOut;

struct _wfs_idc_chip_io
 {
 WORD   wChipProtocol;
 ULONG   ulChipDataLength;
 LPBYTE   lpbChipData;
 } WFSIDCCHIPIO, * LPWFSIDCCHIPIO;

wChipProtocol

Identifies the protocol that is used to communicate with the chip. This field contains the same value as the corresponding field in the input structure.

ulChipDataLength

Specifies the length of the following field lpbChipData.

lpbChipData

Points to the data responded from the chip.

Error Codes The following additional error codes can be generated by this command:

Value Meaning

WFS_ERR_IDC_MEDIAJAM The card is jammed. Operator intervention is required.

WFS_ERR_IDC_NOMEDIA There is no card inside the device.

WFS_ERR_IDC_INVALIDMEDIA No chip found; card may have been inserted or pulled through the wrong way.

WFS_ERR_IDC_INVALIDDATA An error occurred while communicating with the chip.

WFS_ERR_IDC_PROTOCOLNOTSUPP The protocol used was not supported by the service provider.

WFS_ERR_IDC_ATRNOTOBTAINED The ATR was not obtained before by issuing a Read Command.

Events The following additional events can be generated by this command:

Value Meaning

WFS_SRVE_IDC_MEDIAREMOVED This event is generated when a card is removed before completion of a write operation.

Comments None.


5. Events


5.1 WFS_EXEE_IDC_INVALIDTRACKDATA

Description This execute event specifies that a track contained invalid or no data.

Event Param LPWFSIDCTRACKEVENT lpTrackEvent;

struct _wfs_idc_track_event
{
WORD fwStatus;
LPSTR lpstrTrack;
LPSTR lpstrData;
} WFSIDCTRACKEVENT, * LPWFSIDCTRACKEVENT;

fwStatus
Status of reading the track. Possible values are :

Value Meaning

WFS_IDC_DATAMISSING The track is blank.

WFS_IDC_DATAINVALID The data contained on the track is invalid.

WFS_IDC_DATATOOLONG The data contained on the track is too long.

WFS_IDC_DATATOOSHORT The data contained on the track is too short.

lpstrTrack
Points to the keyword of the track on which the error occurred.

lpstrData
Points to the data that could be read (that may be only a fragment of the track), terminated by a null character. This data is simply a stream of characters; it does not contain keywords.


5.2 WFS_EXEE_IDC_MEDIAINSERTED

Description This execute event specifies that a card was inserted into the device.

Event Param None.


5.3 WFS_SRVE_IDC_MEDIAREMOVED

Description This service event specifies that the inserted card was manually removed by the user during the processing of a read/write command or after an eject operation.

Event Param None.


5.4 WFS_EXEE_IDC_INVALIDMEDIA

Description This execute event specifies that the media the user is attempting to insert is not a valid card or it is a card but it is in the wrong orientation.

Event Param None.


5.5 WFS_SRVE_IDC_CARDACTION

Description This service event specifies that a card has been retained or ejected by either the automatic power on or power off action of the device.

Event Param LPWFSIDCCARDACT lpCardAct;

typedef struct _wfs_idc_card_act
 {
 WORD   wAction;
 WORD   wPosition;
 } WFSIDCCARDACT, * LPWFSIDCCARDACT;

wAction
Specifies which action has been performed with the card. Possible values are :

Value Meaning

WFS_IDC_CARDRETAINED The card has been retained.

WFS_IDC_CARDEJECTED The card has been ejected.

WFS_IDC_CARDREADPOSITION The card has been moved to the read position

wPosition
Position of card before being retained or ejected. Possible values are :

Value Meaning

WFS_IDC_MEDIAUNKNOWN The position of the card can not be determined.

WFS_IDC_MEDIAPRESENT The card was present in the reader.

WFS_IDC_MEDIAENTERING The card was entering the reader.


5.6 WFS_USRE_IDC_RETAINBINTHRESHOLD

Description This user event specifies that the retain bin holding the retained cards is near full (according to the threshold value in the registry), requiring operator intervention soon.

Event Param LPWORD lpfwRetainBin;

lpfwRetainBin
Specifies the state of the ID card unit retain bin as one of the following flags:

Value Meaning

WFS_IDC_RETAINBINOK The retain bin of the ID card unit was emptied.

WFS_IDC_RETAINBINFULL The retain bin of the ID card unit is full.

WFS_IDC_RETAINBINHIGH The retain bin of the ID card unit is nearly full.


6. Form Description

This section describes the forms mechanism used to define the tracks to be read or written. Forms are contained in a single file, with one section for each defined form. The name of each section is the form name parameter in the WFS_CMD_IDC_READ_TRACK and WFS_CMD_IDC_WRITE_TRACK commands.

The currently active ID card unit (IDCU) form file is configured through the following key

WOSA/XFS_ROOT

FORMS

IDCU

formfile=<path><filename>

The read form defines which tracks should be read in the WFS_CMD_IDC_READ_TRACK command and what the response should be to a read failure. The read form can also be used to define logical track data, i.e. fields like “account number,” “issuer identifier,” and their position within the physical track data. For example, the output parameter of the WFS_CMD_IDC_READ_TRACK command with input parameter lpstrFormName = READTRACK3GERMAN could look like (see example 1 below):

"TRACK3:MII=59\0ISSUERID=50050500\0ACCOUNT=1234567890\0LUHNT3=1\0\0\0"

The write form defines which track is to be written, the logical track data that is handed over in the WFS_CMD_IDC_WRITE_TRACK command, and how the write data is to be converted to the physical data to be written.

Reserved Keywords/Operands Meaning

[] form name delimiters

TRACK1 keyword to identify track 1

TRACK2 keyword to identify track 2

TRACK3 keyword to identify track 3

FIELDSEPT1 value of field separator of track 1

FIELDSEPT2 value of field separator of track 2

FIELDSEPT3 value of field separator of track 3

READ description of read action; the TRACKn keywords are processed left to right

WRITE description of write action

ALL read or write the complete track

SECURE do the security check via the security module (CIM86 or MM)

& read/write all tracks specified, abort reading on read failure

| read/write at least one of the tracks specified, continue reading on read failure

FIELDSEPPOSn position of the nth occurrence of field separator on track

, separator in a list of logical fields

DEFAULT string for default substitution of track data to be written, that is not defined explicitly by the form fields. DEFAULT also allows an application to input fewer fields than those defined by the form.

? Reserved value for DEFAULT keyword: substitute track data to write with its value read before.

ENDTRACK is the reference to the end track position. It is used to identify fields positioned after the last field separator

Notes

The & and | operands may be combined in a single READ statement; for example:

  • read track3 or track2, trying track3 first:
    READ= TRACK3 | TRACK2

  • read track 3 and at least one of track2 or track1:
    READ= TRACK3 & (TRACK2 | TRACK1)
    or:
    READ= TRACK2 | TRACK1 & TRACK3

Use of field separators in track layouts is to replace optional fields and terminate variable length fields.

Write forms are designed for updating specific fields without altering the position of the field separators.

The application may alter the position of the field separators by rewriting the card tracks (ALL option or DEFAULT option with default track data).

Example 1 Reading tracks:

[READTRACK3GERMAN]
 FIELDSEPT1= =   /* field separator of track 1 */
 FIELDSEPT2= =  /* field separator of track 2 */
 FIELDSEPT3= =  /* field separator of track 3 */
 READ= TRACK3 & TRACK1 & TRACK2  /* all tracks must be read */
TRACK3= MII, ISSUERID, ACCOUNT, LUHNT3, SECURE /* read logical fields as defined below; also check the security */
 MII= FIELDSEPPOS1 + 1, FIELDSEPPOS1 + 2
 ISSUERID= FIELDSEPPOS1 + 3, FIELDSEPPOS1 + 10
 ACCOUNT= FIELDSEPPOS1 + 11, FIELDSEPPOS2 - 2
 LUHNT3= FIELDSEPPOS2 - 1, FIELDSEPPOS2 - 1
 TRACK2= ALL  /* return track2 complete,
       don't return logical fields */
 TRACK1= ALL  /* return track1 complete,
       don't return logical fields */

All tracks must be read (‘READ’), that is, the read fails if an error occurs on reading any one of the tracks (the ‘&’ operand). The field “major industry identifier” (‘MII’) is located after the first field separator (‘FIELDSEPPOS1’) and its length is two bytes. The “issuer identifier” field (‘ISSUERID’) is located after the MII field, with a length of eight bytes. The next field, “account number” (‘ACCOUNT’) is variable length; it ends before the luhn digit field (‘LUHNT3’) that is the last digit in front of the second field separator (‘FIELDSEPPOS2’).

Example 2 Write a track:

[WRITETRACK3]
FIELDSEPT3=  =
DEFAULT= ? /* fields not specified in the write form are to be left unchanged, i.e., read and the same data written back to them */
WRITE= TRACK3
TRACK3= RETRYCOUNT, DATE
RETRYCOUNT= FIELDSEPPOS2, + 22, FIELDSEPPOS2 + 22
DATE= FIELDSEPPOS5 + 1, FIELDSEPPOS5 + 4

Track 3 is to be written. In the example only the retry counter and the date of the last transaction are updated, the other fields are unchanged. (If the field ALL is defined, the data passed in the WFS_CMD_IDC_WRITE_TRACK command is written to the physical track without formatting.)


7. C-Header file

/******************************************************************************
*                                                                             *
* xfsidc.h    WOSA/XFS - Identification card reader/writer (IDC) definitions  *
*                                                                             *
*             Version 2.00  (11/11/96)                                        *
*                                                                             *
******************************************************************************/

#ifndef __INC_XFSIDC__H
#define __INC_XFSIDC__H

#ifdef __cplusplus
extern "C" {
#endif

#include <xfsapi.h>

/*   be aware of alignment   */
#pragma pack(push,1)

/* values of WFSIDCCAPS.wClass */

#define     WFS_SERVICE_CLASS_IDC               (2)
#define     WFS_SERVICE_CLASS_NAME_IDC          "IDC"
#define     WFS_SERVICE_CLASS_VERSION_IDC       0x0002

#define     IDC_SERVICE_OFFSET                  (WFS_SERVICE_CLASS_IDC * 100)

/* IDC Info Commands */

#define     WFS_INF_IDC_STATUS                  (IDC_SERVICE_OFFSET + 1)
#define     WFS_INF_IDC_CAPABILITIES            (IDC_SERVICE_OFFSET + 2)
#define     WFS_INF_IDC_FORM_LIST               (IDC_SERVICE_OFFSET + 3)
#define     WFS_INF_IDC_QUERY_FORM              (IDC_SERVICE_OFFSET + 4)

/* IDC Execute Commands */

#define     WFS_CMD_IDC_READ_TRACK              (IDC_SERVICE_OFFSET + 1)
#define     WFS_CMD_IDC_WRITE_TRACK             (IDC_SERVICE_OFFSET + 2)
#define     WFS_CMD_IDC_EJECT_CARD              (IDC_SERVICE_OFFSET + 3)
#define     WFS_CMD_IDC_RETAIN_CARD             (IDC_SERVICE_OFFSET + 4)
#define     WFS_CMD_IDC_RESET_COUNT             (IDC_SERVICE_OFFSET + 5)
#define     WFS_CMD_IDC_SETKEY                  (IDC_SERVICE_OFFSET + 6)
#define     WFS_CMD_IDC_READ_RAW_DATA           (IDC_SERVICE_OFFSET + 7)
#define     WFS_CMD_IDC_WRITE_RAW_DATA          (IDC_SERVICE_OFFSET + 8)
#define     WFS_CMD_IDC_CHIP_IO                 (IDC_SERVICE_OFFSET + 9)

/* IDC Messages */

#define     WFS_EXEE_IDC_INVALIDTRACKDATA       (IDC_SERVICE_OFFSET + 1)
#define     WFS_EXEE_IDC_MEDIAINSERTED          (IDC_SERVICE_OFFSET + 3)
#define     WFS_SRVE_IDC_MEDIAREMOVED           (IDC_SERVICE_OFFSET + 4)
#define     WFS_SRVE_IDC_CARDACTION             (IDC_SERVICE_OFFSET + 5)
#define     WFS_USRE_IDC_RETAINBINTHRESHOLD     (IDC_SERVICE_OFFSET + 6)
#define     WFS_EXEE_IDC_INVALIDMEDIA           (IDC_SERVICE_OFFSET + 7)

/* values of WFSIDCSTATUS.fwDevice */
#define     WFS_IDC_DEVONLINE                   WFS_STAT_DEVONLINE
#define     WFS_IDC_DEVOFFLINE                  WFS_STAT_DEVOFFLINE
#define     WFS_IDC_DEVPOWEROFF                 WFS_STAT_DEVPOWEROFF
#define     WFS_IDC_DEVBUSY                     WFS_STAT_DEVBUSY
#define     WFS_IDC_DEVNODEVICE                 WFS_STAT_DEVNODEVICE
#define     WFS_IDC_DEVHWERROR                  WFS_STAT_DEVHWERROR
#define     WFS_IDC_DEVUSERERROR                WFS_STAT_DEVUSERERROR

/* values of WFSIDCSTATUS.fwMedia, WFSIDCRETAINCARD.fwPosition,  */
/* WFSIDCCARDACT.fwPosition  */

#define     WFS_IDC_MEDIAPRESENT                (1)
#define     WFS_IDC_MEDIANOTPRESENT             (2)
#define     WFS_IDC_MEDIAJAMMED                 (3)
#define     WFS_IDC_MEDIANOTSUPP                (4)
#define     WFS_IDC_MEDIAUNKNOWN                (5)
#define     WFS_IDC_MEDIAENTERING               (6)

/* values of WFSIDCSTATUS.fwRetainBin */

#define     WFS_IDC_RETAINBINOK                 (1)
#define     WFS_IDC_RETAINNOTSUPP               (2)
#define     WFS_IDC_RETAINBINFULL               (3)
#define     WFS_IDC_RETAINBINHIGH               (4)

/* values of WFSIDCSTATUS.fwSecurity */

#define     WFS_IDC_SECNOTSUPP                  (1)
#define     WFS_IDC_SECNOTREADY                 (2)
#define     WFS_IDC_SECOPEN                     (3)

/* values of WFSIDCCAPS.fwPowerOnOption, WFSIDCCAPS.fwPowerOffOption,  */

#define     WFS_IDC_NOACTION                    (1)
#define     WFS_IDC_EJECT                       (2)
#define     WFS_IDC_RETAIN                      (3)
#define     WFS_IDC_EJECTTHENRETAIN             (4)
#define     WFS_IDC_READPOSITION                (5)

/* values of WFSIDCCAPS.fwType */

#define     WFS_IDC_TYPEMOTOR                   (1)
#define     WFS_IDC_TYPESWIPE                   (2)
#define     WFS_IDC_TYPEDIP                     (3)
#define     WFS_IDC_TYPECONTACTLESS             (4)

/* values of WFSIDCCAPS.fwReadTracks, WFSIDCCAPS.fwWriteTracks,
             WFSIDCCARDDATA.wDataSource */

#define     WFS_IDC_NOTSUPP                     0x0000
#define     WFS_IDC_TRACK1                      0x0001
#define     WFS_IDC_TRACK2                      0x0002
#define     WFS_IDC_TRACK3                      0x0004

/* further values of WFSIDCCARDDATA.wDataSource */

#define     WFS_IDC_CHIP                        0x0008
#define     WFS_IDC_SECURITY                    0x0010

/* values of WFSIDCCAPS.fwChipProtocols */

#define     WFS_IDC_CHIPT0                      0x0001
#define     WFS_IDC_CHIPT1                      0x0002
#define     WFS_IDC_CHIPT2                      0x0004
#define     WFS_IDC_CHIPT3                      0x0008
#define     WFS_IDC_CHIPT4                      0x0010
#define     WFS_IDC_CHIPT5                      0x0020
#define     WFS_IDC_CHIPT6                      0x0040
#define     WFS_IDC_CHIPT7                      0x0080
#define     WFS_IDC_CHIPT8                      0x0100
#define     WFS_IDC_CHIPT9                      0x0200
#define     WFS_IDC_CHIPT10                     0x0400
#define     WFS_IDC_CHIPT11                     0x0800
#define     WFS_IDC_CHIPT12                     0x1000
#define     WFS_IDC_CHIPT13                     0x2000
#define     WFS_IDC_CHIPT14                     0x4000
#define     WFS_IDC_CHIPT15                     0x8000

/* values of WFSIDCCAPS.fwSecType */

#define     WFS_IDC_SECNOTSUPP                  (1)
#define     WFS_IDC_SECMMBOX                    (2)
#define     WFS_IDC_SECCIM86                    (3)

/* values of WFSIDCFORM.fwAction */

#define     WFS_IDC_ACTIONREAD                  (1)
#define     WFS_IDC_ACTIONWRITE                 (2)

/* values of WFSIDCTRACKEVENT.fwStatus, WFSIDCCARDDATA.wStatus */

#define     WFS_IDC_DATAOK                      (0)
#define     WFS_IDC_DATAMISSING                 (1)
#define     WFS_IDC_DATAINVALID                 (2)
#define     WFS_IDC_DATATOOLONG                 (3)
#define     WFS_IDC_DATATOOSHORT                (4)
#define     WFS_IDC_DATASRCNOTSUPP              (5)
#define     WFS_IDC_DATASRCMISSING              (6)

/* values WFSIDCCARDACT.wAction */

#define     WFS_IDC_CARDRETAINED                (1)
#define     WFS_IDC_CARDEJECTED                 (2)
#define     WFS_IDC_CARDREADPOSITION            (3)

/* WOSA/XFS IDC Errors */

#define WFS_ERR_IDC_MEDIAJAM                    (-(IDC_SERVICE_OFFSET + 0))
#define WFS_ERR_IDC_NOMEDIA                     (-(IDC_SERVICE_OFFSET + 1))
#define WFS_ERR_IDC_MEDIARETAINED               (-(IDC_SERVICE_OFFSET + 2))
#define WFS_ERR_IDC_RETAINBINFULL               (-(IDC_SERVICE_OFFSET + 3))
#define WFS_ERR_IDC_INVALIDDATA                 (-(IDC_SERVICE_OFFSET + 4))
#define WFS_ERR_IDC_INVALIDMEDIA                (-(IDC_SERVICE_OFFSET + 5))
#define WFS_ERR_IDC_FORMNOTFOUND                (-(IDC_SERVICE_OFFSET + 6))
#define WFS_ERR_IDC_FORMINVALID                 (-(IDC_SERVICE_OFFSET + 7))
#define WFS_ERR_IDC_DATASYNTAX                  (-(IDC_SERVICE_OFFSET + 8))
#define WFS_ERR_IDC_SHUTTERFAIL                 (-(IDC_SERVICE_OFFSET + 9))
#define WFS_ERR_IDC_SECURITYFAIL                (-(IDC_SERVICE_OFFSET + 10))
#define WFS_ERR_IDC_PROTOCOLNOTSUPP             (-(IDC_SERVICE_OFFSET + 11))
#define WFS_ERR_IDC_ATRNOTOBTAINED              (-(IDC_SERVICE_OFFSET + 12))

/*=================================================================*/
/* IDC Info Command Structures and variables */
/*=================================================================*/

typedef struct _wfs_idc_status
{
    WORD            fwDevice;
    WORD            fwMedia;
    WORD            fwRetainBin;
    WORD            fwSecurity;
    USHORT          usCards;
    LPSTR           lpszExtra;
} WFSIDCSTATUS, * LPWFSIDCSTATUS;

typedef struct _wfs_idc_caps
{
    WORD            wClass;
    WORD            fwType;
    BOOL            bCompound;
    WORD            fwReadTracks;
    WORD            fwWriteTracks;
    WORD            fwChipProtocols;
    USHORT          usCards;
    WORD            fwSecType;
    WORD            fwPowerOnOption;
    WORD            fwPowerOffOption;
    LPSTR           lpszExtra;
} WFSIDCCAPS, * LPWFSIDCCAPS;

typedef struct _wfs_idc_form
{
    LPSTR           lpszFormName;
    CHAR            cFieldSeparatorTrack1;
    CHAR            cFieldSeparatorTrack2;
    CHAR            cFieldSeparatorTrack3;
    WORD            fwAction;
    LPSTR           lpszTracks;
    BOOL            bSecure;
    LPSTR           lpszTrack1Fields;
    LPSTR           lpszTrack2Fields;
    LPSTR           lpszTrack3Fields;
} WFSIDCFORM, * LPWFSIDCFORM;

/*=================================================================*/
/* IDC Execute Command Structures */
/*=================================================================*/

typedef struct _wfs_idc_write_track
{
    LPSTR           lpstrFormName;
    LPSTR           lpstrTrackData;
} WFSIDCWRITETRACK, * LPWFSIDCWRITETRACK;

typedef struct _wfs_idc_retain_card
{
    USHORT          usCount;
    WORD            fwPosition;
} WFSIDCRETAINCARD, * LPWFSIDCRETAINCARD;

typedef struct _wfs_idc_setkey
{
    USHORT          usKeyLen;
    LPBYTE          lpbKeyValue;
} WFSIDCSETKEY, * LPWFSIDCSETKEY;

typedef struct _wfs_idc_card_data
{
    WORD            wDataSource;
    WORD            wStatus;
    ULONG           ulDataLength;
    LPBYTE          lpbData;
} WFSIDCCARDDATA, * LPWFSIDCCARDDATA;

typedef struct _wfs_idc_chip_io
{
    WORD           wChipProtocol;
    ULONG          ulChipDataLength;
    LPBYTE         lpbChipData;
} WFSIDCCHIPIO, * LPWFSIDCCHIPIO;

/*=================================================================*/
/* IDC Message Structures */
/*=================================================================*/

typedef struct _wfs_idc_track_event
{
    WORD            fwStatus;
    LPSTR           lpstrTrack;
    LPSTR           lpstrData;
} WFSIDCTRACKEVENT, * LPWFSIDCTRACKEVENT;

typedef struct _wfs_idc_card_act
{
    WORD            wAction;
    WORD            wPosition;
} WFSIDCCARDACT, * LPWFSIDCCARDACT;

/*   restore alignment   */
#pragma pack(pop)

#ifdef __cplusplus
}       /*extern "C"*/
#endif

#endif  /* __INC_XFSIDC__H */


WOSA

(Windowsä Open Services Architecture)

Extensions for Financial Services

A Client-Server Architecture for
Financial Enterprise Computing under Microsoft® Windows

Cash Dispenser Device Class Interface

–––––––––––––––––––––––––––––––––––

Programmer’s Reference

Revision 2.00

November 11, 1996

Developed by the members of the Banking Solutions Vendor Council


Table of Contents

1. Introduction

1.1 WOSA/XFS Service-Specific Programming

2. Cash Dispensers
3. Info Commands

3.1 WFS_INF_CDM_STATUS

3.2 WFS_INF_CDM_CAPABILITIES

3.3 WFS_INF_CDM_CASH_UNIT_INFO

3.4 WFS_INF_CDM_TELLER_INFO

3.5 WFS_INF_CDM_TELLER_POSITIONS

3.6 WFS_INF_CDM_CURRENCY_EXP

3.7 WFS_INF_CDM_MIX_TYPES

3.8 WFS_INF_CDM_MIX_TABLE

3.9 WFS_INF_CDM_PRESENT_STATUS

4. Execute Commands

4.1 WFS_CMD_CDM_DENOMINATE

4.2 WFS_CMD_CDM_DISPENSE

4.3 WFS_CMD_CDM_PRESENT

4.4 WFS_CMD_CDM_REJECT

4.5 WFS_CMD_CDM_RETRACT

4.6 WFS_CMD_CDM_CASH_IN

4.7 WFS_CMD_CDM_OPEN_SHUTTER

4.8 WFS_CMD_CDM_CLOSE_SHUTTER

4.9 WFS_CMD_CDM_SET_TELLER_INFO

4.10 WFS_CMD_CDM_SET_CASH_UNIT_INFO

4.11 WFS_CMD_CDM_START_EXCHANGE

4.12 WFS_CMD_CDM_END_EXCHANGE

4.13 WFS_CMD_CDM_OPEN_SAFE_DOOR

4.14 WFS_CMD_CDM_CHECK_VANDALISM

4.15 WFS_CMD_CDM_CALIBRATE_CASH_UNIT

4.16 WFS_CMD_CDM_SET_TELLER_POSITIONS

4.17 WFS_CMD_CDM_CASH_IN_START

4.18 WFS_CMD_CDM_CASH_IN_END

4.19 WFS_CMD_CDM_CASH_IN_ROLLBACK

4.20 WFS_CMD_CDM_SET_MIX_TABLE

5. Events

5.1 WFS_SRVE_CDM_SAFEDOOROPEN

5.2 WFS_SRVE_CDM_SAFEDOORCLOSED

5.3 WFS_USRE_CDM_CASHUNITTHRESHOLD

5.4 WFS_SRVE_CDM_CASHUNITINFOCHANGED

5.5 WFS_SRVE_CDM_TELLERINFOCHANGED

5.6 WFS_EXEE_CDM_DELAYEDDISPENSE

5.7 WFS_EXEE_CDM_STARTDISPENSE

5.8 WFS_EXEE_CDM_CASHUNITERROR

5.9 WFS_SRVE_CDM_BILLSTAKEN

5.10 WFS_EXEE_CDM_PARTIALDISPENSE

5.11 WFS_EXEE_CDM_SUBDISPENSEOK

5.12 WFS_EXEE_CDM_INPUTREFUSE

6. C - Header file


1.1 WOSA/XFS Service-Specific Programming

The service classes are defined by their service-specific commands and the associated data structures, error codes, messages, etc. These commands are used to request functions that are specific to one or more classes of service providers, but not all of them, and therefore are not included in the common API for basic or administration functions.

When a service-specific command is common among two or more classes of service providers, the syntax of the command is as similar as possible across all services, since a major objective of the WOSA Extensions for Financial Services is to standardize command codes and structures for the broadest variety of services. For example, using the WFSExecute function, the commands to read data from various services are as similar as possible to each other in their syntax and data structures.

In general, the specific command set for a service class is defined as the union of the sets of specific capabilities likely to be provided by the developers of the services of that class; thus any particular device will normally support only a subset of the command set defined for the class.

There are three cases in which a service provider may receive a service-specific command that it does not support:

  • The requested capability is defined for the class of service providers by the WOSA/XFS specification, the particular vendor implementation of that service does not support it, and the unsupported capability is not considered to be fundamental to the service. In this case, the service provider returns a successful completion, but does no operation. An example would be a request from an application to turn on a control indicator on a passbook printer; the service provider recognizes the command, but since the passbook printer it is managing does not include that indicator, the service provider does no operation and returns a successful completion to the application.

  • The requested capability is defined for the class of service providers by the WOSA/XFS specification, the particular vendor implementation of that service does not support it, and the unsupported capability is considered to be fundamental to the service. In this case, a WFS_ERR_UNSUPP_COMMAND error is returned to the calling application. An example would be a request from an application to a cash dispenser to dispense coins; the service provider recognizes the command but, since the cash dispenser it is managing dispenses only bills, returns this error.

  • The requested capability is not defined for the class of service providers by the WOSA/XFS specification. In this case, a WFS_ERR_INVALID_COMMAND error is returned to the calling application.

This design allows implementation of applications that can be used with a range of services that provide differing subsets of the functionalities that are defined for their service class. Applications may use the WFSGetInfo and WFSAsyncGetInfo commands to inquire about the capabilities of the service they are about to use, and modify their behavior accordingly, or they may use functions and then deal with WFS_ERR_UNSUPP_COMMAND error returns to make decisions as to how to use the service.


2. Cash Dispensers

This specification describes the functionality of the services provided by cash dispenser module (CDM) services under WOSA/XFS, by defining the service-specific commands that can be issued, using the WFSGetInfo, WFSAsyncGetInfo, WFSExecute and WFSAsyncExecute functions. This section describes the functionality of a cash dispenser module (CDM) service that applies to both Automated Teller Safes (ATS) and Automated Teller Machines (ATM).

The components of an Automated Teller Safe are a cash (bills) dispenser, a transport unit, an output unit, and in some cases it also contains a coin dispenser and an alert unit.

An Automated Teller Machine contains the modules for cash dispensing plus additional modules such as magnetic card reader/writer, PIN pad, terminal, etc. The modules used for cash dispensing are essentially the same as those contained in the ATS: a bill/coupon/document dispenser, a transport module, an output module, and a coin dispenser, if available. Therefore, the cash dispensing functionality of the ATS and of the ATM is included in a single service class definition, referred to in this specification as “CDM” (cash dispenser module).

The implementation of the individual commands is device dependent (ATS or ATM). This is described in the documentation of each function.

The following table specifies which WFSGetInfo, WFSAsyncGetInfo, WFSExecute and WFSAsyncExecute commands are typically meaningful for the two kinds of devices.

Command | ATS | ATM
WFS_INF_CDM_STATUS | X | X
WFS_INF_CDM_CAPABILITIES | X | X
WFS_INF_CDM_CASH_UNIT_INFO | X | X
WFS_INF_CDM_TELLER_INFO | X |
WFS_INF_CDM_TELLER_POSITIONS | X |
WFS_INF_CDM_CURRENCY_EXP | X | X
WFS_INF_CDM_MIX_TYPES | X | X
WFS_INF_CDM_MIX_TABLE | X | X
WFS_INF_CDM_PRESENT_STATUS |  | X
WFS_CMD_CDM_DENOMINATE | X | X
WFS_CMD_CDM_DISPENSE | X | X
WFS_CMD_CDM_PRESENT |  | X
WFS_CMD_CDM_REJECT |  | X
WFS_CMD_CDM_RETRACT |  | X
WFS_CMD_CDM_CASH_IN | X |
WFS_CMD_CDM_SET_TELLER_INFO | X |
WFS_CMD_CDM_SET_CASH_UNIT_INFO | X | X
WFS_CMD_CDM_START_EXCHANGE | X | X
WFS_CMD_CDM_END_EXCHANGE | X | X
WFS_CMD_CDM_OPEN_SAFE DOOR | X | X
WFS_CMD_CDM_CLOSE_SHUTTER |  | X
WFS_CMD_CDM_OPEN_SHUTTER |  | X
WFS_CMD_CDM_CHECK_VANDALISM |  | X
WFS_CMD_CDM_CALIBRATE_CASH_UNIT | X | X
WFS_CMD_CDM_SET_TELLER_POSITIONS | X |
WFS_CMD_CDM_CASH_IN_START | X |
WFS_CMD_CDM_CASH_IN_END | X |
WFS_CMD_CDM_CASH_IN_ROLLBACK | X |
WFS_CMD_CDM_SET_MIX_TABLE | X | X

NOTE: All money amount parameters in this specification are expressed as a quantity of minimum dispense units for the respective currency, as defined in the description of the WFS_INF_CDM_CURRENCY_EXP command (Section 3.6).


3.1 WFS_INF_CDM_STATUS

Description This command is used to request the status of the devices attached to a CDM, such as the safedoor and other devices, or to retrieve device-specific information.

Input Param None.

Output Param LPWFSCDMSTATUS lpStatus;

typedef struct _wfs_cdm_status
 {
 WORD   fwDevice;
 WORD   fwSafeDoor;
 WORD   fwDispenser;
 WORD   fwIntermediateStacker;
 LPWFSCDMOUTPOS * lppOutputPositions;
 LPSTR   lpszExtra;
 } WFSCDMSTATUS, *  LPWFSCDMSTATUS;

fwDevice
Specifies the state of the cash dispenser device as one of the following flags:

Value Meaning

WFS_CDM_DEVONLINE The device is online. This is returned when the dispenser is present and operational. The fwDispenser field should be checked to determine the state of the cash units; if the state is WFS_CDM_DISPCUSTOP, no bills can be dispensed. The fwSafeDoor field can be checked to determine the state of the safe door, but note that the effect of the door state on the ability to dispense cash depends on the implementation of the specific service.

WFS_CDM_DEVOFFLINE The device is present and powered on, but is offline.

WFS_CDM_DEVPOWEROFF The device is present but is powered off.

WFS_CDM_DEVBUSY The device is busy processing a WFS[Async]Execute or WFS[Async]GetInfo request.

WFS_CDM_DEVNODEVICE There is no device connected.

WFS_CDM_DEVUSERERROR The device is present but a person is preventing proper device operation. The application should suspend the device from service until the service provider generates a device state change event indicating the condition of the device has changed, e.g., the error is removed (WFS_CDM_DEVONLINE) or a permanent error condition has occurred (WFS_CDM_DEVHWERROR).

WFS_CDM_DEVHWERROR The device is present and powered on, but is inoperable due to a hardware error. The device stays in this condition until the hardware error is cleared.

fwSafeDoor
Specifies the state of the safe door as one of the following flags:

Value Meaning

WFS_CDM_DOORNOTSUPPORTED Physical device has no safe door or door state reporting is not supported.

WFS_CDM_DOOROPEN Safe door is open.

WFS_CDM_DOORCLOSED Safe door is closed but not locked.

WFS_CDM_DOORLOCKED Safe door is closed and locked.

WFS_CDM_DOORUNKNOWN Due to a hardware error or other condition, the state of the door cannot be determined.

fwDispenser
Specifies the state of the dispenser cash units as one of the following flags:

Value Meaning

WFS_CDM_DISPOK All logical cash units present are in a good state.

WFS_CDM_DISPCUSTATE One of the logical cash units present is in an abnormal state. The dispenser is operational, but one or more of the cash units is in a low, empty or inoperative condition. Bills can still be dispensed from at least one of the cash units.

WFS_CDM_DISPCUSTOP Due to a cash unit failure dispensing is impossible. The dispenser is operational, but no bills can be dispensed because all of the cash units are in an empty or inoperative condition. This state also occurs when a reject cash unit is full or no reject cassette is present.

WFS_CDM_DISPCUUNKNOWN Due to a hardware error or other condition, the state of the cash units cannot be determined.

fwIntermediateStacker
Specifies the state of the intermediate stacker as one of the following flags:

Value Meaning

WFS_CDM_ISEMPTY The intermediate stacker is empty.

WFS_CDM_ISNOTEMPTY The intermediate stacker is not empty.

WFS_CDM_ISUNKNOWN Due to a hardware error or other condition, the state of the intermediate stacker cannot be determined.

WFS_CDM_ISNOTSUPPORTED The physical device has no intermediate stacker.

lppOutputPositions
Pointer to a NULL terminated array of pointers to WFSCDMOUTPOS structures (one for each supported output position):

typedef struct _wfs_cdm_outpos
 {
 WORD   fwPosition;
 WORD   fwShutter;
 WORD   fwOutputPosition;
 WORD   fwTransport;
 } WFSCDMOUTPOS, * LPWFSCDMOUTPOS;

fwPosition
Specifies the output position as one of the following flags:

Value Meaning

WFS_CDM_POSLEFT left output position.

WFS_CDM_POSRIGHT right output position.

WFS_CDM_POSCENTER center output position.

fwShutter
Specifies the state of the shutter as one of the following flags:

Value Meaning

WFS_CDM_SHTCLOSED The shutter is closed.

WFS_CDM_SHTOPEN The shutter is opened.

WFS_CDM_SHTJAMMED The shutter is jammed.

WFS_CDM_SHTUNKNOWN Due to a hardware error or other condition, the state of the shutter cannot be determined.

WFS_CDM_SHTNOTSUPPORTED The physical device has no shutter or shutter state reporting is not supported.

fwOutputPosition
Specifies the state of the cash tray as one of the following flags:

Value Meaning

WFS_CDM_CTEMPTY The cash tray is empty.

WFS_CDM_CTNOTEMPTY The cash tray is not empty.

WFS_CDM_CTUNKNOWN Due to a hardware error or other condition, the state of the cash tray cannot be determined.

WFS_CDM_CTNOTSUPPORTED The physical device has no cash tray or cash tray state reporting is not supported.

fwTransport
Specifies the state of the transport mechanism as one of the following flags:

Value Meaning

WFS_CDM_TPOK The transport is in a good state.

WFS_CDM_TPINOP The transport is inoperative due to a hardware failure or media jam.

WFS_CDM_TPUNKNOWN Due to a hardware error or other condition, the state of the transport cannot be determined.

WFS_CDM_TPNOTSUPPORTED The physical device has no transport or transport state reporting is not supported.

lpszExtra
Points to a list of vendor-specific, or any other extended information. The information is returned as a series of “key=value” strings so that it is easily extensible by service providers. Each string will be null-terminated, with the final string terminating with two null characters.

Error Codes There are no additional error codes generated by this command.

Comments Applications which require or expect specific information to be present in the lpszExtra parameter may not be device or vendor-independent.


3.2 WFS_INF_CDM_CAPABILITIES

Description This command is used to retrieve the capabilities of the cash dispenser.

Input Param None.

Output Param LPWFSCDMCAPS lpCaps;

typedef struct _wfs_cdm_caps
 {
 WORD   wClass;
 WORD   fwType;
 WORD   wMaxBills;
 WORD   wMaxCoins;
 BOOL   bCompound;
 BOOL   bShutter;
 BOOL   bRetract;
 BOOL   bSafeDoor;
 BOOL   bCoins;
 BOOL   bCylinders;
 BOOL   bCashBox;
 BOOL   bCashIn;
 BOOL   bRefill;
 BOOL   bAutoDeposit;
 BOOL   bVandalCheck;
 BOOL   bIntermediateStacker;
 BOOL   bBillsTakenSensor;
 WORD   fwOutputPositions;
 LPSTR   lpszExtra;
 } WFSCDMCAPS, * LPWFSCDMCAPS;

wClass
Specifies the logical service class. Value is:

WFS_SERVICE_CLASS_CDM

fwType
Specifies the type of the physical device driven by the logical service. Values are:

Value Meaning

WFS_CDM_TYPEATSAFE Device is an Automated Teller Safe.

WFS_CDM_TYPEATMACHINE Device is an Automated Teller Machine.

wMaxBills
Specifies the maximum number of bills or documents that can be dispensed by a single dispensing command; normally reflects hardware limitations of the device. If wMaxBills is 0 then no limit applies to the number of bills to be dispensed in a single dispense command. If the number of bills to be dispensed exceeds the hardware limitations of the device, this will be implemented by the Service Provider by multiple dispenses.

wMaxCoins
Specifies the maximum number of coins that can be dispensed by a single dispensing command; normally reflects hardware limitations of the device.

bCompound
Specifies whether the logical device is part of a compound physical device and is either TRUE or FALSE.

bShutter
Specifies whether the cash dispenser transport mechanism includes a shutter which normally is controlled by the dispensE or PRESENT command, but can be explicitly opened using WFS_CMD_CDM_OPEN_SHUTTER and closed using WFS_CMD_CDM_CLOSE_SHUTTER. Value is either TRUE or FALSE.

bRetract
Specifies whether the cash dispenser transport mechanism has the ability to retract presented bills. Value is either TRUE or FALSE. If no separate retract cash unit is present in the physical device, then retracts are retracted to the reject cash unit.

bSafedoor
Specifies whether the safe door has an electrical time lock, controlled by the WFS_CMD_CDM_OPEN_SAFE_DOOR command. Value is either TRUE or FALSE.

bCoins
Specifies whether the cash dispenser device includes a coin dispensing facility. Value is either TRUE or FALSE.

bCylinders
Specifies whether the coin dispenser device allows for number of coins per cylinder as input, or whether only totals are allowed. Value is either TRUE or FALSE.

bCashBox
Specifies whether the service provides the ability to count for a cashbox assigned to each teller. Value is either TRUE or FALSE. This field is always FALSE if the fwType is WFS_CDM_TYPEATMACHINE.

bCashIn
Specifies whether the service provides the ability to accumulate a cash in amount per currency assigned to each teller. Value is either TRUE or FALSE.

bRefill
Specifies that the device is equipped with cassettes that can be refilled during runtime by just dropping a bundle of bills on top of the stack. Normally, the device cannot detect and count the number of bills in the cassettes. Value is either TRUE or FALSE.

bAutoDeposit
Specifies whether the cash in device is able to deposit money and to provide the denomination as result. Value is either TRUE or FALSE.

bVandalCheck
Specifies whether the physical device includes a feature to check for vandalism. Value is either TRUE or FALSE.

bIntermediateStacker
Specifies whether or not the cash dispenser device supports stacking bills to an intermediate position before the bills are presented to the exit position. Value is either TRUE or FALSE. TRUE means the capability exists and the DISPENSE command can optionally stack bills using the input parameter bPresent=FALSE. Following this DISPENSE, a PRESENT command or REJECT command may be issued. FALSE means the DISPENSE command with a bPresent parameter of FALSE will be rejected with WFS_ERR_UNSUPP_COMMAND.

bBillsTakenSensor
Specifies whether or not the cash dispenser has the ability to detect when bills delivered to the exit position are taken by the user. TRUE means a sensor exists and the “bills taken” condition can be detected.

fwOutputPositions
Specifies which output positions are available on the physical device as a combination of the following flags:

Value Meaning

WFS_CDM_POSLEFT Device has a left output position.

WFS_CDM_POSRIGHT Device has a right output position.

WFS_CDM_POSCENTER Device has a center output position.

lpszExtra
Pointer to a list of vendor-specific, or any other extended information. The information is returned as a series of “key=value” strings so that it is easily extensible by service providers. Each string is null-terminated, with the final string terminating with two null characters.

Error Codes There are no additional error codes generated by this command.

Comments Applications which require or expect specific information to be present in the lpszExtra parameter may not be device or vendor-independent.


3.3 WFS_INF_CDM_CASH_UNIT_INFO

Description This command is used to get information about the status and contents of the logical and physical cash units used in the dispenser module.

Each logical bill or coin type cash unit can comprise one or more physical cash units. For all other types of cash unit there is a one to one relationship between physical and logical cash unit.

Information on logical cash units is used by the application to process transactions while the information on physical cash units is used during replenishment and maintenance operations.

All counters returned by this command are software counters and therefore might not represent the actual physical cash counts.

Input Param None.

Output Param LPWFSCDMCUINFO lpCashUnitInfo;

typedef struct _wfs_cdm_cu_info
 {
 USHORT     usTellerID;
 USHORT     usCount;
 LPWFSCDMCASHUNIT * lppList;
 } WFSCDMCUINFO, * LPWFSCDMCUINFO;

usTellerID
This field is not used in this command and is always NULL. In other commands that use this structure, and that relate to individual tellers (i.e., WFS_CMD_CDM_SET_CASH_UNIT_INFO, WFS_CMD_CDM_START_EXCHANGE, WFS_CMD_CDM_END_EXCHANGE), this field contains the appropriate teller ID value.

usCount
Specifies the number of cash unit structures returned.

lppList
Pointer to an array of pointers to cash unit structures:

typedef struct _wfs_cdm_cashunit
 {
 USHORT   usNumber;
 USHORT   usType;
 CHAR    cUnitID[5];
 CHAR    cCurrencyID[3];
 ULONG    ulValues;
 ULONG    ulInitialCount;
 ULONG    ulCount;
 ULONG    ulMinimum;
 ULONG    ulMaximum;
 BOOL    bAppLock;
 BOOL    bDevLock;
 USHORT   usStatus;
 LPSTR    lpPhysicalPositionName;
 USHORT   usNumPhysicalCUs;
 LPWFSCDMPHCU   * lppPhysical;
 } WFSCDMCASHUNIT, * LPWFSCDMCASHUNIT;

usNumber
Logical number of cash unit. Each structure has a unique logical number starting with a value of one (1) for the first structure, and incrementing by one for each subsequent structure.

usType
Type of cash unit. Possible values are:

Value Meaning

WFS_CDM_TYPENA Not applicable; typically means cash unit is missing.

WFS_CDM_TYPEREJECTCASSETTE Reject cassette of the cash dispenser.

WFS_CDM_TYPEBILLCASSETTE Bill cassette of the cash dispenser.

WFS_CDM_TYPECOINCYLINDER Cylinder of the coin dispenser.

WFS_CDM_TYPECOINDISPENSER Coin dispenser as a whole unit.

WFS_CDM_TYPERETRACTCASSETTE Retract cassette of the cash dispenser.

WFS_CDM_TYPECOUPON Cassette for coupons or advertising material.

WFS_CDM_TYPEDOCUMENT Cassette for documents.

cUnitID
Cash unit ID. This field provides information identifying a cash unit.

cCurrencyID
Currency ID (ISO format). Three blanks for a reject or a retract cassette which stores more than one currency type and for coupon cassettes which do not contain currencies.

ulValues
Values of coins/bills. This is the value of a single coin or bill in the cash unit, not the total value of the coins or bills present. (Amount expressed in minimum dispense units; see WFS_INF_CDM_CURRENCY_EXP.) Zero for a reject or a retract cassette and for coupon cassettes which do not contain valuable documents.

ulInitialCount
Initial number of coins/bills. This value is persistent; i.e, maintained through power failures, opens, closes and system resets. It is set by the WFS_CMD_CDM_END_EXCHANGE and the WFS_CMD_CDM_SET_CASH_UNIT_INFO commands.

ulCount
Actual count of coins/bills. This value is persistent; i.e, maintained through power failures, opens, closes and system resets. It is set by the WFS_CMD_CDM_END_EXCHANGE and the WFS_CMD_CDM_SET_CASH_UNIT_INFO commands, and is adjusted each time coins/bills are moved from or to the cash unit by a WFSExecute command. Note that for a reject cassette, this value is unreliable, since the typical reason for dumping bills to the reject cassette is a suspected count failure. For a retract cassette this value specifies the number of retracts.

ulMinimum
Specifies the minimum number of bills in a cash unit. If the number falls short of this value a threshold event (WFS_USRE_CDM_CASHUNITTHRESHOLD) is created. For retract and reject cassettes this value equals zero.

ulMaximum
Specifies the maximum number of bills in a cash unit. This value is needed for cash units that are refilled during a cash in operation, reject and retract cassettes. For all other cash units it equals zero. If the number exceeds this value a threshold event (WFS_USRE_CDM_CASHUNITTHRESHOLD) is created.

bAppLock
Application lock status of the logical cash unit. If set to TRUE, the cash unit is locked by the application and cannot be used until unlocked. Application locks can only be applied to bill cassettes and coin cylinders.

bDevLock
Device lock status of the logical cash unit. If set to TRUE, the cash unit is locked by the device and cannot be used until unlocked. Device locks can only be applied to bill cassettes and coin cylinders. Support for device locks is vendor-dependent.

usStatus
Describes the status of the logical cash unit. Available values are:

Value Meaning

WFS_CDM_STATCUOK The cash unit is in a good state.

WFS_CDM_STATCUFULL The reject or retract cassette is full.

WFS_CDM_STATCUHIGH The reject or retract cassette is almost full (threshold).

WFS_CDM_STATCULOW The cassette or coin cylinder is almost empty (threshold).

WFS_CDM_STATCUEMPTY The cassette or coin cylinder is empty.

WFS_CDM_STATCUINOP The cassette or coin cylinder is inoperative.

WFS_CDM_STATCUMISSING The cassette, reject or retract cassette is missing.

WFS_CDM_STATCUNOVAL The values of the specified cash unit are not available. This can be the case when the cassette is changed without using the operator functions.

WFS_CDM_STATCUNOREF There is no reference value available for the notes in this cassette.

lpPhysicalPositionName
This field points to a name (e.g. “hopper 1”) indicating the physical location in the dispenser device in which this cash unit is installed. This field is only used when the logical cash unit refers to one physical cash unit.

usNumPhysicalCUs
This value indicates the number of physical cash unit structures returned. If this field is zero then the logical cash unit structure above relates directly to a physical cash unit.

lppPhysical
Pointer to an array of pointers to physical cash unit structures:

typedef struct _wfs_cdm_physicalcu
{
LPSTR   lpPhysicalPositionName;
CHAR  cUnitID[5];
ULONG  ulCount;
USHORT  usPStatus;
} WFSCDMPHCU, * LPWFSCDMPHCU;

lpPhysicalPositionName

This field points to a name (e.g. “hopper 1”) indicating the physical location in the dispenser device in which this cash unit is installed.

cUnitID
Cash unit ID. This field provides information identifying a physical cassette clearly.

ulCount
Actual count of coins/bills in the physical cash unit.

usPStatus
Describes the status of the physical cash unit. Same values as usStatus.

Error Codes There are no additional error codes generated by this command.

Comments None.


3.4 WFS_INF_CDM_TELLER_INFO

Description This command is used for getting the tallies assigned to a teller. A set of tallies can be requested for each currency assigned to the teller.

Input Param LPWFSCDMTELLERINFO lpTellerInfo;

typedef struct _wfs_cdm_teller_info
 {
 USHORT   usTellerID;
 CHAR   cCurrencyID[3];
 } WFSCDMTELLERINFO, *LPWFSCDMTELLERINFO;

usTellerID
Identification of teller. The service provider maintains a list of valid teller IDs; if the usTellerID value is not present in the list, an error is reported. The implementation of the list is vendor dependent.

cCurrencyID
Identification of currency (ISO format).

Output Param LPWFSCDMTELLERTOTALS lpTellerTotals;

typedef struct _wfs_cdm_teller_totals
 {
 USHORT   usTellerID;
 CHAR   cCurrencyID[3];
 ULONG   ulBills;
 ULONG   ulCoins;
 ULONG   ulCashIn;
 ULONG   ulCashBox;
 } WFSCDMTELLERTOTALS, * LPWFSCDMTELLERTOTALS;

usTellerID
Identification of teller.

cCurrencyID
Identification of currency (ISO format).

ulBills
Amount of money dispensed from bill cassettes. (Amount expressed in minimum dispense units; see WFS_INF_CDM_CURRENCY_EXP.)

ulCoins
Amount of money dispensed from coin cylinders. (Amount expressed in minimum dispense units; see WFS_INF_CDM_CURRENCY_EXP.)

ulCashIn
Amount of money cashed in by teller. (Amount expressed in minimum dispense units; see WFS_INF_CDM_CURRENCY_EXP.)

ulCashBox
Amount dispensed from teller’s cash box. (Amount expressed in minimum dispense units; see WFS_INF_CDM_CURRENCY_EXP.)

Error Codes The following additional error codes can be generated by this command:

Value Meaning

WFS_ERR_CDM_INVALIDCURRENCY Specified currency not currently available

WFS_ERR_CDM_INVALIDTELLERID Teller ID not present in service provider’s teller ID list.

Comments None.


3.5 WFS_INF_CDM_TELLER_POSITIONS

Description This command is used to get the output position assigned to each teller.

Input Param None.

Output Param LPWFSCDMTELLERPOS * lppTellerPos;
Pointer to a null-terminated array of pointers to teller position structures:

typedef struct _wfs_cdm_teller_pos
 {
 USHORT  usTellerID;
 USHORT  usPosition;
 } WFSCDMTELLERPOS, *LPWFSCDMTELLERPOS;

usTellerID
Identification of teller.

usPosition
Output position where cash is presented to the teller. Possible values are:

Value Meaning

WFS_CDM_POSNULL No position assigned to teller.

WFS_CDM_POSLEFT Left position assigned to teller.

WFS_CDM_POSRIGHT Right position assigned to teller.

WFS_CDM_POSCENTER Center position assigned to teller.

Error Codes There are no additional error codes generated by this command.

Comments None.


3.6 WFS_INF_CDM_CURRENCY_EXP

Description This command is used for getting the exponents assigned to each currency used.

Input Param None.

Output Param LPWFSCDMCURRENCYEXP * lppCurrencyExp;
Pointer to a null-terminated array of pointers to currency exponent structures:

typedef struct _wfs_cdm_currency_exp
 {
 CHAR   cCurrencyID[3];
 SHORT   sExponent;
 } WFSCDMCURRENCYEXP, *LPWFSCDMCURRENCYEXP;

cCurrencyID
Currency identifier (ISO 4217 format).

sExponent
Currency exponent.

Error Codes There are no additional error codes generated by this command.

Comments For each currency ISO 4217 defines the currency identifier (a three character code) and a currency unit (e.g., German mark, Italian lira). In the interface defined by this specification, every money amount is specified in terms of multiples of the minimum dispense unit, which is equal to the currency unit times the currency exponent. Thus a money amount parameter relates to the actual cash amount as follows:
<cash_amount> = <money_amount_parameter> * 10^<sExponent>

Example #1 — Germany
Currency identifier is ‘DEM’
Currency unit is 1 German mark (= 100 pfennig)
A service provider is developed for an ATM that can dispense coins down to one pfennig. The currency exponent (sExponent) is set to -2 (minus two), so the minimum dispense unit is one pfennig (1 * 10^-2 mark); all amounts at the XFS interface are in pfennigs. Thus a money amount parameter of 10050 is 100 marks and 50 pfennig.

Example #2 — Italy
Currency identifier is ‘LIT’
Currency unit is 1 Italian lira
A service provider is required to dispense a minimum amount of 100 lire. The currency exponent (sExponent) is set to +2 (plus two), so the minimum dispense unit is 100 lire; all amounts at the XFS interface are in multiples of 100 lire. Thus a money amount parameter of 150 is 15000 lire.


3.7 WFS_INF_CDM_MIX_TYPES

Description This command is used to retrieve a list of supported mix algorithms and available house mix tables.

Input Param None.

Output Param LPWFSCDMMIXTYPE * lppMixTypes;
Pointer to a null-terminated array of pointers to mix type structures:

typedef struct _wfs_cdm_mix_type
 {
 USHORT   usMixNumber;
 USHORT   usMixType;
 USHORT   usSubType;
 LPSTR   lpszName;
 } WFSCDMMIXTYPE, *LPWFSCDMMIXTYPE;

usMixNumber
Internal number identifying the mix algorithm or the house mix table. This number is passed to the WFS_INF_CDM_MIX_TABLE, WFS_CMD_CDM_DISPENSE and WFS_CMD_CDM_DENOMINATE commands.

usMixType
Specifies whether the mix type is an algorithm or a house mix table. Values are:

Value Meaning

WFS_CDM_MIXALGORITHM Denominations are calculated using a mix algorithm.

WFS_CDM_MIXTABLE Denominations are calculated using a house mix table.

usSubType
Contains a service provider defined number that identify the type of algorithm or table. Predefined values are:

Value Meaning

WFS_CDM_MIX_MINIMUM_NUMBER_OF_BILLS The minimum number of bills possible is taken.

WFS_CDM_MIX_EQUAL_EMPTYING_OF_CASH_UNITS The cash units are equally emptied.

lpszName
Points to the name of the table/algorithm used.

Error Codes There are no additional error codes generated by this command.

Comments None.


3.8 WFS_INF_CDM_MIX_TABLE

Description This command is used to retrieve the house mix table specified by the mix number.

Input Param LPUSHORT lpusMixNumber;

lpusMixNumber
Points to the number of the requested house mix table.

Output Param LPWFSCDMMIXTABLE lpMixTable;

typedef struct _wfs_cdm_mix_table
 {
 USHORT    usMixNumber;
 LPSTR    lpszName;
 USHORT    usRows;
 USHORT    usCols;
 LPULONG   lpulMixHeader;
 LPWFSCDMMIXROW * lppMixRows;
 } WFSCDMMIXTABLE, *LPWFSCDMMIXTABLE;

usMixNumber
Internal number of house mix table.

lpszName
Points to the name of the table.

usRows
Number of rows in the house mix table. There is at least one row for each distinct total amount to be denominated.

usCols
Number of columns in the house mix table. There is one column for each distinct bill and coin value included in the mix.

lpulMixHeader
Pointer to an array of length usCols of unsigned longs ; each element defines the value of the bill or coin corresponding to its respective column. (See WFS_INF_CDM_CURRENCY_EXP.)

lppMixRows
Pointer to an array (of length usRows) of pointers to WFSCDMMIXROW structures:

typedef struct _wfs_cdm_mix_row
 {
 ULONG     ulAmount;
 LPUSHORT    lpusMixture;
 } WFSCDMMIXROW, *LPWFSCDMMIXROW;

ulAmount
Amount denominated by this mix row (See WFS_INF_CDM_CURRENCY_EXP).

lpusMixture
Pointer to a mix row, an array of length usCols of unsigned integers; each element defines the quantity of each bill and coin denomination in the mix used in the denomination of ulAmount.

Error Codes The following additional error codes can be generated by this command:

Value Meaning

WFS_ERR_CDM_INVALIDMIXNUMBER The lpusMixNumber parameter does not correspond to a defined mix table.

Comments None.


3.9 WFS_INF_CDM_PRESENT_STATUS

Description This command is used to inform about the status of the last dispense and is used only by ATM’s. It is necessary to decide whether the money was in customer access or not. After a reboot this command returns the status of the last dispense before reboot. This status is valid until the next dispense command.

Input Param None.

Output Param LPWFSCDMPRESENTSTATUS lpPresentStatus;

typedef struct _wfs_cdm_present_status
 {
 LPWFSCDMDENOMINATION lpDenomination;
 WORD      wPresentState;
 LPSTR      lpszExtra;
 } WFSCDMPRESENTSTATUS, *LPWFSCDMPRESENTSTATUS;

lpDenomination
Pointer to a WFSCDMDENOMINATION structure, describing the denominations used for the dispense operation. For a description of the WFSCDMDENOMINATION structure see the definition of the command WFS_CMD_CDM_DENOMINATE.

wPresentState
State of the money. Possible values are:

Value Meaning

WFS_CDM_PRESENTED The money was presented. This value is set as soon as bills are accessible by the customer.

WFS_CDM_NOTPRESENTED The money was not presented.

WFS_CDM_UNKNOWN It is unknown if the money could be accessed by the customer.

lpszExtra
Points to a list of vendor-specific, or any other extended information. The information is returned as a series of “key=value” strings so that it is easily extensible by service providers. Each string will be null-terminated, with the final string terminating with two null characters.

Error Codes There are no additional error codes generated by this command.

Comments None.


4.1 WFS_CMD_CDM_DENOMINATE

Description This command, which is designed to support denomination dialogues, will provide a denomination, i.e., a mix of bills and/or coins, capable of being paid out according to the amount (in terms of the minimum dispense unit) and currency specified, the mix algorithm selected and the desired denomination. In addition to that, it provides a facility for checking any given denomination for its capability of being paid out.

For the denomination of a specified amount the money can be retrieved from three different sources:

  • the cash dispenser

  • the coin dispenser (see WFS_INF_CDM_CAPABILITIES)

  • the teller's cash box (see WFS_INF_CDM_CAPABILITIES)

The configuration specifies which of these three sources are allowed to be used in the denomination. For a ATS all three can be used. If the device used is an ATM, only the cash dispenser and, optionally, the coin dispenser can be available.

For the cash dispenser module there is a parameter (wMaxBills in the WFS_INF_CDM_CAPABILITIES command) controlling the maximum number of bills or documents that can be paid out within a single dispensing command. The coin dispenser has a parameter (wMaxCoins in the WFS_INF_CDM_CAPABILITIES command) specifying the maximum number of coins that can be paid out.

Existing variants for dispensing of bills or documents are:

  • House mix tables (denomination tables), defined in the configuration

  • Denomination algorithms, such as balanced use of the different cash units, use of bills with highest possible values, etc.

There are four distinct combinations of the inputs to this command:

  1. Input parameters are currency and denomination, with mix number WFS_CDM_INDIVIDUAL and amount equal to zero. In this case the service checks only whether the denomination is valid according to the counters and the states of the cash units.

  2. Input parameters are currency, amount and denomination, with mix number WFS_CDM_INDIVIDUAL. The service checks amount and denomination and returns amount, currency and denomination, if the denomination specified is OK.

  3. Input parameters are currency, amount and mix number. The denomination is performed depending on the specified amount and mix number, and the configuration (coin dispenser and/or cash box; see WFS_INF_CDM_CAPABILITIES). The service returns the values for amount, currency and denomination (given the general capability to pay out the amount specified; see above).

If, for example, the amount of £34.00 has been chosen, the CDM service will try to separate the required coins (up to the configured maximum value) using a coin dispenser. If no coin dispenser is available, the separated amount is assigned to sources other than the CDM (such as the teller's cash box). An ATM (having no cash box) raises an error indicating that this amount cannot be denominated.

If, for example, there are no more £10.00 bills in the CDM (cash unit minimum has been reached), it performs payments using bills denominating £20.00 while the remaining £10.00 will have to be paid out from the cash box, if present.

  1. Input parameters are currency, amount and mix number, where the desired denomination is partly defined or a minimum amount for the cashbox is specified. In these cases the partly specified denomination is completed; the cashbox amount may be updated and returned together with the amount and the desired currency.

The following errors can occur:

  • If the denomination specified requires the selection of a locked cash unit, the CDM service returns the error WFS_ERR_CDM_CASHUNITERROR.

  • If the sum total of the denomination is greater than the amount specified (exception: amount is zero), the CDM service returns the error WFS_ERR_CDM_INVALIDDENOMINATION.

  • If the amount specified cannot be dispensed, either because a bill value or coin type is not in the machine, the difference is requested from the teller's cash box. If the device is an ATM, there is no cash box and the error WFS_ERR_CDM_NOTDISPENSABLE is returned.

  • If no coin dispenser is in the unit and a coin amount is specified, a WFS_ERR_CDM_CASHUNITERROR error is returned.

  • If the desired denomination refers to cash units containing different currencies, the CDM-service returns the error WFS_ERR_CDM_NOCURRENCYMIX. A cash unit with a currency type indicating a coupon or non-cash item can be mixed with other currencies.

  • If the currency specified is not configured for the service, a WFS_ERR_CDM_INVALIDCURRENCY error is returned.

Input Param LPWFSCDMDENOMINATE lpDenominate;

typedef struct _wfs_cdm_denominate
 {
 USHORT      usTellerID;
 USHORT      usMixNumber;
 LPWFSCDMDENOMINATION lpDenomination;
 } WFSCDMDENOMINATE, * LPWFSCDMDENOMINATE;

usTellerID
Identification of teller.

usMixNumber
Mix algorithm or house mix table to be used. If the value is WFS_CDM_INDIVIDUAL, the service does not calculate an alternative denomination.

lpDenomination
Pointer to a WFSCDMDENOMINATION structure, describing the contents of the denomination operation.

typedef struct _wfs_cdm_denomination
 {
 CHAR   cCurrencyID[3];
 ULONG   ulAmount;
 USHORT   usCount;
 LPULONG  lpulValues;
 ULONG   ulCashBox;
 } WFSCDMDENOMINATION, * LPWFSCDMDENOMINATION;

cCurrencyID
Identification of currency (ISO format).

ulAmount
The total amount of money to be dispensed. (Amount expressed in minimum dispense units; see WFS_INF_CDM_CURRENCY_EXP.)

usCount
Number of cash units used. Size of the array lpulValues.

lpulValues
Pointer to a list of ULONGs, specifying the number of coins/bills to take from the cash unit. The position in the list defines the logical number of the logical cash unit to be used, the first value in the array is related to the cash unit with the logical number 1. When more than one physical cash unit exists for a logical cash unit, the device selects the actual physical cash unit to use.

ulCashBox
Amount of money that could not be denominated and has to be paid from the tellers cash box. (Amount expressed in minimum dispense units; see WFS_INF_CDM_CURRENCY_EXP.)

Output Param LPWFSCDMDENOMINATION lpDenomination;
For a description see the input structure.

Error Codes The following additional error codes can be generated by this command:

Value Meaning

WFS_ERR_CDM_CASHUNITERROR The specified cash unit caused a problem. A WFS_EXECUTE_EVENT with an id of WFS_EXEE_CDM_CASHUNITERROR is posted with the details.

WFS_ERR_CDM_EXCHANGEACTIVE The CDM service is in an exchange state (see WFS_CMD_CDM_START_EXCHANGE).

WFS_ERR_CDM_INVALIDCURRENCY Currency type is not configured.

WFS_ERR_CDM_INVALIDDENOMINATION The sum of the values for cashbox, cash unit and coin were greater than the amount specified. Or, usMixNumber was WFS_CDM_INDIVIDUAL and the calculated denomination is smaller than the given amount.

WFS_ERR_CDM_INVALIDMIXNUMBER Mix algorithm is not known.

WFS_ERR_CDM_INVALIDTELLERID Teller ID not present in service provider’s teller ID list

WFS_ERR_CDM_NOCURRENCYMIX More than one currency was selected when the cash units were specified. The exception to this is when the cash unit selected contains a non-currency value such as a coupon.

WFS_ERR_CDM_NOTDISPENSABLE The amount is not dispensable by the cash dispenser.

WFS_ERR_CDM_TOOMANYBILLS The request would require too many bills to be dispensed.

WFS_ERR_CDM_TOOMANYCOINS The request would require too many coins to be dispensed.

Events The following additional events can be generated by this command:

Value Meaning

WFS_EXEE_CDM_CASHUNITERROR An error occurred while attempting to denominate from the cash unit specified by the event.

Comments None.


4.2 WFS_CMD_CDM_DISPENSE

Description This command controls the dispensing of money. It requires specifications for the amount of the dispense (expressed in minimum dispense units; see WFS_INF_CDM_CURRENCY_EXP), the desired denomination (or, alternatively, a procedure for the denomination) and the currency desired for the payout. If both the amount and the denomination have been specified, their consistency is checked, while a specification of amount, mix type and currency will produce a response that indicates the denomination. If the amount is not specified (amount is zero), but the denomination is, there is only a check for an approved denomination (as in WFS_CMD_CDM_DENOMINATE), then the dispense occurs.

Instead of using the input parameter usPosition (which is set to WFS_CDM_POSNULL in this case), the teller number can be used so that the teller list can be employed to perform the dispensing to the assigned teller position.

The WFS_CMD_CDM_DISPENSE command is essentially the same as the WFS_CMD_CDM_DENOMINATE command, the main difference between them being that, in addition to the denomination, the dispensing is performed, too. A configuration parameter (WFS_INF_CDM_CAPABILITIES cashbox) determines whether even if only part of the total amount is capable of being denominated, its dispensing will be performed by the CDM.

Examples:

  1. If $30.00 is to be dispensed by the CDM but the smallest currency unit available is a $20 bill, it is possible to dispense $20.00 from the CDM, while the remaining $10.00 is requested from the teller's cash box.

  2. The CDM service returns a message saying that the amount of a payout cannot be denominated (WFS_ERR_CDM_NOTDISPENSABLE).
Input Param LPWFSCDMDISPENSE lpDispense;
typedef struct _wfs_cdm_dispense
 {
 USHORT      usTellerID;
 USHORT      usMixNumber;
 USHORT      usPosition;
 BOOL      bPresent;
 LPWFSCDMDENOMINATION lpDenomination;
 } WFSCDMDISPENSE, *LPWFSCDMDISPENSE;

usTellerID
Identification of teller.

usMixNumber
Mix algorithm or house mix table to be used. If the value is WFS_CDM_INDIVIDUAL, the service does not calculate an alternative denomination.

usPosition
Determines to which side the amount is dispensed; values are:

Value Meaning

WFS_CDM_POSNULL This implies that the default configuration information is used. This can be either position dependent or teller dependent for determining which side the currency is presented.

WFS_CDM_POSLEFT Present money to left side of device.

WFS_CDM_POSRIGHT Present money to right side of device.

WFS_CDM_POSCENTER Present money to center output position.

bPresent
Controls whether the bills should be presented to the user (= TRUE) or only transported to the stacker (= FALSE). See WFS_CMD_CDM_PRESENT and WFS_CMD_CDM_REJECT.

lpDenomination
Pointer to a WFSCDMDENOMINATION structure, describing the denominations used for the dispense operation. For a description of the WFSCDMDENOMINATION structure see the definition of the command WFS_CMD_CDM_DENOMINATE.

Output Param LPWFSCDMDENOMINATION lpDenomination;
For a description of the WFSCDMDENOMINATION structure see the definition of the command WFS_CMD_CDM_DENOMINATE. Note that the values in this structure report the actual total amount and number of each denomination dispensed.

Error Codes The following additional error codes can be generated by this command:

Value Meaning

WFS_ERR_CDM_CASHUNITERROR A cash unit specified caused a problem, e.g., ran out of bills/coins (short dispense). A WFS_EXEE_CDM_CASHUNITERROR EXECUTE_EVENT is posted with the details.

WFS_ERR_CDM_EXCHANGEACTIVE The CDM service is in an exchange state (see WFS_CMD_CDM_START_EXCHANGE).

WFS_ERR_CDM_INVALIDCURRENCY Currency type is not configured

WFS_ERR_CDM_INVALIDDENOMINATION The sum of the values for cashbox, cash unit and coin were greater than the amount specified.

WFS_ERR_CDM_INVALIDMIXNUMBER Mix algorithm is not known

WFS_ERR_CDM_INVALIDPOSITION The specified output position is invalid.

WFS_ERR_CDM_INVALIDTELLERID Teller ID not present in service provider’s teller ID list

WFS_ERR_CDM_NOCURRENCYMIX Cash units containing two or more different currencies were selected. This error is not generated if one or more non-currency value cash units (e.g., containing coupons) are selected, together with currency cash units of a single currency type.

WFS_ERR_CDM_NOTDISPENSABLE The requested amount is not dispensable by the cash dispenser.

WFS_ERR_CDM_POSITIONLOCKED The output position is locked.

WFS_ERR_CDM_SAFEDOOROPEN The safe door is open.

WFS_ERR_CDM_TOOMANYBILLS The request would require too many bills to be dispensed.

WFS_ERR_CDM_TOOMANYCOINS The request would require too many coins to be dispensed.

Events The following additional events can be generated:

Value Meaning

WFS_EXEE_CDM_DELAYEDDISPENSE Time before dispensing starts, because of a security procedure (German national regulation).

WFS_EXEE_CDM_STARTDISPENSE Point of time where the dispense order starts. Necessary to know for a CDM application because of queueing orders from different clients.

WFS_EXEE_CDM_PARTIALDISPENSE The dispense order is divided into several suborders.

WFS_EXEE_CDM_SUBDISPENSEOK One of the dispense suborders was finished successfully.

WFS_EXEE_CDM_CASHUNITERROR An error occurred while attempting to dispense cash.

Comments All error codes and events listed under the WFS_CMD_CDM_PRESENT command description, with the exception of WFS_ERR_CDM_NOBILLS, can also occur on this command.


4.3 WFS_CMD_CDM_PRESENT

Description This command is only used for ATMs; it causes presentation of the currency. It can be used only following the WFS_CMD_CDM_DISPENSE command (with bPresent = FALSE).

The command completes when the bills are positioned at the exit slot of the device. A service event is generated to report the user has removed the bills. If no event is received within a reasonable time period, the application should send a WFS_CMD_CDM_RETRACT to clear the bills from the exit. On devices which do not have the ability to detect when bills are taken (see WFS_INF_CDM_CAPABILITIES) the service event is generated as soon as the bills are available to the user.

Input Param None.

Output Param None.

Error Codes The following additional error codes can be generated by this command:

Value Meaning

WFS_ERR_CDM_EXCHANGEACTIVE The CDM service is in an exchange state (see WFS_CMD_CDM_START_EXCHANGE).

WFS_ERR_CDM_NOBILLS There were no bills on the stacker to present.

WFS_ERR_CDM_SHUTTERNOTOPEN The shutter is not open or did not open when it should have. No bills presented.

WFS_ERR_CDM_SHUTTEROPEN The shutter is open when it should be closed. No bills presented.

WFS_ERR_CDM_PRERRORNOBILLS There was an error during the present operation - no bills are presented.

WFS_ERR_CDM_PRERRORBILLS There was an error during the present operation - at least some of the bills are presented.

WFS_ERR_CDM_PRERRORUNKNOWN There was an error during the present operation - the position of the bills is unknown. Intervention may be required to reconcile the cash amount totals.

Events The following additional events can be generated:

Value Meaning

WFS_SRVE_CDM_BILLSTAKEN The bills presented have been removed by the user.

Comments None.


4.4 WFS_CMD_CDM_REJECT

Description This command is used only in ATMs. It causes money to be transported from the stacker into the reject bin. It can be used only following the WFS_CMD_CDM_DISPENSE command (with bPresent = FALSE).

Input Param None.

Output Param None.

Error Codes The following additional error codes can be generated by this command:

Value Meaning

WFS_ERR_CDM_EXCHANGEACTIVE The CDM service is in an exchange state (see WFS_CMD_CDM_START_EXCHANGE).

WFS_ERR_CDM_NOBILLS There were no bills on the stacker to reject.

Events There are no additional events generated by this command.

Comments None.


4.5 WFS_CMD_CDM_RETRACT

Description This command is used only for ATMs. It allows the application to force cash that has been presented to be retracted. Not all cash dispensers support this capability.

Input Param LPUSHORT lpusRetractArea;
Pointer to value indicating the area in the reject bin where retracted cash is to be stored. Not all systems require this parameter, and it may differ in content from system to system (NULL if not relevant).

Output Param None.

Error Codes The following additional error codes can be generated by this command:

Value Meaning

WFS_ERR_CDM_BILLSTAKEN Bills were present at the exit at the start of the operation, but were removed before the operation was complete, so some or all of the bills were not retracted.

WFS_ERR_CDM_EXCHANGEACTIVE The CDM service is in an exchange state (see WFS_CMD_CDM_START_EXCHANGE).

WFS_ERR_CDM_INVALIDRETRACT Retract function is invalid for this system.

WFS_ERR_CDM_SHUTTERNOTCLOSED The shutter failed to close.

WFS_ERR_CDM_NOBILLS There were no presented bills to retract.

Events There are no additional events generated by this command.

Comments None.


4.6 WFS_CMD_CDM_CASH_IN

Description This command is not used for ATMs; there are two possibilities for use of this API.

The amount to be deposited is expressed in minimum dispense units; see WFS_INF_CDM_CURRENCY_EXP. It affects the teller counters only. The input parameters cCurrencyID and ulAmount are required as input.

If the hardware is capable of identifying the currency and the denomination of the amount deposited, the output parameters cCurrencyID, ulAmount, lpulValues, and ulCashBox will be returned.

If the hardware is equipped with refill containers the amount cashed in is simply placed on top of the cash already in the refill containers. The input parameters cCurrencyID, ulAmount and lpulValues are required.

Input Param LPWFSCDMCASHIN lpCashIn;

typedef struct _wfs_cdm_cashin
 {
 USHORT      usTellerID;
 LPWFSCDMDENOMINATION lpDenomination;
 } WFSCDMCASHIN, * LPWFSCDMCASHIN;

usTellerID
Identification of Teller.

lpDenomination
Pointer to a WFSCDMDENOMINATION structure, describing the denomination of the cash in operation. For a description of the WFSCDMDENOMINATION structure see the definition of the WFS_CMD_CDM_DENOMINATE function.

Output Param LPWFSCDMDENOMINATION lpDenomination;
For a description of the WFSCDMDENOMINATION structure see the definition of the command WFS_CMD_CDM_DENOMINATE.

Error Codes The following additional error codes can be generated by this command:

Value Meaning

WFS_ERR_CDM_EXCHANGEACTIVE The CDM service is in an exchange state (see WFS_CMD_CDM_START_EXCHANGE).

WFS_ERR_CDM_INVALIDCURRENCY Specified currency not currently available

WFS_ERR_CDM_INVALIDTELLERID Teller ID not present in service provider’s teller ID list

WFS_ERR_CDM_NOCASHINSTARTED The WFS_CMD_CDM_CASH_IN_START was not issued before

Events The following additional events can be generated:

Value Meaning

WFS_EXEE_CDM_INPUTREFUSE A part of the amount of the cash in order was refused.

Comments None.


4.7 WFS_CMD_CDM_OPEN_SHUTTER

Description This command is used only for ATMs. It opens the shutter.

Input Param None.

Output Param None.

Error Codes The following additional error codes can be generated by this command:

Value Meaning

WFS_ERR_CDM_EXCHANGEACTIVE The CDM service is in an exchange state (see WFS_CMD_CDM_START_EXCHANGE).

WFS_ERR_CDM_SHUTTERNOTOPEN Shutter failed to open

WFS_ERR_CDM_SHUTTEROPEN Shutter was already open

Events There are no additional events generated by this command.

Comments None.


4.8 WFS_CMD_CDM_CLOSE_SHUTTER

Description This command is used only for ATMs. It closes the shutter.

Input Param None.

Output Param None.

Error Codes The following additional error codes can be generated by this command:

Value Meaning

WFS_ERR_CDM_EXCHANGEACTIVE The CDM service is in an exchange state (see WFS_CMD_CDM_START_EXCHANGE).

WFS_ERR_CDM_SHUTTERCLOSED Shutter was already closed

WFS_ERR_CDM_SHUTTERNOTCLOSED Shutter failed to close

Events There are no additional events generated by this command.

Comments None.


4.9 WFS_CMD_CDM_SET_TELLER_INFO

Description This command is used for initializing the tallies assigned to a teller. All values are absolute. For each currency a different set of tallies is used.

Input Param LPWFSCDMTELLERTOTALS lpTellerTotals;
For a description of the struct WFSCDMTELLERTOTALS see the definition of the WFS_INF_CDM_TELLER_INFO command.

Output Param None.

Error Codes The following additional error codes can be generated by this command:

Value Meaning

WFS_ERR_CDM_EXCHANGEACTIVE The CDM service is in an exchange state (see WFS_CMD_CDM_START_EXCHANGE).

WFS_ERR_CDM_INVALIDCURRENCY Specified currency not currently available

WFS_ERR_CDM_INVALIDTELLERID Teller ID not present in service provider’s teller ID list

Events The following additional events can be generated by this command:

Value Meaning

WFS_SRVE_CDM_TELLERINFOCHANGED Teller information has been changed.

Comments None.


4.10 WFS_CMD_CDM_SET_CASH_UNIT_INFO

Description This command is used to adjust both cash unit counters and cash unit IDs. In addition to that, application locks for cash units can be either installed or removed. It is also useful for setting or altering threshold values of cassettes.

This command can be used when a problem has occurred and the start and end cash unit exchange is not acceptable.

The following parameters defined in the WFSCDMCASHUNIT structure cannot be set by the application and, therefore, are ignored by this command:
bDevLock
usStatus
lpPhysicalPositionName
lppPhysical[]->usPStatus
lppPhysical[]->lpPhysicalPositionName

Input Param LPWFSCDMCUINFO lpCUInfo;
For a description of the WFSCDMCUINFO structure, see the WFS_INF_CDM_CASH_UNIT_INFO command.

Output Param None.

Error Codes The following additional error codes can be generated by this command:

Value Meaning

WFS_ERR_CDM_CASHUNITERROR A cash unit specified caused a problem. A WFS_EXEE_CDM_CASHUNITERROR execute event is posted with the details.

WFS_ERR_CDM_INVALIDCASHUNIT Invalid cash unit ID.

WFS_ERR_CDM_INVALIDTELLERID Teller ID not present in service provider’s teller ID list

WFS_ERR_CDM_EXCHANGEACTIVE The CDM service is in an exchange state (see WFS_CMD_CDM_START_EXCHANGE).

Events The following additional events can be generated:

Value Meaning

WFS_SRVE_CDM_CASHUNITINFOCHANGED A cash unit was changed.

Comments This command generates a service event (WFS_SRVE_CDM_CASHUNITINFOCHANGED) that allows applications to be aware that they should update their cash unit status for the service


4.11 WFS_CMD_CDM_START_EXCHANGE

Description This command is used to start the exchange of cash units as well as their emptying, replenishment, removal or replacement. The command returns the current values in the device and the device itself initiates cash unit removal (for example by means of lowering the cash units). A WFSLock should be performed before this command is initiated, to ensure exclusive control by the replenishment application.

After WFS_CMD_CDM_START_EXCHANGE has been successfully initiated, the CDM enters the exchange state, and accepts only the following functions:

  • WFS[Async]Execute, with WFS_CMD_CDM_END_EXCHANGE command only

  • WFS[Async]GetInfo commands

  • WFSClose

Any other commands issued when the CDM service is in the exchange state are rejected with an error condition of WFS_ERR_CDM_EXCHANGEACTIVE. If an error occurs at the CDM during the execution of this command, the cash unit values are not returned.

Input Param LPWFSCDMSTARTEX lpStartEx;

typedef struct _wfs_cdm_start_ex
 {
 USHORT   usTellerID;
 USHORT   usCount;
 LPUSHORT  lpusCUNumList;
 } WFSCDMSTARTEX, * LPWFSCDMSTARTEX;

usTellerID
Identification of teller.

usCount
Number of cash units to be exchanged. Size of the array lpusCUNumList.

lpusCUNumList
Pointer to a list of the logical numbers (unsigned shorts) of the cash units to be exchanged.

Output Param LPWFSCDMCUINFO lpCUInfo;
For a description of the WFSCDMCUINFO structure, see the definition of the WFS_INF_CDM_CASH_UNIT_INFO command.

Error Codes The following additional error codes can be generated by this command:

Value Meaning

WFS_ERR_CDM_EXCHANGEACTIVE The CDM service is already in an exchange state.

WFS_ERR_CDM_INVALIDTELLERID Teller ID not present in service provider’s teller ID list

Events There are no additional events generated by this command.

Comments None.


4.12 WFS_CMD_CDM_END_EXCHANGE

Description This command is initiated after a cash unit has been exchanged, refilled, etc. It supplies the latest cash unit information and cash unit IDs. Cash units are set as ready (e.g., lifted upwards; there may also be a dispenser test), any cash unit inoperative conditions are cleared, and reject counters are reset; the current status of the safe door is ignored. After this command the cash dispenser service will accept a WFS[Async]Unlock request.

The service provider may be able to obtain cash unit information directly from the dispenser device, such as cash unit ID and replenishment state. In this case, the corresponding input parameters to this command may be ignored.

Errors can be generated by this command. When a cash unit error is returned, the application must issue a WFS_INF_CDM_CASH_UNIT_INFO command to get the cash unit status.

Input Param LPWFSCDMCUINFO lpCUInfo;
For a description of the WFSCDMCUINFO structure, see the definition of the WFS_INF_CDM_CASH_UNIT_INFO command. If this pointer is NULL, the contents of the cash units are not changed.

Output Param None.

Error Codes The following additional error codes can be generated by this command:

Value Meaning

WFS_ERR_CDM_NOEXCHANGEACTIVE There is no exchange active

WFS_ERR_CDM_INVALIDCASHUNIT Invalid cash unit ID

WFS_ERR_CDM_INVALIDTELLERID Teller ID not present in service provider’s teller ID list

Events The following additional events can be generated by this command:

Value Meaning

WFS_SRVE_CDM_CASHUNITINFOCHANGED A cash unit was changed.

Comments This command generates a service event (WFS_SRVE_CDM_CASHUNITINFOCHANGED) that allows applications to be aware that they should update their cash unit status for the service, using the WFS_INF_CDM_CASH_UNIT_INFO command.


4.13 WFS_CMD_CDM_OPEN_SAFE_DOOR

Description This command controls the time lock for the safe door. It sends the currently configured value for the safe door timer to the device. This configuration parameter is vendor dependent.

Input Param None.

Output Param None.

Error Codes The following additional error codes can be generated by this command:

Value Meaning

WFS_ERR_CDM_EXCHANGEACTIVE The CDM service is in an exchange state (see WFS_CMD_CDM_START_EXCHANGE).

Events There are no additional events generated by this command.

Comments None.


4.14 WFS_CMD_CDM_CHECK_VANDALISM

Description This command is used only for ATMs. If implemented, it checks whether there has been any attempt to manipulate the ATM. If vandalism was detected, it is reported through this function.

Input Param None.

Output Param LPUSHORT lpusVandalism;

Flag specifying whether there has been an attempt to manipulate the device since the last time this command was issued. Values are:

Value Meaning

WFS_CDM_NODEVMANIPULATION No attempt has been made to manipulate the device.

WFS_CDM_DEVMANIPULATION An attempt to manipulate the device has been detected.

Error Codes The following additional error codes can be generated by this command:

Value Meaning

WFS_ERR_CDM_EXCHANGEACTIVE The CDM service is in an exchange state (see WFS_CMD_CDM_START_EXCHANGE).

Events There are no additional events generated by this command.

Comments None.


4.15 WFS_CMD_CDM_CALIBRATE_CASH_UNIT

Description This command is used to initialize the reference value of a cash unit. It will action a vendor dependent sequence of hardware events which will calibrate the physical cash unit. This is necessary if a new type of bank note is put into the cash unit. By this command the cash unit gets the new measures of the bank notes.

If more than one physical cash unit is related to the logical cash unit, it is up to the Service Provider to select the appropriate actions. Whether, all the physical cash units have to be calibrated or if it is sufficient to do the calibration for one physical unit and load the data into the others.

Input Param LPWFSCDMCALIBRATE lpCalibrateIn;

typedef struct _wfs_cdm_calibrate
 {
 USHORT   usNumber;
 USHORT   usNumOfBills;
 } WFSCDMCALIBRATE, * LPWFSCDMCALIBRATE;

usNumber
Logical number of cash unit.

usNumOfBills
Number of bills to be dispensed during the process of measuring.

Output Param LPWFSCDMCALIBRATE lpCalibrateOut;

For a description of the WFSCDMCALIBRATE structure, see the definition of the Input Param.

usNumber
Logical number of cash unit.

usNumOfBills
Number of bills that were dispensed during the process of measuring. It can differ from the value in the input structure, if the cash dispenser always dispenses a default number of bills.

Error Codes The following additional error code can be generated by this command:

Value Meaning

WFS_ERR_CDM_EXCHANGEACTIVE The CDM service is in an exchange state (see WFS_CMD_CDM_START_EXCHANGE).

WFS_ERR_CDM_CASHUNITERROR The specified cash unit caused an error.

Events The following additional events can be generated by this command:

Value Meaning

WFS_SRVE_CDM_CASHUNITINFOCHANGED A cash unit was changed.

Comments None.


4.16 WFS_CMD_CDM_SET_TELLER_POSITIONS

Description This command is used to set the output position assigned to each teller.

Input Param LPWFSCDMTELLERPOS *lppTellerPos;
For a description of the struct WFSCDMTELLERPOS see the definition of the command WFS_INF_CDM_TELLER_POSITIONS.

Output Param None.

Error Codes There are no additional error codes generated by this command.

Events There are no additional events generated by this command.

Comments None.


4.17 WFS_CMD_CDM_CASH_IN_START

Description Each cash in procedure has to be handled as a transaction that can be rolled back if a difference occurs between the amount counted by the ATS and the amount the teller inserted. This command is used to start the cash in transaction.

Input Param LPUSHORT lpusTellerID;
Identification of teller.

Output Param None.

Error Codes The following additional error codes can be generated by this command:

Value Meaning

WFS_ERR_CDM_CASHINACTIVE The CDM service has already got a WFS_CMD_CDM_CASH_IN_START command.

Events There are no additional events generated by this command.

Comments None.


4.18 WFS_CMD_CDM_CASH_IN_END

Description Each cash in procedure has to be handled as a transaction that can be rolled back if a difference occurs between the amount counted by the ATS and the amount the teller inserted. This command is used to end the cash in transaction.

Input Param LPUSHORT lpusTellerID;
Identification of teller. It has to be the same as issued in the WFS_CMD_CDM_CASH_IN_START command.

Output Param None.

Error Codes The following additional error codes can be generated by this command:

Value Meaning

WFS_ERR_CDM_NOCASHINSTARTED The WFS_CMD_CDM_CASH_IN_START was not issued before

Events There are no additional events generated by this command.

Comments None.


4.19 WFS_CMD_CDM_CASH_IN_ROLLBACK

Description Each cash in procedure has to be handled as a transaction that can be rolled back if a difference occurs between the amount counted by the ATS and the amount the teller inserted. This command is used to roll back the cash in transaction. All the notes cashed in since the last WFS_CMD_CDM_CASH_IN_START command are returned to the teller. If an ATS does not have this capability, it returns 0 number of bills in the output structure.

Input Param LPUSHORT lpusTellerID;
Identification of teller. It has to be the same as issued in the WFS_CMD_CDM_CASH_IN_START command.

Output Param LPWFSCDMDENOMINATION lpDenomination;
For a description of the struct WFSCDMDENOMINATION see the definition of the command WFS_CMD_CDM_DENOMINATE.

Error Codes The following additional error codes can be generated by this command:

Value Meaning

WFS_ERR_CDM_NOCASHINSTARTED The WFS_CMD_CDM_CASH_IN_START was not issued before

Events There are no additional events generated by this command.

Comments None.


4.20 WFS_CMD_CDM_SET_MIX_TABLE

Description This command is used to set up the mix table specified by the mix number.

Input Param LPWFSCDMMIXTABLE lpMixTable;
For a description of the struct WFSCDMMIXTABLE see the definition of the command WFS_INF_CDM_MIX_TABLE.

Output Param None.

Error Codes The following additional error codes can be generated by this command:

Value Meaning

WFS_ERR_CDM_INVALIDMIXNUMBER The usMixNumber parameter refers to a predefined and reserved mix algorithm.

WFS_ERR_CDM_INVALIDMIXTABLE The contents of at least one of the defined rows of the mix table is incorrect.

Events There are no additional events generated by this command.

Comments None.


5.1 WFS_SRVE_CDM_SAFEDOOROPEN

Description This service event specifies that the safe door has been opened.

Event Param None.

Comments None.


5.2 WFS_SRVE_CDM_SAFEDOORCLOSED

Description This service event specifies that the safe door has been closed.

Event Param None.

Comments None.


5.3 WFS_USRE_CDM_CASHUNITTHRESHOLD

Description This user event specifies that a threshold condition has occured in one of the cash units.

Event Param LPWFSCDMCASHUNIT lpCashUnit;

lpCashUnit
Pointer to WFSCDMCASHUNIT structure, describing the cash unit on which the threshold condition occurred. See lpCashUnit->usStatus for the type of condition. For a description of the WFSCDMCASHUNIT structure, see the definition of the WFS_INF_CDM_CASH_UNIT_INFO command.

Comments None.


5.4 WFS_SRVE_CDM_CASHUNITINFOCHANGED

Description This service event specifies that a cash unit was exchanged, a new cash unit was added, or the contents of a cash unit were modified using the WFS_CMD_CDM_SET_CASH_UNIT_INFO command. This event is also posted after a WFS_CMD_CDM_END_EXCHANGE or a WFS_CMD_CDM_CALIBRATE_CASH_UNIT command successfully completes.

Event Param LPWFSCDMCASHUNIT lpCashUnit;

lpCashUnit
Pointer to the changed cash unit structure. For a description of the WFSCDMCASHUNIT structure see the definition of the WFS_INF_CDM_CASH_UNIT_INFO command.

Comments None.


5.5 WFS_SRVE_CDM_TELLERINFOCHANGED

Description This service event specifies that the tallies assigned to the specified teller have been changed. This event is only returned as a result of a WFS_CMD_CDM_SET_TELLER_INFO command.

Event Param LPUSHORT lpusTellerID;

lpusTellerID
Pointer to an unsigned short holding the ID of the teller whose tallies have been changed.

Comments None.


5.6 WFS_EXEE_CDM_DELAYEDDISPENSE

Description This execute event specifies that the start of the physical dispensing of the money has been delayed.

Event Param LPULONG lpulDelay;

lpulDelay
Pointer to the time in milliseconds the dispense job will be delayed.

Comments None.


5.7 WFS_EXEE_CDM_STARTDISPENSE

Description This execute event specifies the start of the physical dispensing of the money of the formerly delayed job.

Event Param LPREQUESTID lpReqID;

lpReqID
Pointer to the RequestID of the dispense command that has started.

Comments None.


5.8 WFS_EXEE_CDM_CASHUNITERROR

Description This execute event specifies that in a denominate or dispense command a cash unit was addressed which caused a problem.

Event Param LPWFSCDMCUERROR lpCashUnitError;

typedef struct _wfs_cdm_cu_error
 {
 WORD     wFailure;
 LPWFSCDMCASHUNIT  lpCashUnit;
 } WFSCDMCUERROR, * LPWFSCDMCUERROR;

wFailure
Specifies the kind of failure that occurred in the cash unit. Values are:

Value Meaning

WFS_CDM_CASHUNITEMPTY Specified cash unit is empty.

WFS_CDM_CASHUNITERROR Specified cash unit has malfunctioned.

WFS_CDM_CASHUNITFULL Specified cash unit is full.

WFS_CDM_CASHUNITLOCKED Specified cash unit is locked.

WFS_CDM_CASHUNITNOTCONF Specified cash unit is not configured.

WFS_CDM_CASHUNITINVALID Specified cash unit ID is invalid.

lpCashUnit
Pointer to the cash unit structure that caused the problem. For a description of the WFSCDMCASHUNIT structure see the definition of the WFS_INF_CDM_CASH_UNIT_INFO command.

Comments None.


5.9 WFS_SRVE_CDM_BILLSTAKEN

Description This service event specifies that the bills presented to the user have been taken.

Event Param None.

Comments None.


5.10 WFS_EXEE_CDM_PARTIALDISPENSE

Description This execute event specifies that the dispense order is divided into several suborders because the capacity of the device is exceeded.

Event Param LPUSHORT lpusDispNum;

lpusDispNum
Specifies the number of suborders into which the dispense order is divided.

Comments None.


5.11 WFS_EXEE_CDM_SUBDISPENSEOK

Description This execute event specifies that one of the suborders into which the dispense order was divided was finished successfully.

Event Param LPWFSCDMDENOMINATION lpDenomination;

lpDenomination
For a description of the struct WFSCDMDENOMINATION see the definition of the command WFS_CMD_CDM_DENOMINATE. Note that in this case the values in this structure report the amount and number of each denomination dispensed in the suborder this event belongs to.

Comments None.


5.12 WFS_EXEE_CDM_INPUTREFUSE

Description This execute event specifies that the device has refused a part of the amount of the cash in order.

Event Param LPUSHORT lpusReason;

lpusReason
Specifies the reason for refusing a part of the amount. Possible values are:.

Value Meaning

WFS_CDM_CASHUNITFULL Cash unit is full.

WFS_CDM_INVALIDBILL One or more of the bills are invalid.

Comments None.


6. C - Header file

/******************************************************************************
*                                                                             *
* xfscdm.h      WOSA/XFS - Cash Dispenser (CDM) definitions                   *
*                                                                             *
*               Version 2.00 (11/11/96)                                       *
*                                                                             *
******************************************************************************/

#ifndef __INC_XFSCDM__H
#define __INC_XFSCDM__H

#ifdef __cplusplus
extern "C" {
#endif

#include <xfsapi.h>

/* be aware of alignment */
#pragma pack (push, 1)

/* values of WFSCDMCAPS.wClass */

#define     WFS_SERVICE_CLASS_CDM               (3)
#define     WFS_SERVICE_CLASS_VERSION_CDM       0x0002
#define     WFS_SERVICE_CLASS_NAME_CDM          "CDM"

#define     CDM_SERVICE_OFFSET                  (WFS_SERVICE_CLASS_CDM * 100)

/* CDM Info Commands */

#define     WFS_INF_CDM_STATUS                  (CDM_SERVICE_OFFSET + 1)
#define     WFS_INF_CDM_CAPABILITIES            (CDM_SERVICE_OFFSET + 2)
#define     WFS_INF_CDM_CASH_UNIT_INFO          (CDM_SERVICE_OFFSET + 3)
#define     WFS_INF_CDM_TELLER_INFO             (CDM_SERVICE_OFFSET + 4)
#define     WFS_INF_CDM_TELLER_POSITIONS        (CDM_SERVICE_OFFSET + 5)
#define     WFS_INF_CDM_CURRENCY_EXP            (CDM_SERVICE_OFFSET + 6)
#define     WFS_INF_CDM_MIX_TYPES               (CDM_SERVICE_OFFSET + 7)
#define     WFS_INF_CDM_MIX_TABLE               (CDM_SERVICE_OFFSET + 8)
#define     WFS_INF_CDM_PRESENT_STATUS          (CDM_SERVICE_OFFSET + 9)

/* CDM Execute Commands */

#define     WFS_CMD_CDM_DENOMINATE              (CDM_SERVICE_OFFSET + 1)
#define     WFS_CMD_CDM_DISPENSE                (CDM_SERVICE_OFFSET + 2)
#define     WFS_CMD_CDM_PRESENT                 (CDM_SERVICE_OFFSET + 3)
#define     WFS_CMD_CDM_REJECT                  (CDM_SERVICE_OFFSET + 4)
#define     WFS_CMD_CDM_RETRACT                 (CDM_SERVICE_OFFSET + 5)
#define     WFS_CMD_CDM_CASH_IN                 (CDM_SERVICE_OFFSET + 6)
#define     WFS_CMD_CDM_OPEN_SHUTTER            (CDM_SERVICE_OFFSET + 7)
#define     WFS_CMD_CDM_CLOSE_SHUTTER           (CDM_SERVICE_OFFSET + 8)
#define     WFS_CMD_CDM_SET_TELLER_INFO         (CDM_SERVICE_OFFSET + 9)
#define     WFS_CMD_CDM_SET_CASH_UNIT_INFO      (CDM_SERVICE_OFFSET + 10)
#define     WFS_CMD_CDM_START_EXCHANGE          (CDM_SERVICE_OFFSET + 11)
#define     WFS_CMD_CDM_END_EXCHANGE            (CDM_SERVICE_OFFSET + 12)
#define     WFS_CMD_CDM_OPEN_SAFE_DOOR          (CDM_SERVICE_OFFSET + 13)
#define     WFS_CMD_CDM_CHECK_VANDALISM         (CDM_SERVICE_OFFSET + 14)
#define     WFS_CMD_CDM_CALIBRATE_CASH_UNIT     (CDM_SERVICE_OFFSET + 15)
#define     WFS_CMD_CDM_SET_TELLER_POSITIONS    (CDM_SERVICE_OFFSET + 16)
#define     WFS_CMD_CDM_CASH_IN_START           (CDM_SERVICE_OFFSET + 17)
#define     WFS_CMD_CDM_CASH_IN_END             (CDM_SERVICE_OFFSET + 18)
#define     WFS_CMD_CDM_CASH_IN_ROLLBACK        (CDM_SERVICE_OFFSET + 19)
#define     WFS_CMD_CDM_SET_MIXTABLE            (CDM_SERVICE_OFFSET + 20)

/* CDM Messages */

#define     WFS_SRVE_CDM_SAFEDOOROPEN           (CDM_SERVICE_OFFSET + 1)
#define     WFS_SRVE_CDM_SAFEDOORCLOSED         (CDM_SERVICE_OFFSET + 2)
#define     WFS_USRE_CDM_CASHUNITTHRESHOLD      (CDM_SERVICE_OFFSET + 3)
#define     WFS_SRVE_CDM_CASHUNITINFOCHANGED    (CDM_SERVICE_OFFSET + 4)
#define     WFS_SRVE_CDM_TELLERINFOCHANGED      (CDM_SERVICE_OFFSET + 5)
#define     WFS_EXEE_CDM_DELAYEDDISPENSE        (CDM_SERVICE_OFFSET + 6)
#define     WFS_EXEE_CDM_STARTDISPENSE          (CDM_SERVICE_OFFSET + 7)
#define     WFS_EXEE_CDM_CASHUNITERROR          (CDM_SERVICE_OFFSET + 8)
#define     WFS_SRVE_CDM_BILLSTAKEN             (CDM_SERVICE_OFFSET + 9)
#define     WFS_EXEE_CDM_PARTIALDISPENSE        (CDM_SERVICE_OFFSET + 10)
#define     WFS_EXEE_CDM_SUBDISPENSEOK          (CDM_SERVICE_OFFSET + 11)
#define     WFS_EXEE_CDM_INPUTREFUSE            (CDM_SERVICE_OFFSET + 12)

/* values of WFSCDMSTATUS.fwDevice */
#define     WFS_CDM_DEVONLINE                   WFS_STAT_DEVONLINE
#define     WFS_CDM_DEVOFFLINE                  WFS_STAT_DEVOFFLINE
#define     WFS_CDM_DEVPOWEROFF                 WFS_STAT_DEVPOWEROFF
#define     WFS_CDM_DEVBUSY                     WFS_STAT_DEVBUSY
#define     WFS_CDM_DEVNODEVICE                 WFS_STAT_DEVNODEVICE
#define     WFS_CDM_DEVHWERROR                  WFS_STAT_DEVHWERROR
#define     WFS_CDM_DEVUSERERROR                WFS_STAT_DEVUSERERROR

/* values of WFSCDMSTATUS.fwSafeDoor */

#define     WFS_CDM_DOORNOTSUPPORTED            (1)
#define     WFS_CDM_DOOROPEN                    (2)
#define     WFS_CDM_DOORCLOSED                  (3)
#define     WFS_CDM_DOORLOCKED                  (4)
#define     WFS_CDM_DOORUNKNOWN                 (5)

/* values of WFSCDMSTATUS.fwDispenser */

#define     WFS_CDM_DISPOK                      (0)
#define     WFS_CDM_DISPCUSTATE                 (1)
#define     WFS_CDM_DISPCUSTOP                  (2)
#define     WFS_CDM_DISPCUUNKNOWN               (3)

/* values of WFSCDMSTATUS.fwShutter */

#define     WFS_CDM_SHTCLOSED                   (0)
#define     WFS_CDM_SHTOPEN                     (1)
#define     WFS_CDM_SHTJAMMED                   (2)
#define     WFS_CDM_SHTUNKNOWN                  (3)
#define     WFS_CDM_SHTNOTSUPPORTED             (4)

/* values of WFSCDMSTATUS.fwOutputPosition */

#define     WFS_CDM_CTEMPTY                     (0)
#define     WFS_CDM_CTNOTEMPTY                  (1)
#define     WFS_CDM_CTUNKNOWN                   (2)
#define     WFS_CDM_CTNOTSUPPORTED              (3)

/* values of WFSCDMSTATUS.fwTransport */

#define     WFS_CDM_TPOK                        (0)
#define     WFS_CDM_TPINOP                      (1)
#define     WFS_CDM_TPUNKNOWN                   (2)
#define     WFS_CDM_TPNOTSUPPORTED              (3)

/* values of WFSCDMSTATUS.fwIntermediateStacker */

#define     WFS_CDM_ISEMPTY                     (0)
#define     WFS_CDM_ISNOTEMPTY                  (1)
#define     WFS_CDM_ISUNKNOWN                   (2)
#define     WFS_CDM_ISNOTSUPPORTED              (3)

/* values of WFSCDMCAPS.fwType */

#define     WFS_CDM_TYPEATSAFE                  (1)
#define     WFS_CDM_TYPEATMACHINE               (2)

/* values of WFSCDMCASHUNIT.usType */

#define     WFS_CDM_TYPENA                      (1)
#define     WFS_CDM_TYPEREJECTCASSETTE          (2)
#define     WFS_CDM_TYPEBILLCASSETTE            (3)
#define     WFS_CDM_TYPECOINCYLINDER            (4)
#define     WFS_CDM_TYPECOINDISPENSER           (5)
#define     WFS_CDM_TYPERETRACTCASSETTE         (6)
#define     WFS_CDM_TYPECOUPON                  (7)
#define     WFS_CDM_TYPEDOCUMENT                (8)

/* values of WFSCDMCASHUNIT.usStatus */

#define     WFS_CDM_STATCUOK                    (0)
#define     WFS_CDM_STATCUFULL                  (1)
#define     WFS_CDM_STATCUHIGH                  (2)
#define     WFS_CDM_STATCULOW                   (3)
#define     WFS_CDM_STATCUEMPTY                 (4)
#define     WFS_CDM_STATCUMISSING               (5)
#define     WFS_CDM_STATCUINOP                  (6)
#define     WFS_CDM_STATCUNOVAL                 (7)
#define     WFS_CDM_STATCUNOREF                 (8)

/* values of WFSCDMMIXTYPE.usMixType */

#define     WFS_CDM_MIXALGORITHM                (1)
#define     WFS_CDM_MIXTABLE                    (2)

/* values of WFSCDMMIXTYPE.usMixNumber */

#define     WFS_CDM_INDIVIDUAL                  (0)

/* values of WFSCDMMIXTYPE.usSubType (predefined mix algorithms) */
#define     WFS_CDM_MIX_MINIMUM_NUMBER_OF_BILLS            (1)
#define     WFS_CDM_MIX_EQUAL_EMPTYING_OF_CASH_UNITS       (2)

/* values of WFSCDMPRESENTSTATUS.wPresentState */

#define     WFS_CDM_PRESENTED                   (1)
#define     WFS_CDM_NOTPRESENTED                (2)
#define     WFS_CDM_UNKNOWN                     (3)

/* values of WFSCDMDISPENSE.usPosition */
/* values of WFSCDMCAPS.fwOutputPositions */
/* values of WFSCDMOUTPOS.fwPosition */
/* values of WFSCDMTELLERPOS.usPosition */

#define     WFS_CDM_POSNULL                     (0x0000)
#define     WFS_CDM_POSLEFT                     (0x0001)
#define     WFS_CDM_POSRIGHT                    (0x0002)
#define     WFS_CDM_POSCENTER                   (0x0004)

/* values of lpusVandalism */

#define     WFS_CDM_NODEVMANIPULATION           (0)
#define     WFS_CDM_DEVMANIPULATION             (1)

/* values of WFSCDMCUERROR.wFailure */

#define     WFS_CDM_CASHUNITEMPTY               (1)
#define     WFS_CDM_CASHUNITLOCKED              (2)
#define     WFS_CDM_CASHUNITNOTCONF             (3)
#define     WFS_CDM_CASHUNITINVALID             (4)
#define     WFS_CDM_CASHUNITERROR               (5)
#define     WFS_CDM_CASHUNITFULL                (6)

/* values of lpusReason in WFS_EXEE_CDM_INPUTREFUSE */
#define     WFS_CDM_INVALIDBILL                 (7)

/* WOSA/XFS CDM Errors */

#define WFS_ERR_CDM_INVALIDCURRENCY     (-(CDM_SERVICE_OFFSET + 0))
#define WFS_ERR_CDM_INVALIDTELLERID     (-(CDM_SERVICE_OFFSET + 1))
#define WFS_ERR_CDM_CASHUNITERROR       (-(CDM_SERVICE_OFFSET + 2))
#define WFS_ERR_CDM_INVALIDDENOMINATION (-(CDM_SERVICE_OFFSET + 3))
#define WFS_ERR_CDM_INVALIDMIXNUMBER    (-(CDM_SERVICE_OFFSET + 4))
#define WFS_ERR_CDM_NOCURRENCYMIX       (-(CDM_SERVICE_OFFSET + 5))
#define WFS_ERR_CDM_NOTDISPENSABLE      (-(CDM_SERVICE_OFFSET + 6))
#define WFS_ERR_CDM_TOOMANYBILLS        (-(CDM_SERVICE_OFFSET + 7))
#define WFS_ERR_CDM_INVALIDPOSITION     (-(CDM_SERVICE_OFFSET + 8))
#define WFS_ERR_CDM_POSITIONLOCKED      (-(CDM_SERVICE_OFFSET + 9))
#define WFS_ERR_CDM_SAFEDOOROPEN        (-(CDM_SERVICE_OFFSET + 10))
#define WFS_ERR_CDM_INVALIDRETRACT      (-(CDM_SERVICE_OFFSET + 11))
#define WFS_ERR_CDM_SHUTTERNOTOPEN      (-(CDM_SERVICE_OFFSET + 12))
#define WFS_ERR_CDM_SHUTTEROPEN         (-(CDM_SERVICE_OFFSET + 13))
#define WFS_ERR_CDM_SHUTTERCLOSED       (-(CDM_SERVICE_OFFSET + 14))
#define WFS_ERR_CDM_INVALIDCASHUNIT     (-(CDM_SERVICE_OFFSET + 15))
#define WFS_ERR_CDM_NOBILLS             (-(CDM_SERVICE_OFFSET + 16))
#define WFS_ERR_CDM_EXCHANGEACTIVE      (-(CDM_SERVICE_OFFSET + 17))
#define WFS_ERR_CDM_NOEXCHANGEACTIVE    (-(CDM_SERVICE_OFFSET + 18))
#define WFS_ERR_CDM_SHUTTERNOTCLOSED    (-(CDM_SERVICE_OFFSET + 19))
#define WFS_ERR_CDM_PRERRORNOBILLS      (-(CDM_SERVICE_OFFSET + 20))
#define WFS_ERR_CDM_PRERRORBILLS        (-(CDM_SERVICE_OFFSET + 21))
#define WFS_ERR_CDM_PRERRORUNKNOWN      (-(CDM_SERVICE_OFFSET + 22))
#define WFS_ERR_CDM_BILLSTAKEN          (-(CDM_SERVICE_OFFSET + 23))
#define WFS_ERR_CDM_TOOMANYCOINS        (-(CDM_SERVICE_OFFSET + 24))
#define WFS_ERR_CDM_CASHINACTIVE        (-(CDM_SERVICE_OFFSET + 25))
#define WFS_ERR_CDM_NOCASHINSTARTED     (-(CDM_SERVICE_OFFSET + 26))
#define WFS_ERR_CDM_INVALIDMIXTABLE     (-(CDM_SERVICE_OFFSET + 27))

/*=================================================================*/
/* CDM Info Command Structures */
/*=================================================================*/

typedef struct _wfs_cdm_outpos
{
    WORD            fwPosition;
    WORD            fwShutter;
    WORD            fwOutputPosition;
    WORD            fwTransport;
} WFSCDMOUTPOS, * LPWFSCDMOUTPOS;

typedef struct _wfs_cdm_status
{
    WORD             fwDevice;
    WORD             fwSafeDoor;
    WORD             fwDispenser;
    WORD             fwIntermediateStacker;
    LPWFSCDMOUTPOS * lppOutputPositions;
    LPSTR            lpszExtra;
} WFSCDMSTATUS, * LPWFSCDMSTATUS;

typedef struct _wfs_cdm_caps
{
    WORD            wClass;
    WORD            fwType;
    WORD            wMaxBills;
    WORD            wMaxCoins;
    BOOL            bCompound;
    BOOL            bShutter;
    BOOL            bRetract;
    BOOL            bSafeDoor;
    BOOL            bCoins;
    BOOL            bCylinders;
    BOOL            bCashBox;
    BOOL            bCashIn;
    BOOL            bRefill;
    BOOL            bAutoDeposit;
    BOOL            bVandalCheck;
    BOOL            bIntermediateStacker;
    BOOL            bBillsTakenSensor;
    WORD            fwOutputPositions;
    LPSTR           lpszExtra;
} WFSCDMCAPS, * LPWFSCDMCAPS;

typedef struct _wfs_cdm_physicalcu
{
    LPSTR           lpPhysicalPositionName;
    CHAR            cUnitID[5];
    ULONG           ulCount;
    USHORT          usPStatus;
} WFSCDMPHCU, * LPWFSCDMPHCU;

typedef struct _wfs_cdm_cashunit
{
    USHORT          usNumber;
    USHORT          usType;
    CHAR            cUnitID[5];
    CHAR            cCurrencyID[3];
    ULONG           ulValues;
    ULONG           ulInitialCount;
    ULONG           ulCount;
    ULONG           ulMinimum;
    ULONG           ulMaximum;
    BOOL            bAppLock;
    BOOL            bDevLock;
    USHORT          usStatus;
    LPSTR           lpPhysicalPositionName;
    USHORT          usNumPhysicalCUs;
    LPWFSCDMPHCU   *lppPhysical;
} WFSCDMCASHUNIT, * LPWFSCDMCASHUNIT;

typedef struct _wfs_cdm_cu_info
{
    USHORT          usTellerID;
    USHORT          usCount;
    LPWFSCDMCASHUNIT *lppList;
} WFSCDMCUINFO, * LPWFSCDMCUINFO;

typedef struct _wfs_cdm_teller_info
{
    USHORT          usTellerID;
    CHAR            cCurrencyID[3];
} WFSCDMTELLERINFO, * LPWFSCDMTELLERINFO;

typedef struct _wfs_cdm_teller_totals
{
    USHORT          usTellerID;
    CHAR            cCurrencyID[3];
    ULONG           ulBills;
    ULONG           ulCoins;
    ULONG           ulCashIn;
    ULONG           ulCashBox;
} WFSCDMTELLERTOTALS, * LPWFSCDMTELLERTOTALS;

typedef struct _wfs_cdm_teller_pos
{
    USHORT          usTellerID;
    USHORT          usPosition;
} WFSCDMTELLERPOS, * LPWFSCDMTELLERPOS;

typedef struct _wfs_cdm_currency_exp
{
    CHAR            cCurrencyID[3];
    SHORT           sExponent;
} WFSCDMCURRENCYEXP, * LPWFSCDMCURRENCYEXP;

typedef struct _wfs_cdm_mix_type
{
    USHORT          usMixNumber;
    USHORT          usMixType;
    USHORT          usSubType;
    LPSTR           lpszName;
} WFSCDMMIXTYPE, * LPWFSCDMMIXTYPE;

typedef struct _wfs_cdm_mix_row
{
    ULONG           ulAmount;
    LPUSHORT        lpusMixture;
} WFSCDMMIXROW, * LPWFSCDMMIXROW;

typedef struct _wfs_cdm_mix_table
{
    USHORT          usMixNumber;
    LPSTR           lpszName;
    USHORT          usRows;
    USHORT          usCols;
    LPULONG         lpulMixHeader;
    LPWFSCDMMIXROW  *lppMixRows;
} WFSCDMMIXTABLE, * LPWFSCDMMIXTABLE;

typedef struct _wfs_cdm_denomination
{
    CHAR            cCurrencyID[3];
    ULONG           ulAmount;
    USHORT          usCount;
    LPULONG         lpulValues;
    ULONG           ulCashBox;
} WFSCDMDENOMINATION, * LPWFSCDMDENOMINATION;

typedef struct _wfs_cdm_present_status
{
    LPWFSCDMDENOMINATION  lpDenomination;
    WORD                  wPresentState;
    LPSTR                 lpszExtra;
} WFSCDMPRESENTSTATUS, * LPWFSCDMPRESENTSTATUS;

/*=================================================================*/
/* CDM Execute Command Structures */
/*=================================================================*/

typedef struct _wfs_cdm_denominate
{
    USHORT                usTellerID;
    USHORT                usMixNumber;
    LPWFSCDMDENOMINATION  lpDenomination;
} WFSCDMDENOMINATE, * LPWFSCDMDENOMINATE;

typedef struct _wfs_cdm_dispense
{
    USHORT                usTellerID;
    USHORT                usMixNumber;
    USHORT                usPosition;
    BOOL                  bPresent;
    LPWFSCDMDENOMINATION  lpDenomination;
} WFSCDMDISPENSE, * LPWFSCDMDISPENSE;

typedef struct _wfs_cdm_cashin
{
    USHORT                usTellerID;
    LPWFSCDMDENOMINATION  lpDenomination;
} WFSCDMCASHIN, * LPWFSCDMCASHIN;

typedef struct _wfs_cdm_start_ex
{
    USHORT           usTellerID;
    USHORT           usCount;
    LPUSHORT         lpusCUNumList;
} WFSCDMSTARTEX, * LPWFSCDMSTARTEX;

typedef struct _wfs_cdm_calibrate
{
    USHORT        usNumber;
    USHORT        usNumOfBills;
} WFSCDMCALIBRATE, * LPWFSCDMCALIBRATE;

/*=================================================================*/
/* CDM Message Structures */
/*=================================================================*/

typedef struct _wfs_cdm_cu_error
{
    WORD              wFailure;
    LPWFSCDMCASHUNIT  lpCashUnit;
} WFSCDMCUERROR, * LPWFSCDMCUERROR;

/* restore alignment */
#pragma pack (pop)

#ifdef __cplusplus
}       /*extern "C"*/
#endif

#endif /* __INC_XFSCDM__H */


WOSA

(Windowsä Open Services Architecture)

Extensions for Financial Services

A Client-Server Architecture for Financial Enterprise Computing under Microsoft® Windows

PIN Keypad Device Class Interface

–––––––––––––––––––––––––––––––––––

Programmer’s Reference

Revision 2.00

November 11, 1996

Developed by the members of the Banking Solutions Vendor Council


Table of Contents

1. Introduction
1.1 WOSA/XFS Service-Specific Programming

2. Personal Identification Number (PIN) Keypads

3. Info Commands
3.1 WFS_INF_PIN_STATUS

3.2 WFS_INF_PIN_CAPABILITIES

3.3 WFS_INF_PIN_KEY_DETAIL

3.4 WFS_INF_PIN_FUNCKEY_DETAIL

4. Execute Commands
4.1 WFS_CMD_PIN_CRYPT

4.2 WFS_CMD_PIN_IMPORT_KEY

4.3 WFS_CMD_PIN_DERIVE_KEY

4.4 WFS_CMD_PIN_GET_PIN

4.5 WFS_CMD_PIN_LOCAL_DES

4.6 WFS_CMD_PIN_CREATE_OFFSET

4.7 WFS_CMD_PIN_LOCAL_EUROCHEQUE

4.8 WFS_CMD_PIN_LOCAL_VISA

4.9 WFS_CMD_PIN_PRESENT_IDC

4.10 WFS_CMD_PIN_GET_PINBLOCK

4.11 WFS_CMD_PIN_GET_DATA

4.12 WFS_CMD_PIN_INITIALIZATION

5. Events
5.1 WFS_EXEE_PIN_KEY

5.2 WFS_SRVE_PIN_INITIALIZED

5.3 WFS_SRVE_PIN_ILLEGAL_KEY_ACCESS

6. C - Header File


1.1 WOSA/XFS Service-Specific Programming

The service classes are defined by their service-specific commands and the associated data structures, error codes, messages, etc. These commands are used to request functions that are specific to one or more classes of service providers, but not all of them, and therefore are not included in the common API for basic or administration functions.

When a service-specific command is common among two or more classes of service providers, the syntax of the command is as similar as possible across all services, since a major objective of the WOSA Extensions for Financial Services is to standardize command codes and structures for the broadest variety of services. For example, using the WFSExecute function, the commands to read data from various services are as similar as possible to each other in their syntax and data structures.

In general, the specific command set for a service class is defined as the union of the specific capabilities likely to be provided by the developers of the services of that class; thus any particular device will normally support only a subset of the defined command set.

There are three cases in which a service provider may receive a service-specific command that it does not support:

  • The requested capability is defined for the class of service providers by the WOSA/XFS specification, the particular vendor implementation of that service does not support it, and the unsupported capability is not considered to be fundamental to the service. In this case, the service provider returns a successful completion, but does no operation. An example would be a request from an application to turn on a control indicator on a passbook printer; the service provider recognizes the command, but since the passbook printer it is managing does not include that indicator, the service provider does no operation and returns a successful completion to the application.

  • The requested capability is defined for the class of service providers by the WOSA/XFS specification, the particular vendor implementation of that service does not support it, and the unsupported capability is considered to be fundamental to the service. In this case, a WFS_ERR_UNSUPP_COMMAND error is returned to the calling application. An example would be a request from an application to a cash dispenser to dispense coins; the service provider recognizes the command but, since the cash dispenser it is managing dispenses only notes, returns this error.

  • The requested capability is not defined for the class of service providers by the WOSA/XFS specification. In this case, a WFS_ERR_INVALID_COMMAND error is returned to the calling application .

This design allows implementation of applications that can be used with a range of services that provide differing subsets of the functionalities that are defined for their service class. Applications may use the WFSGetInfo and WFSAsyncGetInfo commands to inquire about the capabilities of the service they are about to use, and modify their behavior accordingly, or they may use functions and then deal with WFS_ERR_UNSUPP_COMMAND error returns to make decisions as to how to use the service.


2. Personal Identification Number (PIN) Keypads

This section describes the application program interface for personal identification number keypads (PIN pads) and other encryption/decryption devices. This description includes definitions of the service-specific commands that can be issued, using the WFSAsyncExecute, WFSExecute, WFSGetInfo and WFSAsyncGetInfo functions.

This section describes the general interface for the following functions:

  • Administration of encryption devices

  • Loading of encryption keys

  • Encryption / decryption

  • Entering Personal Identification Numbers (PINs)

  • PIN verification

  • PIN block generation (encrypted PIN)

  • Clear text data handling

  • Function key handling

  • PIN presentation to chip card

If the PIN Pad device has local display capability, display handling should be handled using the Text Terminal Unit (TTU) interface.

This specification does not claim to adhere to any security standards, any security standards supported will be vendor dependent.

Important Notes:

  • This revision of this specification does not define key management procedures; key management is vendor-specific.

  • Key space management is customer-specific, and is therefore handled by vendor-specific mechanisms.

  • Only numeric PIN pads are handled in this specification.


3.1 WFS_INF_PIN_STATUS

Description The WFS_INF_PIN_STATUS command returns several kinds of status information.

Input Param None.

Output Param LPWFSPINSTATUS lpStatus;

typedef struct _wfs_pin_status
 {
 WORD    fwDevice;
 WORD    fwEncStat;
 LPSTR    lpszExtra;
 } WFSPINSTATUS, * LPWFSPINSTATUS;

fwDevice
Specifies the state of the PIN pad device as one of the following flags:

Value Meaning

WFS_PIN_DEVONLINE The device is on-line.

WFS_PIN_DEVOFFLINE The device is off-line.

WFS_PIN_DEVPOWEROFF The device is powered off.

WFS_PIN_DEVBUSY The device is busy processing a request.

WFS_PIN_DEVNODEVICE There is no device connected.

WFS_PIN_DEVHWERROR The device is inoperable due to a hardware error.

WFS_PIN_DEVUSERERROR The device is inoperable due to interference by a user.

fwEncStat
Specifies the state of the Encryption Module as one of the following flags:

Value Meaning

WFS_PIN_ENCNOTREADY The encryption module is not ready.

WFS_PIN_ENCNOTINITIALIZED The encryption module is not initialized (no master key loaded).

WFS_PIN_ENCINITIALIZED The encryption module is initialized and master key (where required) and any other initial keys are loaded; ready to import other keys.

WFS_PIN_ENCREADY The encryption module is initialized and ready (at least one key is imported into the encryption module).

WFS_PIN_ENCBUSY The encryption module is busy (implies that the device is busy).

WFS_PIN_ENCUNDEFINED The encryption module state is undefined.

lpszExtra
Specifies a list of vendor-specific, or any other extended, information. The information is returned as a series of “key=value” strings so that it is easily extendable by service providers. Each string will be null-terminated, with the final string terminating with two null characters.

Error Codes There are no additional error codes generated by this command.

Comments Applications which require or expect specific information to be present in the lpszExtra parameter may not be device or vendor-independent.


3.2 WFS_INF_PIN_CAPABILITIES

Description This command is used to retrieve the capabilities of the PIN pad.

Input Param None.

Output Param LPWFSPINCAPS lpCaps;

typedef struct _wfs_pin_caps
 {
 WORD   wClass;
 WORD   fwType;
 BOOL   bCompound;
 USHORT   usKeyNum;
 WORD   fwAlgorithms;
 WORD   fwPinFormats;
 WORD   fwDerivationAlgorithms;
 WORD   fwPresentationAlgorithms;
 WORD   fwDisplay;
 BOOL   bIDConnect;
 WORD   fwIDKey;
 WORD   fwValidationAlgorithms;
 LPSTR   lpszExtra;
 } WFSPINCAPS, * LPWFSPINCAPS;

wClass
Specifies the logical service class, value is:
WFS_SERVICE_CLASS_PIN

fwType
Specifies the type of the PIN pad security module as a combination of the following flags:

Value Meaning

WFS_PIN_TYPEEPP electronic PIN pad

WFS_PIN_TYPEEDM encryption/decryption module

bCompound
Specifies whether the logical device is part of a compound physical device and is either TRUE or FALSE.

usKeyNum
Number of the keys which can be stored in the encryption/decryption module.

fwAlgorithms
Supported encryption modes; a combination of the following flags:

Value Meaning

WFS_PIN_CRYPTDESECB Electronic Code Book

WFS_PIN_CRYPTDESCBC Cipher Block Chaining

WFS_PIN_CRYPTDESMAC MAC calculation using CBC

WFS_PIN_CRYPTDESCFB Cipher Feed Back

WFS_PIN_CRYPTRSA RSA Encryption

WFS_PIN_CRYPTECMA ECMA Encryption

WFS_PIN_CRYPTTRIDESECB Triple DES with Electronic Code Book

WFS_PIN_CRYPTTRIDESCBC Triple DES with Cipher Block Chaning

WFS_PIN_CRYPTTRIDESCFB Triple DES with Cipher Feed Back

WFS_PIN_CRYPTTRIDESMAC Triple DES MAC calculation using CBC

fwPinFormats
Supported PIN formats; a combination of the following flags:

Value Meaning

WFS_PIN_FORM3624 PIN left justified, filled with padding characters, PIN length 4-16 digits

WFS_PIN_FORMANSI PIN is preceded by 0x00 and the length of the PIN (0x04 to 0x0C), filled with padding character 0x0F to the right, PIN length 4-12 digits, XORed with PAN (Primary Account Number, minimum 12 digits without check number)

WFS_PIN_FORMISO0 PIN is preceded by 0x00 and the length of the PIN (0x04 to 0x0C), filled with padding character 0x0F to the right, PIN length 4-12 digits, XORed with PAN (Primary Account Number, no minimum length specified, missing digits are filled with 0x00)

WFS_PIN_FORMISO1 PIN is preceded by 0x01 and the length of the PIN (0x04 to 0x0C), padding characters are taken from a transaction field (10 digits)

WFS_PIN_FORMECI2 (similar to WFS_PIN_FORM3624), PIN only 4 digits

WFS_PIN_FORMECI3 PIN is preceded by the length (digit), PIN length 4-6 digits, padded with 0x00

WFS_PIN_FORMVISA same as WFS_PIN_FORMECI3

WFS_PIN_FORMDIEBOLD PIN is padded with the padding character and may be not encrypted, single encrypted or double encrypted.

WFS_PIN_FORMDIEBOLDCO PIN is preceeded by the two-digit coordination number, padded with the padding character and may be not encrypted, single encrypted or double encrypted.

fwDerivationAlgorithms
Supported derivation algorithms; a combination of the following flags:

Value Meaning

WFS_PIN_CHIP_ZKA Algorithm for the derivation of a chip card individual key as described by the German ZKA.

fwPresentationAlgorithms
Supported presentation algorithms; a combination of the following flags:

Value Meaning

WFS_PIN_PRESENT_CLEAR Algorithm for the presentation of a clear text PIN to a chip card.

fwDisplay
Specifies the type of the display used in the PIN pad module as one of the following flags:

Value Meaning

WFS_PIN_DISPNONE no display unit

WFS_PIN_DISPLEDTHROUGH lights next to text guide user

WFS_PIN_DISPDISPLAY a real display is available (this doesn’t apply for self-service)

bIDConnect
Specifies whether the PIN pad is directly physically connected to the ID card unit. The value of this parameter is either TRUE or FALSE.

fwIDKey
Specifies whether an ID key is supported as a combination of the following flags:

Value Meaning

WFS_PIN_IDKEYINITIALIZATION ID key supported in the WFS_CMD_PIN_INITIALIZATION command.

WFS_PIN_IDKEYIMPORT ID key supported in the WFS_CMD_PIN_IMPORT_KEY command.

fwValidationAlgorithms
Specifies the algorithms for PIN validation supported by the service; combination of the following flags:

Value Meaning

WFS_PIN_DES DES algorithm

WFS_PIN_EUROCHEQUE EUROCHEQUE algorithm

WFS_PIN_VISA VISA algorithm

WFS_PIN_DES_OFFSET DES offset generation algorithm

lpszExtra
Points to a list of vendor-specific, or any other extended information. The information is returned as a series of “key=value” strings so that it is easily extendable by service providers. Each string is null-terminated, with the final string terminating with two null characters.

Error Codes There are no additional error codes generated by this command.

Comments Applications which require or expect specific information to be present in the lpsExtra parameter may not be device or vendor-independent.


3.3 WFS_INF_PIN_KEY_DETAIL

Description This command returns detailed information about the keys in the encryption module.

Input Param LPSTR lpsKeyName;

lpsKeyName
Name of the key for which detailed information is requested.
If NULL, detailed information about all the keys in the encryption module is returned.

Output Param LPWFSPINKEYDETAIL * lppKeyDetail;

Pointer to a null-terminated array of pointers to key detail structures.

typedef struct _wfs_pin_key_detail
 {
 LPSTR   lpsKeyName;
 WORD   fwUse;
 BOOL   bLoaded;
 } WFSPINKEYDETAIL, * LPWFSPINKEYDETAIL;

lpsKeyName
Specifies the name of the key.

fwUse
Specifies the type of access for which the key is used as a combination of the following flags:

Value Meaning

WFS_PIN_USECRYPT key can be used for encryption/decryption

WFS_PIN_USEFUNCTION key can be used for PIN functions

WFS_PIN_USEMACING key can be used for MACing

WFS_PIN_USEKEYENCKEY key is used as key encryption key

WFS_PIN_USESVENCKEY key is used as CBC Start Value encryption key

WFS_PIN_USENODUPLICATE key can be imported only once

bLoaded
Specifies whether the key has been loaded (imported from Application or locally from Operator) and is either TRUE or FALSE.

Error Codes The following additional error codes can be generated by this command:

Value Meaning

WFS_ERR_PIN_KEYNOTFOUND The specified key name is not found.

Comments None.


3.4 WFS_INF_PIN_FUNCKEY_DETAIL

Description This command returns information about the names of the Function Keys supported by the device. Location information is also returned for the supported FDKs (Function Descriptor Keys) or Touch Screen Pads if this XFS interface is used for Touch Screen input.

Input Param LPULONG lpulFDKMask;

lpulFDKMask
Mask for the FDKs for which additional information is requested.
If 0x00000000, only information about function keys is returned.
If 0xFFFFFFFF, information about all the supported FDKs is returned.

Output Param LPWFSPINFUNCKEYDETAIL lpFuncKeyDetail;

typedef struct _wfs_pin_func_key_detail
 {
  ULONG    ulFuncMask;
 USHORT    usNumberFDKs;
 LPWFSPINFDK  * lppFDKs;
 } WFSPINFUNCKEYDETAIL, * LPWFSPINFUNCKEYDETAIL;

ulFuncMask
Specifies the function keys available for this physical device as a combination of the following flags:

WFS_PIN_FK_0

WFS_PIN_FK_1

WFS_PIN_FK_2

WFS_PIN_FK_3

WFS_PIN_FK_4

WFS_PIN_FK_5

WFS_PIN_FK_6

WFS_PIN_FK_7

WFS_PIN_FK_8

WFS_PIN_FK_9

WFS_PIN_FK_ENTER

WFS_PIN_FK_CANCEL

WFS_PIN_FK_CLEAR

WFS_PIN_FK_BACKSPACE

WFS_PIN_FK_HELP

WFS_PIN_FK_DECPOINT

WFS_PIN_FK_00

WFS_PIN_FK_000

WFS_PIN_FK_RES1 (reserved for future use)

WFS_PIN_FK_RES2 (reserved for future use)

WFS_PIN_FK_RES3 (reserved for future use)

WFS_PIN_FK_RES4 (reserved for future use)

WFS_PIN_FK_RES5 (reserved for future use)

WFS_PIN_FK_RES6 (reserved for future use)

WFS_PIN_FK_RES7 (reserved for future use)

WFS_PIN_FK_RES8 (reserved for future use)

The remaining 6 bit masks may be used as vendor dependent keys.

WFS_PIN_FK_OEM1

WFS_PIN_FK_OEM2

WFS_PIN_FK_OEM3

WFS_PIN_FK_OEM4

WFS_PIN_FK_OEM5

WFS_PIN_FK_OEM6

usNumberFDKs
This value indicates the number of FDK structures returned. This number can be less than the number of keys requested, if any keys are not supported.

lppFDKs
Pointer to an array of pointers to FDK structures.

 typedef struct _wfs_pin_fdk
  {
  ULONG  ulFDK;
  USHORT  usXPosition;
  USHORT  usYPosition;
  } WFSPINFDK, * LPWFSPINFDK;

ulFDK
Specifies the code returned by this FDK, defined as one of the following values:

WFS_PIN_FK_FDK01

WFS_PIN_FK_FDK02

WFS_PIN_FK_FDK03

WFS_PIN_FK_FDK04

WFS_PIN_FK_FDK05

WFS_PIN_FK_FDK06

WFS_PIN_FK_FDK07

WFS_PIN_FK_FDK08

WFS_PIN_FK_FDK09

WFS_PIN_FK_FDK10

WFS_PIN_FK_FDK11

WFS_PIN_FK_FDK12

WFS_PIN_FK_FDK13

WFS_PIN_FK_FDK14

WFS_PIN_FK_FDK15

WFS_PIN_FK_FDK16

WFS_PIN_FK_FDK17

WFS_PIN_FK_FDK18

WFS_PIN_FK_FDK19

WFS_PIN_FK_FDK20

WFS_PIN_FK_FDK21

WFS_PIN_FK_FDK22

WFS_PIN_FK_FDK23

WFS_PIN_FK_FDK24

WFS_PIN_FK_FDK25

WFS_PIN_FK_FDK26

WFS_PIN_FK_FDK27

WFS_PIN_FK_FDK28

WFS_PIN_FK_FDK29

WFS_PIN_FK_FDK30

WFS_PIN_FK_FDK31

WFS_PIN_FK_FDK32

usXPosition
For FDKs, specifies the FDK position relative to the Left Hand side of the screen expressed as a percentage of the width of the screen.

usYPosition
For FDKs, specifies the FDK position relative to the top of the screen expressed as a percentage of the height of the screen.

Error Codes There are no additonal error codes generated by this command.

Comments None.


4.1 WFS_CMD_PIN_CRYPT

Description The input data is either encrypted or decrypted using the specified or selected encryption mode. The available modes are defined in the WFS_INF_PIN_CAPABILITIES command.

This command can also be used for Message Authentication Code generation (i.e. MACing). For this purpose, it is possible to specify how the data is formatted before the encryption.

The input data can be expanded with a fill-character to the necessary length (mandated by the encryption algorithm being used).

The Start Value (or Initialization Vector) should be able to be passed encrypted like the specified encryption/decryption key. It would therefore need to be decrypted with a loaded key so the name of this key must also be passed. However, both these parameters are optional.

Input Param LPWFSPINCRYPT lpCrypt;

typedef struct _wfs_pin_crypt
 {
 WORD    wMode;
 LPSTR    lpsKey;
 LPWFSXDATA  lpxKeyEncKey;
 WORD    wAlgorithm;
 LPSTR    lpsStartValueKey;
 LPWFSXDATA  lpxStartValue;
 BYTE    bPadding;
 BYTE    bCompression;
 LPWFSXDATA  lpxCryptData;
 } WFSPINCRYPT, * LPWFSPINCRYPT;

wMode
Specifies whether to encrypt or decrypt, values are one of the following:

Value Meaning

WFS_PIN_MODEENCRYPT encrypt with key

WFS_PIN_MODEDECRYPT decrypt with key

This parameter does not apply to MACing.

lpsKey
Specifies the name of the stored key.

lpxKeyEncKey
If NULL, lpsKey is used directly for encryption/decryption. Otherwise, lpsKey is used to decrypt the encrypted key passed in lpxKeyEncKey and the result is used for encryption/decryption. Key is a double length key when used for Triple DES encryption/decryption. Users of this specification must adhere to local regulations when using Triple DES.

wAlgorithm
Specifies the encryption algorithm. Possible values are those described in WFS_INF_PIN_CAPABILITIES.

lpsStartValueKey
Specifies the name of the stored key used to decrypt the lpxStartValue to obtain the Initialization Vector. If this parameter is NULL, lpxStartValue is used as the Initialization Vector.

lpxStartValue
DES and Triple DES initialization vector for CBC / CFB encryption and MACing. If this parameter is NULL lpsStartValueKey is used as the Start Value. If lpsStartValueKey is also NULL, the default value for CBC / CFB / MAC is 16 hex digits 0x0.

bPadding
Specifies the padding character for encryption.

bCompression
Specifies whether data is to be compressed (blanks removed) before building the MAC. If bCompression is 0x00 no compression is selected, otherwise bCompression holds the representation of the blank character in the actual code table.

lpxCryptData
Pointer to the data to be encrypted, decrypted, or MACed.

Output Param LPWFSXDATA lpxCryptData;

lpxCryptData
Pointer to the encrypted or decrypted data, or MAC value.

Error Codes The following additional error codes can be generated by this command:

Value Meaning

WFS_ERR_PIN_KEYNOTFOUND The specified key was not found.

WFS_ERR_PIN_KEYNOVALUE The specified key is not loaded.

WFS_ERR_PIN_USEVIOLATION The specified use is not supported by this key.

WFS_ERR_PIN_MODENOTSUPPORTED The specified mode is not supported.

WFS_ERR_PIN_ACCESSDENIED The encryption module is either not initialized or not ready for any vendor specific reason.

WFS_ERR_PIN_INVALIDKEYLENGTH The length of lpxKeyEncKey or lpxStartValue is not supported.

Events The following additional events can be generated by this command:

Value Meaning

WFS_SRVE_PIN_ILLEGAL_KEY_ACCESS An error occured accessing an encryption key.

Comments The datatype LPWFSXDATA is used to pass hexadecimal data and is defined as follows :

typedef struct _wfs_hex_data
 {
 USHORT  usLength;
 LPBYTE  lpbData;
 } WFSXDATA, *LPWFSXDATA;

usLength
Length of the byte stream pointed to by lpbData.

lpbData
Pointer to the binary data stream.


4.2 WFS_CMD_PIN_IMPORT_KEY

Description The key passed by the application is loaded in the encryption module. The key can be passed in clear text mode or encrypted with an accompanying “key encryption key”.

Input Param LPWFSPINIMPORT lpImport;

typedef struct _wfs_pin_import
 {
 LPSTR    lpsKey;
 LPSTR    lpsEncKey;
 LPWFSXDATA  lpxIdent;
 LPWFSXDATA  lpxValue;
 WORD    fwUse;
 } WFSPINIMPORT, * LPWFSPINIMPORT;

lpsKey
Specifies the name of key being loaded.

lpsEncKey
If lpsEncKey is NULL the key is loaded directly into the encryption module. Otherwise, lpsEncKey specifies a key name or a format name which were used to encrypt the key string passed in lpxValue.

lpxIdent
Specifies the key owner identification. The use of this parameter is vendor dependent.

lpxValue
Specifies the value of key to be loaded.

fwUse
Specifies the type of access for which the key can be used as a combination of the following flags:

Value Meaning

WFS_PIN_USECRYPT key can be used for encryption/decryption

WFS_PIN_USEFUNCTION key can be used for PIN functions

WFS_PIN_USEMACING key can be used for MACing

WFS_PIN_USEKEYENCKEY key is used as key encryption key

WFS_PIN_USESVENCKEY key is used as CBC Start Value encryption key

WFS_PIN_USENODUPLICATE key can be imported only once

Output Param LPWFSXDATA lpxKVC;

lpxKVC
pointer to the key verification code data that can be used for verification of the loaded key, NULL if device does not have that capability.

Error Codes The following additional error codes can be generated by this command:

Value Meaning

WFS_ERR_PIN_KEYNOTFOUND The specified key encryption key was not found.

WFS_ERR_PIN_KEYNOVALUE The specified key encryption key is not loaded.

WFS_ERR_PIN_USEVIOLATION The specified use is not supported by this key.

WFS_ERR_PIN_ACCESSDENIED The encryption module is either not initialized or not ready for any vendor specific reason.

WFS_ERR_PIN_INVALIDID The ID passed was not valid.

WFS_ERR_PIN_DUPLICATEKEY A key exists with that name and cannot be overwritten.

WFS_ERR_PIN_INVALIDKEYLENGTH The length of lpxValue is not supported.

Events The following additional events can be generated by this command:

Value Meaning

WFS_SRVE_PIN_ILLEGAL_KEY_ACCESS An error occured accessing an encryption key.

Comments None.


4.3 WFS_CMD_PIN_DERIVE_KEY

Description A key is derived from input data using a key generating key and an initialization vector. The input data can be expanded with a fill-character to the necessary length (mandated by the encryption algorithm being used). The derived key is imported into the encryption module and is used for encryption or decryption operations.

Input Param LPWFSPINDERIVE lpDerive;

typedef struct _wfs_pin_derive
 {
 WORD    wDerivationAlgorithm;
 LPSTR    lpsKey;
 LPSTR    lpsKeyGenKey;
 LPSTR    lpsStartValueKey;
 LPWFSXDATA  lpxStartValue;
 BYTE    bPadding;
 LPWFSXDATA  lpxInputData;
 LPWFSXDATA  lpxIdent;
 } WFSPINDERIVE, * LPWFSPINDERIVE;

wDerivationAlgorithm
Specifies the algorithm that is used for derivation. Possible values are:
(see command WFS_INF_PIN_CAPABILITIES)

lpsKey
Specifies the name where the derived key will be stored.

lpsKeyGenKey
Specifies the name of the key generating key that is used for the derivation.

lpsStartValueKey
Specifies the name of the stored key used to decrypt the lpxStartValue to obtain the Initialization Vector. If this parameter is NULL, lpxStartValue is used as the Initialization Vector.

lpxStartValue
DES initialization vector for the encryption step within the derivation.

bPadding
Specifies the padding character for the encryption step within the derivation.

lpxInputData
Pointer to the data to be used for key derivation.

lpxIdent
Specifies the key owner identification. The use of this parameter is vendor dependent.

Output Param None.

Error Codes The following additional error codes can be generated by this command:

Value Meaning

WFS_ERR_PIN_KEYNOTFOUND The specified key was not found.

WFS_ERR_PIN_KEYNOVALUE The specified key is not loaded.

WFS_ERR_PIN_USEVIOLATION The specified use is not supported by this key.

WFS_ERR_PIN_MODENOTSUPPORTED The specified algorithm is not supported.

WFS_ERR_PIN_ACCESSDENIED The encryption module is either not initialized (or not ready for some vendor specific reason).

WFS_ERR_PIN_INVALIDID The ID passed was not valid.

WFS_ERR_PIN_DUPLICATEKEY A key exists with that name and cannot be overwritten.

WFS_ERR_PIN_INVALIDKEYLENGTH The length of lpxStartValue is not supported.

Events The following additional events can be generated by this command:

Value Meaning

WFS_SRVE_PIN_ILLEGAL_KEY_ACCESS An error occured accessing an encryption key.

Comments None.


4.4 WFS_CMD_PIN_GET_PIN

Description This function stores the PIN entry via the PIN pad. From the point this function is invoked, PIN digit entries are not passed to the application. For each PIN digit, or any other active key entered, an execute notification event is sent in order to allow an application to perform the appropriate display action (i.e. when the PIN pad has no integrated display). The application is not informed of the value entered, the execute notification only informs that a key has been depressed.

Some PIN pad devices do not inform the application as each PIN digit is entered, but locally process the PIN entry based upon minimum PIN length and maximum PIN length input parameters. These PIN pad devices which provide local PIN entry management and optional display tracking may or may not notify the application of a minimum PIN length violation.

When the maximum number of PIN digits is entered, or a completion key is pressed after the minimum number of PIN digits is entered, a WFS_EXEC_COMPLETE event message is sent to the application. Once this notification is received, the output parameters are then returned to the application from this function call. The depression of the <Cancel> key is also passed to the application via the WFS_EXEC_COMPLETE event message.

If usMaxLen is zero, the service provider does not terminate the command unless the application sets ulTerminateKeys or ulTerminateFDKs. In the event that ulTerminateKeys or ulTerminateFDKs are not set and usMaxLen is zero, the command will not terminate and the application must issue a WFSCancel command.

Input Param LPWFSPINGETPIN lpGetPin;

typedef struct _wfs_pin_getpin
 {
 USHORT  usMinLen;
 USHORT  usMaxLen;
 BOOL  bAutoEnd;
 CHAR  cEcho;
 ULONG  ulActiveFDKs;
 ULONG  ulActiveKeys;
 ULONG  ulTerminateFDKs;
 ULONG  ulTerminateKeys;
 } WFSPINGETPIN, * LPWFSPINGETPIN;

usMinLen
Specifies the minimum number of digits which must be entered for the PIN. A value of zero indicates no minimum PIN length verification.

usMaxLen
Specifies the maximum number of digits which can be entered for the PIN.

bAutoEnd
If bAutoEnd is set to true, the service provider terminates the command when the maximum number of digits are entered. Otherwise, the input is terminated by the user using one of the termination keys. When usMaxLen is reached, the service provider will disable all numeric keys. bAutoEnd is ignored when usMaxLen is set to 0.

cEcho
Specifies the replace character to be echoed on a local display for the PIN digit.

ulActiveFDKs
Specifies those FDKs which are active during the execution of the command.

ulActiveKeys
Specifies those (other) Function Keys which are active during the execution of the command.

ulTerminateFDKs
Specifies those FDKs which must terminate the execution of the command.

ulTerminateKeys
Specifies those (other) Function Keys which must terminate the execution of the command.

Output Param LPWFSPINENTRY lpEntry;

typedef struct _wfs_pin_entry
 {
 USHORT  usDigits;
 WORD  wCompletion;
 } WFSPINENTRY, * LPWFSPINENTRY;

usDigits
Specifies the number of PIN digits entered.

wCompletion
Specifies the reason for completion of the entry. Possible values are:

Value Meaning

WFS_PIN_COMPAUTO The command terminated automatically, because maximum PIN length was reached.

WFS_PIN_COMPENTER The ENTER Function Key was pressed.

WFS_PIN_COMPCANCEL The CANCEL Function Key was pressed.

WFS_PIN_COMPCONTINUE Input continues (this value is only used in the execute event WFS_EXEE_PIN_KEY).

WFS_PIN_COMPCLEAR The CLEAR Function Key was pressed and the previous input is cleared (this value is only used in the execute event WFS_EXEE_PIN_KEY).

WFS_PIN_COMPBACKSPACE The last input digit was cleared (this value is only used in the execute event WFS_EXEE_PIN_KEY).

WFS_PIN_COMPFDK An FDK was pressed.

WFS_PIN_COMPHELP The HELP Function Key was pressed..

WFS_PIN_COMPFK A Function Key (FK) other than ENTER, CLEAR, CANCEL, BACKSPACE, HELP was pressed.

Error Codes The following additional error codes can be generated by this command:

Value Meaning

WFS_ERR_PIN_KEYINVALID At least one of the specified function keys or FDKs is invalid.

WFS_ERR_PIN_KEYNOTSUPPORTED At least one of the specified function keys or FDKs is not supported by the service provider.

WFS_ERR_PIN_NOACTIVEKEYS There are no active function keys specified.

WFS_ERR_PIN_NOTERMINATEKEYS There are no terminate keys specified and usMaxLen is set to 0.

WFS_ERR_PIN_MINIMUMLENGTH The minimum PIN length field is invalid or greater than the maximum PIN length field.

Events The following additional events can be generated by this command:

Value Meaning

WFS_EXEE_PIN_KEY A key has been pressed at the PIN pad.

Comments None.


4.5 WFS_CMD_PIN_LOCAL_DES

Description The PIN, which was entered with the WFS_PIN_GET_PIN command, is combined with the requisite data specified by the DES validation algorithm and locally verified for correctness. The local DES verification is based on the IBM 3624 standard. The result of the verification is returned to the application. This command will clear the PIN.

Input Param LPWFSPINLOCALDES lpLocalDES;

typedef struct _wfs_pin_local_des
 {
 LPSTR   lpsValidationData;
 LPSTR   lpsOffset;
 BYTE   bPadding;
 USHORT   usMaxPIN;
 USHORT   usValDigits;
 BOOL   bNoLeadingZero;
 LPSTR   lpsKey;
 LPWFSXDATA lpxKeyEncKey;
 LPSTR   lpsDecTable;
 } WFSPINLOCALDES, * LPWFSPINLOCALDES;

lpsValidationData
Validation data

lpsOffset
Offset for the PIN block; if NULL then no offset is used.

bPadding
Specifies the padding character for validation data.

usMaxPIN
Maximum number of PIN digits to be used for validation.

usValDigits
Number of Validation digits to be used for validation.

bNoLeadingZero
If set to TRUE and the first digit of result of the modulo 10 addition is a X’0’, it is replaced with X’1’ before performing the verification against the entered PIN. If set to FALSE, a leading zero is allowed in entered PINs.

lpsKey
Name of the validation key

lpxKeyEncKey
If NULL, lpsKey is used directly for PIN validation. Otherwise, lpsKey is used to decrypt the encrypted key passed in lpxKeyEncKey and the result is used for PIN validation.

lpsDecTable
ASCII decimalization table (16 character string containing characters ‘0’ to ‘9’). Used to convert the hexadecimal digits (0x0 to 0xF) of the encrypted validation data to decimal digits (0x0 to 0x9).

Output Param LPBOOL pbResult;

lpbResult
Pointer to a boolean value which specifies whether the PIN is correct or not.

Error Codes The following additional error codes can be generated by this command:

Value Meaning

WFS_ERR_PIN_KEYNOTFOUND The specified key was not found.

WFS_ERR_PIN_KEYNOVALUE The specified key is not loaded.

WFS_ERR_PIN_USEVIOLATION The specified use is not supported by this key.

WFS_ERR_PIN_ACCESSDENIED The encryption module is either not initialized or not ready for any vendor specific reason.

WFS_ERR_PIN_NOPIN PIN has not been entered or has been cleared.

Events The following additional events can be generated by this command:

Value Meaning

WFS_SRVE_PIN_ILLEGAL_KEY_ACCESS An error occured accessing an encryption key.

Comments None.


4.6 WFS_CMD_PIN_CREATE_OFFSET

Description This function is used to generate a PIN Offset that is used to verify PINs using the WFS_CMD_PIN_LOCAL_DES execute command. The PIN offset is computed by combining validation data with the keypad entered PIN. This command will clear the PIN

Input Param LPWFSPINCREATEOFFSET lpPINOffset;

typedef struct _wfs_pin_create_offset
 {
 LPSTR   lpsValidationData;
 BYTE   bPadding;
 USHORT   usMaxPIN;
 USHORT   usValDigits;
 LPSTR   lpsKey;
 LPWFSXDATA lpxKeyEncKey;
 LPSTR   lpsDecTable;
 } WFSPINCREATEOFFSET, * LPWFSPINCREATEOFFSET;

lpsValidationData
Validation data

bPadding
Specifies the padding character for validation data.

usMaxPIN
Maximum number of PIN digits to be used for PIN Offset creation.

usValDigits
Number of Validation Data digits to be used for PIN Offset creation.

lpsKey
Name of the validation key

lpxKeyEncKey
If NULL, lpsKey is used directly in PIN Offset creation. Otherwise, lpsKey is used to decrypt the encrypted key passed in lpxKeyEncKey and the result is used in PIN Offset creation.

lpsDecTable
ASCII decimalization table (16 character string containing characters ‘0’ to ‘9’). Used to convert the hexadecimal digits (0x0 to 0xF) of the encrypted validation data to decimal digits (0x0 to 0x9).

Output Param LPSTR lpsOffset;

lpsOffset
Computed PIN Offset.

Error Codes The following additional error codes can be generated by this command:

Value Meaning

WFS_ERR_PIN_KEYNOTFOUND The specified key was not found.

WFS_ERR_PIN_KEYNOVALUE The specified key is not loaded.

WFS_ERR_PIN_USEVIOLATION The specified use is not supported by this key.

WFS_ERR_PIN_ACCESSDENIED The encryption module is either not initialized or not ready for any vendor specific reason.

WFS_ERR_PIN_NOPIN PIN has not been entered or has been cleared.

WFS_ERR_PIN_NOTALLOWED PIN entered by the user is not allowed.

Events The following additional events can be generated by this command:

Value Meaning

WFS_SRVE_PIN_ILLEGAL_KEY_ACCESS An error occured accessing an encryption key.

Comments The list of ‘forbidden’ PINs (values that cannot be chosen as a PIN, e.g. 1111) is configured in the device in a vendor dependent way during the configuration of the system.


4.7 WFS_CMD_PIN_LOCAL_EUROCHEQUE

Description The PIN, which was entered with the WFS_PIN_GET_PIN command, is combined with the requisite data specified by the Eurocheque validation algorithm and locally verified for correctness. The result of the verification is returned to the application. This command will clear the PIN.

Input Param LPWFSPINLOCALEUROCHEQUE lpLocalEurocheque;

typedef struct _wfs_pin_local_eurocheque
 {
 LPSTR   lpsEurochequeData;
 LPSTR   lpsPVV;
 WORD   wFirstEncDigits;
 WORD   wFirstEncOffset;
 WORD   wPVVDigits;
 WORD   wPVVOffset;
 LPSTR   lpsKey;
 LPWFSXDATA lpxKeyEncKey;
 LPSTR   lpsDecTable;
 } WFSPINLOCALEUROCHEQUE, * LPWFSPINLOCALEUROCHEQUE;

lpsEurochequeData
Track-3 Eurocheque data

lpsPVV
PIN Validation Value from track data.

wFirstEncDigits
Number of digits to extract after first encryption.

wFirstEncOffset
Offset of digits to extract after first encryption.

wPVVDigits
Number of digits to extract for PVV.

wPVVOffset
Offset of digits to extract for PVV.

lpsKey
Name of the validation key.

lpxKeyEncKey
If NULL, lpsKey is used directly for PIN validation. Otherwise, lpsKey is used to decrypt the encrypted key passed in lpxKeyEncKey and the result is used for PIN validation.

lpsDecTable
ASCII decimalization table (16 character string containing characters ‘0’ to ‘9’). Used to convert the hexadecimal digits (0x0 to 0xF) of the encrypted validation data to decimal digits (0x0 to 0x9).

Output Param LPBOOL lpbResult;

lpbResult
Pointer to a boolean value which specifies whether the PIN is correct or not.

Error Codes The following additional error codes can be generated by this command:

Value Meaning

WFS_ERR_PIN_KEYNOTFOUND The specified key was not found.

WFS_ERR_PIN_KEYNOVALUE The specified key is not loaded.

WFS_ERR_PIN_USEVIOLATION The specified use is not supported by this key.

WFS_ERR_PIN_ACCESSDENIED The encryption module is either not initialized or not ready for any vendor specific reason.

WFS_ERR_PIN_NOPIN PIN has not been entered or has been cleared.

Events The following additional events can be generated by this command:

Value Meaning

WFS_SRVE_PIN_ILLEGAL_KEY_ACCESS An error occured accessing an encryption key.

Comments None.


4.8 WFS_CMD_PIN_LOCAL_VISA

Description The PIN, which was entered with the WFS_PIN_GET_PIN command, is combined with the requisite data specified by the VISA validation algorithm and locally verified for correctness. The result of the verification is returned to the application. This command will clear the PIN.

Input Param LPWFSPINLOCALVISA lpLocalVISA;

typedef struct _wfs_pin_local_visa
 {
 LPSTR   lpsPAN;
 LPSTR   lpsPVV;
 WORD   wPVVDigits;
 LPSTR   lpsKey;
 LPWFSXDATA lpxKeyEncKey;
 } WFSPINLOCALVISA, * LPWFSPINLOCALVISA;

lpsPAN
Primary Account Number from track data.

lpsPVV
PIN Validation Value from track data.

wPVVDigits
Number of digits of PVV.

lpsKey
Name of the validation key.

lpxKeyEncKey
If NULL, lpsKey is used directly for PIN validation. Otherwise, lpsKey is used to decrypt the encrypted key passed in lpxKeyEncKey and the result is used for PIN validation.

Output Param LPBOOL lpbResult;

lpbResult
Pointer to a boolean value which specifies whether the PIN is correct or not.

Error Codes The following additional error codes can be generated by this command:

Value Meaning

WFS_ERR_PIN_KEYNOTFOUND The specified key was not found.

WFS_ERR_PIN_KEYNOVALUE The specified key is not loaded.

WFS_ERR_PIN_USEVIOLATION The specified use is not supported by this key.

WFS_ERR_PIN_ACCESSDENIED The encryption module is either not initialized or not ready for any vendor specific reason.

WFS_ERR_PIN_NOPIN PIN has not been entered or has been cleared.

Events The following additional events can be generated by this command:

Value Meaning

WFS_SRVE_PIN_ILLEGAL_KEY_ACCESS An error occured accessing an encryption key.

Comments None.


4.9 WFS_CMD_PIN_PRESENT_IDC

Description The PIN, which was entered with the WFS_PIN_GET_PIN command, is combined with the requisite data specified by the IDC presentation algorithm and presented to the smartcard contained in the ID Card unit. The result of the presentation is returned to the application. This command will clear the PIN.

Input Param LPWFSPINPRESENTIDC lpPresentIDC;

typedef struct _wfs_pin_presentidc
 {
 WORD   wPresentAlgorithm;
 WORD   wChipProtocol;
 ULONG   ulChipDataLength;
 LPBYTE   lpbChipData;
 LPVOID   lpAlgorithmData;
 } WFSPINPRESENTIDC, * LPWFSPINPRESENTIDC;

wPresentAlgorithm
Specifies the algorithm that is used for presentation. Possible values are: (see command WFS_INF_PIN_CAPABILITIES).

wChipProtocol
Identifies the protocol that is used to communicate with the chip. Possible values are: (see command WFS_INF_IDC_CAPABILITIES in the Identification Card Device Class Interface).

ulChipDataLength
Specifies the length of the byte stream pointed to by lpbChipData.

lpbChipData
Points to the data to be sent to the chip.

lpAlgorithmData
Pointer to a structure that contains the data required for the specified presentation algorithm.
For the WFS_PIN_PRESENT_CLEAR algorithm, this structure is defined as:

typedef struct _wfs_pin_presentclear
 {
 ULONG   ulPINPointer;
 USHORT   usPINOffset;
 } WFSPINPRESENTCLEAR, * LPWFSPINPRESENTCLEAR;

ulPINPointer

Describes the byte position where to insert the PIN in the lpbChipData buffer. The first byte of the lpbChipData buffer is numbered 0.

usPINOffset

Describes the bit position where to insert the PIN in the lpbChipData buffer. In each byte, the most-significant bit is numbered 0, the less significant bit is numbered 7.

Output Param LPWFSPINPRESENTRESULT lpPresentResult;

typedef struct _wfs_pin_present_result
 {
 WORD  wChipProtocol;
 ULONG  ulChipDataLength;
 LPBYTE  lpbChipData;
 } WFSPINPRESENTRESULT, * LPWFSPINPRESENTRESULT;

wChipProtocol
Identifies the protocol that was used to communicate with the chip. This field contains the same value as the corresponding field in the input structure.

ulChipDataLength
Specifies the length of the byte stream pointed to by lpbChipData.

lpbChipData
Points to the data responded from the chip.

Error Codes The following additional error codes can be generated by this command:

Value Meaning

WFS_ERR_PIN_INVALIDDATA An error occurred while communicating with the chip.

WFS_ERR_PIN_PROTOCOLNOTSUPP The specified protocol is not supported by the service provider.

WFS_ERR_PIN_NOPIN PIN has not been entered or has been cleared.

WFS_ERR_PIN_ACCESSDENIED The ID card unit is not ready for PIN presentation or for any vendor specific reason. The ID card service provider, if any, may have generated a service event that further describes the reason for that error code.

Events There are no additional events generated by this command.

Comments None.


4.10 WFS_CMD_PIN_GET_PINBLOCK

Description This function takes the account information and a PIN entered by the user to build a formatted PIN. Encrypting this formatted PIN once or twice returns a PIN block which can be written on a magnetic card or sent to a host. The PIN block can be calculated using one of the formats specified in the WFS_INF_PIN_CAPABILITIES command. This command clears the PIN.

Input Param LPWFSPINBLOCK lpPinBlock;

typedef struct _wfs_pin_block
 {
 LPSTR   lpsCustomerData;
 LPSTR   lpsXORData;
 BYTE   bPadding;
 WORD   wFormat;
 LPSTR   lpsKey;
 LPSTR   lpsKeyEncKey;
 } WFSPINBLOCK, * LPWFSPINBLOCK;

lpsCustomerData
Used for ANSI, ISO-0 and ISO-1 algorithm to build the formatted PIN. For ANSI and ISO-0 the PAN (Primary Account Number) is used, for ISO-1 a ten digit transaction field is required. If not used a NULL is required.
Used for DIEBOLD with coordination number, as a two digit coordination number.

lpsXORData
If the formatted PIN is encrypted twice to build the resulting PIN block, this data can be used to modify the result of the first encryption by an XOR-operation.

bPadding
Specifies the padding character.

wFormat
Specifies the format of the PIN block. Possible values are:
(see command WFS_INF_PIN_CAPABILITIES)

lpsKey
Specifies the key used to encrypt the formatted pin for the first time, NULL if no encryption is required.

lpsEncKey
Specifies the key used to format the once encrypted formatted PIN, NULL if no second encryption required.

Output Param LPWFSXDATA lpxPinBlock;

lpxPinBlock
Pointer to the encrypted/decrypted data.

Error Codes The following additional error codes can be generated by this command:

Value Meaning

WFS_ERR_PIN_KEYNOTFOUND The specified key was not found

WFS_ERR_PIN_KEYNOVALUE The specified key is not loaded.

WFS_ERR_PIN_USEVIOLATION The specified use is not supported by this key.

WFS_ERR_PIN_MODENOTSUPPORTED The specified mode is not supported.

WFS_ERR_PIN_ACCESSDENIED The encryption module is either not initialized or not ready for any vendor specific reason.

WFS_ERR_PIN_NOPIN PIN has been cleared.

Events The following additional events can be generated by this command:

Value Meaning

WFS_SRVE_PIN_ILLEGAL_KEY_ACCESS An error occured accessing an encryption key.

Comments None.


4.11 WFS_CMD_PIN_GET_DATA

Description This function is used to return keystrokes entered by the user. It will automatically set the PIN pad to echo characters on the display if there is a display. For each keystroke an execute notification event is sent in order to allow an application to perform the appropriate display action (i.e. when the PIN pad has no integrated display).

If usMaxLen is zero, the service provider does not terminate the command unless the application sets ulTerminateKeys or ulTerminateFDKs. In the event that ulTerminateKeys or ulTerminateFDKs are not set and usMaxLen is zero, the command will not terminate and the application must issue a WFSCancel command.

Input Param LPWFSPINGETDATA lpPinGetData;

typedef struct _wfs_pin_getdata
{
USHORT usMaxLen;
BOOL bAutoEnd;
ULONG ulActiveFDKs;
ULONG ulActiveKeys;
ULONG ulTerminateFDKs;
ULONG ulTerminateKeys;
 } WFSPINGETDATA, * LPWFSPINGETDATA;

usMaxLen
Specifies the maximum number of digits which can be returned to the application in the data buffer.

bAutoEnd
If bAutoEnd is set to true, the service provider terminates the command when the maximum number of digits are entered. Otherwise, the input is terminated by the user using one of the termination keys. When usMaxLen is reached, the service provider will disable all numeric keys. bAutoEnd is ignored when usMaxLen is set to 0.

ulActiveFDKs
Specifies those FDKs which are active during the execution of the command.

ulActiveKeys
Specifies those (other) Function Keys which are active during the execution of the command.

ulTerminateFDKs
Specifies those FDKs which must terminate the execution of the command.

ulTerminateKeys
Specifies those (other) Function Keys which must terminate the execution of the command.

Output Param LPWFSPINDATA lpPinData;

typedef struct _wfs_pin_data
 {
 LPSTR   lpsData;
 WORD   wCompletion;
 } WFSPINDATA, * LPWFSPINDATA

lpsData
Pointer to the data entered by the user. This pointer is set to NULL if usMaxLen is set to 0.

wCompletion
Specifies the reason for completion of the entry. Possible values are:
(see command WFS_CMD_PIN_GET_PIN)

Error Codes The following additional error codes can be generated by this command:

Value Meaning

WFS_ERR_PIN_KEYINVALID At least one of the specified function keys or FDKs is invalid.

WFS_ERR_PIN_KEYNOTSUPPORTED At least one of the specified function keys or FDKs is not supported by the service provider.

WFS_ERR_PIN_NOACTIVEKEYS There are no active function keys specified.

Events The following additional events can be generated by this command:

Value Meaning

WFS_EXEE_PIN_KEY A key has been pressed at the PIN pad.

Comments None.


4.12 WFS_CMD_PIN_INITIALIZATION

Description The encryption module must be initialized before any encryption function can be used. Every initialization destroys all keys that have been loaded or imported. Usually this command is called by an operator task and not by the application program.

Initialization also involves loading “initial” application keys and local vendor dependent keys. These can be supplied, for example, by an operator through a keyboard, a local configuration file or possibly by means of some secure hardware that can be attached to the device. The application “initial” keys would normally get updated by the application during a WFS_EXEC_PIN_IMPORT command as soon as possible. Local vendor dependent static keys (e.g. storage, firmware and offset keys) would normally be transparent to the application and by definition can not be dynamically changed.

Where initial keys are not available immediately when this command is issued (i.e. when operator intervention is required), the Service Provider returns WFS_ERR_PIN_ACCESS_DENIED and the application must await the WFS_SRVE_PIN_INITIALIZED event.

During initialization an optional encrypted ID key can be stored in the HW module. The ID key and the corresponding encryption key can be passed as parameters; if not, they are generated automatically by the encryption module. The encrypted ID is returned to the application and serves as authorization for the key import function. The WFS_INF_PIN_CAPABILITIES command indicates whether or not the device will support this feature.

Input Param LPWFSPININIT lpInit;

typedef struct _wfs_pin_init
 {
 LPWFSXDATA  lpxIdent;
 LPWFSXDATA  lpxKey;
 } WFSPININIT, * LPWFSPININIT;

lpxIdent
Pointer to the value of the ID key. Null if not required.

lpxKey
Pointer to the value of the encryption key. Null if not required.

Output Param LPWFSXDATA lpxIdentification;

lpxIdentification
Pointer to the value of the ID key encrypted by the encryption key. Can be used as authorization for the WFS_CMD_PIN_IMPORT_KEY command, can be NULL if no authorization required.

Error Codes The following additional error codes can be generated by this command:

Value Meaning

WFS_ERR_PIN_ACCESSDENIED The encryption module is either not initialized (or not ready for some vendor specific reason).

WFS_ERR_PIN_INVALIDID The ID passed was not valid.

Events The following additional events can be generated by this command:

Value Meaning

WFS_SRVE_PIN_ILLEGAL_KEY_ACCESS An error occured accessing an encryption key.

WFS_SRVE_PIN_INITIALIZED The encryption module is now initialized.

Comments None.


5.1 WFS_EXEE_PIN_KEY

Description This event specifies that a key has been pressed at the PIN pad. It is used if the device has no internal display unit and the application has to manage the display of the entered digits.

Event Param LPWFSPINKEY lpKey;

typedef struct _wfs_pin_key
 {
 WORD  wCompletion;
 ULONG  ulDigit;
 } WFSPINKEY, * LPWFSPINKEY;

wCompletion
Specifies the reason for completion of the entry. Possible values are:
(see command WFS_CMD_PIN_GET_PIN)

ulDigit
Specifies the digit entered by the user or the replace character when working in encryption mode (WFS_CMD_PIN_GET_PIN). If no digit but a function key has been depressed, the key code is returned in this parameter.

Comments None.


5.2 WFS_SRVE_PIN_INITIALIZED

Description This event specifies that, as a result of a WFS_CMD_PIN_INITIALIZATION, the encryption module is now initialized and the master key (where required) and any other initial keys are loaded; ready to import other keys.

Event Param LPWFSPININIT lpInit;

lpInit
For a definition of WFSPININIT see command WFS_CMD_PIN_INITIALIZATION.

Comments None.


5.3 WFS_SRVE_PIN_ILLEGAL_KEY_ACCESS

Description This event specifies that an error occurred accessing an encryption key. Possible situations for generating this event are the encryption key was not found, had no value, or a use violation.

Event Param LPWFSPINACCESS lpAccess;

typedef struct _wfs_pin_access
 {
 LPSTR  lpsKeyName;
 LONG  lErrorCode;
 } WFSPINACCESS, * LPWFSPINACCESS;

lpsKeyName
Specifies the name of the key that caused the error.

lErrorCode
Specifies the type of illegal key access that occurred. Possible values are:

Value Meaning

WFS_ERR_PIN_KEYNOTFOUND The specified key was not loaded.

WFS_ERR_PIN_KEYNOVALUE The specified key is not loaded.

WFS_ERR_PIN_USEVIOLATION The specified use is not supported by this key.

Comments None.


6. C - Header File

/****************************************************************************
*                                                                           *
*xfspin.h WOSA/XFS - Personal Identification Number Keypad (PIN) definitions*
*                                                                           *
*            Version 2.00  (11/11/96)                                       *
*                                                                           *
****************************************************************************/

#ifndef __INC_XFSPIN__H
#define __INC_XFSPIN__H

#ifdef __cplusplus
extern "C" {
#endif

#include <xfsapi.h>

/*   be aware of alignment   */
#pragma pack(push,1)

/* values of WFSPINCAPS.wClass */

#define WFS_SERVICE_CLASS_PIN             (4)
#define WFS_SERVICE_CLASS_VERSION_PIN     (0x0002) /* Version 2.00 */
#define WFS_SERVICE_CLASS_NAME_PIN        "PIN"

#define PIN_SERVICE_OFFSET                (WFS_SERVICE_CLASS_PIN * 100)

/* PIN Info Commands */

#define WFS_INF_PIN_STATUS                (PIN_SERVICE_OFFSET + 1)
#define WFS_INF_PIN_CAPABILITIES          (PIN_SERVICE_OFFSET + 2)
#define WFS_INF_PIN_KEY_DETAIL            (PIN_SERVICE_OFFSET + 4)
#define WFS_INF_PIN_FUNCKEY_DETAIL        (PIN_SERVICE_OFFSET + 5)

/* PIN Command Verbs */

#define WFS_CMD_PIN_CRYPT                 (PIN_SERVICE_OFFSET + 1)
#define WFS_CMD_PIN_IMPORT_KEY            (PIN_SERVICE_OFFSET + 3)
#define WFS_CMD_PIN_GET_PIN               (PIN_SERVICE_OFFSET + 5)
#define WFS_CMD_PIN_GET_PINBLOCK          (PIN_SERVICE_OFFSET + 7)
#define WFS_CMD_PIN_GET_DATA              (PIN_SERVICE_OFFSET + 8)
#define WFS_CMD_PIN_INITIALIZATION        (PIN_SERVICE_OFFSET + 9)
#define WFS_CMD_PIN_LOCAL_DES             (PIN_SERVICE_OFFSET + 10)
#define WFS_CMD_PIN_LOCAL_EUROCHEQUE      (PIN_SERVICE_OFFSET + 11)
#define WFS_CMD_PIN_LOCAL_VISA            (PIN_SERVICE_OFFSET + 12)
#define WFS_CMD_PIN_CREATE_OFFSET         (PIN_SERVICE_OFFSET + 13)
#define WFS_CMD_PIN_DERIVE_KEY            (PIN_SERVICE_OFFSET + 14)
#define WFS_CMD_PIN_PRESENT_IDC           (PIN_SERVICE_OFFSET + 15)

/* PIN Messages */

#define WFS_EXEE_PIN_KEY                  (PIN_SERVICE_OFFSET + 1)
#define WFS_SRVE_PIN_INITIALIZED          (PIN_SERVICE_OFFSET + 2)
#define WFS_SRVE_PIN_ILLEGAL_KEY_ACCESS   (PIN_SERVICE_OFFSET + 3)

/* values of WFSPINSTATUS.fwDevice */

#define WFS_PIN_DEVONLINE                 WFS_STAT_DEVONLINE
#define WFS_PIN_DEVOFFLINE                WFS_STAT_DEVOFFLINE
#define WFS_PIN_DEVPOWEROFF               WFS_STAT_DEVPOWEROFF
#define WFS_PIN_DEVBUSY                   WFS_STAT_DEVBUSY
#define WFS_PIN_DEVNODEVICE               WFS_STAT_DEVNODEVICE
#define WFS_PIN_DEVHWERROR                WFS_STAT_DEVHWERROR
#define WFS_PIN_DEVUSERERROR              WFS_STAT_DEVUSERERROR

/* values of WFSPINSTATUS.fwEncStat */

#define WFS_PIN_ENCREADY                  (0)
#define WFS_PIN_ENCNOTREADY               (1)
#define WFS_PIN_ENCNOTINITIALIZED         (2)
#define WFS_PIN_ENCBUSY                   (3)
#define WFS_PIN_ENCUNDEFINED              (4)
#define WFS_PIN_ENCINITIALIZED            (5)

/* values of WFSPINCAPS.wType */

#define WFS_PIN_TYPEEPP                   (0x0001)
#define WFS_PIN_TYPEEDM                   (0x0002)

/* values of WFSPINCAPS.fwAlgorithms, WFSPINCRYPT.wAlgorithm */

#define WFS_PIN_CRYPTDESECB               (0x0001)
#define WFS_PIN_CRYPTDESCBC               (0x0002)
#define WFS_PIN_CRYPTDESCFB               (0x0004)
#define WFS_PIN_CRYPTRSA                  (0x0008)
#define WFS_PIN_CRYPTECMA                 (0x0010)
#define WFS_PIN_CRYPTDESMAC               (0x0020)
#define WFS_PIN_CRYPTTRIDESECB            (0x0040)
#define WFS_PIN_CRYPTTRIDESCBC            (0x0080)
#define WFS_PIN_CRYPTTRIDESCFB            (0x0100)
#define WFS_PIN_CRYPTTRIDESMAC            (0x0200)

/* values of WFSPINCAPS.fwPinFormats */

#define WFS_PIN_FORM3624                  (0x0001)
#define WFS_PIN_FORMANSI                  (0x0002)
#define WFS_PIN_FORMISO0                  (0x0004)
#define WFS_PIN_FORMISO1                  (0x0008)
#define WFS_PIN_FORMECI2                  (0x0010)
#define WFS_PIN_FORMECI3                  (0x0020)
#define WFS_PIN_FORMVISA                  WFS_PIN_FORMECI3
#define WFS_PIN_FORMDIEBOLD               (0x0080)
#define WFS_PIN_FORMDIEBOLDCO             (0x0100)

/* values of WFSPINCAPS.fwDerivationAlgorithms */

#define WFS_PIN_CHIP_ZKA                  (0x0001)

/* values of WFSPINCAPS.fwPresentationAlgorithms */

#define WFS_PIN_PRESENT_CLEAR             (0x0001)

/* values of WFSPINCAPS.fwDisplay */

#define WFS_PIN_DISPNONE                  (1)
#define WFS_PIN_DISPLEDTHROUGH            (2)
#define WFS_PIN_DISPDISPLAY               (3)

/* values of WFSPINCAPS.fwIDKey */

#define WFS_PIN_IDKEYINITIALIZATION       (0x0001)
#define WFS_PIN_IDKEYIMPORT               (0x0002)

/* values of WFSPINCAPS.fwValidationAlgorithms */

#define WFS_PIN_DES                       (0x0001)
#define WFS_PIN_EUROCHEQUE                (0x0002)
#define WFS_PIN_VISA                      (0x0004)
#define WFS_PIN_DES_OFFSET                (0x0008)

/* values of WFSPINKEYDETAIL.fwUse */

#define WFS_PIN_USECRYPT                  (0x0001)
#define WFS_PIN_USEFUNCTION               (0x0002)
#define WFS_PIN_USEMACING                 (0x0004)
#define WFS_PIN_USEKEYENCKEY              (0x0020)
#define WFS_PIN_USENODUPLICATE            (0x0040)
#define WFS_PIN_USESVENCKEY               (0x0080)

/* values of WFSPINFUNCKEYDETAIL.ulFuncMask */

#define WFS_PIN_FK_0                      (0x00000001)
#define WFS_PIN_FK_1                      (0x00000002)
#define WFS_PIN_FK_2                      (0x00000004)
#define WFS_PIN_FK_3                      (0x00000008)
#define WFS_PIN_FK_4                      (0x00000010)
#define WFS_PIN_FK_5                      (0x00000020)
#define WFS_PIN_FK_6                      (0x00000040)
#define WFS_PIN_FK_7                      (0x00000080)
#define WFS_PIN_FK_8                      (0x00000100)
#define WFS_PIN_FK_9                      (0x00000200)
#define WFS_PIN_FK_ENTER                  (0x00000400)
#define WFS_PIN_FK_CANCEL                 (0x00000800)
#define WFS_PIN_FK_CLEAR                  (0x00001000)
#define WFS_PIN_FK_BACKSPACE              (0x00002000)
#define WFS_PIN_FK_HELP                   (0x00004000)
#define WFS_PIN_FK_DECPOINT               (0x00008000)
#define WFS_PIN_FK_00                     (0x00010000)
#define WFS_PIN_FK_000                    (0x00020000)
#define WFS_PIN_FK_RES1                   (0x00040000)
#define WFS_PIN_FK_RES2                   (0x00080000)
#define WFS_PIN_FK_RES3                   (0x00100000)
#define WFS_PIN_FK_RES4                   (0x00200000)
#define WFS_PIN_FK_RES5                   (0x00400000)
#define WFS_PIN_FK_RES6                   (0x00800000)
#define WFS_PIN_FK_RES7                   (0x01000000)
#define WFS_PIN_FK_RES8                   (0x02000000)
#define WFS_PIN_FK_OEM1                   (0x04000000)
#define WFS_PIN_FK_OEM2                   (0x08000000)
#define WFS_PIN_FK_OEM3                   (0x10000000)
#define WFS_PIN_FK_OEM4                   (0x20000000)
#define WFS_PIN_FK_OEM5                   (0x40000000)
#define WFS_PIN_FK_OEM6                   (0x80000000)

/* values of WFSPINFUNCKEY.ulFDK */

#define WFS_PIN_FK_FDK01                  (0x00000001)
#define WFS_PIN_FK_FDK02                  (0x00000002)
#define WFS_PIN_FK_FDK03                  (0x00000004)
#define WFS_PIN_FK_FDK04                  (0x00000008)
#define WFS_PIN_FK_FDK05                  (0x00000010)
#define WFS_PIN_FK_FDK06                  (0x00000020)
#define WFS_PIN_FK_FDK07                  (0x00000040)
#define WFS_PIN_FK_FDK08                  (0x00000080)
#define WFS_PIN_FK_FDK09                  (0x00000100)
#define WFS_PIN_FK_FDK10                  (0x00000200)
#define WFS_PIN_FK_FDK11                  (0x00000400)
#define WFS_PIN_FK_FDK12                  (0x00000800)
#define WFS_PIN_FK_FDK13                  (0x00001000)
#define WFS_PIN_FK_FDK14                  (0x00002000)
#define WFS_PIN_FK_FDK15                  (0x00004000)
#define WFS_PIN_FK_FDK16                  (0x00008000)
#define WFS_PIN_FK_FDK17                  (0x00010000)
#define WFS_PIN_FK_FDK18                  (0x00020000)
#define WFS_PIN_FK_FDK19                  (0x00040000)
#define WFS_PIN_FK_FDK20                  (0x00080000)
#define WFS_PIN_FK_FDK21                  (0x00100000)
#define WFS_PIN_FK_FDK22                  (0x00200000)
#define WFS_PIN_FK_FDK23                  (0x00400000)
#define WFS_PIN_FK_FDK24                  (0x00800000)
#define WFS_PIN_FK_FDK25                  (0x01000000)
#define WFS_PIN_FK_FDK26                  (0x02000000)
#define WFS_PIN_FK_FDK27                  (0x04000000)
#define WFS_PIN_FK_FDK28                  (0x08000000)
#define WFS_PIN_FK_FDK29                  (0x10000000)
#define WFS_PIN_FK_FDK30                  (0x20000000)
#define WFS_PIN_FK_FDK31                  (0x40000000)
#define WFS_PIN_FK_FDK32                  (0x80000000)

/* values of WFSPINCRYPT.wMode */

#define WFS_PIN_MODEENCRYPT               (1)
#define WFS_PIN_MODEDECRYPT               (2)

/* values of WFSPINENTRY.wCompletion */

#define WFS_PIN_COMPAUTO                  (0)
#define WFS_PIN_COMPENTER                 (1)
#define WFS_PIN_COMPCANCEL                (2)
#define WFS_PIN_COMPCONTINUE              (6)
#define WFS_PIN_COMPCLEAR                 (7)
#define WFS_PIN_COMPBACKSPACE             (8)
#define WFS_PIN_COMPFDK                   (9)
#define WFS_PIN_COMPHELP                  (10)
#define WFS_PIN_COMPFK                    (11)

/* WOSA/XFS PIN Errors */

#define WFS_ERR_PIN_KEYNOTFOUND           (-(PIN_SERVICE_OFFSET + 0))
#define WFS_ERR_PIN_MODENOTSUPPORTED      (-(PIN_SERVICE_OFFSET + 1))
#define WFS_ERR_PIN_ACCESSDENIED          (-(PIN_SERVICE_OFFSET + 2))
#define WFS_ERR_PIN_INVALIDID             (-(PIN_SERVICE_OFFSET + 3))
#define WFS_ERR_PIN_DUPLICATEKEY          (-(PIN_SERVICE_OFFSET + 4))
#define WFS_ERR_PIN_KEYNOVALUE            (-(PIN_SERVICE_OFFSET + 6))
#define WFS_ERR_PIN_USEVIOLATION          (-(PIN_SERVICE_OFFSET + 7))
#define WFS_ERR_PIN_NOPIN                 (-(PIN_SERVICE_OFFSET + 8))
#define WFS_ERR_PIN_INVALIDKEYLENGTH      (-(PIN_SERVICE_OFFSET + 9))
#define WFS_ERR_PIN_KEYINVALID            (-(PIN_SERVICE_OFFSET + 10))
#define WFS_ERR_PIN_KEYNOTSUPPORTED       (-(PIN_SERVICE_OFFSET + 11))
#define WFS_ERR_PIN_NOACTIVEKEYS          (-(PIN_SERVICE_OFFSET + 12))
#define WFS_ERR_PIN_INVALIDKEY            (-(PIN_SERVICE_OFFSET + 13))
#define WFS_ERR_PIN_NOTERMINATEKEYS       (-(PIN_SERVICE_OFFSET + 14))
#define WFS_ERR_PIN_MINIMUMLENGTH         (-(PIN_SERVICE_OFFSET + 15))
#define WFS_ERR_PIN_PROTOCOLNOTSUPP       (-(PIN_SERVICE_OFFSET + 16))
#define WFS_ERR_PIN_INVALIDDATA           (-(PIN_SERVICE_OFFSET + 17))
#define WFS_ERR_PIN_NOTALLOWED            (-(PIN_SERVICE_OFFSET + 18))

/*=================================================================*/
/* PIN Info Command Structures and variables */
/*=================================================================*/

typedef struct _wfs_pin_status
{
    WORD                fwDevice;
    WORD                fwEncStat;
    LPSTR               lpszExtra;
} WFSPINSTATUS, * LPWFSPINSTATUS;

typedef struct _wfs_pin_caps
{
    WORD                wClass;
    WORD                fwType;
    BOOL                bCompound;
    USHORT              usKeyNum;
    WORD                fwAlgorithms;
    WORD                fwPinFormats;
    WORD                fwDerivationAlgorithms;
    WORD                fwPresentationAlgorithms;
    WORD                fwDisplay;
    BOOL                bIDConnect;
    WORD                fwIDKey;
    WORD                fwValidationAlgorithms;
    LPSTR               lpszExtra;
} WFSPINCAPS, * LPWFSPINCAPS;

typedef struct _wfs_pin_key_detail
{
    LPSTR               lpsKeyName;
    WORD                fwUse;
    BOOL                bLoaded;
} WFSPINKEYDETAIL, * LPWFSPINKEYDETAIL;

typedef struct _wfs_pin_fdk
{
    ULONG               ulFDK;
    USHORT              usXPosition;
    USHORT              usYPosition;
} WFSPINFDK, * LPWFSPINFDK;

typedef struct _wfs_pin_func_key_detail
{
    ULONG               ulFuncMask;
    USHORT              usNumberFDKs;
    LPWFSPINFDK       * lppFDKs;
} WFSPINFUNCKEYDETAIL, * LPWFSPINFUNCKEYDETAIL;

/*=================================================================*/
/* PIN Execute Command Structures */
/*=================================================================*/

typedef struct _wfs_hex_data
{
    USHORT              usLength;
    LPBYTE              lpbData;
} WFSXDATA, * LPWFSXDATA;

typedef struct _wfs_pin_crypt
{
    WORD                wMode;
    LPSTR               lpsKey;
    LPWFSXDATA          lpxKeyEncKey;
    WORD                wAlgorithm;
    LPSTR               lpsStartValueKey;
    LPWFSXDATA          lpxStartValue;
    BYTE                bPadding;
    BYTE                bCompression;
    LPWFSXDATA          lpxCryptData;
} WFSPINCRYPT, * LPWFSPINCRYPT;

typedef struct _wfs_pin_import
{
    LPSTR               lpsKey;
    LPSTR               lpsEncKey;
    LPWFSXDATA          lpxIdent;
    LPWFSXDATA          lpxValue;
    WORD                fwUse;
} WFSPINIMPORT, * LPWFSPINIMPORT;

typedef struct _wfs_pin_derive
{
    WORD                wDerivationAlgorithm;
    LPSTR               lpsKey;
    LPSTR               lpsKeyGenKey;
    LPSTR               lpsStartValueKey;
    LPWFSXDATA          lpxStartValue;
    BYTE                bPadding;
    LPWFSXDATA          lpxInputData;
    LPWFSXDATA          lpxIdent;
 } WFSPINDERIVE, * LPWFSPINDERIVE;

typedef struct _wfs_pin_getpin
{
    USHORT              usMinLen;
    USHORT              usMaxLen;
    BOOL                bAutoEnd;
    CHAR                cEcho;
    ULONG               ulActiveFDKs;
    ULONG               ulActiveKeys;
    ULONG               ulTerminateFDKs;
    ULONG               ulTerminateKeys;
} WFSPINGETPIN, * LPWFSPINGETPIN;

typedef struct _wfs_pin_entry
{
    USHORT              usDigits;
    WORD                wCompletion;
} WFSPINENTRY, * LPWFSPINENTRY;

typedef struct _wfs_pin_local_des
{
    LPSTR               lpsValidationData;
    LPSTR               lpsOffset;
    BYTE                bPadding;
    USHORT              usMaxPIN;
    USHORT              usValDigits;
    BOOL                bNoLeadingZero;
    LPSTR               lpsKey;
    LPWFSXDATA          lpxKeyEncKey;
    LPSTR               lpsDecTable;
} WFSPINLOCALDES, * LPWFSPINLOCALDES;

typedef struct _wfs_pin_create_offset
{
    LPSTR               lpsValidationData;
    BYTE                bPadding;
    USHORT              usMaxPIN;
    USHORT              usValDigits;
    LPSTR               lpsKey;
    LPWFSXDATA          lpxKeyEncKey;
    LPSTR               lpsDecTable;
} WFSPINCREATEOFFSET, * LPWFSPINCREATEOFFSET;

typedef struct _wfs_pin_local_eurocheque
{
    LPSTR               lpsEurochequeData;
    LPSTR               lpsPVV;
    WORD                wFirstEncDigits;
    WORD                wFirstEncOffset;
    WORD                wPVVDigits;
    WORD                wPVVOffset;
    LPSTR               lpsKey;
    LPWFSXDATA          lpxKeyEncKey;
    LPSTR               lpsDecTable;
} WFSPINLOCALEUROCHEQUE, * LPWFSPINLOCALEUROCHEQUE;

typedef struct _wfs_pin_local_visa
{
    LPSTR               lpsPAN;
    LPSTR               lpsPVV;
    WORD                wPVVDigits;
    LPSTR               lpsKey;
    LPWFSXDATA          lpxKeyEncKey;
} WFSPINLOCALVISA, * LPWFSPINLOCALVISA;

typedef struct _wfs_pin_presentidc
{
    WORD                wPresentAlgorithm;
    WORD                wChipProtocol;
    ULONG               ulChipDataLength;
    LPBYTE              lpbChipData;
    LPVOID              lpAlgorithmData;
} WFSPINPRESENTIDC, * LPWFSPINPRESENTIDC;

typedef struct _wfs_pin_present_result
{
    WORD                wChipProtocol;
    ULONG               ulChipDataLength;
    LPBYTE              lpbChipData;
} WFSPINPRESENTRESULT, * LPWFSPINPRESENTRESULT;

typedef struct _wfs_pin_presentclear
{
    ULONG               ulPINPointer;
    USHORT              usPINOffset;
} WFSPINPRESENTCLEAR, * LPWFSPINPRESENTCLEAR;

typedef struct _wfs_pin_block
{
    LPSTR               lpsCustomerData;
    LPSTR               lpsXORData;
    BYTE                bPadding;
    WORD                wFormat;
    LPSTR               lpsKey;
    LPSTR               lpsKeyEncKey;
} WFSPINBLOCK, * LPWFSPINBLOCK;

typedef struct _wfs_pin_getdata
{
    USHORT              usMaxLen;
    BOOL                bAutoEnd;
    ULONG               ulActiveFDKs;
    ULONG               ulActiveKeys;
    ULONG               ulTerminateFDKs;
    ULONG               ulTerminateKeys;
} WFSPINGETDATA, * LPWFSPINGETDATA;

typedef struct _wfs_pin_data
{
    LPSTR               lpsData;
    WORD                wCompletion;
} WFSPINDATA, * LPWFSPINDATA;

typedef struct _wfs_pin_init
{
    LPWFSXDATA          lpxIdent;
    LPWFSXDATA          lpxKey;
} WFSPININIT, * LPWFSPININIT;

/*=================================================================*/
/* PIN Message Structures */
/*=================================================================*/

typedef struct _wfs_pin_key
{
    WORD                wCompletion;
    ULONG               ulDigit;
} WFSPINKEY, * LPWFSPINKEY;

typedef struct _wfs_pin_access
    {
    LPSTR               lpsKeyName;
    LONG                lErrorCode;
    } WFSPINACCESS, * LPWFSPINACCESS;

/* restore alignment */
#pragma pack(pop)

#ifdef __cplusplus
}       /*extern "C"*/
#endif

#endif    /* __INC_XFSPIN__H */


Check Reader/Scanner Device Class Interface

A Client-Server Architecture for Financial Enterprise Computing under Microsoft® Windows

Programmer’s Reference

Revision 1.11

February 3, 1995

Developed by the members of the Banking Solutions Vendor Council

Revision History:
1.0 | May 24, 1993 | Initial release of API and SPI specification
1.01 | June 11, 1993 | Minor updates to BSVC member contact list
1.1 | April 14, 1994 | Major updates and additions
1.11 | February 3, 1995 | Separation of specification into separate documents for API/SPI and service class definitions; with updates

The information in this document was contributed by members of the Banking Solutions Vendor Council and represents its 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. The Banking Solutions Vendor Council makes no warranty, express or implied, with respect to this document.

Microsoft is a registered trademark, and Windows and Windows NT are trademarks of Microsoft Corporation.

Apple and Macintosh are registered trademarks of Apple Computer, Inc.

IBM and NetView are registered trademarks of International Business Machines Corporation.

UNIX is a registered trademark of UNIX Systems Laboratories.


1. Introduction

  • This is Revision 1.11 of the service class specifications for check readers and scanners; part of the Windows Open Services Architecture, Extensions for Financial Services (WOSA/XFS). The other relevant specifications are the overall API/SPI specification and the other four service class specifications (banking printers, magnetic stripe readers/writers, PIN pads and cash dispensers) that have been defined thus far. These specifications are part of the Software Development Kit (SDK), which supplies the components and tools to allow the implementation of compliant applications and services. These specifications are distributed to the financial services community for continuing review and comment, to allow them to provide input to the ongoing enhancement of WOSA/XFS.

  • The members of the Banking Solutions Vendor Council encourage banks and other financial services companies world-wide, as well as their technology suppliers, to get updated information on the status of the project, and to submit comments, questions, and requests for the specification and SDK. This may be done via one of the Council members or on CompuServe—see the WOSA/XFS message section and library in the Windows Extensions forum (“GO WINEXT”). Note that the most recent versions of the WOSA/XFS specifications may be downloaded from this library.

  • The Banking Solutions Vendor Council is accepting applications for affiliate membership; interested parties should contact one of the Council members, post a message in the WOSA/XFS message section on CompuServe, or send email to bsvc@microsoft.com.


1.1 WOSA/XFS Service-Specific Programming

The service classes are defined by their service-specific commands and the associated data structures, error codes, messages, etc. These commands are used to request functions that are specific to one or more classes of service providers, but not all of them, and therefore are not in included in the common API for basic or administration functions.

When a service-specific command is common among two or more classes of service providers, the syntax of the command is as similar as possible across all services, since a major objective of the WOSA Extensions for Financial Services is to standardize command codes and structures for the broadest variety of services. For example, using the WFSExecute function, the commands to read data from various services are as similar as possible to each other in their syntax and data structures.

In general, the specific command set for a service class is defined as the union of the sets of specific capabilities likely to be provided by the developers of the services of that class; thus any particular device will normally support only a subset of the command set defined for the class.

There are three cases in which a service provider may receive a service-specific command that it does not support:

The requested capability is defined for the class of service providers by the WOSA/XFS specification, the particular vendor implementation of that service does not support it, and the unsupported capability is not considered to be fundamental to the service. In this case, the service provider returns a successful completion, but does no operation. An example would be a request from an application to turn on a control indicator on a passbook printer; the service provider recognizes the command, but since the passbook printer it is managing does not include that indicator, the service provider does no operation and returns a successful completion to the application.

The requested capability is defined for the class of service providers by the WOSA/XFS specification, the particular vendor implementation of that service does not support it, and the unsupported capability is considered to be fundamental to the service. In this case, a WFS_ERR_UNSUPP_COMMAND error is returned to the calling application. An example would be a request from an application to a cash dispenser to dispense coins; the service provider recognizes the command but, since the cash dispenser it is managing dispenses only notes, returns this error.

The requested capability is not defined for the class of service providers by the WOSA/XFS specification. In this case, a WFS_ERR_INVALID_COMMAND error is returned to the calling application.

This design allows implementation of applications that can be used with a range of services that provide differing subsets of the functionalities that are defined for their service class. Applications may use the WFSGetInfo and WFSAsyncGetInfo commands to inquire about the capabilities of the service they are about to use, and modify their behavior accordingly, or they may use functions and then deal with WFS_ERR_UNSUPP_COMMAND error returns to make decisions as to how to use the service.


2. Check Readers and Scanners

This specification describes the WOSA/XFS service class of check readers and scanners. Check image scanners are treated as a special case of check readers, i.e., image-enabled instances of the latter. This class includes devices with a range of features, from small hand-held read-only devices through which checks are manually swiped one at a time, to much larger devices (i.e., tabletop) which automatically feed checks by the batch past a reader, an encoder, an endorser, an optional image scanner, to be sorted into one of several pockets. The high end device of this class usually found in bank branches shares many capabilities with the still larger devices usually found only in a bank's central data processing site (i.e., high-speed reader/sorters), but the latter are not explicitly addressed here. The specification of this service class includes definitions of the service-specific commands that can be issued, using the WFSAsyncExecute, WFSExecute, WFSGetInfo and WFSAsyncGetInfo functions.

In the U.S., checks are always encoded in magnetic ink for reading by Magnetic Ink Character Recognition (MICR), and a single font is always used. In Europe some countries use MICR and some use Optical Character Recognition (OCR) character sets, with different fonts, for their checks.

In all countries, typical fields found encoded on a check include the bank ID number and the account number. Part of the processing done by the bank is to also encode the amount on the check, usually done by having an operator enter the handwritten or typewritten face amount on a numeric keypad.


3.1 WFS_INF_CHK_STATUS

Description

This function is used to query the status of the device and the service.

Input Param

None.

Output Param
LPWFSCHKSTATUS
struct _wfs_chk_status
     {
     WORD     fwDevice;
     WORD     fwMedia;
     WORD     fwInk;
     DWORD    dwMode;
     WORD     fwLamp;
     LPSTR    lpszExtra;
     } WFSCHKSTATUS, * LPWFSCHKSTATUS;

fwDevice

Specifies the state of the check reader device as one of:

WFS_CHK_DEVONLINE | Device is online.
WFS_CHK_DEVOFFLINE | Device is offline.
WFS_CHK_DEVPOWEROFF | Device is powered off.
WFS_CHK_DEVNODEVICE | No device is connected.

fwMedia

Specifies the status of the media in the check reader as one of:

WFS_CHK_MEDIANOTPRESENT | No media is inserted in device.
WFS_CHK_MEDIAREQUIRED | Insertion of media required.
WFS_CHK_MEDIAPRESENT | Media inserted in device.
WFS_CHK_MEDIAJAMMED | Media jam in device.

fwInk

Specifies the status of the ink in the check reader as one of:

WFS_CHK_INKFULL | Ink supply in device is full.
WFS_CHK_INKLOW | Ink supply in device is low.
WFS_CHK_INKOUT | Ink supply in device is empty.

dwMode

Specifies the autofeed status of the check reader as one of:

WFS_CHK_MODEMANUAL | Device is in manual mode.
WFS_CHK_MODEAUTOFEED | Device is in autofeed mode.

fwLamp

Specifies the status of the check reader imaging lamp as one of:

WFS_CHK_LAMPOK | The lamp is OK.
WFS_CHK_LAMPFADING | The lamp should be changed.

lpszExtra

Points to a list of vendor-specific, or any other extended information. The information is returned as a series of “key=value” strings so that it is easily extensible by service providers. Each string is null-terminated, with the final string terminating with two null characters.

Error Code

There are no additional error codes generated by this command.

Comments

Applications which require or expect specific information to be present in the lpszExtra parameter may not be device or vendor-independent.


3.2 WFS_INF_CHK_CAPABILITIES

Description

This function is used to request device capability information.

Input Param

None.

Output Param
LPWFSCHKCAPS
typedef struct _wfs_chk_caps
     {
     WORD     wClass;
     WORD     fwType;
     BOOL     bCompound;
     BOOL     fMICR;
     BOOL     fOCR;
     BOOL     fAutoFeed;
     BOOL     fEndorser;
     BOOL     fEncoder;
     WORD     fwStamp;
     WORD     wImageCapture;
     USHORT   nPockets;
     LPSTR    lpszFontNames;
     LPSTR    lpszEncodeNames;
     LPSTR    lpszExtra;
     }  WFSCHKCAPS, * LPWFSCHKCAPS

fwClass

Specifies the logical service; value is WFS_SERVICE_CLASS_CHK.

fwType

Specifies the type of the physical device; only current value is WFS_CHK_TYPECHK.

bCompound

TRUE if the logical device is part of a compound device.

fMICR

Can read MICR on checks.

fOCR

Can read OCR on checks.

fAutoFeed

Has autofeed capability; if FALSE has only manual feed.

fEndorser

A programmable endorser is present.

fEncoder

An encoder is present.

fwStamp

One of:

WFS_CHK_STAMPNONE
WFS_CHK_STAMPFRONT
WFS_CHK_STAMPREAR
WFS_CHK_STAMPBOTH

wImageCapture

Same values as wStamp

nPockets

Number of pockets; if 0 or 1, device has no pockets.

lpszFontNames

The names of the fonts supported for reading; each is terminated with a NULL and the string is terminated with two NULLs.

lpszEncodeNames

The names of the fonts supported for encoding; each is terminated with a NULL and the string is terminated with two NULLs.

lpszExtra

Points to a list of vendor-specific, or any other extended information. The information is returned as a series of “key=value” strings so that it is easily extensible by service providers. Each string is null-terminated, with the final string terminating with two null characters.

Error Code

There are no additional error codes generated by this command.

Comments

The font names are standardized so that applications can check for standard literals, e.g.: CMC7, E13B. Reserved OCR font names are TBD due to numerous local variants. (i.e. OCRA and OCRB are not enough).

Applications which require or expect specific information to be present in the lpszExtra parameter may not be device or vendor-independent.

3.3 WFS_INF_CHK_FORM_LIST

Description

This function is used to retrieve the list of forms available to the service.

Input Param

None.

Output Param
LPSTR          lpszFormList;

lpszFormList

Points to a list of null-terminated form names, with the final name terminating with two null characters.

Error Codes

There are no additional error codes generated by this command.

3.4 WFS_INF_CHK_QUERY_FORM

Description

This function is used to retrieve the details on the definition of a specified form.

Input Param
LPSTR          lpszFormName;

lpszFormName

Specifies the null-terminated name of the form on which to retrieve details.

Output Param
LPWFSFRMHEADER

See section 7.1.4.5 WFS_INF_PTR_QUERY_FORM, for details of this structure.

Error Codes

The following additional error code can be generated by this command:

Value | Meaning
WFS_ERR_CHK _FORMNOTFOUND | The specified form cannot be found.

3.5 WFS_INF_CHK_QUERY_FIELD

Description

This function is used to retrieve details on the definition of a single or all fields on a specified form.

Input Param

LPWFSCHKQUERYFIELD, as defined below.
typedef struct _wfs_chk_query_field
     {
     LPSTR                    lpszFormName;
     LPSTR                    lpszFieldName;
     } WFSCHKQUERYFIELD, * LPWFSCHKQUERYFIELD;

lpszFormName

Points to the null-terminated form name.

lpszFieldName

Points to the null-terminated name of the field about which to retrieve details. If this value is NULL, then retrieve details for all fields on the form.

Output Param
LPWFSFRMFIELD          * lpFields;

See Section 7.1.4.7, WFS_PTR_QUERY_FIELD for details of this structure.

Error Codes

The following additional error codes can be generated by this command:

Value | Meaning
WFS_ERR_CHK _FORMNOTFOUND | The specified form cannot be found.
WFS_ERR_CHK _FIELDNOTFOUND | The specified field cannot be found.


3.2 WFS_INF_CHK_CAPABILITIES

3.3 WFS_INF_CHK_FORM_LIST

Description

This function is used to retrieve the list of forms available to the service.

Input Param

None.

Output Param
LPSTR          lpszFormList;

lpszFormList

Points to a list of null-terminated form names, with the final name terminating with two null characters.

Error Codes

There are no additional error codes generated by this command.


3.2 WFS_INF_CHK_CAPABILITIES

3.4 WFS_INF_CHK_QUERY_FORM

Description

This function is used to retrieve the details on the definition of a specified form.

Input Param
LPSTR          lpszFormName;

lpszFormName

Specifies the null-terminated name of the form on which to retrieve details.

Output Param
LPWFSFRMHEADER

See section 7.1.4.5 WFS_INF_PTR_QUERY_FORM, for details of this structure.

Error Codes

The following additional error code can be generated by this command:

Value | Meaning
WFS_ERR_CHK _FORMNOTFOUND | The specified form cannot be found.


3.2 WFS_INF_CHK_CAPABILITIES

3.5 WFS_INF_CHK_QUERY_FIELD

Description

This function is used to retrieve details on the definition of a single or all fields on a specified form.

Input Param

LPWFSCHKQUERYFIELD, as defined below.
typedef struct _wfs_chk_query_field
     {
     LPSTR                    lpszFormName;
     LPSTR                    lpszFieldName;
     } WFSCHKQUERYFIELD, * LPWFSCHKQUERYFIELD;

lpszFormName

Points to the null-terminated form name.

lpszFieldName

Points to the null-terminated name of the field about which to retrieve details. If this value is NULL, then retrieve details for all fields on the form.

Output Param
LPWFSFRMFIELD          * lpFields;

See Section 7.1.4.7, WFS_PTR_QUERY_FIELD for details of this structure.

Error Codes

The following additional error codes can be generated by this command:

Value | Meaning
WFS_ERR_CHK _FORMNOTFOUND | The specified form cannot be found.
WFS_ERR_CHK _FIELDNOTFOUND | The specified field cannot be found.


4.1 WFS_CMD_CHK_READ_FORM

Description

This function returns the data from the current check. The contents of all the fields within the form are returned to the application. For small hand-held check readers, this command might be the only one used.

Input Param
LPWFSCHKINREADFORM
typedef struct _wfs_chk_in_read_form
     {
     LPSTR     lpszFormName;
     LPSTR     lpszFieldNames;
     DWORD     dwOptions;
     LPSTR     lpszExtra;
     }  WFSCHKINREADFORM, * LPWFSCHKINREADFORM;

lpszFormName

Points to the null-terminated name of the form.

lpszFieldNames

Points to a list of NULL-terminated field names from which to read input data, with the final name terminating with two NULLs.

dwOptions

WFS_CHK_OPTAUTOFEED

lpszExtra

Points to a list of vendor-specific, or any other extended information. The information is returned as a series of “key=value” strings so that it is easily extensible by service providers. Each string is null-terminated, with the final string terminating with two null characters.

Output Param
LPWFSCHKOUTREADFORM
typedef struct _wfs_chk_out_read_form
     {
     WORD      hDoc;
     LPSTR     lpszFields;
     }  WFSCHKOUTREADFORM, * LPWFSCHKOUTREADFORM;

hDoc

Handle to this check.

lpszFields

Points to a list of field data returned. See Comments.

Error Code

The following additional error codes can be generated by this command:

Value | Meaning
WFS_ERR_CHK_REQDFIELDMISSING | The check was blank.
WFS_ERR_CHK_FORMNOTFOUND | Invalid form name.
WFS_ERR_CHK_FIELDSPECFAILURE | The syntax of the lpszFields member is invalid.
WFS_ERR_CHK_INCOMPLETEREAD | Read errors occurred and an incomplete code line is available. Question marks are returned in place of any numbers which could not be read. A code line will always be returned when this error occurs, and the application may choose different behavior depending on the number of question marks returned, e.g., prompt the operator to enter missing numbers.

Execute Events

WFS_EXEE_CHK_NOMEDIA | No check has been inserted in the (manual mode) check reader; to be used by the application to generate a message to the operator to insert a check.
WFS_EXEE_CHK_MEDIAINSERTED | A check was inserted; this is only issued following the above event.

Comments.

At the end of a successful WFS_CMD_CHK_READ_FORM, the string pointed to by lpsFields will contain a sequence such as (given a U.S. personal check):
ROUTETRANS=021203501\0ACCOUNT=370361\0TRANCODE=2199\0AMOUNT=0000001000\0\0

Each fieldname=value pair is terminated by a NULL; the end of the buffer is marked with an additional NULL. Any embedded space characters (0x20) are significant; trailing spaces are not.

The timeout parameter (dwTimeOut) in the WFSExecute request that passes this command should always be large enough to accomodate prompting the operator to insert a check, having the operator do so, and processing the check. If the timeout expires before these operations are completed, the WFSExecute will be canceled, possibly leaving an application-generated prompt on the operator's screen.


4.2 WFS_CMD_CHK_MULTICOMMAND

Description

This function is used to encode the amount field of the check, optionally stamp and endorse the check, and select a pocket to which the check will be sorted if the device supports these capabilities.

Input Param
LPWFSCHKMULTICOMMAND
typedef struct _wfs_in_multicommand
     {
     WORD      hDoc;
     DWORD     dwOptions;
     BYTE    . pocket;
     LPSTR     lpszEncodeFormName;
     LPSTR     lpszEncodeFields;
     LPSTR     lpszEndorserFormName;
     LPSTR     lpszEndorserFields;
     LPSTR     lpszExtra;
     } WFSCHKMULTICOMMAND, * LPWFSCHKMULTICOMMAND;

hDoc

handle to the check to be processed; NULL means "current" check.

dwOptions

Command options, as a combination of the following flags:
WFS_CHK_OPTSTAMPFRONT
WFS_CHK_OPTSTAMPBACK
WFS_CHK_OPTENDORSEFRONT
WFS_CHK_OPTENDORSEBACK
WFS_CHK_OPTSORTONLY
WFS_CHK_OPTTAKEIMAGE

pocket

Ignored if no sorter present.

lpszEncodeFormName

Name of form defining encoder fields.

lpszEncodeFields

List of fieldname/value pairs for encoder.

lpszEndorserFormName

Name of form defining endorser fields.

lpszEndorserFields

List of fieldname/value pairs for endorser.

lpszExtra

Points to a list of vendor-specific, or any other extended information. The information is returned as a series of “key=value” strings so that it is easily extensible by service providers. Each string is null-terminated, with the final string terminating with two null characters.

Output Param

None.

Error Codes

The following additional error codes can be generated by this command:

Value | Meaning
WFS_ERR_CHK _FORMNOTFOUND | Invalid form name.
WFS_ERR_CHK _FIELDNOTFOUND | Invalid field name.
WFS_ERR_CHK _REQDFIELDMISSING | A field required by the form is not supplied.
WFS_ERR_CHK _EXTRAFIELD | A field supplied by the application does not exist in this form (warning).
WFS_ERR_CHK _FIXEDOVERWRITE | The application passed a field which is marked as fixed in the form description (warning).
WFS_ERR_CHK _FIELDSPECFAILURE | The syntax of the lpszFields member is invalid.
WFS_ERR_CHK _UNSUPPORTEDCAP | The service does not have a capability requested in this command (i.e. a pocket sort was requested on a device with zero pockets). This is a warning; the requested capability is ignored.

Execute Events

WFS_EXEE_CHK _NOMEDIA | No check has been inserted in the (manual mode) check reader.
WFS_EXEE_CHK _MEDIAINSERTED | A check was inserted; this is only issued following the above event.

Comments

The contents of the lpszFields parameter is as follows:
fieldname=value\0fieldname=value\0.......fieldname=value\0\0

Each fieldname=value pair is terminated with a NULL; the end of the buffer is marked with an additional NULL.

If an extra field is passed to the command verb a warning message will be returned. If a required field is missing an error message is returned and the form is not printed. Missing optional fields don't cause a problem. Overwriting of a fixed field results in an error and the print operation does not occur.

The lpszEncodeFormName parameter should be the same as the form name used previously to read the encode line with WFS_CMD_CHK_READ_FORM. Results are unpredictable if a different form name is used.


4.3 WFS_CMD_CHK_READ_IMAGE

Description

This function returns image data from the current check in TIFF 6.0 format.

Input Param
LPWFSCHKINREADIMAGE
typedef struct _wfs_in_read_image
     {
     WORD      hDoc;
     DWORD     dwOptions;
     LPSTR     lpszExtra;
     } WFSCHKINREADIMAGE, * LPWFSCHKINREADIMAGE;

hDoc

Handle to the check whose image is to be returned.

DwOptions

[No options have been defined as of this revision.]

lpszExtra

Points to a list of vendor-specific, or any other extended information. The information is returned as a series of “key=value” strings so that it is easily extensible by service providers. Each string is null-terminated, with the final string terminating with two null characters.

Output Param
LPWFSCHKOUTREADIMAGE
struct wfs_out_read_image
     {
     WORD      cbImage;
     LPSTR     lpImage;
     } WFSCHKOUTREADIMAGE, * LPWFSCHKOUTREADIMAGE;

cbImage

Count of bytes of image data.

lpImage

Points to the image data.

Error Code

The following additional error codes can be generated by this command:

Value | Meaning
WFS_ERR_CHK _INVALIDHDOC | hDoc is required but the value input does not correspond to a previously read document.
WFS_ERR_CHK _IMAGENOTAVAIL | The check referred to by hDoc does not have an image available.

Execute Events

None.

Comments.

Applications which require or expect specific information to be present in the lpszExtra parameter may not be device or vendor-independent.


4.4 WFS_CMD_CHK_MODE_SWITCH

Description

This function is used to turn the autofeed mechanism off if it is running, or to turn it on if it is not.

Input Param
struct _wfs_in_mode_switch
     {
          DWORD     dwMode;        #  WFS_CHK_MODEMANUAL
                                   #  WFS_CHK_MODEAUTOFEED
     }

Output Param

None.

Error Codes

The following additional error code can be generated by this command:

Value | Meaning
WFS_ERR_CHK _INVALIDCOMMAND | The device does not support a mode switch.

Execute Events

None.

Comments

None.


5. Pragmatics of using the commands*^

This section discusses how the WFSExecute commands above map to the variety of check readers used in branch banking.

Small hand-held devices which contain only a MICR or an OCR reader, and through which checks are manually swiped, will normally be managed using only the WFS_CMD_CHK_READ_FORM command. Applications written for such devices can make sure that the check readers to which they are configured to attach are suitable by using the WFS_INF_CHK_CAPABILITIES command in WFSGetInfo to make sure that fAutoFeed is FALSE, nPockets is zero, and so on.

Applications written for table-top check readers with autofeed and/or sorting capability should ensure that the services to which they connect have the appropriate capabilities. The error WFS_ERR_UNSUPP_CATEGORY will be returned if the service does not have these capabilities. In many cases, the applications for such devices will have to run on the workstation to which the check reader is directly attached in order that the commands be able to keep up with the track through which the checks are moving.


6. Execute Events, Results, Codes


6.1 WFS_EXEE_CHK_NOMEDIA

Description

This event specifies that the physical check must be inserted into the device in order for the execute command to proceed.

Event Param
LPSTR     lpszUserPrompt;

lpszUserPrompt

Points to a null-terminated string which identifies the prompt string which is configured for the form (the USERPROMPT attribute of the XFSFORM section).

Comments

The application may use the lpszUserPrompt in any manner it sees fit. For example, it might display the string to the operator, along with a message that the check should be inserted.


6.2 WFS_EXEE_CHK_MEDIAINSERTED

Description

This event specifies that the physical check has been inserted into the device.

Event Param

None.

Comments

The application may use this event to, for example, remove a message box from the screen telling the user to insert the next check.


7. Forms Language Usage

This section covers the usage of the forms language to accomodate check readers. The WOSA/XFS forms language is defined in section 7.1.

The forms language contains the FORMAT attribute in the XFSFIELD section. For check readers, the formatstring is used to generate the delimiters for the check fields; its usage is not application-defined. The usage is the same for the check readers service class. For forms intended for use with check readers, the FORMAT attribute is required:

field Amount | FORMAT ":NNNNNNNNNN:"
field AccountNum | FORMAT "0000NNNNNN<"
field RouteTransit | FORMAT ";NNNNNNNNN;"

using punctuation in place of the standard field separators. A capital N means a number to be read and returned. A zero (“0”) means an optional number which, if present, is read and returned. Note that all fields on a check encoder line that have optional numbers should place the zeros on the same end of the format string as an aid to the Service Provider in parsing the code line (for instance, most check readers read the MICR line right to left, so optional numbers should always be on the left side of fields which have them.).

Normally, the format string, which gives the starting delimiter for each field, and the FOLLOWS clause, allow the service to parse the fields from the check's code line. The position attributes are used to specify the minimum and maximum starting locations for each field, so that a misread delimiter character can be detected and the parsing corrected (if the service is sophisticated enough to do this).

If the device supports reading multiple fonts, the FONT attribute of the XFSFIELD section might be significant. The name of the font (e.g. CMC7, E13B, etc), given here, will cause the check reader to use the appropriate font.

For endorsing checks, the field description specifies the “front” or “back” of the check using the SIDE attribute, and position relative to the trailing or (usually) leading edge of the check.


WOSA

(Windowsä Open Services Architecture)

Extensions for Financial Services

A Client-Server Architecture for Financial Enterprise Computing under Microsoft® Windows

Depository Device Class Interface

–––––––––––––––––––––––––––––––––––

Programmer’s Reference

Revision 2.00

November 11, 1996

Developed by the members of the Banking Solutions Vendor Council


Table of Contents

1. Introduction

1.1 WOSA/XFS Service-Specific Programming

2. Depository Unit

3. Info Commands

3.1 WFS_INF_DEP_STATUS

3.2 WFS_INF_DEP_CAPABILITIES

4. Execute Commands

4.1 WFS_CMD_DEP_ENTRY

4.2 WFS_CMD_DEP_DISPENSE

4.3 WFS_CMD_DEP_RETRACT

4.4 WFS_CMD_DEP_CLEAR_TRANSPORT

4.5 WFS_CMD_DEP_RESET_COUNT

5. Events

5.1 WFS_SRVE_DEP_ENVTAKEN

5.2 WFS_EXEE_DEP_ENVDEPOSITED

5.3 WFS_EXEE_DEP_DEPOSITERROR

5.4 WFS_USRE_DEP_DEPTHRESHOLD

5.5 WFS_USRE_DEP_TONERTHRESHOLD

5.6 WFS_USRE_DEP_ENVTHRESHOLD

5.7 WFS_SRVE_DEP_CONTINSERTED

5.8 WFS_SRVE_DEP_CONTREMOVED

6. C-Header file


1.1 WOSA/XFS Service-Specific Programming

The service classes are defined by their service-specific commands and the associated data structures, error codes, messages, etc. These commands are used to request functions that are specific to one or more classes of service providers, but not all of them, and therefore are not included in the common API for basic or administration functions.

When a service-specific command is common among two or more classes of service providers, the syntax of the command is as similar as possible across all services, since a major objective of the WOSA Extensions for Financial Services is to standardize command codes and structures for the broadest variety of services. For example, using the WFSExecute function, the commands to read data from various services are as similar as possible to each other in their syntax and data structures.

In general, the specific command set for a service class is defined as the union of the specific capabilities likely to be provided by the developers of the services of that class; thus any particular device will normally support only a subset of the defined command set.

There are three cases in which a service provider may receive a service-specific command that it does not support:

  • The requested capability is defined for the class of service providers by the WOSA/XFS specification, the particular vendor implementation of that service does not support it, and the unsupported capability is not considered to be fundamental to the service. In this case, the service provider returns a successful completion, but does no operation. An example would be a request from an application to turn on a control indicator on a passbook printer; the service provider recognizes the command, but since the passbook printer it is managing does not include that indicator, the service provider does no operation and returns a successful completion to the application.

  • The requested capability is defined for the class of service providers by the WOSA/XFS specification, the particular vendor implementation of that service does not support it, and the unsupported capability is considered to be fundamental to the service. In this case, a WFS_UNSUPP_COMMAND error is returned to the calling application. An example would be a request from an application to a cash dispenser to dispense coins; the service provider recognizes the command but, since the cash dispenser it is managing dispenses only notes, returns this error.

  • The requested capability is not defined for the class of service providers by the WOSA/XFS specification. In this case, a WFS_ERR_INVALID_COMMAND error is returned to the calling application.

This design allows implementation of applications that can be used with a range of services that provide differing subsets of the functionalities that are defined for their service class. Applications may use the WFSGetInfo and WFSAsyncGetInfo commands to inquire about the capabilities of the service they are about to use, and modify their behavior accordingly, or they may use functions and then deal with WFS_ERR_UNSUPP_COMMAND error returns to make decisions as to how to use the service.


2. Depository Unit

This specification describes the functionality of the services provided by the Depository (DEP) services under WOSA/XFS, by defining the service-specific commands that can be issued, using the WFSGetInfo, WFSAsyncGetInfo, WFSExecute and WFSAsyncExecute functions.

A Depository is used for the acceptance and deposit of media into the device or terminal. There are two main types of depository: an envelope depository for the deposit of media in envelopes and a night safe depository for the deposit of bags containing bulk media.

An envelope depository accepts media, prints on the media and deposits the media into a holding container or bin. Some envelope depositories offer the capability to dispense an envelope to the customer at the start of a transaction. The customer takes this envelope, fills in the deposit media, possibly inscribes it and puts it into the deposit slot. The envelope is then accepted, printed and transported into a deposit container.

The envelope dispense mechanism may be part of the envelope depository device mechanism with the same entry/exit slot or it may be a separate mechanism with separate entry/exit slot.

Envelopes dispensed and not taken by the customer can be retracted back into the device. When the dispenser is a separate mechanism the envelope is retracted back into the dispenser container. When the dispenser is a common mechanism the envelope is retracted into the depository container.

A night safe depository normally only logs the deposit of a bag and does not print on the media.


3.1 WFS_INF_DEP_STATUS

Description This command reports the full range of information available, including the information that is provided by the service provider.

Input Param None.

Output Param LPWFSDEPSTATUS lpStatus;

typedef struct _wfs_dep_status
 {
 WORD   fwDevice;
 WORD   fwDepContainer;
 WORD   fwDepTransport;
 WORD   fwEnvSupply;
 WORD   fwEnvDispenser;
 WORD   fwPrinter;
 WORD   fwToner;
 WORD   fwShutter;
 WORD   wNumOfDeposits;
 LPSTR   lpszExtra;
 } WFSDEPSTATUS, * LPWFSDEPSTATUS;

fwDevice
Specifies the state of the Depository device as one of the following flags:

Value Meaning

WFS_DEP_DEVONLINE The device is on-line. The device is present and operational (i.e. not busy processing a request and does not have a hardware error).

WFS_DEP_DEVOFFLINE The device is off-line. The device is present and powered on but it is not operational (e.g. a switch may have been used to change it to an off-line state).

WFS_DEP_DEVPOWEROFF The device is powered off. The device is present, but is currently powered off.

WFS_DEP_DEVBUSY The device is busy processing a request. The device is present and an EXECUTE request is currently being processed.

WFS_DEP_DEVNODEVICE There is no device connected.

WFS_DEP_DEVHWERROR The device is inoperable due to a hardware error. The device is present but a hardware fault prevents it from being used.

WFS_DEP_DEVUSERERROR The device is present but a person is preventing proper operation. The application should suspend the device operation or remove the device from service until the service provider generates a device state change event indicating the condition of the device has changed i.e. the error is removed (WFS_DEP_DEVONLINE) or a permanent error condition has occurred (WFS_DEP_DEVHWERROR).

fwDepContainer
Specifies the state of the deposit container that contains the deposited envelopes or bags as one of the following flags:

Value Meaning

WFS_DEP_DEPOK The deposit container is in a good state.

WFS_DEP_DEPHIGH The deposit container is almost full (threshold).

WFS_DEP_DEPFULL The deposit container is full.

WFS_DEP_DEPINOP The deposit container is inoperable.

WFS_DEP_DEPMISSING The deposit container is missing.

fwDepTransport
Specifies the state of the deposit transport mechanism that transports the envelope into the deposit container. Specified as one of the following flags:

Value Meaning

WFS_DEP_DEPOK The deposit transport is in a good state.

WFS_DEP_DEPINOP The deposit transport is inoperative due to a hardware failure or media jam.

WFS_DEP_DEPUNKNOWN Due to a hardware error or other condition, the state of the deposit transport cannot be determined.

WFS_DEP_DEPNOTSUPP The physical device has no deposit transport.

fwEnvSupply
Specifies the state of the envelope supply unit as one of the following flags:

Value Meaning

WFS_DEP_ENVOK The envelope supply unit is in a good state (and locked).

WFS_DEP_ENVLOW The envelope supply unit is present but low.

WFS_DEP_ENVEMPTY The envelope supply unit is present but empty. No envelopes can be dispensed.

WFS_DEP_ENVINOP The envelope supply unit is in an inoperable state. No envelopes can be dispensed.

WFS_DEP_ENVMISSING The envelope supply unit is missing.

WFS_DEP_ENVUNLOCKED The envelope supply unit is unlocked

fwEnvDispenser
Specifies the state of the envelope dispenser. Specified as one of the following flags.

Value Meaning

WFS_DEP_ENVOK The envelope dispenser is present and in a good state.

WFS_DEP_ENVINOP The envelope dispenser is present but in an inoperable state. No envelopes can be dispensed.

WFS_DEP_ENVUNKNOWN Due to a hardware error or other condition, the state of the envelope dispenser cannot be determined.

WFS_DEP_ENVNOTSUPP The physical device has no envelope dispenser.

fwPrinter
Specifies the state of the printer. Specified as one of the following flags:

Value Meaning

WFS_DEP_PTROK The printer is present and in a good state.

WFS_DEP_PTRINOP The printer is inoperative.

WFS_DEP_PTRUNKNOWN Due to a hardware error or other condition, the state of the printer cannot be determined.

WFS_DEP_PTRNOTSUPP The physical device has no printer.

fwToner
Specifies the state of the toner (or ink) for the printer. Specified as one of the following flags:

Value Meaning

WFS_DEP_TONOK The toner cassette is full.

WFS_DEP_TONLOW The toner in the printer is low.

WFS_DEP_TONEMPTY The toner in the printer is empty.

WFS_DEP_TONUNKNOWN Due to a hardware error or other condition, the state of the toner for the printer cannot be determined.

WFS_DEP_TONNOTSUPP The physical device has no toner.

fwShutter
Specifies the state of the shutter or door. Specified as one of the following flags:

Value Meaning

WFS_DEP_SHTCLOSED The shutter is closed.

WFS_DEP_SHTOPEN The shutter is opened.

WFS_DEP_SHTJAMMED The shutter is jammed.

WFS_DEP_SHTUNKNOWN Due to a hardware error or other condition, the state of the shutter cannot be determined.

WFS_DEP_SHTNOTSUPP The physical device has no shutter.

wNumOfDeposits
Specifies the number of envelopes or bags in the deposit container. This value is persistent, i.e. maintained through power failures, opens, closes and system resets.

lpszExtra
Specifies a list of vendor-specific, or any other extended, information. The information is returned as a series of "key=value" strings so that it is easily extensible by service providers. Each string will be null-terminated, with the final string terminating with two null characters.

Error Codes There are no additional error codes generated by this command.

Comments Applications which require or expect specific information to be present in the lpszExtra parameter may not be device or vendor-independent.


3.2 WFS_INF_DEP_CAPABILITIES

Description This command is used to retrieve the capabilities of the Depository.

Input Param None.

Output Param LPWFSDEPCAPS lpCaps;

typedef struct _wfs_dep_caps
 {
 WORD   wClass;
 WORD   fwType;
 WORD   fwEnvSupply;
 BOOL   bDepTransport;
 BOOL   bPrinter;
 BOOL   bToner;
 BOOL   bShutter;
 BOOL   bPrintOnRetracts;
 BOOL   bRetractToDeposit;
 WORD   wMaxNumChars;
 LPSTR   lpszExtra;
 } WFSDEPCAPS, * LPWFSDEPCAPS;

wClass
Specifies the logical service class, value is:
WFS_SERVICE_CLASS_DEP

fwType
Specifies the type of the depository device as a combination of the following flags:

Value Meaning

WFS_DEP_TYPEENVELOPE Depository accepts envelopes

WFS_DEP_TYPEBAGDROP Depository accepts bags

fwEnvSupply
Defines what type of Envelope Supply Unit exists as one of the following flags:

Value Meaning

WFS_DEP_ENVMOTORIZED Envelope Supply can dispense envelopes

WFS_DEP_ENVMANUAL Envelope Supply is manual and must be unlocked to allow envelopes to be taken. The Service Event, WFS_SRVE_DEP_ENVTAKEN, can not be sent and the Execute Command, WFS_CMD_DEP_RETRACT can not be supported.

WFS_DEP_ENVNONE No Envelope Supply or Envelope Supply is manual and envelopes can be taken at any time. The Service Event, WFS_SRVE_DEP_ENVTAKEN, can not be sent. and the Execute Command, WFS_CMD_DEP_RETRACT can not be supported.

bDepTransport
Specifies whether a deposit transport mechanism is available and is either TRUE or FALSE.

bPrinter
Specifies whether a printer is available and is either TRUE or FALSE.

bToner
Specifies whether the printer has a toner (or ink) cassette and is either TRUE or FALSE.

bShutter
Specifies whether a deposit transport shutter is available and is either TRUE or FALSE.

bPrintOnRetracts
Specifies whether the device can print on retracted envelopes and is either TRUE or FALSE.

bRetractToDeposit
Specifies whether retracted envelopes are put in the deposit container and is either TRUE or FALSE. If TRUE, envelopes are retracted back to the deposit container. If FALSE, envelopes are retracted back to the envelope dispenser.

wMaxNumChars
Specifies the maximum number of characters that can be printed on the envelope.

lpszExtra
Specifies a list of vendor-specific, or any other extended, information. The information is returned as a series of "key=value" strings so that it is easily extensible by service providers. Each string will be null-terminated, with the final string terminating with two null characters.

Error Codes There are no additional error codes generated by this command.

Comments Applications which require or expect specific information to be present in the lpszExtra parameter may not be device or vendor-independent.


4.1 WFS_CMD_DEP_ENTRY

Description This command starts the entry of an envelope and deposits it into the deposit container. If the envelope entered has an incorrect size and the deposit was not completed, the envelope is returned to the exit slot for removal by the customer. A WFS_SRVE_DEP_ENVTAKEN is sent when the envelope is removed.

If a deposit takes place then this command will report a successful operation and any errors detected during the operation will be returned by the WFS_EXEE_DEP_DEPOSITERROR event.

Input Param LPWFSDEPENVELOPE lpEnvelope;

typedef struct _wfs_dep_envelope
 {
 LPSTR   lpszPrintData;
 } WFSDEPENVELOPE, * LPWFSDEPENVELOPE;

lpszPrintData
Specifies the data that will be printed on the envelope that is entered by the customer.

Output Param None.

Error Codes The following additional error codes can be generated by this command:

Value Meaning

WFS_ERR_DEP_ENVJAMMED An envelope jam occurred in the deposit transport.

WFS_ERR_DEP_DEPFULL The deposit container is full.

WFS_ERR_DEP_CONTMISSING The deposit container is not present.

WFS_ERR_DEP_ENVSIZE The envelope entered has an incorrect size.

WFS_ERR_DEP_PTRFAIL The printer failed.

WFS_ERR_DEP_SHTNOTCLOSED The shutter failed to close.

WFS_ERR_DEP_SHTNOTOPENED The shutter failed to open.

WFS_ERR_DEP_DEPUNKNOWN The result of the deposit is not known. This error code is only returned by the WFS_EXEE_DEP_DEPOSITERROR event.

Events The following additional events can be generated by this command:

Value Meaning

WFS_EXEE_DEP_ENVDEPOSITED The envelope has been deposited in the deposit container.

WFS_EXEE_DEP_DEPOSITERROR An error occured during the deposit operation.

WFS_SRVE_DEP_ENVTAKEN The envelope has been taken by the user.

Comments None.


4.2 WFS_CMD_DEP_DISPENSE

Description This command is used to dispense an envelope from the envelope supply. This command will either action the dispensing of an envelope from the envelope supply or will unlock the envelope supply for manual access.

Input Param None.

Output Param None.

Error Codes The following additional error codes can be generated by this command:

Value Meaning

WFS_ERR_DEP_ENVEMPTY There is no envelope in the envelope unit.

WFS_ERR_DEP_ENVJAMMED An envelope jam occurred in the dispenser transport.

WFS_ERR_DEP_SHTNOTOPENED The shutter failed to open.

Events The following additional events can be generated by this command:

Value Meaning

WFS_SRVE_DEP_ENVTAKEN The envelope has been taken by the user.

Comments None.


4.3 WFS_CMD_DEP_RETRACT

Description This command is used to retract an envelope that was not taken by a customer after an envelope dispense operation. The given string is printed on the envelope and the envelope is retracted into the deposit container or back to the envelope dispenser, depending on the capabilities of the physical device.

Input Param LPWFSDEPENVELOPE lpEnvelope;

typedef struct _wfs_dep_envelope
 {
 LPSTR   lpszPrintData;
 } WFSDEPENVELOPE, * LPWFSDEPENVELOPE;

lpszPrintData
Specifies the data that will be printed on the envelope that is retracted.

Output Param None.

Error Codes The following additional error codes can be generated by this command:

Value Meaning

WFS_ERR_DEP_DEPFULL The deposit container is full.

WFS_ERR_DEP_DEPJAMMED An envelope jam occurred in the deposit transport.

WFS_ERR_DEP_CONTMISSING The deposit container is not present.

WFS_ERR_DEP_ENVJAMMED An envelope jam occurred

WFS_ERR_DEP_NOENV No envelope to retract.

WFS_ERR_DEP_PTRFAIL The printer failed.

WFS_ERR_DEP_SHTNOTCLOSED The shutter failed to close.

Events There are no additional events generated by this command.

Comments None.


4.4 WFS_CMD_DEP_CLEAR_TRANSPORT

Description This command is used to clear the envelope deposit transport from any envelopes or items left in the entry slot of the device. The envelopes can be either captured or completely ejected.

Input Param None.

Output Param None.

Error Codes The following additional error codes can be generated by this command:

Value Meaning

WFS_ERR_DEP_DEPFULL The deposit container is full.

WFS_ERR_DEP_DEPJAMMED An envelope jam occurred in the deposit transport.

WFS_ERR_DEP_CONTMISSING The deposit container is not present.

WFS_ERR_DEP_SHTNOTCLOSED The shutter failed to close.

Events There are no additional events generated by this command.

Comments None.


4.5 WFS_CMD_DEP_RESET_COUNT

Description This command is used to reset the present value for number of envelopes/bags in the deposit container to zero.

Input Param None.

Output Param None.

Error Codes There are no additional error codes returned by this command.

Events There are no additional events generated by this command.

Comments None.


5.1 WFS_SRVE_DEP_ENVTAKEN

Description This service event is used to specify that the envelope has been taken by the customer.

Event Param None.

Comments None.


5.2 WFS_EXEE_DEP_ENVDEPOSITED

Description This execute event is used to specify that the envelope has been deposited in the deposit container.

Event Param None.

Comments None.


5.3 WFS_EXEE_DEP_DEPOSITERROR

Description This execute event is used to specify that an error occurred during the deposit operation. For every error that occurred a single execute event is generated.

Event Param LPLONG lplError;

For a list of possible error conditions see the description of the WFS_CMD_DEP_ENTRY command.

Comments None.


5.4 WFS_USRE_DEP_DEPTHRESHOLD

Description This user event is used to specify that the state of the deposit container reached a threshold.

Event Param LPWORD lpwDepositThreshold;

Specified as one of the following flags:

Value Meaning

WFS_DEP_DEPHIGH The deposit container is almost full (threshold).

WFS_DEP_DEPFULL The deposit container is full.

Comments None.


5.5 WFS_USRE_DEP_TONERTHRESHOLD

Description This user event is used to specify that the state of the toner (or ink) reached a threshold.

Event Param LPWORD lpwTonerThreshold;

Specified as one of the following flags:

Value Meaning

WFS_DEP_TONLOW The toner (or ink) in the printer is low.

WFS_DEP_TONEMPTY The toner (or ink) in the printer is empty.

Comments None.


5.6 WFS_USRE_DEP_ENVTHRESHOLD

Description This user event is used to specify that the state of the envelope supply reached a threshold.

Event Param LPWORD lpwEnvelopeThreshold;

Specified as one of the following flags:

Value Meaning

WFS_DEP_ENVLOW The envelope supply is present but low.

WFS_DEP_ENVEMPTY The envelope supply is present but empty. No envelopes can be dispensed.

Comments None.


5.7 WFS_SRVE_DEP_CONTINSERTED

Description This service event is used to specify that the deposit container has been reinserted into the device.

Event Param None.

Comments None.


5.8 WFS_SRVE_DEP_CONTREMOVED

Description This service event is used to specify that the deposit container has been removed from the device.

Event Param None.

Comments None.


6. C-Header file

/******************************************************************************
*                                                                             *
* xfsdep.h   WOSA/XFS - Depository (DEP) definitions                          *
*                                                                             *
*            Version 2.00  (11/11/96)                                         *
*                                                                             *
*******************************************************************************/

#ifndef __INC_XFSDEP__H
#define __INC_XFSDEP__H

#ifdef __cplusplus
extern "C" {
#endif

#include <xfsapi.h>

/*   be aware of alignment   */
#pragma pack(push,1)

/* values of WFSDEPCAPS.wClass */

#define    WFS_SERVICE_CLASS_DEP             (6)
#define    WFS_SERVICE_CLASS_VERSION_DEP     (0x0002) /* Version 2.00 */
#define    WFS_SERVICE_CLASS_NAME_DEP        “DEP”

#define    DEP_SERVICE_OFFSET           (WFS_SERVICE_CLASS_DEP * 100)

/* DEP Info Commands */

#define    WFS_INF_DEP_STATUS           (DEP_SERVICE_OFFSET + 1)
#define    WFS_INF_DEP_CAPABILITIES     (DEP_SERVICE_OFFSET + 2)

/* DEP Execute Commands */

#define    WFS_CMD_DEP_ENTRY            (DEP_SERVICE_OFFSET + 1)
#define    WFS_CMD_DEP_DISPENSE         (DEP_SERVICE_OFFSET + 2)
#define    WFS_CMD_DEP_RETRACT          (DEP_SERVICE_OFFSET + 3)
#define    WFS_CMD_DEP_CLEAR_TRANSPORT  (DEP_SERVICE_OFFSET + 4)
#define    WFS_CMD_DEP_RESET_COUNT      (DEP_SERVICE_OFFSET + 5)

/* DEP Messages */

#define    WFS_SRVE_DEP_ENVTAKEN        (DEP_SERVICE_OFFSET + 1)
#define    WFS_EXEE_DEP_ENVDEPOSITED    (DEP_SERVICE_OFFSET + 2)
#define    WFS_EXEE_DEP_DEPOSITERROR    (DEP_SERVICE_OFFSET + 3)
#define    WFS_USRE_DEP_DEPTHRESHOLD    (DEP_SERVICE_OFFSET + 4)
#define    WFS_USRE_DEP_TONERTHRESHOLD  (DEP_SERVICE_OFFSET + 5)
#define    WFS_USRE_DEP_ENVTHRESHOLD    (DEP_SERVICE_OFFSET + 6)
#define    WFS_SRVE_DEP_CONTINSERTED    (DEP_SERVICE_OFFSET + 7)
#define    WFS_SRVE_DEP_CONTREMOVED     (DEP_SERVICE_OFFSET + 8)

/* values of WFSDEPSTATUS.fwDevice */
#define    WFS_DEP_DEVONLINE            WFS_STAT_DEVONLINE
#define    WFS_DEP_DEVOFFLINE           WFS_STAT_DEVOFFLINE
#define    WFS_DEP_DEVPOWEROFF          WFS_STAT_DEVPOWEROFF
#define    WFS_DEP_DEVBUSY              WFS_STAT_DEVBUSY
#define    WFS_DEP_DEVNODEVICE          WFS_STAT_DEVNODEVICE
#define    WFS_DEP_DEVHWERROR           WFS_STAT_DEVHWERROR
#define    WFS_DEP_DEVUSERERROR         WFS_STAT_DEVUSERERROR

/* values of WFSDEPSTATUS.fwDepContainer, fwDepTransport */

#define    WFS_DEP_DEPOK                (0)
#define    WFS_DEP_DEPHIGH              (1)
#define    WFS_DEP_DEPFULL              (2)
#define    WFS_DEP_DEPINOP              (3)
#define    WFS_DEP_DEPMISSING           (4)
#define    WFS_DEP_DEPUNKNOWN           (5)
#define    WFS_DEP_DEPNOTSUPP           (6)

/* values of WFSDEPSTATUS.fwEnvSupply, fwEnvDispenser */

#define    WFS_DEP_ENVOK                (0)
#define    WFS_DEP_ENVLOW               (1)
#define    WFS_DEP_ENVEMPTY             (2)
#define    WFS_DEP_ENVINOP              (3)
#define    WFS_DEP_ENVMISSING           (4)
#define    WFS_DEP_ENVUNKNOWN           (5)
#define    WFS_DEP_ENVNOTSUPP           (6)
#define    WFS_DEP_ENVUNLOCKED          (7)

/* values of WFSDEPSTATUS.fwPrinter */

#define    WFS_DEP_PTROK                (0)
#define    WFS_DEP_PTRINOP              (1)
#define    WFS_DEP_PTRUNKNOWN           (2)
#define    WFS_DEP_PTRNOTSUPP           (3)

/* values of WFSDEPSTATUS.fwToner */

#define    WFS_DEP_TONOK                (0)
#define    WFS_DEP_TONLOW               (1)
#define    WFS_DEP_TONEMPTY             (2)
#define    WFS_DEP_TONUNKNOWN           (3)
#define    WFS_DEP_TONNOTSUPP           (4)

/* values of WFSDEPSTATUS.fwShutter */

#define    WFS_DEP_SHTCLOSED            (0)
#define    WFS_DEP_SHTOPEN              (1)
#define    WFS_DEP_SHTJAMMED            (2)
#define    WFS_DEP_SHTUNKNOWN           (3)
#define    WFS_DEP_SHTNOTSUPP           (4)

/* values of WFSDEPCAPS.fwType */

#define    WFS_DEP_TYPEENVELOPE         (1)
#define    WFS_DEP_TYPEBAGDROP          (2)

/* values of WFSDEPCAPS.fwEnvSupply */

#define    WFS_DEP_ENVMOTORIZED         (1)
#define    WFS_DEP_ENVMANUAL            (2)
#define    WFS_DEP_ENVNONE              (3)

#define    WFS_ERR_DEP_DEPFULL          (-(DEP_SERVICE_OFFSET + 0))
#define    WFS_ERR_DEP_DEPJAMMED        (-(DEP_SERVICE_OFFSET + 1))
#define    WFS_ERR_DEP_ENVEMPTY         (-(DEP_SERVICE_OFFSET + 2))
#define    WFS_ERR_DEP_ENVJAMMED        (-(DEP_SERVICE_OFFSET + 3))
#define    WFS_ERR_DEP_ENVSIZE          (-(DEP_SERVICE_OFFSET + 4))
#define    WFS_ERR_DEP_NOENV            (-(DEP_SERVICE_OFFSET + 5))
#define    WFS_ERR_DEP_PTRFAIL          (-(DEP_SERVICE_OFFSET + 6))
#define    WFS_ERR_DEP_SHTNOTCLOSED     (-(DEP_SERVICE_OFFSET + 7))
#define    WFS_ERR_DEP_SHTNOTOPENED     (-(DEP_SERVICE_OFFSET + 8))
#define    WFS_ERR_DEP_CONTMISSING      (-(DEP_SERVICE_OFFSET + 9))
#define    WFS_ERR_DEP_DEPUNKNOWN       (-(DEP_SERVICE_OFFSET + 10))

/*====================================================================*/
/*    DEP Info Command Structures and variables                       */
/*====================================================================*/

typedef struct _wfs_dep_status
{
    WORD        fwDevice;
    WORD        fwDepContainer;
    WORD        fwDepTransport;
    WORD        fwEnvSupply;
    WORD        fwEnvDispenser;
    WORD        fwPrinter;
    WORD        fwToner;
    WORD        fwShutter;
    WORD        wNumOfDeposits;
    LPSTR       lpszExtra;
} WFSDEPSTATUS, * LPWFSDEPSTATUS;

typedef struct _wfs_dep_caps
{
    WORD        wClass;
    WORD        fwType;
    WORD        fwEnvSupply;
    BOOL        bDepTransport;
    BOOL        bPrinter;
    BOOL        bToner;
    BOOL        bShutter;
    BOOL        bPrintOnRetracts;
    BOOL        bRetractToDeposit;
    WORD        wMaxNumChars;
    LPSTR       lpszExtra;
} WFSDEPCAPS, * LPWFSDEPCAPS;

/*====================================================================*/
/*    DEP Execute Command Structures                   */
/*====================================================================*/

typedef struct _wfs_dep_envelope
{
    LPSTR       lpszPrintData;
} WFSDEPENVELOPE, * LPWFSDEPENVELOPE;

/*====================================================================*/
/*    DEP Message Structures                       */
/*====================================================================*/

/*    restore alignment        */
#pragma pack(pop)

#ifdef __cplusplus
}    /*extern "C"*/
#endif

#endif  /* __INC_XFSDEP__H */


Text Terminal Unit

WOSA

(Windowsä Open Services Architecture)

Extensions for Financial Services

A Client-Server Architecture for
Financial Enterprise Computing under Microsoft® Windows

Text Terminal Unit
Device Class Interface

–––––––––––––––––––––––––––––––––––

Programmer’s Reference

Revision 2.00

November 11, 1996

Developed by the members of the Banking Solutions Vendor Council


Table of Contents

1. Introduction

1.1 WOSA/XFS Service-Specific Programming

2. Text Terminal Unit

3. Info Commands

3.1 WFS_INF_TTU_STATUS

3.2 WFS_INF_TTU_CAPABILITIES

3.3 WFS_INF_TTU_FORM_LIST

3.4 WFS_INF_TTU_QUERY_FORM

3.5 WFS_INF_TTU_QUERY_FIELD

4. Execute Commands

4.1 WFS_CMD_TTU_BEEP

4.2 WFS_CMD_TTU_CLEARSCREEN

4.3 WFS_CMD_TTU_DISPLIGHT

4.4 WFS_CMD_TTU_SET_LED

4.5 WFS_CMD_TTU_SET_RESOLUTION

4.6 WFS_CMD_TTU_DISPLAY_FORM

4.7 WFS_CMD_TTU_READ_FORM

4.8 WFS_CMD_TTU_WRITE

4.9 WFS_CMD_TTU_READ

5. Events

6. Form and Field Definitions

6.1 Definition Syntax

6.2 Form Definition

6.3 Field Definition

7. C - Header file


1.1 WOSA/XFS Service-Specific Programming

The service classes are defined by their service-specific commands and the associated data structures, error codes, messages, etc. These commands are used to request functions that are specific to one or more classes of service providers, but not all of them, and therefore are not included in the common API for basic or administration functions.

When a service-specific command is common among two or more classes of service providers, the syntax of the command is as similar as possible across all services, since a major objective of the WOSA Extensions for Financial Services is to standardize function codes and structures for the broadest variety of services. For example, using the WFSExecute function, the commands to read data from various services are as similar as possible to each other in their syntax and data structures.

In general, the specific command set for a service class is defined as a superset of the specific capabilities likely to be provided by the developers of the services of that class; thus any particular device will normally support only a subset of the defined command set.

There are three cases in which a service provider may receive a service-specific command that it does not support:

  • The requested capability is defined for the class of service providers by the WOSA/XFS specification, the particular vendor implementation of that service does not support it, and the unsupported capability is not considered to be fundamental to the service. In this case, the service provider returns a successful completion, but does no operation. An example would be a request from an application to turn on a control indicator on a passbook printer; the service provider recognizes the command, but since the passbook printer it is managing does not include that indicator, the service provider does no operation and returns a successful completion to the application.

  • The requested capability is defined for the class of service providers by the WOSA/XFS specification, the particular vendor implementation of that service does not support it, and the unsupported capability is considered to be fundamental to the service. In this case, a WFS_ERR_UNSUPP_COMMAND error is returned to the calling application. An example would be a request from an application to a cash dispenser to dispense coins; the service provider recognizes the command but, since the cash dispenser it is managing dispenses only notes, returns this error.

  • The requested capability is not defined for the class of service providers by the WOSA/XFS specification. In this case, a WFS_ERR_INVALID_COMMAND error is returned to the calling application.

This design allows implementation of applications that can be used with a range of services that provide differing subsets of the functionalities that are defined for their service class. Applications may use the WFSGetInfo and WFSAsyncGetInfo commands to inquire about the capabilities of the service they are about to use, and modify their behavior accordingly, or they may use functions and then deal with WFS_ERR_UNSUPP_COMMAND error returns to make decisions as to how to use the service.


2. Text Terminal Unit

This specification describes the functionality of the services provided by text terminal unit (TTU) services under WOSA/XFS, by defining the service-specific commands that can be issued, using the WFSGetInfo, WFSAsyncGetInfo, WFSExecute and WFSAsyncExecute functions.

This section describes the functions provided by a generic Text Terminal Unit (TTU) service. A Text Terminal Unit is a text i/o device, which applies both to ATM operator panels and to displays incorporated in devices such as PIN pads and printers. This service allows for the following categories of functions:

  • Forms oriented input and output

  • Direct display output

  • Keyboard input

  • LED settings and control


3.1 WFS_INF_TTU_STATUS

Description This command reports the full range of information available, including the information that is provided by the service provider.

Input Param None.

Output Param LPWFSTTUSTATUS lpStatus;

typedef struct _wfs_ttu_status
 {
 WORD   fwDevice;
 WORD   wKeyboard;
 WORD   wKeyLock;
 WORD   wLEDs [WFS_TTU_LEDS_MAX];
 WORD   wDisplaySizeX;
 WORD   wDisplaySizeY;
 LPSTR   lpszExtra;
 } WFSTTUSTATUS, * LPWFSTTUSTATUS;

fwDevice
Specifies the state of the text terminal unit as one of the following flags:

Value Meaning

WFS_TTU_DEVONLINE The device is on-line. The device is present and operational (i.e. not busy processing a request and not having a hardware error).

WFS_TTU_DEVOFFLINE The device is off-line. The device is present and powered on but it is not operational (e.g. a switch may have been used to change it to an off-line state).

WFS_TTU_DEVPOWEROFF The device is powered off. The device is present, but is currently powered off.

WFS_TTU_DEVBUSY The device is busy processing a request. The device is present and an EXECUTE request is currently being processed.

WFS_TTU_DEVNODEVICE There is no device connected.

WFS_TTU_DEVHWERROR The device is inoperable due to a hardware error. The device is present but a hardware fault prevents it from being used.

WFS_TTU_DEVUSERERROR The device is present but a person is preventing proper operation. The application should suspend the device operation or remove the device from service until the service provider generates a device state change event indicating the condition of the device has changed i.e. the error is removed (WFS_TTU_DEVONLINE) or a permanent error condition has occurred (WFS_TTU_DEVHWERROR).

wKeyboard
Specifies the state of the keyboard in the text terminal unit as one of the following flags:

Value Meaning

WFS_TTU_KBDON The keyboard is activated.

WFS_TTU_KBDOFF The keyboard is not activated.

WFS_TTU_KBDNA The keyboard is not available.

wKeyLock
Specifies the state of the keyboard lock of the text terminal unit as one of the following flags:

Value Meaning

WFS_TTU_KBDLOCKON The keyboard lock switch is activated.

WFS_TTU_KBDLOCKOFF The keyboard lock switch is not activated.

WFS_TTU_KBDLOCKNA The keyboard lock switch is not available.

wLEDs [WFS_TTU_LEDS_MAX]
Specifies the state of the LEDs. The maximum guidance light index is WFS_TTU_LEDS_MAX. The number of available LEDs can be retrieved with the WFS_INF_TTU_CAPABILITIES info command. All member elements in this array are specified as one of the following flags:

Value Meaning

WFS_TTU_LEDNA The status is not available.

WFS_TTU_LEDOFF The LED is turned off.

WFS_TTU_LEDSLOWFLASH The LED is blinking slowly.

WFS_TTU_LEDMEDIUMFLASH The LED is blinking medium frequency.

WFS_TTU_LEDQUICKFLASH The LED is blinking quickly.

WFS_TTU_LEDCONTINUOUS The light is turned on continuous (steady).

wDisplaySizeX
Specifies the horizontal size of the display of the text terminal unit (the number of columns that can be displayed).

wDisplaySizeY
Specifies the vertical size of the display of the text terminal unit (the number of rows that can be displayed).

lpszExtra
Specifies a list of vendor-specific, or any other extended, information. The information is returned as a series of "key=value" strings so that it is easily extensible by service providers. Each string will be null-terminated, with the final string terminating with two null characters.

Error Codes There are no additional error codes generated by this command.

Comments Applications which require or expect specific information to be present in the lpszExtra parameter may not be device or vendor-independent.


3.2 WFS_INF_TTU_CAPABILITIES

Description This command is used to retrieve the capabilities of the text terminal unit.

Input Param None.

Output Param LPWFSTTUCAPS lpCaps;

typedef struct _wfs_ttu_caps
 {
 WORD      wClass;
 WORD      fwType;
 LPWFSTTURESOLUTION * lppResolutions;
 WORD      wNumOfLEDs;
 WORD      fwKeys;
 BOOL      bKeyLock;
 BOOL      bDisplayLight;
 BOOL      bCursor;
 BOOL      bForms;
 LPSTR      lpszExtra;
 } WFSTTUCAPS, * LPWFSTTUCAPS;

wClass
Specifies the logical service class, value is:
WFS_SERVICE_CLASS_TTU

fwType
Specifies the type of the text terminal unit as one of the following flags:

Value Meaning

WFS_TTU_FIXED The text terminal unit is a fixed device.

WFS_TTU_REMOVABLE The text terminal unit is a removable device.

lppResolutions
Pointer to a NULL terminated array of pointers WFSTTURESOLUTION structures. Specifies the resolutions supported by the physical display device. (For a definition of WFSTTURESOLUTION see command WFS_CMD_TTU_SET_RESOLUTION).

wNumOfLEDs
Specifies the number of LEDs available in this text terminal unit.

fwKeys
Specifies which types of keys the key pad of the text terminal unit supports as a combination of the following flags:

Value Meaning

WFS_TTU_KEYNUMERIC The text terminal unit has keys for numeric values.

WFS_TTU_KEYHEXADECIMAL The text terminal unit has keys for hexadecimal values.

WFS_TTU_KEYALPHANUMERIC The text terminal unit has keys for alphanumeric values.

bKeyLock
Specifies whether the text terminal unit has a key lock switch. The value can be either FALSE (not available) or TRUE (available).

bDisplayLight
Specifies whether the text terminal unit has a display light. The value can be either FALSE (not available) or TRUE (available).

bCursor
Specifies whether the text terminal unit display supports a cursor. The value can be either FALSE (not available) or TRUE (available).

bForms
Specifies whether the text terminal unit service supports forms oriented input and output. The value can be either FALSE (not available) or TRUE (available).

lpszExtra
Specifies a list of vendor-specific, or any other extended, information. The information is returned as a series of "key=value" strings so that it is easily extensible by service providers. Each string will be null-terminated, with the final string terminating with two null characters.

Error Codes There are no additional error codes generated by this command.

Comments Applications which require or expect specific information to be present in the lpszExtra parameter may not be device or vendor-independent.


3.3 WFS_INF_TTU_FORM_LIST

Description This command is used to retrieve the list of forms available on the device.

Input Param None.

Output Param LPSTR lpszFormList;

lpszFormList
Pointer to a list of null-terminated form names, with the final name terminating with two null characters.

Error Codes There are no additional error codes generated by this command.

Comments None.


3.4 WFS_INF_TTU_QUERY_FORM

Description This command is used to retrieve details of the definition of a specified form.

Input Param LPSTR lpszFormName;

lpszFormName
Points to the null-terminated form name on which to retrieve details.

Output Param LPWFSTTUFRMHEADER lpFrmHeader;

typedef struct _wfs_ttu_frm_header
 {
 LPSTR lpszFormName;
 WORD wWidth;
 WORD wHeight;
 WORD wVersionMajor;
 WORD wVersionMinor;
 LPSTR lpszFields;
 } WFSTTUFRMHEADER, * LPWFSTTUFRMHEADER;

lpszFormName
Specifies the null-terminated name of the form.

wWidth
Specifies the width of the form in columns.

wHeight
Specifies the height of the form in rows.

wVersionMajor
Specifies the major version of the form.

wVersionMinor
Specifies the minor version of the form.

lpszFields
Pointer to a list of null-terminated field names, with the final name terminating with two null characters.

Error Codes The following additional error codes can be generated by this command:

Value Meaning

WFS_ERR_TTU_FORMNOTFOUND The specified form cannot be found.

WFS_ERR_TTU_FORMINVALID The specified form is invalid.

Comments None.


3.5 WFS_INF_TTU_QUERY_FIELD

Description This command is used to retrieve details of the definition of a single or all fields on a specified form.

Input Param LPWFSTTUQUERYFIELD lpQueryField;

typedef struct _wfs_ttu_query_field
 {
 LPSTR    lpszFormName;
 LPSTR    lpszFieldName;
 } WFSTTUQUERYFIELD, * LPWFSTTUQUERYFIELD;

lpszFormName
Pointer to the null-terminated form name.

lpszFieldName
Pointer to the null-terminated name of the field about which to retrieve details. If this value is NULL, then retrieve details for all fields on the form.

Output Param LPWFSTTUFRMFIELD * lppFields;

lppFields
Pointer to a null-terminated array of pointers to field definition structures:

typedef struct _wfs_ttu_frm_field
 {
 LPSTR  lpszFieldName;
 WORD  fwType;
 WORD  fwClass;
 WORD  fwAccess;
 WORD  fwOverflow;
 LPSTR  lpszFormat;
 } WFSTTUFRMFIELD, * LPWFSTTUFRMFIELD;

lpszFieldName
Pointer to the null-terminated field name.

fwType
Specifies the type of field and can be one of the following:

Value Meaning

WFS_TTU_FIELDTEXT A text field.

WFS_TTU_FIELDINVISIBLE An invisible text field.

WFS_TTU_FIELDPASSWORD A password field, input is echoed as ‘*’.

fwClass
Specifies the class of the field and can be one of the following:

Value Meaning

WFS_TTU_CLASSSTATIC The field data cannot be set by the application.

WFS_TTU_CLASSOPTIONAL The field data can be set by the application.

WFS_TTU_CLASSREQUIRED The field data must be set by the application.

fwAccess
Specifies whether the field is to be used for input, output, or both and can be a combination of the following bit-flags:

Value Meaning

WFS_TTU_ACCESSREAD The field is used for input from the physical device.

WFS_TTU_ACCESSWRITE The field is used for output to the physical device.

fwOverflow
Specifies how an overflow of field data should be handled and can be one of the following:

Value Meaning

WFS_TTU_OVFTERMINATE Return an error and terminate display of the form.

WFS_TTU_OVFTRUNCATE Truncate the field data to fit in the field.

WFS_TTU_OVFOVERWRITE Print the field data beyond the extents of the field boundary.

Error Codes The following additional error codes can be generated by this command:

Value Meaning

WFS_ERR_TTU_FORMNOTFOUND The specified form cannot be found.

WFS_ERR_TTU_FORMINVALID The specified form is invalid.

WFS_ERR_TTU_FIELDNOTFOUND The specified field cannot be found.

WFS_ERR_TTU_FIELDINVALID The specified field is invalid.

Comments None.


4.1 WFS_CMD_TTU_BEEP

Description This command is used to beep at the text terminal unit.

Input Param LPWORD lpwBeep;

lpwBeep
Specifies whether the beeper should be turned on or off. Specified as one of the following flags of type A and B, or as WFS_TTU_BEEPCONTINUOUS in combination with one of the flags of type B:

Value Meaning Type

WFS_TTU_BEEPOFF | The beeper is turned off. | A
WFS_TTU_BEEPKEYPRESS | The beeper sounds a key click signal. | B
WFS_TTU_BEEPEXCLAMATION | The beeper sounds a exclamation signal. | B
WFS_TTU_BEEPWARNING | The beeper sounds a warning signal. | B
WFS_TTU_BEEPERROR | The beeper sounds a error signal. | B
WFS_TTU_BEEPCRITICAL | The beeper sounds a critical error signal. | B
WFS_TTU_BEEPCONTINUOUS | The beeper sound is turned on continuously. | C

Output Param None.

Error Codes There are no additional error codes generated by this command.

Events There are no additional events generated by this command.

Comments None.


4.2 WFS_CMD_TTU_CLEARSCREEN

Description This command clears the specified area of the text terminal unit screen. The cursor is positioned to the upper left corner of the cleared area.

Input Param LPWFSTTUCLEARSCREEN lpClearScreen;

struct _wfs_ttu_clear_screen
 {
 WORD   wPositionX;
 WORD   wPositionY;
 WORD   wWidth;
 WORD   wHeight;
 } WFSTTUCLEARSCREEN, * LPWFSTTUCLEARSCREEN;

wPositionX
Specifies the horizontal position of the area to be cleared.

wPositionY
Specifies the vertical position of the area to be cleared.

wWidth
Specifies the width of the area to be cleared.

wHeight
Specifies the height of the area to be cleared.

Output Param None.

Error Codes There are no additional error codes generated by this command.

Events There are no additional events generated by this command.

Comments If the input parameter is NULL, the whole screen will be cleared.


4.3 WFS_CMD_TTU_DISPLIGHT

Description This command is used to switch the lighting of the text terminal unit on or off.

Input Param LPWFSTTUDISPLIGHT lpDispLight;

typedef struct _wfs_ttu_disp_light
 {
 BOOL  bMode;
 } WFSTTUDISPLIGHT, * LPWFSTTUDISPLIGHT;

bMode
Specifies whether the lighting of the text terminal unit is switched on (TRUE) or off (FALSE).

Output Param None.

Error Codes There are no additional error codes generated by this command.

Events There are no additional events generated by this command.

Comments None.


4.4 WFS_CMD_TTU_SET_LED

Description This command is used to set the status of the LEDs.

Input Param LPWFSTTUSETLEDS lpSetLEDs;

typedef struct _wfs_ttu_set_leds
 {
 WORD   wLED;
 WORD   fwCommand;
 } WFSTTUSETLEDS, * LPWFSTTUSETLEDS;

wLED
Specifies the index of the LED to set.

fwCommand
Specifies the state of the LED, as one of the following flags:

Value Meaning

WFS_TTU_LEDOFF The LED is turned off.

WFS_TTU_LEDSLOWFLASH The LED is set to flash slowly.

WFS_TTU_LEDMEDIUMFLASH The LED is blinking medium frequency.

WFS_TTU_LEDQUICKFLASH The LED is set to flash quickly.

WFS_TTU_LEDCONTINUOUS The LED is turned on continuously (steady).

Output Param None.

Error Codes The following additional error codes can be generated by this command:

Value Meaning

WFS_ERR_TTU_INVALIDLED An attempt to set a LED to a new value was invalid because the LED does not exist.

Events There are no additional events generated by this command.

Comments None.


4.5 WFS_CMD_TTU_SET_RESOLUTION

Description This command is used to set the resolution of the display.

Input Param LPWFSTTURESOLUTION lpResolution;

typedef struct _wfs_ttu_resolution
 {
 WORD    wSizeX;
 WORD    wSizeY;
 } WFSTTURESOLUTION, * LPWFSTTURESOLUTION;

wSizeX
Specifies the horizontal size of the display of the text terminal unit (the number of columns that can be displayed)

wSizeY
Specifies the vertical size of the display of the text terminal unit (the number of rows that can be displayed)

Output Param None.

Error Codes The following additional error codes can be generated by this command:

Value Meaning

WFS_ERR_TTU_RESNOTSUPP The specified resolution is not supported by the display.

Events There are no additional events generated by this command.

Comments None.


4.6 WFS_CMD_TTU_DISPLAY_FORM

Description This command is used to display a form by merging the supplied variable field data with the defined form and field data specified in the form.

Input Param LPWFSTTUDISPLAYFORM lpDisplayform;

typedef struct _wfs_ttu_display_form
 {
 LPSTR  lpszFormName;
 BOOL  bClearScreen;
 LPSTR  lpszFields;
 } WFSTTUDISPLAYFORM, * LPWFSTTUDISPLAYFORM;

lpszFormName
Pointer to the null-terminated form name.

bClearScreen
Specifies whether the screen is cleared before displaying the form (TRUE) or not (FALSE).

lpszFields
Pointer to a series of "<FieldName>=<FieldValue>" strings, where each string is null-terminated with the final string terminating with two null characters.

Output Param None.

Error Codes The following additional error codes can be generated by this command:

Value Meaning

WFS_ERR_TTU_FORMNOTFOUND The specified form definition cannot be found.

WFS_ERR_TTU_FORMINVALID The specified form definition is invalid.

WFS_ERR_TTU_MEDIAOVERFLOW The form overflowed the media.

WFS_ERR_TTU_FIELDSPECFAILURE The syntax of the lpszFields member is invalid.

WFS_ERR_TTU_FIELDERROR An error occurred while processing a field, causing termination of the display request

Events There are no additional events generated by this command.

Comments None.


4.7 WFS_CMD_TTU_READ_FORM

Description This command is used to read data from input fields on the specified form.

Input Param LPWFSTTUREADFORM lpReadForm;

typedef struct _wfs_ttu_read_form
 {
 LPSTR  lpszFormName;
 LPSTR  lpszFieldNames;
 } WFSTTUREADFORM, * LPWFSTTUREADFORM;

lpszFormName
Pointer to the null-terminated name of the form.

lpszFieldNames
Pointer to a list of null-terminated field names from which to read input data, with the final name terminating with two null characters. If this value is NULL, then read data from all input fields on the form.

Output Param LPSTR lpszFields;

lpszFields
Pointer to a series of "<FieldName>=<FieldValue>" strings, where each string is null-terminated with the final string terminating with two null characters.

Error Codes The following additional error codes can be generated by this command:

Value Meaning

WFS_ERR_TTU_FORMNOTFOUND The specified form cannot be found.

WFS_ERR_TTU_FORMINVALID The specified form definition is invalid.

WFS_ERR_TTU_FIELDSPECFAILURE The syntax of the lpszFieldNames member is invalid.

WFS_ERR_TTU_KEYCANCELED The read operation was terminated by pressing the <CANCEL>-key.

Events There are no additional events generated by this command.

Comments None.


4.8 WFS_CMD_TTU_WRITE

Description This command displays the specified text on the display of the text terminal unit .

Input Param LPWFSTTUWRITE lpWrite;

typedef struct _wfs_ttu_write
 {
 WORD   fwMode;
 WORD   wPosX;
 WORD   wPosY;
 WORD   fwTextAttr;
 LPSTR   lpsText;
 } WFSTTUWRITE, * LPWFSTTUWRITE;

fwMode
Specifies whether the position of the output is absolute or relative to the current cursor position. Possible values are:

Value Meaning

WFS_TTU_POSRELATIVE The output is positioned relative to the current cursor position.

WFS_TTU_POSABSOLUTE The output is positioned absolute at the position specified in wPosX and wPosY.

wPosX
Specifies the horizontal position, if fwMode is set to WFS_TTU_POSABSOLUTE. Or an offset relative to the current cursor position, if fwMode is set to WFS_TTU_POSRELATIVE.

wPosY
Specifies the vertical position, if fwMode is set to WFS_TTU_POSABSOLUTE. Or an offset relative to the current cursor position, if fwMode is set to WFS_TTU_POSRELATIVE.

fwTextAttr
Specifies the text attributes used for displaying the text as a combination of the following flags:

Value Meaning

WFS_TTU_TEXTUNDERLINED The displayed text will be underlined.

WFS_TTU_TEXTINVERTED The displayed text will be inverted.

WFS_TTU_TEXTFLASH The displayed text will be flashing.

lpsText
Specifies the text that will be displayed.

Output Param None.

Error Codes There are no additional error codes generated by this command.

Events There are no additional events generated by this command.

Comments None.


4.9 WFS_CMD_TTU_READ

Description This command activates the keyboard of the text terminal unit for input of the specified number of characters. Depending on the specified flush mode the input buffer is cleared.

Input Param LPWFSTTUREAD lpRead;

typedef struct _wfs_ttu_read
 {
 WORD   wNumOfChars;
 WORD   fwMode;
 WORD   wPosX;
 WORD   wPosY;
 WORD   fwEchoMode;
 WORD   fwEchoAttr;
 WORD   wKeys;
 BOOL   bCursor;
 BOOL   bFlush;
 BOOL   bAutoEnd;
 } WFSTTUREAD, * LPWFSTTUREAD;

wNumOfChars
Specifies the number of characters that will be read from the text terminal unit key pad.

fwMode
Specifies where the cursor is positioned for the read operation. Possible values are:

Value Meaning

WFS_TTU_POSRELATIVE The cursor is positioned relative to the current cursor position.

WFS_TTU_POSABSOLUTE The cursor is positioned absolute at the position specified in wPosX and wPosY.

wPosX
Specifies the horizontal position, if fwMode is set to WFS_TTU_POSABSOLUTE. Or an offset relative to the current cursor position, if fwMode is set to WFS_TTU_POSRELATIVE.

wPosY
Specifies the vertical position, if fwMode is set to WFS_TTU_POSABSOLUTE. Or an offset relative to the current cursor position, if fwMode is set to WFS_TTU_POSRELATIVE.

fwEchoMode
Specifies how the user input is echoed to the screen as one of the following flags:

Value Meaning

WFS_TTU_ECHOTEXT The user input is echoed to the screen.

WFS_TTU_ECHOINVISIBLE The user input is not echoed to the screen.

WFS_TTU_ECHOPASSWORD The keys entered by the user are echoed as the replace character on the screen.

fwEchoAttr
Specifies the text attributes with which the user input is echoed to the screen as a combination of the following flags:

Value Meaning

WFS_TTU_TEXTUNDERLINED The displayed text will be underlined.

WFS_TTU_TEXTINVERTED The displayed text will be inverted.

WFS_TTU_TEXTFLASH The displayed text will be flashing.

wKeys
Specifies the keys which will be accepted as input to this command as on of the following flags:

Value Meaning

WFS_TTU_KEYNUMERIC Accept numeric values.

WFS_TTU_KEYHEXADECIMAL Accept hexadecimal values.

WFS_TTU_KEYALPHANUMERIC Accept alphanumeric values.

bCursor
Specifies whether the cursor is visible (TRUE) or invisible (FALSE).

bFlush
Specifies whether the keyboard input buffer is cleared before allowing for user input (TRUE) or not (FALSE).

bAutoEnd
Specifies whether the command input is automatically ended by the Service Provider if the maximum number of digits is entered.

Output Param LPSTR lpszInput;

lpszInput
Specifies a zero terminated string containing all the characters read from the text terminal unit key pad.

Error Codes The following additional error codes can be generated by this command:

Value Meaning

WFS_ERR_TTU_KEYCANCELED The read operation was terminated by pressing the <CANCEL>-key.

Events There are no additional events generated by this command.

Comments None.


5. Events

There are no additional events generated by this device class.


6. Form and Field Definitions

This section outlines the format of the definitions of forms, the fields within them, and the media on which they are printed.


6.1 Definition Syntax

The syntactic rules for form, field and media definitions are as follows:

  • White space space, tab

  • Line continuation backslash (\)

  • Line termination CR, LF, CR/LF; line termination ends a “keyword section”
    (a keyword and its value[s])

  • Keywords must be all upper case

  • Names (field/media/font names) any case; case is preserved;
    service providers are case sensitive

  • Strings all strings must be enclosed in double quote characters (");
    standard C escape sequences are allowed.

  • Comments start with two forward slashes (//), end at line termination

Other notes:

  • If a keyword is present, all its values must be specified; default values are used only if the keyword is absent.

  • Values that are character strings are marked with asterisks in the definitions below, and must be quoted as specified above.

  • Fields are processed in the sequence they are defined in the form.


6.2 Form Definition
XFSFORM |  | formname* |
BEGIN |  |  |
(required) | SIZE | width, | Width of form
 |  | height | Height of form
 | VERSION | major, | Major version number
 |  | minor, | Minor version number
 |  | date*, | Creation/modification date
 |  | author* | Author of form
(required) | LANGUAGE | languageID | Language used in this form – a 16 bit value (LANGID) which is a combination of a primary (10 bits) and a secondary (6 bits) language ID (This is the standard language ID in the Win32 API; standard macros support construction and decomposition of this composite ID)
 | COPYRIGHT | copyright* | Copyright entry
 | TITLE | title* | Title of form
 | COMMENT | comment* | Comment section
 | [ XFSFIELD | fieldname* | One field definition (as defined in the next section) for each field in the form
 | BEGIN . . . END ] |  |
END |  |  |


6.3 Field Definition
XFSFIELD |  | fieldname* |
BEGIN |  |  |
(required) | POSITION | x, | Horizontal position (relative to left side of form)
 |  | y | Vertical position (relative to top of form)
(required) | SIZE | width, | Field width
 |  | height | Field height
 | TYPE | fieldtype | Type of field: TEXT (default) INVISIBLE PASSWORD (contents is echoed with ‘*’)
 | CLASS | class | Field class OPTIONAL (default) STATIC REQUIRED
 | KEYS | keys | Accepted input key types: NUMERIC HEXADECIMAL ALPHANUMERIC
 | ACCESS | access | Access rights of field WRITE (default) READ READWRITE
 | OVERFLOW | overflow | Action on field overflow: TERMINATE (default) TRUNCATE OVERWRITE
 | STYLE | style | Display attributes as a combination of the following, ORed together using the "|" operator: NORMAL (default) UNDER (single underline) INVERTED FLASHING
 | HORIZONTAL | justify | Horizontal alignment of field contents LEFT (default) RIGHT CENTER
 | FORMAT | formatstring* | Application defined
 | INITIALVALUE | value* | Initial value
END |  |  |


7. C - Header file

/******************************************************************************
*                                                                             *
* xfsttu.h      WOSA/XFS - definitions                                        *
*               for the Text Terminal Unit - services                         *
*                                                                             *
*               Version 2.00 (11/11/96)                                       *
*                                                                             *
******************************************************************************/

#ifndef __INC_XFSTTU__H
#define __INC_XFSTTU__H

#ifdef __cplusplus
extern "C" {
#endif

#include <xfsapi.h>

/*   be aware of alignment   */
#pragma pack(push,1)

/* values of WFSTTUCAPS.wClass */
#define     WFS_SERVICE_CLASS_TTU               (7)
#define     WFS_SERVICE_CLASS_NAME_TTU          "TTU"
#define     WFS_SERVICE_CLASS_VERSION_TTU       (0x0002)

#define     TTU_SERVICE_OFFSET                  (WFS_SERVICE_CLASS_TTU * 100)

/* TTU Info Commands */
#define     WFS_INF_TTU_STATUS                  (TTU_SERVICE_OFFSET + 1)
#define     WFS_INF_TTU_CAPABILITIES            (TTU_SERVICE_OFFSET + 2)
#define     WFS_INF_TTU_FORM_LIST               (TTU_SERVICE_OFFSET + 3)
#define     WFS_INF_TTU_QUERY_FORM              (TTU_SERVICE_OFFSET + 4)
#define     WFS_INF_TTU_QUERY_FIELD             (TTU_SERVICE_OFFSET + 5)

/* TTU Command Verbs */
#define     WFS_CMD_TTU_BEEP                    (TTU_SERVICE_OFFSET + 1)
#define     WFS_CMD_TTU_CLEARSCREEN             (TTU_SERVICE_OFFSET + 2)
#define     WFS_CMD_TTU_DISPLIGHT               (TTU_SERVICE_OFFSET + 3)
#define     WFS_CMD_TTU_SET_LED                 (TTU_SERVICE_OFFSET + 4)
#define     WFS_CMD_TTU_SET_RESOLUTION          (TTU_SERVICE_OFFSET + 5)
#define     WFS_CMD_TTU_DISPLAY_FORM            (TTU_SERVICE_OFFSET + 6)
#define     WFS_CMD_TTU_READ_FORM               (TTU_SERVICE_OFFSET + 7)
#define     WFS_CMD_TTU_WRITE                   (TTU_SERVICE_OFFSET + 8)
#define     WFS_CMD_TTU_READ                    (TTU_SERVICE_OFFSET + 9)

/* WOSA/XFS TTU Errors */

#define     WFS_ERR_TTU_FIELDERROR              (-(TTU_SERVICE_OFFSET + 1))
#define     WFS_ERR_TTU_FIELDINVALID            (-(TTU_SERVICE_OFFSET + 2))
#define     WFS_ERR_TTU_FIELDNOTFOUND           (-(TTU_SERVICE_OFFSET + 3))
#define     WFS_ERR_TTU_FIELDSPECFAILURE        (-(TTU_SERVICE_OFFSET + 4))
#define     WFS_ERR_TTU_FORMINVALID             (-(TTU_SERVICE_OFFSET + 5))
#define     WFS_ERR_TTU_FORMNOTFOUND            (-(TTU_SERVICE_OFFSET + 6))
#define     WFS_ERR_TTU_INVALIDLED              (-(TTU_SERVICE_OFFSET + 7))
#define     WFS_ERR_TTU_KEYCANCELED             (-(TTU_SERVICE_OFFSET + 8))
#define     WFS_ERR_TTU_MEDIAOVERFLOW           (-(TTU_SERVICE_OFFSET + 9))
#define     WFS_ERR_TTU_RESNOTSUPP              (-(TTU_SERVICE_OFFSET + 10))

/* Values of WFSTTUSTATUS.fwDevice */
#define     WFS_TTU_DEVONLINE                   WFS_STAT_DEVONLINE
#define     WFS_TTU_DEVOFFLINE                  WFS_STAT_DEVOFFLINE
#define     WFS_TTU_DEVPOWEROFF                 WFS_STAT_DEVPOWEROFF
#define     WFS_TTU_DEVBUSY                     WFS_STAT_DEVBUSY
#define     WFS_TTU_DEVNODEVICE                 WFS_STAT_DEVNODEVICE
#define     WFS_TTU_DEVHWERROR                  WFS_STAT_DEVHWERROR
#define     WFS_TTU_DEVUSERERROR                WFS_STAT_DEVUSERERROR

/* Values of WFSTTUSTATUS.wKeyboard */
#define     WFS_TTU_KBDNA                       (0)
#define     WFS_TTU_KBDON                       (1)
#define     WFS_TTU_KBDOFF                      (2)

/* Values of WFSTTUSTATUS.wKeyLock */
#define     WFS_TTU_KBDLOCKNA                   (0)
#define     WFS_TTU_KBDLOCKON                   (1)
#define     WFS_TTU_KBDLOCKOFF                  (2)

#define     WFS_TTU_LEDS_MAX                    (8)

/* Values of WFSTTUSTATUS.fwLEDs */
#define     WFS_TTU_LEDNA                       (0x0000)
#define     WFS_TTU_LEDOFF                      (0x0001)
#define     WFS_TTU_LEDON                       (0x0002)
#define     WFS_TTU_LEDSLOWFLASH                (0x0004)
#define     WFS_TTU_LEDMEDIUMFLASH              (0x0008)
#define     WFS_TTU_LEDQUICKFLASH               (0x0010)
#define     WFS_TTU_LEDCONTINUOUS               (0x0080)

/* Values of WFSTTUCAPS.fwType */
#define     WFS_TTU_FIXED                       (0x0001)
#define     WFS_TTU_REMOVABLE                   (0x0002)

/* Values of WFSTTUCAPS.fwKeys */
#define     WFS_TTU_KEYNUMERIC                  (0x0001)
#define     WFS_TTU_KEYHEXADECIMAL              (0x0002)
#define     WFS_TTU_KEYALPHANUMERIC             (0x0004)

/* Values of WFSTTUFRMFIELD.fwType */
#define     WFS_TTU_FIELDTEXT                   (0)
#define     WFS_TTU_FIELDINVISIBLE              (1)
#define     WFS_TTU_FIELDPASSWORD               (2)

/* Values of WFSTTUFRMFIELD.fwClass */
#define     WFS_TTU_CLASSOPTIONAL               (0)
#define     WFS_TTU_CLASSSTATIC                 (1)
#define     WFS_TTU_CLASSREQUIRED               (2)

/* Values of WFSTTUFRMFIELD.fwAccess */
#define     WFS_TTU_ACCESSREAD                  (0x0001)
#define     WFS_TTU_ACCESSWRITE                 (0x0002)

/* Values of WFSTTUFRMFIELD.fwOverflow */
#define     WFS_TTU_OVFTERMINATE                (0)
#define     WFS_TTU_OVFTRUNCATE                 (1)
#define     WFS_TTU_OVFOVERWRITE                (2)

/* Values of WFSTTUWRITE.fwMode */
#define     WFS_TTU_POSRELATIVE                 (0)
#define     WFS_TTU_POSABSOLUTE                 (1)

/* Values of WFSTTUWRITE.fwTextAttr */
#define     WFS_TTU_TEXTUNDERLINE               (0x0001)
#define     WFS_TTU_TEXTINVERTED                (0x0002)
#define     WFS_TTU_TEXTFLASH                   (0x0004)

/* Values of WFSTTUFRMREAD.fwEchoMode */
#define     WFS_TTU_ECHOTEXT                    (0)
#define     WFS_TTU_ECHOINVISIBLE               (1)
#define     WFS_TTU_ECHOPASSWORD                (2)

#define     WFS_TTU_BEEPOFF                     (0x0001)
#define     WFS_TTU_BEEPKEYPRESS                (0x0002)
#define     WFS_TTU_BEEPEXCLAMATION             (0x0004)
#define     WFS_TTU_BEEPWARNING                 (0x0008)
#define     WFS_TTU_BEEPERROR                   (0x0010)
#define     WFS_TTU_BEEPCRITICAL                (0x0020)
#define     WFS_TTU_BEEPCONTINUOUS              (0x0080)

/*=================================================================*/
/* TTU Info Command Structures and variables */
/*=================================================================*/

typedef struct _wfs_ttu_status
{
    WORD            fwDevice;
    WORD            wKeyboard;
    WORD            wKeylock;
    WORD            wLEDs[WFS_TTU_LEDS_MAX];
    WORD            wDisplaySizeX;
    WORD            wDisplaySizeY;
    LPSTR           lpszExtra;
} WFSTTUSTATUS, * LPWFSTTUSTATUS;

typedef struct _wfs_ttu_resolution
{
    WORD            wSizeX;
    WORD            wSizeY;
} WFSTTURESOLUTION, * LPWFSTTURESOLUTION;

typedef struct _wfs_ttu_caps
{
    WORD                  wClass;
    WORD                  fwType;
    LPWFSTTURESOLUTION *  lppResolutions;
    WORD                  wNumOfLEDs;
    BOOL                  bKeyLock;
    BOOL                  bDisplayLight;
    WORD                  fwKeys;
    BOOL                  bCursor;
    BOOL                  bForms;
    LPSTR                 lpszExtra;
} WFSTTUCAPS, * LPWFSTTUCAPS;

typedef struct _wfs_ttu_frm_header
{
    LPSTR           lpszFormName;
    WORD            wWidth;
    WORD            wHeight;
    WORD            wVersionMajor;
    WORD            wVersionMinor;
    LPSTR           lpszFields;
} WFSTTUFRMHEADER, * LPWFSTTUFRMHEADER;

typedef struct _wfs_ttu_query_field
{
    LPSTR           lpszFormName;
    LPSTR           lpszFieldName;
} WFSTTUQUERYFIELD, * LPWFSTTUQUERYFIELD;

typedef struct _wfs_ttu_frm_field
{
    LPSTR           lpszFieldName;
    WORD            fwType;
    WORD            fwClass;
    WORD            fwAccess;
    WORD            fwOverflow;
    LPSTR           lpszFormat;
} WFSTTUFRMFIELD, * LPWFSTTUFRMFIELD;

typedef struct _wfs_ttu_clear_screen
{
    WORD            wPositionX;
    WORD            wPositionY;
    WORD            wWidth;
    WORD            wHeight;
} WFSTTUCLEARSCREEN, * LPWFSTTUCLEARSCREEN;

typedef struct _wfs_ttu_disp_light
{
    BOOL            bMode;
} WFSTTUDISPLIGHT, * LPWFSTTUDISPLIGHT;

typedef struct _wfs_ttu_set_leds
{
    WORD            wLED;
    WORD            fwCommand;
} WFSTTUSETLEDS, * LPWFSTTUSETLEDS;

typedef struct _wfs_ttu_display_form
{
    LPSTR           lpszFormName;
    BOOL            bClearScreen;
    LPSTR           lpszFields;
} WFSTTUDISPLAYFORM, * LPWFSTTUDISPLAYFORM;

typedef struct _wfs_ttu_read_form
{
    LPSTR           lpszFormName;
    LPSTR           lpszFieldNames;
} WFSTTUREADFORM, * LPWFSTTUREADFORM;

typedef struct _wfs_ttu_write
{
    WORD            fwMode;
    WORD            wPosX;
    WORD            wPosY;
    WORD            fwTextAttr;
    LPSTR           lpsText;
} WFSTTUWRITE, * LPWFSTTUWRITE;

typedef struct _wfs_ttu_read
{
    WORD            wNumOfChars;
    WORD            fwMode;
    WORD            wPosX;
    WORD            wPosY;
    WORD            fwEchoMode;
    WORD            fwEchoAttr;
    WORD            wKeys;
    BOOL            bCursor;
    BOOL            bFlush;
    BOOL            bAutoEnd;
} WFSTTUREAD, * LPWFSTTUREAD;

/* restore alignment */
#pragma pack(pop)

#ifdef __cplusplus
}       /*extern "C"*/
#endif

#endif  /* __INC_XFSTTU__H */


WOSA

(Windowsä Open Services Architecture)

Extensions for Financial Services

A Client-Server Architecture for Financial Enterprise Computing under Microsoft® Windows

Sensors and Indicators Unit Device Class Interface

–––––––––––––––––––––––––––––––––––

Programmer’s Reference

Revision 2.00

November 11, 1996

Developed by the members of the Banking Solutions Vendor Council


Table of Contents

1. Introduction

1.1 WOSA/XFS Service-Specific Programming

2. Sensors and Indicators Unit

3. Info Commands

3.1 WFS_INF_SIU_STATUS

3.2 WFS_INF_SIU_CAPABILITIES

4. Execute Commands

4.1 WFS_CMD_SIU_ENABLE_EVENTS

4.2 WFS_CMD_SIU_SET_PORTS

4.3 WFS_CMD_SIU_SET_DOOR

4.4 WFS_CMD_SIU_SET_INDICATOR

4.5 WFS_CMD_SIU_SET_AUXILIARY

4.6 WFS_CMD_SIU_SET_GUIDLIGHT

5. Events

5.1 WFS_SRVE_SIU_PORT_STATUS

5.2 WFS_EXEE_SIU_PORT_ERROR

6. C - header file


2. Sensors and Indicators Unit

This specification describes the functionality of the services provided by the Sensors and Indicators Unit (SIU) services under WOSA/XFS, by defining the service-specific commands that can be issued, using the WFSGetInfo, WFSAsyncGetInfo, WFSExecute and WFSAsyncExecute functions.

This section describes the functions provided by a generic Sensors and Indicators Unit service. This service allows for the operation of the following categories of ports:

  • Door sensors, such as cabinet, safe or vandal shield doors;

  • Alarm sensors, such as tamper, seismic or heat sensors;

  • Generic sensors, such as proximity or ambient light sensors;

  • Key switch sensors, such as the ATM operator switch;

  • Lamp/sign indicators, such as fascia light or audio indicators;

  • Auxiliary indicators.

In self-service devices, the sensors and indicators unit is capable of dealing with external sensors, such as door switches, locks, alarms and proximity sensors, as well as external indicators, such as turning on lamps or heating.


3.1 WFS_INF_SIU_STATUS

Description This command reports the full range of information available, including the information that is provided by the service provider.

Input Param None.

Output Param LPWFSSIUSTATUS lpStatus;

typedef struct _wfs_siu_status
 {
 WORD   fwDevice;
 WORD   fwSensors [WFS_SIU_SENSORS_SIZE];
 WORD   fwDoors [WFS_SIU_DOORS_SIZE];
 WORD   fwIndicators [WFS_SIU_INDICATORS_SIZE];
 WORD   fwAuxiliaries [WFS_SIU_AUXILIARIES_SIZE];
 WORD   fwGuidLights [WFS_SIU_GUIDLIGHTS_SIZE];
 LPSTR   lpszExtra;
 } WFSSIUSTATUS, * LPWFSSIUSTATUS;

fwDevice
Specifies the state of the Sensors and Indicators Unit device as one of the following flags:

Value Meaning

WFS_SIU_DEVONLINE The device is on-line. The device is present and operational (i.e. not busy processing a request and does not have a hardware error).

WFS_SIU_DEVOFFLINE The device is off-line. The device is present and powered on but it is not operational (e.g. a switch may have been used to change it to an off-line state).

WFS_SIU_DEVPOWEROFF The device is powered off. The device is present, but is currently powered off.

WFS_SIU_DEVBUSY The device is busy processing a request. The device is present and an EXECUTE request is currently being processing.

WFS_SIU_DEVNODEVICE There is no device connected.

WFS_SIU_DEVHWERROR The device is inoperable due to a hardware error. The device is present but a hardware fault prevents it from being used.

WFS_SIU_DEVUSERERROR The device is present but a person is preventing proper operation. The application should suspend the device operation or remove the device from service until the service provider generates a device state change event indicating the condition of the device has changed i.e. the error is removed (WFS_SIU_DEVONLINE) or a permanent error condition has occurred (WFS_SIU_DEVHWERROR).

fwSensors [...]
Specifies the state of the Sensors. A number of sensor types are defined below. Vendor specific sensors are defined starting from the end of the array. The maximum sensor index is WFS_SIU_SENSORS_MAX.

fwSensors [WFS_SIU_OPERATORSWITCH]
Specifies the state of the Operator Switch(es). This switch is used to tell the terminal if an Operator/Supervisor wants to change the state from Run to Operators/Supervisors mode or vice versa. The Run mode is used for normal consumer operations/transactions. The Maintenance mode is used when replenish the terminal. The Supervisor mode is used when operating the terminal for service and testing. Supervisor mode has higher priority than maintenance mode. Specified as one of the following flags:

Value Meaning

WFS_SIU_NOT_AVAILABLE The status is not available.

WFS_SIU_RUN The switch is in Run mode.

WFS_SIU_MAINTENANCE The switch is in Maintenance mode.

WFS_SIU_SUPERVISOR The switch is in Supervisor mode.

fwSensors [WFS_SIU_TAMPER]
Specifies the state of the Tamper Sensor for the terminal. This sensor indicates whether the terminal has been tampered with (such as a burglar attempt). Specified as one of the following flags:

Value Meaning

WFS_SIU_NOT_AVAILABLE The status is not available.

WFS_SIU_OFF There is no indication of a tampering attempt.

WFS_SIU_ON There has been a tampering attempt.

fwSensors [WFS_SIU_INTTAMPER]
Specifies the state of the Tamper Sensor for the internal alarm. This sensor indicates whether the internal alarm has been tampered with (such as a burglar attempt). Specified as one of the following flags:

Value Meaning

WFS_SIU_NOT_AVAILABLE The status is not available.

WFS_SIU_OFF There is no indication of a tampering attempt.

WFS_SIU_ON There has been a tampering attempt.

fwSensors [WFS_SIU_SEISMIC]
Specifies the state of the Seismic Sensor. This sensor indicates whether the terminal has been shaken (e.g. burglar attempt or seismic activity). Specified as one of the following flags:

Value Meaning

WFS_SIU_NOT_AVAILABLE The status is not available.

WFS_SIU_OFF The seismic activity has not been high enough to trigger the sensor.

WFS_SIU_ON The seismic or other activity has triggered the sensor.

fwSensors [WFS_SIU_HEAT]
Specifies the state of the Heat Sensor. This sensor is triggered by excessive heat (fire) near the terminal. Specified as one of the following flags:

Value Meaning

WFS_SIU_NOT_AVAILABLE The status is not available.

WFS_SIU_OFF The heat has not been high enough to trigger the sensor.

WFS_SIU_ON The heat has been high enough to trigger the sensor.

fwSensors [WFS_SIU_PROXIMITY]
Specifies the state of the Proximity Sensor. This sensor is triggered by movements around the terminal. Specified as one of the following flags:

Value Meaning

WFS_SIU_NOT_AVAILABLE The status is not available.

WFS_SIU_NOT_PRESENT The sensor can not sense any people around the terminal.

WFS_SIU_PRESENT The sensor is showing that there is someone present at the terminal.

fwSensors [WFS_SIU_AMBLIGHT]
Specifies the state of the Ambient Light Sensor. This sensor indicates the level of ambient light around the terminal. Specified as one of the following flags:

Value Meaning

WFS_SIU_NOT_AVAILABLE The status is not available.

WFS_SIU_VERY_LIGHT The level of light is: very light

WFS_SIU_LIGHT The level of light is: light

WFS_SIU_MEDIUM_LIGHT The level of light is: medium light

WFS_SIU_DARK The level of light is: dark

WFS_SIU_VERY_DARK The level of light is: very dark

fwDoors [...]
Specifies the state of the Doors. A number of door types are defined below. Vendor specific doors are defined starting from the end of the array. The maximum door index is WFS_SIU_DOORS_MAX.

fwDoors [WFS_SIU_CABINET]
Specifies the state of the Cabinet Doors. Cabinet Doors are doors that open up for consumables, and hardware that does not have to be in a secure place. Specified as one of the following flags.

Value Meaning

WFS_SIU_NOT_AVAILABLE The status is not available.

WFS_SIU_OPEN At least one of the Cabinet Doors is open.

WFS_SIU_CLOSED The Cabinet Doors are closed.

WFS_SIU_LOCKED The Cabinet Doors are closed and locked.

WFS_SIU_BOLTED The Cabinet Doors are closed, locked and bolted.

fwDoors [WFS_SIU_SAFE]
Specifies the state of the Safe Doors. Safe Doors are doors that open up for secure hardware, such as the note dispenser, the security device, etc. Specified as one of the following flags:

Value Meaning

WFS_SIU_NOT_AVAILABLE The status is not available.

WFS_SIU_OPEN At least one of the Safe Doors is open.

WFS_SIU_CLOSED The Safe Doors are closed.

WFS_SIU_LOCKED The Safe Doors are closed and locked.

WFS_SIU_BOLTED The Safe Doors are closed, locked and bolted.

fwDoors [WFS_SIU_VANDALSHIELD]
Specifies the state of the Vandal Shield. The Vandal Shield is a door that open up for consumer access to the terminal. Specified as one of the following flags:

Value Meaning

WFS_SIU_NOT_AVAILABLE The status is not available.

WFS_SIU_OPEN The Vandal Shield is open.

WFS_SIU_CLOSED The Vandal Shield is closed.

WFS_SIU_LOCKED The Vandal Shield is closed and locked.

WFS_SIU_SERVICE The Vandal Shield is in service position.

WFS_SIU_KEYBOARD The Vandal Shield position permits access to the keyboard.

WFS_SIU_AJAR The Vandal Shield is ajar.

WFS_SIU_JAMMED The Vandal Shield is jammed.

fwIndicators [...]
Specifies the state of the Status Indicators. A number of Status Indicator types are defined below. Vendor specific indicators are defined starting from the end of the array. The maximum indicator index is WFS_SIU_INDICATORS_MAX.

fwIndicators [WFS_SIU_OPENCLOSE]
Specifies the state of the Open/Closed Indicator as one of the following flags:

Value Meaning

WFS_SIU_NOT_AVAILABLE The status is not available.

WFS_SIU_CLOSED The terminal is closed for a consumer.

WFS_SIU_OPEN The terminal is open to be used by a consumer.

fwIndicators [WFS_SIU_FASCIALIGHT]
Specifies the state of the Fascia Light as one of the following flags:

Value Meaning

WFS_SIU_NOT_AVAILABLE The status is not available.

WFS_SIU_OFF The Fascia Light is turned off.

WFS_SIU_ON The Fascia Light is turned on.

fwIndicators [WFS_SIU_AUDIO]
Specifies the state of the Audio Indicator as one of the following flags of type A and B, or as WFS_SIU_ CONTINUOUS in combination with one of the flags of type B:

Value Meaning Type

WFS_SIU_NOT_AVAILABLE | The status is not available. | A
WFS_SIU_OFF | The Audio Indicator is turned off. | A
WFS_SIU_KEYPRESS | The Audio Indicator sounds a key click signal. | B
WFS_SIU_EXCLAMATION | The Audio Indicator sounds a exclamation signal. | B
WFS_SIU_WARNING | The Audio Indicator sounds a warning signal. | B
WFS_SIU_ERROR | The Audio Indicator sounds a error signal. | B
WFS_SIU_CRITICAL | The Audio Indicator sounds a critical signal. | B
WFS_SIU_CONTINUOUS | The Audio Indicator sound is turned on continuously. | C

fwIndicators [WFS_SIU_HEATING]
Specifies the state of the internal heating as one of the following flags:

Value Meaning

WFS_SIU_NOT_AVAILABLE The status is not available.

WFS_SIU_OFF The Heating is turned off.

WFS_SIU_ON The Heating is turned on.

fwAuxiliaries [...]
Specifies the state of the Auxiliary indicators. A number of Auxiliary indicator types are defined below. Vendor specific Auxiliaries are defined starting from the end of the array. The maximum auxiliary index is WFS_SIU_AUXILIARIES_MAX.

fwAuxiliaries [WFS_SIU_VOLUME]
Specifies the value of the volume control. The value of volume control is defined in an interval from 1 to 1000 where 1 is the lowest volume level and 1000 is the highest volume level. The interval is defined in logarithmic steps, e.g. a volume control on a radio. Note: The volume control field is handled as unsigned short.

Value Meaning

WFS_SIU_NOT_AVAILABLE The status is not available.

1, ..., 1000 The volume level. This field is handled as an unsigned short.

fwAuxiliaries [WFS_SIU_UPS]
Specifies the state of the Uninterruptable Power Supply device as WFS_SIU_NOT_AVAILABLE or as a combination of the following flags of type B:

Value Meaning Type

WFS_SIU_NOT_AVAILABLE | There is no UPS available. | A
WFS_SIU_AVAILABLE | The UPS is available | B
WFS_SIU_LOW | The charge level of the UPS is low | B
WFS_SIU_ENGAGED | The UPS is engaged | B
WFS_SIU_POWERING | The UPS is powering the system. The main power supply is off. | B
WFS_SIU_RECOVERED | The UPS was engaged when the main power went off | B

fwGuidLights [...]
Specifies the state of the Guidance Light Indicators. A number of guidance light types are defined below. Vendor specific guidance lights are defined starting from the end of the array. The maximum guidance light index is WFS_SIU_GUIDLIGHTS_MAX. All member elements in this array are specified as one of the following flags:

Value Meaning

WFS_SIU_NOT_AVAILABLE The status is not available.

WFS_SIU_OFF The light is turned off.

WFS_SIU_SLOW_FLASH The light is blinking slowly.

WFS_SIU_MEDIUM_FLASH The light is blinking medium frequency.

WFS_SIU_QUICK_FLASH The light is blinking quickly.

WFS_SIU_CONTINUOUS The light is turned on continuous (steady).

fwGuidLights [WFS_SIU_CARDUNIT]
Specifies the state of the Guidance Light Indicator on the Card Unit (IDC).

fwGuidLights [WFS_SIU_PINPAD]
Specifies the state of the Guidance Light Indicator on the PIN pad unit.

fwGuidLights [WFS_SIU_NOTESDISPENSER]
Specifies the state of the Guidance Light Indicator on the note dispenser unit.

fwGuidLights [WFS_SIU_COINDISPENSER]
Specifies the state of the Guidance Light Indicator on the coin dispenser unit.

fwGuidLights [WFS_SIU_RECEIPTPRINTER]
Specifies the state of the Guidance Light Indicator on the receipt printer unit.

fwGuidLights [WFS_SIU_PASSBOOKPRINTER]
Specifies the state of the Guidance Light Indicator on the passbook printer unit.

fwGuidLights [WFS_SIU_ENVDEPOSITORY]
Specifies the state of the Guidance Light Indicator on the envelope depository unit.

fwGuidLights [WFS_SIU_CHEQUEUNIT]
Specifies the state of the Guidance Light Indicator on the cheque processing unit.

fwGuidLights [WFS_SIU_BILLACCEPTOR]
Specifies the state of the Guidance Light Indicator on the bill acceptor unit.

fwGuidLights [WFS_SIU_ENVDISPENSER]
Specifies the state of the Guidance Light Indicator on the envelope dispenser unit.

lpszExtra
Specifies a list of vendor-specific, or any other extended, information. The information is returned as a series of "key=value" strings so that it is easily extensible by service providers. Each string will be null-terminated, with the final string terminating with two null characters.

Error Codes There are no additional error codes generated by this command.

Comments Applications which require or expect specific information to be present in the lpszExtra parameter may not be device or vendor-independent.


3.2 WFS_INF_SIU_CAPABILITIES

Description This command is used to retrieve the capabilities of the Sensors and Indicators Unit.

Input Param None.

Output Param LPWFSSIUCAPS lpCaps;

typedef struct _wfs_siu_caps
 {
 WORD   wClass;
 WORD   fwType;
 WORD   fwSensors [WFS_SIU_SENSORS_SIZE];
 WORD   fwDoors [WFS_SIU_DOORS_SIZE];
 WORD   fwIndicators [WFS_SIU_INDICATORS_SIZE];
 WORD   fwAuxiliaries [WFS_SIU_AUXILIARIES_SIZE];
 WORD   fwGuidLights [WFS_SIU_GUIDLIGHTS_SIZE];
 LPSTR   lpszExtra;
 } WFSSIUCAPS, * LPWFSSIUCAPS;

wClass
Specifies the logical service class, value is:
WFS_SERVICE_CLASS_SIU

fwType
Specifies the type of sensors and indicators supported by this device as a combination of the following flags:

Value Meaning

WFS_SIU_SENSORS The device supports input Sensors.

WFS_SIU_DOORS The device support Door sensors.

WFS_SIU_INDICATORS The device supports Status Indicators.

WFS_SIU_AUXILIARIES The device supports Auxiliary Indicators.

WFS_SIU_GUIDLIGHTS The device supports Guidance Lights.

fwSensors [...]
Specifies which Sensors that are available, and if so, which states they can take. A number of sensor types are defined below. Vendor specific sensors are defined starting from the end of the array. The maximum sensor index is WFS_SIU_SENSORS_MAX.

fwSensors [WFS_SIU_OPERATORSWITCH]
Specifies whether the Operator switch is available, and if so, which states it can take. Specified as WFS_SIU_NOT_AVAILABLE or as a combination of the following flags of type B:

Value Meaning Type

WFS_SIU_NOT_AVAILABLE | There is no Operator Switch available. | A
WFS_SIU_RUN | The switch can be set in Run mode. | B
WFS_SIU_MAINTENANCE | The switch can be set in Maintenance mode. | B
WFS_SIU_SUPERVISOR | The switch can be set in Supervisors mode. | B

fwSensors [WFS_SIU_TAMPER]
Specifies whether the Tamper Sensor for the terminal is available. Specified as one of the following flags:

Value Meaning

WFS_SIU_NOT_AVAILABLE There is no Tamper Sensor available.

WFS_SIU_AVAILABLE The Tamper Sensor is available.

fwSensors [WFS_SIU_INTTAMPER]
Specifies whether the Tamper Sensor for internal alarm is available. Specified as one of the following flags:

Value Meaning

WFS_SIU_NOT_AVAILABLE There is no internal Tamper Sensor available.

WFS_SIU_AVAILABLE The internal Tamper Sensor is available.

fwSensors [WFS_SIU_SEISMIC]
Specifies whether the Seismic Sensor is available. Specified as one of the following flags:

Value Meaning

WFS_SIU_NOT_AVAILABLE There is no Seismic Sensor available.

WFS_SIU_AVAILABLE The Seismic Sensor is available.

fwSensors [WFS_SIU_HEAT]
Specifies whether the Heat Sensor is available. Specified as one of the following flags:

Value Meaning

WFS_SIU_NOT_AVAILABLE There is no Heat Sensor available.

WFS_SIU_AVAILABLE The Heat Sensor is available.

fwSensors [WFS_SIU_PROXIMITY]
Specifies whether the Proximity Sensor is available. Specified as one of the following flags:

Value Meaning

WFS_SIU_NOT_AVAILABLE There is no Proximity Sensor available.

WFS_SIU_AVAILABLE The Proximity Sensor is available.

fwSensors [WFS_SIU_AMBLIGHT]
Specifies whether the Ambient Light Sensor is available. Specified as one of the following flags:

Value Meaning

WFS_SIU_NOT_AVAILABLE There is no Ambient Light Sensor available.

WFS_SIU_AVAILABLE The Ambient Light Sensor is available.

fwDoors [...]
Specifies which Doors that are available, and if so, which states they can take. A number of door types are defined below. Vendor specific doors are defined starting from the end of the array. The maximum door index is WFS_SIU_DOORS_MAX.

fwDoors [WFS_SIU_CABINET]
Specifies whether the Cabinet Doors are available, and if so, which states they can take. Specified as WFS_SIU_NOT_AVAILABLE or as a combination of the following flags of type B:

Value Meaning Type

WFS_SIU_NOT_AVAILABLE | There is no Cabinet Door available. | A
WFS_SIU_LOCKED | The Cabinet Doors can be locked. | B
WFS_SIU_BOLTED | The Cabinet Doors can be bolted. | B
WFS_SIU_CLOSED | The Cabinet Doors can be closed. | B
WFS_SIU_OPEN | The Cabinet Doors can be open. | B

fwDoors [WFS_SIU_SAFE]
Specifies whether the Safe Doors are available, and if so, which states they can take. Specified as WFS_SIU_NOT_AVAILABLE or as a combination of the following flags of type B:

Value Meaning Type

WFS_SIU_NOT_AVAILABLE | There is no Safe Door available. | A
WFS_SIU_LOCKED | The Safe Doors can be locked. | B
WFS_SIU_BOLTED | The Safe Doors can be bolted. | B
WFS_SIU_CLOSED | The Safe Doors can be closed. | B
WFS_SIU_OPEN | The Safe Doors can be open. | B

fwDoors [WFS_SIU_VANDALSHIELD]
Specifies whether the Vandal Shield is available, and if so, which states it can take. Specified as WFS_SIU_NOT_AVAILABLE or as a combination of the following flags of type B:

Value Meaning Type

WFS_SIU_NOT_AVAILABLE | There is no Vandal Shield available. | A
WFS_SIU_OPEN | The Vandal Shield can be open. | B
WFS_SIU_SERVICE | The Vandal Shield can be in service position. | B
WFS_SIU_KEYBOARD | The Vandal Shield can be in position that permits access to the keyboard. | B
WFS_SIU_CLOSED | The Vandal Shield can be closed. | B
WFS_SIU_LOCKED | The Vandal Shield can be locked. | B

fwIndicators [...]
Specifies which Status Indicators that are available, and if so, which states they can take. A number of Status Indicator types are defined below. Vendor specific indicators are defined starting from the end of the array. The maximum indicator index is WFS_SIU_INDICATORS_MAX.

fwIndicators [WFS_SIU_OPENCLOSE]
Specifies whether the Open/Closed Indicator is available. Specified as one of the following flags:

Value Meaning

WFS_SIU_NOT_AVAILABLE There is no Open/Closed Indicator available.

WFS_SIU_AVAILABLE The Open/Closed Indicator is available.

fwIndicators [WFS_SIU_FASCIALIGHT]
Specifies whether the Fascia Light is available. Specified as one of the following flags:

Value Meaning

WFS_SIU_NOT_AVAILABLE There is no Fascia Light available.

WFS_SIU_AVAILABLE The Fascia Light is available.

fwIndicators [WFS_SIU_AUDIO]
Specifies whether the Audio Indicator device is available. Specified as one of the following flags:

Value Meaning

WFS_SIU_NOT_AVAILABLE There is no Audio Indicator available.

WFS_SIU_AVAILABLE The Audio Indicator is available.

fwIndicators [WFS_SIU_HEATING]
Specifies whether the internal Heating device is available. Specified as one of the following flags:

Value Meaning

WFS_SIU_NOT_AVAILABLE There is no Heating device available.

WFS_SIU_AVAILABLE The Heating device is available.

fwAuxiliaries [...]
Specifies which Auxiliaries that are available, and if so, which states they can take. A number of Auxiliary indicator types are defined below. Vendor specific Auxiliaries are defined starting from the end of the array. The maximum auxiliary index is WFS_SIU_AUXILIARIES_MAX.

fwAuxiliaries [WFS_SIU_VOLUME]
Specifies if the volume control is available, and if so, the increment/decrement value recommended by the vendor.

Value Meaning

WFS_SIU_NOT_AVAILABLE There is no volume control available.

1, ..., 1000 The recommended increment/decrement value for the volume control.

fwAuxiliaries [WFS_SIU_UPS]
Specifies if the UPS device is available, and if so, which states it can take. Specified as WFS_SIU_NOT_AVAILABLE or as a combination of the following flags of type B:

Value Meaning Type

WFS_SIU_NOT_AVAILABLE | There is no UPS available. | A
WFS_SIU_AVAILABLE | The UPS is available | B
WFS_SIU_LOW | The UPS can indicate that its charge level is low | B
WFS_SIU_ENGAGED | The UPS can be engaged and disengaged by the application | B
WFS_SIU_POWERING | The UPS can indicate that it is powering the system while the main power supply is off. | B
WFS_SIU_RECOVERED | The UPS can indicate that it was engaged when the main power went off | B

fwGuidLights [...]
Specifies which Guidance Lights that are available, and if so, which states they can take. A number of guidance light types are defined below. Vendor specific guidance lights are defined starting from the end of the array. The maximum guidance light index is WFS_SIU_GUIDLIGHTS_MAX. The elements of this array are specified as one of the following flags:

Value Meaning

WFS_SIU_NOT_AVAILABLE There is no Guidance Light available at this position.

WFS_SIU_AVAILABLE A Guidance Light is available at this position.

fwGuidLights [WFS_SIU_CARDUNIT]
Specifies whether the Guidance Light Indicator on the Card Unit (IDC) is available.

fwGuidLights [WFS_SIU_PINPAD]
Specifies whether the Guidance Light Indicator on the PIN pad unit is available.

fwGuidLights [WFS_SIU_NOTESDISPENSER]
Specifies whether the Guidance Light Indicator on the note dispenser unit is available.

fwGuidLights [WFS_SIU_COINDISPENSER]
Specifies whether the Guidance Light Indicator on the coin dispenser unit is available.

fwGuidLights [WFS_SIU_RECEIPTPRINTER]
Specifies whether the Guidance Light Indicator on the receipt printer unit is available.

fwGuidLights [WFS_SIU_PASSBOOKPRINTER]
Specifies whether the Guidance Light Indicator on the passbook printer unit is available.

fwGuidLights [WFS_SIU_ENVDEPOSITORY]
Specifies whether the Guidance Light Indicator on the envelope depository unit is available.

fwGuidLights [WFS_SIU_CHEQUEUNIT]
Specifies whether the Guidance Light Indicator on the cheque processing unit is available.

fwGuidLights [WFS_SIU_BILLACCEPTOR]
Specifies whether the Guidance Light Indicator on the bill acceptor unit is available.

fwGuidLights [WFS_SIU_ENVDISPENSER]
Specifies whether the Guidance Light Indicator on the envelope dispenser unit is available.

lpszExtra
Specifies a list of vendor-specific, or any other extended, information. The information is returned as a series of "key=value" strings so that it is easily extensible by service providers. Each string will be null-terminated, with the final string terminating with two null characters.

Error Codes There are no additional error codes generated by this command.

Comments Applications which require or expect specific information to be present in the lpszExtra parameter may not be device or vendor-independent.


4.1 WFS_CMD_SIU_ENABLE_EVENTS

Description This command is used to enable or disable events from the Sensors and Indicators Unit. The default condition is that all events are disabled.

Input Param LPWFSSIUENABLE lpEnable;

typedef struct _wfs_siu_enable
 {
 WORD   fwSensors [WFS_SIU_SENSORS_SIZE];
 WORD   fwDoors [WFS_SIU_DOORS_SIZE];
 WORD   fwIndicators [WFS_SIU_INDICATORS_SIZE];
 WORD   fwAuxiliaries [WFS_SIU_AUXILIARIES_SIZE];
 WORD   fwGuidLights [WFS_SIU_GUIDLIGHTS_SIZE];
 LPSTR   lpszExtra;
 } WFSSIUENABLE, * LPWFSSIUENABLE;

fwSensors [...]
Specifies which of the Sensors that should report changes. A number of sensor types are defined below. Vendor specific sensors are defined starting from the end of the array. The maximum sensor index is WFS_SIU_SENSORS_MAX.

fwSensors [WFS_SIU_OPERATORSWITCH]
Specifies whether the Operator Switch should report whenever the switch changes the operating mode. Specified as one of the following flags:

Value Meaning

WFS_SIU_NO_CHANGE Do not change the current reporting status.

WFS_SIU_ENABLE_EVENT The Operators Switch should report whenever it changes mode from Run to Maintenance or Supervisor mode or vice versa.

WFS_SIU_DISABLE_EVENT The Operators Switch should not report any changes of it operating mode.

fwSensors [WFS_SIU_TAMPER]
Specifies whether the Tamper Sensor should report whenever someone tampers with the terminal. Specified as one of the following flags:

Value Meaning

WFS_SIU_NO_CHANGE Do not change the current reporting status.

WFS_SIU_ENABLE_EVENT The Tamper Sensor should report whenever it detects any tampering attempt.

WFS_SIU_DISABLE_EVENT The Tamper Sensor should not report any changes of its status.

fwSensors [WFS_SIU_INTTAMPER]
Specifies whether the internal Tamper Sensor should report whenever someone tampers with the internal alarm. Specified as one of the following flags:

Value Meaning

WFS_SIU_NO_CHANGE Do not change the current reporting status.

WFS_SIU_ENABLE_EVENT The Tamper Sensor should report whenever it detects any tampering attempt.

WFS_SIU_DISABLE_EVENT The Tamper Sensor should not report any changes of its status.

fwSensors [WFS_SIU_SEISMIC]
Specifies whether the Seismic Sensor should report whenever any seismic activity is detected. Specified as one of the following flags:

Value Meaning

WFS_SIU_NO_CHANGE Do not change the current reporting status.

WFS_SIU_ENABLE_EVENT The Seismic Sensor should report whenever it detects any seismic activity.

WFS_SIU_DISABLE_EVENT The Seismic Sensor should not report any changes of its status.

fwSensors [WFS_SIU_HEAT]
Specifies whether the Heat Sensor should report whenever any excessive heat is detected. Specified as one of the following flags:

Value Meaning

WFS_SIU_NO_CHANGE Do not change the current reporting status.

WFS_SIU_ENABLE_EVENT The Heat Sensor should report whenever it detects any excessive heat.

WFS_SIU_DISABLE_EVENT The Heat Sensor should not report any changes of its status.

fwSensors [WFS_SIU_PROXIMITY]
Specifies whether the Proximity Sensor should report whenever any movement is detected close to the terminal. Specified as one of the following flags:

Value Meaning

WFS_SIU_NO_CHANGE Do not change the current reporting status.

WFS_SIU_ENABLE_EVENT The Proximity Sensor should report whenever it detects any movement.

WFS_SIU_DISABLE_EVENT The Proximity Sensor should not report any changes of its status.

fwSensors [WFS_SIU_AMBLIGHT]
Specifies whether the Ambient Light Sensor should report whenever it detects changes in the ambient light. Specified as one of the following flags:

Value Meaning

WFS_SIU_NO_CHANGE Do not change the current reporting status.

WFS_SIU_ENABLE_EVENT The Ambient Light Sensor should report whenever it detects a change.

WFS_SIU_DISABLE_EVENT The Ambient Light Sensor should not report any change.

fwDoors [...]
Specifies which of the Doors that should report changes. A number of door types are defined below. Vendor specific doors are defined starting from the end of the array. The maximum door index is WFS_SIU_DOORS_MAX.

fwDoors [WFS_SIU_CABINET]
Specifies whether the Cabinet Doors sensor should report whenever the doors are opened, closed, bolted or locked. Specified as one of the following flags:

Value Meaning

WFS_SIU_NO_CHANGE Do not change the current reporting status.

WFS_SIU_ENABLE_EVENT The Cabinet Doors should report whenever the doors are opened, closed, locked or bolted.

WFS_SIU_DISABLE_EVENT The Cabinet Doors sensor should not report any changes of the doors status.

fwDoors [WFS_SIU_SAFE]
Specifies whether the Safe Doors should report whenever the doors are opened, closed, bolted or locked. Specified as one of the following flags:

Value Meaning

WFS_SIU_NO_CHANGE Do not change the current reporting status.

WFS_SIU_ENABLE_EVENT The Safe Doors should report whenever the doors are opened, closed, locked or bolted.

WFS_SIU_DISABLE_EVENT The Safe Doors should not report any changes of the doors status.

fwDoors [WFS_SIU_VANDALSHIELD]
Specifies whether the Vandal Shield should report whenever the shield changed position. Specified as one of the following flags:

Value Meaning

WFS_SIU_NO_CHANGE Do not change the current reporting status.

WFS_SIU_ENABLE_EVENT The Vandal Shield should report whenever the doors are opened or closed.

WFS_SIU_DISABLE_EVENT The Vandal Shield should not report any changes of the status.

fwIndicators [...]
Specifies which of the Status Indicators that should report changes. A number of Status Indicator types are defined below. Vendor specific indicators are defined starting from the end of the array. The maximum indicator index is WFS_SIU_INDICATORS_MAX.

fwIndicators [WFS_SIU_OPENCLOSE]
Specifies whether the Open/Closed Indicator should report whenever it is turned on (set to open) or turned off (set to closed). Specified as one of the following flags:

Value Meaning

WFS_SIU_NO_CHANGE Do not change the current reporting status.

WFS_SIU_ENABLE_EVENT The Open/Closed Indicator should report whenever it is turned on or off.

WFS_SIU_DISABLE_EVENT The Open/Closed Indicator should not report any changes of the indicator.

fwIndicators [WFS_SIU_FASCIALIGHT]
Specifies whether the Fascia Light should report whenever it is turned on or turned off. Specified as one of the following flags:

Value Meaning

WFS_SIU_NO_CHANGE Do not change the current reporting status.

WFS_SIU_ENABLE_EVENT The Fascia Light should report whenever it is turned on or off.

WFS_SIU_DISABLE_EVENT The Fascia Light should not report any changes.

fwIndicators [WFS_SIU_AUDIO]
Specifies whether the Audio Indicator should report whenever it is turned on or turned off. Specified as one of the following flags:

Value Meaning

WFS_SIU_NO_CHANGE Do not change the current reporting status.

WFS_SIU_ENABLE_EVENT The Audio Indicator should report whenever it is turned on or off.

WFS_SIU_DISABLE_EVENT The Audio Indicator should not report any changes.

fwIndicators [WFS_SIU_HEATING]
Specifies whether the Heating device should report whenever it is turned on or turned off. Specified as one of the following flags:

Value Meaning

WFS_SIU_NO_CHANGE Do not change the current reporting status.

WFS_SIU_ENABLE_EVENT The Heating device should report whenever it is turned on or off.

WFS_SIU_DISABLE_EVENT The Heating device should not report any changes.

fwAuxiliaries [...]
Specifies which of the Auxiliary Indicators that should report changes. A number of Auxiliary Indicator types are defined below. Vendor specific indicators are defined starting from the end of the array. The maximum indicator index is WFS_SIU_AUXILIARIES_MAX.

fwAuxiliaries[WFS_SIU_VOLUME]
Specifies whether the Volume control device should report whenever it is changed or not. Specified as one of the following flags:

Value Meaning

WFS_SIU_NO_CHANGE Do not change the current reporting status.

WFS_SIU_ENABLE_EVENT The Volume control device should report whenever it is changed.

WFS_SIU_DISABLE_EVENT The Volume control device should not report any changes.

fwAuxiliaries[WFS_SIU_UPS]
Specifies whether the UPS device should report whenever it is changed or not. Specified as one of the following flags:

Value Meaning

WFS_SIU_NO_CHANGE Do not change the current reporting status.

WFS_SIU_ENABLE_EVENT The UPS device should report whenever it is changed.

WFS_SIU_DISABLE_EVENT The UPS device should not report any changes.

fwGuidLights [...]
Specifies which of the Guidance Light Indicators should report whenever any of them changes its state. Specified as one of the following flags:

Value Meaning

WFS_SIU_NO_CHANGE Do not change the current reporting status.

WFS_SIU_ENABLE_EVENT The Light Indicators should report whenever any of them changes its state.

WFS_SIU_DISABLE_EVENT The Light Indicators should not report any changes of their states.

fwGuidLights [WFS_SIU_CARDUNIT]
Specifies whether the Guidance Light Indicator on the Card Unit (IDC) should report whenever it changes status.

fwGuidLights [WFS_SIU_PINPAD]
Specifies whether the Guidance Light Indicator on the PIN pad unit should report whenever it changes status.

fwGuidLights [WFS_SIU_NOTESDISPENSER]
Specifies whether the Guidance Light Indicator on the note dispenser unit should report whenever it changes status.

fwGuidLights [WFS_SIU_COINDISPENSER]
Specifies whether the Guidance Light Indicator on the coin dispenser unit should report whenever it changes status.

fwGuidLights [WFS_SIU_RECEIPTPRINTER]
Specifies whether the Guidance Light Indicator on the receipt printer unit should report whenever it changes status.

fwGuidLights [WFS_SIU_PASSBOOKPRINTER]
Specifies whether the Guidance Light Indicator on the passbook printer unit should report whenever it changes status.

fwGuidLights [WFS_SIU_ENVDEPOSITORY]
Specifies whether the Guidance Light Indicator on the envelope depository unit should report whenever it changes status.

fwGuidLights [WFS_SIU_CHEQUEUNIT]
Specifies whether the Guidance Light Indicator on the cheque processing unit should report whenever it changes status.

fwGuidLights [WFS_SIU_BILLACCEPTOR]
Specifies whether the Guidance Light Indicator on the bill acceptor unit should report whenever it changes status.

fwGuidLights [WFS_SIU_ENVDISPENSER]
Specifies whether the Guidance Light Indicator on the envelope dispenser unit should report whenever it changes status.

lpszExtra
Specifies a list of vendor-specific, or any other extended, information. The information is passed as a series of "key=value" strings so that it is easily extensible by service providers. Each string will be null-terminated, with the final string terminating with two null characters.

Output Param None.

Error Codes The following additional error codes can be generated by this command:

Value Meaning

WFS_ERR_SIU_INVALID_PORT An attempt to enable or disable events to a port was invalid because the port does not exist.

WFS_ERR_SIU_SYNTAX The command was invoked with incorrect input data. E.g. an attempt to both enable and disable events to the same port was made.

Events The following additional events can be generated by this command:

Value Meaning

WFS_EXEE_SIU_PORT_ERROR A error occurred while enabling or disabling events on one or more ports.

Comments No action has been taken if this command returns an error. If a hardware error occurs while executing the command, the command will return OK, but execute event(s) will be generated which indicate(s) the port(s) which have failed.


4.2 WFS_CMD_SIU_SET_PORTS

Description This command is used to set or clear one or more output ports (indicators) in the Sensors and Indicators Unit.

Input Param LPWFSSIUSETPORTS lpSetPorts;

typedef struct _wfs_siu_set_ports
 {
 WORD   fwDoors [WFS_SIU_DOORS_SIZE];
 WORD   fwIndicators [WFS_SIU_INDICATORS_SIZE];
 WORD   fwAuxiliaries [WFS_SIU_AUXILIARIES_SIZE];
 WORD   fwGuidLights [WFS_SIU_GUIDLIGHTS_SIZE];
 LPSTR   lpszExtra;
 } WFSSIUSETPORTS, * LPWFSSIUSETPORTS;

fwDoors [WFS_SIU_CABINET]
Specifies whether the Cabinet Doors should be bolted or unbolted. Specified as one of the following flags:

Value Meaning

WFS_SIU_NO_CHANGE Do not change the current status of the Cabinet doors.

WFS_SIU_BOLT The Cabinet doors are bolted.

WFS_SIU_UNBOLT The Cabinet doors are unbolted.

fwDoors [WFS_SIU_SAFE]
Specifies whether the Safe Doors should be bolted or unbolted. Specified as one of the following flags:

Value Meaning

WFS_SIU_NO_CHANGE Do not change the current status of the Safe doors.

WFS_SIU_BOLT The Safe doors are bolted.

WFS_SIU_UNBOLT The Safe doors are unbolted.

fwDoors [WFS_SIU_VANDALSHIELD]
Specifies whether the Vandal Shield should change position. Specified as one of the following flags:

Value Meaning

WFS_SIU_NO_CHANGE Do not change the current position of the Vandal shield.

WFS_SIU_OPEN The Vandal Shield is opened.

WFS_SIU_SERVICE The Vandal Shield is set in service position.

WFS_SIU_KEYBOARD The Vandal Shield is set in position that permits access to the keyboard.

WFS_SIU_CLOSED The Vandal Shield is closed.

fwIndicators [WFS_SIU_OPENCLOSE]
Specifies whether the Open/Closed Indicator should show Open or Close to a consumer. Specified as one of the following flags:

Value Meaning

WFS_SIU_NO_CHANGE Do not change the current status of the indicator.

WFS_SIU_CLOSED The indicator is changed to show that the terminal is closed for a consumer.

WFS_SIU_OPEN The indicator is changed to show that the terminal is open to be used by a consumer.

fwIndicators [WFS_SIU_FASCIALIGHT]
Specifies whether the Fascia Lights should be turned on or off. Specified as one of the following flags:

Value Meaning

WFS_SIU_NO_CHANGE Do not change the current status of the light.

WFS_SIU_OFF The Fascia Light is turned off.

WFS_SIU_ON The Fascia Light is turned on.

fwIndicators [WFS_SIU_AUDIO]
Specifies whether the Audio Indicator should be turned on or off. Specified as one of the following flags of type A and B, or as WFS_SIU_CONTINUOUS in combination with one of the flags of type B:

Value Meaning Type

WFS_SIU_NO_CHANGE | Do not change the current status of the beeper. | A
WFS_SIU_OFF | The Audio Indicator is turned off. | A
WFS_SIU_KEYPRESS | The Audio Indicator sounds a key click signal. | B
WFS_SIU_EXCLAMATION | The Audio Indicator sounds a exclamation signal. | B
WFS_SIU_WARNING | The Audio Indicator sounds a warning signal. | B
WFS_SIU_ERROR | The Audio Indicator sounds a error signal. | B
WFS_SIU_CRITICAL | The Audio Indicator sounds a critical error signal. | B
WFS_SIU_CONTINUOUS | The Audio Indicator sound is turned on continuously. | C

fwIndicators [WFS_SIU_HEATING]
Specifies whether the internal Heating device should be turned on or off. Specified as one of the following flags:

Value Meaning

WFS_SIU_NO_CHANGE Do not change the current status of the light.

WFS_SIU_OFF The Heating is turned off.

WFS_SIU_ON The Heating is turned on.

fwAuxiliaries [WFS_SIU_VOLUME]
Specifies whether the value of the volume control should be changed or not. If so, the value of volume control is defined in an interval from 1 to 1000 were 1 is the lowest volume level and 1000 is the highest volume level. Specified as one of the following values:

Value Meaning

WFS_SIU_NO_CHANGE Do not change the current status of the light.

1, ..., 1000 The volume level. This field is handled as an unsigned short. If a value greater than 1000 is used, the provider will map the value to 1000.

fwAuxiliaries [WFS_SIU_UPS]
Specifies whether the UPS device should be engaged or disengaged. The UPS device should not be engaged when the charge level is low. Specified as one of the following flags:

Value Meaning

WFS_SIU_NO_CHANGE Do not change the current status of the UPS device.

WFS_SIU_ENGAGE Engage the UPS.

WFS_SIU_DISENGAGE Disengage the UPS.

fwGuidLights [...]
Specifies whether the Guidance Light Indicators should be turned on or off, or if they should flash. All member elements of the Guidance Lights structure can be specified as one of the following values:

Value Meaning

WFS_SIU_NO_CHANGE | Do not change the current status of the Light Indicator.
WFS_SIU_OFF | The Light Indicator is turned off.
WFS_SIU_SLOW_FLASH | The Light Indicator is set to flash slowly.
WFS_SIU_MEDIUM_FLASH | The light is blinking medium frequency.
WFS_SIU_QUICK_FLASH | The Light Indicator is set to flash quickly.
WFS_SIU_CONTINUOUS | The Light Indicator is turned on continuously (steady).

fwGuidLights [WFS_SIU_CARDUNIT]
Specifies the state of the Guidance Light Indicator on the Card Unit (IDC).

fwGuidLights [WFS_SIU_PINPAD]
Specifies the state of the Guidance Light Indicator on the PIN pad unit.

fwGuidLights [WFS_SIU_NOTESDISPENSER]
Specifies the state of the Guidance Light Indicator on the note dispenser unit.

fwGuidLights [WFS_SIU_COINDISPENSER]
Specifies the state of the Guidance Light Indicator on the coin dispenser unit.

fwGuidLights [WFS_SIU_RECEIPTPRINTER]
Specifies the state of the Guidance Light Indicator on the receipt printer unit.

fwGuidLights [WFS_SIU_PASSBOOKPRINTER]
Specifies the state of the Guidance Light Indicator on the passbook printer unit.

fwGuidLights [WFS_SIU_ENVDEPOSITORY]
Specifies the state of the Guidance Light Indicator on the envelope depository unit.

fwGuidLights [WFS_SIU_CHEQUEUNIT]
Specifies the state of the Guidance Light Indicator on the cheque processing unit.

fwGuidLights [WFS_SIU_BILLACCEPTOR]
Specifies the state of the Guidance Light Indicator on the bill acceptor unit.

fwGuidLights [WFS_SIU_ENVDISPENSER]
Specifies the state of the Guidance Light Indicator on the envelope dispenser unit.

lpszExtra
Specifies a list of vendor-specific, or any other extended, information. The information is passed as a series of "key=value" strings so that it is easily extensible by service providers. Each string will be null-terminated, with the final string terminating with two null characters.

Output Param None.

Error Codes The following additional error codes can be generated by this command:

Value Meaning

WFS_ERR_SIU_INVALID_PORT An attempt to set a port to a new value was invalid because the port does not exist or the port is pre-configured as an input port.

WFS_ERR_SIU_SYNTAX The command was invoked with incorrect input data.

Events The following additional events can be generated by this command:

Value Meaning

WFS_EXEE_SIU_PORT_ERROR An error occurred while attempting to set or clear one or more output ports (indicators).

Comments No action has been taken if this command returns an error. If a hardware error occurs while executing the command, the command will return OK, but execute event(s) will be generated which indicate(s) the port(s) which have failed.


4.3 WFS_CMD_SIU_SET_DOOR

Description This command is used to set the status of one of the Doors.

Input Param LPWFSSIUSETDOOR lpSetDoor;

typedef struct _wfs_siu_set_door
 {
 WORD   wDoor;
 WORD   fwCommand;
 } WFSSIUSETDOOR, * LPWFSSIUSETDOOR;

wDoor
Specifies the index of the Door to set as one of the following values:

Value Meaning

WFS_SIU_CABINET Bolt/unbolt the Cabinet doors.

WFS_SIU_SAFE Bolt/unbolt the Safe doors.

WFS_SIU_VANDALSHIELD Set position of the Vandal Shield.

fwCommand
Specifies if the Cabinet or Safe doors should be bolted or unbolted or if the position of the Vandal Shield should be changed, as one of the following flags:

Value Meaning

WFS_SIU_BOLT Bolt the Safe- or Cabinet doors.

WFS_SIU_UNBOLT Unbolt the Safe- or Cabinet doors.

WFS_SIU_OPEN Open the Vandal Shield.

WFS_SIU_SERVICE Position the Vandal Shield in service position.

WFS_SIU_KEYBOARD Position the Vandal Shield to permit access to the keyboard.

WFS_SIU_CLOSED Close the Vandal Shield.

See WFS_CMD_SIU_SET_PORTS command for a detailed description.

Output Param None.

Error Codes The following additional error codes can be generated by this command:

Value Meaning

WFS_ERR_SIU_INVALID_PORT An attempt to set a port to a new value was invalid because the port does not exist or the port is pre-configured as an input port.

WFS_ERR_SIU_SYNTAX The command was invoked with incorrect input data.

WFS_ERR_SIU_PORT_ERROR A hardware error occurred while executing the command.

Events The following additional events can be generated by this command:

Value Meaning

WFS_EXEE_SIU_PORT_ERROR An error occurred while attempting to set the status of the door.

Comments None.


4.4 WFS_CMD_SIU_SET_INDICATOR

Description This command is used to set the status of an Indicator.

Input Param LPWFSSIUSETINDICATOR lpSetIndicator;

typedef struct _wfs_siu_set_indicator
 {
 WORD   wIndicator;
 WORD   fwCommand;
 } WFSSIUSETINDICATOR, * LPWFSSIUSETINDICATOR;

wIndicator
Specifies the index of the Status Indicator to set as one of the following values:

Value Meaning

WFS_SIU_OPENCLOSE Set Open/Close indicator for the consumer.

WFS_SIU_FASCIALIGHT Turn on/off the fascia light.

WFS_SIU_AUDIO Turn on/off the audio indicator.

WFS_SIU_HEATING Turn on/off the heating device.

fwCommand
Specifies the commands for the open/close indicator, fascia light, audio indicator and heating device, as one of the following flags:

Value Meaning

WFS_SIU_CLOSED The Open/Close indicator is changed to show that the terminal is closed for a consumer.

WFS_SIU_OPEN The Open/Close indicator is changed to show that the terminal is open to be used by a consumer.

WFS_SIU_OFF The Audio Indicator, Fascia Light or Heating is turned off.

WFS_SIU_ON The Fascia Light or Heating is turned on.

WFS_SIU_KEYPRESS The Audio Indicator sounds a key click signal.

WFS_SIU_EXCLAMATION The Audio Indicator sounds a exclamation signal.

WFS_SIU_WARNING The Audio Indicator sounds a warning signal.

WFS_SIU_ERROR The Audio Indicator sounds a error signal.

WFS_SIU_CRITICAL The Audio Indicator sounds a critical error signal.

WFS_SIU_CONTINUOUS The Audio Indicator sound is turned on continuously.

See WFS_CMD_SIU_SET_PORTS command for a detailed description.

Output Param None.

Error Codes The following additional error codes can be generated by this command:

Value Meaning

WFS_ERR_SIU_INVALID_PORT An attempt to set a port to a new value was invalid because the port does not exist or the port is pre-configured as an input port.

WFS_ERR_SIU_SYNTAX The command was invoked with incorrect input data.

WFS_ERR_SIU_PORT_ERROR A hardware error occurred while executing the command.

Events The following additional events can be generated by this command:

Value Meaning

WFS_EXEE_SIU_PORT_ERROR An error occurred while attempting to set the status of the indicator.

Comments None.


4.5 WFS_CMD_SIU_SET_AUXILIARY

Description This command is used to set the status of an Auxiliary indicator.

Input Param LPWFSSIUSETAUXILIARY lpSetAuxiliary;

typedef struct _wfs_siu_set_auxiliary
 {
 WORD   wAuxiliary;
 WORD   fwCommand;
 } WFSSIUSETAUXILIARY, * LPWFSSIUSETAUXILIARY;

wAuxiliary
Specifies the index of the Auxiliary indicator to set as one of the following values:

Value Meaning

WFS_SIU_VOLUME Set the value of the volume control.

WFS_SIU_UPS Set the value of the UPS.

fwCommand
It specifies the values for the volume control or the command to the UPS device. Specified as one of the following values:

Value Meaning

1, ..., 1000 The volume level. This field is handled as an unsigned short. If a value greater than 1000 is used, the provider will map the value to 1000.

WFS_SIU_ENGAGE Engage the UPS.

WFS_SIU_DISENGAGE Disengage the UPS.

See WFS_CMD_SIU_SET_PORTS command for a detailed description.

Output Param None.

Error Codes The following additional error codes can be generated by this command:

Value Meaning

WFS_ERR_SIU_INVALID_PORT An attempt to set a port to a new value was invalid because the port does not exist or the port is pre-configured as an input port.

WFS_ERR_SIU_SYNTAX The command was invoked with incorrect input data.

WFS_ERR_SIU_PORT_ERROR A hardware error occurred while executing the command.

Events The following additional events can be generated by this command:

Value Meaning

WFS_EXEE_SIU_PORT_ERROR An error occurred while attempting to set the status of the auxiliary indicator.

Comments None.


4.6 WFS_CMD_SIU_SET_GUIDLIGHT

Description This command is used to set the status of a Guidance Light.

Input Param LPWFSSIUSETGUIDLIGHT lpSetGuidLight;

typedef struct _wfs_siu_set_guidlight
 {
 WORD   wGuidLight;
 WORD   fwCommand;
 } WFSSIUSETGUIDLIGHT, * LPWFSSIUSETGUIDLIGHT;

wGuidLights
Specifies the index of the Guidance Light to set as one of the following values:

Value Meaning

WFS_SIU_CARDUNIT Set the state of the Guidance Light Indicator on the Card Unit (IDC).

WFS_SIU_PINPAD Set the state of the Guidance Light Indicator on the PIN pad unit.

WFS_SIU_NOTESDISPENSER Set the state of the Guidance Light Indicator on the note dispenser unit.

WFS_SIU_COINDISPENSER Set the state of the Guidance Light Indicator on the coin dispenser unit.

WFS_SIU_RECEIPTPRINTER Set the state of the Guidance Light Indicator on the receipt printer unit.

WFS_SIU_PASSBOOKPRINTER Set the state of the Guidance Light Indicator on the passbook printer unit.

WFS_SIU_ENVDEPOSITORY Set the state of the Guidance Light Indicator on the envelope depository unit.

WFS_SIU_CHEQUEUNIT Set the state of the Guidance Light Indicator on the cheque processing unit.

WFS_SIU_BILLACCEPTOR Set the state of the Guidance Light Indicator on the bill acceptor unit.

WFS_SIU_ENVDISPENSER Set the state of the Guidance Light Indicator on the envelope dispenser unit.

fwCommand
Specifies the state of the Guidance Light indicators, as one of the following flags:

Value Meaning

WFS_SIU_OFF The Light Indicator is turned off.

WFS_SIU_SLOW_FLASH The Light Indicator is set to flash slowly.

WFS_SIU_MEDIUM_FLASH The light is blinking medium frequency.

WFS_SIU_QUICK_FLASH The Light Indicator is set to flash quickly.

WFS_SIU_CONTINUOUS The Light Indicator is turned on continuously (steady).

See WFS_CMD_SIU_SET_PORTS command for a detailed description.

Output Param None.

Error Codes The following additional error codes can be generated by this command:

Value Meaning

WFS_ERR_SIU_INVALID_PORT An attempt to set a port to a new value was invalid because the port does not exist or the port is pre-configured as an input port.

WFS_ERR_SIU_SYNTAX The command was invoked with incorrect input data.

Events The following additional events can be generated by this command:

Value Meaning

WFS_EXEE_SIU_PORT_ERROR An error occurred while attempting to set or clear one or more output ports (indicators).

Comments None.


5.1 WFS_SRVE_SIU_PORT_STATUS

Description This event id is used to specify that a port has changed its state, due to the result of a command or to some external condition. Reporting of this event is controlled by the WFS_CMD_SIU_ENABLE_EVENTS command. Event reporting is disabled as a default situation.

Event Param LPWFSSIUPORTEVENT lpPortEvent;

typedef struct _wfs_siu_port_event
{
WORD wPortType;
WORD wPortIndex;
WORD wPortStatus;
LPSTR lpszExtra;
 } WFSSIUPORTEVENT, * LPWFSSIUPORTEVENT;

wPortType
Specifies the type of sensors and indicators that has changed state by one of the following flags:

Value Meaning

WFS_SIU_SENSORS A port in the input Sensors has changed state.

WFS_SIU_DOORS A port in the Door sensors has changed state.

WFS_SIU_INDICATORS A port in the Status Indicators has changed state.

WFS_SIU_AUXILIARIES A port in the Auxiliary Indicators has changed state.

WFS_SIU_GUIDLIGHTS A port in the Guidance Lights has changed state.

wPortIndex
Specifies the index of the port that has changed state by one of the following values:

Value Meaning

WFS_SIU_OPERATORSWITCH The Operator Switch has changed its state.

WFS_SIU_TAMPER The Tamper Sensor has changed its state.

WFS_SIU_INTTAMPER The internal Tamper Sensor has changed its state.

WFS_SIU_SEISMIC The Seismic Sensor has changed its state.

WFS_SIU_HEAT The Heat Sensor has changed its state.

WFS_SIU_PROXIMITY The Proximity Sensor has changed its state.

WFS_SIU_AMBLIGHT The Ambient Light Sensor has changed its state.

WFS_SIU_CABINET The Cabinet Doors have changed their state.

WFS_SIU_SAFE The Safe Doors have changed their state.

WFS_SIU_VANDALSHIELD The Vandal Shield has changed its state.

WFS_SIU_OPENCLOSE The Open/Close Indicator state has changed.

WFS_SIU_FASCIALIGHT The Fascia Light state has changed.

WFS_SIU_AUDIO The Audio Indicator state has changed.

WFS_SIU_HEATING The Heating device state has changed.

WFS_SIU_VOLUME The Volume control device has changed its value.

WFS_SIU_UPS The UPS device state has changed.

WFS_SIU_CARDUNIT The Guidance Light state for the card unit has changed.

WFS_SIU_PINPAD The Guidance Light state for the PIN pad unit has changed.

WFS_SIU_NOTESDISPENSER The Guidance Light state for the note dispenser unit has changed.

WFS_SIU_COINDISPENSER The Guidance Light state for the coin dispenser unit has changed.

WFS_SIU_RECEIPTPRINTER The Guidance Light state for the receipt printer unit has changed.

WFS_SIU_PASSBOOKPRINTER The Guidance Light state for the passbook printer unit has changed.

WFS_SIU_ENVDEPOSITORY The Guidance Light state for the envelope depository unit has changed.

WFS_SIU_CHEQUEUNIT The Guidance Light state for the cheque unit has changed.

WFS_SIU_BILLACCEPTOR The Guidance Light state for the bill acceptor unit has changed.

WFS_SIU_ENVDISPENSER The Guidance Light state for the envelope dispenser unit has changed.

wPortStatus
Specifies the new state of the port indicated in the wPortEvent. See the WFS_INF_SIU_STATUS information command for the possible values.

lpszExtra
Specifies a list of vendor-specific, or any other extended, information. The information is returned as a series of "key=value" strings so that it is easily extensible by service providers. Each string will be null-terminated, with the final string terminating with two null characters.

Comments None.


5.2 WFS_EXEE_SIU_PORT_ERROR

Description This event id is used to specify that a port has detected an error.

Event Param LPWFSSIUPORTERROR pPortError;

typedef struct _wfs_siu_port_error
{
WORD wPortType;
WORD wPortIndex;
HRESULT PortError;
WORD wPortStatus;
LPSTR lpszExtra;
 } WFSSIUPORTERROR, * LPWFSSIUPORTERROR;

wPortType
Specifies the type of sensors and indicators that has detected an error by one of the following flags:

Value Meaning

WFS_SIU_SENSORS A port in the input Sensors has detected an error.

WFS_SIU_DOORS A port in the Door sensors has detected an error.

WFS_SIU_INDICATORS A port in the Status Indicators has detected an error.

WFS_SIU_AUXILIARIES A port in the Auxiliary Indicators has detected an error.

WFS_SIU_GUIDLIGHTS A port in the Guidance Lights has detected an error.

wPortIndex
Specifies the index of the port that has detected an error by one of the following values:

Value Meaning

WFS_SIU_OPERATORSWITCH The Operator Switch has detected an error.

WFS_SIU_TAMPER The Tamper Sensor has detected an error.

WFS_SIU_INTTAMPER The internal Tamper Sensor has detected an error.

WFS_SIU_SEISMIC The Seismic Sensor has detected an error.

WFS_SIU_HEAT The Heat Sensor has detected an error.

WFS_SIU_PROXIMITY The Proximity Sensor has detected an error.

WFS_SIU_AMBLIGHT The Ambient Light Sensor has detected an error.

WFS_SIU_CABINET The Cabinet Doors have detected an error.

WFS_SIU_SAFE The Safe Doors have detected an error.

WFS_SIU_VANDALSHIELD The Vandal Shield has detected an error.

WFS_SIU_OPENCLOSE The Open/Close Indicator has detected an error.

WFS_SIU_FASCIALIGHT The Fascia Light state has detected an error.

WFS_SIU_AUDIO The Audio Indicator state has detected an error.

WFS_SIU_HEATING The Heating device state has detected an error.

WFS_SIU_VOLUME The Volume control device has detected an error.

WFS_SIU_UPS The UPS device has detected an error.

WFS_SIU_CARDUNIT The Guidance Light state for the card unit has detected an error.

WFS_SIU_PINPAD The Guidance Light state for the PIN pad unit has detected an error.

WFS_SIU_NOTESDISPENSER The Guidance Light state for the note dispenser unit has detected an error.

WFS_SIU_COINDISPENSER The Guidance Light state for the coin dispenser unit has detected an error.

WFS_SIU_RECEIPTPRINTER The Guidance Light state for the receipt printer unit has detected an error.

WFS_SIU_PASSBOOKPRINTER The Guidance Light state for the passbook printer unit has detected an error.

WFS_SIU_ENVDEPOSITORY The Guidance Light state for the envelope depository unit has detected an error.

WFS_SIU_CHEQUEUNIT The Guidance Light state for the cheque unit has detected an error.

WFS_SIU_BILLACCEPTOR The Guidance Light state for the bill acceptor unit has detected an error.

WFS_SIU_ENVDISPENSER The Guidance Light state for the envelope dispenser unit has detected an error.

PortError
Specifies the error of the port indicated in the wPortType and wPortIndex by one of the following values:

Value Meaning

WFS_ERR_SIU_INVALID_PORT An attempt to enable or disable events to a port was invalid because the port does not exist.

WFS_ERR_SIU_SYNTAX Syntax error in the input parameters. E.g. an attempt to both enable and disable events to the same port was made.

WFS_ERR_SIU_PORT_ERROR A hardware error occurred while executing a command.

wPortStatus
Specifies the new state of the port indicated in the wPortEvent. See the WFS_INF_SIU_STATUS information command for the possible values.

lpszExtra
Specifies a list of vendor-specific, or any other extended, information. The information is returned as a series of "key=value" strings so that it is easily extensible by service providers. Each string will be null-terminated, with the final string terminating with two null characters.

Comments None.


6. C - header file

/******************************************************************************
*                                                                             *
* xfssiu.h      WOSA/XFS - definitions                                        *
*               for the Sensors and Indicators Unit - services                *
*                                                                             *
*               Version 2.00 (11/11/96)                                       *
*                                                                             *
******************************************************************************/

#ifndef __INC_XFSSIU__H
#define __INC_XFSSIU__H

#ifdef __cplusplus
extern "C" {
#endif

#include <xfsapi.h>

/* be aware of alignment */
#pragma pack (push, 1)

/* values of WFSSIUCAPS.wClass */
#define     WFS_SERVICE_CLASS_SIU               (8)

#define     WFS_SERVICE_CLASS_NAME_SIU          “SIU“
#define     WFS_SERVICE_CLASS_VERSION_SIU       0x0002

#define     SIU_SERVICE_OFFSET                  (WFS_SERVICE_CLASS_SIU * 100)

/* SIU Info Commands */
#define     WFS_INF_SIU_STATUS                  (SIU_SERVICE_OFFSET + 1)
#define     WFS_INF_SIU_CAPABILITIES            (SIU_SERVICE_OFFSET + 2)

/* SIU Command Verbs */
#define     WFS_CMD_SIU_ENABLE_EVENTS           (SIU_SERVICE_OFFSET + 1)
#define     WFS_CMD_SIU_SET_PORTS               (SIU_SERVICE_OFFSET + 2)
#define     WFS_CMD_SIU_SET_DOOR                (SIU_SERVICE_OFFSET + 3)
#define     WFS_CMD_SIU_SET_INDICATOR           (SIU_SERVICE_OFFSET + 4)
#define     WFS_CMD_SIU_SET_AUXILIARY           (SIU_SERVICE_OFFSET + 5)
#define     WFS_CMD_SIU_SET_GUIDLIGHT           (SIU_SERVICE_OFFSET + 6)

/* SIU Messages */
#define     WFS_SRVE_SIU_PORT_STATUS            (SIU_SERVICE_OFFSET + 1)
#define     WFS_EXEE_SIU_PORT_ERROR             (SIU_SERVICE_OFFSET + 2)

/* Values of WFSSIUSTATUS.fwDevice */
#define     WFS_SIU_DEVONLINE                   WFS_STAT_DEVONLINE
#define     WFS_SIU_DEVOFFLINE                  WFS_STAT_DEVOFFLINE
#define     WFS_SIU_DEVPOWEROFF                 WFS_STAT_DEVPOWEROFF
#define     WFS_SIU_DEVBUSY                     WFS_STAT_DEVBUSY
#define     WFS_SIU_DEVNODEVICE                 WFS_STAT_DEVNODEVICE
#define     WFS_SIU_DEVHWERROR                  WFS_STAT_DEVHWERROR
#define     WFS_SIU_DEVUSERERROR                WFS_STAT_DEVUSERERROR

/* Size and max index of fwSensors array */
#define     WFS_SIU_SENSORS_SIZE                (32)
#define     WFS_SIU_SENSORS_MAX                 (WFS_SIU_SENSORS_SIZE - 1)

/* Size and max index of fwDoors array */
#define     WFS_SIU_DOORS_SIZE                  (16)
#define     WFS_SIU_DOORS_MAX                   (WFS_SIU_DOORS_SIZE - 1)

/* Size and max index of fwIndicators array */
#define     WFS_SIU_INDICATORS_SIZE             (16)
#define     WFS_SIU_INDICATORS_MAX              (WFS_SIU_INDICATORS_SIZE - 1)

/* Size max index of fwAuxiliaries array */
#define     WFS_SIU_AUXILIARIES_SIZE            (16)
#define     WFS_SIU_AUXILIARIES_MAX             (WFS_SIU_AUXILIARIES_SIZE - 1)

/* Size and max index of fwGuidLights array */
#define     WFS_SIU_GUIDLIGHTS_SIZE             (16)
#define     WFS_SIU_GUIDLIGHTS_MAX              (WFS_SIU_GUIDLIGHTS_SIZE - 1)

/* Indices of WFSSIUSTATUS.fwSensors [...]
          WFSSIUCAPS.fwSensors [...]
          WFSSIUENABLE.fwSensors [...]
          WFSSIUPORTEVENT.wPortIndex
          WFSSIUPORTERROR.wPortIndex */
#define     WFS_SIU_OPERATORSWITCH              (0)
#define     WFS_SIU_TAMPER                      (1)
#define     WFS_SIU_INTTAMPER                   (2)
#define     WFS_SIU_SEISMIC                     (3)
#define     WFS_SIU_HEAT                        (4)
#define     WFS_SIU_PROXIMITY                   (5)
#define     WFS_SIU_AMBLIGHT                    (6)

/* Indices of WFSSIUSTATUS.fwDoors [...]
           WFSSIUCAPS.fwDoors [...]
           WFSSIUENABLE.fwDoors [...]
           WFSSIUSETPORT.fwDoors [...]
           WFSSIUSETDOORS.wDoor
           WFSSIUPORTEVENT.wPortIndex
           WFSSIUPORTERROR.wPortIndex */
#define     WFS_SIU_CABINET                     (0)
#define     WFS_SIU_SAFE                        (1)
#define     WFS_SIU_VANDALSHIELD                (2)

/* Indices of WFSSIUSTATUS.fwIndicators [...]
           WFSSIUCAPS.fwIndicators [...]
           WFSSIUENABLE.fwIndicators [...]
           WFSSIUSETPORT.wIndicators [...]
           WFSSIUSETINDICATORS.wIndicator
           WFSSIUPORTEVENT.wPortIndex
           WFSSIUPORTERROR.wPortIndex */
#define     WFS_SIU_OPENCLOSE                   (0)
#define     WFS_SIU_FASCIALIGHT                 (1)
#define     WFS_SIU_AUDIO                       (2)
#define     WFS_SIU_HEATING                     (3)

/* Indices of WFSSIUSTATUS.fwAuxiliaries [...]
           WFSSIUCAPS.fwAuxiliaries [...]
           WFSSIUENABLE.fwAuxiliaries [...]
           WFSSIUSETPORT.wAuxiliaries [...]
           WFSSIUSETAUXILIARIES.wAuxiliary
           WFSSIUPORTEVENT.wPortIndex
           WFSSIUPORTERROR.wPortIndex */
#define     WFS_SIU_VOLUME                      (0)
#define     WFS_SIU_UPS                      (1)

/* Indices of WFSSIUSTATUS.fwGuidLights [...]
           WFSSIUCAPS.fwGuidLights [...]
           WFSSIUENABLE.fwGuidLights [...]
           WFSSIUSETPORT.wGuidLights [...]
           WFSSIUSETGUIDLIGHTS.wGuidLight
           WFSSIUPORTEVENT.wPortIndex
           WFSSIUPORTERROR.wPortIndex */
#define     WFS_SIU_CARDUNIT                    (0)
#define     WFS_SIU_PINPAD                      (1)
#define     WFS_SIU_NOTESDISPENSER              (2)
#define     WFS_SIU_COINDISPENSER               (3)
#define     WFS_SIU_RECEIPTPRINTER              (4)
#define     WFS_SIU_PASSBOOKPRINTER             (5)
#define     WFS_SIU_ENVDEPOSITORY               (6)
#define     WFS_SIU_CHEQUEUNIT                  (7)
#define     WFS_SIU_BILLACCEPTOR                (8)
#define     WFS_SIU_ENVDISPENSER                (9)

/* Values of WFSSIUSTATUS.fwSensors [...]
          WFSSIUSTATUS.fwDoors [...]
          WFSSIUSTATUS.fwIndicators [...]
          WFSSIUSTATUS.fwAuxiliaries [...]
          WFSSIUSTATUS.fwGuidLights [...]
          WFSSIUCAPS.fwSensors [...]
          WFSSIUCAPS.fwDoors [...]
          WFSSIUCAPS.fwIndicators [...]
          WFSSIUCAPS.fwAuxiliaries [...]
          WFSSIUCAPS.fwGuidLights [...] */
#define     WFS_SIU_NOT_AVAILABLE               (0x0000)
#define     WFS_SIU_AVAILABLE                   (0x0001)

/* Values of WFSSIUSTATUS.fwSensors [WFS_SIU_OPERATORSWITCH]
          WFSSIUCAPS.fwSensors [WFS_SIU_OPERATORSWITCH]
          WFSSIUPORTEVENT.fwPortStatus
          WFSSIUPORTERROR.fwPortStatus */
#define     WFS_SIU_RUN                         (0x0001)
#define     WFS_SIU_MAINTENANCE                 (0x0002)
#define     WFS_SIU_SUPERVISOR                  (0x0004)

/* Values of WFSSIUSTATUS.fwDoors [...]
          WFSSIUSTATUS.fwIndicators [WFS_SIU_OPENCLOSE]
          WFSSIUCAPS.fwDoors [...]
          WFSSIUCAPS.fwIndicators [WFS_SIU_OPENCLOSE]
          WFSSIUSETPORT.fwDoors [...]
          WFSSIUSETPORT.fwIndicators [WFS_SIU_OPENCLOSE]
          WFSSIUSETDOOR.wDoor
          WFSSIUSETINDICATOR.wCommand
          WFSSIUPORTEVENT.wPortStatus
          WFSSIUPORTERROR.wPortStatus */
#define     WFS_SIU_CLOSED                      (0x0001)
#define     WFS_SIU_OPEN                        (0x0002)
#define     WFS_SIU_LOCKED                      (0x0004)
#define     WFS_SIU_BOLTED                      (0x0008)
#define     WFS_SIU_SERVICE                     (0x0010)
#define     WFS_SIU_KEYBOARD                    (0x0020)
#define     WFS_SIU_AJAR                        (0x0040)
#define     WFS_SIU_JAMMED                      (0x0080)

/* Values of WFSSIUSTATUS.fwIndicators [WFS_SIU_AUDIO]
          WFSSIUSETPORT.fwIndicators [WFS_SIU_AUDIO]
          WFSSIUSETINDICATOR.wCommand
          WFSSIUPORTEVENT.wPortStatus
          WFSSIUPORTERROR.wPortStatus */
#define     WFS_SIU_KEYPRESS                    (0x0002)
#define     WFS_SIU_EXCLAMATION                 (0x0004)
#define     WFS_SIU_WARNING                     (0x0008)
#define     WFS_SIU_ERROR                       (0x0010)
#define     WFS_SIU_CRITICAL                    (0x0020)

/* Values of WFSSIUSTATUS.fwSensors [...]
          WFSSIUSTATUS.fwIndicators [...]
          WFSSIUSTATUS.fwGuidLights [...]
          WFSSIUCAPS.fwSensors [...]
          WFSSIUCAPS.fwIndicators [...]
          WFSSIUCAPS.fwGuidLights [...]
          WFSSIUSETPORT.fwIndicators [...]
          WFSSIUSETPORT.fwGuidLights [...]
          WFSSIUSETINDICATORS.fwCommand [...]
          WFSSIUSETGUIDLIGHTS.fwCommand [...]
          WFSSIUPORTEVENT.wPortStatus
          WFSSIUPORTERROR.wPortStatus */
#define     WFS_SIU_OFF                         (0x0001)
#define     WFS_SIU_ON                          (0x0002)
#define     WFS_SIU_SLOW_FLASH                  (0x0004)
#define     WFS_SIU_MEDIUM_FLASH                (0x0008)
#define     WFS_SIU_QUICK_FLASH                 (0x0010)
#define     WFS_SIU_CONTINUOUS                  (0x0080)

/* Values of WFSSIUSTATUS.fwSensors [WFS_SIU_PROXIMITY]
          WFSSIUPORTEVENT.wPortStatus
          WFSSIUPORTERROR.wPortStatus */
#define     WFS_SIU_PRESENT                     (0x0001)
#define     WFS_SIU_NOT_PRESENT                 (0x0002)

/* Values of WFSSIUSTATUS.fwSensors [WFS_SIU_AMBLIGHT]
          WFSSIUCAPS.fwSensors [WFS_SIU_AMBLIGHT]
          WFSSIUPORTEVENT.fwPortStatus
          WFSSIUPORTERROR.fwPortStatus */
#define     WFS_SIU_VERY_DARK                   (0x0001)
#define     WFS_SIU_DARK                        (0x0002)
#define     WFS_SIU_MEDIUM_LIGHT                (0x0004)
#define     WFS_SIU_LIGHT                       (0x0008)
#define     WFS_SIU_VERY_LIGHT                  (0x0010)

/* Values of WFSSIUSTATUS.fwAuxiliaries [WFS_SIU_UPS]
             WFSSIUCAPS.fwAuxiliaries [WFS_SIU_UPS]
WFSSIUPORTEVENT.wPortStatus
WFSSIUPORTERROR.wPortStatus */
#define WFS_SIU_LOW                      (0x0002)
#define WFS_SIU_ENGAGED                  (0x0004)
#define WFS_SIU_POWERING                 (0x0008)
#define WFS_SIU_RECOVERED                (0x0010)

/* Values of WFSSIUCAPS.fwType */
#define     WFS_SIU_SENSORS                     (0x0001)
#define     WFS_SIU_DOORS                       (0x0002)
#define     WFS_SIU_INDICATORS                  (0x0004)
#define     WFS_SIU_AUXILIARIES                  (0x0008)
#define     WFS_SIU_GUIDLIGHTS                  (0x0010)

/* Values of WFSSIUENABLE.fwSensors [...]
          WFSSIUENABLE.fwDoors [...]
          WFSSIUENABLE.fwIndicators [...]
          WFSSIUENABLE.fwAuxiliaries [...]
          WFSSIUENABLE.fwGuidLights [...]
          WFSSIUSETPORTS.fwDoors [...]
          WFSSIUSETPORTS.fwIndicators [...]
          WFSSIUSETPORTS.fwAuxiliaries [...]
          WFSSIUSETPORTS.fwGuidLights [...] */
#define     WFS_SIU_NO_CHANGE                   (0x0000)
#define     WFS_SIU_ENABLE_EVENT                (0x0001)
#define     WFS_SIU_DISABLE_EVENT               (0x0002)

/* Values of WFSSIUSETPORTS.fwDoors [...]
          WFSSIUSETDOORS.fwCommand [...] */
#define     WFS_SIU_BOLT                        (0x0001)
#define     WFS_SIU_UNBOLT                      (0x0002)

/* Values of WFSSIUSETPORTS.fwAuxiliaries [WFS_SIU_UPS]
      WFSSIUSETAUXILIARY.wAuxiliary [WFS_SIU_UPS] */
#define WFS_SIU_ENGAGE                   (0x0001)
#define WFS_SIU_DISENGAGE                (0x0002)

/* WOSA/XFS SIU Errors */

#define     WFS_ERR_SIU_INVALID_PORT            (-(SIU_SERVICE_OFFSET + 1))
#define     WFS_ERR_SIU_SYNTAX                  (-(SIU_SERVICE_OFFSET + 2))
#define     WFS_ERR_SIU_PORT_ERROR              (-(SIU_SERVICE_OFFSET + 3))

/*=================================================================*/
/* SIU Info Command Structures and variables */
/*=================================================================*/

typedef struct _wfs_siu_status
{
    WORD            fwDevice;
    WORD            fwSensors [WFS_SIU_SENSORS_SIZE];
    WORD            fwDoors [WFS_SIU_DOORS_SIZE];
    WORD            fwIndicators [WFS_SIU_INDICATORS_SIZE];
    WORD            fwAuxiliaries [WFS_SIU_AUXILIARIES_SIZE];
    WORD            fwGuidLights [WFS_SIU_GUIDLIGHTS_SIZE];
    LPSTR                       lpszExtra;
} WFSSIUSTATUS, * LPWFSSIUSTATUS;

typedef struct _wfs_siu_caps
{
    WORD            wClass;
    WORD            fwType;
    WORD            fwSensors [WFS_SIU_SENSORS_SIZE];
    WORD            fwDoors [WFS_SIU_DOORS_SIZE];
    WORD            fwIndicators [WFS_SIU_INDICATORS_SIZE];
    WORD            fwAuxiliaries [WFS_SIU_AUXILIARIES_SIZE];
    WORD            fwGuidLights [WFS_SIU_GUIDLIGHTS_SIZE];
    LPSTR           lpszExtra;
} WFSSIUCAPS, * LPWFSSIUCAPS;

/*=================================================================*/
/* SIU Execute Command Structures */
/*=================================================================*/

typedef struct _wfs_siu_enable
{
    WORD            fwSensors [WFS_SIU_SENSORS_SIZE];
    WORD            fwDoors [WFS_SIU_DOORS_SIZE];
    WORD            fwIndicators [WFS_SIU_INDICATORS_SIZE];
    WORD            fwAuxiliaries [WFS_SIU_AUXILIARIES_SIZE];
    WORD            fwGuidLights [WFS_SIU_GUIDLIGHTS_SIZE];
    LPSTR           lpszExtra;
} WFSSIUENABLE, * LPWFSSIUENABLE;

typedef struct _wfs_siu_set_ports
{
    WORD            fwDoors [WFS_SIU_DOORS_SIZE];
    WORD            fwIndicators [WFS_SIU_INDICATORS_SIZE];
    WORD            fwAuxiliaries [WFS_SIU_AUXILIARIES_SIZE];
    WORD            fwGuidLights [WFS_SIU_GUIDLIGHTS_SIZE];
    LPSTR           lpszExtra;
} WFSSIUSETPORTS, * LPWFSSIUSETPORTS;

typedef struct _wfs_siu_set_door
{
    WORD            wDoor;
    WORD            fwCommand;
} WFSSIUSETDOOR, * LPWFSSIUSETDOOR;

typedef struct _wfs_siu_set_indicator
{
    WORD            wIndicator;
    WORD            fwCommand;
} WFSSIUSETINDICATOR, * LPWFSSIUSETINDICATOR;

typedef struct _wfs_siu_set_auxiliary
{
    WORD            wAuxiliary;
    WORD            fwCommand;
} WFSSIUSETAUXILIARY, * LPWFSSIUSETAUXILIARY;

typedef struct _wfs_siu_set_guidlight
{
    WORD            wGuidLight;
    WORD            fwCommand;
} WFSSIUSETGUIDLIGHT, * LPWFSSIUSETGUIDLIGHT;

/*=================================================================*/
/* SIU Message Structures */
/*=================================================================*/

typedef struct _wfs_siu_port_event
{
    WORD            wPortType;
    WORD            wPortIndex;
    WORD            wPortStatus;
    LPSTR           lpszExtra;
} WFSSIUPORTEVENT, * LPWFSSIUPORTEVENT;

typedef struct _wfs_siu_port_error
{
    WORD            wPortType;
    WORD            wPortIndex;
    HRESULT         PortError;
    WORD            wPortStatus;
    LPSTR                       lpszExtra;
} WFSSIUPORTERROR, * LPWFSSIUPORTERROR;

/* restore alignment */
#pragma pack (pop)

#ifdef __cplusplus
}       /*extern "C"*/
#endif

#endif  /* __INC_XFSSIU__H */


Vendor Dependent Mode Device Class Interface

WOSA

(Windowsä Open Services Architecture)

Extensions for Financial Services

A Client-Server Architecture for Financial Enterprise Computing under Microsoft® Windows

Vendor Dependent Mode

Device Class Interface

–––––––––––––––––––––––––––––––––––

Programmer’s Reference

Revision 2.00

November 11, 1996

Developed by the members of the Banking Solutions Vendor Council


Table of Contents

1. Introduction
1.1 WOSA/XFS Service-Specific Programming

2. Vendor Dependent Mode

3. Info Commands
3.1 WFS_INF_VDM_STATUS

3.2 WFS_INF_VDM_CAPABILITIES

4. Execute Commands
4.1 WFS_CMD_VDM_ENTER_MODE_REQ

4.2 WFS_CMD_VDM_ENTER_MODE_ACK

4.2 WFS_CMD_VDM_EXIT_MODE_REQ

4.2 WFS_CMD_VDM_EXIT_MODE_ACK

5. Events
5.1 WFS_SRVE_VDM_ENTER_MODE_REQ

5.2 WFS_SRVE_VDM_EXIT_MODE_REQ

5.3 WFS_SYSE_VDM_MODEENTERED

5.4 WFS_SYSE_VDM_MODEEXITED

6. C-Header file


2. Vendor Dependent Mode

This specification describes the functionality of the services provided by the Vendor Dependent Mode (VDM) services under WOSA/XFS, by defining the service-specific commands that can be issued, using the WFSGetInfo, WFSAsyncGetInfo, WFSExecute and WFSAsyncExecute functions.

In all device classes there needs to be some method of going into a vendor specific mode to allow for capabilities which go beyond the scope of the current WOSA/XFS specifications. A typical usage of such a mode might be to handle some configuration or diagnostic type of function or perhaps perform some 'off-line' testing of the device. These functions are normally available on Self-Service devices in a mode traditionally referred to as Maintenance Mode or Supervisor Mode and usually require operator intervention. It is those vendor-specific functions not covered by (and not required to be covered by) WOSA/XFS Service Providers that will be available once the device is in Vendor-Dependent mode.

This service provides the mechanism for switching to and from Vendor Dependent Mode. The VDM Service Provider can be seen as the central point through which all Enter and Exit VDM requests are synchronised.

Entry into, or exit from, Vendor Dependent Mode can be initiated either by an application or by the VDM Service Provider itself. If initiated by an application, then this application needs to issue the appropriate command to request entry or exit. If initiated by the VDM Service Provider i.e. some vendor dependent switch, then these request commands are in-appropriate and not issued.

Once the entry request has been made, all registered applications will be notified of the entry request by an event message. These applications must attempt to close all open sessions with WOSA/XFS Service Providers as soon as possible and then issue an acknowledgement command to the VDM Service Provider when ready. Once all applications have acknowledged, the VDM Service Provider will issue event messages to these applications to indicate that the System is in Vendor Dependent Mode.

Similarly, once the exit request has been made all registered applications will be notified of the exit request by an event message. These applications must then issue an acknowledgement command to the VDM Service Provider immediately. Once all applications have acknowledged, the VDM Service Provider will issue event messages to these applications to indicate that the System has exited from Vendor Dependent Mode.

Thus, WOSA/XFS compliant applications that do not need the system to be in Vendor Dependent Mode, must comply with the following:

- Every WOSA/XFS application should open a session with the VDM ServiceProvider passing a valid ApplId and then register for all VDM entry and exit notices.

- Before opening any session with any other WOSA/XFS Service Provider, check the status of the VDM Service Provider. If Vendor Dependent Mode is not “Inactive”, do not open a session.

- When getting a VDM entry notice, close all open sessions with all other WOSA/XFS Service Providers as soon as possible and issue an acknowledgement for the entry to VDM.

- When getting a VDM exit notice, acknowledge at once.

- When getting a VDM exited notice, re-open any required sessions with other WOSA/XFS Service Providers.

VDM Entry triggered by WOSA/XFS Application

At time t0, status is “Inactive” and a request to Enter VDM arises from within the Application system.

At time t1, an Application Process/Thread/Function issues the CMD_ENTER_MODE_REQ Execute cmd.

Status then becomes “Enter Pending”.

At time t2, the VDM Service Provider issues the SRVE_ENTER_MODE_REQ Event to all registered applications.

At time t3, the VDM Service Provider receives a CMD_ENTER_MODE_ACK Execute Commandfrom a WOSA/XFS Compliant Application

At time t4, the VDM Service Provider receives a CMD_ENTER_MODE_ACK Execute Commandfrom another WOSA/XFS Compliant Application

At time t5, the VDM Service Provider receives a CMD_ENTER_MODE_ACK Execute Commandfrom the last WOSA/XFS Compliant Application

At time t6, the VDM Service Provider issues the SYSE_MODEENTERED Event to all registered applications

Status then becomes “Active”.

The system is now in Vendor Dependent Mode and the Vendor Dependent Application can exclusively use the system devices in a Vendor Dependent manner.

VDM Entry triggered by Vendor Dependent Switch

At time t0, status is “Inactive” and a request to Enter VDM arises from within the Vendor System.

Status then becomes “Enter Pending”.

At time t1, the VDM Service Provider issues the SRVE_ENTER_MODE_REQ Event to all registered applications.

At time t2, the VDM Service Provider receives a CMD_ENTER_MODE_ACK Execute Commandfrom a WOSA/XFS Compliant Application

At time t3, the VDM Service Provider receives a CMD_ENTER_MODE_ACK Execute Commandfrom another WOSA/XFS Compliant Application

At time t4, the VDM Service Provider receives a CMD_ENTER_MODE_ACK Execute Commandfrom the last WOSA/XFS Compliant Application

At time t5, the VDM Service Provider issues the SYSE_MODEENTERED Event to all registered applications

Status then becomes “Active”.

The system is now in Vendor Dependent Mode and the Vendor Dependent Application can exclusively use the system devices in a Vendor Dependent manner.

VDM Exit triggered by WOSA/XFS Application

At time t0, status is “Active” and a request to Exit VDM arises from within the Application system.

At time t1, an Application Process/Thread/Function issues the CMD_EXIT_MODE_REQ Execute cmd.

Status then becomes “Exit Pending”.

At time t2, the VDM Service Provider issues the SRVE_EXIT_MODE_REQ Event to all registered applications.

At time t3, the VDM Service Provider receives a CMD_EXIT_MODE_ACK Execute Commandfrom a WOSA/XFS Compliant Application

At time t4, the VDM Service Provider receives a CMD_EXIT_MODE_ACK Execute Commandfrom another WOSA/XFS Compliant Application

At time t5, the VDM Service Provider receives a CMD_EXIT_MODE_ACK Execute Commandfrom the last WOSA/XFS Compliant Application

At time t6, the VDM Service Provider issues the SYSE_MODEEXITED Event to all registered applications

Status then becomes “Inactive”.

The system is now no longer in Vendor Dependent Mode and the WOSA/XFS Compliant Applications can re-open any required services with other WOSA/XFS Service Providers.

VDM Exit triggered by Vendor Dependent Switch

At time t0, status is “Active” and a request to Exit VDM arises from within the Vendor System.

Status then becomes “Exit Pending”.

At time t1, the VDM Service Provider issues the SRVE_EXIT_MODE_REQ Event to all registered applications.

At time t2, the VDM Service Provider receives a CMD_EXIT_MODE_ACK Execute Commandfrom a WOSA/XFS Compliant Application

At time t3, the VDM Service Provider receives a CMD_EXIT_MODE_ACK Execute Commandfrom another WOSA/XFS Compliant Application

At time t4, the VDM Service Provider receives a CMD_EXIT_MODE_ACK Execute Commandfrom the last WOSA/XFS Compliant Application

At time t5, the VDM Service Provider issues the SYSE_MODEEXITED Event to all registered applications.

Status then becomes “Inactive”.

The system is now no longer in Vendor Dependent Mode and the WOSA/XFS Compliant Applications can re-open any required services with other WOSA/XFS Service Providers.


3.1 WFS_INF_VDM_STATUS

Description This command indicates whether or not the system is in Vendor-Dependent Mode. It will also indicate which Applications have not responded to the VDM Request Enter Event or VDM Request Exit Event if the current Service status is WFS_VDM_ENTERPENDING or WFS_VDM_EXITPENDING respectively.

Input Param None.

Output Param LPWFSVDMSTATUS lpStatus;

typedef struct _wfs_vdm_status
{
WORD wDevice;
WORD wService;
LPWFSVDMAPPSTATUS * lppAppStatus;
LPSTR lpszExtra;
} WFSVDMSTATUS, * LPWFSVDMSTATUS;

wDevice
Specifies the status of the Vendor Dependent Mode Service Class. Status will be one of the following flags:

Value Meaning

WFS_VDM_DEVONLINE Vendor Dependent Mode service available.

WFS_VDM_DEVOFFLINE Vendor Dependent Mode service unavailable.

wService
Specifies the Service state as one of the following flags:

Value Meaning

WFS_VDM_ENTERPENDING Vendor Dependent Mode Enter Request pending.

WFS_VDM_ACTIVE Vendor Dependent Mode Active.

WFS_VDM_EXITPENDING Vendor Dependent Mode Exit Request pending.

WFS_VDM_INACTIVE Vendor Dependent Mode Inactive.

lppAppStatus
Pointer to a null-terminated array of pointers to Application Status structures:

typedef struct _wfs_vdm_appstatus
{
LPSTR lpszAppID;
WORD wAppStatus;
} WFSVDMAPPSTATUS, * LPWFSVDMAPPSTATUS;

lpszAppID
Application ID string

wAppStatus
Specifies whether the particular Application is ready for the System to enter or exit Vendor Dependent Mode. Values can be one of the following:

Value Meaning

WFS_VDM_ENTERPENDING Application not yet ready to Enter VDM.

WFS_VDM_ACTIVE Application ready to Enter VDM.

WFS_VDM_EXITPENDING Application not yet ready to Exit VDM.

WFS_VDM_INACTIVE Application ready to Exit VDM.

lpszExtra
Specifies a list of vendor-specific, or any other extended, information. The information is returned as a series of "key=value" strings so that it is easily extendable by service providers. Each string will be null-terminated, with the final string terminating with two null characters.

Error Codes There are no additional error codes generated by this command.

Comments Applications which require or expect specific information to be present in the lpszExtra parameter may not be device or vendor-independent.


3.2 WFS_INF_VDM_CAPABILITIES

Description This command is used to retrieve the capabilities of the VDM Service

Input Param None.

Output Param LPWFSVDMCAPS lpCaps;

typedef struct _wfs_vdm_caps
{
WORD wClass;
LPSTR lpszExtra;
} WFSVDMCAPS, * LPWFSVDMCAPS;
 wClass
Specifies the logical service class, value is:
WFS_SERVICE_CLASS_VDM

lpszExtra
Specifies a list of vendor-specific, or any other extended, information. The information is returned as a series of "key=value" strings so that it is easily extendable by service providers. Each string will be null-terminated, with the final string terminating with two null characters.

Error Codes There are no additional error codes generated by this command.

Comments Applications which require or expect specific information to be present in the lpszExtra parameter may not be device or vendor-independent.


4.1 WFS_CMD_VDM_ENTER_MODE_REQ

Description This command is issued by an application to indicate a logical request to enter Vendor Dependent Mode. The VDM Service Provider will then indicate the request to all registered applications by sending a WFS_SRVE_VDM_ENTER_MODE_REQ Event message and then wait for an acknowledgement back from each registered application before putting the system into Vendor Dependent Mode. The Service Class status will change to WFS_VDM_ENTERPENDING on receipt of this command and will prevail until all applications have acknowledged, at which time the status will change to WFS_VDM_ACTIVE and the WFS_CMD_VDM_ENTER_MODE_REQ completes.

If the command fails when the status is WFS_VDM_ENTERPENDING, the status is changed to WFS_VDM_INACTIVE and a WFS_SYSE_VDM_MODEEXITED Event message is sent to all registered applications.

Input Param None.

Output Param None.

Error Codes There are no additional error codes returned by this command.

Events The following additional events can be generated by this command:

Value Meaning

WFS_SRVE_VDM_ENTER_MODE_REQ Request to enter VDM Mode.

WFS_SYSE_VDM_MODEENTERED The system has entered VDM.

WFS_SYSE_VDM_MODEEXITED The system has exited VDM.

Comments None.


4.2 WFS_CMD_VDM_ENTER_MODE_ACK

Description This command is issued by a registered application as an acknowledgement to the WFS_SRVE_VDM_ENTER_MODE_REQ Event message and it indicates that the application is ready for the system to enter Vendor Dependent Mode. Completion of this command is immediate.

Input Param None.

Output Param None.

Error Codes There are no additional error codes returned by this command.

Events There are no additional events generated by this command.

Comments None.


4.3 WFS_CMD_VDM_EXIT_MODE_REQ

Description This command is issued by an application to indicate a logical request to exit Vendor Dependent Mode. The VDM Service Provider will then indicate the request to all registered applications by sending a WFS_SRVE_VDM_EXIT_MODE_REQ Event message and then wait for an acknowledgement back from each registered application before removing the system from Vendor Dependent Mode. The Service Class status will change to WFS_VDM_EXITPENDING on receipt of this command and will prevail until all applications have acknowledged, at which time the status will change to WFS_VDM_INACTIVE and the WFS_CMD_VDM_EXIT_MODE_REQ completes.

If the command fails when the status is WFS_VDM_EXITPENDING, the status is changed to WFS_VDM_ACTIVE and a WFS_SYSE_VDM_MODEENTERED Event message is sent to all registered applications.

Input Param None.

Output Param None.

Error Codes There are no additional error codes returned by this command.

Events The following additional events can be generated by this command:

Value Meaning

WFS_SRVE_VDM_EXIT_MODE_REQ Request to exit VDM Mode.

WFS_SYSE_VDM_MODEENTERED The system has entered VDM.

WFS_SYSE_VDM_MODEEXITED The system has exited VDM.

Comments None.


4.4 WFS_CMD_VDM_EXIT_MODE_ACK

Description This command is issued by a registered application as an acknowledgement to the WFS_SRVE_VDM_EXIT_MODE_REQ Event message and it indicates that the application is ready for the system to exit Vendor Dependent Mode. Completion of this command is immediate.

Input Param None.

Output Param None.

Error Codes There are no additional error codes returned by this command.

Events There are no additional events generated by this command.

Comments None.


5.1 WFS_SRVE_VDM_ENTER_MODE_REQ

Description This service event is used to indicate the request to enter Vendor-Dependent Mode.

Event Param None.

Comments None.


5.2 WFS_SRVE_VDM_EXIT_MODE_REQ

Description This service event is used to indicate the request to exit Vendor-Dependent Mode.

Event Param None.

Comments None.


5.3 WFS_SYSE_VDM_MODEENTERED

Description This system event is used to indicate that the system has entered Vendor-Dependent Mode.

Event Param None.

Comments None.


5.4 WFS_SYSE_VDM_MODEEXITED

Description This system event is used to indicate that the system has exited Vendor-Dependent Mode.

Event Param None.

Comments None.


6. C-Header file

/**************************************************************************                                                                         *                                                                         *
* xfsvdm.h WOSA/XFS - Vendor Dependent Mode (VDM) definitions             *
*                                                                         *
*                     Version 2.00 (11/11/96)                             *
*                                                                         *
**************************************************************************/

#ifndef __INC_XFSVDM__H
#define __INC_XFSVDM__H

#ifdef __cplusplus
extern "C" {
#endif

#include <xfsapi.h>

/* be aware of alignment */
#pragma pack(push,1)

/* values of WFSVDMCAPS.wClass */

#define WFS_SERVICE_CLASS_VDM             (9)
#define WFS_SERVICE_CLASS_VERSION_VDM     (0x0002) /* Version 2.00 */
#define WFS_SERVICE_CLASS_NAME_VDM   “VDM”

#define VDM_SERVICE_OFFSET                (WFS_SERVICE_CLASS_VDM * 100)

/* VDM Info Commands */

#define WFS_INF_VDM_STATUS                (VDM_SERVICE_OFFSET + 1)
#define WFS_INF_VDM_CAPABILITIES          (VDM_SERVICE_OFFSET + 2)

/* VDM Execute Commands */

#define WFS_CMD_VDM_ENTER_MODE_REQ        (VDM_SERVICE_OFFSET + 1)
#define WFS_CMD_VDM_ENTER_MODE_ACK        (VDM_SERVICE_OFFSET + 2)
#define WFS_CMD_VDM_EXIT_MODE_REQ         (VDM_SERVICE_OFFSET + 3)
#define WFS_CMD_VDM_EXIT_MODE_ACK         (VDM_SERVICE_OFFSET + 4)

/* VDM Messages */

#define WFS_SRVE_VDM_ENTER_MODE_REQ       (VDM_SERVICE_OFFSET + 1)
#define WFS_SRVE_VDM_EXIT_MODE_REQ        (VDM_SERVICE_OFFSET + 2)
#define WFS_SYSE_VDM_MODEENTERED          (VDM_SERVICE_OFFSET + 3)
#define WFS_SYSE_VDM_MODEEXITED           (VDM_SERVICE_OFFSET + 4)

/* values of WFSVDMSTATUS.wDevice */
#define WFS_VDM_DEVONLINE                 WFS_STAT_DEVONLINE
#define WFS_VDM_DEVOFFLINE                WFS_STAT_DEVOFFLINE

/* values of WFSVDMSTATUS.wService */
#define WFS_VDM_ENTERPENDING              (0)
#define WFS_VDM_ACTIVE                    (1)
#define WFS_VDM_EXITPENDING               (2)
#define WFS_VDM_INACTIVE                  (3)

/*=================================================================*/
/* VDM Info Command Structures and variables */
/*=================================================================*/

typedef struct _wfs_vdm_appstatus
{
    LPSTR               lpszAppID;
    WORD                wAppStatus;
} WFSVDMAPPSTATUS, * LPWFSVDMAPPSTATUS;

typedef struct _wfs_vdm_status
{
     WORD               wDevice;
     WORD               wService;
     LPWFSVDMAPPSTATUS  *lppAppStatus;
     LPSTR              lpszExtra;
} WFSVDMSTATUS, * LPWFSVDMSTATUS;

typedef struct _wfs_vdm_caps
{
     WORD               wClass;
     LPSTR              lpszExtra;
} WFSVDMCAPS, * LPWFSVDMCAPS;

/*=================================================================*/
/* VDM Execute Command Structures */
/*=================================================================*/

/*=================================================================*/
/* VDM Message Structures */
/*=================================================================*/

/* restore alignment */
#pragma pack(pop)

#ifdef __cplusplus
} /*extern "C"*/
#endif

#endif  /* __INC_XFSVDM__H */


WOSA

(Windowsä Open Services Architecture)

Extensions for Financial Services

A Client-Server Architecture for Financial Enterprise Computing under Microsoft® Windows

Camera Device Class Interface

–––––––––––––––––––––––––––––––––––

Programmer’s Reference

Revision 2.00

November 11, 1996

Developed by the members of the Banking Solutions Vendor Council


Table of Contents

1. Introduction

1.1 WOSA/XFS Service-Specific Programming

2. Banking Cameras

3. Info Commands

3.1 WFS_INF_CAM_STATUS

3.2 WFS_INF_CAM_CAPABILITIES

4. Execute Commands

4.1 WFS_CMD_CAM_TAKE_PICTURE

5. Events

5.1 WFS_USRE_CAM_MEDIATHRESHOLD

5.2 WFS_EXEE_CAM_INVALIDDATA

6. C - Header file


2. Banking Cameras

This specification describes the functionality of the services provided by the Camera (CAM) services under WOSA/XFS, by defining the service-specific commands that can be issued, using the WFSGetInfo, WFSAsyncGetInfo, WFSExecute and WFSAsyncExecute functions.

Banking camera systems usually consist of a recorder, a video mixer and one or more cameras. If there are several cameras, each camera focuses a special place within the self-service area (eg. the room, the customer or the cash tray). By using the video mixer it can be decided, which of the cameras should take the next photo. Furthermore data can be given to be inserted in the photo (eg. date, time or bankcode).

If there is only one camera that can switch to take photos from different positions, it is presented by the service provider as a set of cameras, one for each of its possible positions.


3.1 WFS_INF_CAM_STATUS

Description This command reports the full range of information available, including the information that is provided by the service provider.

Input Param None.

Output Param LPWFSCAMSTATUS lpStatus;

typedef struct _wfs_cam_status
 {
 WORD   fwDevice;
 WORD   fwMedia;
 WORD   fwCameras[WFS_CAM_CAMERAS_SIZE];
 USHORT   usPictures;
 LPSTR   lpszExtra;
 } WFSCAMSTATUS, * LPWFSCAMSTATUS;

fwDevice
Specifies the state of the Camera device as one of the following flags:

Value Meaning

WFS_CAM_DEVONLINE The device is on-line. The device is present and operational (i.e. not busy processing a request and does not have a hardware error).

WFS_CAM_DEVOFFLINE The device is off-line. The device is present and powered on but it is not operational (e.g. a switch may have been used to change it to an off-line state).

WFS_CAM_DEVPOWEROFF The device is powered off. The device is present, but is currently powered off.

WFS_CAM_DEVBUSY The device is busy processing a request. The device is present and an EXECUTE request is currently being processed.

WFS_CAM_DEVNODEVICE There is no device connected.

WFS_CAM_DEVHWERROR The device is inoperable due to a hardware error. The device is present but a hardware fault prevents it from being used.

WFS_CAM_DEVUSERERROR The device is present but a person is preventing proper operation. The application should suspend the device operation or remove the device from service until the service provider generates a device state change event indicating the condition of the device has changed i.e. the error is removed (WFS_CAM_DEVONLINE) or a permanent error condition has occurred (WFS_CAM_DEVHWERROR).

fwMedia
Specifies the state of the recording media. Specified as one of the following flags:

Value Meaning

WFS_CAM_MEDIAOK The media is in a good state.

WFS_CAM_MEDIAHIGH The media is almost full (threshold).

WFS_CAM_MEDIAFULL The media is full.

WFS_CAM_MEDIAUNKNOWN Due to a hardware error or other condition, the state of the media cannot be determined.

fwCameras[...]
Specifies the state of the cameras. A number of cameras are defined below. The maximum camera index is WFS_CAM_CAMERAS_MAX.

fwCameras[WFS_CAM_ROOM]
Specifies the state of the camera that monitors the whole self-service area. Specified as one of the following flags:

Value Meaning

WFS_CAM_CAMNOTSUPP The camera is not supported.

WFS_CAM_CAMOK The camera is in a good state.

WFS_CAM_CAMINOP The camera is inoperative.

WFS_CAM_CAMUNKNOWN Due to a hardware error or other condition, the state of the camera cannot be determined.

fwCameras[WFS_CAM_PERSON]
Specifies the state of the camera that monitors the person standing in front of the self-service machine. Specified as one of the following flags:

Value Meaning

WFS_CAM_CAMNOTSUPP The camera is not supported.

WFS_CAM_CAMOK The camera is in a good state.

WFS_CAM_CAMINOP The camera is inoperative.

WFS_CAM_CAMUNKNOWN Due to a hardware error or other condition, the state of the camera cannot be determined.

fwCameras[WFS_CAM_EXITSLOT]
Specifies the state of the camera that monitors the exit slot(s) of the self-service machine. Specified as one of the following flags:

Value Meaning

WFS_CAM_CAMNOTSUPP The camera is not supported.

WFS_CAM_CAMOK The camera is in a good state.

WFS_CAM_CAMINOP The camera is inoperative.

WFS_CAM_CAMUNKNOWN Due to a hardware error or other condition, the state of the camera cannot be determined.

usPictures
Specifies the number of pictures stored on the recording media.

lpszExtra
Specifies a list of vendor-specific, or any other extended, information. The information is returned as a series of "key=value" strings so that it is easily extensible by service providers. Each string will be null-terminated, with the final string terminating with two null characters.

Error Codes There are no additional error codes generated by this command.

Comments Applications which require or expect specific information to be present in the lpszExtra parameter may not be device or vendor-independent.


3.2 WFS_INF_CAM_CAPABILITIES

Description This command is used to retrieve the capabilities of the Camera System

Input Param None.

Output Param LPWFSCAMCAPS lpCaps;

typedef struct _wfs_cam_caps
 {
 WORD   wClass;
 WORD   fwType;
 WORD   fwCameras[WFS_CAM_CAMERAS_SIZE];
 USHORT   usMaxPictures;
 WORD   fwCamData;
 USHORT   usMaxDataLength;
 LPSTR   lpszExtra;
 } WFSCAMCAPS, * LPWFSCAMCAPS;

wClass
Specifies the logical service class, value is:
WFS_SERVICE_CLASS_CAM

fwType
Specifies the type of the camera device; only current value is:

Value Meaning

WFS_CAM_TYPE_CAM Camera system

fwCameras[...]
Specifies which cameras are available. A number of cameras are defined below. The maximum camera index is WFS_CAM_CAMERAS_MAX.

fwCameras[WFS_CAM_ROOM]
Specifies whether the camera that monitors the whole self-service area is available. Specified as one of the following flags:

Value Meaning

WFS_CAM_NOT_AVAILABLE This camera is not available.

WFS_CAM_AVAILABLE This camera is available.

fwCameras[WFS_CAM_PERSON]
Specifies whether the camera that monitors the person standing in front of the self-service machine is available. Specified as one of the following flags:

Value Meaning

WFS_CAM_NOT_AVAILABLE This camera is not available.

WFS_CAM_AVAILABLE This camera is available.

fwCameras[WFS_CAM_EXITSLOT]
Specifies whether the camera that monitors the exit slot(s) of the self-service machine is available. Specified as one of the following flags:

Value Meaning

WFS_CAM_NOT_AVAILABLE This camera is not available.

WFS_CAM_AVAILABLE This camera is available.

usMaxPictures
Specifies the maximum number of pictures that can be stored on the recording media.

fwCamData
Specifies, if data can be added to the picture.

Specified as a combination of the following flags:

Value Meaning

WFS_CAM_NOTADD No data can be added to the picture.

WFS_CAM_AUTOADD Data is added automatically to the picture.

WFS_CAM_MANADD Data can be added manually to the picture using the filed lpszCamData in the WFS_CMD_CAM_TAKE_PICTURE command.

usMaxDataLength
Specifies the maximum length of the data that is displayed on the photo. Zero, if data cannot be manually added to the picture.

lpszExtra
Specifies a list of vendor-specific, or any other extended, information. The information is returned as a series of "key=value" strings so that it is easily extensible by service providers. Each string will be null-terminated, with the final string terminating with two null characters.

Error Codes There are no additional error codes generated by this command.

Comments Applications which require or expect specific information to be present in the lpszExtra parameter may not be device or vendor-independent.


4.1 WFS_CMD_CAM_TAKE_PICTURE

Description This command is used to start the recording of the camera system. It is possible to select which camera or which camera position should be used to take a picture. Furthermore data can be sent to be displayed on the photo.

Input Param LPWFSCAMTAKEPICT lpTakePict;

typedef struct _wfs_cam_take_picture
 {
 WORD   wCamera;
 LPSTR   lpszCamData;
 } WFSCAMTAKEPICT, * LPWFSCAMTAKEPICT;

wCamera
Specifies the camera that should take the photo as one of the following flags:

Value Meaning

WFS_CAM_ROOM Monitors the whole self-service area.

WFS_CAM_PERSON Monitors the person standing in front of the self-service machine.

WFS_CAM_EXITSLOT Monitors the exit slot(s) of the self-service machine.

lpszCamData
Specifies the text string to be displayed on the photo. If the maximum text length is exceeded, it will be truncated. In this case or if the text given is invalid an execute event WFS_EXEE_CAM_INVALIDDATA is generated. Nevertheless the picture is taken.

Output Param None.

Error Codes The following additional error codes can be generated by this command:

Value Meaning

WFS_ERR_CAM_CAMNOTSUPP The specified camera is not supported.

WFS_ERR_CAM_CAMINOP The specified camera is inoperable.

WFS_ERR_CAM_MEDIAFULL The recording media is full.

Events The following additional events can be generated by this command:

Value Meaning

WFS_USRE_CAM_MEDIATHRESHOLD The state of the recording media reached a threshold.

WFS_EXEE_CAM_INVALIDDATA The text string given is to long or in some other way invalid.

Comments None.


5.1 WFS_USRE_CAM_MEDIATHRESHOLD

Description This user event is used to specify that the state of the recording media reached a threshold.

Event Param LPWORD lpwMediaThreshold;

Specified as one of the following flags:

Value Meaning

WFS_CAM_MEDIAHIGH The recording media is almost full.

WFS_CAM_MEDIAFULL The recording media is full.

Comments None.


5.2 WFS_EXEE_CAM_INVALIDDATA

Description This execute event is used to specify that the text string given was to long or in some other way invalid.

Event Param None.

Comments None.


6. C - Header file

/******************************************************************************
*                                                                             *
* xfscam.h      WOSA/XFS - Camera (CAM) definitions                           *
*                                                                             *
*               Version 2.00 (11/11/96)                                       *
*                                                                             *
******************************************************************************/

#ifndef __INC_XFSCAM__H
#define __INC_XFSCAM__H

#ifdef __cplusplus
extern "C" {
#endif

#include    <xfsapi.h>

/* be aware of  alignment */
#pragma pack (push, 1)

/* values of WFSCAMCAPS.wClass */

#define     WFS_SERVICE_CLASS_CAM               (10)
#define     WFS_SERVICE_VERSION_CAM             (0x0002) /* Version 2.00 */
#define     WFS_SERVICE_NAME_CAM                "CAM"

#define     CAM_SERVICE_OFFSET                  (WFS_SERVICE_CLASS_CAM * 100)

/* CAM Info Commands */

#define     WFS_INF_CAM_STATUS                  (CAM_SERVICE_OFFSET + 1)
#define     WFS_INF_CAM_CAPABILITIES            (CAM_SERVICE_OFFSET + 2)

/* CAM Execute Commands */

#define     WFS_CMD_CAM_TAKE_PICTURE            (CAM_SERVICE_OFFSET + 1)

/* CAM Messages */

#define     WFS_USRE_CAM_MEDIATHRESHOLD         (CAM_SERVICE_OFFSET + 1)
#define     WFS_EXEE_CAM_INVALIDDATA            (CAM_SERVICE_OFFSET + 2)

/* values of WFSCAMSTATUS.fwDevice */

#define     WFS_CAM_DEVONLINE                   WFS_STAT_DEVONLINE
#define     WFS_CAM_DEVOFFLINE                  WFS_STAT_DEVOFFLINE
#define     WFS_CAM_DEVPOWEROFF                 WFS_STAT_DEVPOWEROFF
#define     WFS_CAM_DEVBUSY                     WFS_STAT_DEVBUSY
#define     WFS_CAM_DEVNODEVICE                 WFS_STAT_DEVNODEVICE
#define     WFS_CAM_DEVHWERROR                  WFS_STAT_DEVHWERROR
#define     WFS_CAM_DEVUSERERROR                WFS_STAT_DEVUSERERROR

/* number of cameras supported/length of WFSCAMSTATUS.fwCameras field */

#define     WFS_CAM_CAMERAS_SIZE                (8)
#define     WFS_CAM_CAMERAS_MAX                 (WFS_CAM_CAMERAS_SIZE - 1)

/* indices of WFSCAMSTATUS.fwCameras [...]
              WFSCAMCAPS.fwCameras [...]
              WFSCAMTAKEPICT.wCamera             */
#define     WFS_CAM_ROOM                        (0)
#define     WFS_CAM_PERSON                      (1)
#define     WFS_CAM_EXITSLOT                    (2)

/* values of WFSCAMSTATUS.fwMedia */

#define     WFS_CAM_MEDIAOK                     (0)
#define     WFS_CAM_MEDIAHIGH                   (1)
#define     WFS_CAM_MEDIAFULL                   (2)
#define     WFS_CAM_MEDIAUNKNOWN                (3)

/* values of WFSCAMSTATUS.fwCameras */

#define     WFS_CAM_CAMNOTSUPP                  (0)
#define     WFS_CAM_CAMOK                       (1)
#define     WFS_CAM_CAMINOP                     (2)
#define     WFS_CAM_CAMUNKNOWN                  (3)

/* values of WFSCAMCAPS.fwType */

#define     WFS_CAM_TYPE_CAM                    (1)

/* values of WFSCAMCAPS.fwCamData */

#define     WFS_CAM_NOTADD                      (0)
#define     WFS_CAM_AUTOADD                     (1)
#define     WFS_CAM_MANADD                      (2)

/* WOSA/XFS CAM Errors */

#define WFS_ERR_CAM_CAMNOTSUPP          (-(CAM_SERVICE_OFFSET + 0))
#define WFS_ERR_CAM_MEDIAFULL           (-(CAM_SERVICE_OFFSET + 1))
#define WFS_ERR_CAM_CAMINOP             (-(CAM_SERVICE_OFFSET + 2))

/*=================================================================*/
/* CAM Info Command Structures */
/*=================================================================*/

typedef struct _wfs_cam_status
{
    WORD            fwDevice;
    WORD            fwMedia;
    WORD            fwCameras[WFS_CAM_CAMERAS_SIZE];
    USHORT          usPictures;
    LPSTR           lpszExtra;
} WFSCAMSTATUS, *LPWFSCAMSTATUS;

typedef struct _wfs_cam_caps
{
    WORD            wClass;
    WORD            fwType;
    WORD            fwCameras[WFS_CAM_CAMERAS_SIZE];
    USHORT          usMaxPictures;
    WORD            fwCamData;
    USHORT          usMaxDataLength;
    LPSTR           lpszExtra;
} WFSCAMCAPS, * LPWFSCAMCAPS;

/*=================================================================*/
/* CAM Execute Command Structures */
/*=================================================================*/

typedef struct _wfs_cam_take_picture
{
    WORD            wCamera;
    LPSTR           lpszCamData;
} WFSCAMTAKEPICT, *LPWFSCAMTAKEPICT;

/* restore alignment */
#pragma pack (pop)

#ifdef __cplusplus
}       /*extern "C"*/
#endif

#endif /* __INC_XFSCAM__H */