SDK Programming Guide

Property	Type	Description
Value	VARIANT (String Name)	(Read / Write) All the Text Driver properties. This is Default Property. Meaning, it could be referred as obj("property_name") as well as obj.Value("property_name") All the parameters are listed below.
DocumentName	String	(Read Only) Original name of the printed document
TotalPages	Number	(Read Only) Total estimated amount of pages in current print job
RenderedPages	Number	(Read Only) Amount of rendered pages in current print job
TotalJobs	Number	(Read Only) Number of printed documents spooled in Text Driver and waiting for processing
JobProperty	VARIANT (String Name)	(Read Only) Current job various properties. All the parameters are listed below.
AutoSave	Number	(Read / Write) 0 - interactive mode; 1 - Process and Auto-send to the specified destinations
Identity	Number	(Read / Write) Identity value to replace {{IDENTITY}} tag
Format	String	(Read / Write) 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.
FormatParamNoCheck	VARIANT(String PluginName, String ParameterName)	(Write Only) Format Plug-in Parameters. Use this option to set only appropriate property, without updating plug-in user interface and checking value. This option is useful when you need to set all options in a batch, and some options affect others. After all options are set, call FormatCheckSettings to update plug-in state correctly.
FormatPluginNames	String Collection	(Read Only) List of installed format plug-ins (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.
TransportParamNoCheck	VARIANT(String PluginName, String ParameterName)	(Write Only) Transport Plug-in Parameters. Use this option to set only appropriate property, without updating plug-in user interface and checking value. This option is useful when you need to set all options in a batch, and some options affect others. After all options are set, call TransportCheckSettings to update plug-in state correctly.
TransportPluginNames	String Collection	(Read Only) List of installed transport plug-ins (File, FTP and so on)
Printer	String	(Read / Write) Name of the currently selected printer
Printers	String Collection	(Read Only) List of all printers in 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.
UILoaded (hidden)	Number	(Read / Write) 0 - UI not loaded; 1 - UI loaded. UI should set this value when it loaded and initialized and clear (set to 0) on unload. When you read from this property, it returns number of UIs loaded.
UILoadedWithEvents (hidden)	Number	(Write only) 0 - UI not loaded; 1 - UI loaded. UI should set this value when it loaded and initialized and clear (set to 0) on unload. UI chould use this value if it needs to receive all necessary print job events (StartJob, StartPage, EndJob) even if it started in the middle of print job processing (see UI working scheme).
Listeners (hidden)	Number	(Read only) Number of processes/modules subscribed to events. Text Driver may work with several UIs and ordinary listeners. UIs, in difference of listeners, registers themselves using UILoaded.
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. Returns immediately.
CancelJobWait	None	Cancel current Print Job. Waits until current job will be cancelled and the new one will be opened, if any.
CancelAllJobs	None	Cancel 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 page_number	Send particular page through selected Transport Plug-Ins. Returns immediately.
SaveAllPages	None	Send All through selected Transport Plug-Ins. Returns immediately.
SavePageWait	Number page_number	Send particular page through selected Transport Plug-Ins. Waits until page will be saved.
SaveAllPagesWait	None	Send All through selected Transport Plug-Ins. Waits until all pages will be saved.
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.
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.
Redirect	String printer, String document	This method provides an alternative way to print a copy of print job to another printer. Unlike RedirectPrinter property, which allows to set printer for automatic redirect, this method may be used in scripts or external programs when additional analysis needed to decide, redirect this job to that printer or not. Returns immediately. "Document" parameter allows you to provide alternative name of redirected print job. Ignored if NULL or empty string.
RedirectWait	String printer, String document	The same as Redirect method, but waits until redirect process will be completed.
LoadUI	None	Loads user interface component if it is not already loaded.
UnloadUI	None	Unloads user interface component, if it supports OnUnload event.
GetEMFPage	Number index, String filename	Extracts a page referred by index from current job and saves it as a file "filename" in EMF format. Caller is responsible for deleting this file. This method works only with print jobs in EMF format. Special tags supported.
SetEMFPage	Number index, String filename	Assigns a file "filename" to be a content of page referred by index. File must be in EMF format. Caller is responsible for deleting this file. File must not be deleted before the job is redirected. To set page back to original content from print job spool file, set filename to empty string or NULL value. This page manipulation will affect only EMF print job intended for redirect to another printer, not text job image for save. This method works only with print jobs in EMF format. Special tags supported.

All these properties accessible via default "Value" property:
obj.Value("Charset") = 1250
or just
obj("Charset") = 1250

Property	Type	Description
Charset	Number	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	End Of Line style 0 means "Windows" EOL style (\r\n or 0x0D, 0x0A) 1 means "UNIX" EOL style (\n or 0x0A)
PageBreak	Number	1 - insert page break symbols (0xc) between pages; 0 - don't.
UnicodePrefix	Number	1 - insert Unicode prefix (0xfeff) before Unicode content; 0 - don't.
REMFMargins	Number	Value of redirection margins enumeration: 0 - Auto-compensated, 1 - Auto-normal, 2 - Custom.
REMFTop	Number	Value of top custom margin.
REMFBottom	Number	Value of bottom custom margin.
REMFLeft	Number	Value of left custom margin.
REMFRight	Number	Value of right custom margin.
REMFCompatibility	Number	Turn on/off Save as Image mode for EMF redirection
REMFConstrain	Number	Turn on/off constrain proportions for EMF redirection
RTextFont	String	Name of font which will be used for text redirection
RTextSize	Number	Text size which will be used for text redirection
RTextWeight	Number	Font weight (100 - 900) which will be used for text redirection
RPrinterSettings	ByteArray	One-dimentional Safearray of bytes containing printer settings (DEVMODE). To use default printer settings, set this value to the empty Safearray of bytes.

All these properties accessible via "JobProperty" property:
var job_status = obj.JobProperty("Status")

Property	Type	Description
JobID	Number	System print job ID for the current job. 0 if no active job.
Status	Number	Current job status. Binary flags (ORed): 0 - No print jobs currently in progress. 1 - Started - initial state just after StartJob event from driver. 2 - Opened for rendering. This may happen just after the job will be created, if not other jobs are in Text Driver queue, or after it will be printed, when current job will be saved and cancelled. 4 - Printed - printer driver completed all operations with current job. After that, the job may still not be available for save, it must be Opened and Rendered first. 8 - Rendered - ready for save. All the job contents are processed by selected rendering plug-in.
Resolution	Number	Resolution for the current job, in DPI. 0 if no active job.
Printer	String	Printer name for the current job. Empty string if no active job.
Document	String	Document name for the current job. Empty string if no active job.
Format	String	Data format for the current job - TEXT / NT EMF 1.006 / NT EMF 1.007 / NT EMF 1.008. Empty string if no active job.
SpoolFile	String	Spool file name with full path for the current job. Empty string if no active job.
SepFile	String	Separator file name with full path for the current job. Empty string if no active job or if no separator page applied to the job.

File
Property	Type	Description
path	String	Destination File Path. Special tags supported.
filename	String	Destination File Name. Special tags 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. Special tags supported. Ignored if open=0.
param	String	additional parameters for post-processor. Special tags supported. 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.
wait	Number	Set it to 1 if you wish to wait application termination before continue. Ignored if open=0.
FTP
Property	Type	Description
url	String	Destination FTP directory URL. Special tags supported.
file	String	Destination File Name. Special tags supported.
passive	Number	0 = FTP passive mode OFF. 1 = FTP passive mode ON.
user	String	FTP server username.
password	String	FTP server password.
HTTP
Property	Type	Description
url	String	Destination HTTP URL. Special tags supported.
file	String	Destination File Name. Special tags supported.
put	Number	0 = use POST method. 1 = use PUT method.
user	String	username.
password	String	password.
Printer
Property	Type	Description
printer	String	Printer name. Can be a real printer name or "Default" string which means default printer.
settings	ByteArray	One-dimentional Safearray of bytes containing printer settings (DEVMODE). To use default printer settings, set this value to the empty Safearray of bytes.
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. Special tags supported.
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. Special tags supported.
attach	Number	Set it to 1 if you wish to send result as an attachment.
filename	String	Name of file which will be used as an attachment. Special tags supported.
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. Special tags supported. Ignored if open=0.
param	String	additional parameters for post-processor. Special tags supported. Ignored if open=0.
wait	Number	Set it to 1 if you wish to wait application termination before continue.

Plain Text (Plain)
Property	Type	Description
delim	String	Delimiter which will be used to separate text boxes during rendering. This value may include the following escaped special characters: \s (whitespace), \t, \r, \n, \f, \\ (backslash itself) and \xnnnn (nnnn is a hexadecimal code of Unicode symbol).
lheight	Number	Vertical rendering mode: 0 = automatic, 1 = fixed.
ilgap	Number	Value of inter-line gap, in tenths of percents, it lheight = 0.
heightval	Number	Line height in pixels, if lheight = 1.
Formatted Text (Formatted)
Property	Type	Description
margins	Number	1 - use printer margins in text rendering (at top and left side); 0 - don't.
usespaces	Number	1 - use whitespace strings from document; 0 - don't.
right	Number	1 - use right alignment rendering; 0 - don't.
char	Number	Character width calculation option: 0 - "Automatic, each page", 1 - "Automatic, first page", 2 - "Fixed value".
cwidth	Number	Manual character width if char option is set to 2.
lheight	Number	Vertical rendering mode: 0 = automatic, 1 = fixed.
ilgap	Number	Value of inter-line gap, in tenths of percents, it lheight = 0.
heightval	Number	Line height in pixels, if lheight = 1.
Text with Layout (TWL)
Property	Type	Description
margins	Number	1 - use printer margins in text rendering (at top and left side); 0 - don't.
usespaces	Number	1 - use whitespace strings from document; 0 - don't.
lheight	Number	Vertical rendering mode: 0 = automatic, 1 = fixed.
ilgap	Number	Value of inter-line gap, in tenths of percents, it lheight = 0.
heightval	Number	Line height in pixels, if lheight = 1.
XML (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).
RSS-Atom (RSS)
Property	Type	Description
author	String	Author attribute of RSS channel/Atom feed (document).
link	String	Link attribute of RSS channel/Atom feed (document).
description	String	Description attribute of RSS channel/Atom feed (document).
br	Number	1 - add <BR> tag to the end of description lines; 0 - don't. HTML content type for Atom feed.

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.
OnSavingEvent	Number event	Called on start and finish of various saving and processing stages. This event lets receiver know exactly when and which process is going on. The following codes suported: 1 - Save individual page started 2 - Save document started 3 - Redirect started 4 - Save individual page ended 5 - Save document ended 6 - Redirect ended
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 "Redirect" which reflects the state of redirection to another printer. 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: 1 - "Cannot get transport parameter" 2 - "Cannot select transport" 3 - "Cannot put transport parameter" 4 - "Cannot get format parameter" 5 - "Cannot select format plug-in" 6 - "Cannot put format parameter" 7 - "Invalid printer name" 8 - "Cannot change printer" 9 - "Cannot save configuration" 10 - "No transports selected" 11 - "Invalid format plug-in name" 12 - "Sorry, you are not allowed to print to this printer" 13 - "Invalid page number" 14 - "Trial period expired" 15 - "Cannot start driver engine" 16 - "There is no job ready for save" 17 - "Busy: processing is in progress" 18 - "Empty job - will be cancelled automatically" 19 - "User Interface component already loaded" 20 - "User Interface component is not loaded" 21 - "Transport Start failed" 22 - "Transport Process failed" 23 - "Transport End failed" 24 - "Redirect: Cannot open printer" 25 - "Redirect: OpenSpoolFile" 26 - "Redirect: CreateFileMapping" 27 - "Redirect: Malformed Spool File" 28 - "Redirect: StartDoc" 29 - "Redirect: Printer is not ready" 30 - "Redirect: ReadFile" 31 - "Redirect: WritePrinter" 32 - "Redirect: UnderWrite" 33 - "Redirect: Create Printer Font" 34 - "Redirect: GetTextMetrics" 35 - "Send thread initialization error" 36 - "Cannot set value" 37 - "Cannot save EMF page" 38 - "Cannot load EMF page" 39 - "Job is not in EMF format" 40 - "Unknown value name" 41 - "Stuck job - will be cancelled automatically" 42 - "Cannot set redirect printer to itself" 0x100 - Transport plug-ins errors
OnPageSaving	Number	Called when Core saves particular page. Parameter is a number of page. UI may use this value to update its page number.
OnAddRemovePrinter	Number	Core monitors printers add/remove operations and default printer change in the system. When this happen, it generates this event to let UI update lists of printers. In responce to this event, UI must update its own printer lists and send update signal to its set of transport plug-ins to allow them update their printer lists, by calling CheckSettings method with appropriate parameter. Parameter may have the following values: 0 - Default printer changed. 1 - Some printer added/removed, not from MTD family and not redirect printer. 2 - Some printer from MTD family added/removed. 3 - Redirect printer removed.
OnSettingChanged	String target, String property, Variant value	When some of clients connected to particular Core object changes a property of this object, Core will broadcast this event to all its listeners. For Core properties, target will be "Core", for plug-ins - plug-in name. Other parameters are property name and its new value. Using this mechanism, it is possible to use Text Driver with several UIs or other listeners, each will always have actual set of property values. Special case of property is a "Printer" value. It changes when Core receives print job for different printer or after initial configuration load. UI must re-read all the configuration from Core. If property changed to its current value, event will be sent with empty Variant. Please, note that client (UI) initiated the change will receive this event as well.
OnSettingsChangeFailed	String target, String property	If some configuration parameter has been changed incorrectly, or change in one parameter changes another settings, Core fires this event. In responce to this event, UI must reload apporpriate porperty.

Miraplacid 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}.
Examples of registration utility are located at examples.vb\register and examples.net\MTD_SE_Reg folders at this package.

