ADC Home > Reference Library > Reference > Carbon > File Management > Translation Manager Reference >

< Previous PageNext Page > Hide TOC

Deprecated Translation Manager Functions

A function identified as deprecated has been superseded and may become unsupported in the future.

Deprecated in Mac OS X v10.3

CanDocBeOpened

Determines whether a specified application can open a particular document. (Deprecated in Mac OS X v10.3. Use Launch Services to determine whether a document can be opened. See Launch Services Programming Guide.)

Not Recommended

OSErr CanDocBeOpened (
   const FSSpec *targetDocument,
   short appVRefNumHint,
   OSType appSignature,
   const FileType *nativeTypes,
   Boolean onlyNative,
   DocOpenMethod *howToOpen,
   FileTranslationSpec *howToTranslate
);

Parameters
targetDocument

A pointer to 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 pointer to the zero-terminated list of file types that the application can open without translation; if this parameter contains NULL, 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 return, a pointer to a constant indicating the method of opening the document. This field contains a meaningful value only if the function returns noErr (indicating that the specified document can be opened). See “DocOpenMethod” for a description of the values you can use here.

howToTranslate

On return, if the document needs to be translated before it can be opened, a pointer to a buffer of information (in a private format) indicating how to translate the document. You pass the information returned in this parameter to the TranslateFile function.

Return Value

A result code. If the application can open the document, the function returns noErr.

Discussion

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

Special Considerations

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

Availability
Declared In
Translation.h

DisposeGetScrapDataUPP

Disposes of a universal procedure pointer (UPP) to a source-data fetcher callback. (Deprecated in Mac OS X v10.3. There is no replacement function. You should adopt Translation Services instead.)

void DisposeGetScrapDataUPP (
   GetScrapDataUPP userUPP
);

Parameters
userUPP

The universal procedure pointer.

Discussion

See the callback GetScrapDataProcPtr for more information.

Availability
Declared In
Translation.h

ExtendFileTypeList

Creates a list of file types that can be translated into a type in a given list. (Deprecated in Mac OS X v10.3. Use the Translation Services function TranslationCreateWithSourceArray instead.)

Not Recommended

OSErr ExtendFileTypeList (
   const FileType *originalTypeList,
   short numberOriginalTypes,
   FileType *extendedTypeList,
   short *numberExtendedTypes
);

Parameters
originalTypeList

A pointer to a list of file types that can be opened.

numberOriginalTypes

The number of file types in the originalTypeList parameter.

extendedTypeList

On return, a pointer to a buffer filled with file types that can be translated into the types in originalTypeList.

numberExtendedTypes

On input, a pointer to the maximum number of file types that can be put into the buffer passed in the extendedTypeList parameter. On return, a pointer to the actual number of file types put into the extended type list.

Return Value

A result code. See “Translation Manager Result Codes.”

Discussion

Note that the number of types specified in the parameters numberOriginalTypes and numberExtendedTypes is limited only by available memory.

The Standard File Package calls this function internally your application probably won’t need to use it.

Special Considerations

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

Availability
Declared In
Translation.h

GetDocumentKindString

Allows you to get a document kind string. (Deprecated in Mac OS X v10.3. There is no replacement function, but you can use Launch Services to obtain similar information. See Launch Services Programming Guide.)

Not Recommended

OSErr GetDocumentKindString (
   short docVRefNum,
   OSType docType,
   OSType docCreator,
   Str63 kindString
);

Parameters
docVRefNum

The volume containing the document. This is a hint to the Translation Manager. If it doesn't find the string on that volume, it will use an internal search path to look on other volumes for the string.

docType

The type code of the document you want to query.

docCreator

The creator code of the document you want to query.

kindString

Upon return, contains the kind string to display for the specified document type and creator.

Return Value

A result code. See “Translation Manager Result Codes.”

Availability
Declared In
Translation.h

GetFileTranslationPaths

A low-level routine that allows you to get all the translation capabilities of the Translation Manager. (Deprecated in Mac OS X v10.3. Use the Translation Services function TranslationCreateWithSourceArray instead.)

Not Recommended

short GetFileTranslationPaths (
   const FSSpec *srcDocument,
   FileType dstDocType,
   unsigned short maxResultCount,
   FileTranslationSpecArrayPtr resultBuffer
);

Parameters
srcDocument

A source document (optional), or NULL.

dstDocType

The desired document type to which you would like srcDocument translated.

resultBuffer

The requested translation information.

Return Value

Returns the number of translation paths, or a result code if the value is negative.

Availability
Declared In
Translation.h

GetFileTypesThatAppCanNativelyOpen

Obtains a list of file types that an application can open by itself. (Deprecated in Mac OS X v10.3. There is no replacement function. Applications should use Translation Services instead.)

