Inside Macintosh: More Macintosh Toolbox /

Chapter 7 - Translation Manager

Summary of Translation Extensions

This section provides Pascal, C, and assembly-language summaries for the constants, data types, and routines you can use to write a translation extension. For a summary of the constants, data types, and routines that applications can use, see "Summary of the Translation Manager" beginning on page 7-63.

Pascal Summary

Constants

CONST
   {component flags}
   kSupportsFileTranslation               = 1;  {file translation extension}
   kSupportsScrapTranslation              = 2;  {scrap translation extension}
   {translation attributes}
   taDstDocNeedsResourceFork              = 1;  {doc needs a resource fork}
   taDstIsAppTranslation                  = 2;  {app will translate doc}
   {request codes for translation extensions}
   kTranslateGetFileTranslationList       = 0;
   kTranslateIdentifyFile                 = 1;
   kTranslateTranslateFile                = 2;
   kTranslateGetScrapTranslationList      = 10;
   kTranslateIdentifyScrap                = 11;
   kTranslateTranslateScrap               = 12;

Data Types

TYPE
   FileType                = OSType;   {file types}
   ScrapType               = ResType;  {scrap types}
   TranslationAttributes   = LongInt;
   FileTypeSpec = 
   RECORD
      format:           FileType;
      hint:             LongInt;
      flags:            TranslationAttributes;
      catInfoType:      OSType;
      catInfoCreator:   OSType;
   END;
   FileTranslationList = 
   RECORD
      modDate:                LongInt;
      groupCount:             LongInt;
      {group1SrcCount:        LongInt;}
      {group1SrcEntrySize:    LongInt;}
      {group1SrcTypes:        ARRAY[1..group1SrcCount] OF FileTypeSpec;}
      {group1DstCount:        LongInt;}
      {group1DstEntrySize:    LongInt;}
      {group1DstTypes:        ARRAY[1..group1DstCount] OF FileTypeSpec;}
      {repeat above six lines for a total of groupCount times}
   END;
   FileTranslationListPtr     = ^FileTranslationList;
   FileTranslationListHandle  = ^FileTranslationListPtr;
   ScrapTypeSpec = 
   RECORD
      format:           ScrapType;
      hint:             LongInt;
   END;
   ScrapTranslationList = 
   RECORD
      modDate:                LongInt;
      groupCount:             LongInt;
      {group1SrcCount:        LongInt;}
      {group1SrcEntrySize:    LongInt;}
      {group1SrcTypes:        ARRAY[1..group1SrcCount] OF ScrapTypeSpec;}
      {group1DstCount:        LongInt;}
      {group1DstEntrySize:    LongInt;}
      {group1DstTypes:        ARRAY[1..group1DstCount] OF ScrapTypeSpec;}
      {repeat above six lines for a total of groupCount times}
   END;
   ScrapTranslationListPtr    = ^ScrapTranslationList;
   ScrapTranslationListHandle = ^ScrapTranslationListPtr;
   TranslationRefNum          = LongInt;

Translation Extension Routines

Managing Translation Progress Dialog Boxes

FUNCTION SetTranslationAdvertisement
                          (refNum: TranslationRefNum; 
                           advertisement: PicHandle): OSErr;
FUNCTION UpdateTranslationProgress
                          (refNum: TranslationRefNum; 
                           percentDone: Integer; 
                           VAR canceled: Boolean): OSErr;

Translation Extension-Defined Routines

File Translation Extension Routines

FUNCTION DoGetFileTranslationList
                          (self: ComponentInstance; 
                           translationList: FileTranslationListHandle)
                           : ComponentResult;
FUNCTION DoIdentifyFile   (self: ComponentInstance; 
                           theDoc: FSSpec; 
                           VAR docKind: FileType): ComponentResult;
FUNCTION DoTranslateFile  (self: ComponentInstance; 
                           refNum: TranslationRefNum; 
                           srcDoc: FSSpec; 
                           srcType: FileType; 
                           srcTypeHint: LongInt; 
                           dstDoc: FSSpec; 
                           dstType: FileType; 
                           dstTypeHint: LongInt): ComponentResult;

Scrap Translation Extension Routines

FUNCTION DoGetScrapTranslationList
                          (self: ComponentInstance;
                           list: ScrapTranslationListHandle)
                           : ComponentResult;
FUNCTION DoIdentifyScrap  (self: ComponentInstance;
                           dataPtr: Ptr;
                           dataLength: Size;
                           VAR dataFormat: ScrapType): ComponentResult;
FUNCTION DoTranslateScrap (self: ComponentInstance;
                           refNum: TranslationRefNum;
                           srcDataPtr: Ptr;
                           srcDataLength: Size;
                           srcType: ScrapType;
                           srcTypeHint: LongInt;
                           dstData: Handle;
                           dstType: ScrapType;
                           dstTypeHint: LongInt): ComponentResult;

C Summary

Constants

/*component flags*/
#define kSupportsFileTranslation          1  /*file translation extension*/
#define kSupportsScrapTranslation         2  /*scrap translation extension*/
/*translation attributes*/
#define taDstDocNeedsResourceFork         1  /*doc needs a resource fork*/
#define taDstIsAppTranslation             2  /*app will translate doc*/
/*request codes for translation extensions*/
enum {
   kTranslateGetFileTranslationList       = 0,
   kTranslateIdentifyFile,
   kTranslateTranslateFile,
   kTranslateGetScrapTranslationList      = 10,
   kTranslateIdentifyScrap,
   kTranslateTranslateScrap
};

