SDK Programming Guide

Miraplacid Publisher SDK Programming Guide
Miraplacid Publisher is actually a collection of ActiveX objects which communicate with each other trough well-defined COM interfaces. This model allows us to keep the system highly scalabe and extensible. Every component could be developed independently and base on different technologies as long as it supports COM. All examples provided in two separate folders: "examples.vb" containing project written in VB 6.0, and "examples.net" containing projects written in C#.
There are 5 different types of software modules in Publisher: This manual describes only Core and UI interaction details and registration services.
Transport and Rendering plug-ins interfaces are still subject of change and will be presented in the next version os SDK.

For simple solutions like scripting support or object creation from VB, please, refer to Scripting manual.

Miraplacid Publisher Object Model
Publisher Core component consists of two COM objects (coclasses): MP_Register object will be always created and its interface will allow calling program to verify Publisher registration status and to register Publisher. MP object will not be created successfully if trial period is expired. Unlimited version of SDK does not contain MP_Register coclass and object MP will be created always.

For C++ users: Number means long and String means BSTR in this guide.
Do not forget to add get_ (read) and put_ (write) prefixes for properties.

Miraplacid Publisher IMP Object Reference
This is a main Publisher interface. Its IID is {D5FD471D-BAEC-4dfa-8C3C-CCD09050B3AA}.

Property Type Description
Value VARIANT (String Name) (Read / Write) All the Miraplacid Publsher Properties. This is Default Property. Meaning, it could be referred as obj("property_name") as well as obj.Value("property_name")
All the parameters are listed below.
DocumentName String (Read Only) Original name of the printed document
TotalPages Number (Read Only) total estimated amount of pages in current print job
ReadyPages Number (Read Only) Amount of pages ready to process
JobProperty VARIANT (String Name) (Read Only) Current job various properties. All the parameters are listed below.
TotalJobs Number (Read Only) Number of printed documents spooled in Publisher and waiting for processing
AutoSend Number (Read / Write) 0 - interactive mode; 1 - Process and Auto-send to the specified destinations
Identity Number (Read / Write) Identity value to replace {{IDENTITY}} tag
Format String (Read / Write) Selected Format Plug-in name
FormatParam VARIANT (String PluginName, String ParameterName) (Read / Write) Format Plug-in Parameters
All the parameters for all plug-ins are listed below.
FormatParamNoCheck VARIANT(String PluginName, String ParameterName) (Write Only) Format Plug-in Parameters. Use this option to set only appropriate property, without updating plug-in user interface and checking value. This option is useful when you need to set all options in a batch, and some options affect others. After all options are set, call FormatCheckSettings to update plug-in state correctly.
FormatPluginNames String Collection (Read Only) List of installed format plug-ins (BMP, JPG and so on)
Transport String (Read / Write) Selected Transport Plug-in names. If more than one transport plug-in selected, names shall be comma delimited.
TransportParam VARIANT(String PluginName, String ParameterName) (Read / Write) Transport Plug-in Parameters
All the parameters for all plug-ins are listed below.
TransportParamNoCheck VARIANT(String PluginName, String ParameterName) (Write Only) Transport Plug-in Parameters. Use this option to set only appropriate property, without updating plug-in user interface and checking value. This option is useful when you need to set all options in a batch, and some options affect others. After all options are set, call TransportCheckSettings to update plug-in state correctly.
TransportPluginNames String Collection (Read Only) List of installed transport plug-ins (File, FTP and so on)
Printer String (Read / Write) Name of the currently selected printer
Printers String Collection (Read Only) List of all printers in Publisher collection.
SystemPrinters String Collection (Read Only) List of all printers installed in the system. Useful for user interface, this property allows UI to avoid using spooler API.
DefaultPrinter String (Read Only) Name of the default printer in the system.
ValueNoRedraw (hidden) VARIANT (String Name) (Write Only) Does the same as Value except that ValueNoRedraw does not force image re-processing after changing value.
To prevent processing overhead when you need to change several parameters at once, you may use ValueNoRedraw to set all parameters exacept the last, and Value for last parameter to let Core re-process the page once with cumulative changes.
UILoaded (hidden) Number (Read / Write) 0 - UI not loaded; 1 - UI loaded.
UI should set this value when it loaded and initialized and clear (set to 0) on unload. When you read from this property, it returns number of UIs loaded.
UILoadedWithEvents (hidden) Number (Write only) 0 - UI not loaded; 1 - UI loaded.
UI should set this value when it loaded and initialized and clear (set to 0) on unload. UI chould use this value if it needs to receive all necessary print job events (StartJob, StartPage, EndJob) even if it started in the middle of print job processing (see UI working scheme).
Listeners (hidden) Number (Read only) Number of processes/modules subscribed to events.
Publisher may work with several UIs and ordinary listeners. UIs, in difference of listeners, registers themselves using UILoaded.
Method Parameters Description
SendPage Number Send a particular page as an image through selected Transport Plug-Ins. Returns immediately.
SendPageWait Number Send a particular page as an image through selected Transport Plug-Ins. Waits until all pages will be saved.
SendAll None Send All through selected Transport Plug-Ins. Returns immediately.
SendAllWait None Send All through selected Transport Plug-Ins. Waits until page will be saved.
CancelJob None Cancel current Print Job. Returns immediately.
CancelJobWait None Cancel current Print Job. Waits until current job will be cancelled and the new one will be opened, if any.
CancelAllJobs None Cancel Publisher's internal print queue and spooler queue associated with Publisher
SaveConfiguration None Save current configuration for active user and active printer
SaveCommonConfiguration None Save current configuration for all users (who do not have own configurations yet) and active printer
LoadUI None Loads user interface component if it is not already loaded.
UnloadUI None Unloads user interface component, if it supports OnUnload event.
GetEMFPage Number index, String filename Extracts a page referred by index from current job and saves it as a file "filename" in EMF format. Caller is responsible for deleting this file.
Special tags supported.
SetEMFPage Number index, String filename Assigns a file "filename" to be a content of page referred by index. File must be in EMF format. Caller is responsible for deleting this file. File must not be deleted before the job is saved.
If EMF image dimensions from external file are different from those used in other pages in print job, multipage saving will not work.
To set page back to original content from print job spool file, set filename to empty string or NULL value.
Special tags supported.
Stop None Unloads plug-ins, get ready for unloading from memory. System will unload Miraplacid Publisher core form memory with 2-5 seconds delay. We recommend you to add this method call at the end of each script.
FormatCheckSettings String plug-in Call this method after updating several plug-in settings in a batch (using FormatParamNoCheck). Some settings may affect others, and this method guarantees that they will be updated in correct order.
TransportCheckSettings String plug-in Call this method after updating several plug-in settings in a batch (using TransportParamNoCheck). Some settings may affect others, and this method guarantees that they will be updated in correct order.
PreparePage (hidden) Number UI should call this method to force Core prepare page (load, make processing according current settings) for displaying to user.
Parameter mean number of page to prepare, staring from 1. Core will return immediately and provide the page with OnPageReady event.