Not Recommended

OSErr GetFileTypesThatAppCanNativelyOpen (
   short appVRefNumHint,
   OSType appSignature,
   FileType *nativeTypes
);

Parameters
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

On return, a pointer to an array of file types that the application can open without translation. If successful, the array contains up to 64 file types. If fewer than 64 types are returned, the end of the list is indicated by an entry whose value is 0.

Return Value

A result code. See “Translation Manager Result Codes.”

Special Considerations

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

Availability
Declared In
Translation.h

GetPathFromTranslationDialog

Displays the Translation Dialog, which attempts to generate a list of translation paths resulting in a document readable by the target application. (Deprecated in Mac OS X v10.3. There is no replacement function. However, applications can obtain this information using Launch Services, Translation Services, and uniform type identifiers.)

Not Recommended

OSErr GetPathFromTranslationDialog (
   const FSSpec *theDocument,
   const FSSpec *theApplication,
   TypesBlockPtr typeList,
   DocOpenMethod *howToOpen,
   FileTranslationSpec *howToTranslate
);

Parameters
theDocument

The target file.

theApplication

The target application.

typeList

Specifies a list of file types into which to translate the target document.

howToOpen

Upon return, contains the translation open method.

howToTranslate

Upon return, contains the translation specification.

Return Value

A result code. See “Translation Manager Result Codes.”

Special Considerations

For information about using Launch Services and uniform type identifiers, see Launch Services Programming Guide and Uniform Type Identifiers Overview.

Availability
Declared In
Translation.h

GetTranslationExtensionName

Finds the name of the extension performing the translation. (Deprecated in Mac OS X v10.3. There is no replacement function. However, you can obtain useful user-level information by calling the Translation Manager function TranslationCopyDestinationType and the uniform type identifiers function UTTypeCopyDescription.)

Not Recommended

OSErr GetTranslationExtensionName (
   const FileTranslationSpec *translationMethod,
   Str31 extensionName
);

Parameters
translationMethod

A file translation method obtained by calling CanDocBeOpened or GetFileTranslationPaths.

extensionName

Upon return, contains the name of the extension performing the translation.

Return Value

A result code. See “Translation Manager Result Codes.”

Availability
Declared In
Translation.h

InvokeGetScrapDataUPP

Calls a source-data fetcher callback. (Deprecated in Mac OS X v10.3. There is no replacement function. You should adopt Translation Services instead.)

OSErr InvokeGetScrapDataUPP (
   ScrapType requestedFormat,
   Handle dataH,
   void *srcDataGetterRefCon,
   GetScrapDataUPP userUPP
);

Discussion

You should not need to use the function InvokeGetScrapDataUPP, as the system calls your source-data fetcher callback for you. See the callback GetScrapDataProcPtr for more information.

Availability
Declared In
Translation.h

NewGetScrapDataUPP

Creates a new universal procedure pointer (UPP) to a source-data fetcher callback. (Deprecated in Mac OS X v10.3. There is no replacement function. You should adopt Translation Services instead.)

GetScrapDataUPP NewGetScrapDataUPP (
   GetScrapDataProcPtr userRoutine
);

Parameters
userRoutine

A pointer to your source-data fetcher callback.

Return Value

On return, a UPP to the source-data fetcher callback.

Discussion

See the callback GetScrapDataProcPtr for more information.

Availability
Declared In
Translation.h

SetTranslationAdvertisement

Allows your translation extension to install an advertisement into the upper portion of the progress dialog box. (Deprecated in Mac OS X v10.3. There is no replacement function. You should adopt Translation Services instead.)

Unsupported

OSErr SetTranslationAdvertisement (
   TranslationRefNum refNum,
   PicHandle advertisement
);

Parameters
refNum

A translation reference number. You should set this parameter to the translation reference number passed to your DoTranslateFileProcPtr or DoTranslateScrapProcPtr callback functions. The Translation Manager uses that number internally.

advertisement

A handle to a picture to display in the upper portion of the dialog box. If this parameter is NULL, no advertisement is displayed and the upper portion of the dialog box is removed before the box is displayed to the user. After the function installs the specified advertisement, it then displays the dialog box.

Your translation extension can read the picture data from its resource fork, but it should detach the resource from the resource fork (by calling the DetachResource function) and make the handle unpurgeable before calling this function. Because you’ll usually load the picture data into the temporary heap provided for the translation extension, the picture data is automatically disposed of when that heap is destroyed. If your translation extension loads the picture data elsewhere in memory, you are responsible for disposing of it before returning from your DoTranslateFile or DoTranslateScrap callback function.

The size of the picture to display can be no larger than 280 by 50 pixels. If the picture you specify is smaller than that, it is automatically centered (both vertically and horizontally) in the available space.

