Как правильно передать дату из 1С во внешнюю компоненту через Native API?

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

Понимание механизмов Native API

В отличие от классического COM, где часто используется тип DATE (который по сути является double), Native API требует более строгого подхода. Платформа 1С:Предприятие ожидает, что при передаче даты во внешнюю компоненту будет использован специальный тип данных VTYPE_TM, а само значение будет упаковано в структуру tm (стандартная структура из time.h).

Почему это важно? Использование VTYPE_TM гарантирует, что 1С правильно интерпретирует передаваемые компонентой или принимаемые ею данные, исключая «размытие» временных меток и ошибки смещения часовых поясов.

Реализация передачи данных через структуру tm

Рассмотрим пошагово, как подготовить данные для передачи. При работе с tVariant (базовой структурой данных в Native API), вам необходимо заполнить поля структуры tm в соответствии с требованиями языка C/C++:

1. tm_year: Обратите внимание, что это количество лет с 1900 года. Если вам нужно передать 2024 год, значение будет 124.
2. tm_mon: Индексация месяцев начинается с нуля. Январь — это 0, февраль — 1, и так далее до декабря (11).
3. tm_mday: День месяца указывается в обычном формате, начиная с 1.

Для корректного взаимодействия с tVariant используйте следующий подход:

// Пример заполнения структуры tm для передачи
struct tm timeInfo;
memset(&timeInfo, 0, sizeof(struct tm));

timeInfo.tm_year = year - 1900; // год
timeInfo.tm_mon = month - 1;    // месяц (0-11)
timeInfo.tm_mday = day;         // день

// Заполнение tVariant
varResult.vt = VTYPE_TM;
varResult.tmVal = timeInfo;

Альтернативный способ: использование VTYPE_DATE

Если ваша компонента должна возвращать дату обратно в 1С, вы можете использовать тип VTYPE_DATE. В этом случае 1С воспринимает дату как число с плавающей точкой (double), где целая часть — это количество дней, прошедших с 30 декабря 1899 года, а дробная часть — время суток. Этот способ является более простым для расчетов внутри самой компоненты, так как позволяет избежать ручного заполнения полей структуры tm.

Однако помните: при получении данных от 1С всегда проверяйте тип значения в tVariant с помощью макроса TV_VT(varPropVal), чтобы убедиться, что платформа передала именно дату, а не строку или число.

Рекомендации по проектированию компонент

Работая с Native API, мы рекомендуем придерживаться следующих правил для повышения надежности кода:

• Всегда проверяйте типы: Перед преобразованием данных в tVariant обязательно используйте проверку if (TV_VT(varPropVal) != VTYPE_DATE). Это предотвратит аварийное завершение работы компоненты при передаче неверных аргументов из кода 1С.
• Кроссплатформенность: Помните, что структуры tm могут незначительно отличаться в реализации стандартных библиотек разных ОС. При компиляции под Linux и Windows используйте стандартные заголовочные файлы платформы для корректного маппинга типов.
• Сложные структуры: Если вы планируете передавать большие массивы данных, содержащие даты, строки и числа, рассмотрите вариант сериализации данных в формат JSON. Передача одной длинной строки (VTYPE_PWSTR) с последующим парсингом внутри компоненты может оказаться значительно проще и гибче, чем работа с массивами tVariant.

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