Legacy Document

Inside Macintosh: More Macintosh Toolbox /

Chapter 7 - Translation Manager / Translation Manager Reference

Translation Manager Routines / Getting Translation Information

CanDocBeOpened

You can use the CanDocBeOpened function to determine whether a specified application can open a particular document.

FUNCTION CanDocBeOpened 
                  (targetDocument: FSSpec; 
                   appVRefNumHint: Integer; 
                   appSignature: OSType; 
                   nativeTypes: TypesBlockPtr; 
                   onlyNative: Boolean; 
                   VAR howToOpen: DocOpenMethod; 
                   VAR howToTranslate: FileTranslationSpec)
                   : OSErr;

targetDocument

The document to check.

appVRefNumHint

The volume reference number of the volume containing the
application. The search for the specified application begins on this volume; if the application isn't found there, the search continues to other mounted volumes.

appSignature

The signature of the application.

nativeTypes

A zero-terminated list of file types that the application can open without translation; if this parameter contains NIL, the default list of file types returned by the GetFileTypesThatAppCanNativelyOpen function is used.

onlyNative

If TRUE, determine only whether the application can open the document without translation; otherwise, determine whether the application can open the document after translation.

howToOpen

On exit, the method of opening the document. This field contains a meaningful value only if CanDocBeOpened returns noErr (indicating that the specified document can be opened).

howToTranslate

On exit, a buffer of information (in a private format) indicating how to translate the document.

DESCRIPTION

The CanDocBeOpened function determines whether a document can be opened by a particular application. If the application can open the document, CanDocBeOpened returns the result code noErr and sets the howToOpen parameter to a constant that indicates the method that the application would use to open the document. The howToOpen parameter contains a document-opening method:

TYPE DocOpenMethod = 
      (domCannot, domNative, domTranslateFirst, domWildcard);

The domCannot constant indicates that the application cannot open the document. The domNative constant indicates that the application can open the document natively.
The domTranslateFirst constant indicates that the application can open the document only after it's been translated. The domWildcard constant indicates that the application has the file type '****' in its list of the file types that it can open and hence can open any type of document.

If the document needs to be translated before it can be opened (as indicated by the domTranslateFirst method), CanDocBeOpened returns in the howToTranslate parameter a buffer of information indicating how to translate the document. The format of this information is private.

TYPE
   FileTranslationSpec     = ARRAY[1..12] OF LongInt;

You pass the information returned in the howToTranslate parameter to the TranslateFile function.

SPECIAL CONSIDERATIONS

A preference must have already been set (using the Document Converter tool) on how to open the document.

The CanDocBeOpened function is not available in all versions of system software; use the Gestalt function to determine whether the Translation Manager is available before calling it.

The CanDocBeOpened function might cause memory to be moved or purged; you should not call it at interrupt time.

ASSEMBLY-LANGUAGE INFORMATION

The trap macro and routine selector for the CanDocBeOpened procedure are

Trap macro	Selector
_TranslationDispatch	$001E

RESULT CODES

noErr	0	No error
nsvErr	-35	No such volume
ioErr	-36	I/O error
bdNamErr	-37	Bad filename
fnfErr	-43	File not found
paramErr	-50	Parameter error
extFSErr	-58	External file system
dirNFErr	-120	Directory not found or incomplete pathname
badTranslationSpecErr	-3031	Translation path is invalid
noPrefAppErr	-3032	No translation preference available
afpItemNotFound	-5012	Information not found