Property	Type	Description
Valid	Number	(Read Only) May be used to examine current evaluation state. Has the following values: <=0 - Internal error happened in verification code. This could be caused by corrupted .key file, wrong permissions of .key file, etc. 1 - Text Driver is registered. 2 - Text Driver is unregistered but trial period is not expired. 3 - Trial periond is expired.
Users	String Collection	(Read / Write) List of users currently allowed to print to Text Driver. Implemented in Terminal Server version only.
UserLicenses	Number	(Read Only) Maximum number of end user licenses. Implemented in Terminal Server version only.

Method	Parameters	Returns	Description
SetLicense	String RegName, String Keycode	Number	This method is intended for registering Text Driver. Application must provide Registration Name and Keycode generated by Miraplacid to this method. Resulting value is 1 if registration succeeded, 0 if not.
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.net\MTD_SE_UI folder of SDK package.

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). This property counts active UIs, and, if UI was loaded and the last UI sets UILoaded=0, core will save configuration automatically.
   When Core launches UI, it looks for "WaitUILoaded" parameter in its registry folder (HKLM).
   
   If WaitUILoaded = 0 (default value), Core does not wait for UI to be loaded. So, when UI will be ready to listen events, it will appear in the middle of print job (OnStartJob + some page or whole job events may be missed).
   And, even if user starts UI from Desktop, it may connect to Core with current print job already waiting for user input (save or cancel).
   To avoid this situation and get current status correctly, there are two possibilities exists:
   • Get the current job status from core before subsribing to events, as did in .Net UI example. This is the most correct method.
   • Use UILoadedWithEvents = 1 construction. This property will feed UI with all needed events for current job automatically, if Core has active job.
     This is the most simple method, but it has one side-effect: if you use several applications listens events from Core, all them will receive print job events missed by this UI. This is the only way for applications written in languages like VB, which creates objects and subscribes to events in one operation (Dim WithEvents).
     In this case, you need to set UILoadedWithEvents right after object creation.
   We recommend to use this method for UIs intended for interactive job with user.
   
   If WaitUILoaded = 1, Core waits UI to be loaded (on StartJob) for 60 seconds maximum, then continues job processing. This method is convenient for UIs which perform job data processing in automatic mode, without significant user intervention.
   UI should use any method of events subscription and UILoaded=1 and it will not miss any events from Core.
   If you wish to use this mode, do not forget to set WaitUILoaded parameter to 1 in your installer.

