home *** CD-ROM | disk | FTP | other *** search
/ QuickTime 2.0 Developer Kit / QuickTime 2.0 Developer Kit.iso / mac / MAC / Programming Stuff / Interfaces / PInterfaces / Translation.p < prev    next >
Encoding:
Text File  |  1994-11-11  |  11.6 KB  |  315 lines  |  [TEXT/MPS ]
  1. {
  2.      File:        Translation.p
  3.  
  4.      Copyright:    © 1984-1994 by Apple Computer, Inc.
  5.                  All rights reserved.
  6.  
  7.      Version:    Universal Interfaces 2.0a3  ETO #16, MPW prerelease.  Friday, November 11, 1994. 
  8.  
  9.      Bugs?:        If you find a problem with this file, send the file and version
  10.                  information (from above) and the problem description to:
  11.  
  12.                      Internet:    apple.bugs@applelink.apple.com
  13.                      AppleLink:    APPLE.BUGS
  14.  
  15. }
  16.  
  17. {$IFC UNDEFINED UsingIncludes}
  18. {$SETC UsingIncludes := 0}
  19. {$ENDC}
  20.  
  21. {$IFC NOT UsingIncludes}
  22.  UNIT Translation;
  23.  INTERFACE
  24. {$ENDC}
  25.  
  26. {$IFC UNDEFINED __TRANSLATION__}
  27. {$SETC __TRANSLATION__ := 1}
  28.  
  29. {$I+}
  30. {$SETC TranslationIncludes := UsingIncludes}
  31. {$SETC UsingIncludes := 1}
  32.  
  33.  
  34. {$IFC UNDEFINED __TYPES__}
  35. {$I Types.p}
  36. {$ENDC}
  37. {    ConditionalMacros.p                                            }
  38.  
  39. {$IFC UNDEFINED __FILES__}
  40. {$I Files.p}
  41. {$ENDC}
  42. {    MixedMode.p                                                    }
  43. {    OSUtils.p                                                    }
  44. {        Memory.p                                                }
  45.  
  46. {$IFC UNDEFINED __COMPONENTS__}
  47. {$I Components.p}
  48. {$ENDC}
  49.  
  50. {$IFC UNDEFINED __TRANSLATIONEXTENSIONS__}
  51. {$I TranslationExtensions.p}
  52. {$ENDC}
  53. {    Quickdraw.p                                                    }
  54. {        QuickdrawText.p                                            }
  55.  
  56. {$PUSH}
  57. {$ALIGN MAC68K}
  58. {$LibExport+}
  59.     
  60. TYPE
  61.     DocOpenMethod = INTEGER;
  62.  
  63.  
  64. CONST
  65.     domCannot                    = 0;
  66.     domNative                    = 1;
  67.     domTranslateFirst            = 2;
  68.     domWildcard                    = 3;
  69.  
  70. { 0L terminated array of OSTypes, or FileTypes}
  71.     
  72. TYPE
  73.     TypesBlock = ARRAY [0..63] OF OSType;
  74.  
  75.     TypesBlockPtr = ^OSType;
  76.  
  77. { Progress dialog resource ID}
  78.  
  79. CONST
  80.     kTranslationScrapProgressDialogID = -16555;
  81.  
  82. { block of data that describes how to translate}
  83.  
  84. TYPE
  85.     FileTranslationSpec = RECORD
  86.         componentSignature:        OSType;
  87.         translationSystemInfo:    Ptr;
  88.         src:                    FileTypeSpec;
  89.         dst:                    FileTypeSpec;
  90.     END;
  91.     FileTranslationSpecArrayPtr = ^FileTranslationSpec;
  92.  
  93. {****************************************************************************************
  94. * 
  95. *   GetFileTypesThatAppCanNativelyOpen
  96. * 
  97. *  This routine returns a list of all FileTypes that an application can open by itself
  98. * 
  99. *  Enter:    appVRefNumHint        volume where application resides (can be wrong, and if is, will be used as a starting point)
  100. *             appSignature        signature (creator) of application
  101. *             nativeTypes            pointer to a buffer to be filled with up to 64 FileTypes
  102. * 
  103. *  Exit:    nativeTypes            zero terminated array of FileTypes that can be opened by app
  104. }
  105.  
  106. FUNCTION GetFileTypesThatAppCanNativelyOpen(appVRefNumHint: INTEGER; appSignature: OSType; VAR nativeTypes: FileType): OSErr;
  107.     {$IFC NOT GENERATINGCFM}
  108.     INLINE $701C, $ABFC;
  109.     {$ENDC}
  110. {****************************************************************************************
  111. * 
  112. *  ExtendFileTypeList
  113. * 
  114. *  This routine makes a new list of file types that can be translated into a type in the given list
  115. *  Used by StandardFile
  116. * 
  117. *  Enter:    originalTypeList        pointer to list of file types that can be opened
  118. *             numberOriginalTypes        number of file types in orgTypeList
  119. *              extendedTypeList        pointer to a buffer to be filled with file types
  120. *             numberExtendedTypes        max number of file types that can be put in extendedTypeList
  121. * 
  122. *  Exit:    extendedTypeList        buffer filled in with file types that can be translated
  123. *             numberExtendedTypes        number of file types put in extendedTypeList
  124. }
  125. FUNCTION ExtendFileTypeList({CONST}VAR originalTypeList: FileType; numberOriginalTypes: INTEGER; VAR extendedTypeList: FileType; VAR numberExtendedTypes: INTEGER): OSErr;
  126.     {$IFC NOT GENERATINGCFM}
  127.     INLINE $7009, $ABFC;
  128.     {$ENDC}
  129. {****************************************************************************************
  130. * 
  131. * 
  132. *  This routine checks if a file can be opened by a particular application.
  133. *  If so, it returns if it needs to be translated first, and if so then how.
  134. *  The FileTypes that the app can open are specified by nativelyOpenableTypes,
  135. *  or if it is NULL, GetFileTypesThatAppCanNativelyOpen is called.
  136. * 
  137. *  Enter:    targetDocument        document to check if it can be opened
  138. *             appVRefNumHint        vRefNum of application to open doc ( can be wrong, and if is, will be used as a starting point)
  139. *             appSignature        signature (creator) of application to open doc
  140. *             nativeTypes            zero terminated list of FileTypes app can open natively, or NULL to use default list
  141. *             onlyNative            whether to consider if document can be translated before opening
  142. *             howToOpen            pointer to buffer in which to put how the document can be opened
  143. *             howToTranslate        pointer to buffer in which to put a FileTranslationSpec record
  144. * 
  145. *  Exit:    howToOpen            whether file needs to be translated to be read
  146. *             howToTranslate        if file can be translated, buffer filled in with how to translate
  147. *             returns                noErr, noPrefAppErr
  148. }
  149. FUNCTION CanDocBeOpened({CONST}VAR targetDocument: FSSpec; appVRefNumHint: INTEGER; appSignature: OSType; {CONST}VAR nativeTypes: FileType; onlyNative: BOOLEAN; VAR howToOpen: DocOpenMethod; VAR howToTranslate: FileTranslationSpec): OSErr;
  150.     {$IFC NOT GENERATINGCFM}
  151.     INLINE $701E, $ABFC;
  152.     {$ENDC}
  153. {****************************************************************************************
  154. * 
  155. *  GetFileTranslationPaths
  156. * 
  157. *  This routine returns a list of all ways a translation can occure to or from a FileType.
  158. *  The app is checked to exist.  The hint for each app is the VRefNum and DTRefNum
  159. * 
  160. *  Enter:    srcDoc            source file or NULL for all matches
  161. *             dstDoc            destination FileType or NULL for all matches
  162. *             maxResultCount
  163. *             resultBuffer
  164. *  Exit:    number of paths
  165. }
  166. FUNCTION GetFileTranslationPaths(VAR srcDocument: FSSpec; dstDocType: FileType; maxResultCount: INTEGER; resultBuffer: FileTranslationSpecArrayPtr): INTEGER;
  167.     {$IFC NOT GENERATINGCFM}
  168.     INLINE $7038, $ABFC;
  169.     {$ENDC}
  170. {****************************************************************************************
  171. * 
  172. *  GetPathFromTranslationDialog
  173. * 
  174. *  This routine, with a given document, application, and a passed typelist will display the
  175. *  Macintosh Easy Open translation dialog allowing the user to make a choice.  The choice
  176. *  made will be written as a preference (so the next call to CanDocBeOpened() will work).
  177. *  The routine returns the translation path information.
  178. * 
  179. *  Enter:    theDocument            FSSpec to document to open
  180. *             theApplication        FSSpec to application to open document
  181. *             typeList            Nil terminated list of FileType's (e.g. SFTypeList-like) of types
  182. *                                 you would like the documented translated to.  Order most perferred
  183. *                                 to least.
  184. * 
  185. *  Exit:    howToOpen            Translation method needed to open document
  186. *             howToTranslate        Translation specification
  187. *             returns                Any errors that might occur.
  188. }
  189. FUNCTION GetPathFromTranslationDialog({CONST}VAR theDocument: FSSpec; {CONST}VAR theApplication: FSSpec; typeList: TypesBlockPtr; VAR howToOpen: DocOpenMethod; VAR howToTranslate: FileTranslationSpec): OSErr;
  190.     {$IFC NOT GENERATINGCFM}
  191.     INLINE $7037, $ABFC;
  192.     {$ENDC}
  193. {****************************************************************************************
  194. * 
  195. *   TranslateFile
  196. * 
  197. *  This routine reads a file of one format and writes it to another file in another format. 
  198. *  The information on how to translated is generated by the routine CanDocBeOpened.
  199. *  TranslateFile calls through to the TranslateFile Extension's DoTranslateFile routine.  
  200. *  The destination file must not exist.  It is created by this routine.  
  201. * 
  202. *  Enter:    sourceDocument            input file to translate
  203. *             destinationDocument        output file of translation
  204. *             howToTranslate            pointer to info on how to translate
  205. *  Exit:    returns                    noErr, badTranslationSpecErr 
  206. }
  207. FUNCTION TranslateFile({CONST}VAR sourceDocument: FSSpec; {CONST}VAR destinationDocument: FSSpec; {CONST}VAR howToTranslate: FileTranslationSpec): OSErr;
  208.     {$IFC NOT GENERATINGCFM}
  209.     INLINE $700C, $ABFC;
  210.     {$ENDC}
  211. {****************************************************************************************
  212. * 
  213. *   GetDocumentKindString
  214. * 
  215. *  This routine returns the string the Finder should show for the "kind" of a document
  216. *  in the GetInfo window and in the kind column of a list view.  
  217. * 
  218. *  Enter:    docVRefNum        The volume containing the document
  219. *             docType            The catInfo.fdType of the document
  220. *             docCreator        The catInfo.fdCreator of the document
  221. *             kindString        pointer to where to return the string
  222. * 
  223. *  Exit:    kindString        pascal string.  Ex: "\pSurfCalc spreadsheet"
  224. *             returns            noErr, or afpItemNoFound if kind could not be determined
  225. }
  226. FUNCTION GetDocumentKindString(docVRefNum: INTEGER; docType: OSType; docCreator: OSType; VAR kindString: Str63): OSErr;
  227.     {$IFC NOT GENERATINGCFM}
  228.     INLINE $7016, $ABFC;
  229.     {$ENDC}
  230. {****************************************************************************************
  231. * 
  232. *  GetTranslationExtensionName
  233. * 
  234. *  This routine returns the translation system name from a specified TranslationSpec
  235. * 
  236. *  Enter:    translationMethod    The translation path to get the translation name from
  237. * 
  238. *  Exit:    extensionName        The name of the translation system
  239. *             returns                Any errors that might occur
  240. }
  241. FUNCTION GetTranslationExtensionName({CONST}VAR translationMethod: FileTranslationSpec; VAR extensionName: Str31): OSErr;
  242.     {$IFC NOT GENERATINGCFM}
  243.     INLINE $7036, $ABFC;
  244.     {$ENDC}
  245. {****************************************************************************************
  246. * 
  247. *  GetScrapDataProcPtr
  248. * 
  249. *  This is a prototype for the function you must supply to TranslateScrap. It is called to 
  250. *  get the data to be translated.  The first call TranslateScrap will make to this is to
  251. *  ask for the 'fmts' data.  That is a special.   You should resize and fill in the handle
  252. *  with a list all the formats that you have available to be translated, and the length of each.
  253. *  (See I.M. VI 4-23 for details of 'fmts').  It will then be called again asking for one of  
  254. *  the formats that 'fmts' list said was available.
  255. * 
  256. *  Enter:    requestedFormat            Format of data that TranslateScrap needs.
  257. *             dataH                    Handle in which to put the requested data
  258. *             srcDataGetterRefCon        Extra parameter for you passed to TranslateScrap
  259. *             
  260. *  Exit:    dataH                    Handle is resized and filled with data in requested format
  261. }
  262. TYPE
  263.     GetScrapDataProcPtr = ProcPtr;  { FUNCTION GetScrapData(requestedFormat: ScrapType; dataH: Handle; srcDataGetterRefCon: UNIV Ptr): OSErr; }
  264.     GetScrapDataUPP = UniversalProcPtr;
  265.  
  266. CONST
  267.     uppGetScrapDataProcInfo = $00000FE0; { FUNCTION (4 byte param, 4 byte param, 4 byte param): 2 byte result; }
  268.  
  269. FUNCTION NewGetScrapDataProc(userRoutine: GetScrapDataProcPtr): GetScrapDataUPP;
  270.     {$IFC NOT GENERATINGCFM }
  271.     INLINE $2E9F;
  272.     {$ENDC}
  273.  
  274. FUNCTION CallGetScrapDataProc(requestedFormat: ScrapType; dataH: Handle; srcDataGetterRefCon: UNIV Ptr; userRoutine: GetScrapDataUPP): OSErr;
  275.     {$IFC NOT GENERATINGCFM}
  276.     INLINE $205F, $4E90;
  277.     {$ENDC}
  278.     
  279. TYPE
  280.     GetScrapData = GetScrapDataUPP;
  281.  
  282. {****************************************************************************************
  283. * 
  284. *  TranslateScrap
  285. * 
  286. *  This routine resizes the destination handle and fills it with data of the requested format.
  287. *  The data is generated by translated one or more source formats of data supplied by
  288. *  the procedure srcDataGetter.  
  289. *  This routine is automatically called by GetScrap and ReadEdition.  You only need to call
  290. *  this if you need to translated scrap style data, but are not using the ScrapMgr or EditionMgr.
  291. * 
  292. *  Enter:    sourceDataGetter            Pointer to routine that can get src data
  293. *             sourceDataGetterRefCon        Extra parameter for dataGetter
  294. *             destinationFormat            Format of data desired
  295. *             destinationData                Handle in which to store translated data
  296. *             
  297. *  Exit:    dstData                        Handle is resized and filled with data in requested format
  298. }
  299.  
  300. FUNCTION TranslateScrap(sourceDataGetter: GetScrapData; sourceDataGetterRefCon: UNIV Ptr; destinationFormat: ScrapType; destinationData: Handle; progressDialogID: INTEGER): OSErr;
  301.     {$IFC NOT GENERATINGCFM}
  302.     INLINE $700E, $ABFC;
  303.     {$ENDC}
  304.  
  305. {$ALIGN RESET}
  306. {$POP}
  307.  
  308. {$SETC UsingIncludes := TranslationIncludes}
  309.  
  310. {$ENDC} {__TRANSLATION__}
  311.  
  312. {$IFC NOT UsingIncludes}
  313.  END.
  314. {$ENDC}
  315.