Data Types

typedef OSType             FileType;               /*file types*/
typedef ResType            ScrapType;              /*scrap types*/
typedef unsigned long      TranslationAttributes;
struct FileTypeSpec {
   FileType                   format;
   long                       hint;
   TranslationAttributes      flags;      
   OSType                     catInfoType;
   OSType                     catInfoCreator;
}
typedef struct FileTypeSpec FileTypeSpec;
struct FileTranslationList {
   unsigned long              modDate;
   unsigned long              groupCount;
   /*unsigned long            group1SrcCount;*/
   /*unsigned long            group1SrcEntrySize;*/
   /*FileTypeSpec             group1SrcTypes[group1SrcCount];*/
   /*unsigned long            group1DstCount;*/
   /*unsigned long            group1DstEntrySize;*/
   /*FileTypeSpec             group1DstTypes[group1DstCount];*/
   /*repeat above six lines for a total of groupCount times*/
};
typedef struct FileTranslationList FileTranslationList;
typedef FileTranslationList   *FileTranslationListPtr, 
                              **FileTranslationListHandle;
struct ScrapTypeSpec {
   ScrapType                  format;
   long                       hint;
}
typedef struct ScrapTypeSpec ScrapTypeSpec;
struct ScrapTranslationList {
   unsigned long              modDate;
   unsigned long              groupCount;
   /*unsigned long            group1SrcCount;*/
   /*unsigned long            group1SrcEntrySize;*/
   /*ScrapTypeSpec            group1SrcTypes[group1SrcCount];*/
   /*unsigned long            group1DstCount;*/
   /*unsigned long            group1DstEntrySize;*/
   /*ScrapTypeSpec            group1DstTypes[group1DstCount];*/
   /*repeat above six lines for a total of groupCount times*/
};
typedef struct ScrapTranslationList ScrapTranslationList;
typedef ScrapTranslationList  *ScrapTranslationListPtr, 
                              **ScrapTranslationListHandle;
typedef long                  TranslationRefNum;

Translation Extension Routines

Managing Translation Progress Dialog Boxes

pascal OSErr SetTranslationAdvertisement
                        (TranslationRefNum refnum, 
                         PicHandle advertisement);
pascal OSErr UpdateTranslationProgress
                        (TranslationRefNum refnum,
                         short percentDone, 
                         Boolean* canceled);

Translation Extension-Defined Routines

File Translation Extension Routines

pascal ComponentResult DoGetFileTranslationList
                        (ComponentInstance self, 
                         FileTranslationListHandle translationList);
pascal ComponentResult DoIdentifyFile
                        (ComponentInstance self, 
                         const FSSpec* theDoc, 
                         FileType* docKind);
pascal ComponentResult DoTranslateFile
                        (ComponentInstance self, 
                         TranslationRefNum refNum, 
                         const FSSpec* srcDoc, 
                         FileType srcType, 
                         long srcTypeHint, 
                         const FSSpec* dstDoc, 
                         FileType dstType, 
                         long dstTypeHint);

Scrap Translation Extension Routines

pascal ComponentResult DoGetScrapTranslationList
                        (ComponentInstance self, 
                         ScrapTranslationListHandle list);
pascal ComponentResult DoIdentifyScrap
                        (ComponentInstance self, 
                         const void* dataPtr, 
                         Size dataLength, 
                         ScrapType* dataFormat);
pascal ComponentResult DoTranslateScrap
                        (ComponentInstance self, 
                         TranslationRefNum refNum, 
                         const void* srcDataPtr, 
                         Size srcDataLength, 
                         ScrapType srcType, 
                         long srcTypeHint, 
                         Handle dstData, 
                         ScrapType dstType, 
                         long dstTypeHint);

Assembly-Language Summary

Data Structures

File Type Specification

0	format	4 bytes	the file type
4	hint	4 bytes	reserved for use by your translation extension
8	flags	4 bytes	flags for controlling translation
12	catInfoType	4 bytes	the file's catalog type
16	catInfoCreator	4 bytes	the file's catalog creator

File Translation List

0	modDate	4 bytes	the creation date of the file translation list
4	groupCount	4 bytes	the number of translation groups that follow

Scrap Type Specification

0	format	4 bytes	the scrap type
4	hint	4 bytes	reserved for use by your translation extension

Scrap Translation List

0	modDate	4 bytes	the creation date of the scrap translation list
4	groupCount	4 bytes	the number of translation groups that follow

Trap Macros

Trap Macros Requiring Routine Selectors

_TranslationDispatch

Selector	Routine
$0001	UpdateTranslationProgress
$0002	SetTranslationAdvertisement

Result Codes

noErr	0	No error
dskFulErr	-34	Not enough disk space to translate file
fnfErr	-43	Document not found
paramErr	-50	Parameter error
noTypeErr	-102	Unrecognized file or scrap type
memFullErr	-108	Not enough memory
dirNFErr	-120	Source or destination directory does not exist
wrgVolTypErr	-123	Volume does not support Desktop Manager
userCanceledErr	-128	The user canceled the translation
invalidTranslationPathErr	-3025	srcType to dstType is not a valid path
couldNotParseSourceFileErr	-3026	Source document is not of type srcType
afpItemNotFound	-5012	Could not determine kind string; or, application information not found