26.09.2018

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

Внимание! Данные требования устарели. Актуальные требования размещены в статье.

Версия 1.4

• Введение
• Общие требования к разрабатываемому драйверу
• Обязательные команды, связанные с использованием драйвера в системе
• Описание команд, специфичных для работы с подключаемым оборудованием
  • Требования к разработке драйверов устройств ввода
  • Требования к разработке драйверов принтеров чеков
  • Требования к разработке драйверов платежных систем
  • Требования к разработке драйверов для ККТ с функцией передачи в ОФД
• Подключение драйверов разработанных по стандарту «1С: Совместимо» к конфигурации БПО

Введение

Данный документ описывает технологию и требования к разработке мобильных драйверов подключаемого оборудования с использованием новой технологии создания внешних компонент, представленной в платформе "1С:Предприятие" версии 8.3.9. Для просмотра документа по разработке интеграционных приложений для мобильной платформы версии 8.3.8 и ранее перейдите по данной ссылке. При этом механизм работы с интеграционными приложениями также поддерживается в платформе 8.3.9, но при разработке новых драйверов мы рекомендуем использовать новую технологию и данный документ.

Для подключения оборудования по новой технологии к мобильной платформе "1С:Предприятие" и при последующей работе с ним используется "1С:Библиотека подключаемого оборудования для мобильных приложений, редакция 2.0”. Библиотека предоставляет набор механизмов для унифицированной работы с подключаемым оборудованием. Применение данной библиотеки позволяет ускорить реализацию поддержки широкого спектра моделей подключаемого оборудования в разрабатываемых конфигурациях, а также добавить готовые функциональные блоки в уже работающие мобильные приложения. 

Для подключения оборудования к "1С:Библиотека подключаемого оборудования для мобильных приложений, редакция 2.0” необходимо разработать мобильный драйвер на основе внешней компоненты по технологии создания внешних компонент, реализующий интерфейс по требованиям, описываемым в данном документе. 

Интерфейс мобильного драйвера можно условно разделить на несколько частей:

• Первый раздел - общие требования к мобильному драйверу и его архитектуре;
• Второй раздел - системная, определяет набор служебных функций и методов, связанных с использованием мобильного драйвера подключаемого оборудования в системе – подключение и настройка драйвера, получение его описания, тестирование и обслуживание ошибок;
• Третий раздел - функциональная, определяет обязательный набор команд, специфичных для определенного типа подключаемого оборудования;
• Четвертый раздел - действия по подключению драйверов, разработанных по стандарту «1С: Совместимо» к конфигурации "1С:Библиотека подключаемого оборудования для мобильных приложений, редакция 2.0”.

1. Общие требования к разрабатываемому драйверу

Разрабатываемый драйвер должен:

1. Быть разработан в виде внешней компоненты по технологии Native API создания внешних компонент, приведенной в статье "Технология создания внешних компонент". При разработке стоит учитывать некоторые специфические требования, относящиеся к внешним компонентам для мобильной платформы.
2. Внешняя компонента для работы с подключаемым оборудованием должна содержать только один объект, реализующий расширение встроенного языка, и возвращать методом «RegisterExtensionAs» имя расширения, совпадающее с второй частью ProgID компоненты. Пример: для компоненты с ProgID «AddIn.Scanner» функция должна возвращать «Scanner». Имя расширения не должно содержать пробелов и недопустимых символов (в соответствии с правилами формирования имен объектов "1С:Предприятия").
3. Обеспечить возможность реализации функционала в полном объеме (должны быть реализованы и работать все методы) для подключаемого типа оборудования. Если оборудованием данная функция не поддерживается, должно возвращаться "False", а в описании ошибки, возвращаемом методом «ПолучитьОшибку (GetLastError)», содержится текст, что данная функция оборудованием не поддерживается.
4. Предоставлять русскоязычные и англоязычные названия методов (например ПолучитьОшибку() - GetLastError() и др.).
5. Поддерживать работу с несколькими экземплярами устройств, в рамках процедур в которых используется данное оборудование.
6. При возникновении ошибки в работе предоставлять подробное описание произошедшей ошибки, позволяющее пользователю понять причину ее возникновения и возможный способ устранения.
7. При возникновении внештатных ситуаций (некорректные действия пользователя, отсутствие запрашиваемого метода или функции, передача некорректных значений и др.) корректно обрабатывать их. Не должно быть аварийных завершений работы драйвера и прочих действий драйвера, которые могут привести к нарушению нормальной работы пользователя.
8. Принимать/возвращать и обрабатывать таблицы значений в виде XML документа (текст в формате XML с кодировкой UTF-8, передаваемый с помощью параметра типа STRING). Для упрощения обработки структур данных используются наименования атрибутов только на английском языке.
9. Обрабатывать метод SetLocale для локализации драйвера в соответствии с полученным кодом локализации и настраивать свое окружение (текстовые надписи, сообщения об ошибках и т.д.). Драйвер должен поддерживать локализированное окружение для локального кода региона и локализацию окружения на английском языке. Если полученный код локализации отличается от предусмотренного в драйвере, то драйвер должен настроить свое окружение на использование английского языка. Более подробно использование метода SetLocale описано в документе "Технология создания внешних компонент".

