/*
File: Translation.h
Contains: Translation Manager (Macintosh Easy Open) Interfaces.
Version: QuickTime 7.3
Copyright: (c) 2007 (c) 1991-2001 by Apple Computer, Inc., all rights reserved.
Bugs?: For bug reports, consult the following page on
the World Wide Web:
http://developer.apple.com/bugreporter/
*/
#ifndef __TRANSLATION__
#define __TRANSLATION__
#ifndef __MACTYPES__
#include <MacTypes.h>
#endif
#ifndef __FILES__
#include <Files.h>
#endif
#ifndef __COMPONENTS__
#include <Components.h>
#endif
#ifndef __TRANSLATIONEXTENSIONS__
#include <TranslationExtensions.h>
#endif
#if PRAGMA_ONCE
#pragma once
#endif
#ifdef __cplusplus
extern "C" {
#endif
#if PRAGMA_IMPORT
#pragma import on
#endif
#if PRAGMA_STRUCT_ALIGN
#pragma options align=mac68k
#elif PRAGMA_STRUCT_PACKPUSH
#pragma pack(push, 2)
#elif PRAGMA_STRUCT_PACK
#pragma pack(2)
#endif
/* enumerated types on how a document can be opened*/
typedef short DocOpenMethod;
enum {
domCannot = 0,
domNative = 1,
domTranslateFirst = 2,
domWildcard = 3
};
/* 0L terminated array of OSTypes, or FileTypes*/
typedef OSType TypesBlock[64];
typedef OSType * TypesBlockPtr;
/* Progress dialog resource ID*/
enum {
kTranslationScrapProgressDialogID = -16555
};
/* block of data that describes how to translate*/
struct FileTranslationSpec {
OSType componentSignature;
const void * translationSystemInfo;
FileTypeSpec src;
FileTypeSpec dst;
};
typedef struct FileTranslationSpec FileTranslationSpec;
typedef FileTranslationSpec * FileTranslationSpecArrayPtr;
typedef FileTranslationSpecArrayPtr * FileTranslationSpecArrayHandle;
/*****************************************************************************************
*
* GetFileTypesThatAppCanNativelyOpen
*
* This routine returns a list of all FileTypes that an application can open by itself
*
* Enter: appVRefNumHint volume where application resides (can be wrong, and if is, will be used as a starting point)
* appSignature signature (creator) of application
* nativeTypes pointer to a buffer to be filled with up to 64 FileTypes
*
* Exit: nativeTypes zero terminated array of FileTypes that can be opened by app
*/
/*
* GetFileTypesThatAppCanNativelyOpen()
*
* Availability:
* Non-Carbon CFM: in Translation 1.0 and later
* CarbonLib: in CarbonLib 1.0 and later
* Mac OS X: in version 10.0 and later
*/
EXTERN_API( OSErr )
GetFileTypesThatAppCanNativelyOpen(
short appVRefNumHint,
OSType appSignature,
FileType * nativeTypes) TWOWORDINLINE(0x701C, 0xABFC);
/*****************************************************************************************
*
* ExtendFileTypeList
*
* This routine makes a new list of file types that can be translated into a type in the given list
* Used by StandardFile
*
* Enter: originalTypeList pointer to list of file types that can be opened
* numberOriginalTypes number of file types in orgTypeList
* extendedTypeList pointer to a buffer to be filled with file types
* numberExtendedTypes max number of file types that can be put in extendedTypeList
*
* Exit: extendedTypeList buffer filled in with file types that can be translated
* numberExtendedTypes number of file types put in extendedTypeList
*/
/*
* ExtendFileTypeList()
*
* Availability:
* Non-Carbon CFM: in Translation 1.0 and later
* CarbonLib: in CarbonLib 1.0 and later
* Mac OS X: in version 10.0 and later
*/
EXTERN_API( OSErr )
ExtendFileTypeList(
const FileType * originalTypeList,
short numberOriginalTypes,
FileType * extendedTypeList,
short * numberExtendedTypes) TWOWORDINLINE(0x7009, 0xABFC);
/*****************************************************************************************
*
*
* This routine checks if a file can be opened by a particular application.
* If so, it returns if it needs to be translated first, and if so then how.
* The FileTypes that the app can open are specified by nativelyOpenableTypes,
* or if it is NULL, GetFileTypesThatAppCanNativelyOpen is called.
*
* Enter: targetDocument document to check if it can be opened
* appVRefNumHint vRefNum of application to open doc ( can be wrong, and if is, will be used as a starting point)
* appSignature signature (creator) of application to open doc
* nativeTypes zero terminated list of FileTypes app can open natively, or NULL to use default list
* onlyNative whether to consider if document can be translated before opening
* howToOpen pointer to buffer in which to put how the document can be opened
* howToTranslate pointer to buffer in which to put a FileTranslationSpec record
*
* Exit: howToOpen whether file needs to be translated to be read
* howToTranslate if file can be translated, buffer filled in with how to translate
* returns noErr, noPrefAppErr
*/
/*
* CanDocBeOpened()
*
* Availability:
* Non-Carbon CFM: in Translation 1.0 and later
* CarbonLib: in CarbonLib 1.0 and later
* Mac OS X: in version 10.0 and later
*/
EXTERN_API( OSErr )
CanDocBeOpened(
const FSSpec * targetDocument,
short appVRefNumHint,
OSType appSignature,
const FileType * nativeTypes,
Boolean onlyNative,
DocOpenMethod * howToOpen,
FileTranslationSpec * howToTranslate) TWOWORDINLINE(0x701E, 0xABFC);
/*****************************************************************************************
*
* GetFileTranslationPaths
*
* This routine returns a list of all ways a translation can occure to or from a FileType.
* The app is checked to exist. The hint for each app is the VRefNum and DTRefNum
*
* Enter: srcDoc source file or NULL for all matches
* dstDoc destination FileType or 0 for all matches
* maxResultCount
* resultBuffer
* Exit: number of paths
*/
/*
* GetFileTranslationPaths()
*
* Availability:
* Non-Carbon CFM: in Translation 1.0 and later
* CarbonLib: in CarbonLib 1.0 and later
* Mac OS X: in version 10.0 and later
*/
EXTERN_API( short )
GetFileTranslationPaths(
const FSSpec * srcDocument,
FileType dstDocType,
unsigned short maxResultCount,
FileTranslationSpecArrayPtr resultBuffer) TWOWORDINLINE(0x7038, 0xABFC);
/*****************************************************************************************
*
* GetPathFromTranslationDialog
*
* This routine, with a given document, application, and a passed typelist will display the
* Macintosh Easy Open translation dialog allowing the user to make a choice. The choice
* made will be written as a preference (so the next call to CanDocBeOpened() will work).
* The routine returns the translation path information.
*
* Enter: theDocument FSSpec to document to open
* theApplication FSSpec to application to open document
* typeList Nil terminated list of FileType's (e.g. SFTypeList-like) of types
* you would like the documented translated to. Order most perferred
* to least.
*
* Exit: howToOpen Translation method needed to open document
* howToTranslate Translation specification
* returns Any errors that might occur.
*/
/*
* GetPathFromTranslationDialog()
*
* Availability:
* Non-Carbon CFM: in Translation 1.0 and later
* CarbonLib: in CarbonLib 1.0 and later
* Mac OS X: in version 10.0 and later
*/
EXTERN_API( OSErr )
GetPathFromTranslationDialog(
const FSSpec * theDocument,
const FSSpec * theApplication,
TypesBlockPtr typeList,
DocOpenMethod * howToOpen,
FileTranslationSpec * howToTranslate) TWOWORDINLINE(0x7037, 0xABFC);
/*****************************************************************************************
*
* TranslateFile
*
* This routine reads a file of one format and writes it to another file in another format.
* The information on how to translated is generated by the routine CanDocBeOpened.
* TranslateFile calls through to the TranslateFile Extension's DoTranslateFile routine.
* The destination file must not exist. It is created by this routine.
*
* Enter: sourceDocument input file to translate
* destinationDocument output file of translation
* howToTranslate pointer to info on how to translate
* Exit: returns noErr, badTranslationSpecErr
*/
/*
* TranslateFile()
*
* Availability:
* Non-Carbon CFM: in Translation 1.0 and later
* CarbonLib: in CarbonLib 1.0 and later
* Mac OS X: in version 10.0 and later
*/
EXTERN_API( OSErr )
TranslateFile(
const FSSpec * sourceDocument,
const FSSpec * destinationDocument,
const FileTranslationSpec * howToTranslate) TWOWORDINLINE(0x700C, 0xABFC);
/*****************************************************************************************
*
* GetDocumentKindString
*
* This routine returns the string the Finder should show for the "kind" of a document
* in the GetInfo window and in the kind column of a list view.
*
* Enter: docVRefNum The volume containing the document
* docType The catInfo.fdType of the document
* docCreator The catInfo.fdCreator of the document
* kindString pointer to where to return the string
*
* Exit: kindString pascal string. Ex: "\pSurfCalc spreadsheet"
* returns noErr, or afpItemNoFound if kind could not be determined
*/
/*
* GetDocumentKindString()
*
* Availability:
* Non-Carbon CFM: in Translation 1.0 and later
* CarbonLib: in CarbonLib 1.0 and later
* Mac OS X: in version 10.0 and later
*/
EXTERN_API( OSErr )
GetDocumentKindString(
short docVRefNum,
OSType docType,
OSType docCreator,
Str63 kindString) TWOWORDINLINE(0x7016, 0xABFC);
/*****************************************************************************************
*
* GetTranslationExtensionName
*
* This routine returns the translation system name from a specified TranslationSpec
*
* Enter: translationMethod The translation path to get the translation name from
*
* Exit: extensionName The name of the translation system
* returns Any errors that might occur
*/
/*
* GetTranslationExtensionName()
*
* Availability:
* Non-Carbon CFM: in Translation 1.0 and later
* CarbonLib: in CarbonLib 1.0 and later
* Mac OS X: in version 10.0 and later
*/
EXTERN_API( OSErr )
GetTranslationExtensionName(
const FileTranslationSpec * translationMethod,
Str31 extensionName) TWOWORDINLINE(0x7036, 0xABFC);
/*****************************************************************************************
*
* GetScrapDataProcPtr
*
* This is a prototype for the function you must supply to TranslateScrap. It is called to
* get the data to be translated. The first call TranslateScrap will make to this is to
* ask for the 'fmts' data. That is a special. You should resize and fill in the handle
* with a list all the formats that you have available to be translated, and the length of each.
* (See I.M. VI 4-23 for details of 'fmts'). It will then be called again asking for one of
* the formats that 'fmts' list said was available.
*
* Enter: requestedFormat Format of data that TranslateScrap needs.
* dataH Handle in which to put the requested data
* srcDataGetterRefCon Extra parameter for you passed to TranslateScrap
*
* Exit: dataH Handle is resized and filled with data in requested format
*/
typedef CALLBACK_API( OSErr , GetScrapDataProcPtr )(ScrapType requestedFormat, Handle dataH, void *srcDataGetterRefCon);
typedef STACK_UPP_TYPE(GetScrapDataProcPtr) GetScrapDataUPP;
/*
* NewGetScrapDataUPP()
*
* Availability:
* Non-Carbon CFM: available as macro/inline
* CarbonLib: in CarbonLib 1.0 and later
* Mac OS X: in version 10.0 and later
*/
EXTERN_API_C( GetScrapDataUPP )
NewGetScrapDataUPP(GetScrapDataProcPtr userRoutine);
#if !OPAQUE_UPP_TYPES
enum { uppGetScrapDataProcInfo = 0x00000FE0 }; /* pascal 2_bytes Func(4_bytes, 4_bytes, 4_bytes) */
#ifdef __cplusplus
inline DEFINE_API_C(GetScrapDataUPP) NewGetScrapDataUPP(GetScrapDataProcPtr userRoutine) { return (GetScrapDataUPP)NewRoutineDescriptor((ProcPtr)(userRoutine), uppGetScrapDataProcInfo, GetCurrentArchitecture()); }
#else
#define NewGetScrapDataUPP(userRoutine) (GetScrapDataUPP)NewRoutineDescriptor((ProcPtr)(userRoutine), uppGetScrapDataProcInfo, GetCurrentArchitecture())
#endif
#endif
/*
* DisposeGetScrapDataUPP()
*
* Availability:
* Non-Carbon CFM: available as macro/inline
* CarbonLib: in CarbonLib 1.0 and later
* Mac OS X: in version 10.0 and later
*/
EXTERN_API_C( void )
DisposeGetScrapDataUPP(GetScrapDataUPP userUPP);
#if !OPAQUE_UPP_TYPES
#ifdef __cplusplus
inline DEFINE_API_C(void) DisposeGetScrapDataUPP(GetScrapDataUPP userUPP) { DisposeRoutineDescriptor((UniversalProcPtr)userUPP); }
#else
#define DisposeGetScrapDataUPP(userUPP) DisposeRoutineDescriptor(userUPP)
#endif
#endif
/*
* InvokeGetScrapDataUPP()
*
* Availability:
* Non-Carbon CFM: available as macro/inline
* CarbonLib: in CarbonLib 1.0 and later
* Mac OS X: in version 10.0 and later
*/
EXTERN_API_C( OSErr )
InvokeGetScrapDataUPP(
ScrapType requestedFormat,
Handle dataH,
void * srcDataGetterRefCon,
GetScrapDataUPP userUPP);
#if !OPAQUE_UPP_TYPES
#ifdef __cplusplus
inline DEFINE_API_C(OSErr) InvokeGetScrapDataUPP(ScrapType requestedFormat, Handle dataH, void * srcDataGetterRefCon, GetScrapDataUPP userUPP) { return (OSErr)CALL_THREE_PARAMETER_UPP(userUPP, uppGetScrapDataProcInfo, requestedFormat, dataH, srcDataGetterRefCon); }
#else
#define InvokeGetScrapDataUPP(requestedFormat, dataH, srcDataGetterRefCon, userUPP) (OSErr)CALL_THREE_PARAMETER_UPP((userUPP), uppGetScrapDataProcInfo, (requestedFormat), (dataH), (srcDataGetterRefCon))
#endif
#endif
#if CALL_NOT_IN_CARBON || OLDROUTINENAMES
/* support for pre-Carbon UPP routines: New...Proc and Call...Proc */
#define NewGetScrapDataProc(userRoutine) NewGetScrapDataUPP(userRoutine)
#define CallGetScrapDataProc(userRoutine, requestedFormat, dataH, srcDataGetterRefCon) InvokeGetScrapDataUPP(requestedFormat, dataH, srcDataGetterRefCon, userRoutine)
#endif /* CALL_NOT_IN_CARBON */
typedef GetScrapDataUPP GetScrapData;
/*****************************************************************************************
*
* TranslateScrap
*
* This routine resizes the destination handle and fills it with data of the requested format.
* The data is generated by translated one or more source formats of data supplied by
* the procedure srcDataGetter.
* This routine is automatically called by GetScrap and ReadEdition. You only need to call
* this if you need to translated scrap style data, but are not using the ScrapMgr or EditionMgr.
*
* Enter: sourceDataGetter Pointer to routine that can get src data
* sourceDataGetterRefCon Extra parameter for dataGetter
* destinationFormat Format of data desired
* destinationData Handle in which to store translated data
*
* Exit: dstData Handle is resized and filled with data in requested format
*/
/*
* TranslateScrap()
*
* Availability:
* Non-Carbon CFM: in Translation 1.0 and later
* CarbonLib: in CarbonLib 1.0 and later
* Mac OS X: in version 10.0 and later
*/
EXTERN_API( OSErr )
TranslateScrap(
GetScrapDataUPP sourceDataGetter,
void * sourceDataGetterRefCon,
ScrapType destinationFormat,
Handle destinationData,
short progressDialogID) TWOWORDINLINE(0x700E, 0xABFC);
#if PRAGMA_STRUCT_ALIGN
#pragma options align=reset
#elif PRAGMA_STRUCT_PACKPUSH
#pragma pack(pop)
#elif PRAGMA_STRUCT_PACK
#pragma pack()
#endif
#ifdef PRAGMA_IMPORT_OFF
#pragma import off
#elif PRAGMA_IMPORT
#pragma import reset
#endif
#ifdef __cplusplus
}
#endif
#endif /* __TRANSLATION__ */