Miraplacid Publisher Programming Manual
Contents
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 this guide are written in VB 6.0 for simplicity.
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.
- Format plug-ins. Inproc dll COM modules which performs graphics data conversion
from internal into particular format.
Core component manages these modules.
- Transport plug-ins. Inproc dll COM 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 Format 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 {60FDE45D-BB59-4789-AEA4-80632F03B926}.
| 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.
|
| Configurations |
String Collection |
(Read Only) List of all saved profiles, including "Defualt". |
| Configuration |
String |
(Read / Write) Name of the currently selected profile |
| 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 ParameterName) |
(Read / Write) Format Plug-in Parameters
All the parameters for all plug-ins are listed below.
|
| 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.
|
| 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 the 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 |
| PrinterName |
String |
(Read Only) Name of Miraplacid Publisher printer to use for switching to Publisher in scripts |
| 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 |
| 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 |
String |
Save Current Configuration under specified name |
| DeleteConfiguration |
String |
Delete Configuration with specified name |
| 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.
|
| SendPage (hidden) |
None |
This method allows UI to save particular page. The page must be previously prepared with PreparePage method.
|
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 |
| scalepercent |
Number |
0 - scale size in pixels, 1 - scale size in percents |
| scaleconstrain |
Number |
1 - constrain scaling proportions, 0 - not |
| 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, 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 |
flip image vertical |
| flipv |
Number |
flip image horizontal |
| 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, 1 - force grayscale |
| invert |
Number |
invert image colors |
| originalname |
Number |
do not replace {{PAGE}} with page number for the first page |
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("multipage")=0
| BMP |
| Property |
Type |
Description |
| multipage |
Number |
0 = regular mode. 1 = multipage mode
(All the pages will be glued into a single enormous image.)
|
| output |
Number |
Output Format. 0 = Color (RGB) 24 bit per pixel.
1 = Grayscale 8 bit per pixel.
|
| JPG |
| Property |
Type |
Description |
| multipage |
Number |
0 = regular mode. 1 = multipage mode
(All the pages will be glued into a single enormous image.)
|
| quality |
Number |
Output Format. 0 = 100% quality, 1 = 95% quality and so on.
18 = 10% quality.
|
| PDF |
| Property |
Type |
Description |
| multipage |
Number |
0 = single PDF per page. 1 = multipage PDF (recommended)
|
| quality |
Number |
(Read / Write) Output Format. 0 = 100% quality, 1 = 95% quality and so on.
18 = 10% quality.
|
| title |
String |
PDF document Title
|
| creator |
String |
PDF document Creator
|
| author |
String |
PDF document Author
|
| PNG |
| Property |
Type |
Description |
| multipage |
Number |
0 = regular mode. 1 = multipage mode
(All the pages will be glued into a single enormous image.)
|
| output |
Number |
Output Format. 0 = Color (RGB) 24 bit per pixel.
1 = Grayscale 8 bit per pixel.
|
| compression |
Number |
0 = No Compression. 1 = Default Compression. 2 = Fast Compression.
3 = Best Compression (recommended)
|
| TGA |
| Property |
Type |
Description |
| multipage |
Number |
0 = regular mode. 1 = multipage mode
(All the pages will be glued into a single enormous image.)
|
| output |
Number |
Output Format. 0 = Color (ARGB) 32 bit per pixel.
1 = Color (RGB) 24 bit per pixel.
2 = Color (RGB) 16 bit per pixel.
3 = Grayscale 8 bit per pixel.
|
| TIFF |
| Property |
Type |
Description |
| multipage |
Number |
0 = regular mode, single TIFF file per page.
1 = multipage mode (multi-page TIFF will be created)
|
| output |
Number |
Output Format.
0 = CCITT Group 4 fax encoding.
1 = CCITT Group 3 fax encoding
2 = CCITT Group 3 (Modified Huffman)
3 = 24 bit RGB (no compression)
4 = 24 bit RGB (packbits)
5 = Grayscale (no compression)
6 = Grayscale
7 = Black/White (no compression)
8 = Black/White
|
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. {{PAGE}}, {{JOB}}, {{IDENTITY}}, {{DATE}}, {{TIME}} supported.
|
| filename |
String |
Destination File Name. {{PAGE}}, {{JOB}}, {{IDENTITY}}, {{DATE}}, {{TIME}} supported.
|
| setfilename |
Number |
Set it to 1 if you wish to specify filename. Set it to 0 if you Miraplacid Publisher to use original
document name as a file name.
|
| 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. {{PAGE}}, {{JOB}}, {{IDENTITY}}, {{DATE}},
{{TIME}} 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.
|
| put |
Number |
0 = use POST method. 1 = use PUT method.
|
| user |
String |
username.
|
| password |
String |
password.
|
| Printer |
| Property |
Type |
Description |
| printer |
Number |
Printer number. Depends on printers installed in your system.
Please start Miraplacid Publisher and check Printer drop-down for Send To: Printer.
Default printer will have index 0, others will have further numbers, as shown in drop-down box.
|
| 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 |
String |
Called when Core prepared a page for displaying in responce to PreparePage
method call.
String 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 page, 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.
Page is a number of page currently in progress, and 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.
|
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.
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.
See also:
|
