XFS-сервис класса CIM. Модель MEI-SC83

Файлы

• CimLimitsCheckerSrv.exe;

• shqPS.CIM.MEI-Cashflow.exe;

• shqSPCIM.dll.

Настройки XFS-провайдера

Инсталляционные настройки

Раздел реестра: [HKLM\Software\XFS\PHYSICAL_SERVICES\CIM-MEI-CASHFLOW]

Параметры драйвера:

• PORT – номер порта, к которому подключено устройство.

• CassetteCapacity – емкость кассеты в банкнотах. Возможные значения: 2200, 1200, 900 , 600. Количество банкнот соответствуют определенной модификации купюроприемника: SCXL[2200], SCL[1200], SCM[900], SC[600].

• ForceFullIfPhMaximumReached – переводить/не переводить состояние кассеты в Full (полная кассета) в случае достижения счетчиком банкнот значения емкости кассеты (CassetteCapacity). Возможные значения: YES, NO. Значение по умолчанию не предусмотрено. Рекомендуется использовать для устройств, ненадежно работающих, приближаясь к аппаратному переполнению.

• CashInFinishIfBanknoteRefused – завершать/не завершать операцию приема наличных (WFS_CMD_CIM_CASH_IN) при отбракованной банкноте. Возможные значения: YES (завершать), NO (не завершать). При установке значения NO устройство будет ожидать вставки банкноты.

• EmulateItemsTakenEvent – эмулировать/не эмулировать событие извлечения банкноты из презентера. Возможные значения: YES (эмулировать), NO (не эмулировать). При установке значения YES событие будет отправляться сразу при предъявлении банкноты клиенту. Данный параметр необходим из-за особенностей оборудования или прошивки устройства, так как по протоколу невозможно отследить момент изъятия банкноты из удерживающих роликов устройства.

• EnableHighSecurityMode – включить/отключить режим повышенной безопасности валидации банкнот. Возможные значения: YES (режим включен), NO (режим отключен).

• ExpReductionToZero – приводить/не приводить номиналы банкнот к нулевому значению. Возможные значения: YES, NO. YES – номинал будет иметь свое действительное значение, указанное на банкноте. NO – номиналы банкнот будут приводиться к значению, полученному по запросу WFS_INF_CIM_CURRENCY_EXP для своего типа валюты.

• ForceHwErrorIfCassetteInop – параметр принудительно переводит устройство (поле fwDevice в запросе WFS_INF_CIM_STATUS) в состояние WFS_CIM_DEVHWERROR при неработоспособной кассете, включая статус кассеты WFS_CIM_STATCUMISSING, WFS_CIM_STATCUMANIP.

• DelayTimeAcceptanceStop – время задержки (в мс) подачи команды завершения приема банкнот на устройство после отработки запроса WFS_CMD_CIM_CASH_IN_END. Актуально для устройств с псевдопачечным приемом ввиду того, что устройство при складировании очередной банкноты уже подхватывает следующую. Команда WFS_CMD_CIM_CASH_IN производит сброс отложенной подачи команды запрета приема. Значение по умолчанию: 2000.

• DISABLE_CU_MANIPULATED – отключить отслеживание и перевод кассеты в состояние MANIPULATED (в случае, если кассета извлекалась вне рамок процедуры инкассации). Возможные значения: 1, 0.

Переопределение кода валюты

Сервис-провайдер поддерживает функционал переопределения кодов валют. Например, можно переопределить возвращаемый сервис-провайдером код валюты RUB (российский рубль ISO4217) на RUR (код российского рубля до деноминации 1998г.). Данная настройка доступна в реестре: [HKEY_LOCAL_MACHINE\SOFTWARE\XFS\PHYSICAL_SERVICES\CIM-MEICashflow\currencies]. Далее названием параметра будет являться текущий код валюты, а значением код валюты на который нужно поменять, после чего сервис-провайдер во всех запросах будет возвращать на выход уже переопределенный код валюты. Для мультивалютной прошивки можно переопределить сразу несколько валют.

