Miraplacid Text Driver SDK 2008: Programming

Property	Type	Description
Format	String	(Read / Write) Selects format plug-in ("Output Style"). PLug-ins should be named by their internal (short) names. The following values are valid: Formatted - "Formatted Text" TWL - "Text with Layout" XML - "XML" RSS - "RSS" Plain - "Plain Text"
FormatParam	VARIANT(String PluginName, String ParameterName)	(Read / Write) Format Plug-in Parameters. All the parameters for all plug-ins are listed below.
FormatPluginNames	String Collection	(Read Only) List of installed format plug-ins (XML, Plain Text and so on)
Transport	String	(Read / Write) Selected Transport Plug-in names. If more than one transport plug-in selected, names should be comma delimited. The following values are valid: Clipboard, FTP, File, HTTP. Mail, Printer.
TransportParam	VARIANT(String PluginName, String ParameterName)	(Read / Write) Transport 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)
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
PageBreak	Number	(Read / Write) 1 - insert page break symbols (0xc) between pages; 0 - don't.
TotalPages	Number	(Read Only) Total estimated amount of pages in current print job
RenderedPages	Number	(Read Only) Amount of rendered pages in current print job
DocumentName	String	(Read Only) Original name of the printed document
JobStatus	Number	(Read Only) 0 - Created, 0001b - Opened, 0010b - Printed, 0100b - RequestedPagePrepared, 1000b - Aborted
Printer	String	(Read / Write) Name of the currently selected printer
Printers	String Collection	(Read Only) List of all printers in Text Driver collection.
RedirectPrinter	String	(Read / Write) Name of the currently selected printer for redirection. If empty, no redirection will be performed.
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.
UnicodePrefix	Number	(Read / Write) 1 - insert Unicode prefix (0xfeff) before Unicode content; 0 - don't.
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
GetPage	Number, returns String	Get a rendered page by index.
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	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
SavePage	Number	Save one page specified by argument (index)
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.

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 resulting text 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.
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.
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	String	Printer name. Can be a real printer name or "Default" string which means default printer.
font	String	Font family name to use in print output or "Default" string to not to use any specific font when printing.
charset	Number	Numeric code of character set or DEFAULT_CHARSET value (equal to 1).
weight	Number	Weight of characters to be used in print output. The following values will be accepted: 0 - DONTCARE 100 - THIN 200 - EXTRALIGHT 300 - LIGHT 400 - NORMAL 500 - MEDIUM 600 - SEMIBOLD 700 - BOLD 800 - EXTRABOLD 900 - BLACK
height	Number	Height of characters to be used in print output.
italic	Number	Specifies an italic font if set to 1.
strikeout	Number	Specifies an strikeout font if set to 1.
underline	Number	Specifies an underline font if set to 1.
Mail
Property	Type	Description
mail	String	A set of email addresses of mail recipients, separated by semicolon.
subject	String	Email subject.
message	String	Email message body. This value will be used as a header before actual email content (printed pages). Text Driver will place this message, separator line, then printed pages.
Clipboard
Property	Type	Description
open	Number	Opens resulting text 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.

Plain Text
Property	Type	Description
delim	String	Delimiter which will be used to separate text boxes during rendering.
Formatted Text
Property	Type	Description
margins	Number	1 - use printer margins in text rendering (at top and left side); 0 - don't.
space	Number	Value in percents of average symbol width (10 - 100).
Text with Layout
Property	Type	Description
margins	Number	1 - use printer margins in text rendering (at top and left side); 0 - don't.
XML
Property	Type	Description
optimize	Number	1 - merge textboxes into whole words; 0 - don't.
space	Number	Value in percents of average symbol width (10 - 100).
docname (hidden, Write only)	String	This parameter is used by Core component to feed plug-ins with document name to allow them use document name as a part of document's body. This parameter has not appropriate entry in Layout property and will not be saved in registry as an item of configuration.
RSS
Property	Type	Description
link	String	Link attribute of RSS channel (document).
description	String	Description attribute of RSS channel (document).
br	Number	1 - add <BR> tag to the end of description lines; 0 - don't.
docname (hidden, Write only)	String	This parameter is used by Core component to feed plug-ins with document name to allow them use document name as a part of document's body. This parameter has not appropriate entry in Layout property and will not be saved in registry as an item of configuration.

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. The job is removed from MTD.
OnRewindJob	None	Called instead of OnCancelJob when SendAll finished with errors. The job is not destroyed and still active.
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 is a name of transport plug-in - it reflects sending progress for this particular plug-in. 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.
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.
OnPageSaving	Number	Called when Core saves particular page. Paramtere is a number of page. UI may use this value to update its page number.

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.

