Convert Registry entry

is a document handle used to identify the document type being converted (the start format).

How to identify a document handle

A document handle is a label that is used to identify a document format. For example, the document handle for an HTML file is HTMLFile. The handle is used in place of a document extension to tie a file to a given piece of software.

Using the document handle it is possible to set up different conversion Registry entries for documents with the same file extension. For example, if MS Word is installed on a computer, the document handle for .doc files is Word.Document.8. If WordPad is installed rather than MS Word, the document handle for .doc files will be Wordpad.Document.1. As the handles are different, even though the file extension is the same, different conversion filters can be set up. This allows filters to be set based on the software installed on a user's machine.

To determine what the handle is for a given file type, it is necessary to look in the Windows Registry. The handle is the (Default) Registry value for the Registry key:

\HKEY_CLASSES_ROOT\fileextension

e.g. for a file extension of .aif, consulting the Windows Registry for the value of (Default) for \HKEY_CLASSES_ROOT\.aif gives the handle AIFFile:

Similarly, checking the file extension for .html (or .htm) gives a value of htmlfile; .txt yields txtfile.

It is important to remember that the document handle is used to determine how a document is translated from one format to another. For example, converting a .doc file on a machine that has MS Word installed (with a document handle of Word.Document.8) to an HTML file (with a file extension of html), EMu Registry entries that would apply would be:

Key	User	Group	System
Key 1	User	Group	System
Key 2	user	group	Setting
Key 3	Setting	Setting	Multimedia
Key 4	Multimedia	Multimedia	Convert
Key 5	Convert	Convert	Word.Document.8
Key 6	Word.Document.8	Word.Document.8	html
Key 7	html	html	filtertype
Key 8	filtertype	filtertype
Value	options

If the same conversion was to take place on a machine that has WordPad installed rather than MS Word, the following Registry entries would apply:

Key	User	Group	System
Key 1	User	Group	System
Key 2	user	group	Setting
Key 3	Setting	Setting	Multimedia
Key 4	Multimedia	Multimedia	Convert
Key 5	Convert	Convert	Wordpad.Document.1
Key 6	Wordpad.Document.1	Wordpad.Document.1	html
Key 7	html	html	filtertype
Key 8	filtertype	filtertype
Value	options

Note: When installing new conversion Registry entries it is important to make sure the correct document handle is used to specify the original document format. It is also worth considering what software may be installed that can perform the conversion. If a Registry entry cannot be found for translating a document, the conversion fails and the required document format is not produced.

indicates what type of filter is to be used. Allowable values are:

• DDE
  Client-side DDE filters: document conversion carried out by client-side (Windows) DDE server

  A client-side DDE filter uses the Microsoft Dynamic Data Exchange mechanism to convert a document to a new format. DDE allows a program to be invoked and commands sent to it to be executed. Using this technology it is possible to "drive" an application from within EMu. For DDE to function a client/server setup is required. EMu operates as a client connecting to a DDE server. The server must support the Execute transaction.

  An example of a DDE server is MS Word. In order to translate a document from Word's internal format (.doc) to HTML it is possible to invoke Word, open up the file to be translated and perform a Save As... in HTML format, then close the original document. Similarly the Save As... facility could be used to generate TEXT and RTF documents.

  DDE uses an Application label to determine which DDE Server should be executed. The Application label is determined from the Windows Registry. For example, the Application label for Microsoft Windows is WinWord. Within an application a Topic is set to determine what part of the application is to be used. All DDE servers must support the System Topic. Using the Application and Topic settings it is possible to invoke a DDE server and prepare it to execute commands. EMu Registry entries suitable for setting the Application are:

  Key	User	Group	System
  Key 1	User	Group	System
  Key 2	user	group	Setting
  Key 3	Setting	Setting	Multimedia
  Key 4	Multimedia	Multimedia	Convert
  Key 5	Convert	Convert	handle
  Key 6	handle	handle	fileext
  Key 7	fileext	fileext	DDE
  Key 8	DDE	DDE	Application
  Key 9	Application	Application
  Value	application

  and the Topic:

  Key	User	Group	System
  Key 1	User	Group	System
  Key 2	user	group	Setting
  Key 3	Setting	Setting	Multimedia
  Key 4	Multimedia	Multimedia	Convert
  Key 5	Convert	Convert	handle
  Key 6	handle	handle	fileext
  Key 7	fileext	fileext	DDE
  Key 8	DDE	DDE	Topic
  Key 9	Topic	Topic
  Value	topic

  Note: To determine the Application and Topic values required for a given DDE server, it is necessary to consult the server documentation.

  Once the server has been invoked it is possible to send it a command for execution. The format of the command varies from server to server. In essence the command should open up the original file, save it in the required format and close the original file. The format of a suitable Command Registry entry is:

  Key	User	Group	System
  Key 1	User	Group	System
  Key 2	user	group	Setting
  Key 3	Setting	Setting	Multimedia
  Key 4	Multimedia	Multimedia	Convert
  Key 5	Convert	Convert	handle
  Key 6	handle	handle	fileext
  Key 7	fileext	fileext	DDE
  Key 8	DDE	DDE	Command
  Key 9	Command	Command
  Value	command

  The command is a sequence of instructions sent to the DDE server for execution. As for all commands, %1 and %2 are replaced with the input and output file respectively.

  The final setting allows a delay to be set after the command has finished being executed. Some DDE servers may indicate that the command has completed before the output file is ready for use by EMu (this is typically the case if EMu cannot open the generated file). The Registry entry for the delay is:

  Key	User	Group	System
  Key 1	User	Group	System
  Key 2	user	group	Setting
  Key 3	Setting	Setting	Multimedia
  Key 4	Multimedia	Multimedia	Convert
  Key 5	Convert	Convert	handle
  Key 6	handle	handle	fileext
  Key 7	fileext	fileext	DDE
  Key 8	DDE	DDE	Wait
  Key 9	Wait	Wait
  Value	seconds

  where seconds is the number of seconds to delay after the server has finished executing the command and before EMu tries to access the output file. If the Registry entry does not exist, a default value of 10 seconds is assumed. If EMu cannot access the output file after the translation, increasing this value may solve the problem.

  Example

  The following Registry entries could be used to provide translation from an MS Word document to an HTML document:

  Key	System	System	System	System
  Key 1	System	System	System	System
  Key 2	Setting	Setting	Setting	Setting
  Key 3	Multimedia	Multimedia	Multimedia	Multimedia
  Key 4	Convert	Convert	Convert	Convert
  Key 5	Word.Document.8	Word.Document.8	Word.Document.8	Word.Document.8
  Key 6	HTML	HTML	HTML	HTML
  Key 7	DDE	DDE	DDE	DDE
  Key 8	Application	Topic	Wait	Command
  Value	WinWord	System	20	[FileOpen("%1")][FileSaveAs("%2", ConverterLookup ("HTML"))][FileClose(0)]

  All the above Registry entries should appear one per line. The Command entry is a set of VBA commands executed by Word to open the original document, save it as HTML and then close the original document. Note that if Word is already running, DDE will not start a new instance, rather it will use the existing one.

• Command
  Client-side filters: document conversion carried out by a client-side (Windows) program

  A client-side filter is a program executed on a Windows machine to convert a document from its original format into another format. EMu will run the filter and wait for it to complete. Once completed, EMu uses the output file as the translated document. The format of the Registry entries for client-side commands is:

  Key	User	Group	System
  Key 1	User	Group	System
  Key 2	user	group	Setting
  Key 3	Setting	Setting	Multimedia
  Key 4	Multimedia	Multimedia	Convert
  Key 5	Convert	Convert	handle
  Key 6	handle	handle	fileext
  Key 7	fileext	fileext	Command
  Key 8	Command	Command
  Value	command

  When a client-side filter is run, EMu creates a temporary file with the correct file extension (as specified by the fileext value). The temporary file is used as the output file into which the translated document is to be placed. The format of the command is the name of the program to perform the conversion along with any associated options and arguments. Two place-holders may be used in the command:

  • The first is %1, which is replaced with the full path to the input file (the file to be translated).
  • The second is %2, which is replaced with the name of the file into which the output is to be placed.

  For example, we have developed a VBA script that can convert an HTML document into a text document. The script takes two arguments. The first is the name of the HTML document to be converted and the second is the name of the output file into which the text is to be placed. A suitable Registry entry would be:

  Key	System
  Key 1	System
  Key 2	Setting
  Key 3	Multimedia
  Key 4	Convert
  Key 5	HTMLFile
  Key 6	txt
  Key 7	Command
  Value	MyScript %1 %2

  where:

  HTMLFile	is the document handle for HTML files.
  txt	is the file extension to be generated.

  When the command is executed, %1 and %2 are replaced with the input file and output file respectively. Note that EMu will suspend execution until the filter has completed running. If the output file does not exist after the filter has finished, the translation is deemed to have failed and the conversion is aborted.

  As a special case the command may be the keyword None. In this case the input file is simply copied to the output file and an external filter is not invoked.

• Server Command
  Server-side filters: document conversion carried out by server-side program

  A server-side filter is very similar to a client-side filter except that the command is executed on the EMu server. Using server-side filters will allow the translation software to be installed on one machine (the server) while being accessible to all users (clients). Suitable Registry entries are:

  Key	User	Group	System
  Key 1	User	Group	System
  Key 2	user	group	Setting
  Key 3	Setting	Setting	Multimedia
  Key 4	Multimedia	Multimedia	Convert
  Key 5	Convert	Convert	handle
  Key 6	handle	handle	fileext
  Key 7	fileext	fileext	Server Command
  Key 8	Server Command	Server Command
  Value	command

  The format of the command is exactly the same as for client-side filters. In other words it is the program to perform the translation along with its options and arguments. Also the place-holders %1 and %2 are replaced with the input and output file respectively. When a server-side filter is invoked, EMu copies the original file from the client machine to a temporary area on the server. The command is then executed on the server. Once the command has completed, the output file is copied back from the server to the client machine for use.

  Example

  Assume that a filter called /usr/local/bin/pdftotext is installed on the EMu server and it can convert PDF files into text. The filter takes some options and two arguments, namely the input and output files respectively. A suitable Registry entry would be:

  Key	System
  Key 1	System
  Key 2	Setting
  Key 3	Multimedia
  Key 4	Convert
  Key 5	AcroExch.Document
  Key 6	txt
  Key 7	Server Command
  Value	/usr/local/bin/pdftotext -eol dos %1 %2

  where:

  AcroExch.Document

  is the document handle for PDF files. Note: The document handle may not necessarily be AcroExch.Document in your environment - this will depend on the application installed to read PDF documents. You would identify the handle by checking the Windows Registry entry \HKEY_CLASSES_ROOT\.pdf

  The command executed on the server is invoked within a UNIX shell (/bin/sh) so any valid shell syntax may be used. If an error message is sent to STDERR, the filter is deemed to have failed and the translation is aborted.

  Note: There is also a pdftohtml filter that operates in the same manner.