Miraplacid Publisher Properties Reference
All these properties accessible via default "Value" property:
obj.Value("ScaleWidth") = 1024
or just
obj("ScaleWidth") = 1024
In C language, this will be:
_bstr_t pname;
pname=L"WcaleWidth";
mp_core->put_Value(pname,_variant_t((ULONG)1024));

Property Type Description
ScaleWidth Number scale size
ScaleHeight Number scale size
ScaleMode Number scaling algorithm: 0 - no scaling (default), 1 - Fast, 2 - Bilinear, 3 - Bicubic
ScalePercent Number 0 - scale size in pixels (default), 1 - scale size in percents
ScaleConstrain Number 1 - constrain scaling proportions, 0 - not (default)
BorderWidth Number leave that many pixels space left and right from the detected area (auto-detect mode only)
BorderHeight Number leave that many pixels space top and bottom from the detected area (auto-detect mode only)
BorderType Number 0 - No (default), 1 - Auto-detect, 2 - Manual
BorderLeft Number in Manual Mode - set left border for clipping
BorderRight Number in Manual Mode - set right border for clipping
BorderTop Number in Manual Mode - set top border for clipping
BorderBottom Number in Manual Mode - set bottom border for clipping
FlipH Number 1 - flip image vertical, 0 - not (default)
FlipV Number 1 - flip image horizontal, 0 - not (default)
Gamma Number gamma (0 .. 511, 255 is default)
Saturation Number saturation (0 .. 511, 255 is default)
Value Number value (0 .. 511, 255 is default)
Hue Number hue (0 .. 359, 179 is default)
GrayScale Number 0 - color (default), 1 - force grayscale
Invert Number 1 - invert image colors, 0 - not (default)
MultiPage Number 1 - generate one multipage image of document, 0 - one image per page (default)
BackgroundImage String Name of file which will be used as a background image