1. 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.
2. UI loads MTD object and obtains IMTD 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). 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.

4. 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. Together with this event, Core sends OnChangePrinter (for printer name and configuration update) and OnSetDocName (for transports update).
   
5. 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.
   
6. 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.

8. 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.
9. User can change configurations, create new configurations and delete existing (except Default). When User Interface changes configuration, it shall reload all settings.
10. User can save current page. UI shall call SendPage method.
11. User can change current page. UI shall call UpdatePage method with new contents of the page.
12. 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.
13. User can cancel the job. UI must call CancelJob method. In response, Core generates OnCancelJob event.
14. 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 Text Driver Rendering plug-ins.

Rendering plug-ins are Text Driver components intended for text pages creation from text boxes collected by driver engine.
Rendering 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 Text Driver Rendering Plug-ins" COM category (844F0FA2-6FCF-4DDC-8028-EA9B2678D549), but not create it.
• It must implement IMTD_FPLUGIN interface (769FF02D-AD79-4b0e-9DC7-0CD85C896520) and realize _IMTD_FPlugin_Events connection point dispinterface (79EADD1F-C31C-44ef-8287-267CB278E60B).
• It must not register its own type library. Ready for use type library provided in imtd_plugin.dll.

IMTD_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.
Name	String	(Read Only) Plug-in name for internal use.
Descirption	String	(Read Only) Plug-in name use in user interface or so (full name).
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
StartDoc	no parameterts; returns String	MTD Core call this member when it performs SaveAll procedure (saves whole document). This will happen after all rendering has completed. Plug-in should return document header to Core. If document has no special header, plug-in should return E_NOTIMPL.
EndDoc	no parameterts; returns String	MTD Core call this member when it performs SaveAll procedure (saves whole document). This method will be called directly after StartDoc. Plug-in should return document footer to Core. If document has no special footer, plug-in should return E_NOTIMPL.
StartPage	Number DPI, Number Xsize, Number Ysize	MTD Core call this member before rendering each page. DPI is page resolution, XSize is X dimension in "dots", Ysize is Y dimension.
Add	Number X0, Number X1, Number Y0, Number Y1, String text, String font	With this method, MTD Core feeds rendering plug-in with textboxes for rendering. X0, X1, Y0, Y1 are textbox coordinates, "text" is a text itself, "font" is a font name.
Render	no parameterts; returns String	MTD Core call this member when it finishes adding all textboxes of the page to rendering plug-in. Plug-in should render the text and return it to Core.

_IMTD_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.

Rendering plug-in working scheme

1. UI starts and loads plug-ins. It subscribes to _IMTD_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.
3. Core creates plug-ins too, but it does not subscribe to events.
4. Core gets Layout property. According to Layout parameters, it reads saved values from configuration (registry) and sets as Values of plug-in.

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:

5. User changes settings of plug-in. Plug-in updates its internal state and raises OnChangeParam to UI.
6. 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.

7. When Core has complete page to render, it calls StartPage method.
8. After that, it feeds plug-in with all textboxes belonging to this page.
9. Finally, Core calls Render method and gets rendered text to its storage.
10. If Core performs SaveAll procedure, after rendering all pages, it calls StartDoc and EndDoc, inserts these pages into its internal storage and save its contents to chosen destinations.