Further steps (4 - 6) make an event-driven loop.
Core generates events in two modes: syncronous and asyncronous. To control this mode, installer may set "AsyncEvents" parameter in MTD registry folder (HKLM).
When Core users asyncronous events mode, it sends events from separate thread and does not wait for UI to return. So, if your UI performs some processing on events (not just mirror Core state), we recommend you to use asyncronous mode - the printing process will be faster. Core may collect print jobs with its maximal speed, and UI will process them with its own speed.
But, please, be careful when your UI works in asyncronous mode and Core is in autosave mode. If your UI slower than Core and it makes some actions with print job (getting/setting pages, saving particular pages/all pages, etc), these actions in autosave mode may affect wrong print job because in autosave mode Core does not wait the job to be calcelled from UI - it saves a job automatically and get the next one from queue.
In this case, you need to ensure that Core is not in autosave mode.

4. OnStartJob: On this event UI may prepare internal structures for a new job 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).
   
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.

7. User can change settings. Appropriate Core properties must be set by UI. During this process, OnError event might be raised in response to incorrect property change. OnSettingChanged event will be received by UI, with empty Variant value if no real change made, and OnSettingChangeFailed on attenpt to set invalid value. So, UI will always receive an event after each property change and it will help it to update internal change state accordingly even if used in asyncronous mode.
8. User can change active printer, save its configuration for current user or for all users.
9. User can save current page. UI shall call SendPage method.
10. User can change current page. UI shall call UpdatePage method with new contents of the page.
11. 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 saving is done. On this event, UI must get ready for the next job.
12. User can cancel the job. UI must call CancelJob method. In response, Core generates OnCancelJob event.
13. During saving process, Core will generate OnSavingEvent, OnPageSaving and OnProgress events or OnError if some error happened.