Miraplacid Publisher Job Properties Reference
All these properties accessible via "JobProperty" property:
var job_status = obj.JobProperty("Status")

Property Type Description
JobID Number System print job ID for the current job.
0 if no active job.
Status Number Current job status. Binary flags (ORed):
  • 0 - No print jobs currently in progress.
  • 1 - Started - initial state just after StartJob event from driver.
  • 2 - Opened for rendering. This may happen just after the job will be created, if not other jobs are in Publisher queue,
  • 4 - Printed - printer driver completed all operations with current job. After that, the job may still not be available for save, it must be Opened and Rendered first.
  • 8 - Rendered - ready for save. All the job contents are processed by selected rendering plug-in.
  • 16 - MixedOrientation - a bit flag. Set by Core pre-processor if the job contains pages with different page orientations or dimensions.
    This flag prohibits saving multipage documents in some graphics formats.
Resolution Number Resolution for the current job, in DPI.
0 if no active job.
Printer String Printer name for the current job.
Empty string if no active job.
Document String Document name for the current job.
Empty string if no active job.
SpoolFile String Spool file name with full path for the current job.
Empty string if no active job.

Miraplacid Publisher Output Format (Format plug-ins) parameters
To query or modify Format plug-in parameters, use FormatParam property of Miraplacid Publisher object.
obj.FormatParam("GIF","palette")=64

Bitmap
Property Type Description
output Number Output Format. 0 = 32-bit, 1 = 24-bit, 2 = 16-bit, 3 = 8-bit, 4 = 4-bit, 5 = 1-bit.
diffusion Number 0 = turn off errors diffusion algorithm, 1 = turn on
palette Number 0 = use default palette, 1 = use custom palette
GIF
Property Type Description
palette Number Number of colors in resulting GIF file.
delay Number Delay in milliseconds between frames in multipage (animated) GIF.
loops Number Number of repetitions of frame loop in multipage (animated) GIF.
diffusion Number 0 = turn off errors diffusion algorithm, 1 = turn on
JPG
Property Type Description
output Number Output image quality. 0 = 100% quality, 1 = 95% quality and so on up to 10%. 18 = 10% quality.
PDF
Property Type Description
output Number Output Format. 0 = 100% quality, 1 = 95% quality and so on up to 10%. 18 = 10% quality.
title String PDF document Title
creator String PDF document Creator
author String PDF document Author
PNG
Property Type Description
output Number Output Format. 0 = 24-bit, 1 = 8-bit, 2 = 4-bit, 3 = 1-bit.
compression Number 0 = No Compression. 1 = Default Compression. 2 = Fast Compression. 3 = Best Compression (recommended)
diffusion Number 0 = turn off errors diffusion algorithm, 1 = turn on
palette Number 0 = use default palette, 1 = use custom palette
TGA
Property Type Description
output Number Output Format. 0 = 32-bit, 1 = 24-bit, 2 = 16-bit, 3 = 8-bit.
diffusion Number 0 = turn off errors diffusion algorithm, 1 = turn on
palette Number 0 = use default palette, 1 = use custom palette
TIFF
Property Type Description
output Number Output Format. 0 = 32-bit CMYK, 1 = 24-bit, 2 = 8-bit, 3 = 4-bit, 4 = 1-bit.
compression Number 0 = No Compression. 1 = Packbits (RLE), 2 = LZW, 3 = CCITT Group 3, 4 = CCITT Group 4.
2 and 4 work only for 1-bit mode.
diffusion Number 0 = turn off errors diffusion algorithm, 1 = turn on
palette Number 0 = use default palette, 1 = use custom palette

Miraplacid Publisher Send To (Transport plug-ins) parameters
To query or modify Transport plug-in parameters, use TransportParam property of Miraplacid Publisher object.
obj.TransportParam("File","filename")="image_{{PAGE}}"