Return Value

A result code. See “Translation Manager Result Codes.”

Discussion

Your translation extension should call this function only in response to the kTranslateTranslateFile or kTranslateTranslateScrap request code (that is, you should only call this function in your DoTranslateFile or DoTranslateScrap callback function). Do not call this function in response to any other request code or from any code that isn’t a translation extension.

You must call this function before you call the UpdateTranslationProgress function for the first time.

Special Considerations

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

Carbon Porting Notes

The functions contained in TranslationExtensions.h were originally written to be used only by someone implementing a Mac Easy Open translation component. Carbon, however, is for applications and not extensions. Therefore, this function is not supported.

Availability
Declared In
TranslationExtensions.h

TranslateFile

Translates a document from one format to another. (Deprecated in Mac OS X v10.3. Use the Translation Services function TranslationPerformForFile or TranslationPerformForURL instead.)

Not Recommended

OSErr TranslateFile (
   const FSSpec *sourceDocument,
   const FSSpec *destinationDocument,
   const FileTranslationSpec *howToTranslate
);

Parameters
sourceDocument

A pointer to the document to translate.

destinationDocument

A pointer to the file to put the translated document into. Note that your application only specifies the name and location for the file; the function creates the file and puts the translated data into it. The destination file must not exist before you call this function.

howToTranslate

A pointer to a buffer of information indicating how to translate the document. Usually, you’ll get this information by calling the CanDocBeOpened function.

Return Value

A result code. See “Translation Manager Result Codes.”

Special Considerations

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

Availability
Declared In
Translation.h

TranslateScrap

Uses a client-specified callback function to get the source data to translate. (Deprecated in Mac OS X v10.3. Use the Translation Manager function TranslationPerformForData instead.)

Not Recommended

OSErr TranslateScrap (
   GetScrapDataUPP sourceDataGetter,
   void *sourceDataGetterRefCon,
   ScrapType destinationFormat,
   Handle destinationData,
   short progressDialogID
);

Parameters
sourceDataGetter

The callback that provides the data to translate.

sourceDataGetterRefCon

A generic pointer to private information for your callback.

destinationFormat

The desired translation format.

destinationData

A handle you provide. The Translation Extension will automatically re-size it as necessary during translation. Upon exit, if the routine successfully executes, it will contain the translated information.

progressDialogID

This parameter should always be assigned the value TranslationScrapProgressDialogID.

Return Value

A result code. See “Translation Manager Result Codes.”

Availability
Declared In
Translation.h

UpdateTranslationProgress

Allows your translation extension to update the progress dialog box that is displayed during file and scrap translation and give the user a chance to cancel. (Deprecated in Mac OS X v10.3. There is no replacement function. You should adopt Translation Services instead.)

Unsupported

OSErr UpdateTranslationProgress (
   TranslationRefNum refNum,
   short percentDone,
   Boolean *canceled
);

Parameters
refNum

A translation reference number. You should set this parameter to the translation reference number passed to your DoTranslateFileProcPtr or DoTranslateScrapProcPtr callback function. The Translation Manager uses that number internally.

percentDone

A value in the range 0–100 that indicates the percentage of the translation that has been completed (the approximate percentage of time elapsed until completion). When the translation is complete, you should call this function with this parameter set to 100 so that the user can see that the translation is complete.

canceled

On return, a pointer to a value which indicates whether or not the user canceled the translation. TRUE if the user clicked the Cancel button in the progress dialog box, or typed Command-period while the box is displayed; otherwise, FALSE. When TRUE, you should stop the translation, and your DoTranslateFile or DoTranslateScrap callback function should return the result code userCancelledErr.

Return Value

A result code. See “Translation Manager Result Codes.”

Discussion

Your translation extension should call this function only in response to the kTranslateTranslateFile or kTranslateTranslateScrap request code (that is, you should only call this function in your DoTranslateFile or DoTranslateScrap callback function). Do not call this function in response to any other request code or from any code that isn’t a translation extension.

You should already have called SetTranslationAdvertisement before calling UpdateTranslationProgress.

Special Considerations

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

Carbon Porting Notes

The functions contained in TranslationExtensions.h were originally written to be used only by someone implementing a Mac Easy Open translation component. Carbon, however, is for applications and not extensions. Therefore, this function is not supported.

Availability
Declared In
TranslationExtensions.h

< Previous PageNext Page > Hide TOC

© 2003, 2006 Apple Computer, Inc. All Rights Reserved. (Last updated: 2006-07-12)

Did this document help you?
Yes: Tell us what works for you.
It’s good, but: Report typos, inaccuracies, and so forth.
It wasn’t helpful: Tell us what would have helped.