At any time, Core may send OnAddRemovePrinter event if some printer configuration changed in the system.
Dependent from this event argument, UI should take appropriate measures - reload printer lists, configuration, etc.

Miraplacid 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 (listed in Layout) will 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.
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 in configuration or restored from it. Format of this string is: "Bparam1,Lparam2,EParam3", where "B", "L" and "E" are prefixes meaning type of parameter (BSTR, Long and Encrypted BSTR, which will be saved in encrypted form and decrypted on load from registry, accordingly). Parameter names should be separated by commas. Spaces are not allowed.
Extension	String	(Read Only) File extension corresponding current rendering plug-in, without leading period, i.e. "xml", "rss".
Method	Parameters	Description
StartDoc	Number DPI; returns String	MTD Core call this member when it performs SaveAll procedure (saves whole document). DPI is print job resolution. 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 PageNo, Number Xsize, Number Ysize	MTD Core call this member before rendering each page. PageNo is page number (0-based), 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.
CheckSettings	no parameterts; returns nothing	Call this method after a series of ValueNoCheck done to perform values (mutual) check and update plug-in UI state.
InitSettings	no parameterts; returns nothing	Core calls this method when there is no configuration for current printer loaded. Plug-in must update its internal settings and UI.

_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 (using ValueNoCheck property and calls CheckSettings).
3. Core creates plug-ins too and subscribes to events (OnChangeParam). Using this mechanism, plug-ins may have special parameters which will be changed dynamically and will be supported by Core as a part of configuration and will be saved in registry.
4. Core gets Layout property. According to Layout parameters, it reads saved values from configuration (registry) and sets as Values of plug-in (using ValueNoCheck property and calls CheckSettings). If configuration for current printer does not exist, Core calls InitSettings.

Remark: UI and Core may start each other, but the final situation does not change: Core reads settings and sets plug-in properties first, then UI reads these properties and sets them to its "own" plug-ins.
There are two sets of plug-ins exists in the scheme, because UI and Core are separate processes.

Interactive job cycle:

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 saves its contents to chosen destinations.
11. If some "dynamic" parameter will be changed during working process, plug-in will fire OnChangeParam event. Core will broadcast this event to all subscribers and save it in configuration.

Miraplacid 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.
ValueNoCheck	Variant	(Write Only) The same as Value, but does not check value itself or against other values and does not update UI. Use to prevent update relative settings in a wrong order. When all the settings updated, call CheckSettings method.
Name	String	(Read Only) Plug-in name (short).
Layout	String	(Read Only) This string contains a list of properties (Values) which should be saved in configuration or restored from it. Format of this string is: "Bparam1,Lparam2,EParam3", where "B", "L" and "E" are prefixes meaning type of parameter (BSTR, Long and Encrypted BSTR, which will be saved in encrypted form and decrypted on load from registry, accordingly). Parameter names should be separated by commas. Spaces are not allowed.
Method	Parameters	Description
Start	IRenderedCollection coll	MTD Core call this member when it begins saving text page(s). Plug-in may update its internal state and prepare resources. "coll" parameter is an interface provided by Core which should be used to retrieve useful information or call TranslateString.
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	IRenderedCollection coll	MTD Core call this member on end of saving to let plug-in free used resources and update its state. "coll" parameter is an interface provided by Core which should be used to retrieve useful information or call TranslateString.
CheckSettings	Number	Call this method with parameter = 0 after a series of ValueNoCheck done to perform values (mutual) check and update plug-in UI state. Other values of parameter is for plug-ins which deals with printers. If some plug-in will not need this information, it may ignore calls with values other than 0 and return immediately. If parameter = 1 - default printer changed. Plug-in may just update visual representation of its printer list. If parameter = 2 - some printer added/removed. Plug-in must reload printer list and update all settings.
InitSettings	no parameterts; returns nothing	Core calls this method when there is no configuration for current printer loaded. Plug-in must update its internal settings and UI.

