libepf

libepf – небольшая библиотека для работы с файлами epf/erf (внешние обработки и отчеты) 1С:Предприятия 8.х. Библиотека была создана для внутреннего употребления и выложена в надежде, что кому-нибудь будет полезна.

Страница проекта на SourceForge: http://sourceforge.net/projects/libepf/
Описание формата epf в объеме, реализованном в данной библиотеке. Спасибо библиотеке V8Unpack за прояснение ряда деталей.

exe-файл

Основным результатом работы является exe-файл, имеющий следующие ключи запуска:

• --help или -? – справка по ключам.
• --epf_file ИмяФайла – имя epf- или erf-файла.
• --get_module ИмяФайла – указывает имя файла, куда следует сохранить модуль внешнего отчета или внешней обработки.
• --set_module ИмяФайла – указывает имя файла, откуда следует взять текст модуля. Это модуль будет помещен во внешний отчет/обработку. Текст модуля должен быть в кодировке UTF-8 с BOM.
• --form Индекс – индекс формы отчета/обработки, начинается с 0.
• --get_form_module ИмяФайла – указывает имя файла, куда следует сохранить модуль указанной формы.
• --set_form_module ИмяФайла – указывает имя файла, откуда следует взять текст модуля, который будет помещен в модуль указанной формы.
• --dump_file ИмяКаталога – указывает каталог, куда будут извлечены файлы, хранящиеся в файле epf/erf. Каждый файл получает расширение .txt.

Программу можно скачать здесь: http://sourceforge.net/projects/libepf/files/

Документация по классам

Исходники доступны на SourceForge в репозитории Mercurial. Скачать можно командой
hg clone http://hg.code.sf.net/p/libepf/code libepf-code

Для использования библиотеки в составе своего проекта на C++ можно включить в проект все *.h и *.cpp файлы библиотеки за исключением V8Format.cpp, который отвечает за функционал exe-файла.

Доступные классы следующие.

Epf::File_t

Самый высокоуровневый класс. При конструировании целиком загружает данный epf/erf файл из файла или произвольного потока. Позволяет выполнить высокоуровневые операции с файлом, когда пользователю класс не требуется знать о внутренней структуре epf-файлов. Результат позволяет сохранить в файл или произвольный поток.

namespace Epf { class File_t { public: File_t (boost::iostreams::filtering_istream &Stream); File_t (std::string const &FileName); void WriteTo (boost::iostreams::filtering_ostream &Stream); void WriteToFile (std::string const &Name); void GetModule (std::vector<char> &Buffer); void SetModule (std::vector<char> const &Buffer); FormsCollection_t &GetForms (); FormsCollection_t const &GetForms () const; }; } // namespace Epf

• File_t (boost::iostreams::filtering_istream &Stream); конструирует объект на основе произвольного потока. После того, как объект сконструирован, поток может быть закрыт или разрушен.

• File_t (std::string const &FileName); конструирует поток на основе имени файла. Открывает данный файл и загружает его содержимое.

• void WriteTo (boost::iostreams::filtering_ostream &Stream); записывает epf-файл в данный поток.

• void WriteToFile (std::string const &Name); записывает epf-файл в указанный файл.

• void GetModule (std::vector<char> &Buffer); получает текст модуля.

• void SetModule (std::vector<char> const &Buffer); устанавливает текст модуля. Текст модуля должен быть в кодировке UTF-8 с BOM.

• FormsCollection_t &GetForms (); возвращает ссылку на коллекцию форм объекта.

FormsCollection_t