File
Property Type Description
path String Destination File Path. Special tags supported.
filename String Destination File Name. Special tags supported.
open Number Opens result image file with post-processor.
everypage Number 0 = call post-processor once per document. 1 = call post-processor for each saved image. Ignored if open=0.
hide Number 0 = show post-processor window. 1 = hide post-processor window. Ignored if open=0.
exec String Post-processor filename with full path. Special tags supported. Ignored if open=0.
param String additional parameters for post-processor. Special tags supported. Ignored if open=0.
wait Number Set it to 1 if you wish to wait application termination before continue. Ignored if open=0.
unilist Number Set it to 1 if you wish to get list file content in Unicode. Ignored if open=0 or everypage = 0.
FTP
Property Type Description
url String Destination FTP directory URL. Special tags supported.
file String Destination File Name. Special tags supported.
passive Number 0 = FTP passive mode OFF. 1 = FTP passive mode ON.
user String FTP server username.
password String FTP server password.
HTTP
Property Type Description
url String Destination HTTP URL. Special tags supported.
file String Destination File Name. Special tags supported.
put Number 0 = use POST method. 1 = use PUT method.
user String username.
password String password.
Mail
Property Type Description
mail String Semicolon-separated list of email addresses.
message String Email message body. Special tags supported.
subject String Email message subject. Special tags supported.
filename String Name of attachment file. Special tags supported.
Printer
Property Type Description
printer String Printer name. Can be a real printer name or "Default" string which means default printer.
settings ByteArray One-dimentional Safearray of bytes containing printer settings (DEVMODE).
To use default printer settings, set this value to the empty Safearray of bytes.
margins Number 1 - use printer margins, 0 - not.
fit Number 0 = Print page as-is. 1 - Fit image to printer page.
scale Number scale factor, in percents, for additonally adjust fit to page feature. Ignored if fit=0.

Miraplacid Publisher _IMPEvents Events Reference.
This is connection point interface which UI uses to catch printing events from Core component. Its IID is {BCDAF6C5-8CA2-4eea-A299-45F0FE0365F5}.

Event Parameters Description
OnStartJob None Called when Core receives start job signal from driver.
OnPagePrinted Number Called when Core receives next job from driver with page number as a parameter.
OnAllPagesPrinted None Called when Core receives end job signal from driver.
OnPageReady Number page_id, String object Called when Core prepared a page for displaying in responce to PreparePage method call. Page_id is a number of prepared page. Object parameter is a name of Windows FileMapping object which contains ready-to-display Windows bitmap.
UI may use this object as a memory object with OpenFileMapping/MapViewOfFile API calls.
OnCancelJob None Called when Core finishes all activity with current job as an acknowledge for CancelJob call from UI or after SendAll process end.
OnUnload None Called when AutoSend property is set to true. UI should unload upon receiving this event.
OnProgress String source, Number value Called when some lengthy process is taking place. Source could be a name of transport plug-in - in this case it reflects sending progress for this particular plug-in; or special value "Process" which reflects the state of image processing. Special value of "Convert" reflects state of image conversion process (from internal representation to perticular image format). Value is the value of progress indicator (0 - 100).
OnProcessingEvent Number event Called on start and finish of various saving and processing stages. This event lets receiver know exactly when and which process is going on.
The following codes suported:
  • 1 - Page or document processing started
  • 2 - Page or document conversion (to chosen graphics format) started
  • 3 - Save page started
  • 4 - Save document started
  • 5 - Page or document processing ended
  • 6 - Page or document conversion (to chosen graphics format) ended
  • 7 - Save page ended
  • 8 - Save document ended
OnError Number code, String message Called when some error is happened. Message is textual representation of the error. There are the folowing codes could be passed to this event:
  • 1 - "Cannot get transport parameter"
  • 2 - "Cannot select transport"
  • 3 - "Cannot put transport parameter"
  • 4 - "Cannot get format parameter"
  • 5 - "Cannot select format plug-in"
  • 6 - "Cannot put format parameter"
  • 7 - "Invalid printer name"
  • 8 - "Cannot change printer"
  • 9 - "Cannot save configuration"
  • 10 - "No transports selected"
  • 11 - "Invalid format plug-in name"
  • 12 - "Sorry, you are not allowed to print to this printer"
  • 13 - "Invalid page number"
  • 14 - "Trial period expired"
  • 15 - "Cannot start driver engine"
  • 16 - "Cannot put value"
  • 17 - "Cannot open own printer"
  • 18 - "There is no job ready for save"
  • 19 - "Busy: processing is in progress"
  • 20 - "Cannot save multipage document with mixed page orientation using this output type"
  • 21 - "Empty job - will be cancelled automatically"
  • 22 - "User Interface component already loaded"
  • 23 - "User Interface component is not loaded"
  • 24 - "Cannot load temporal image"
  • 25 - "Cannot convert image"
  • 26 - "Transport Start failed"
  • 27 - "Transport Process failed"
  • 28 - "Transport End failed"
  • 29 - "Selected transport plug-ins are incompatible with Multipage saving mode"
  • 30 - "Cannot save EMF page"
  • 31 - "Cannot load EMF page"
  • 32 - "Unknown value name"
  • 33 - "Stuck job - will be cancelled automatically"
  • 0x100 - Transport plug-ins errors
