Miraplacid Text Driver Programming Manual
Contents
Miraplacid Text Driver 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 Text Driver:
- Driver components. These are system dll modules and settings files.
This is mandatory part of Text Driver.
- Core component (mtd_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 (mtd_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 Text Driver Core and Driver, they can work fine without UI.
- Rendering plug-ins. Inproc dll COM modules which performs text rendering (reconstruction)
from internal representation into particular text 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 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 Text Driver Object Model
Text Driver Core component consists of two COM objects (coclasses):
- coclass MTD (MiraplacidSE.TextDriver {B2A1B097-BA0F-45d5-918E-E3585D214DB5}). This is the main part of Text Driver.
The folowing interfaces included:
- IMTD (default interface). Includes all methods and properties which control Text Driver functionality, including plug-ins.
- _IMTDEvents (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 MTD_Register (MiraplacidSE.TextDriverRegistrator {106FEB4A-D696-4557-82CB-69BCECF76A61}).
This objects includes single interface IMTD_Register, which manages registration and verification services.
MTD_Register object will be always created and its interface will allow calling program
to verify Text Driver registration status and to register Text Driver.
MTD object will not be created successfully if trial period is expired.
Unlimited version of SDK does not contain MTD_Register coclass and object
MTD 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 Text Driver IMP Object Reference
This is a main Text Driver interface. Its IID is {D5FD471D-BAEC-4dfa-8C3C-CCD09050B3AA}.
| Property |
Type |
Description |
| PluginID |
Number |
(Read / Write) Select format plug-in ("Output Style"), sorted by alphabet.
0 - Formatted Text
1 - Plain Text
2 - Text with Layout
3 - XML
|
| PluginName |
String |
(Read / Write) More reliable method to select format plug-in ("Output Style").
The following values are valid:
"Formatted Text"
"Text with Layout"
"XML"
"Plain Text"
|
| DocumentName |
String |
(Read Only) Original name of the printed document |
| Charset |
Number |
(Read / Write) Character set (codepage number)
5 - UNICODE
437 - OEM American DOS
850 - OEM Latin-1 DOS
852 - OEM Eastern Europe DOS
866 - OEM Cyrillic DOS
932 - Japanese
936 - Chinese (Simplified")
949 - Korean
950 - Chinese (Traditional)"
1250 - ANSI Latin-1 Windows
1251 - ANSI Cyrillic Windows
1252 - ANSI Eastern Europe Windows
1257 - ANSI Baltic Windows
...etc...
|
| UnixEOL |
Number |
(Read / Write) End Of Line style
0 means "Windows" EOL style (\r\n or 0x0D, 0x0A)
1 means "UNIX" EOL style (\n or 0x0A) |
| AutoSave |
Number |
(Read / Write) 0 - interactive mode; 1 - Process and Auto-send to the specified destinations |
| Delim |
String |
(Read / Write) Delimiter string for Plain Text plug-in |
| Pages |
String Collection |
(Read only) Collection of text pages extracted |
| PluginNames |
String Collection |
(Read Only) List of installed format plug-ins (XML, Plain Text and so on) |
| 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 |
| Transport |
String |
(Read / Write) Selected Transport Plug-in names. If more than one transport plug-in selected, names should be comma delimited. |
| TransportPluginNames |
String Collection |
(Read Only) List of installed transport plug-ins (File, FTP and so on) |
| TransportParam |
VARIANT(String PluginName, String ParameterName) |
(Read / Write) Transport Plug-in Parameters
All the parameters for all plug-ins are listed below. |
| Configuration |
String |
(Read / Write) Name of the currently selected profile |
| Configurations |
String Collection |
(Read Only) List of all saved profiles, including "Defualt". |
| PrinterName |
String |
(Read Only) Name of Miraplacid Text Driver printer to use for switching to Text Driver in scripts |
| Plugin (hidden) |
IMTD_PLUGIN interface |
(Read Only) Returns interface pointer to currently used Rendering plug-in. |
| AutoSaveFromUI (hidden) |
Number |
(Write only) 0 - interactive mode; 1 - Process and Auto-save 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.
|
| 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 |
| UpdatePage |
Number n, String s |
Replace contents of nth page by s. |
| CancelJob |
None |
Cancel current Print Job |
| CancelAllJobs |
None |
Cancel all jobs for this printer |
| SaveConfiguration |
String |
Save Current Configuration under specified name |
| DeleteConfiguration |
String |
Delete Current Configuration with specified name |
| SaveAllPages |
None |
Send All through selected Transport Plug-Ins |
| Stop |
None |
Unloads plug-ins, get ready for unloading from memory. System will unload Miraplacid Text Driver core form memory with 2-5 seconds delay. We recommend you to add this method call at the end of each script. |
| SavePage (hidden) |
Number |
Save one page specified by argument (index) |
Miraplacid Text Driver Send To (Transport plug-ins) parameters
To query or modify Transport plug-in parameters, use TransportParam property of Miraplacid Text Driver object.
obj.TransportParam("File","filename")="textout_{{PAGE}}.txt"
| 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.
|
| open |
Number |
Opens result image file with post-processor.
|
| 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.
|
| setfilename |
Number |
Set it to 0 if you wish to specify filename. Set it to 1 if you Miraplacid Text Driver to use original document name as a file name.
Ignored if open=0.
|
| append |
Number |
Set it to 0 if you wish to overwrite resulting file. Set it to 1 if you wish to append current result to a previous file.
|
| pagebreak |
Number |
Set it to 1 if you wish to to separate pages from each other by pagebreak symbol (0xC).
|
| 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.
|
| setfilename |
Number |
Set it to 0 if you wish to specify filename. Set it to 1 if you Miraplacid Text Driver to use original document name as a file name.
Ignored if open=0.
|
| pagebreak |
Number |
Set it to 1 if you wish to to separate pages from each other by pagebreak symbol (0xC).
|
| 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.
|
| setfilename |
Number |
Set it to 0 if you wish to specify filename. Set it to 1 if you Miraplacid Text Driver to use original document name as a file name.
Ignored if open=0.
|
| pagebreak |
Number |
Set it to 1 if you wish to to separate pages from each other by pagebreak symbol (0xC).
|
| Printer |
| Property |
Type |
Description |
| printer |
Number |
Printer number. Depends on printers installed in your system.
Please start Miraplacid Text Driver 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.
|
| font |
Number |
1 - use default font. 0 - select custom font.
|
You can change the default font by changing the file mtdcfg.ini.
| mtdcfg.ini |
| Key |
Description |
| Facename |
String that specifies the name of the font.For example "Arial".
|
| Charset |
The possible significances of this key were described above.
|
| Strikeout |
Specifies a strikeout font if set to 1.
|
| Underline |
Specifies an underlined font if set to 1.
|
| Height |
Specifies a height for a font with a specified point size.
|
| Italic |
Specifies an italic font if set to 1.
|
| Weight |
Specifies the weight of the font in the range 0 through 1000.The following values are defined for convenience.
0 - DONTCARE
100 - THIN
200 - EXTRALIGHT
300 - LIGHT
400 - NORMAL
500 - MEDIUM
600 - SEMIBOLD
700 - BOLD
800 - EXTRABOLD
900 - BLACK
|
Except these settings, mtdcfg.ini contains redirect options for each user, saved in [redirect] section.
Miraplacid Text Driver _IMTDEvents Events Reference.
This is connection point interface which UI uses to catch printing events from Core component.
Its IID is {95204725-F17E-43c0-A56B-784D7292D28F}.
| Event |
Parameters |
Description |
| OnStartJob |
None |
Called when Core receives start job signal from driver.
|
| OnPageRendered |
Number |
Called when Core receives all text fragments for the current page and rendered it with currently selected Rendering plug-in.
|
| OnAllPagesRendered |
None |
Called when Core receives end job signal from driver and rendered all job pages.
|
| 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 is a name of transport plug-in - it reflects sending progress for
this particular plug-in.
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 page ID 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 Text Driver IMTD_Register Object Reference.
When evaluation period is expired, object of the main interface (IMTD) will not be created
successfully.
Application should use IMTD_Register interface to register Text Driver.
Its IID is {F33D6725-86D8-401b-A5B9-9331DCE23125}.
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 - Text Driver is registered.
- 2 - Text Driver 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 Text Driver. 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 Text Driver 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 AutoSave property is in false state
or by user when he clicks on Text Driver icon
on Desktop or Programs folder.
- UI loads MTD object and obtains IMTD 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.
- OnPageRendered: This event will be generated for every page of the job during rendering process even if actual print
job was completed. On this event, its possible to get the page with Pages Core property and update UI state.
- OnAllPagesPrinted: This is informational event which allows UI to update its internal state
(and interface elements like SaveAll button).
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 can change current page. UI shall call UpdatePage method with new contents of the page.
- 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:
|