Miraplacid Text Driver Transport plug-ins.

Transport plug-ins are Text Driver components intended saving rendered text pages 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 Text Driver Transport Plug-ins" COM category (3B71E527-6CFD-41d3-ABDF-280EF6BB077C), but not create it.
• It must implement IMTD_TPLUGIN interface (515485DA-9BDB-4552-9D00-FA5C11A9FB6C) and realize _IMTD_TPlugin_Events connection point dispinterface (05EBA977-C40C-47f7-9A9E-6CED35615557).
• It must not register its own type library. Ready for use type library provided in imtd_tplugin.dll.
• Default write-only property docname may be used in transport plug-in to capture this setting from UI.

IMTD_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.
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.
Method	Parameters	Description
Start	None	MTD Core call this member when it begins saving text page(s). Plug-in may update its internal state and prepare resources.
Process	IRenderedCollection coll, BOOL saveall, Number page_id	MTD Core calls this method once regardless of number of pages to save. "coll" parameter is an interface provided by Core which allows plug-in to retrieve pages from Core storage. "saveall" = true - save all pages into destination; otherwise plug-in must use page_id to retrieve particular page. "page_id" is current page number for save if saveall is false.
End	None	MTD Core call this member on end of saving to let plug-in free used resources and update its state.

_IMTD_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).

IRenderedCollection Core interface:

Property	Type	Description
Count	Number	(Read Only) Number of pages in document.
Unicode	Number	(Read Only) Returns TRUE if the current codepage is Unicode and Unicode prefix option is ON. Plug-ins should use this property before saving all the pages, i.e. should send Unicode prefix (0xfeff) into its output stream before all other content.
Method	Parameters	Description
Item	Number index; returns VARIANT	With this method, plug-in receives page content identified by "index". Methods makes all necessary processing with page (end-of-line conversion, translation into needed codepage and page breaks insertion) and provides a result as a VARIANT containing one-dimension SAFEARRAY of bytes.
GetItem	Number index; returns String	In some cases, plug-in does not need to have processed result. In this case, it should call GetItem method to get just Unicode string of rendered page. Examples of such plug-ins are Clipboard and Printer.
ItemSize	Number index; returns Number	Some plug-ins need to know page size before sending actual content to destination because transport protocol requires size to be indicated before body; for example, HTTP plug-in. This method returns size of particular page in bytes, taking into account all necessary transformations.
TranslateString	String input, Number page_id; returns Number page_flag (actually fills pointer to long) and String output (out, retval) value	Translates string possibly containing special tags and replaces these tags with their actual values. page_id provided by caller because several plug-ins may work with different pages simultaneously.

Transport plug-in working scheme

1. UI starts and loads plug-ins. It subscribes to _IMTD_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.
3. Core creates plug-ins and subscribes to events. UI listens OnParamChange event; Core listens other events: OnError and OnProgress.
4. Core gets Layout property. According to Layout parameters, it reads saved values from configuration (registry) and sets as Values of plug-in.

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:

5. User changes settings of plug-in. Plug-in updates its internal state and raises OnChangeParam to UI.
6. In responce, UI sets appropriate Core property with TrandportParam. In result, all parameters are in sync.

Saving job cycle.

7. 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.
8. After that, it calls Process method with appropriate parameters. During this call, plug-ins may call TranslateString method provided by Core.
9. Finally, Core calls End method.

See also:

• About Miraplacid Text Driver 2008 SDK
• Miraplacid Text Driver 2008 SDK: Installation
• Miraplacid Text Driver 2008 SDK: SetupMaker
• Miraplacid Text Driver 2008 SDK: Installation Component
• Miraplacid Text Driver 2008 SDK: Programming Guide
• Miraplacid Text Driver SDK 2008 Main Page