OnAddRemovePrinter Number Core monitors printers add/remove operations and default printer change in the system. When this happen, it generates this event to let UI update lists of printers. In responce to this event, UI must update its own printer lists and send update signal to its set of transport plug-ins to allow them update their printer lists, by calling CheckSettings method with appropriate parameter.
Parameter may have the following values:
  • 0 - Default printer changed.
  • 1 - Some printer added/removed, not from Publisher family and not redirect printer.
  • 2 - Some printer from Publisher family added/removed.
OnSettingChanged String target, String property, Variant value When some of clients connected to particular Core object changes a property of this object, Core will broadcast this event to all its listeners. For Core properties, target will be "Core", for plug-ins - plug-in name.
Other parameters are property name and its new value.
Using this mechanism, it is possible to use Publisher with several UIs or other listeners, each will always have actual set of property values.
Special case of property is a "Printer" value. It changes when Core receives print job for different printer or after initial configuration load. UI must re-read all the configuration from Core.
If property changed to its current value, event will be sent with empty Variant.
Please, note that client (UI) initiated the change will receive this event as well.
OnSettingsChangeFailed String target, String property If some configuration parameter has been changed incorrectly, or change in one parameter changes another settings, Core fires this event.
In responce to this event, UI must reload apporpriate porperty.

Miraplacid Publisher IMP_Register Object Reference.
When evaluation period is expired, object of the main interface (IMP) will not be created successfully. Application should use IMP_Register interface to register Publisher. Its IID is {90D08213-5B6D-4103-96A7-297AA8EC4DEB}.
Examples of registration utility are located at examples.vb\register and examples.net\MP_SE_Reg folders at this package.

Property Type Description
Valid Number (Read Only) May be used to examine current evaluation state. Has the following values:
  • <=0 - Internal error happened in verification code. This could be caused by corrupted .key file, wrong permissions of .key file, etc.
  • 1 - Publisher is registered.
  • 2 - Publisher is unregistered but trial period is not expired.
  • 3 - Trial periond is expired.
Users String Collection (Read / Write) List of users currently allowed to print to Publisher. Implemented in Terminal Server version only.
UserLicenses Number (Read Only) Maximum number of end user licenses. Implemented in Terminal Server version only.
Method Parameters Returns Description
SetLicense String FirtsName, String LastName, String Keycode Number This method is intended for registering Publisher. Application must provide FirstName, LastName and Keycode generated by Miraplacid to this method. Resulting value is 1 if registration succeeded, 0 if not. After 3 unsuccessful registration attempts this method will always return CLASS_E_NOTLICENSED and will not actually try to register. Application should re-create the object to continue registering.
LoadUI None None Method LoadUI allows application to force loading UI which will ask user for registration information. This could be done if Valid property returns 2 or 3.

Miraplacid Publisher UI working scheme.
You can see a live custom UI examples in examples.vb\customui and examples.net\MP_SE_UI folders of SDK package.
  1. UI is launched by Core when it receives a new job and AutoSend property is in false state or by user when he clicks on Publisher icon on Desktop or Programs folder.
  2. UI loads MP object and obtains IMP interface pointer.
  3. UI establishes a connection with Core and loads configuration (by reading properties). After initialization steps (when it will be ready to receive events), UI must set UILoaded property to 1 (true). This property counts active UIs, and, if UI was loaded and the last UI sets UILoaded=0, core will save configuration automatically.
    When Core launches UI, it looks for "WaitUILoaded" parameter in its registry folder (HKLM).

    If WaitUILoaded = 0 (default value), Core does not wait for UI to be loaded. So, when UI will be ready to listen events, it will appear in the middle of print job (OnStartJob + some page or whole job events may be missed).
    And, even if user starts UI from Desktop, it may connect to Core with current print job already waiting for user input (save or cancel).
    To avoid this situation and get current status correctly, there are two possibilities exists:
    • Get the current job status from core before subsribing to events, as did in .Net UI example. This is the most correct method.
    • Use UILoadedWithEvents = 1 construction. This property will feed UI with all needed events for current job automatically, if Core has active job.
      This is the most simple method, but it has one side-effect: if you use several applications listens events from Core, all them will receive print job events missed by this UI. This is the only way for applications written in languages like VB, which creates objects and subscribes to events in one operation (Dim WithEvents).
      In this case, you need to set UILoadedWithEvents right after object creation.
    We recommend to use this method for UIs intended for interactive job with user.

    If WaitUILoaded = 1, Core waits UI to be loaded (on StartJob) for 60 seconds maximum, then continues job processing. This method is convenient for UIs which perform job data processing in automatic mode, without significant user intervention.
    UI should use any method of events subscription and UILoaded=1 and it will not miss any events from Core.
    If you wish to use this mode, do not forget to set WaitUILoaded parameter to 1 in your installer.
