ATMC开发SDM及厂商SP接口.doc

1. 背景CEN/XFS标准是由CEN（欧洲标准委员会）组织推行的用于金融扩展服务设备的统一标准，其3.0版本已得到了全球绝大多数金融设备供应商的支持。在理想状况下，基于CEN/XFS3.0标准开发的自助终端应用程序应能无缝的运行在不同厂商的符合XFS3.0标准的金融设备上，但由于XFS3.0标准并没有对厂商如何实现该标准做严格的约束，同时CEN组织是非盈利性机构，无力对各金融设备供应商进行符合XFS3.0标准的认证测试，因此各厂商对XFS3.0标准的理解与实现，存在一些差异，从而使基于该标准开发的应用程序无法无缝的运行在不同厂商的金融设备上。目前正在进行统一的跨平台ATMC与跨平台自助终端C的实施工作。为了使跨平台自助设备C的实施能顺利开展，必须对CEN/XFS3.0标准进行补充与细化，统一规范各厂商对标准的理解，清除在实现该标准时可能产生的歧义，从而使跨平台自助设备C的实施工作能顺利开展，使统一的自助设备C能无缝运行在各品牌型号的自助设备上。2. 范围本细化实施规范基于CEN/XFS3.0标准的文档（编号CWA14050-1至CWA14050-15）制定。在本细化规范中将对CEN/XFS3.0标准中可能引起歧义、或有特殊用法的地方进行特别说明。本文件中未说明的均以CEN/XFS3.0标准文档为准。本文件中所有的函数、参数、常量、变量的定义均引自CEN/XFS3.0标准。3. 规范性引用文件CWA 14050-1 Part 1: Application Programming Interface (API) Service Provider Interface (SPI); Programmers ReferenceCWA 14050-2 Part 2: Service Classes Definition; Programmers ReferenceCWA 14050-3 Part 3: Printers Device Class Interface; Programmers ReferenceCWA 14050-4 Part 4: Identification Card Device Class Interface -Programmers ReferenceCWA 14050-5 Part 5: Cash Dispenser Device Class InterfaceCWA 14050-6 Part 6: PIN Keypad Device Class Interface Programmers ReferenceCWA 14050-7 Part 7: Check Reader/Scanner Device Class InterfaceCWA 14050-8Part 8: Depository Device Class InterfaceCWA 14050-9 Part 9: Text Terminal Unit Device Class InterfaceCWA 14050-10 Part 10: Sensors and Indicators Unit Device Class InterfaceCWA 14050-11 Part 11: Vendor Dependent Mode Class InterfaceCWA 14050-12Part 12: Camera Device Class InterfaceCWA 14050-13Part 13: Alarm Device Class InterfaceCWA 14050-14Part 14: Card Embossing Unit Class InterfaceCWA 14050-15Part 15: Cash In Module Device Class Interface -Programmers Reference4. 术语与定义CEN欧洲标准化委员会XFS扩展金融服务ATM自动柜员机PTR打印机，包括凭条打印机、流水打印机IDC读卡器，包括磁条读卡器、IC卡读卡器CDM出钞模块PIN加密键盘CHK支票模块DEP信封存款模块TTU字符终端SIU传感器与指示灯VDM厂商模式CAM摄像机ALM警报器CEU压卡模块CIM现金存款模块5. 对规范的细化5.1 PINPIN必须至少支持下表中列出的命令：Info CommandsExecute CommandsWFS_INF_PIN_STATUSWFS_CMD_PIN_IMPORT_KEYWFS_INF_PIN_CAPABILITIESWFS_CMD_PIN_GET_PINWFS_INF_PIN_KEY_DETAILWFS_CMD_PIN_GET_PINBLOCKWFS_INF_PIN_FUNCKEY_DETAILWFS_CMD_PIN_GET_DATAWFS_CMD_PIN_INITIALIZATIONWFS_CMD_PIN_RESETWFS_CMD_PIN_CRYPTWFS_INF_PIN_STATUSfwDevice当设备正在执行Execute Command 时处于WFS_PIN_DEVBUSY状态，此时所有的Info Command命令均应立即返回正确信息。fwEncStat除WFS_PIN_ENCBUSY外，其他状态均不应影响fwDevice的值。例如，当fwEncStat从WFS_PIN_ENCREADY 变为WFS_PIN_ENCNOTREADY时，fwDevice值不应该改变。WFS_INF_PIN_CAPABILITIESfwType必须至少包含WFS_PIN_TYPEEPP与 WFS_PIN_TYPEEDMusKeyNum不得小于12fwAlgorithms必须至少包含下表所列算法WFS_PIN_CRYPTDESECB WFS_PIN_CRYPTDESCBC WFS_PIN_CRYPTDESMAC WFS_PIN_CRYPTTRIDESECBWFS_PIN_CRYPTTRIDESCBCWFS_PIN_CRYPTTRIDESMAC其中，WFS_PIN_CRYPTTRIDESMAC算法必须符合银联的3DES算法规定。fwPinFormats必须至少包含下表所列格式WFS_PIN_FORM3624 WFS_PIN_FORMANSI WFS_PIN_FORMISO0 WFS_PIN_FORMISO1 WFS_PIN_FORMECI2 WFS_PIN_FORMECI3 WFS_PIN_FORMVISA WFS_PIN_FORMDIEBOLWFS_PIN_FORMDIEBOLCOWFS_INF_PIN_FUNCKEY_DETAILPINPAD上必须包含以下按键：数字0到数字9，小数点，ENTER，CANCEL。此外，CLEAR与BACKSPACE两个按键必须至少存在一个。还必须包含FDK01到FDK08八个功能键。所有按键对应的返回值键码，均应采用本对照表。ulFuncMask返回值键WFS_PIN_FK_0 数字0WFS_PIN_FK_1 数字1WFS_PIN_FK_2 数字2WFS_PIN_FK_3 数字3WFS_PIN_FK_4 数字4WFS_PIN_FK_5 数字5WFS_PIN_FK_6 数字6WFS_PIN_FK_7 数字7WFS_PIN_FK_8 数字8WFS_PIN_FK_9 数字9WFS_PIN_FK_ENTER ENTERWFS_PIN_FK_CANCEL CANCELWFS_PIN_FK_CLEAR CLEARWFS_PIN_FK_BACKSPACE BACKSPACEWFS_PIN_FK_HELP HELPWFS_PIN_FK_DECPOINT 小数点WFS_PIN_FK_00 00WFS_PIN_FK_000 000功能键说明返回值备注屏幕左侧第一个按键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_FDK08WFS_CMD_PIN_GET_PINulActiveFDKs如激活了CLEAR键，则按下CLEAR键将清空PIN BufferulActiveKeys如设备支持双零键“00”或三零键“000”。调用此命令时激活了双零键或三零键，则命令失败，返回WFS_ERR_PIN_KEYINVALIDWFS_CMD_PIN_INITIALIZATION在应用程序中不会调用此命令。因此厂商应在安装设备sp时进行加密模块的初始化，或者在应用程序第一次调用WFS_CMD_PIN_IMPORT_KEY命令时自动进行初始化。 5.2 TTUTTU为可选设备，但如果自助设备上配置了TTU，则必须满足如下要求：TTU屏幕必须至少为16行32列。TTU上必须至少配置从0到9十个数字键，以及ENTER、CANCEL、CLEAR键。允许有其他按键。TTU必须支持UNICODE，必须支持显示中文。TTU必须至少支持下表中列出的命令：Info CommandsExecute CommandsWFS_INF_TTU_STATUSWFS_CMD_TTU_BEEPWFS_INF_TTU_CAPABILITIESWFS_CMD_TTU_CLEARSCREENWFS_INF_TTU_KEY_DETAILWFS_CMD_TTU_DISPLIGHTWFS_CMD_TTU_SET_LEDWFS_CMD_TTU_SET_RESOLUTIONWFS_CMD_TTU_WRITE_FORMWFS_CMD_TTU_READ_FORMWFS_CMD_TTU_WRITEWFS_CMD_TTU_READWFS_CMD_TTU_RESETWFS_INF_TTU_STATUSfwDevice当设备正在执行Execute Command时处于WFS_TTU_DEVBUSY状态，此时所有的Info Command命令均应立即返回正确信息。WFS_CMD_TTU_CLEARSCREEN当屏幕上显示中文信息时，如果一个中文字符显示为两个ASCII字符的宽度，且此命令的参数指定的清屏范围将截断某一个中文字符，则执行此命令应将整个中文字符清除，不能出现将中文字符截断一半显示乱码的情况。WFS_CMD_TTU_WRITE如果在TTU上一个中文显示为两个ASCII字符的宽度，且此命令执行时将覆盖屏幕上原有的文字，则执行此命令后，应覆盖整个中文字符，不应出现将中文字符截断一半显示乱码的情况。5.3 VDM自助设备必须支持VDM。VDM必须支持下表中列出的命令：Info CommandsExecute CommandsWFS_INF_VDM_STATUSWFS_CMD_VDM_ENTER_MODE_REQWFS_INF_VDM_CAPABILITIESWFS_CMD_VDM_ENTER_MODE_ACKWFS_CMD_VDM_EXIT_MODE_REQWFS_CMD_VDM_EXIT_MODE_ACK5.4 PTR打印机必须支持中文（Unicode）打印、英文大小写打印、常用符号、条形码及图片打印。PTR必须支持CEN/XFS3.0标准中列出的所有命令。WFS_INF_PTR_STATUSfwDevice当fwPaper状态为WFS_PTR_PAPERLOW或WFS_PTR_PAPEROUT时设备状态应为WFS_PTR_DEVONLINE当设备正执行Execute Command时处于WFS_PTR_DEVBUSY状态时，此时所有的Info Command命令均应立即返回正确信息。WFS_INF_PTR_CAPABILITIESfwReadForm凭条打印机、回单打印机必须包含WFS_PTR_READBARCODE、WFS_PTR_READIMAGEfwWriteForm凭条打印机必须至少包含WFS_PTR_WRITETEXT流水打印机必须至少包含WFS_PTR_WRITETEXTfwControl凭条打印机必须至少包含WFS_PTR_CTRLEJECT、WFS_PTR_CTRLCUT、WFS_PTR_CTRLSKIP、WFS_PTR_CTRLFLUSH、WFS_PTR_CTRLALARM流水打印机必须至少包含WFS_PTR_CTRLFLUSHfwCharSupport所有打印机都必须支持WFS_PTR_ASCII、WFS_PTR_UNICODEWFS_INF_PTR_FORM_LIST命令执行时，只列出该逻辑打印设备的Form名称，而不能列出其他打印设备的Form名称。WFS_INF_PTR_QUERY_FORMwBaseForm必须至少包含WFS_FRM_MM、WFS_FRM_ROWCOLUMNwAlignmentForm必须支持WFS_FRM_TOPLEFT、WFS_FRM_TOPRIGHT、WFS_FRM_BOTTOMLEFT、WFS_FRM_BOTTORMRIGHTfwCharSupport所有Form都必须支持WFS_PTR_ASCIIWFS_INF_PTR_QUERY_FIELDSP必须支持查询Form某个域字段或全部域字段的定义细节。在打印FORM时，如果打印数据溢出，则SP必须提供两种方式进行处理：a. WFS_FRM_OVFTERMINATEb. WFS_FRM_OVFTRUNCATEWFS_CMD_PTR_CONTROL_MEDIAlpdwMediaControlWFS_PTR_CTRLCUT切纸时，必须支持在黑标处切断。当该命令执行出错时必须正确的返回相应的错误码WFS_CMD_PTR_RAW_DATAulSize当目标打印机内容长度超出打印介质宽度时，自动换行打印lpbData打印时支持换行符nWFS_EXEE_PTR_FIELDERROR当Field出错时该事件应及时被触发，并给出具体的wFailure值WFS_USRE_PTR_RETRACTBINTHRESHOLD当RETRACT BIN 达到High或者Full时该事件应及时被触发WFS_USRE_PTR_PAPERTHRESHOLD打印机少纸或缺纸发生时，纸阈值事件应及时被触发WFS_SRVE_PTR_MEDIADETECTED当执行Reset命令时，如果打印机中遗留有Media时，应及时触发此事件wPosition当Reset后其值应为WFS_PTR_MIDIARETRACTEDFORM与MEDIA定义FORM&MEDIA存放位置Receipt Printer的Form文件存放在：C:xfsformrptr下Journal Printer的Form文件存放在：C:xfsformjptr下Receipt Printer的Media文件存放在：C:xfsmediarptr下Journal Printer的Media文件存放在：C:xfsmediajptr下Form&Media文件的文件类型Form文件的文件后缀名为def，也就是说Form文件必须是*.def文件。Form定义应支持在Form名称唯一的情况下，使用多个不同的def文件。Media文件的文件后缀名为def，也就是说Media文件必须是*.def文件。Form定义l Form、Media的度量基本单位支持毫米、行列。l FORM定义中所有坐标的起始位置必须从1开始计算。l Field数据String中可包含换行符n，打印时应能正确处理。l 域中的每个中文或全角符号的宽度为两个ASCII字符。l 打印ASCII字符必须支持以下字体中的一种：Time New Roman，INTERNATIONAL，宋体，楷体_GB2312。l 打印中文字符必须支持以下字体中的一种：宋体，楷体_GB2312。l 需支持所有的OVERFLOW，STYLE。l 对凭条打印机，其FIELD在CPI为15时，应能每行打印40字符或以上，单张凭条能打印24行或以上。异常FORM的处理下列情况SP应返回错误：l 如FORM中两个域的定义范围有重合。l 如FORM中从域的起始列加上域的列宽超出MIEDIA的边界。l 如FORM中从域的起始行加上域的行数超出MIEDIA的边界。5.5 CDMCDM必须至少支持下表中列出的命令：Info CommandsExecute CommandsWFS_INF_CDM_STATUSWFS_CMD_CDM_DENOMINATEWFS_INF_CDM_CAPABILITIESWFS_CMD_CDM_DISPENSEWFS_INF_CDM_CASH_UNIT_INFOWFS_CMD_CDM_COUNTWFS_INF_CDM_MIX_TYPESWFS_CMD_CDM_PRESENTWFS_INF_CDM_PRESENT_STATUSWFS_CMD_CDM_REJECTWFS_CMD_CDM_RETRACTWFS_CMD_CDM_SET_CASH_UNIT_INFOWFS_CMD_CDM_START_EXCHANGEWFS_CMD_CDM_END_EXCHANGEWFS_CMD_CDM_RESET对CEN/XFS标准及本细化实施标准中所要求的持久值（persistent），在拔插取款模块的各钞箱时不应被改变。WFS_INF_CDM_STATUSfwDevice当设备正在执行Execute Command时处于WFS_CDM_DEVBUSY状态，此时所有的Info Command命令均应立即返回正确信息。设备Retract失败，或者Dispense成功后Present失败且Reject失败应转入WFS_CDM_DEVHWERROR状态。WFS_INF_CDM_CAPABILITIESfwType在ATM上，必须为WFS_CDM_SELFSERVICEBILL。wMaxDispenseItems出钞模块一次出钞动作可吐出的最大张数。如果DISPENSE命令指定的出钞张数大于此限制，则DISPENSE命令失败，返回WFS_ERR_CDM_TOOMANYBILLS。不允许sub_dispense。bShutteControl必须为TRUE。即Shutter是由SP控制，而不需应用程序显示控制。fwRetractAreas至少包含WFS_CDM_RA_REJECT。bItemsTakenSensor必须为TRUE，即设备应能检测取钞动作。fwExchangeType必须至少包含WFS_CIM_EXBYHAND。WFS_INF_CDM_CASH_UNIT_INFO允许一个逻辑钞箱对应一个或多个物理钞箱。WFSCDMCASHUNIT结构中的cCurrencyID，ulValues，ulInitialCount，ulCount，ulRejectCount，ulMinimum，ulMaximum，及WFSCDMPHCU结构中的ulInitialCount，ulCount，ulRejectCount，ulMaximum均为持久值（persistent）。ulMinimum如果此值大于0，当钞箱内剩余钞票张数小于此值时，此钞箱应可以继续出钞，直到张数为0或张数小于钞箱的物理限制值时，此钞箱无法出钞，此时将忽略检测阈值的硬件传感器。如果此值为0，且存在检测阈值的硬件传感器，则在该逻辑钞箱对应的所有物理钞箱都到达阈值时，激发WFS_USRE_CIM_CASHUNITTHRESHOLD事件。ulMaximum如果此值大于0，当钞箱内钞票张数大于此值时，钞箱仍可继续吞钞，直到张数达到钞箱的物理限制，此时将忽略检测阈值的硬件传感器。如果此值为0，且存在检测阈值的硬件传感器，则在该逻辑钞箱对应的所有物理钞箱都到达阈值时，激发WFS_USRE_CIM_CASHUNITTHRESHOLD事件。WFS_INF_CDM_MIX_TYPES必须至少支持下述两种配钞算法：WFS_CDM_MIX_MINIMUM_NUMBER_OF_BILLS与WFS_CDM_MIX_EQUAL_EMPTYING_OF_CASH_UNITSWFS_CMD_CDM_DISPENSEDISPENSE命令完成后，不论命令是否成功，各钞箱的钞票张数计数器均应能正确反应DISPENSE命令执行后的情况。如某钞箱的钞票张数小于最小阈值，则激发WFS_USRE_CDM_CASHUNITTHRESHOLD事件。调用此命令时应按照钞箱剩余钞票的逻辑计数计算配钞方案，如某钞箱的逻辑计数为0，则不应从此钞箱出钞。不支持部分出钞。bPresent如设备无叠钞区（bIntermediateStackerFalse），则此参数必须为TRUE。否则返回错误WFS_ERR_UNSUPP_COMMAND。WFS_ERR_CDM_SAFEDOOROPEN：如调用此命令前设备的SAFEDOOR处于打开状态，或在此命令执行过程中打开SAFEDOOR，则命令失败，且必须返回此错误码。lpDenomination如无法按此参数指定的配钞方案出钞，则SP应能调整配钞方案，通过从其他钞箱出钞的方式，尽最大可能保证命令成功，并在返回参数中包含实际的配钞方案。WFS_CMD_CDM_REJECTREJECT命令成功后，各钞箱的钞票张数计数器均应能正确反应REJECT命令执行后的情况。如废钞箱的钞票张数大于最大阈值，则激发WFS_USRE_CDM_CASHUNITTHRESHOLD事件。如REJECT命令失败，则CDM设备状态变为WFS_CDM_DEVHWERROR。WFS_CMD_CDM_RETRACTRETRACT命令成功后，各钞箱的钞票张数计数器均应能正确反应命令执行后的情况。如废钞箱的钞票张数大于最大阈值，则激发WFS_USRE_CDM_CASHUNITTHRESHOLD事件。如RETRACT命令失败，则CDM设备状态变为WFS_CDM_DEVHWERROR。WFS_CMD_CDM_SET_CASH_UNIT_INFOWFSCDMCUINFO结构中的usCount参数应与当前CDM中逻辑钞箱的数量相等，否则返回WFS_ERR_INVALID_DATA。如修改后出钞钞箱的ulCount大于0且小于ulMinimum，或废钞箱RejectBIN的ulCount大于ulMaximum，则应激发WFS_USRE_CDM_CASHUNITTHRESHOLD事件。WFS_CMD_CDM_START_EXCHANGE调用此命令后，如系统断电重启，则应清除Exchange Active状态，即重启后再次调用此命令不应返回WFS_ERR_CDM_EXCHANGEACTIVE错误。WFS_CMD_CDM_END_EXCHANGEWFSCDMCUINFO结构中的usCount参数应与当前CDM中逻辑钞箱的数量想等，否则返回WFS_ERR_INVALID_DATA。任何参数被修改均应激发WFS_SRVE_CDM_CASHUNITINFOCHANGED事件。WFS_CMD_CDM_CALIBRATE_CASH_UNIT如执行此命令后钞票在出钞口，则取钞后应激发WFS_SRVE_CDM_BILLSTAKEN事件。出钞命令流如无叠钞区（bIntermediateStackerFalse）步骤客户应用程序CDM Device1客户要求出钞2调用DENOMINATE配钞（可选）3调用DISPENSE（参数bPresent=TRUE）出钞4打开出钞口5吐出钞票6DISPENSE命令完成，等待客户取钞7客户取钞8激发BILLS TAKEN事件9关闭出钞口10出钞成功，命令流结束11如第7步后需吞钞（比如客户未取钞）12调用RETRACT吞钞13钞票吞回14关闭出钞口15RETRACT命令完成 16吞钞成功，命令流结束如有叠钞区（bIntermediateStacker=TRUE）步骤客户应用程序CDM Device1客户要求出钞2调用DENOMINATE配钞（可选）3调用DISPENSE（参数bPresent=FALSE）出钞4将钞票放入Stacker5DISPENSE命令完成6调用PRESENT吐钞7出钞口打开8吐出钞票9PRESENT命令完成，等待客户取钞10客户取钞11激发BILLS TAKEN事件12关闭出钞口13出钞成功，命令流结束14如第10步后需吞钞（比如客户未取钞）15调用RETRACT吞钞16钞票吞回17关闭出钞口18RETRACT命令完成 19吞钞成功，命令流结束5.6 SIUSIU必须至少支持下表中列出的命令：Info CommandsExecute CommandsWFS_INF_SIU_STATUSWFS_CMD_SIU_ENABLE_EVENTSWFS_INF_SIU_CAPABILITIESWFS_CMD_SIU_SET_PORTSWFS_CMD_SIU_SET_DOORWFS_CMD_SIU_SET_INDICATORWFS_CMD_SIU_SET_AUXILIARYWFS_CMD_SIU_SET_GUIDLIGHTWFS_CMD_SIU_RESETWFS_INF_SIU_STATUSfwDevice当设备正在执行Execute Command时处于WFS_SIU_DEVBUSY状态，此时所有的Info Command命令均应立即返回正确信息。5.7 IDCSIU必须至少支持下表中列出的命令：Info CommandsExecute CommandsWFS_INF_IDC_STATUSWFS_CMD_IDC_EJECT_CARD(仅对motor driven 读卡器)WFS_INF_IDC_CAPABILITIESWFS_CMD_IDC_RETAIN_CARD(仅对motor driven 读卡器)WFS_CMD_IDC_RESET_COUNT(仅对motor driven 读卡器)WFS_CMD_IDC_READ_RAW_DATAWFS_CMD_IDC_WRITE_RA