Miraplacid Publisher SDK 2009: Programming
| |
|
|
|
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" 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:
- Driver components. These are system dll modules and settings files.
This is mandatory part of Publisher.
- Core component (mp_core.exe). This is the heart of the whole system.
It takes data from the driver,
keeps it in internal queue and manages all other components - plug-ins and UI.
- UI (mp_ui.exe). This is User Interface component. This is COM client of Core component;
it uses Core methods and receives
COM events from Core. UI interacts with Core only; it have no direct access to other components.
User Interface module is not required for Publisher Core and Driver, they can work fine without UI.
To display transport and rendering plug-ins user interfaces, UI loads its own set of plug-ins as an ActiveX components.
- Format plug-ins. Inproc dll ActiveX modules which performs conversion
from internal graphics representation into particular graphics format.
Core component manages these modules.
- Transport plug-ins. Inproc dll ActiveX modules which allows to save resulting files to some locations.
Core component manages these modules.
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):
- coclass MP (MiraplacidSE.Publisher {C9828C82-2136-4e25-894F-399109583971}). This is the main part of Publisher.
The folowing interfaces included:
- IMP (default interface). Includes all methods and properties which control Publisher functionality, including plug-ins.
- _IMPEvents (default, source interface). This interface is collection of COM events and provided for Core and UI interoperability.
- Some other internal interfaces which are out of scope of current document. You do not have to learn them to build your system.
- coclass MP_Register (MiraplacidSE.PublisherRegistrator {235836F3-0079-4067-98B9-7F2E8FFE5876}).
This objects includes single interface IMP_Register, which manages registration and verification services.
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.
|
| Printers |
String Collection |
(Read Only) List of all printers in Publisher collection. |
| Printer |
String |
(Read / Write) Name of the currently selected printer |
| FormatPluginNames |
String Collection |
(Read Only) List of installed format plug-ins (BMP, JPG and so on) |
| 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.
|
| TransportPluginNames |
String Collection |
(Read Only) List of installed transport plug-ins (File, FTP 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.
|
| DocumentName |
String |
(Read Only) Original name of the printed document |
| ReadyPages |
Number |
(Read Only) Amount of pages ready to process |
| TotalPages |
Number |
(Read Only) total estimated amount of pages in current print job |
| JobStatus |
Number |
(Read Only) 0 - Created, 0001b - Opened, 0010b - Printed, 0100b - RequestedPagePrepared, 1000b - Aborted |
| AutoSend |
Number |
(Read / Write) 0 - interactive mode; 1 - Process and Auto-send to the specified destinations |
| 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. |
| AutoSendFromUI (hidden) |
Number |
(Write only) 0 - interactive mode; 1 - Process and Auto-send to the specified destinations.
This property is intended for use from UI. Regular property AutoSend causes core to unload UI. AutoSendFromUI does not lead UI unloading.
|
| 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.
|
| Method |
Parameters |
Description |
| CancelJob |
None |
Cancel current Print Job |
| CancelAllJobs |
None |
Cancel Publisher's internal print queue and spooler queue associated with Publisher |
| SendAll |
None |
Send All through selected Transport Plug-Ins |
| SendPage |
Number |
Send a particular page as an image |
| 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. |
| 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 |
| 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.
|
| 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.
|
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"scalewidth";
mp_core->put_Value(pname,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) |
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.
Ignored if open=0.
|
| param |
String |
additional parameters for post-processor.
Ignored if open=0.
|
| FTP |
| Property |
Type |
Description |
| url |
String |
Destination FTP directory URL.
|
| 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.
|
| 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.
|
| fit |
Number |
0 = Print page as-is. 1 - Fit image to printer page.
|
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.
|
| OnRewindJob |
None |
Called instead of OnCancelJob when SendAll finished with errors.
|
| 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).
|
| 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:
- General errors - code = 1
- If Value is wrong - code = 0x400
- Name errors: configuration, unknown transport or format selected - code = 0x600
- Range 0x100 - 0x1ff has a special meaning - these are transport plug-in errors.
Source transport plug-in may be located by its index which is equal to error_code - 0x100;
these errors may happen only during saving procedure.
|
| OnSetDocName |
String |
Called when Core sets document name to let UI update its status line, etc.
|
| OnChangePrinter |
String |
Called when Core receives print job for different printer or after initial configuration load. UI must re-read all the configuration from Core.
|
| OnAddRemovePrinter |
None |
Core monitors printers add/remove operations in the system. When this happen, Core analyses this incident, and, if
printer from Publisher family is added/removed, it generates this event to let UI update lists of Publisher printers.
|
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}.
Example of registration utility is located at examples\register folder at this package.
It is written in VB.
| Property |
Type |
Description |
| Valid |
Number |
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.
|
| 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 example in examples\customui folder of SDK package.
It is written in VB. Since it is just an example, it does not display pictures and does not
let you to change settings and profiles.
- 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.
- UI loads MP object and obtains IMP interface pointer.
- 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).
Core will wait this for 60 seconds; if UI will not register with this property, Core will continue
without UI.
Further steps (4 - 6) make an event-driven loop.
- 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.
- 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.
- OnAllPagesPrinted: This is informational event which allows UI to update its internal state
(and interface elements like SaveAll button).
- 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.
- 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.
- User can change configurations, create new configurations and delete existing
(except Default).
When User Interface changes configuration, it shall
reload all settings.
- User can save current page. UI shall call SendPage method.
- 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.
- User can cancel the job. UI must call CancelJob method. In response,
Core generates OnCancelJob event.
- Special case is AutoSend property. UI should call AutoSendFromUI instead of AutoSend property.
When AutoSend is set to 1, Core will raise OnUnload event to tell UI that all further processing will be performed automatically and without UI.
AutoSendFromUI property does not generate OnUnload event.
AutoSend property should be used from scripts to make sure that all processing will be performed as fast as possible and completely in the background.
If your UI ignores OnUnload event (does not unload itself), there is no difference between AutoSend and AutopSendFromUI for it.
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.
Format plug-ins are AcitveX components which implements all standard visual ActiveX component interfaces.
Additionally, it must obey the following requirements:
- It must be included into "Miraplacid Publisher Format Plug-ins" COM category (FBFE9C5A-8D40-46bd-99C1-93F162E30AE7), but not create it.
- It must implement IMP_FPLUGIN interface (69E3226F-C540-4829-9CB4-88738766C9E4) and realize _IMP_FPlugin_Events connection point dispinterface (20B34C58-2EE5-4f87-AC73-F8080DA8ABE1).
- It must not register its own type library. Ready for use type library provided in imp_fplugin.dll.
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 inconfiguration or restored from it.
Format of this string is: "Bparam1,Lparam2,BParam3", where "B" and "L" are prefixes meaning type of parameter (BSTR and Long 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. "xml", "rss".
|
| Method |
Parameters |
Description |
| Convert |
IImageCollection *images, String filename |
Conversion procedure. Plug-in sohuld obtain images from images, convert it to appropriate format and save to filename.
|
| 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.
|
_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 image for conversion.
|
Format plug-in working scheme
- UI starts and loads plug-ins. It subscribes to _IMP_FPlugin_Events events interface.
- 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).
- Core creates plug-ins too and subscribes to their events (to get OnProgress event).
- 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).
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:
- User changes settings of plug-in. Plug-in updates its internal state and raises OnChangeParam to UI.
- 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.
- When Core needs to convert (and save) current page or all pages in a single miltipage file, it calls Convert method.
- 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).
- 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.
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:
- It must be included into "Miraplacid Publisher Transport Plug-ins" COM category (92D23852-D793-4251-83C2-9D577A779DFB), but not create it.
- It must implement IMP_TPLUGIN interface (A24B0942-EDCC-47c5-AF3C-82A6A2E4FD11) and realize _IMTD_TPlugin_Events connection point dispinterface (DD69A786-C884-410a-B27B-DECA265042C9).
- It must not register its own type library. Ready for use type library provided in imp_tplugin.dll.
- Default write-only properies docname and extension may be used in transport plug-in to capture this setting from UI.
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 inconfiguration or restored from it.
Format of this string is: "Bparam1,Lparam2,BParam3", where "B" and "L" are prefixes meaning type of parameter (BSTR and Long 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 |
ITransportHelper object |
Publisher Core calls this method when it needs to send converted file to selected location.
"object" parameter is an interface provided by Core which allows plug-in to retrieve input file name needed for save and translate strings.
|
| End |
None |
Publisher Core call this member on end of saving to let plug-in free used resources and update its state.
|
| 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.
|
_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, Number error_code, String error_message |
When some error happens during saving the text, plug-in should raise OnError event.
"error_code" provided mainly for debugging purposes, to watch this value in MTD log file; "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:
| Property |
Type |
Description |
| Source |
String |
(Read Only) 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.
|
| Method |
Parameters |
Description |
| TranslateString |
String input; returns String output |
Translates string possibly containing special tags and replaces these tags with their actual values.
|
Transport plug-in working scheme
- UI starts and loads plug-ins. It subscribes to _IMP_TPlugin_Events events interface.
- 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).
- Core creates plug-ins and subscribes to events. UI listens OnParamChange event; Core listens other events: OnError and OnProgress.
- 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).
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:
- User changes settings of plug-in. Plug-in updates its internal state and raises OnChangeParam to UI.
- In responce, UI sets appropriate Core property with TrandportParam. In result, all parameters are in sync.
Saving job cycle.
- 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.
- After that, it calls Process method with appropriate parameters. During this call, plug-ins may call TranslateString method provided by Core.
- Finally, Core calls End method.
See also:
|
|
|