Further steps (4 - 7) make an event-driven loop.
Core generates events in two modes: syncronous and asyncronous. To control this mode, installer may set "AsyncEvents" parameter in Publisher registry folder (HKLM).
When Core users asyncronous events mode, it sends events from separate thread and does not wait for UI to return. So, if your UI performs some processing on events (not just mirror Core state), we recommend you to use asyncronous mode - the printing process will be faster. Core may collect print jobs with its maximal speed, and UI will process them with its own speed.
But, please, be careful when your UI works in asyncronous mode and Core is in autosend mode. If your UI slower than Core and it makes some actions with print job (saving particular pages/all pages, etc), these actions in autosend mode may affect wrong print job because in autosend mode Core does not wait the job to be calcelled from UI - it saves a job automatically and get the next one from queue.
In this case, you need to ensure that Core is not in autosend mode.
  1. OnStartJob: On this event UI may read document name and examine print job status. Job may already be completed (printed) if next job was printed on background before finalizing previous one.
  2. OnPagePrinted: If the job was already completed, this event will not be generated. On this event, its possible to ask for a page by calling PreparePage method.
    Calling this method will force Core to start processing of the page. It makes sense to ask only for page which is currently displayed.
  3. OnAllPagesPrinted: This is informational event which allows UI to update its internal state (and interface elements like SaveAll button).
  4. OnPageReady: Core sends this event if UI asked for a page and it is ready for displaying. UI may read the picture and display it. This event may be generated not only in responce to PreparePage call; Core will fire it when it saves all job, in page-by-page or multipage mode. The order of pages may be reverse in this case, depending from image format, so page_id parameter is important.
The following stage is interactive job with end user.
  1. User can change settings. Appropriate Core properties must be set by UI. During this process, OnError event might be raised in response to incorrect property change. OnSettingChanged event will be received by UI.
  2. User can change active printer, save its configuration for current user or for all users.
  3. User can save current page. UI shall call SendPage method.
  4. User may want to save all pages. UI shall call SendAllPages method. In response to this call, Core will notify UI by raising OnCancelJob event when job is done. On this event, UI must get ready for the next job. If some transports fail, Core raises OnRewindJob event (but does not cancels the job). On this event UI can rewind the job to the first page, show some (additional) error message, etc.
  5. User can cancel the job. UI must call CancelJob method. In response, Core generates OnCancelJob event.
  6. During saving process, Core will generate OnProgress events or OnError if some error happened.
At any time, Core may send OnAddRemovePrinter event if some printer configuration changed in the system.
Dependent from this event argument, UI should take appropriate measures - reload printer lists, configuration, etc.

Miraplacid Publisher Format plug-ins.
Format plug-ins are Publisher components intended for image conversion from internal image representation (bitmap) to particular graphics format file, or, optionally, for reverse conversion.
Format plug-ins are AcitveX components which implements all standard visual ActiveX component interfaces.
Additionally, it must obey the following requirements:

IMP_FPLUGIN interface:

Property Type Description
Value Variant (Read/Write) Any properties that your plug-in may have. Some of them may be saved into configuration in registry and restored from it.
ValueNoCheck Variant (Write Only) The same as Value, but does not check value itself or against other values and does not update UI. Use to prevent update relative settings in a wrong order. When all the settings updated, call CheckSettings method.
Name String (Read Only) Plug-in name for internal use.
Layout String (Read Only) This string contains a list of properties (Values) which should be saved in configuration or restored from it.
Format of this string is: "Bparam1,Lparam2,EParam3", where "B", "L" and "E" are prefixes meaning type of parameter (BSTR, Long and Encrypted BSTR, which will be saved in encrypted form and decrypted on load from registry, accordingly). Parameter names should be separated by commas. Spaces are not allowed.
Extension String (Read Only) File extension corresponding current rendering plug-in, without leading period, i.e. "gif", "bmp".
SafeForMultipage Number (Read Only) Returns 1 if this plug-in is able to support multipage images with pages of different dimensions. For example, TIFF, GIF and PDF have internal paged stucture, while other plug-ins assemble "multipage" images by glueing pages together, and this prevents them from accepting pages with different dimensions.
Core analyses this property and prohibits saving multipage documents with this format if it does not supprt this feature.
Method Parameters Description
Convert IImageCollection *images, Number resolution, String filename Conversion procedure. Plug-in should obtain images from images, convert it to appropriate format and save to filename.
If images collection provides several images to plug-in, it should generate multipage file filled with all images provided.
Resolution is a printer DPI value which can be set to the image.
ConvertToBitmap String in_file, String out_file Reverse conversion procedure, used for background image loading. Plug-in should read input file and convert it to bitmap file in internmal format.
If image is in wrong format or error happened during decoding, plug-in should return E_FAIL or other appropriate error.
If decoding procedure is not supported, plug-in should return E_NOTIMPL.
CheckSettings no parameterts; returns nothing Call this method after a series of ValueNoCheck done to perform values (mutual) check and update plug-in UI state.
InitSettings no parameterts; returns nothing Core calls this method when there is no configuration for current printer loaded. Plug-in must update its internal settings and UI.