Информационные запросы

WFS_INF_CIM_STATUS

Получить статус устройства.

Определение состояния fwDevice:

• WFS_CIM_DEVONLINE: устройство готово к работе.

• WFS_CIM_DEVPOWEROFF: выставляется в случае потери связи с устройством, в случае изначальной невозможности открыть COM-порт, к которому подключено устройство, в случае достижения таймаута при считывании данных из порта. Любой CMD-запрос к сервису сопровождается ответом WFS_ERR_DEV_NOT_READY.

• WFS_CIM_DEVNODEVICE: выставляется в случае некорректной конфигурации XFS-драйвера: Отсутствие настройки COM-порта или других настроек реестра; Несанкционированное изменение файла mei_sc_persistents.xml В extra-поле в ответе STATUS под ключом DETECTED_PROBLEM записывается причина, повлекшая переход в данное состояние. Любой CMD-запрос к сервису сопровождается ответом WFS_ERR_SOFTWARE_ERROR.

• WFS_CIM_DEVHWERROR: механическая неисправность одного из узлов сервиса, препятствующая дальнейшей работе устройства. Выставляется в случае неуспешного выполнения протокольных команд коммуникации с устройством.

• WFS_CIM_DEVBUSY Устройство занято отработкой CMD-запроса. Любые CMD-запросы, требующие эксклюзивного доступа к аппаратному обеспечению, ставятся в очередь на исполнение, остальные запросы (такие как INF-STATUS и пр.) исполняются немедленно.

Определение состояния fwAcceptor:

• WFS_CIM_ACCOK: Кассета в состоянии OK. Устройство готово к приему.

• WFS_CIM_ACCCUSTATE: Кассета близка к переполнению. Устройство готово к приему.

• WFS_CIM_ACCCUSTOP: Кассета переполнена или в состоянии ошибки. Прием банкнот запрещен.

• WFS_CIM_ACCCUUNKNOWN: В силу поломки/недоступности аппарата невозможно определить состояние.

Поле lpszExtra:

• VENDOR=DORS [SYSTEMA];

• PRODUCT=ProAtm/Xfs;

• VERSION=X.X.X.X (текущая версия сервис-провайдера XFS);

• DEVICE=MEI-SC;

• DETECTED_PROBLEM: описываются ошибки, выявленные в конфигурации;

• HW_ERROR: состав ошибок оборудования;

• MODEL: модель устройства;

• FW_VER: версия прошивки устройства;

• SERIAL_NO: серийный номер устройства.

WFS_INF_CIM_CAPABILITIES

Получить информацию о возможностях устройства.

• Максимальное кол-во принимаемых банкнот за одну операцию (wMaxCashInItems): 1 банкнота.

• Наличие шаттера (bShutter): нет.

• Наличие сейфовой двери (bSafeDoor): нет.

• Емкость escrow (fwIntermediateStacker): 1.

• Датчики банкнот в слоте приема/возврата:

  • взятие банкнот (bItemsTakenSensor), если установлен параметр EmulateItemsTakenEvent;

  • вставка банкнот (bItemsInsertedSensor).

• Позиции приема/возврата (fwPositions): WFS_CIM_POSINCENTER; WFS_CIM_POSOUTCENTER.

• Инкассация (fwExchangeType): Ручная инкассация кассет.

• Ретракт: Не поддерживается.

WFS_INF_CIM_CASH_UNIT_INFO

Получить информацию о кассете устройства.

Устройство имеет одну физическую кассету. Структура данных WFSCIMCASHINFO содержит в себе одну логическую кассету, которая ссылается на одну физическую кассету.

Определение статуса кассеты (usStatus):

• WFS_CIM_STATCUOK Готова к приему.

• WFS_CIM_STATCUFULL Заполнена (аппаратное переполнение).

• WFS_CIM_STATCUHIGH Кассета близка к переполнению. Статус выставляется программно только для логической кассеты по достижению ее максимума (ulMaximum).