При разработке мобильного драйвера вы также можете использовать один из двух подходов

• Однокомпонентный драйвер - драйвер, представляющий из себя лишь внешнюю компоненту, и, таким образом, предназначенный для использования только с мобильной платформой «1С:Предприятие». При разработке драйвера в виде одного файла все используемые run-time библиотеки и другие необходимые файлы должны статически включаться в драйвер, так как на устройстве пользователя их может не оказаться или они могут быть другой версии.
• Многокомпонентный драйвер - драйвер представляющий из себя более сложный комплекс, состоящий из двух частей:
  • Интеграционная библиотека - промежуточная компонента для связи мобильной платформы "1С Предприятия" с основной поставкой драйвера. Имеет интерфейс, разработанный в соответствии с общими требованиями к драйверу и технологией разработки внешних компонент, но не реализует функционала драйвера подключаемого оборудования. Интеграционная библиотека реализует функционал поиска установленной основной поставки драйвера, его инициализации и переадресации вызовов.
  • Основная поставка драйвера - драйвер поставщика, реализованный по произвольной технологии и состоящий из произвольного набора файлов. Протокол взаимодействия драйвера с интеграционной библиотекой не регламентируется данными требованиями. Распространение основной поставки драйвера является прерогативой поставщика.

2. Обязательные функции и методы, связанные с использованием драйвера подключаемого оборудования в системе

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

Драйвер поддерживает два основных этапа работы с оборудованием в конфигурации:

• Регистрация и настройка оборудования
• Использование оборудования пользователем в процессе работы

Регистрация и настройка оборудования

1. Получение описания драйвера вызовом метода «ПолучитьОписание (GetDescription)».
2. Получения доступных параметров для настройки драйвера методом «ПолучитьПараметры (GetParameters)».
3. Построение формы настройки драйвера на основании списка доступных параметров.
4. Сохранение параметров настройки драйвера в базе данных конфигурации.

Использование оборудования пользователем в процессе работы

1. Инициализация устройства сохраненными в базе параметрами методом «УстановитьПараметр (SetParameter)».
2. Подключение оборудования с помощью метода «Подключить (Open)» с текущими значениями параметров, установленными вызовами метода «УстановитьПараметр (SetParameter)».
   Метод «Подключить (Open)» возвращает идентификатор подключенного экземпляра устройства.
3. Вызов обязательных функций и методов, специфичных для данного типа подключаемого оборудования, с использованием идентификатора подключенного экземпляра устройства.
4. Получение кода ошибки и описания ошибки методом «ПолучитьОшибку (GetLastError)» в случае ее возникновения.
5. Отключение устройства методом «Отключить (Close)» по идентификатору подключенного экземпляра устройства.

ВНИМАНИЕ: Все значения интерфейсных элементов (наименование, описание, заголовки, сообщения) должны быть реализованы на языке, установленном кодом локализации. (см. п.9 раздела Общие требования к разрабатываемому драйверу и его архитектуре.)

* - Строка, определяющая тип оборудования, имеет одно из значений: “УстройствоВвода“, “ПринтерЧеков“, “ПлатежнаяСистема“, “ККТ“. 
** - Версия требований – версия текущего документа (Версии 1.1 соответствует число 2001, версии 1.4 соответствует число 2004)

Описание структуры TableParameters

Текст в формате XML, передаваемый с помощью параметра типа STRING. Содержит описание всех параметров драйвера и описание визуального интерфейса настройки драйвера.

Необходимые для работы параметры могут быть структурированы для вывода на форму конфигурации "1С:Предприятия" - распределены по закладкам и группам на закладке. Закладки и группы могут иметь наименования, которые отобразятся на форме. Для параметров могут быть заданы определенные значения, которые сформируют выпадающий список для выбора. Наконец, поля параметров, зависимых от других параметров, могут активироваться по необходимости.