_IMP_FPlugin_Events interface:

Method Parameters Description
OnChangeParam String plugin, String param, VARIANT val When some plug-in parameter has changed via user interface, plug-in informs about that with OnChangeParam event.
"plugin" is internal name of plug-in, "param" is a name of changed parameter, "val" is a new value of parameter.
OnProgress String plugin, long value During conversion process, plug-in may fire this event to provide information about the progress of image conversion.

IImageCollection Core interface:

Property Type Description
Count Number (Read Only) Number of images in image set.
Method Parameters Description
Item Number index; returns String With this method, plug-in receives page content identified by "index". Method returns name of system filemapping object containing bitmap image for conversion.

Format plug-in working scheme

  1. UI starts and loads plug-ins. It subscribes to _IMP_FPlugin_Events events interface.
  2. UI gets Layout property. According to Layout parameters, it reads appropriate FormatParam properties from Core and sets as a Values of plug-in (using ValueNoCheck property and calls CheckSettings).
  3. Core creates plug-ins too and subscribes to events. OnProgress event inform Core about conversion progress. Using OnChangeParam event, plug-ins may have special parameters which will be changed dynamically and will be supported by Core as a part of configuration and will be saved in registry.
  4. Core gets Layout property. According to Layout parameters, it reads saved values from configuration (registry) and sets as Values of plug-in (using ValueNoCheck property and calls CheckSettings). If configuration for current printer does not exist, Core calls InitSettings.
Remark: UI and Core may start each other, but the final situation does not change: Core reads settings and sets plug-in properties first, then UI reads these properties and sets them to its "own" plug-ins.
There are two sets of plug-ins exists in the scheme, because UI and Core are separate processes.

Interactive job cycle:
  1. User changes settings of plug-in. Plug-in updates its internal state and raises OnChangeParam to UI.
  2. In responce, UI sets appropriate Core property with FormatParam. In result, all parameters are in sync.
Rendering job cycle. Job of rendering plug-in is page-oriented.
  1. When Core needs to convert (and save) current page or all pages in a single miltipage file, it calls Convert method.
  2. Plug-in calls Count property of IImageCollection imterface provided as paramter. If count = 1, plug-in calls Item method and get a name of filemapping obect.
    Then, it just converts an image containing in this object to appropriate image fomat and saves it to file.
    Format of filemapping image is bitmap (BimapInfoHeader + bitmap bits, in 24-bit format).
  3. If count > 1, that means plug-in need to save several images to a single multipage file. Formats which support multipage images (TIFF, animated GIF) may use these possibilities; other formats should just make one lenghty contiuous image file.
  4. Upon loading configuration, Core may call ConvertToBitmap method to load background image.
  5. If some "dynamic" parameter will be changed during working process, plug-in will fire OnChangeParam event. Core will broadcast this event to all subscribers and save it in configuration.

Miraplacid Publisher Transport plug-ins.
Transport plug-ins are Publisher components intended for saving converted images to some destination (file, URL) using some transport protocol (file, FTP, HTTP).
Transport plug-ins are AcitveX components which implements all standard visual ActiveX component interfaces.
Additionally, it must obey the following requirements:

IMP_TPLUGIN interface:

