Legacy Document

Inside Macintosh: More Macintosh Toolbox /

Chapter 7 - Translation Manager / Translation Extension Reference

Translation Extension-Defined Routines / File Translation Extension Routines

DoTranslateFile

A file translation extension must respond to the kTranslateTranslateFile request code. The Translation Manager uses this request code to allow the translation extension to translate a file from one format to another. You can handle this request by calling the CallComponentFunctionWithStorage function and passing it a pointer to a function with the syntax defined by the DoTranslateFile function.

FUNCTION DoTranslateFile (self: ComponentInstance; 
                          refNum: TranslationRefNum; 
                          srcDoc: FSSpec; 
                          srcType: FileType; 
                          srcTypeHint: LongInt; 
                          dstDoc: FSSpec; 
                          dstType: FileType; 
                          dstTypeHint: LongInt): ComponentResult;

self

A component instance that identifies the component containing your translation extension.

refNum

The translation reference number for this translation.

srcDoc

A file system specification record that specifies the source document.

srcType

The format of the file to be translated.

srcTypeHint

The value in the hint field of the source document's file type specification.

dstDoc

A file system specification record that specifies the destination document.

dstType

The format into which to translate the source document.

dstTypeHint

The value in the hint field of the destination document's file type specification.

DESCRIPTION

Your DoTranslateFile function translates a document from one format into another. The document to be translated is specified by the srcDoc parameter, and your routine should put the translated document into the file specified by the dstDoc parameter. The data fork of the destination file already exists by the time DoTranslateFile is called. In addition, if the flags field in the appropriate destination file type specification in your extension's file translation list has the taDstDocNeedsResourceFork bit set,
the destination file already contains a resource fork. Your function should open the destination file and fill its data or resource fork (or both) with the appropriate translated data.

The refNum parameter is a reference number that Macintosh Easy Open assigns to the translation. Each translation is assigned a unique number to distinguish the translation from any other translations that might occur. You need to pass this reference number to any Macintosh Easy Open routines you call from within the file translation extension; for instance, if by calling the SetTranslationAdvertisement function you display the progress dialog box, you'll pass that reference number in the refNum parameter.

The DoTranslateFile function can translate the source file itself or rely upon external translators. If it cannot translate the source file, your function should return a result code different from noErr. In that case, Macintosh Easy Open will automatically delete the destination file.

Your translation extension should call the SetTranslationAdvertisement function to display the progress dialog box and the UpdateTranslationProgress function to update the dialog box periodically.

Your DoTranslateFile function should return noErr if successful or an appropriate result code otherwise.

RESULT CODES

noErr	0	No error
userCanceledErr	-128	User canceled the translation
invalidTranslationPathErr	-3025	srcType to dstType is not a valid translation path
couldNotParseSourceFileErr	-3026	The source document is not of type srcType