_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, String error_message	When some error happens during saving the text, plug-in should raise OnError event.
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.
ItemString	Number index; returns String	In some cases, plug-in does not need to have processed result. In this case, it should call ItemString method to get just Unicode string of rendered page. Examples of such plug-ins are Clipboard and Printer.
ItemsSize	Number start_index, Number end_index; returns Number	Some plug-ins need to know page or pages range 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 requested pages in bytes, taking into account all necessary transformations.
ItemsStringSize	Number start_index, Number end_index; returns Number	Returns size, in characters, of the requested pages range, without taking into account conversions - line breaks, page breaks and encoding. Useful for plug-ins which will use ItemString method instead of Item, to have job size before saving will take place (to allocate buffer, etc).
ContainsPage	String sample; returns Number (flag)	Returns non-zero value if input string contains {{PAGE}} tag. This method helps to build different saving strategy, one file per page, instead of saving one contignious file.
TranslateString	String input, Number page_id, Number translate_flag; returns String	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. If translate_flag is not 0, this method changes unsafe characters (which cannot be used in filenames) to underscores when replaces tags.

Transport plug-in working scheme

1. UI starts and loads plug-ins. It subscribes to _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 (using ValueNoCheck property and calls CheckSettings).
3. Core creates plug-ins too and subscribes to events. OnError and OnProgress events inform Core about saving progress. Using OnChangeParam event, plug-ins may have special parameters which will be changed dynamically and will be supported by Core as a part of configuration and will be saved in registry.
4. Core gets Layout property. According to Layout parameters, it reads saved values from configuration (registry) and sets as Values of plug-in (using ValueNoCheck property and calls CheckSettings). If configuration for current printer does not exist, Core calls InitSettings.

Remark: UI and Core may start each other, but the final situation does not change: Core reads settings and sets plug-in properties first, then UI reads these properties and sets them to its "own" plug-ins.
There are two sets of plug-ins exists in the scheme, because UI and Core are separate processes.

Interactive job cycle:

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.
10. If some "dynamic" parameter will be changed during working process, plug-in will fire OnChangeParam event. Core will broadcast this event to all subscribers and save it in configuration.

See also:

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