Коллекция форм объекта.
namespace Epf { class FormsCollection_t { public: std::size_t GetCount () const; Form_t &GetByIndex (std::size_t Index); Form_t const &GetByIndex (std::size_t Index) const; Form_t &GetByName (std::string const &Name); Form_t const &GetByName (std::string const &Name) const; }; // class FormsCollection_t } // namespace Epf

• std::size_t GetCount () const; возвращает количество форм.

• Form_t &GetByIndex (std::size_t Index); возвращает ссылку на форму по ее индексу (индекс начинается с 0).

• Form_t &GetByName (std::string const &Name); возвращает ссылку на форму по ее имени, имя – строка в формате UTF-8.

Form_t

Класс для работы с формой объекта.
namespace Epf { class Form_t { public: std::string const &GetName () const; void GetModule (std::vector<char> &Buffer) const; void SetModule (std::vector<char> const &Buffer); }; // class Form_t } // namespace Epf

• std::string const &GetName () const; возвращает идентификатор формы в UTF-8.

• void GetModule (std::vector<char> &Buffer) const; позволяет получить модуль данной формы.

• void SetModule (std::vector<char> const &Buffer); позволяет установить модуль данной формы. Модуль должен быть строкой в UTF-8 с BOM.

Storage_t

Класс, представляющий файл epf как набор файлов.

namespace Epf { class Storage_t { public: struct File_t { std::vector<char> Attributes; std::vector<char> Data; }; typedef <implemetation-defined> iterator; typedef <implemetation-defined> const_iterator; iterator begin (); const_iterator begin () const; iterator end (); const_iterator end () const; iterator find (std::wstring const &Name); const_iterator find (std::wstring const &Name) const; Storage_t (); Storage_t (boost::iostreams::filtering_istream &Stream, bool UseCompression); void LoadFromStream (boost::iostreams::filtering_istream &Stream, bool UseCompression); void WriteToStream (boost::iostreams::filtering_ostream &Stream, bool FixedDir = false) const; }; } // namespace Epf

• struct File_t – структура, описывающая атрибуты и содержимое файла.

• iterator, const_iterator, begin (), end () – средства доступа к файлам хранилища в STL-стиле. Позволяют произвести итерирование объектов вида std::pair<std::wstring, Storage_t::File_t>, где первый компонент – имя файла, а второй – атрибуты и содержимое файла.

• iterator find (std::wstring const &Name); const_iterator find (std::wstring const &Name) const; – поиск файла по имени.

• Storage_t (); создает пустое хранилище.

• Storage_t (boost::iostreams::filtering_istream &Stream, bool UseCompression); загружает файл epf из данного потока. После конструирования поток может быть закрыт или разрушен. Параметр UseCompression определяет, следует ли производить сжатие содержимого файлов при загрузке и записи.

• void LoadFromStream (boost::iostreams::filtering_istream &Stream, bool UseCompression); то же самое, что аналогичный конструктор.

• void WriteToStream (boost::iostreams::filtering_ostream &Stream, bool FixedDir = false) const; записывает epf-файл в указанный поток. FixedDir определяет, следует ли под оглавление хранилища выделить ровно столько места, сколько требуется для файлов, находящихся сейчас в хранилище, или оглавление нужно сохранять блоками одного и того же размера.

StorageReader_t

Низкоуровневый класс для чтения хранилища epf. Загружает в память только оглавление хранилища.

namespace Epf { class StorageReader_t { public: StorageReader_t (boost::iostreams::filtering_istream &Stream, bool UseCompression); boost::uint32_t GetBlockSize () const; boost::uint32_t GetUnknown () const; boost::uint32_t GetNumFiles () const; void GetFileAttributes (boost::uint32_t Index, std::vector<char> &Attributes); void GetFileAttributes (boost::uint32_t Index, std::vector<char> * pAttributes, std::wstring *pName); void GetFileName (boost::uint32_t Index, std::wstring &Name); void GetFileData (boost::uint32_t Index, std::vector<char> &Buffer); }; // class StorageReader_t } // namespace Epf

• StorageReader_t (boost::iostreams::filtering_istream &Stream, bool UseCompression); конструирует класс на основе данного потока. Поток должен существовать на протяжении всей жизни объекта. Параметр UseCompression указывает, является ли сжатым содержимое файлов хранилища.

• boost::uint32_t GetBlockSize () const; возвращает размер, используемый для блоков оглавления.

• boost::uint32_t GetUnknown () const; возвращает неизвестный параметр из заголовка epf-файла.

• boost::uint32_t GetNumFiles () const; возвращает количество файлов в хранилище.

• void GetFileAttributes (boost::uint32_t Index, std::vector<char> &Attributes); позволяет получить атрибуты файла по его индексу.

• void GetFileAttributes (boost::uint32_t Index, std::vector<char> * pAttributes, std::wstring *pName); позволяет получить атрибуты и имя файла по его имени. Один из параметров может быть NULL. Т.к. имя файла и атрибуты находятся в одном потоке хранилища, то данная функция позволяет получить атрибуты и имя за одно чтение. Тогда как вызов первой версии GetFileAttributes и потом GetFileName потребует двух чтений одного и того же потока.

• void GetFileName (boost::uint32_t Index, std::wstring &Name); возвращает имя файла по его индексу.

• void GetFileData (boost::uint32_t Index, std::vector<char> &Buffer); позволяет получить содержимое данного файла.

StorageWriter_t

Низкоуровневый класс для записи файла epf.

namespace Epf { class StorageWriter_t { public: StorageWriter_t (boost::iostreams::filtering_ostream &Stream, std::size_t BlockSize, boost::uint32_t Unknown, bool UseCompression, std::size_t FixedFilesCount = 0); void WriteFile (std::wstring const &Name, std::vector<char> const &Attributes, std::vector<char> const &Data); }; // class StorageWriter_t } // namespace Epf

• StorageWriter_t (boost::iostreams::filtering_ostream &Stream,
  std::size_t BlockSize, boost::uint32_t Unknown, bool UseCompression,
  std::size_t FixedFilesCount = 0);

• void WriteFile (std::wstring const &Name, std::vector<char> const &Attributes, std::vector<char> const &Data); записывает в поток указанный файл. Выполняет сжатие, если нужно. Модифицирует оглавление.

Сборка проекта

Если каким-то чудом у вас есть настроенное окружение для сборки Йокселя, то сборку libepf можно производить из данного окружения в каталоге исходников libepf командами “omake release” или “omake debug”. Но, скорее всего, такого окружения у вас нет, поэтому сборку можно произвести при помощи Visual Studio 2005 или выше.

Для этого нужно открыть в вашей Студии файл “V8Format.sln”. Это солюшен, в котором имеется два проекта. Проект “V8Format” – это проект для сборки через omake. Это нам не надо. Собирать следует проект “libepf”.

Для сборки потребуется библиотека boost. Если у вас ее все еще нет, то можно пойти двумя путями:

• Скачать исходники с http://boost.org и собрать их самостоятельно. Путь джедая, но многие это делают регулярно.

• Или скачать уже собранные под вашу Студию библиотеки. Сделать это можно здесь: http://www.boostpro.com/download/. При этом вы получите инсталлятор, где нужно указать вашу Студию и какие библиотеки следует загрузить. В проекте используются: iostreams, program_options, system, filesystem. Все библиотеки помечать не стоит. Потому что общий объем для скачивания получается около 1.5Г. И это только в архивах. Т.е. после распаковки будет вообще жуть. К тому же скорость скачивания весьма невелика. Если я случайно пропустил какую-то библиотеку в своем списке, то инсталлятор можно запустить повторно, снять все флажки и отметить только нужные. Если после инсталляции пути к include- и lib-файлам в Студии не прописаны, то это придется сделать вручную.

Т.к. библиотека никак не использует WinAPI и другие платформозависимые функции, то ничто не мешает собрать ее под Linux.