home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 5 / DATAFILE_PDCD5.iso / utilities / d / desklib / !DeskLib / h_doc / File < prev    next >
Encoding:
Text File  |  1996-06-26  |  16.7 KB  |  520 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, Tim Browse, 
  13.                                     Julian Smith, Sergio Monesi,
  14.                                     Jason Howat.
  15.     Version: 1.09 (12 Dec 1995)
  16.     Purpose: Low level file operations, much faster than stdio equivalents,
  17.              and more convenient when interacting with other code that uses
  18.              RISC OS file handles to refer to files.
  19.              Also sundry useful macros and functions to make file
  20.              handling a bit easier.
  21.     Mods:    1.02 (22 Jul 1995) JS Added Desk_File_AllocLoad0().
  22.              1.03 (01 Aug 1995) SM Added Desk_File_ReadExtent().
  23.     
  24.              1.04 (31 Aug 1995) JH A few new filetypes.
  25.              
  26.              1.05 (20 Sep 1995) JS Added Desk_File_CheckError and 
  27.                                    Desk_File_XCheckError
  28.              1.06 (29 Sep 1995) JS Added Desk_File_SaveMemory
  29.              1.07 (31 Oct 1995) BS Changed Desk_File_SetType to be an assembler 
  30.                                    veneer returning (Desk_os_error*)
  31.                                    Added Desk_File_SetLoad, Desk_File_SetExec, Desk_File_CreateDirectory
  32.              1.08 (19 Nov 1995) JS Added Desk_File_AllocLoad
  33.              1.09 (12 Dec 1995) JS Added Desk_File_EnsureDirectory, Desk_File_EnsureParentDirectory
  34.              1.10 (10 Jun 1996) JS Added Desk_File_SaveMemory2 - saves with filetype.
  35.                                 
  36. */
  37.  
  38.  
  39. #ifndef __Desk_File_h
  40. #define __Desk_File_h
  41.  
  42. #ifdef __cplusplus
  43.     extern "C" {
  44. #endif
  45.  
  46. #ifndef __Desk_Core_h
  47.     #include "Desk.Core.h"
  48. #endif
  49.  
  50. #ifndef __Desk_SWI_h
  51.     #include "Desk.SWI.h"
  52. #endif
  53.  
  54. #ifndef __Desk_Error2_h
  55.     #include "Desk.Error2.h"
  56. #endif
  57.  
  58. /*
  59. extern void    Desk_file_lasterror;
  60. Removed - Desk doesn't need this.
  61. */
  62. /*
  63.  *  IMPORTANT NOTE
  64.  *  Desk_file_lasterror is used to provide a more convenient SWI veneer for certain
  65.  *  file operations (Open, reading, etc, return handles/values directly,
  66.  *  rather than you having to provide the address of a variable for the
  67.  *  returned value, leaving no convenient way of returning errors!)
  68.  *
  69.  *  Thus, Desk_file_lasterror is set by the file operations:
  70.  *    Open, Close, EOF, Read8/32/Bytes, Write8/32/Bytes, Seek, ReturnPos
  71.  *
  72.  *  However, note that it is just a pointer to the error returned by the SWI
  73.  *  call, so it MUST be used immediately after the call, or else it may be
  74.  *  invalid or possibly even dangerously corrupted
  75.  *  If for example, you wish to close the file before reporting the error,
  76.  *  you must first copy the error into your own Desk_os_error block.
  77.  *
  78.  *  If no error occurred on the last file op, Desk_file_lasterror will be NULL.
  79.  *  Most of the above functions also return values (filehandle = NULL etc)
  80.  *  that will indicate when an error may have occurred, at which time you
  81.  *  can interrogate Desk_file_lasterror to work out what the error was.
  82.  *
  83.  *  Note also that all of the above calls which do not have a specific
  84.  *  return value (Close, Write*, Seek) return the Desk_os_error pointer directly
  85.  *  as well as setting Desk_file_lasterror, for convenience.
  86.  */
  87.  
  88.  
  89. extern void    Desk_File_Delete( const char *filename);
  90. /*
  91.  *  Attempts to delete the named file. Use carefully!
  92.  */
  93.  
  94.  
  95. extern int Desk_File_Size( const char *filename);
  96. /*
  97.  *  Reads the size (in bytes) of the file. A return value of 0 indicates
  98.  *  either the file is 0 bytes long, or an error occurred (which usually
  99.  *  means that the file doesn't exist)
  100.  */
  101.  
  102.  
  103. extern Desk_bool Desk_File_Exists( const char *filename);
  104. /*
  105.  *  This returns Desk_bool_TRUE if the file exists.
  106.  *  (It attempts to open the file for reading - it returns Desk_bool_TRUE if successful)
  107.  */
  108.  
  109.  
  110.  
  111. typedef int Desk_file_position;
  112. typedef int Desk_file_handle;
  113.  
  114. #define Desk_file_READERROR (-1)
  115.  
  116.  
  117. typedef enum
  118. {
  119.   Desk_file_READ   = 0x40,          /* Open the file for reading                 */
  120.   Desk_file_WRITE  = 0x80,          /* CREATE/WIPE the file, open it for writing */
  121.   Desk_file_APPEND = 0xC0           /* Open for appending to existing file. NOTE
  122.                                 * that I don't have the PRMs so I can't tell
  123.                                 * you where this puts the initial file pointer
  124.                                 */
  125. } Desk_file_access;
  126. /*
  127.  *  These are used when opening files. NOTE that they correspond directly
  128.  *  to Desk_OS_File opening flags (Desk_OS_File register 0 entry value)
  129.  */
  130.  
  131.  
  132. extern Desk_file_handle Desk_File_Open( const char *filename, Desk_file_access access);
  133. /*
  134.  *  Opens the given file for reading or writing (see Desk_file_access's above)
  135.  *  Returns the file handle, or NULL if it failed
  136.  *  (if NULL, you can check Desk_file_lasterror for the reason)
  137.  *
  138.  *  NOTE that the OS will return a NULL file handle if we try to open a
  139.  *  non existent file, but does NOT flag this as an error (i.e. Desk_File_Open
  140.  *  returns NULL, but Desk_file_lasterror is ALSO NULL). You must therefore
  141.  *  check Desk_file_lasterror before blindly trying to use it to report an error.
  142.  */
  143.  
  144.  
  145. extern void    Desk_File_Close(Desk_file_handle handle);
  146. /*
  147.  *  Closes an open file stream, using the handle returned by Desk_File_Open
  148.  *  After a close, the Desk_file_handle is no longer valid, so do not try
  149.  *  to use it.
  150.  */
  151.  
  152.  
  153. extern Desk_bool Desk_File_EOF(Desk_file_handle handle);
  154. /*
  155.  *  Returns Desk_bool_TRUE if the end of the file has been reached
  156.  */
  157.  
  158.  
  159. extern void    Desk_File_Seek(Desk_file_handle handle, Desk_file_position position);
  160. /*
  161.  *  Seeks the file pointer to the given position (an offset in terms of
  162.  *  bytes offset from the start of the file). Subsequent read/write
  163.  *  operations will read from or write to that part of the file.
  164.  */
  165.  
  166.  
  167. extern Desk_file_position Desk_File_ReturnPos(Desk_file_handle handle);
  168. /*
  169.  *  Returns the current file pointer position.
  170.  *  This is a value which, when passed to Desk_File_Seek, will return you to the
  171.  *  same position you were at when you called Desk_File_ReturnPos
  172.  */
  173.  
  174.  
  175. extern int Desk_File_ReadExtent(Desk_file_handle handle);
  176. /*
  177.  *  Returns the current file extent (or -1 if an error occurrs)
  178.  */
  179.  
  180.  
  181. extern void    Desk_File_WriteBytes(Desk_file_handle handle,
  182.                                  const void *buffer, int numbytes);
  183. /*
  184.  *  This writes a chunk of data to the current position in a file opened
  185.  *  for writing. 'numbytes' bytes will be written from the given buffer.
  186.  *  It is important to check for errors from this call as Disc Full errors
  187.  *  are a common occurrence.
  188.  */
  189.  
  190.  
  191. extern int Desk_File_ReadBytes(Desk_file_handle handle, void *buffer, int numbytes);
  192. /*
  193.  *  Reads the given number of bytes of data from the given file, into the
  194.  *  given buffer. Returns the number of bytes NOT successfully read.
  195.  *  (i.e. if you hit EOF during the read, the return value will be non-zero)
  196.  */
  197.  
  198.  
  199. extern void    Desk_File_Write8(Desk_file_handle handle, int byte);
  200. /*
  201.  *  Writes an 8-bit value (a byte/char) to the given output file.
  202.  */
  203.  
  204. #define Desk_File_WriteByte Desk_File_Write8
  205. #define Desk_File_WriteChar Desk_File_Write8
  206.  
  207.  
  208. extern int Desk_File_Read8(Desk_file_handle handle);
  209.  /*
  210.   *  Reads an 8-bit value (a byte/char) from the given input file.
  211.   If this is first attempt to read beyond end of file, Desk_file_READERROR
  212.   *  will be returned. Subsequent attempts will result in an Error2 error being generated.
  213.   (See PRM 2-60, this behaviour mirrors OS_BGet).
  214.   *
  215.   *  VERY IMPORTANT NOTE!
  216.   *  DO NOT use Desk_File_Read8() in a line like the following:
  217.   *    shortvalue = Desk_File_Read8(infile) | (Desk_File_Read8(infile) << 8);
  218.   *
  219.   *  The problem here is that the C compiler is allowed to evaluate the 2
  220.   *  functions in any order it sees fit, so may read the two bytes in the
  221.   *  incorrect order. You MUST therefore do such an operation with code
  222.   *  in the following form if you are to sure it will work:
  223.   *    shortvalue = Desk_File_Read8(infile);
  224.   *    shortvalue |= Desk_File_Read8(infile) << 8;
  225.   */
  226.  
  227. #define Desk_File_ReadByte Desk_File_Read8
  228. #define Desk_File_ReadChar Desk_File_Read8
  229.  
  230.  
  231. extern void    Desk_File_Write32(Desk_file_handle handle, int word);
  232.  /*
  233.   *  Writes an 32-bit value (a word/int/long) to the given output file.
  234.   */
  235.  
  236. #define Desk_File_WriteWord Desk_File_Write32
  237. #define Desk_File_WriteInt  Desk_File_Write32
  238. #define Desk_File_WriteLong Desk_File_Write32
  239.  
  240.  
  241. extern int Desk_File_Read32(Desk_file_handle handle);
  242.  /*
  243.   *  Reads a 32-bit value (a word/int/long) from the given input file.
  244.   */
  245.  
  246. #define Desk_File_ReadWord Desk_File_Read32
  247. #define Desk_File_ReadInt  Desk_File_Read32
  248. #define Desk_File_ReadLong Desk_File_Read32
  249.  
  250.  
  251. extern int Desk_File_Read32R(Desk_file_handle handle);
  252.  /*
  253.   *  Identical to Desk_File_Read32, but reverses the byte ordering as it reads
  254.   *  (converts from little endian to big endian format). This is very useful
  255.   *  for reading textual tags from files, as they can then be compared to
  256.   *  integer constants of the form 'aTag' rather than having to reverse the
  257.   *  byte order manually (i.e. using the tag 'gaTa' which is less human
  258.   *  readable)
  259.   */
  260.  
  261. #define Desk_File_ReadWordR Desk_File_Read32R
  262. #define Desk_File_ReadIntR  Desk_File_Read32R
  263. #define Desk_File_ReadLongR Desk_File_Read32R
  264.  
  265.  
  266. extern void    Desk_File_Write32R(Desk_file_handle handle, int word);
  267.  /*
  268.   *  Same as Write32, but reverses the byte order before writing. See
  269.   *  Read32r for more details about why you'd want to do this.
  270.   */
  271.  
  272. #define Desk_File_WriteWordR Desk_File_Write32R
  273. #define Desk_File_WriteIntR  Desk_File_Write32R
  274. #define Desk_File_WriteLongR Desk_File_Write32R
  275.  
  276.  
  277. extern void    Desk_File_SetType( const char *filename, int type);
  278. /*
  279. Inputs:   filename - name of file to change the type of.
  280.             type     - the number of the filetype to set.
  281. Returns:  pointer to Desk_os_error if an error occurred, or NULL.
  282. Purpose:  Change the filetype of a named file.
  283.             This is an assembler veneer to the standard RISC OS SWI
  284.             service (Desk_OS_File 18).
  285. */
  286.  
  287.  
  288.  
  289. extern void    Desk_File_SetLoad( const char *filename, int load);
  290. /*
  291. Sets load address of the specified file.
  292.  
  293. Assembler veneer onto Desk_OS_File 2.
  294.  */
  295.  
  296. extern void    Desk_File_SetExec( const char *filename, int exec);
  297. /*
  298. Sets execute address of the specified file.
  299.  
  300. Assembler veneer onto Desk_OS_File 3.
  301.  */
  302.  
  303. extern void    Desk_File_CreateDirectory( const char *dirname);
  304. /*
  305. Creates the specified directory.
  306.  
  307. Assembler veneer onto Desk_OS_File 8.
  308.  */
  309.  
  310.  
  311.  
  312. extern int Desk_File_GetType( const char *filename);
  313. /*
  314. Inputs:   filename - name of the file to be examined.
  315. Returns:  Filetype of the named file.
  316. Purpose:  Obtain the filetype of the specified file.
  317. */
  318.  
  319. /*
  320. #define Desk_File_GetLength(filename, Desk_size_ptr) \
  321.   Desk_SWI2(2, 5, Desk_SWI_OS_File, 5, (filename), NULL, NULL, NULL, NULL, (Desk_size_ptr))
  322. */
  323. int    Desk_File_GetLength( const char* filename);
  324. /*
  325. Inputs:   filename - name of the file to be examined.
  326. Returns:  Size of file.
  327. Purpose:  Obtain the size (in bytes) of the named file.
  328. */
  329.  
  330.  
  331. extern Desk_bool Desk_File_IsDirectory( const char *pathname);
  332. /*
  333. Inputs:   pathname - name of object to check
  334. Returns:  Desk_bool_TRUE if the named object is a directory, Desk_bool_FALSE if not, or an
  335.             error occured.
  336. Purpose:  Determine if a filing system object is a directory.
  337. */
  338.  
  339.  
  340. /*
  341.  * Macro to extract the filetype from the values returned from RISC OS
  342.  * routines.
  343.  */
  344.  
  345.  
  346. extern void    Desk_File_LoadTo( const char *filename, void *address, int *size );
  347. /*
  348. Inputs:   filename - Filename of file to be loaded
  349.           address  - Address at which the file is to be loaded
  350.           size     - NULL, or place to recieve the size of the file on exit
  351. Outputs:  size, if non-NULL, will contain the file size on exit
  352. Returns:  NULL, or an error
  353. Purpose:  Loads the given file at the given address. Be very careful
  354.           to ensure that there is enough safe memory at this address
  355.           to accomodate the file.
  356. */
  357.  
  358.  
  359. extern void Desk_File_Date( const char *filename, char *fivebytedate);
  360. /*
  361. Inputs:   filename     - Filename of file to be loaded
  362. Outputs:  fivebytedata - will contain the date stamp
  363. Returns:  -
  364. Purpose:  Reads the datestamp of a file into a five byte block
  365. */
  366.  
  367.  
  368.  
  369. extern char*    Desk_File_AllocLoad( const char* filename, int* lengthptr);
  370. /*
  371. This allocates space for the file, and loads it. The length of the file
  372. is put into 'lengthptr', if it isn't NULL.
  373.  
  374. Returns a pointer to the loaded file, or NULL if an error occurred.
  375. */
  376.  
  377.  
  378.  
  379. extern char*    Desk_File_AllocLoad0( const char *filename);
  380. /*
  381. This allocates space for the file, loads it, and appends a '\0'. The
  382. intention is to allow text-files to be loaded and dealt with as strings.
  383.  
  384. Returns a pointer to the loaded file, or NULL if an error occurred.
  385. */
  386.  
  387.  
  388. extern int Desk_File_printf(Desk_file_handle file, const char *format, ...);
  389. /*
  390. Inputs:   file   - output stream
  391.           format - a printf style format string
  392.           ...    - extra parameters as described in the format string
  393. Outputs:  -
  394. Returns:  The number of characters written (-ve for error)
  395. Purpose:  Equivalent of fprintf(), but uses RISC OS file handles instead
  396.           of FILE pointer to reference the file.
  397. Notes:    This uses a 512 character buffer to compose the string to be
  398.           output; if your string overflows this, your program will crash.
  399. */
  400.  
  401.  
  402. extern int Desk_File_ReadExtent(Desk_file_handle handle);
  403. /*
  404. Returns the current file extent (or -1 if an error occurrs)
  405. */
  406.  
  407.  
  408.  
  409.  
  410.  
  411. void    Desk_File_SaveMemory2( const char* filename, void* buffer, int size, int filetype);
  412. /*
  413. Saves memory to a filename, with a filetype.
  414. Treat like:
  415. void    Desk_File_SaveMemory( char *filename, void *buffer, Desk_size_t size, int filetype);
  416.  */
  417.  
  418.  
  419.  
  420. #define Desk_File_SaveMemory( filename, buffer, size)    Desk_File_SaveMemory2( filename, buffer, size, 0xfff)
  421. /*
  422. Saves memory to a filename.
  423. Treat like:
  424. void    Desk_File_SaveMemory( char *filename, void *buffer, size_t size);
  425.  */
  426.  
  427.  
  428. void    Desk_File_EnsureDirectory( const char* path);
  429. /*
  430. Ensures that the specified directory exists - any required parent
  431. directories are also created.
  432.  */
  433.  
  434.  
  435. void    Desk_File_EnsureParentDirectory( const char* filename);
  436. /*
  437. Uses Desk_File_EnsureDirectory to ensure that the parent of 'filename'
  438. exists.
  439.  */
  440.  
  441.  
  442.  
  443.  
  444.  
  445. #define Desk_FILETYPE(x) (((x) & 0xFFF00) >> 8)
  446.  
  447.  
  448. /*
  449.  * #defines for some common filetypes.
  450.  */
  451.  
  452. #define Desk_filetype_AIM          0x004
  453. #define Desk_filetype_CLEAR         0x690
  454. #define Desk_filetype_DEGAS         0x691
  455. #define Desk_filetype_IMG          0x692
  456. #define Desk_filetype_AMIGAIFF   0x693
  457. #define Desk_filetype_MACPAINT   0x694
  458. #define Desk_filetype_GIF          0x695
  459. #define Desk_filetype_PCX          0x697
  460. #define Desk_filetype_QRT          0x698
  461. #define Desk_filetype_MTV          0x699
  462. #define Desk_filetype_CADSOFT    0x69A
  463. #define Desk_filetype_IRLAM         0x69B
  464. #define Desk_filetype_BMP          0x69C
  465. #define Desk_filetype_TARGA         0x69D
  466. #define Desk_filetype_PBMPlus    0x69E
  467. #define Desk_filetype_ZVDA         0x69F
  468. #define Desk_filetype_MSX2       0x6A0
  469. #define Desk_filetype_RLE        0x6A1
  470. #define Desk_filetype_COLORIX    0x6A2
  471. #define Desk_filetype_FITS       0x6A3
  472. #define Desk_filetype_HAWKV9     0x6A4
  473. #define Desk_filetype_REPLAY     0xAE7
  474. #define Desk_filetype_ALARMS     0xAE9
  475. #define Desk_filetype_DRAWFILE   0xAFF
  476. #define Desk_filetype_BBCROM     0xBBC
  477. #define Desk_filetype_AUDIOWRK   0xBD6
  478. #define Desk_filetype_RENDPIC    0xD58
  479. #define Desk_filetype_ARCHIVE    0xDDC
  480. #define Desk_filetype_PROART     0xDE2
  481. #define Desk_filetype_PICTURE    0xDFA
  482. #define Desk_filetype_PRNTDEFN   0xFC6
  483. #define Desk_filetype_DOSDISC    0xFC8
  484. #define Desk_filetype_SUNRASTR   0xFC9
  485. #define Desk_filetype_DEVICE     0xFCC
  486. #define Desk_filetype_CACHE      0xFCF
  487. #define Desk_filetype_PCEMCONF   0xFD0
  488. #define Desk_filetype_DEBIMAGE   0xFD3
  489. #define Desk_filetype_TASKEXEC   0xFD6
  490. #define Desk_filetype_TASKOBEY   0xFD7
  491. #define Desk_filetype_MAKEFILE   0xFE1
  492. #define Desk_filetype_DOS          0xFE4
  493. #define Desk_filetype_DESKTOP    0xFEA
  494. #define Desk_filetype_OBEY         0xFEB
  495. #define Desk_filetype_TEMPLATE   0xFEC
  496. #define Desk_filetype_PALETTE    0xFED
  497. #define Desk_filetype_TIFF         0xFF0
  498. #define Desk_filetype_CONFIG     0xFF2
  499. #define Desk_filetype_PRINTOUT   0xFF4
  500. #define Desk_filetype_POSCRIPT   0xFF5
  501. #define Desk_filetype_FONT         0xFF6
  502. #define Desk_filetype_BBCFONT    0xFF7
  503. #define Desk_filetype_ABSOLUTE   0xFF8
  504. #define Desk_filetype_SPRITE     0xFF9
  505. #define Desk_filetype_MODULE     0xFFA
  506. #define Desk_filetype_BASIC         0xFFB
  507. #define Desk_filetype_UTILITY    0xFFC
  508. #define Desk_filetype_DATA         0xFFD
  509. #define Desk_filetype_COMMAND    0xFFE
  510. #define Desk_filetype_TEXT         0xFFF
  511. #define Desk_filetype_HTML    0xFAF
  512.  
  513.  
  514.  
  515. #ifdef __cplusplus
  516. }
  517. #endif
  518.  
  519. #endif
  520.