• WFS_CIM_STATCUINOP Не в рабочем состоянии, например, произошло замятие банкноты.

• WFS_CIM_STATCUMISSING Извлечена.

• WFS_CIM_STATCUMANIP Извлекалась вне рамок exchange-сессии (инкассация).

Счетчики кассеты:

• ulCount Текущее количество банкнот в кассете.

• ulCashInCount Счетчик банкнот, помещенных в кассету, равен ulCount.

• noteNumberList Текущий состав банкнот по номиналам в логической кассете.

Счетчики структур данных CEN/XFS 3.10 имеют нулевые значения.

Расчет значения максимума (ulMaximum) по умолчанию: значение максимума формируется с использованием настроечного параметра емкости кассеты (CassetteCapacity).

• lppCashIn[0].ulMaximum = CassetteCapacity – 200 (Логическая кассета);

• lppCashIn[0].lppPhysical[0].ulMaximum = CassetteCapacity (Физическая кассета).

WFS_INF_CIM_CURRENCY_EXP

Получить значение установленной экспоненты для каждой поддерживаемой устройством валюты.

Валюта (cCurrencyID) указывается в формате ISO 4217. Если при инсталляции сервис-провайдера был установлен параметр ExpReductionToZero, то значение экспоненты будет равно нулю.

WFS_INF_CIM_BANKNOTE_TYPES

Получить информацию о типах банкнот, поддерживаемых устройством.

Валюта (cCurrencyID) указывается в формате ISO 4217. Для каждого номинала может быть несколько релизов, но с точки зрения XFS, одинаковые номиналы имеют один и тот же индекс (usNoteID), независимо от релиза!

WFS_INF_CIM_CASH_IN_STATUS

Получить данные о последней транзакции приема наличных.

Определение статуса транзакции (wStatus):

• WFS_CIM_CIOK – прием наличных завершен, банкнота сложена в кассету.

• WFS_CIM_CIROLLBACK – прием наличных завершен, банкнота возвращена обратно клиенту.

• WFS_CIM_CIACTIVE – прием наличных активен, после подачи WFS_CIM_CASH_IN_START.

• WFS_CIM_CIUNKNOWN – прием наличных завершен с ошибкой. WFS_ERR_CIM_NOITEMS ошибкой не является!

Команды

WFS_CMD_CIM_CASH_IN_START

Открыть транзакцию приема наличных. Статус транзакции выставляется в WFS_CIM_CIACTIVE. Никаких механических действий не происходит, команда носит логический характер.

Валидация контекста исполнения:

• сервис в состоянии готовности;

• режим инкассации неактивен;

• транзакция приема наличных неактивна;

• кассета устройства готова к приему (fwAcceptor = WFS_CIM_ACCOK, fwAcceptor = WFS_CIM_ACCCUSTATE).

Валидация входных данных:

• fwOutputPosition – WFS_CIM_POSNULL, WFS_CIM_POSOUTCENTER;

• fwInputPosition – WFS_CIM_POSNULL, WFS_CIM_POSINCENTER.

WFS_CMD_CIM_CASH_IN

Активировать готовность устройства к приему наличных, после чего ожидается вставка банкноты. При обнаружении банкноты в слоте приема устройство осуществляет транспортировку банкноты в escrow.

Команда завершается в следующих ситуациях:

• возникновение ошибки;

• подача асинхронной отмены (cancelasyncrequest);

• вставленная банкнота распознана и помещена в escrow или в кассету;

• банкнота отвергнута, если установлен настроечный параметр cashinfinishifbanknoterefused, в противном случае xfs-сервис будет ожидать вставки валидной банкноты.

Валидация контекста исполнения:

• сервис в состоянии готовности;

• режим инкассации неактивен;

• транзакция приема наличных активна;

• escrow (отсек) не заполнен;

• устройство находится в состоянии IDLING или ACCEPTING.

На выход формируется список принятых банкнот (noteNumberList) в рамках данной операции, в этом случае список будет содержать не более одной банкноты.

