home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1997 January: Mac OS SDK / Dev.CD Jan 97 SDK2.toast / Development Kits (Disc 2) / OpenDoc / Developer Documentation / Recipes, Tech Notes & Articles / Tech Notes / Utilities Documentation / Platform File < prev    next >
Encoding:
Text File  |  1995-11-08  |  6.8 KB  |  208 lines  |  [TEXT/ttxt]
  1. OpenDoc™ Utilities Documentation
  2.  
  3. Platform File Class
  4. by The OpenDoc Design Team
  5.  
  6. © 1993-1995  Apple Computer, Inc. All Rights Reserved.
  7. Apple, the Apple logo, and Macintosh are registered trademarks of Apple Computer, Inc.
  8. Mac and OpenDoc are trademarks of Apple Computer, Inc.
  9.  
  10.  
  11. Introduction
  12.  
  13. This is a utility file that is used by OpenDoc. Developers can use it at their own risk. This class provides an object-oriented interface to a file system file.
  14.  
  15. Many of the methods have names that are self-explanatory or have equivalent functions in the file system. These functions are not being documented fully here.
  16.  
  17. Constructor and Destructor
  18.  
  19. PlatformFile();
  20. ~PlatformFile();
  21.  
  22. Methods you can call when the file is not open:
  23.  
  24. File specification
  25.  
  26.     ODNVMethod    void        Specify(const ODFileSpec* fileSpec);
  27.     ODNVMethod    void        SpecifyFromFile(PlatformFile* file);
  28.     ODNVMethod    void        SetAsciiName(const char* name);
  29.  
  30. These methods are used to specify the file on which the PlatformFile object manipulates. These methods can only be called once in the lifetime of the object. If you want to work with a different file, you need to delete the current object and create a new one.
  31.  
  32.     inline        ODFileSpec&    GetFileSpec();
  33.  
  34. This method returns the file spec of the file to which this object refers.
  35.  
  36. File permission
  37.  
  38.     inline        void        SetPermission(ODFilePermission filePermission);
  39.  
  40. Set the access privileges of the file.
  41.  
  42. Basic file manipulation
  43.  
  44.     inline        void        SetFileRefNum( ODFileRefNum );
  45.     ODNVMethod    void        Create(ODOSType creator, ODOSType fileType, ODScriptCode scriptCode);
  46.     ODNVMethod    void        Open();
  47.     ODNVMethod    void        Delete();
  48.  
  49. Resource fork access
  50.  
  51.     ODNVMethod    void        OpenResFile();
  52.     ODNVMethod    void        CloseResFile();
  53.     ODNVMethod    void        CreateResFile();
  54.  
  55. Note that  CreateResFile cannot be used after Create is called.
  56.  
  57.  
  58. Methods you can call anytime after calling Specify or SetAsciiName
  59.  
  60.     ODNVMethod    ODBoolean    IsEqualTo(PlatformFile* file);
  61.  
  62. This method returns kODTrue if the two objects refers to the same file. This is more than just a pointer comparison.
  63.  
  64. Lock state of the file
  65.  
  66.     ODNVMethod    ODBoolean    IsLocked();
  67.     ODNVMethod    void        Lock();
  68.     ODNVMethod    void        Unlock();
  69.  
  70. Stationery attribute of the file
  71.  
  72.     ODNVMethod    ODBoolean    IsStationery();
  73.     ODNVMethod    void        SetStationery(ODBoolean isStationery);
  74.  
  75. Custom icon
  76.  
  77.     ODNVMethod    void        SetCustomIcon(ODBoolean hasCustomIcon);
  78.     ODNVMethod    ODBoolean    HasCustomIcon();
  79.     ODNVMethod    void        SetCustomIconFamily(ODIconFamily icons);
  80.     ODNVMethod    ODIconFamily    GetCustomIconFamily();
  81.  
  82. Finder Flag
  83.  
  84.     ODNVMethod    ODUShort    GetFInfoFlags();
  85.  
  86. Desktop DB comment field
  87.  
  88.     ODNVMethod    ODIText*    GetComments(ODIText* comments = kODNULL);
  89.     ODNVMethod    void        SetComments(ODIText* comments);
  90.  
  91. Special functions
  92.  
  93.     ODNVMethod    ODBoolean    IsDirectory();
  94.  
  95. This method shows whether the platform file refers to a directory.
  96.  
  97.     ODNVMethod    ODBoolean    Exists();
  98.  
  99. This method shows whether the file this platform file object refers to exists or not.
  100.  
  101.     ODNVMethod    void        FlushVolume();
  102.  
  103. This method flushes the content of the file to the volume.
  104.  
  105.     ODNVMethod    void        MoveToTrash() ;
  106.  
  107. This method moves the file this object is referring to the trash. This object will then be retargeted to refer to the file in trash.
  108.  
  109.     ODNVMethod    void        Move( ODSLong targetParID ) ;
  110.  
  111. This mac-specific method moves the file this object is referring to to the specified directory.
  112.  
  113.  
  114.     ODNVMethod    void        MoveRename( ODFileSpec* newSpec, ODBoolean isDuplicate ) ;
  115.  
  116. This method moves a file to the new location as specified by newSpec. If isDuplicate is on, this method performs a copy operation.
  117.  
  118.     ODNVMethod    void        SetContainerType(ODContainerType containerType);
  119.  
  120. This method sets the OpenDoc-specific container type for the file.
  121.     ODNVMethod    void    UniquifyName( ODSShort uniquifyingStringID,
  122.                     StringHandle uniquifyingString,
  123.                     ODSShort uniquifyingNumberID,
  124.                     StringHandle uniquifyingNumberString,
  125.                     short copyCount,
  126.                     PFUniquifyAction action,
  127.                     ODBoolean forceNewName);
  128.  
  129.  
  130. Given in this a platformfile (whose filespec only is used) that may conflict with an existing file, deal with this conflict in one of two ways depending on the value of action.  The two values are:
  131. 1. kSpecifyNewNameOnly: just change the name field of the filespec so that the platform file represents a file that would be unique if created
  132. 2. kRenameInPlace: this file already exists, but we want it to have a different name so we can reuse this one.  Find that name, and rename the actual file.
  133.  
  134. Two string templates are expected, and the caller can either pass in their resource IDs or StringHandles to the strings themselves, signifying the latter with a resource ID of kODNoResourceID.  The first of these strings is used the first time through the renaming loop (which typically sticks something like " copy" on the end of the file name, and the second is used thereafter (when increasingly large numbers are put into the string in an attempt to make it unique.
  135.  
  136.     ODNVMethod    ODULong     GetAllocationBlockSize();
  137.  
  138. This method returns the allocation block size.
  139.  
  140.     ODNVMethod    void        BumpFolderModDate();
  141.  
  142. This method updates the folder modificaiton date.
  143.  
  144.     ODNVMethod    ODBoolean    IsInTrash( );
  145.  
  146. This method returns kODTrue if the file this object refers to is in trash.
  147.  
  148. File name
  149.  
  150.     ODNVMethod    ODName*        GetName();
  151.     ODNVMethod    void        GetAsciiName(char* name,ODULong maxLength);
  152.  
  153. These methods get the file name in various form.
  154.  
  155.     inline        ODULong        GetAsciiNameLength();
  156.  
  157.     ODNVMethod    void        Rename( Str63 name ) ;
  158.  
  159. This method renames a file.
  160.  
  161. Macintosh-specific File attributes
  162.  
  163.     ODNVMethod    ODOSType    GetPlatformCreator();                    // Macintosh specific
  164.     ODNVMethod    ODOSType    GetPlatformType();                    // Macintosh specific
  165.     ODNVMethod    void        SetPlatformType(ODOSType fileType);    // Macintosh specific
  166.     ODNVMethod    ODContainerType        GetContainerType();
  167.  
  168.  
  169. Macintosh-specific Resource access
  170.  
  171.     ODNVMethod    ODPtr        ReadResourcePtr(ODPlatformType resType, ODSShort resID, ODULong* size);         ODNVMethod    void        WriteResourcePtr(ODPlatformType resType, ODSShort resID, 
  172.                             const void *resPtr, ODULong size);    
  173.     ODNVMethod    void        DeleteResource(ODPlatformType resType, ODSShort resID);
  174.  
  175. Date info
  176.  
  177.     ODNVMethod    ODTime        GetFileModDate();
  178.     ODNVMethod    void        SetFileModDate(ODTime date);
  179.     ODNVMethod    ODTime        GetFileCreationDate();
  180.     ODNVMethod    void        SetFileCreationDate(ODTime date);
  181.  
  182.     
  183.  
  184. Methods you must call while the file is open
  185.  
  186. Basic file manipulation
  187.  
  188.     ODNVMethod    void        Close();
  189.  
  190. File position manipulation
  191.  
  192.     ODNVMethod    void        SetFilePos(ODSShort posMode, ODSLong posOff);
  193.     ODNVMethod    ODSLong        GetFilePos();
  194.     ODNVMethod    ODSLong        GetEndOfFile();
  195.     ODNVMethod    void        SetEndOfFile(ODSLong length);
  196.  
  197. Data access
  198.  
  199.     ODNVMethod    void        Read(void* buffer, ODSLong* count);
  200.     ODNVMethod    void        Write(const void* buffer, ODSLong* count);
  201.  
  202. Special functions
  203.  
  204.     inline        ODFileRefNum    GetFileRefNum();
  205.  
  206.     ODNVMethod    void        CopyFrom( PlatformFile* src );
  207.     
  208. This method copies the entire data fork from another file.