Пример XML описывающего параметры интеграционного приложения:

<?xml version="1.0" encoding="UTF-8" ?>
<Settings>
    <Page Caption="Параметры"> 
        <Group Caption="Параметры подключения">
            <Parameter Name="Model" Caption="Модель"/> 
            <Parameter Name="Port" Caption="Порт" TypeValue="Number" DefaultValue="0">
                <ChoiceList>
                     <Item Value="1">COM1</Item>
                     <Item Value="2">COM2</Item>
                </ChoiceList>
            </Parameter>
            <Parameter Name="Parity" Caption="Четность" TypeValue="Number" DefaultValue="True"/>
            <Parameter Name="Speed" Caption="Скорость" TypeValue="Number" FieldFormat="" DefaultValue="1"/>
        </Group>
    </Page>
</Settings>

3. Описание методов, специфичных для типов подключаемого оборудования

3.1. Требования к разработке драйверов устройств ввода (сканеры штрихкода, считыватели магнитных карт и т.д.)

Данные устройства реализуют функцию автоматического считывания закодированной различными способами информации и асинхронной передачи ее в конфигурацию "1С:Предприятия". Драйвера устройств такого типа не предусматривают специфических для оборудования методов, которые можно вызывать из конфигураций.

Работа с драйвером строится следующим образом:

1. При инициализации объекта компоненты ему передается указатель на интерфейс "1С:Предприятия", с помощью которого можно вызывать метод: 
   HRESULT ExternalEvent(BSTR bstrWho, BSTR bstrWhat, BSTR bstrData)
2. При каждом успешном считывании кода сканером или считывателем драйвер должен вызывать метод HRESULT ExternalEvent(BSTR bstrWho, BSTR bstrWhat, BSTR bstrData).
3. Переданные данные размещаются в очереди сообщений. Сообщения из очереди обрабатываются только после обработки всех системных сообщений "1С:Предприятия". При переполнении очереди полученные сообщения игнорируются.

Описание методов, доступных для асинхронного вызова из драйвера*

* - Описание остальных функций, доступных для вызова из драйвера, см. в документе «Технология создания внешних компонент»
** - В параметре bstrWho драйвер передает уникальный идентификатор подключенного устройства.
*** - Параметр bstrWhat используется для поддержки событий различных типов.

Типы события поддерживаемы драйверами устройства ввода:

3.2. Требования к разработке драйверов принтеров чеков

При работе с принтерами чеков поддерживаются следующие операции:

• Печать текстовых чеков;
• Печать штрихкодов;
• Открытие денежного ящика.

При подключении устройства методом "Подключить (Open)" драйвер устанавливает режим печати, настраивает кодировку принтера чеков или производит другие необходимые действия по инициализации печати на устройстве.

Алгоритм построчной печати чека

Выполнение команд построчной печати чеков осуществляется по следующему алгоритму:

1. Открытие документа;
2. Печать текстовых строк / печать штрихкода;
3. Закрытие документа.

Открытие документа - Открытие текстового чека происходит методом «ОткрытьДокумент (OpenDocument)».

Печать текстовых строк - Печать текстовых строк осуществляется методом «НапечататьСтроку (PrintString)». Выводится произвольная текстовая строка на чековой ленте.
Для длинных строк перенос не предусмотрен: строки обрезаются до максимально возможной длины строки печатающего устройства.

Печать штрихкода - Печать штрихкода осуществляется методом «НапечататьШтрихКод (PrintBarCode)». Осуществляется печать штрихкода в открытом документе, если это позволяет сделать модель устройства.

Закрытие чека - Закрытие документа осуществляется методом «ЗакрытьДокумент (CloseDocument)». В случае необходимости посылается команда отрезчику, и если это позволяет сделать модель устройства.

В рамках одного документа должна быть предусмотрена возможность печати текстовых строк и штрихкода.

Алгоритм пакетной печати документа

Алгоритм пакетной печати документа отличается от построчной печати тем, что все те же команды, которые используется при построчной печати, передаются единым пакетом.
Последовательность команд и их параметры описываются с помощью XML определенного типа - DocumentPackage.
Пакетная печать осуществляется методом «НапечататьТекстовыйДокумент (PrintTextDocument)».

Описание структуры DocumentPackage

Текст в формате XML содержит описание передаваемого для печати документа.

Пример XML описывающего чека для печати:

<?xml version="1.0" encoding="UTF-8" ?>
<Document>
   <Positions> 
      <TextString Text="Участие в дисконтной системе"/>
      <TextString Text="Дисконтная карта: 00002345"/> 
      <Barcode BarcodeType="EAN13" Barcode="2000021262157"/>
   </Positions>
</Document>

3.3. Требования к разработке драйверов для платежных систем

При работе с платежными системами поддерживаются следующие операции:

• Оплата картой
• Отмена платежа по карте
• Возврат платежа по карте
• Получение итогов дня по картам

ВНИМАНИЕ: По требованиям безопасности полный номер карты не предоставляется, предоставляется маскированный номер карты (часть цифр номера карты заменено звездочками).

Оплата картой

При необходимости оплатить покупку платежной картой система вызывает метод «ОплатитьПлатежнойКартой (PayByPaymentCard)», передавая во входных параметрах сумму к оплате для списания с карты и номер чека по которому происходит покупка. Драйвер возвращает результат выполнения команды, код RRN, маскированный номер карты, код авторизации и текст слип-чека.
Текст слип чека печатается на подключенном печатающем устройстве (ФР или Принтер чеков) или передается покупателю средствами мобильного решения (email или sms).

Возврат платежа по карте

При возврате платежа система вызывает команду «ВернутьПлатежПоПлатежнойКарте (ReturnPaymentByPaymentCard)», передавая во входном параметре сумму к возврату на карту, номер карты по которой происходила оплата, номер чека по которому происходит операция, код RRN операции по которой совершается возврат, и код авторизации. Драйвер в ответ возвращает результат выполнения функции, а в выходные параметры записывает код RRN, код авторизации.
Текст слип чека печатает на подключенном печатающем устройстве (ФР или Принтер чеков) или передается покупателю средствами мобильного решения (email или sms).

Отмена платежа по карте

Если происходит отмена платежа, то система вызывает метод «ОтменитьПлатежПоПлатежнойКарте (CancelPaymentByPaymentCard)», передавая во входных параметрах сумму, которая была указана для списания с карты, номер карты по которой происходила оплата, номер чека по которому происходит операция, код RRN операции по которой совершается отмена, и код авторизации. Драйвер в ответ возвращает результат выполнения функции.

Получение итогов дня по картам

Для получения текста отчета система вызывает команду «ИтогиДняПоКартам (Settlement)». Драйвер возвращает результат выполнения функции и текст отчета.

* - Если информация, считанная с карты, передается в эквайринговую систему из конфигурации "1С:Предприятия", содержание этого поля должно отвечать требованиям конкретной эквайринговой системы.

3.4. Требования к разработке драйверов для ККТ с функцией передачи в ОФД

ВНИМАНИЕ: Данный стандарт определяет требования к ККТ на основании форматов фискальных документов версии "1.0" и "1.05".

При работе с ККТ с функцией передачи данных в ОФД поддерживаются следующие операции:

• Получение данных из ККТ для регистрации фискального накопителя и последующей работы;
• Операции с фискальным накопителем: 
  • Регистрация
  • Изменение параметров регистрации
  • Закрытие
• Формирование документов открытия и закрытия смены;
• Формирование фискальных чеков;
• Формирование фискальных чеков коррекции;
• Формирование фискальных отчетов о текущем состоянии расчетов;
• Формирование нефискальных отчетов (отчет без гашения);
• Получение текущего состояние ККТ;
• Печать чеков внесения/выемки денежных средств;
• Печать текстовых документов;
• Открытие денежного ящика.
  

ТаблицаПараметровККТ (TableParametersKKT)

Текст в формате XML, передаваемый с помощью параметра типа STRING.

* Данные поля обязательны для фискализированных ФН.

ПараметрыФискализации (ParametersFiscal)

Текст в формате XML, передаваемый с помощью параметра типа STRING.

* Данное поле обязательно при процедуре изменение параметров регистрации.

Описание структуры InputParameters

Текст в формате XML, передаваемый с помощью параметра типа STRING.

Пример текстового XML:

 <?xml version="1.0" encoding="UTF-8"?>
 <InputParameters> 
	<Parameters CashierName="Иванов И.П." CashierVATIN="32456234523452"/>
 </InputParameters>

Описание структуры OutputParameters для метода "ОткрытьСмену (OpenShift)"

Текст в формате XML, передаваемый с помощью параметра типа STRING.