Property Type Description
Value Variant (Read/Write) Any properties that your plug-in may have. Some of them may be saved into configuration in registry and restored from it.
ValueNoCheck Variant (Write Only) The same as Value, but does not check value itself or against other values and does not update UI. Use to prevent update relative settings in a wrong order. When all the settings updated, call CheckSettings method.
Name String (Read Only) Plug-in name (short).
Layout String (Read Only) This string contains a list of properties (Values) which should be saved in configuration or restored from it.
Format of this string is: "Bparam1,Lparam2,EParam3", where "B", "L" and "E" are prefixes meaning type of parameter (BSTR, Long and Encrypted BSTR, which will be saved in encrypted form and decrypted on load from registry, accordingly). Parameter names should be separated by commas. Spaces are not allowed.
UsesRawImage Number (Read Only) Plug-in should return 1 if it does not need to convert image to particular format; it uses internal representation (bitmap) directly.
Example of such a plug-in could be printer plug-in which prints bitmap to a printer and does not need converted image.
Method Parameters Description
Start None Publisher Core call this member when it begins saving text page(s). Plug-in may update its internal state and prepare resources.
Process String name, ITransportHelper object Publisher Core calls this method when it needs to send converted file to selected location.
"name" is name of the source object to save. For raw plug-ins (UsesRawImage == 1) this will be a name of file mapping object; for other plug-ins this is a name of graphics file.
"object" parameter is an interface provided by Core which allows plug-in to translate strings.
End ITransportHelper object Publisher Core call this member on end of saving to let plug-in free used resources and update its state.
"object" parameter is an interface provided by Core which allows plug-in to translate strings.
CheckSettings Number Call this method with parameter = 0 after a series of ValueNoCheck done to perform values (mutual) check and update plug-in UI state.
Other values of parameter is for plug-ins which deals with printers. If some plug-in will not need this information, it may ignore calls with values other than 0 and return immediately.
If parameter = 1 - default printer changed. Plug-in may just update visual representation of its printer list. If parameter = 2 - some printer added/removed. Plug-in must reload printer list and update all settings.
InitSettings None Core calls this method when there is no configuration for current printer loaded. Plug-in must update its internal settings and UI.

_IMP_TPlugin_Events interface:

Method Parameters Description
OnChangeParam String plugin, String param, VARIANT val When some plug-in parameter has changed via user interface, plug-in informs about that with OnChangeParam event.
"plugin" is internal name of plug-in, "param" is a name of changed parameter, "val" is a new value of parameter.
OnError String plugin, String error_message When some error happens during saving the text, plug-in should raise OnError event. "error_message" is what user will see as an error description.
OnProgress String plugin, Number value Plug-in should raise this event periodically during saving process. Value is the value of progress indicator (0 - 100).

ITransportHelper Core interface:

Method Parameters Description
TranslateString String input; Number translate_flag; returns String output Translates string possibly containing special tags and replaces these tags with their actual values.
If translate_flag is not 0, this method changes unsafe characters (which cannot be used in filenames) to underscores when replaces tags.

Transport plug-in working scheme

  1. UI starts and loads plug-ins. It subscribes to _IMP_TPlugin_Events events interface.
  2. UI gets Layout property. According to Layout parameters, it reads appropriate TransportParam properties from Core and sets as a Values of plug-in (using ValueNoCheck property and calls CheckSettings).
  3. Core creates plug-ins too and subscribes to events. OnError and OnProgress events inform Core about saving progress. Using OnChangeParam event, plug-ins may have special parameters which will be changed dynamically and will be supported by Core as a part of configuration and will be saved in registry.
  4. Core gets Layout property. According to Layout parameters, it reads saved values from configuration (registry) and sets as Values of plug-in (using ValueNoCheck property and calls CheckSettings). If configuration for current printer does not exist, Core calls InitSettings.
Remark: UI and Core may start each other, but the final situation does not change: Core reads settings and sets plug-in properties first, then UI reads these properties and sets them to its "own" plug-ins.
There are two sets of plug-ins exists in the scheme, because UI and Core are separate processes.

Interactive job cycle:
  1. User changes settings of plug-in. Plug-in updates its internal state and raises OnChangeParam to UI.
  2. In responce, UI sets appropriate Core property with TrandportParam. In result, all parameters are in sync.
Saving job cycle.
  1. In response to Save or SaveAll method call, Core initiates saving procedure. Several plug-ins may work at the same time.
    Care calls Start method of each plug-in.
  2. After that, it calls Process method with appropriate parameters. During this call, plug-ins may call TranslateString method provided by Core.
  3. Finally, Core calls End method.
  4. If some "dynamic" parameter will be changed during working process, plug-in will fire OnChangeParam event. Core will broadcast this event to all subscribers and save it in configuration.

See also: