В системе Ultima Businessware® реализована пакетная очередь печати. А именно, несколько заданий могут быть отправлены на печать одним пакетом. Это значит, что на принтере эти задания распечатаются в заданном порядке и между ними не вклинятся сторонние задания. Таким образом, для печати из обработчика необходимо создать пакет и добавить в него нужные задания. Сами задания могут быть как отложенными (обработчик генерации данных печатной формы будет вызван асинхронно из другой транзакции) так и синхронными – обработчик будет вызван немедленно. Второй вариант удлиняет исполнение серверного вызова, однако если есть риск изменения данных между отправкой формы и ее печатью лучше использовать синхронный вариант.

Интерфейс менеджера IPrintManager (из пространства имен Ultima.Printing) реализует следующие методы:

•CreatePackage(long printerId) – создает новый пакет для печати PrintPackage на указанном принтере:

▪printerId – идентификатор принтера;

На стороне клиента этот пакет нужно заполнить заданиями с помощью методов класса PrintPackage:

•Print(PrintPackage pack) – синхронная печать заполненного пакета – вызывается метод GetData для всех задач и пакет добавляется в очередь печати:

▪pack – пакет для печати;

•PrintDelayed(PrintPackage pack) – асинхронная печать – пакет добавляется в очередь печати:

▪pack – пакет для печати;

Также интерфейс реализует методы для печати одиночных заданий, когда не требуется создания пакета (фактически все равно будет создан пакет с единственным заданием). Каждый из методов реализован в двух версиях – для синхронной и асинхронной печати. При синхронной печати объект с данными для печатной формы вычисляется и создается сразу же (при этом клиент ожидает завершения этого процесса), При асинхронной (отложенной) печати данные будут сформированы позднее:

•Print(long printerId, long printFormId, long copies = 1, IDictionary<string, object> parameters = null) – синхронная печать печатной формы, не связанной с каким-либо объектом:

▪printerId – идентификатор принтера;

▪printFormId – идентификатор печатной формы;

▪copies – число печатаемых копий (значение по умолчанию 1);

▪parameters – дополнительные параметры печати (значение по умолчанию null);

•PrintDelayed(long printerId, long printFormId, long copies = 1, IDictionary<string, object> parameters = null) – аналогичный предыдущему метод асинхронной печати;

•PrintDictionaryRecord(long printerId, Type dictionaryType, long recordId, long printFormId, long copies = 1, IDictionary<string, object> parameters = null) – синхронная печать (одной) записи справочника:

▪printerId – идентификатор принтера;

▪dictionaryType – тип справочника;

▪recordId– идентификатор записи справочника;

▪printFormId – идентификатор печатной формы;

▪copies – число печатаемых копий (значение по умолчанию 1);

▪parameters – дополнительные параметры печати (значение по умолчанию null).

Также существует типизированный вариант этого метода PrintDictionaryRecord<T>(this IPrintManager manager, long printerId, long recordId, long printFormId, long copies = 1, IDictionary<string, object> parameters = null);

•PrintDictionaryRecordDelayed(long printerId, Type dictionaryType, long recordId, long printFormId, long copies = 1, IDictionary<string, object> parameters = null) – аналогичный предыдущему метод асинхронной печати.

Также существует типизированный вариант этого метода PrintDictionaryRecordDelayed<T>(this IPrintManager manager, long printerId, long recordId, long printFormId, long copies = 1, IDictionary<string, object> parameters = null);

•PrintDictionaryList(long printerId, Type dictionaryType, IDList recordList, long printFormId, long copies = 1, IDictionary<string, object> parameters = null) – синхронная печать списка записей справочника:

▪printerId – идентификатор принтера;

▪dictionaryType – тип справочника;

▪recordList– список идентификаторов записей справочника;

▪printFormId – идентификатор печатной формы;

▪copies – число печатаемых копий (значение по умолчанию 1);

▪parameters – дополнительные параметры печати (значение по умолчанию null).

Также существует типизированный вариант этого метода PrintDictionaryList<T>(this IPrintManager manager, long printerId, IDList recordList, long printFormId, long copies = 1, IDictionary<string, object> parameters = null);

•PrintDictionaryListDelayed(long printerId, Type dictionaryType, IDList recordList, long printFormId, long copies = 1, IDictionary<string, object> parameters = null) – аналогичный предыдущему метод асинхронной печати.

Также существует типизированный вариант этого метода PrintDictionaryListDelayed<T>(this IPrintManager manager, long printerId, IDList recordList, long printFormId, long copies = 1, IDictionary<string, object> parameters = null);

•PrintDocument(long printerId, long documentId, long printFormId, long copies = 1, IDictionary<string, object> parameters = null) – синхронная печать (одного) документа:

▪printerId – идентификатор принтера;

▪documentId– идентификатор документа;

▪printFormId – идентификатор печатной формы;

▪copies – число печатаемых копий (значение по умолчанию 1);

▪parameters – дополнительные параметры печати (значение по умолчанию null);

•PrintDocumentDelayed(long printerId, long documentId, long printFormId, long copies = 1, IDictionary<string, object> parameters = null) – аналогичный предыдущему метод асинхронной печати;

•PrintDocumentList(long printerId, IDList documentList, long printFormId, long copies = 1, IDictionary<string, object> parameters = null) – синхронная печать списка документов:

▪printerId – идентификатор принтера;

▪documentList– список идентификаторов документов;

▪printFormId – идентификатор печатной формы;

▪copies – число печатаемых копий (значение по умолчанию 1);

▪parameters – дополнительные параметры печати (значение по умолчанию null);

•PrintDocumentListDelayed(long printerId, IDList documentList, long printFormId, long copies = 1, IDictionary<string, object> parameters = null) – аналогичный предыдущему метод асинхронной печати.

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

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

•GetPrintersList(long printServerId) – возвращает список системных имен принтеров для указанного сервера печати:

▪printServerId – идентификатор сервера печати;

•SavePrintStatistics(long userId, string printerName, long printFormId, long versionId, long pages, long copies) – сохраняет статистику печати в базу данных:

▪userId – идентификатор пользователя, печатавшего задание;

▪printerName – имя принтера, на котором осуществлялась печать;

▪printFormId – идентификатор использованной печатной формы;

▪versionId – идентификатор версии метаданных;

▪pages – число распечатанных страниц;

▪copies – число распечатанных копий;

•BuildNextTask() – заполняет данными (если данных нет, т.е. задача была создана с помощью асинхронного метода печати) и рендерит печатную форму следующего задания в очереди печати;

•SendNextTaskToPrint() – отправляет на печать следующее задание в очереди печати;

•MoveTaskToErrorState(long taskId, string errorData) – переводит задание в статус ошибки при печати:

▪taskId – идентификатор задания печати;

▪errorData – данные ошибки;

•PrinterAlarm(long printerId) – информирует администратора о проблеме с принтером:

▪printerId – идентификатор принтера;

•PrinterAlarm(string systemName) – информирует администратора о проблеме с принтером:

▪systemName – системное имя принтера;

•PrintServerAlarm(long printServerId) – информирует администратора о проблеме с сервером печати:

▪printServerId – идентификатор сервера печати;

•GetPrintServerID(long printerID) – возвращает идентификатор сервера печати для указанного принтера:

▪printerID – идентификатор принтера;

•GetFilteredPackageQueue(IDList packageList, PrintPackageFilter filter, int rowsCountLimiter) – возвращает очередь пакетов печати, удовлетворяющую условиям фильтра:

▪packageList – список идентификаторов пакетов. Если в качестве значения параметра указать null – поиск по фильтру будет осуществлен среди всех пакетов печати;

▪filter – фильтр PrintPackageFilter, описывающий какие из пакетов печати будут возвращены. Класс PrintPackageFilter – контейнер данных для значений фильтра, применяемого к пакетам печати – обладает следующими свойствами:

▪FailedOnly, типа bool – если в качестве значения параметра указать true, поиск по фильтру будет осуществлен только среди пакетов печати в статусе с ошибкой;

▪StateID, типа long – идентификатор статуса пакета печати;

▪SessionID, типа string – GUID сессии;

▪PrintTimeFrom, типа DateTime – дата начала периода, в котором был создан пакет печати;

▪DateTime, типа DateTime – дата окончания периода, в котором был создан пакет печати;

▪PrintServerID, типа long – идентификатор сервера печати;

▪PrinterID, типа long – идентификатор принтера;

▪UserID, типа long – идентификатор пользователя;

Если в качестве значения параметра указать null – поиск будет осуществлен с пустым фильтром;

▪rowsCountLimiter – ограничитель количества возвращаемых строк;

•SetPackageState(long packageId, long packageStateId) – устанавливает статус для указанного пакета печати:

▪packageId – идентификатор пакета печати;

▪packageStateId – идентификатор статуса пакета;

•SetPrinterPackagesState(long printerId, long packageStateId) – устанавливает статус всех пакетов печати для указанного принтера:

▪printerId – идентификатор принтера;

▪packageStateId – идентификатор статуса пакетов печати;

•SetPrintServerPackagesState(long printServerId, long packageStateId) – устанавливает статус всех пакетов печати для указанного сервера печати:

▪printServerId – идентификатор сервера печати;

▪packageStateId – идентификатор статуса пакетов печати;

•SetPackagePrinter(long packageId, long printerId) – устанавливает принтер для указанного пакета печати:

▪packageId – идентификатор пакета печати;

▪printerId – идентификатор принтера;

•MovePrinterPackagesToPrinter(long printerId, long newPrinterId) – перемещает все пакеты печати с одного указанного принтера на другой:

▪printerId – идентификатор принтера с которого необходимо переместить пакеты печати;

▪newPrinterId – идентификатор принтера на который следует переместить пакеты;

•CleanupPackage(long packageId) – удалить указанный пакет печати:

▪packageId – идентификатор пакета печати;

•CleanupPrinterPackages(long printerId) – удалить все пакеты печати указанного принтера:

▪printerId – идентификатор принтера;

•CleanupPrintServerPackages(long printServerId) – удалить все пакеты печати указанного сервера печати:

▪printServerId – идентификатор сервера печати;

•EventHandler PrintTasksAvailable – обработчик событий, выполняемый после появления доступных заданий печати.

Класс PrintPackage (из пространства имен Ultima.Printing) – контейнер данных, применяемый для заполнения заданиями печати пакетов в очереди – реализует следующие методы:

•AddTask(long printFormId, long copies = 1, IDictionary<string, object> parameters = null) – добавляет задание печати печатной формы, не связанной с каким либо объектом:

▪printFormId – идентификатор печатной формы;

▪copies – число печатаемых копий (значение по умолчанию 1);

▪parameters – дополнительные параметры печати (значение по умолчанию null);

•AddDictionaryRecordTask(Type dictionaryType, long recordId, long printFormId, long copies = 1, IDictionary<string, object> parameters = null) – добавляет задание печати (одной) записи справочника:

▪dictionaryType – тип справочника;

▪recordId– идентификатор записи справочника;

▪printFormId – идентификатор печатной формы;

▪copies – число печатаемых копий (значение по умолчанию 1);

▪parameters – дополнительные параметры печати (значение по умолчанию null).

Также существует типизированный вариант этого метода AddDictionaryRecordTask<T>(this PrintPackage pack, long recordId, long printFormId, long copies = 1, IDictionary<string, object> parameters = null);

•AddDictionaryListTask(Type dictionaryType, IDList recordList, long printFormId, long copies = 1, IDictionary<string, object> parameters = null) – добавляет задание печати списка записей справочника:

▪dictionaryType – тип справочника;

▪recordList– список идентификаторов записей справочника;

▪printFormId – идентификатор печатной формы;

▪copies – число печатаемых копий (значение по умолчанию 1);

▪parameters – дополнительные параметры печати (значение по умолчанию null).

Также существует типизированный вариант этого метода AddDictionaryListTask<T>(this PrintPackage pack, IDList recordList, long printFormId, long copies = 1, IDictionary<string, object> parameters = null);

•AddDocumentTask(long documentId, long printFormId, long copies = 1, IDictionary<string, object> parameters = null) – добавляет задание печати (одного) документа:

▪documentId– идентификатор документа;

▪printFormId – идентификатор печатной формы;

▪copies – число печатаемых копий (значение по умолчанию 1);

▪parameters – дополнительные параметры печати (значение по умолчанию null);

•AddDocumentListTask(IDList documentList, long printFormId, long copies = 1, IDictionary<string, object> parameters = null) – добавляет задание печати списка документов:

▪documentList– список идентификаторов документов;

▪printFormId – идентификатор печатной формы

▪copies – число печатаемых копий (значение по умолчанию 1);

▪parameters – дополнительные параметры печати (значение по умолчанию null).

Примеры использования API печати: