Объект
CashMaticCashSession отвечает за сеанс купюроприёмника.
Сеанс купюроприёмника - это процесс, в ходе которого купюроприёмник принимает купюры от пользователя.
Сеанс купюроприёмника рассматривается отдельно от платёжного сеанса (см.
Сеанс приёма платежа). Обычно сеанс купюроприёмника входит как стадия в платёжный сеанс, однако возможны и другие сценарии (например, когда приём купюр постоянно разрешён).
С точки зрения общего сценария платежа (сценария работы пользователя) приём купюр часто удобно рассматривать как одно целостное событие или состояние: "пользователь вносит деньги". На самом деле за время этого состояния происходит ряд переключений - сеанс купюроприёмника состоит из одного и более циклов включения-выключения приёма купюр на купюроприёмнике, причём каждый цикл может отличаться от других диапазоном принимаемых купюр, таймаутом и т.п.
Объект
CashMaticCashSession разработан с целью упрощения взаимодействия прикладного скрипта с купюроприёмником, одновременно обеспечивая программиста инструментами гибкого управления процессом приёма купюр и надёжными средствами подсчёта принятых купюр.
Объект
CashMaticCashSession отвечает за все деньги, принятые от текущего пользователя. Теоретически можно создать одновременно несколько объектов
CashMaticCashSession, тогда это будет как бы несколько пулов денег - но на практике вряд ли стоит конструировать столь запутанный для пользователя механизм.
Объект
CashMaticCashSession поддерживает особый режим - проверка купюр (см.
Режимы проверки купюр и приёма купюр). В режиме проверки купюры не принимаются, а только детектируются (определяется подлинность и номинал), после чего не складируются, а возвращаются пользователю. Этот режим можно использовать, например, для проверки исправности купюроприёмника (или можно предложить пользователю терминала некоторый дополнительный сервис).
Основным элементом управления работой оборудования по приёму купюр в
NDemia CashMatic является свойство
Active объекта
CashMaticCashSession (логическое значение).
Присваивание
Active=true включает купюроприёмник на приём/проверку наличных (приём или проверка - в зависимости от значения свойства
Detect, истинное значение соответствует проверке, ложное - приёму).
Далее приём или проверка наличных будет выполняться до одного из следующих событий:
- приём купюры (вызывается событие OnAccept) или проверка купюры (вызывается событие OnDetect);
Примечание: положительный результат ожидания купюры может быть симулирован командой SIMCASH, описанной в разделе Дополнительные средства. Эта команда специально предусмотрена для возможности отладки обработки приёма наличных денег в прикладных скриптах и компонентах расширения (плагинах) NDemia CashMatic без использования и даже без подключения купюроприёмника.
- превышение таймаута, заданного свойством Timeout (вызывается событие OnTimeout);
- отказ купюроприёмника в приёме купюры (вызывается событие OnReject);
- присваивание Active=false или вызов метода Cancel() (вызывается событие OnCancel);
- отказ из-за нештатного состояния оборудования по решению драйвера купюроприёмника (вызывается событие OnCancel);
Примечание: механизм мониторинга состояния купюроприёмника в NDemia CashMatic в общем случае не требует дополнительного программирования или настроек, однако при необходимости прикладной программист имеет возможность вмешаться его в работу. Для этого следует ознакомиться с командами BVSTATMON, CONFIG BillValidatorBadStatusMask, GETCASH (команды описаны в разделе Дополнительные средства). Команда BVSIMEVENT может быть использована для отладки обработки различных состояний купюроприёмника в прикладных скриптах и компонентах расширения (плагинах) без физического подключения купюроприёмника.
- общий отказ (вызывается событие OnFailure);
- удаление объекта CashMaticCashSession (никакие события не вызываются).
После возникновения одного из вышеперечисленных событий свойство
Active переходит в
false. Если требуется/допускается дальнейшее продолжение приёма купюр, требуется явно установить
Active обратно в
true в коде обработки соответствующего события.
При каждом изменении свойства
Active вызывается событие
OnActive.
Присваивание
Active=false (или вызов метода
Cancel()) выключает приём купюр на купюроприёмнике.
Приём купюр на купюроприёмнике нужно обязательно явно выключать до прекращения существования объекта CashMaticCashSession, чтобы можно было узнать окончательное количество принятых денег, иначе есть риск потерять последнюю введённую пользователем купюру. Если по какой-либо причине объект будет удалён без явного прекращения приёма купюр, то может оказаться пропущенной последняя вставка купюры пользователем в купюроприёмник, поскольку не сработают обработчики событий купюроприёмника, связанные с
CashMaticCashSesssion, т.е. последняя купюра окажется вообще нигде не зафиксированной (кроме лог-файлов).
Примечание: прикладному программисту настоятельно рекомендуется в своей разработке принять все возможные меры для явного прекращения приёма купюр в любой ситуации - использовать в javascript обработку try-catch, событие onunload, и т.п. механизмы, обеспечивающие выполнение кода даже в заранее непредусмотренных нештатных ситуациях.
Следует помнить: приём купюр должен быть остановлен (Active=false) до анализа окончательного количества принятых денег, иначе всегда возможен интервал хотя бы в малую долю секунды, за который может поступить сигнал об ещё одной принятой купюре, и она может оказаться нигде не учтённой.
Присваиванию Active=false вполне можно доверять, это не просто сброс флага - запускается целый ряд механизмов внутренней синхронизации NDemia CashMatic, которые однозначно гарантируют, что после выполнения Active=false больше не будет принята ни одна купюра.
Существует возможность ограничить диапазон допустимых номиналов принимаемых купюр (минимальный и максимальный номинал принимаемой купюры), используя свойства
MinBill,
MaxBill или методы
SetBillRange()/
ResetBillRange().
Примеры:
- MinBill=100 - не принимать купюры с номиналом менее 100 рублей.
- MaxBill=500 - не принимать купюры с номиналом более 500 рублей.
- SetBillRange(50, 1000) - принимать купюры только от 50 рублей до 1000 рублей.
- ResetBillRange() - снять все предыдущие ограничения, далее принимать все купюры.
При изменении диапазона допустимых номиналов принимаемых купюр вызывается событие
OnBillRange.
Объект
CashMaticCashSession предоставляет информацию о номинале принятой или проверенной купюры:
- свойство Accepted возвращает принятую купюру (доступно во время выполнения события OnAccept);
- свойство LastAccepted возвращает последнюю принятую купюру на текущий момент (доступно постоянно);
- свойство Detected возвращает проверенную купюру (доступно во время выполнения события OnDetect);
- свойство LastDetected возвращает последнюю проверенную купюру на текущий момент (доступно постоянно).
Объект CashMaticCashSession предоставляет прикладному программисту несколько способов получения информации о происходящих событиях сеанса купюроприёмника (см.
Примеры обработчиков событий сеанса купюроприёмника).
Обработчиком события может быть текстовая строка, которая при вызове события будет выполнена как код javascript в контексте текущего документа.
Обработчиком события может быть функция javascript, которая будет выполняться при вызове события.
Обработчик в виде строки или функции у события может быть только один, назначение нового кода обработки заменяет предыдущий код, если он был.
Кроме того, прикладной скрипт может создать объект-обработчик событий купюроприёмника (см. интерфейс
CashMaticCashSessionEvents)
Объектный обработчик событий купюроприёмника устанавливается вызовом метода
AddHandler и удаляется вызовом метода
RemoveHandler объекта
CashMaticCashSession.
Объектных обработчиков событий купюроприёмника может быть создано и установлено одновременно несколько (более одного), они существуют и вызываются независимо друг от друга, а также от простых обработчиков (т.е. от назначенных в виде строки или функции).
Объект
CashMaticCashSession отвечает за подсчёт принятых и проверенных купюр.
Прикладной программист может использовать различные уровни детализации счётчиков, в зависимости от своих задач:
- свойство BillCount возвращает количество купюр, принятых в ходе сеанса купюроприёмника (не денежную сумму, а именно количество купюр, проверенные и возвращённые купюры не входят в это значение);
- свойство BillTotal возвращает денежную сумму, принятую в ходе сеанса купюроприёмника (проверенные и возвращённые купюры не входят в это значение);
- свойство DetectCount возвращает количество купюр, успешно проверенных и возвращённых пользователю в ходе сеанса купюроприёмника;
- метод GetBillCountByDenom() возвращает количество купюр определённого номинала, принятых в ходе сеанса купюроприёмника;
- метод GetBillCounters() возвращает коллекцию счётчиков купюр для каждого принятого номинала (в виде объекта CashMaticItems);
- свойство RejectCount возвращает количество купюр, забракованных и возвращённых пользователю в ходе сеанса купюроприёмника;
- метод ResetCounters() сбрасывает все счётчики купюр сеанса купюроприёмника.
| Имя | Тип результата | Тип обращения | Назначение |
| Accepted | Объект CashMaticBill, число | Свойство, только чтение | Принятая купюра, номинал.
Совместимость: поддерживается, начиная с версии 2.6.0 |
| Active | Логический | Свойство, чтение/запись | Управление купюроприёмником:
- Истинное значение включает приём или проверку купюр (в зависимости от значения свойства Detect - см. Режимы проверки купюр и приёма купюр);
- Ложное значение выключает приём/проверку купюр.
Не изменять во время вызова события OnActive (•).
|
| AddHandler(Handler) | Число | Метод | Метод устанавливает (добавляет) обработчик событий сеанса купюроприёмника.
Параметр Handler - объект, реализующий интерфейс CashMaticCashSessionEvents.
Возвращаемое численное значение - идентификатор обработчика, используется для последующего удаления обработчика вызовом метода RemoveHandler.
(см. Примеры обработчиков событий сеанса купюроприёмника)
Совместимость: поддерживается, начиная с версии 2.6.0 |
| BillCount | Объект CashMaticCashCounter, число | Свойство, только чтение | Счётчик принятых купюр в данном сеансе купюроприёмника.
Совместимость: ранее версии 2.6.0 количество купюр возвращается только как число. |
| BillTotal | Объект CashMaticCurrency, число | Свойство, только чтение | Количество принятых денег (в денежных единицах) в данном сеансе купюроприёмника.
Совместимость: ранее версии 2.6.0 количество денег возвращается только как число. |
| Cancel() | Пустой | Метод | Метод выключает приём/проверку купюр на купюроприёмнике.
Не вызывать во время вызова события OnActive (•).
Совместимость: поддерживается, начиная с версии 2.6.0 |
| Cash | Объект CashMaticCash | Свойство, только чтение | Возвращает родительский объект управления купюроприёмником CashMaticCash.
Совместимость: поддерживается, начиная с версии 2.6.0 |
| Detect | Логическое | Свойство, чтение/запись | Управление режимом проверки купюр (см. Режимы проверки купюр и приёма купюр):
- Истинное значение включает режим проверки купюр (выключая тем самым режим приёма купюр);
- Ложное значение выключает режим проверки купюр (включая тем самым режим приёма купюр).
Совместимость: поддерживается, начиная с версии 2.6.0 |
| DetectCount | Число | Свойство, только чтение | Количество проверенных купюр в данном сеансе купюроприёмника (см. Режимы проверки купюр и приёма купюр).
Совместимость: поддерживается, начиная с версии 2.6.0 |
| Detected | Объект CashMaticBill, число | Свойство, только чтение | Проверенная купюра, номинал.
Совместимость: поддерживается, начиная с версии 2.6.0 |
| GetBillCountByDenom(Denom) | Объект CashMaticBillCounter, число | Метод | Возвращает количество принятых купюр указанного номинала в данном сеансе купюроприёмника (параметр Denom - численное значение, в денежных единицах).
Совместимость: ранее версии 2.6.0 количество купюр возвращается только как число. |
| GetBillCounters() | Объект CashMaticItems
| Метод | Набор счётчиков купюр, принятых в данном сеансе купюроприёмника, раздельно по типам купюр (отдельный счётчик для каждого типа купюр).
Результат возвращается в виде коллекции CashMaticItems, элементами коллекции являются объекты CashMaticBillCounter.
Совместимость: поддерживается, начиная с версии 2.6.0 |
| LastAccepted | Объект CashMaticBill, число | Свойство, только чтение | Последняя (на текущий момент) купюра, принятая в данном сеансе купюроприёмника, номинал.
Совместимость: поддерживается, начиная с версии 2.6.0 |
| LastDetected | Объект CashMaticBill, число | Свойство, только чтение | Последняя (на текущий момент) купюра, проверенная в данном сеансе купюроприёмника, номинал.
Совместимость: поддерживается, начиная с версии 2.6.0 |
| MaxBill | Объект CashMaticBill, число | Свойство, чтение/запись | Максимальный допустимый номинал следующей купюры в данном сеансе купюроприёмника. По умолчанию - максимальный поддерживаемый номинал (в текущей версии - 5000 руб.).
При изменении значения свойства вызывается событие OnBillRange.
Совместимость: ранее версии 2.6.0 поддерживается только численное значение, событие OnBillRange не поддерживается. |
| MinBill | Объект CashMaticBill, число | Свойство, чтение/запись | Минимальный допустимый номинал следующей купюры в данном сеансе купюроприёмника. По умолчанию - минимальный поддерживаемый номинал (в текущей версии - 5 руб. ).
При изменении значения свойства вызывается событие OnBillRange.
Совместимость: поддерживается, начиная с версии 2.6.0 |
| OnAccept | Строка или функция | Свойство, чтение/запись | Скрипт, выполняемый при успешном приёме купюры в данном сеансе купюроприёмника.
- Если задана строка, то при вызове события она выполняется как javascript (в контексте текущего HTML-документа, принятая купюра доступна через свойство Accepted);
- Если задана функция, то при вызове события она вызывается с параметрами (CashSession, Bill), где:
- CashSession - сеанс купюроприёмника, в котором произошёл приём купюры (объект CashMaticCashSession);
- Bill - принятая купюра, номинал (эквивалентно значению Accepted) (объект CashMaticBill).
Совместимость: ранее версии 2.6.0 поддерживается только строковое значение. |
| OnActive | Строка или функция | Свойство, чтение/запись | Скрипт, выполняемый при изменении активности данного сеанса купюроприёмника (изменении свойства Active или вызове метода Cancel), т.е. при включении или выключении приёма/проверки купюр.
- Если задана строка, то при вызове события она выполняется как javascript (в контексте текущего HTML-документа, состояние активности доступно через свойство Active);
- Если задана функция, то при вызове события она вызывается с параметрами (CashSession, Active), где:
- CashSession - сеанс купюроприёмника, в котором произошло изменение активности (объект CashMaticCashSession);
- Active - логическое значение, равное новому (изменившемуся) значению свойства Active.
Не изменять значение свойства Active во время вызова события OnActive (•).
Совместимость: поддерживается, начиная с версии 2.6.0 |
| OnBillCount | Строка или функция | Свойство, чтение/запись | Скрипт, выполняемый при изменении количества принятых купюр в данном сеансе купюроприёмника (вызывается как при успешном приёме купюры, так и при сбросе счётчиков вызовом метода ResetCounters()).
- Если задана строка, то при вызове события она выполняется как javascript (в контексте текущего HTML-документа, количество принятых купюр доступно через свойство BillCount);
- Если задана функция, то при вызове события она вызывается с параметрами (CashSession, BillCount), где:
- CashSession - сеанс купюроприёмника, в котором произошло изменение количества принятых купюр (объект CashMaticCashSession);
- BillCount - значение, равное новому (изменившемуся) количеству принятых купюр (объект CashMaticCashCounter).
Совместимость: поддерживается, начиная с версии 2.6.0 |
| OnBillRange | Строка или функция | Свойство, чтение/запись | Скрипт, выполняемый при изменении диапазона допустимых номиналов купюр в данном сеансе купюроприёмника (вызывается как при изменении диапазона через свойство MinBill, свойство MaxBill, метод SetBillRange(), так и при сбросе диапазона вызовом метода ResetBillRange()).
- Если задана строка, то при вызове события она выполняется как javascript (в контексте текущего HTML-документа, диапазон допустимых номиналов купюр доступен через свойства MinBill и MaxBill);
- Если задана функция, то при вызове события она вызывается с параметрами (CashSession, MinBill, MaxBill), где:
- CashSession - сеанс купюроприёмника, в котором произошло изменение диапазона допустимых номиналов купюр (объект CashMaticCashSession);
- MinBill - значение, равное новому (изменившемуся) минимальному допустимому номиналу купюр (объект CashMaticBill),
- MaxBill - значение, равное новому (изменившемуся) максимальному допустимому номиналу купюр (объект CashMaticBill).
Совместимость: поддерживается, начиная с версии 2.6.0 |
| OnCancel | Строка или функция | Свойство, чтение/запись | Скрипт, выполняемый при отмене/прекращении приёма/проверки купюр в данном сеансе купюроприёмника.
- Если задана строка, то при вызове события она выполняется как javascript (в контексте текущего HTML-документа);
- Если задана функция, то при вызове события она вызывается с параметром (CashSession), где:
- CashSession - сеанс купюроприёмника, в котором прекратились приём/проверка купюр.
Совместимость: ранее версии 2.6.0 поддерживается только строковое значение. |
| OnDetect | Строка или функция | Свойство, чтение/запись | Скрипт, выполняемый при успешной проверке купюры в данном сеансе купюроприёмника.
- Если задана строка, то при вызове события она выполняется как javascript (в контексте текущего HTML-документа, принятая купюра доступна через свойство Accepted);
- Если задана функция, то при вызове события она вызывается с параметрами (CashSession, Bill), где:
- CashSession - сеанс купюроприёмника, в котором произошла проверка купюры (объект CashMaticCashSession);
- Bill - проверенная купюра, номинал (эквивалентно значению Detected) (объект CashMaticBill).
Совместимость: поддерживается, начиная с версии 2.6.0 |
| OnFailure | Строка или функция | Свойство, чтение/запись | Скрипт, выполняемый при ошибке купюроприёмника в данном сеансе.
- Если задана строка, то при вызове события она выполняется как javascript (в контексте текущего HTML-документа);
- Если задана функция, то при вызове события она вызывается с параметром (CashSession), где:
- CashSession - сеанс купюроприёмника, в котором произошла ошибка.
Совместимость: ранее версии 2.6.0 поддерживается только строковое значение. |
| OnReject | Строка или функция | Свойство, чтение/запись | Скрипт, выполняемый в случае браковки купюры при приёме/проверке в данном сеансе купюроприёмника (купюра возвращается пользователю).
- Если задана строка, то при вызове события она выполняется как javascript (в контексте текущего HTML-документа);
- Если задана функция, то при вызове события она вызывается с параметром (CashSession), где:
- CashSession - сеанс купюроприёмника, в котором произошла браковка купюры.
Совместимость: ранее версии 2.6.0 поддерживается только строковое значение. |
| OnTimeout | Строка или функция | Свойство, чтение/запись | Скрипт, выполняемый в случае завершения по таймауту приёма/проверки купюры в данном сеансе купюроприёмника.
- Если задана строка, то при вызове события она выполняется как javascript (в контексте текущего HTML-документа, значение таймаута доступно через свойство Timeout);
- Если задана функция, то при вызове события она вызывается с параметрами (CashSession, Timeout), где:
- CashSession - сеанс купюроприёмника, в котором произошла браковка купюры.
- Timeout - таймаут (превышенное значение, в секундах - соответствует свойству Timeout).
Совместимость: поддерживается, начиная с версии 2.6.0 |
| RejectCount | Число | Свойство, только чтение | Количество отказов в приёме купюры (см. OnReject) в данном сеансе купюроприёмника. |
| RemoveHandler(Id) | Пустой | Метод | Метод снимает (удаляет) обработчик событий сеанса купюроприёмника.
Параметр Id - идентификатор обработчика (число), полученный при установке обработчика в результате вызова метода AddHandler.
(см. Примеры обработчиков событий сеанса купюроприёмника)
Совместимость: поддерживается, начиная с версии 2.6.0 |
| ResetBillRange() | Пустой | Метод | Метод сбрасывает ограничения диапазона допустимых номиналов купюр.
Минимальный/максимальный допустимые номиналы следующей купюры в данном сеансе купюроприёмника принимают значение по умолчанию - минимальный поддерживаемый номинал (в текущей версии - 5 руб. ), максимальный поддерживаемый номинал (в текущей версии - 5000 руб.).
При сбросе ограничений допустимых номиналов купюр вызывается событие OnBillRange.
Совместимость: поддерживается, начиная с версии 2.6.0 |
| ResetCounters() | Пустой | Метод | Метод сбрасывает все счётчики данного сеанса приёма купюр.
При сбросе счётчиков принятых купюр вызывается событие OnBillCount.
Совместимость: поддерживается, начиная с версии 2.6.0 |
| SetBillRange(MinBill, MaxBill) | Пустой | Метод | Метод устанавливает ограничения диапазона допустимых номиналов купюр.
При изменении ограничений допустимых номиналов купюр вызывается событие OnBillRange.
Совместимость: поддерживается, начиная с версии 2.6.0 |
| Timeout | Число | Свойство, чтение/запись | Таймаут активного состояния приёма/проверки купюры, в секундах (по умолчанию - нулевое значение, соответствует отсутствию ограничения).
Таймаут отсчитывается от момента присваивания истинного значения свойству Active.
При превышении таймаута срабатывает событие OnTimeout.
Совместимость: поддерживается, начиная с версии 2.6.0 |
(•) Попытка изменить значение свойства Active во время выполнения обработчика события OnActive приведёт к программной ошибке с сообщением "Текущий сеанс купюроприёмника невозможно прервать в данный момент" или "Сеанс купюроприёмника невозможно активировать в данный момент".
Совместимость: ошибка вбрасывается, начиная с версии 2.7.2, в предыдущих версиях это действие всё равно запрещено, может быть проигнорировано или выполнено неправильно.
