Программный интерфейс электронного архива:
возможности и принципы построения.
Аннотация: Рассматриваются принципы построения и способы использования программного интерфейса, предназначенного для автоматизированного создания и модификации объектов системы Евфрат, а также поиска по ее базе данных. Интерфейс ориентирован на имеющуюся структуру данных электронного архива и позволяет выполнять полный набор действий с папками и документами системы.
Программный интерфейс системы Евфрат, API (Applied programmer interface), - механизм управления ею (серверное приложение) из других Windows-приложений (клиенты). Он представляет собой динамически загружаемую библиотеку (dll), включаемую в состав клиентского приложения. В отличие от языка сценария [1], программный интерфейс предназначен для использования профессиональными программистами при написании отдельных программ, использующих Евфрат в качестве архивного хранилища своих данных, а также программных модулей, дополняющих возможности Евфрата.
Для лучшего понимания структуры API, остановимся кратко на особенностях самого Евфрата. Он представляет собой информационно-поисковую систему (электронный архив), предназначенную для хранения информации о документах, введенных в компьютер, находящихся в компьютерах локальной сети, а также в глобальной сети Интернет. При этом под документом в системе Евфрат понимается совокупность файлов и значений реквизитов документа, задаваемых как вручную пользователем, так и автоматически. Следует подчеркнуть, что Евфрат, как правило, не хранит сами файлы, составляющие документ, забота об их сохранности лежит на пользователе. В то же время, предоставляются некоторые возможности для облегчения этой работы, такие как поиск перемещенных файлов или возможность создания папок-образов директорий, что позволяет автоматизировать процесс создания документов, соответствующих файлам указанной директории. Таким образом, объектами хранения в базах данных системы являются информация о структуре документов и других объектов, а также значения реквизитов.
Основными объектами системы Евфрат являются:
· Документы.
· Папки, которые могут содержать в себе документы и другие папки.
· Псевдонимы папок и документов, представляющие собой ссылки на объект-оригинал, обладающие несколькими простыми свойствами, а именно, возможностью получить доступ к оригиналу для выяснения его местоположения в папочной структуре и других свойств, а также открыть его для просмотра теми же средствами, что и оригинал – папку или документ.
· Картотеки, представляющие собой механизм ручной реквизитной разметки документов, а также папки, в которых хранятся псевдонимы всех документов, размеченных с использованием данной картотеки. Каждая картотека содержит набор реквизитов, по которым размечается документ. Системные реквизиты, например, Все слова (полнотекстовый индекс) или Имя объекта, заполняются автоматически.
· Рабочий стол, на котором в порядке, задаваемом пользователем, лежат все прочие объекты.
Все функции API в своей работе используют переменные и константы Евфрат, такие как константы для кодов ошибок, типов объектов (папка, документ и т. д.), типов значений реквизитов (текст, целое число, дата, деньги), флагов свойств реквизитов (однозначный, многозначный, с фиксированным словарем, что означает, что значения его берутся из фиксированного набора), а также идентификаторы всех объектов, включая реквизиты. На первый взгляд, работа непосредственно с системными идентификаторами не слишком удобна, однако это – единственный способ добиться однозначности при определении объекта, с которым надо выполнить какие-либо действия. Кроме того, для получения этих идентификаторов предоставляется несколько возможностей, таких как поиск или получение списка подобъектов папки.
Для достижения максимальной универсальности, библиотека оформлена, как самая простая dll с простейшим C-интерфейсом, что означает, что все функции библиотеки имеют параметры стандартных типов, определенных в языке C. Это позволяет вызывать их из программ, написанных на различных языках программирования.
Следует отметить, что указанный метод построения API можно признать нетрадиционным и, возможно, устаревшим. В наиболее распространенных программных продуктах, таких как MS Word и MS Excel, при построении API широко использована технология OLE. Так, в программе Word 6.0, для вызова функций следует первоначально создать объект Word. Basic с интерфейсом IDispatch, однако сами функции имеют обычный, характерный для языка C, вид. В более современных версиях используется так называемый Visual Basic for Applications, язык, построенный на принципах, аналогичных C++. При этом, отдельными объектами языка со своими OLE интерфейсами описываются, например, диапазон ячеек, книга, шрифт, страница, а также все приложение MS Excel. В дальнейшем планируется доработать имеющийся API на этих принципах, создавая объекты, описывающие папки, документы, реквизиты и т. д. Однако, используемый в настоящее время принцип построения библиотеки хорош своей простотой и универсальностью.
Рассмотрим теперь более подробно функции API. Все они возвращают целую переменную 1 в случае успешного завершения и 0 в случае ошибки. В последнем случае более детальную информацию о происшедшем можно получить, вызвав функцию для определения кода последней ошибки. Эти коды описывают ситуации незапущенного Евфрата, неизвестной ошибки в нем при выполнении требуемого действия, слишком короткого буфера для передачи данных, отсутствия требуемого объекта или реквизита, недопустимого типа параметра, занятости Евфрата другим заданием, а также его остановки.
При работе функций, передающих информацию из Евфрата, необходимая память для этих данных выделяется внутри библиотеки, а указатель на буфер передается в вызывающую программу. Для освобождения этой памяти в состав библиотеки включена специальная служебная функция, что позволяет использовать поставляемую библиотеку независимо от режима трансляции вызывающего модуля – с отладочной информацией или без нее.
Следующей служебной функцией библиотеки является функция ее инициализации. При вызове следует указать дескриптор какого-либо окна клиентского приложения, поскольку далее создается невидимое окно, которое служит для обмена системными сообщениями с Евфратом - потомок окна, указанного при инициализации. Специальных функций для завершения работы с библиотекой не предусмотрено, поскольку предполагается, что программа, использующая ее, не в состоянии работать без Евфрата, более того, предусмотрен механизм, позволяющий завершить работу этой программы одновременно с Евфратом.
Наиболее обширной группой функций библиотеки является группа работы с папками и документами. Для получения имени и аннотации (произвольный текст, который можно приписать папке или документу) служат функции GetObjName(DWORD dwObjId, char *cBuf, int nBufLength) и GetObjAnnotation(DWORD dwObjId, char *cBuf, int nBufLength). Соответственно, есть функции SetObjName и SetObjAnnotation, позволяющие задать имя или аннотацию. Эти четыре функции - общие для папок и документов.
Для создания папки предусмотрена функция CreateFolder(DWORD *pObjId, const char *Name), при вызове которой задается идентификатор родительской папки (0 - для рабочего стола) и имя новой папки. После выхода из функции (в случае успешного завершения) в ячейке pObjId находится идентификатор вновь созданного объекта. Предусмотрена также возможность создания группы вложенных папок, начиная с той, которая лежит на рабочем столе. При этом, если несколько начальных из них уже существуют, то создаются только недостающие папки. Кроме этого, есть функция для получения идентификаторов уже существующих папок из требуемой структуры.
Для получения информации о составе папки предусмотрены функции, с помощью которых можно получить список подобъектов: либо папок, либо документов и папок, с указанием типа и имени.
Функции работы с документами позволяют манипулировать как их файловым составом, так и реквизитной разметкой. Для создания документа и задания файлов, входящих в него, используются функции SetDocStruct(DWORD *pDocOrParentId, void *pBuf, int nBufLen) и SetDocStructEx(DWORD *pDocOrParentId, void *pBuf, int nBufLen). В первом параметре, как и в случае работы с папкой, задается идентификатор родительской папки (на выходе – созданного документа), а во втором через оговоренные разделители перечисляются файлы, которые следует включить в документ. Сами указанные функции отличаются друг от друга форматом буфера. Работа с реквизитами документа осуществляется функциями GetDocRecv(DWORD DocId, void **pBuf, int *pBufLen), SetDocRecv(DWORD DocId, void *pBuf, int nBufLen) и RemoveIndexing(DWORD DocId), предназначенными для получения разметки документа, задания новой разметки и удаления всех значений реквизитов документа. При этом, естественно, значения системных реквизитов, не удаляются и не изменяются.
Рассмотрим ряд служебных функций. Как уже отмечалось, для манипулирования объектами Евфрата разработан и реализован язык сценария. Он позволяет выполнять некоторые действия более просто и логично, чем рассматриваемый API, например, ввод большого числа документов, информация о которых была записана Евфратом на какой-либо другой базе. В связи с этим, в библиотеку включены функции запуска сценария, содержащегося в файле, а также предусмотрена возможность динамического формирования такого сценария при работе программы с последующим исполнением. Следующая служебная функция предназначена для получения данных о всех реквизитах системы, доступных через функции API. Эта функция GetAllRecvs(void **pBuf, int *pBufLen) возвращает в согласованном формате системный идентификатор реквизита, тип его значения, флаг свойств, а также название. Полученные данные могут быть использованы при формировании новой реквизитной разметки документа, а также для анализа существующей.
В состав библиотеки включены функции для поиска по базе Евфрат. Одна из них, GetObjFromName(const char *cName, void **pBuf, int *pBufLen), носит служебный характер и предназначена для поиска объекта по его имени. Функция выдает список идентификаторов всех объектов системы с данным именем и их типы – документ, папка, псевдоним. Общая функция поиска по базе имеет вид Search(void *pQuestionBuf, void **pAnswerBuf, int *pBufLen), причем входные данные для нее имеют довольно сложную структуру, которая, однако, полностью повторяет структуру запроса внутри Евфрата. Во входном буфере помещаются несколько групп элементарных запросов, в каждую из которых входят код логической операции (И, ИЛИ, НЕ), тип значения реквизита, идентификатор реквизита, а также две текстовые строчки, содержащие интервал поиска (ОТ и ДО). Предполагается, что программисты, использующие описываемую библиотеку функций, обладают достаточной квалификацией, чтобы самостоятельно формировать такую запросную строку. Результатом работы этой функции является список идентификаторов найденных объектов и их типов.
Система Евфрат предназначена для работы не только в личном, локальном режиме, но и в многопользовательском, клиент-серверном, с использованием локальной компьютерной сети. Перечислим кратко дополнительные действия, доступные в этом режиме через соответствующие служебные функции. Добавление на сервер – этот термин обозначает действие по синхронизации данных в клиентской и серверной базах данных. Получить идентификатор работающего пользователя, что может понадобиться для выяснения, какие действия допустимы в данный момент. Переадресовать объект другому пользователю с указанием, какому пользователю и в какую папку положить объект. При этом есть возможность указать, переадресовывается вся папка или только ее содержимое.
Как видно, перечисленные функции предназначены исключительно для работы с информацией об объектах, хранящейся в базе данных. В тоже время, существует функция для работы с интерфейсными объектами, которая позволяет получить список объектов системы, активных в настоящий момент. Это необходимо для работы через API с теми из них, которые выбраны пользователем.
Литература
1. , , Подрабинович создание объектов в электронном архиве с помощью сценария
– настоящий сборник.