Если операция выполнена с ошибкой, то статус транзакции выставляется в WFS_CIM_CIUNKNOWN, чтобы в дальнейшем можно было выполнить сброс состояния оборудования (Reset). Не актуально для версии CEN/XFS 3.10 и выше!

Рисунок 26. Схема обработки состояний устройства в процессе выполнения WFS_CMD_CIM_CASH_IN

WFS_CMD_CIM_CASH_IN_END

Закрыть транзакцию приема наличных. Статус транзакции выставляется в WFS_CIM_CIOK.

В рамках исполнения данной команды:

• происходит складирование принятой банкноты в кассету;

• пересчитываются счетчики кассеты;

• деактивируется готовность устройства к приему наличных.

Валидация контекста исполнения:

• сервис в состоянии готовности;

• режим инкассации неактивен;

• транзакция приема наличных активна.

Рисунок 27. Схема обработки состояний устройства в процессе выполнения WFS_CMD_CIM_CASH_IN_END

WFS_CMD_CIM_CASH_IN_ROLLBACK

Закрыть транзакцию приема наличных. Статус транзакции выставляется в WFS_CIM_CIROLLBACK.

В рамках исполнения данной команды:

• происходит возврат ранее принятой в escrow банкноты;

• деактивируется готовность устройства к приему наличных.

Валидация контекста исполнения:

• сервис в состоянии готовности;

• режим инкассации неактивен;

• транзакция приема наличных активна.

Рисунок 28. Схема обработки состояний устройства в процессе выполнения WFS_CMD_CIM_CASH_IN_ROLLBACK

WFS_CMD_CIM_SET_CASH_UNIT_INFO

Изменить следующие данные по кассетам:

• cUnitID (для логической и физической кассеты);

• ulMaximum (для логической кассеты);

• bAppLock.

Команда не позволяет менять значения счетчиков.

Параметры логических кассет и результат их изменения:

• usCount – WFS_ERR_UNSUPP_DATA;

• usNumber – WFS_ERR_CIM_INVALIDCASHUNIT;

• fwType – WFS_ERR_INVALID_DATA;

• fwItemType – WFS_ERR_INVALID_DATA;

• cCurrencyID – WFS_ERR_UNSUPP_DATA;

• ulValues – WFS_ERR_UNSUPP_DATA;

• ulCashInCount – WFS_ERR_UNSUPP_DATA;

• ulCount – WFS_ERR_UNSUPP_DATA;

• lpNoteNumberList – WFS_ERR_UNSUPP_DATA.

Параметры физических кассет и результат их изменения:

• usNumPhysicalCUs – WFS_ERR_UNSUPP_DATA;

• lpPhysicalPositionName – WFS_ERR_UNSUPP_DATA;

• ulCashInCount – WFS_ERR_UNSUPP_DATA;

• ulCount – WFS_ERR_UNSUPP_DATA.

При изменении всех остальных параметров возвращается успешный результат, но изменения фактически не произойдет.

Валидация контекста исполнения: режим инкассации неактивен.

WFS_CMD_CIM_START_EXCHANGE

Начать замену кассет (инкассацию).

Валидация контекста исполнения:

• режим инкассации неактивен;

• сервис в состоянии готовности;

• транзакция приема наличных неактивна.

Валидация входных данных:

• fwExchangeType – WFS_CIM_EXBYHAND;

• usCount – 1 (кол-во кассет);

• lpusCUNumList – первый элемент должен быть равен 1 (номер логической кассеты).

WFS_CMD_CIM_END_EXCHANGE

Завершить замену кассет (инкассацию). Команда позволяет только обнуление счетчиков кассеты и пономинального списка банкнот, находящихся в кассете (noteNumberList).

Валидация контекста исполнения: режим инкассации неактивен;

Валидация входных данных:

• допускается NULL в качестве указателя на входную структуру. В данном случае замена кассет завершится без изменения счетчиков;

• ulCount, ulCashInCount = 0;

