home *** CD-ROM | disk | FTP | other *** search
/ RISC DISC 1 / RISC_DISC_1.iso / pd_share / code / desklib / !DeskLib / h / File < prev    next >
Encoding:
Text File  |  1994-05-29  |  13.3 KB  |  402 lines
  1. /*
  2.     ####             #    #     # #
  3.     #   #            #    #       #          The FreeWare C library for
  4.     #   #  ##   ###  #  # #     # ###             RISC OS machines
  5.     #   # #  # #     # #  #     # #  #   ___________________________________
  6.     #   # ####  ###  ##   #     # #  #
  7.     #   # #        # # #  #     # #  #    Please refer to the accompanying
  8.     ####   ### ####  #  # ##### # ###    documentation for conditions of use
  9.     ________________________________________________________________________
  10.  
  11.     File:    File.h
  12.     Author:  Copyright © 1993, 1994 Jason Williams and Tim Browse
  13.     Version: 1.01 (02 Mar 1994)
  14.     Purpose: Low level file operations, much faster than stdio equivalents,
  15.              and more convenient when interacting with other code that uses
  16.              RISC OS file handles to refer to files.
  17.              Also sundry useful macros and functions to make file
  18.              handling a bit easier.
  19. */
  20.  
  21.  
  22. #ifndef __dl_file_h
  23. #define __dl_file_h
  24.  
  25. #ifdef __cplusplus
  26. extern "C" {
  27. #endif
  28.  
  29. #ifndef __dl_core_h
  30. #include "Core.h"
  31. #endif
  32.  
  33. #ifndef __dl_swi_h
  34. #include "SWI.h"
  35. #endif
  36.  
  37.  
  38. extern os_error *file_lasterror;
  39.  
  40. /*  IMPORTANT NOTE
  41.  *  file_lasterror is used to provide a more convenient SWI veneer for certain
  42.  *  file operations (Open, reading, etc, return handles/values directly,
  43.  *  rather than you having to provide the address of a variable for the
  44.  *  returned value, leaving no convenient way of returning errors!)
  45.  *
  46.  *  Thus, file_lasterror is set by the file operations:
  47.  *    Open, Close, EOF, Read8/32/Bytes, Write8/32/Bytes, Seek, ReturnPos
  48.  *
  49.  *  However, note that it is just a pointer to the error returned by the SWI
  50.  *  call, so it MUST be used immediately after the call, or else it may be
  51.  *  invalid or possibly even dangerously corrupted
  52.  *  If for example, you wish to close the file before reporting the error,
  53.  *  you must first copy the error into your own os_error block.
  54.  *
  55.  *  If no error occurred on the last file op, file_lasterror will be NULL.
  56.  *  Most of the above functions also return values (filehandle = NULL etc)
  57.  *  that will indicate when an error may have occurred, at which time you
  58.  *  can interrogate file_lasterror to work out what the error was.
  59.  *
  60.  *  Note also that all of the above calls which do not have a specific
  61.  *  return value (Close, Write*, Seek) return the os_error pointer directly
  62.  *  as well as setting file_lasterror, for convenience.
  63.  */
  64.  
  65.  
  66.  /*  File_Delete
  67.   *  Attempts to delete the named file. Use carefully!
  68.   */
  69. extern os_error *File_Delete(char *filename);
  70.  
  71.  
  72.  /*  File_Size
  73.   *  Reads the size (in bytes) of the file. A return value of 0 indicates
  74.   *  either the file is 0 bytes long, or an error occurred (which usually
  75.   *  means that the file doesn't exist)
  76.   */
  77. extern int File_Size(char *filename);
  78.  
  79.  
  80. /*  File_Exists
  81.  *  This returns TRUE if the file exists.
  82.  *  (It attempts to open the file for reading - it returns TRUE if successful)
  83.  */
  84. extern BOOL File_Exists(char *filename);
  85.  
  86.  
  87.  
  88. typedef int file_position;
  89. typedef int file_handle;
  90.  
  91. #define file_READERROR (-1)
  92.  
  93.  
  94.  /*  file_access values
  95.   *  These are used when opening files. NOTE that they correspond directly
  96.   *  to OS_File opening flags (OS_File register 0 entry value)
  97.   */
  98.  
  99. typedef enum
  100. {
  101.   file_READ   = 0x40,          /* Open the file for reading                 */
  102.   file_WRITE  = 0x80,          /* CREATE/WIPE the file, open it for writing */
  103.   file_APPEND = 0xC0           /* Open for appending to existing file. NOTE
  104.                                 * that I don't have the PRMs so I can't tell
  105.                                 * you where this puts the initial file pointer
  106.                                 */
  107. } file_access;
  108.  
  109.  
  110.  /*  File_Open
  111.   *  Opens the given file for reading or writing (see file_access's above)
  112.   *  Returns the file handle, or NULL if it failed
  113.   *  (if NULL, you can check file_lasterror for the reason)
  114.   *
  115.   *  NOTE that the OS will return a NULL file handle if we try to open a
  116.   *  non existent file, but does NOT flag this as an error (i.e. File_Open
  117.   *  returns NULL, but file_lasterror is ALSO NULL). You must therefore
  118.   *  check file_lasterror before blindly trying to use it to report an error.
  119.   */
  120. extern file_handle File_Open(char *filename, file_access access);
  121.  
  122.  
  123.  /*  File_Close
  124.   *  Closes an open file stream, using the handle returned by File_Open
  125.   *  After a close, the file_handle is no longer valid, so do not try
  126.   *  to use it.
  127.   */
  128. extern os_error *File_Close(file_handle handle);
  129.  
  130.  
  131.  /*  File_EOF
  132.   *  Returns TRUE if the end of the file has been reached
  133.   */
  134. extern BOOL File_EOF(file_handle handle);
  135.  
  136.  
  137.  /*  File_Seek
  138.   *  Seeks the file pointer to the given position (an offset in terms of
  139.   *  bytes offset from the start of the file). Subsequent read/write
  140.   *  operations will read from or write to that part of the file.
  141.   */
  142. extern os_error *File_Seek(file_handle handle, file_position position);
  143.  
  144.  
  145.  /*  File_ReturnPos
  146.   *  Returns the current file pointer position.
  147.   *  This is a value which, when passed to File_Seek, will return you to the
  148.   *  same position you were at when you called File_ReturnPos
  149.   */
  150. extern file_position File_ReturnPos(file_handle handle);
  151.  
  152.  
  153.  /*  File_WriteBytes
  154.   *  This writes a chunk of data to the current position in a file opened
  155.   *  for writing. 'numbytes' bytes will be written from the given buffer.
  156.   *  It is important to check for errors from this call as Disc Full errors
  157.   *  are a common occurrence.
  158.   */
  159. extern os_error *File_WriteBytes(file_handle handle,
  160.                                  void *buffer, int numbytes);
  161.  
  162.  
  163.  /*  File_ReadBytes
  164.   *  Reads the given number of bytes of data from the given file, into the
  165.   *  given buffer. Returns the number of bytes NOT successfully read.
  166.   *  (i.e. if you hit EOF during the read, the return value will be non-zero)
  167.   */
  168. extern int File_ReadBytes(file_handle handle, void *buffer, int numbytes);
  169.  
  170.  
  171.  /*  File_Write8
  172.   *  Writes an 8-bit value (a byte/char) to the given output file.
  173.   */
  174. extern os_error *File_Write8(file_handle handle, int byte);
  175.  
  176. #define File_WriteByte File_Write8
  177. #define File_WriteChar File_Write8
  178.  
  179.  
  180.  /*  File_Read8
  181.   *  Reads an 8-bit value (a byte/char) from the given input file.
  182.   *  If an error (typically EOF) occurs during the read, file_READERROR
  183.   *  will be returned.
  184.   *
  185.   *  VERY IMPORTANT NOTE!
  186.   *  DO NOT use File_Read8() in a line like the following:
  187.   *    shortvalue = File_Read8(infile) | (File_Read8(infile) << 8);
  188.   *
  189.   *  The problem here is that the C compiler is allowed to evaluate the 2
  190.   *  functions in any order it sees fit, so may read the two bytes in the
  191.   *  incorrect order. You MUST therefore do such an operation with code
  192.   *  in the following form if you are to sure it will work:
  193.   *    shortvalue = File_Read8(infile);
  194.   *    shortvalue |= File_Read8(infile) << 8;
  195.   */
  196. extern int File_Read8(file_handle handle);
  197.  
  198. #define File_ReadByte File_Read8
  199. #define File_ReadChar File_Read8
  200.  
  201.  
  202.  /*  File_Write32
  203.   *  Writes an 32-bit value (a word/int/long) to the given output file.
  204.   */
  205. extern os_error *File_Write32(file_handle handle, int word);
  206.  
  207. #define File_WriteWord File_Write32
  208. #define File_WriteInt  File_Write32
  209. #define File_WriteLong File_Write32
  210.  
  211.  
  212.  /*  File_Read32
  213.   *  Reads a 32-bit value (a word/int/long) from the given input file.
  214.   *  If an error (typically EOF) occurs during the read, file_READERROR
  215.   *  will be returned. (Note that this is a perfectly legal value to read
  216.   *  from the file, though, so you should check file_lasterror to see if
  217.   *  an error occurred).
  218.   */
  219. extern int File_Read32(file_handle handle);
  220.  
  221. #define File_ReadWord File_Read32
  222. #define File_ReadInt  File_Read32
  223. #define File_ReadLong File_Read32
  224.  
  225.  
  226.  /*  File_Read32R
  227.   *  Identical to File_Read32, but reverses the byte ordering as it reads
  228.   *  (converts from little endian to big endian format). This is very useful
  229.   *  for reading textual tags from files, as they can then be compared to
  230.   *  integer constants of the form 'aTag' rather than having to reverse the
  231.   *  byte order manually (i.e. using the tag 'gaTa' which is less human
  232.   *  readable)
  233.   */
  234. extern int File_Read32R(file_handle handle);
  235. #define File_ReadWordR File_Read32R
  236. #define File_ReadIntR  File_Read32R
  237. #define File_ReadLongR File_Read32R
  238.  
  239.  
  240.  /*  File_Write32R
  241.   *  Same as Write32, but reverses the byte order before writing. See
  242.   *  Read32r for more details about why you'd want to do this.
  243.   */
  244. extern os_error *File_Write32R(file_handle handle, int word);
  245.  
  246. #define File_WriteWordR File_Write32R
  247. #define File_WriteIntR  File_Write32R
  248. #define File_WriteLongR File_Write32R
  249.  
  250. /*F**************************************************************************
  251.  
  252.     void File_SetType(char *filename, int type)
  253.  
  254.     Inputs:   filename - name of file to change the type of.
  255.                 type     - the number of the filetype to set.
  256.     Returns:  -
  257.     Purpose:  Change the filetype of a named file.
  258.                 This is actually a macro veneer to a standard RISC OS SWI
  259.                 service (OS_File).
  260.  
  261. ****************************************************************************/
  262.  
  263. extern void File_SetType(char *filename, int type);
  264.  
  265.  
  266. /*F**************************************************************************
  267.  
  268.     int File_GetType(char *filename);
  269.  
  270.     Inputs:   filename - name of the file to be examined.
  271.     Returns:  Filetype of the named file, or -1 if an error occured.
  272.     Purpose:  Obtain the filetype of the specified file.
  273.  
  274. ****************************************************************************/
  275.  
  276. extern int File_GetType(char *filename);
  277.  
  278.  
  279. /****************************************************************************
  280.  
  281.     os_error *File_GetLength(char *filename, int *size_ptr)
  282.  
  283.     Inputs:   filename - name of the file to be examined.
  284.     Outputs:  size_ptr - pointer to an integer variable to hold the file
  285.                                size.
  286.     Returns:  Standard error block.
  287.     Purpose:  Obtain the size (in bytes) of the named file.
  288.                 This is actually a macro veneer to a standard RISC OS SWI
  289.                 service (OS_File).
  290.  
  291. ****************************************************************************/
  292.  
  293. #define File_GetLength(filename, size_ptr) \
  294.   SWI(2, 5, OS_File, 5, (filename), NULL, NULL, NULL, NULL, (size_ptr))
  295.  
  296.  
  297. /****************************************************************************
  298.  
  299.     BOOL File_IsDirectory(char *pathname)
  300.  
  301.     Inputs:   pathname - name of object to check
  302.     Returns:  TRUE if the named object is a directory, FALSE if not, or an
  303.                 error occured.
  304.     Purpose:  Determine if a filing system object is a directory.
  305.  
  306. ****************************************************************************/
  307.  
  308. extern BOOL File_IsDirectory(char *pathname);
  309.  
  310.  
  311. /*
  312.  * Macro to extract the filetype from the values returned from RISC OS
  313.  * routines.
  314.  */
  315.  
  316.  
  317. /****************************************************************************
  318.  
  319.     os_error *File_LoadTo(char *filename, void *address, int *size );
  320.  
  321.     Inputs:   filename - Filename of file to be loaded
  322.               address  - Address at which the file is to be loaded
  323.               size     - NULL, or place to recieve the size of the file on exit
  324.     Outputs:  size, if non-NULL, will contain the file size on exit
  325.     Returns:  NULL, or an error
  326.     Purpose:  Loads the given file at the given address. Be very careful
  327.               to ensure that there is enough safe memory at this address
  328.               to accomodate the file.
  329.  
  330. ****************************************************************************/
  331.  
  332. extern os_error *File_LoadTo(char *filename, void *address, int *size );
  333.  
  334.  
  335.  
  336. #define FILETYPE(x) (((x) & 0xFFF00) >> 8)
  337.  
  338.  
  339. /*
  340.  * #defines for some common filetypes.
  341.  */
  342.  
  343. #define FILETYPE_AIM          0x004
  344. #define FILETYPE_CLEAR         0x690
  345. #define FILETYPE_DEGAS         0x691
  346. #define FILETYPE_IMG          0x692
  347. #define FILETYPE_AMIGAIFF   0x693
  348. #define FILETYPE_MACPAINT   0x694
  349. #define FILETYPE_GIF          0x695
  350. #define FILETYPE_PCX          0x697
  351. #define FILETYPE_QRT          0x698
  352. #define FILETYPE_MTV          0x699
  353. #define FILETYPE_CADSOFT    0x69A
  354. #define FILETYPE_IRLAM         0x69B
  355. #define FILETYPE_BMP          0x69C
  356. #define FILETYPE_TARGA         0x69D
  357. #define FILETYPE_PBMPlus    0x69E
  358. #define FILETYPE_ZVDA         0x69F
  359. #define FILETYPE_ALARMS     0xAE9
  360. #define FILETYPE_DRAWFILE   0xAFF
  361. #define FILETYPE_BBCROM     0xBBC
  362. #define FILETYPE_AUDIOWRK   0xBD6
  363. #define FILETYPE_RENDPIC    0xD58
  364. #define FILETYPE_ARCHIVE    0xDDC
  365. #define FILETYPE_PROART     0xDE2
  366. #define FILETYPE_PICTURE    0xDFA
  367. #define FILETYPE_PRNTDEFN   0xFC6
  368. #define FILETYPE_DOSDISC    0xFC8
  369. #define FILETYPE_SUNRASTR   0xFC9
  370. #define FILETYPE_DEVICE     0xFCC
  371. #define FILETYPE_CACHE      0xFCF
  372. #define FILETYPE_PCEMCONF   0xFD0
  373. #define FILETYPE_DEBIMAGE   0xFD3
  374. #define FILETYPE_TASKEXEC   0xFD6
  375. #define FILETYPE_TASKOBEY   0xFD7
  376. #define FILETYPE_MAKEFILE   0xFE1
  377. #define FILETYPE_DOS          0xFE4
  378. #define FILETYPE_DESKTOP    0xFEA
  379. #define FILETYPE_OBEY         0xFEB
  380. #define FILETYPE_TEMPLATE   0xFEC
  381. #define FILETYPE_PALETTE    0xFED
  382. #define FILETYPE_TIFF         0xFF0
  383. #define FILETYPE_CONFIG     0xFF2
  384. #define FILETYPE_PRINTOUT   0xFF4
  385. #define FILETYPE_POSCRIPT   0xFF5
  386. #define FILETYPE_FONT         0xFF6
  387. #define FILETYPE_BBCFONT    0xFF7
  388. #define FILETYPE_ABSOLUTE   0xFF8
  389. #define FILETYPE_SPRITE     0xFF9
  390. #define FILETYPE_MODULE     0xFFA
  391. #define FILETYPE_BASIC         0xFFB
  392. #define FILETYPE_UTILITY    0xFFC
  393. #define FILETYPE_DATA         0xFFD
  394. #define FILETYPE_COMMAND    0xFFE
  395. #define FILETYPE_TEXT         0xFFF
  396.  
  397. #ifdef __cplusplus
  398. }
  399. #endif
  400.  
  401. #endif
  402.