Пример текстового XML:

 <?xml version="1.0" encoding="UTF-8"?>
 <OutputParameters> 
     <Parameters 
           UrgentReplacementFN="false" 
	   MemoryOverflowFN="false" 
           ResourcesExhaustionFN="false" />
 </OutputParameters>

Описание структуры OutputParameters для метода "ЗакрытьСмену (CloseShift)"

Текст в формате XML, передаваемый с помощью параметра типа STRING.

Пример текстового XML:

 <?xml version="1.0" encoding="UTF-8"?>
 <OutputParameters>
     <Parameters  
	OFDTimeout="Иванов И.П." 
	CashierVATIN="32456234523452"/>
 <OutputParameters >

Описание структуры CheckPackage

Текст в формате XML содержит описание передаваемого для формирования чека. Структура описывает параметры и последовательность формирования фискального чека.

Данные агента. XML Структура.

Данные поставщика. XML Структура.

Код товарной номенклатуры. XML Структура.

Описание структуры CheckCorrectionPackage

Текст в формате XML содержит описание передаваемого для печати чека коррекции.

Пример текстового XML:

<?xml version="1.0" encoding="UTF-8"?>
<CheckCorrectionPackage>
	<Parameters PaymentType="1"/>
	<Payments Cash="200"/>
</CheckCorrectionPackage>

Описание структуры DocumentPackage

Текст в формате XML содержит описание текстового документа. Структура описывает последовательность формирования текстового документа.

Пример текстового XML:

<?xml version="1.0" encoding="UTF-8"?>
<Document>
	<Positions>
		<TextString Text="Участие в дисконтной системе"/>
		<TextString Text="Дисконтная карта: 00002345"/>
		<Barcode BarcodeType="EAN13" Barcode="2000021262157"/>
	</Positions>
</Document>

Описание структуры StatusParameters

Текст в формате XML содержит описание параметров текущего состояния ККТ.

Пример текстового XML:

<?xml version="1.0" encoding="UTF-8"?>
<StatusParameters>
	<Parameters BacklogDocumentsCounter="1" BacklogDocumentFirstNumber="34" BacklogDocumentFirstDateTime="2016-12-09T16:13:42"/>
</StatusParameters>

3.7. Требования к разработке драйверов для принтеров чеков

При работе с принтерами чеков поддерживаются следующие операции:

• Печать текстовых чеков (с возможностью печати штрихкодов);
• Открытие денежного ящика.

Алгоритм печати чека.

При подключении устройства командой "Подключить" драйвер инициализирует устройство печати, в том числе определяет кодировку для печати чеков.
При формировании чека конфигурация посылает команду "НапечататьТекстовыйДокумент" для печати текстового документа на принтере чеков. Содержимое печатаемого документа определяется структурой ДанныеДокумента.

Описание структуры DocumentPackage

Текст в формате XML содержит описание текстового документа. Структура описывает последовательность формирования текстового документа.

Пример текстового XML:

<?xml version="1.0" encoding="UTF-8"?>
<Document>
	<Positions>
		<TextString Text="Участие в дисконтной системе"/>
		<TextString Text="Дисконтная карта: 00002345"/>
		<Barcode BarcodeType="EAN13" Barcode="2000021262157"/>
	</Positions>
</Document>

Справочные таблицы

Системы налогообложения

Признаки способа расчета

Признаки предмета расчета

Признаки агента по предмету расчета

4. Подключение драйверов разработанных по стандарту «1С: Совместимо» к конфигурации БПО

Подключение драйвера путем загрузки в информационную базу для мобильной платформы невозможно.
Для подключения разработанного драйвера необходимо открыть БПО в режиме конфигуратора и выполнить следующие действия:

1. Найти в дереве конфигурации элемент Общие макеты, выбрать его и нажать ПКМ (для тестовой среды вы можете использовать поставляемый макет «ДрайверТестовый»);
2. Появится окно загрузки/выгрузки макета. Вам нужно нажать кнопку Загрузить из файла и выбрать файл архива с вашим драйвером, после чего нажать ОК;
3. Далее вам нужен общий модуль «МенеджерОборудованияВызовСервераПереопределяемый», и функцию «ОбновитьПоставляемыеДрайвера»;
4. В ней вам нужно изменить следующий код ("AddIn.Test" изменить на ProgID вашей компоненты);
   
   Пример:

         Справочники.ДрайверыОборудования.ЗаполнитьПредопределенныйЭлемент(
                                Перечисления.ТипыПодключаемогоОборудования.УстройствоВвода,"ДрайверТестовый","Драйвер тестовый","AddIn.Test", Ложь);