• noteNumberList пустой;

• не поддерживается изменение структуры кассет, изменение валют и номиналов, порогов ulMaximum/ulMinimum.

WFS_CMD_CIM_RESET

Сбросить состояние оборудования.

Устройство производит внутреннюю проверку механических узлов. Если взаимодействие с сервис-провайдером открыто под версией CEN/XFS 3.10, то активная транзакция приема наличных или активная сессия замены кассеты будут закрыты.

Валидация контекста исполнения:

• режим инкассации неактивен (неактуально для 3.10);

• транзакция приема наличных неактивна (неактуально для 3.10).

Валидация входных данных: все входные параметры игнорируются.

WFS_CMD_CIM_CONFIGURE_NOTETYPES

Сконфигурировать номиналы, которые в дальнейшем будут поддерживаться в рамках операции приема наличных. Не сконфигурированные номиналы будут возращены при приеме обратно.

Аппаратные особенности купюроприемника не позволяют поддерживать более 50 номиналов.

Валидация контекста исполнения:

• сервис в состоянии готовности;

• режим инкассации неактивен;

• разрешаем выполнять данную команду после старта транзакции приема наличных, однако до вставки первой банкноты.

Валидация входных данных:

• lpusNoteIDs – индексы банкнот должны поддерживаться устройством.

Поддерживаемые события

• WFS_USRE_CIM_CASHUNITTHRESHOLD – cобытие генерируется в случае достижения счетчиком логической кассеты значения максимума логической кассеты (WFSCIMCASHINFO.lppCashIn[0].ulMaximum). Статус кассеты устанавливается в значение WFS_CIM_STATCUHIGH. Значение максимума логической кассеты должно быть больше нуля.

• WFS_SRVE_CIM_CASHUNITINFOCHANGED – cобытие генерируется в случае изменения статуса кассеты (кроме ситуаций, приводящих к событиям WFS_USRE_CIM_CASHUNITTHRESHOLD), а также изменения данных по кассете после конфигурации/инкассации. Консолидирующим событием в случае возникновения ситуации, требующей рассылки событий WFS_USRE_CIM_CASHUNITTHRESHOLD и WFS_SRVE_CIM_CASHUNITINFOCHANGED, будет WFS_SRVE_CIM_CASHUNITINFOCHANGED.

• WFS_SRVE_CIM_ITEMSTAKEN – cобытие генерируется после предъявления банкноты клиенту, если установлен параметр EmulateItemsTakenEvent (эмуляция события взятия банкноты из презентера – отправляется сразу при предъявлении банкноты клиенту). Устройство не контролирует физическое изъятие банкноты из слота приема/возврата наличных.

• WFS_SRVE_CIM_ITEMSPRESENTED – cобытие генерируется в случае предъявления банкноты клиенту в слот приема/возврата для изъятия.

  Случаи предъявления:

  • откат транзакции приема наличных (WFS_CMD_CIM_ROLLBACK);

  • возврат отвергнутой банкноты (REFUSEDITEMS).

• WFS_SRVE_CIM_MEDIADETECTED – Событие генерируется в случае обнаружения банкноты на транспорте (временный накопитель, на этапе складирования в кассету) во время исполнения команды WFS_CMD_CIM_RESET. Впараметрах события указывается место нахождения обнаруженных ранее банкнот по окончанию операции инициализации (кассета, слот приема/возврата).

• WFS_SRVE_CIM_INPUTREFUSE – Событие генерируется в случае наличия отвергнутой банкноты в процессе операции приема наличных (WFS_CMD_CIM_CASH_IN). Возможная причина возврата – WFS_CIM_INVALIDBILL (ошибка валидации, банкнота не разрешена к приему).

• WFS_SRVE_CIM_ITEMSINSERTED – Событие генерируется в случае вставки банкнот в слот приема/возврата устройства.

• WFS_EXEE_CIM_INSERTITEMS – Событие генерируется в случае готовности устройства принять очередную банкноту.