The Datafile PD-CD 5

home *** CD-ROM | disk | FTP | other *** search

/ The Datafile PD-CD 5 / DATAFILE_PDCD5.iso / utilities / d / desklib / !DeskLib / h_doc / Filing < prev next >

Wrap

Text File | 1997-01-22 | 27.9 KB | 730 lines

/* #### # # # # # # # # # The FreeWare C library for # # ## ### # # # # ### RISC OS machines # # # # # # # # # # # ___________________________________ # # #### ### ## # # # # # # # # # # # # # # Please refer to the accompanying #### ### #### # # ##### # ### documentation for conditions of use ________________________________________________________________________ File: Filing.h Author: Copyright © 1994, 1995 Sergio Monesi, Julian Smith Version: 1.04 (27 Aug 1995) Purpose: Easy access to files informations, directory scans, filenames handling. Mods: 06 Jun 1995 - changed some procedure names to a more DeskLib-compliant style 15 Jul 1995 - added Desk_Filing_CanonicalisePath 27 Aug 1995 - made Desk_Filing_ScanDir and Desk_Filing_ScanDirByDir reentrant. Added Desk_Filing_SingleDirEntry and Desk_Filing_SingleDirEntry2 13 Sep 1995 - JS - Added 'void *reference' to Desk_Filing_ScanDir and Desk_Filing_ScanDirByDir. Added Desk_filing_scan_PRUNE. Renamed the function-pointer typedefs used in Desk_Filing_ScanDir and Desk_Filing_ScanDirByDir. 21 Sep 1995 - JS - Added Desk_Filing_CompareDates. 17 Dec 1996 - JS - Added Desk_Filing_OpenDir2(). 22 Jan 1997 - JS - Desk_Filing_CloseDir now returns void. */ #ifndef __Desk_Filing_h #define __Desk_Filing_h #ifdef __cplusplus extern "C" { #endif #ifndef __Desk_Core_h #include "Desk.Core.h" #endif #ifndef Desk_filing_MAXLEAFNAMELEN #define Desk_filing_MAXLEAFNAMELEN 32 /* MACRO: Constant: Desk_filing_MAXLEAFNAMELEN Purpose: The maximum length of a leafname (ie. the filename without the path) that can be stored in a Desk_filing_direntry or Desk_filing_fulldirentry structure. A value of 13 is enough for FileCore based filing system (like ADFS, IDEFS, SCSI, etc.) and for DOS discs. A value of 32 seems to be reasonable for every filing system. You can #define it before including this header if you want to be sure that it is set to the desired value (ie. even if someone changes this header, your value will be still valid). SeeAlso: Desk_filing_direntry; Desk_filing_fulldirentry; */ #endif typedef enum { Desk_filing_NOTFOUND = 0, Desk_filing_FILE = 1, Desk_filing_DIRECTORY = 2, Desk_filing_IMAGEFILE = 3 } Desk_filing_objtype; /* Purpose: Object types. Fields: - SeeAlso: Desk_filing_direntry; Desk_filing_fulldirentry; */ typedef struct { int loadaddr; int execaddr; int length; int attrib; Desk_filing_objtype objtype; char name[ Desk_filing_MAXLEAFNAMELEN]; } Desk_filing_direntry; /* Purpose: Contains file informations (read from directory) Fields: Auto-explicatives... SeeAlso: Desk_filing_fulldirentry; */ typedef struct { int loadaddr; int execaddr; int length; int attrib; Desk_filing_objtype objtype; int SIN; char date[ 5]; char name[ Desk_filing_MAXLEAFNAMELEN]; } Desk_filing_fulldirentry; /* Purpose: Contains full file informations (read from directory) Fields: Auto-explicatives... SeeAlso: Desk_filing_direntry; */ typedef enum { Desk_readdirtype_DIRENTRY, Desk_readdirtype_FULLDIRENTRY, Desk_readdirtype_NAMEONLY } Desk_filing_readdirtype; /* Purpose: These are the way in which the objects in a directory can be read using Desk_Filing_ReadDir function. Fields: Desk_readdirtype_DIRENTRY - reads Desk_filing_direntry objects Desk_readdirtype_FULLDIRENTRY - reads Desk_filing_fulldirentry objects Desk_readdirtype_NAMEONLY - reads just the names of the files SeeAlso: Desk_filing_direntry; Desk_filing_fulldirentry; Desk_Filing_OpenDir; Desk_Filing_ReadDir; */ typedef struct { char *dirname; void *buf; int size; Desk_filing_readdirtype type; union { Desk_filing_direntry *direntry; Desk_filing_fulldirentry *fulldirentry; char *name; void *act; } act; int offset; int read; char *match; } Desk_filing_dirdata; /* Purpose: Contains the data needed by Desk_Filing_OpenDir, Desk_Filing_ReadDir and Desk_Filing_CloseDir. It is automatically filled by Desk_Filing_OpenDir and updated by Desk_Filing_ReadDir. It should not be used by the user, apart from the 'act' field that should be used to read the current object. Fields: The fields should be ignored since they are for internal use. The only important field is: act - this union contains the current object that will be returned by Desk_Filing_ReadDir. Remember that you should only use the type chosen when you called Desk_Filing_OpenDir SeeAlso: Desk_filing_direntry; Desk_filing_fulldirentry; Desk_filing_readdirtype; Desk_Filing_OpenDir; Desk_Filing_ReadDir; Desk_Filing_CloseDir; */ void Desk_Filing_OpenDir( const char *dirname, Desk_filing_dirdata *dirdata, int bufsize, Desk_filing_readdirtype type); /* Purpose: Prepares a directory to be read with Desk_Filing_ReadDir (ie. allocates the buffer and set the starting parameters). After the directory has been read, Desk_Filing_CloseDir should be called to free the buffer. Inputs: dirname - the directory pathname dirdata - a pointer to a (already allocated!) structure that will be filled in by the function bufsize - the size of the buffer that should be allocated. Note that the buffer will be allocated by Desk_Filing_OpenDir itself, you just have to give it the size, so that you can save some memory (but remember that, the bigger the buffer, the faster the reading). bufsize should be at least the size of Desk_filing_direntry, Desk_filing_fulldirentry or leafname maxlength, depending on the type you want to read type - the type of data you want to read from the directory using Desk_Filing_ReadDir Outputs: - Returns: NULL if no error, otherwise the error generated by RISC OS. If an error is returned, the buffer is not allocated Errors: The following custom errors could be returned (apart from the RISC OS generated ones): &00801C00 - Out of memory &00801C01 - Directory is actually a file &00801C02 - Directory doesn't exist SeeAlso: Desk_filing_direntry; Desk_filing_fulldirentry; Desk_filing_readdirtype; Desk_Filing_ReadDir; Desk_Filing_CloseDir; */ void Desk_Filing_OpenDir2( const char *dirname, Desk_filing_dirdata *dirdata, int bufsize, Desk_filing_readdirtype type, const char* wildcard); /* As Desk_Filing_OpenDir, except it accepts a wildcarded leafname specifier. */ void *Desk_Filing_ReadDir( Desk_filing_dirdata *dirdata); /* Purpose: Reads the directory content, one object each call. Desk_Filing_OpenDir must be called before this and Desk_Filing_CloseDir must be called when there are no more entries to read Inputs: dirdata - a pointer to a structure that defines the directory that will be read. This structure should have been already filled by Desk_Filing_OpenDir Outputs: - Returns: The next object to read in the directory or NULL if finished. The returned value is a pointer to a Desk_filing_direntry, Desk_filing_fulldirentry or char depending from the type set with Desk_Filing_OpenDir Errors: Generally no errors should be caused by this function, since they should be already discovered by Desk_Filing_OpenDir. Anyway, if something strange happens, a NULL pointer will be returned SeeAlso: Desk_Filing_OpenDir; Desk_Filing_CloseDir; Desk_filing_direntry; Desk_filing_fulldirentry; Desk_filing_readdirtype; */ void Desk_Filing_CloseDir( Desk_filing_dirdata *dirdata); /* Purpose: Closes a directory after it has been opened with Desk_Filing_OpenDir and read with Desk_Filing_ReadDir. This function frees the buffer allocated by Desk_Filing_OpenDir. This function can be called more than once for the same dirdata - calls after the first will have ano effect. This can simplify error handling. Inputs: dirdata - a pointer to a structure that defines the directory that will be closed. Outputs: - Returns: - Errors: - SeeAlso: Desk_Filing_OpenDir; Desk_Filing_ReadDir; Desk_filing_direntry; Desk_filing_fulldirentry; Desk_filing_readdirtype; */ void Desk_Filing_ReadDirNames( const char *dirname, char *buf, int *number, int *offset, int size, const char *match); /* Purpose: Reads the directory content (only the file names): this function can be called more than once if the content is greater than the size of the buffer. (veneer for SWI Desk_OS_GBPB 9) Inputs: dirname - the directory pathname buf - pointer to a buffer where the content will be stored number - number of elements to read offset - the offset to the first element to read size - the length of the buffer match - (wildcarded) filename to match Outputs: number - the number of elements read offset - the next element to read or -1 if finished Returns: NULL if no error, otherwise the error returned by RISC OS Errors: - SeeAlso: Desk_Filing_ReadDirEntry; Desk_Filing_ReadFullDirEntry; */ void Desk_Filing_ReadDirEntry( const char *dirname, Desk_filing_direntry *buf, int *number, int *offset, int size, const char *match); /* Purpose: Reads the directory content: this function can be called more than once if the content is greater than the size of the buffer. (veneer for SWI Desk_OS_GBPB 10) Inputs: dirname - the directory pathname buf - pointer to a buffer where the content will be stored number - number of elements to read offset - the offset to the first element to read size - the length of the buffer match - (wildcarded) filename to match Outputs: number - the number of elements read offset - the next element to read or -1 if finished Returns: NULL if no error, otherwise the error returned by RISC OS Errors: - SeeAlso: Desk_filing_direntry; Desk_Filing_ReadDirNames; Desk_Filing_ReadFullDirEntry; */ void Desk_Filing_ReadFullDirEntry( const char *dirname, Desk_filing_fulldirentry *buf, int *number, int *offset, int size, const char *match); /* Purpose: Reads the directory content (full info version): this function can be called more than once if the content is greater than the size of the buffer. (veneer for SWI Desk_OS_GBPB 11) Inputs: dirname - the directory pathname buf - pointer to a buffer where the content will be stored number - number of elements to read offset - the offset to the first element to read size - the length of the buffer match - (wildcarded) filename to match Outputs: number - the number of elements read offset - the next element to read or -1 if finished Returns: NULL if no error, otherwise the error Errors: Every possible error returned by RISC OS SeeAlso: Desk_filing_fulldirentry; Desk_Filing_ReadDirNames; Desk_Filing_ReadDirEntry; */ void Desk_Filing_ReadCatalogue( const char *filename, Desk_filing_objtype *objtype, int *loadaddr, int *execaddr, int *length, int *attrib, int *filetype); /* Purpose: Reads file informations. (veneer for SWI Desk_OS_File 20) Inputs: filename - the file pathname Outputs: objtype, loadaddr, execaddr, length, attrib, filetype - the desired file informations. If the file doesn't exist, objtype=0 and the other informations are meaningless; no error is returned Returns: NULL if no error, otherwise the error returned by RISC OS Errors: - SeeAlso: - */ void Desk_Filing_SingleDirEntry( const char *filename, Desk_filing_direntry *buf, int size); /* Purpose: Reads a single directory entry. This function uses Desk_Filing_ReadDirEntry() to read the file informations from its directory. Inputs: filename - the file pathname buf - pointer to a buffer where the content will be stored size - the length of the buffer Outputs: - Returns: NULL if no error, otherwise the error. If the file doesn't exist (but its pathname exists!) no error will be returned but objtype in the Desk_filing_fulldirentry structure will be set to 0. If the pathname is illegal or some directory in this path doesn't exist an error will be returned. Errors: Every possible error returned by RISC OS SeeAlso: Desk_filing_direntry; Desk_Filing_ReadDirEntry; Desk_Filing_SingleDirEntry2; Desk_Filing_SingleFullDirEntry; */ void Desk_Filing_SingleDirEntry2( const char *dirname, Desk_filing_direntry *buf, int size, const char *filename); /* Purpose: Reads a single directory entry (dirname and filename splitted). This function uses Desk_Filing_ReadDirEntry() to read the file informations from its directory. Inputs: dirname - the directory pathname buf - pointer to a buffer where the content will be stored size - the length of the buffer filename - the filename (only the leafname!) Outputs: - Returns: NULL if no error, otherwise the error. If the file doesn't exist (but the pathname exists!) no error will be returned but objtype in the Desk_filing_fulldirentry structure will be set to 0. If the pathname is illegal or some directory in it doesn't exist an error will be returned. Errors: - SeeAlso: Desk_filing_direntry; Desk_Filing_ReadDirEntry; Desk_Filing_SingleDirEntry; */ void Desk_Filing_SingleFullDirEntry( const char *filename, Desk_filing_fulldirentry *buf, int size); /* Purpose: Reads a single directory entry (full info version). This function uses Desk_Filing_ReadFullDirEntry() to read the (full) file informations from its directory. This is (for what I know!) the only way to read the SIN of a single file. Inputs: filename - the file pathname buf - pointer to a buffer where the content will be stored size - the length of the buffer Outputs: - Returns: NULL if no error, otherwise the error. If the file doesn't exist (but its pathname exists!) no error will be returned but objtype in the Desk_filing_fulldirentry structure will be set to 0. If the pathname is illegal or some directory in this path doesn't exist an error will be returned. Errors: Every possible error returned by RISC OS SeeAlso: Desk_filing_fulldirentry; Desk_Filing_ReadFullDirEntry; Desk_Filing_SingleFullDirEntry2; Desk_Filing_SingleDirEntry; */ void Desk_Filing_SingleFullDirEntry2( const char *dirname, Desk_filing_fulldirentry *buf, int size, const char *filename); /* Purpose: Reads a single directory entry (full info version, dirname and filename splitted). This function uses Desk_Filing_ReadFullDirEntry() to read the (full) file informations from its directory. This is (for what I know!) the only way to read the SIN of a single file. Inputs: dirname - the directory pathname buf - pointer to a buffer where the content will be stored size - the length of the buffer filename - the filename (only the leafname!) Outputs: - Returns: NULL if no error, otherwise the error. If the file doesn't exist (but the pathname exists!) no error will be returned but objtype in the Desk_filing_fulldirentry structure will be set to 0. If the pathname is illegal or some directory in it doesn't exist an error will be returned. Errors: - SeeAlso: Desk_filing_fulldirentry; Desk_Filing_ReadFullDirEntry; Desk_Filing_SingleFullDirEntry; */ char *Desk_Filing_GetPathname( const char *filename, char *pathname); /* Purpose: Gets the pathname from a filename (ie. strips out the leafname) Inputs: filename - the filename. If this is a NULL pointer nothing will happen pathname - the string that will contain the pathname. If this is a NULL pointer nothing will happen Outputs: pathname - the pathname. If filename is a leafname (ie. no '.'s in it) pathname will be an empty string Returns: pathname Errors: - SeeAlso: Desk_Filing_GetLeafname; Desk_Filing_FindLeafname; */ char *Desk_Filing_GetLeafname( const char *filename, char *leafname); /* Purpose: Gets the leafname from a filename (ie. strips out the path) Inputs: filename - the filename. If this is a NULL pointer nothing will happen leafname - the string that will contain the pathname. If this is a NULL pointer nothing will happen Outputs: leafname - the leafname. If filename is just a leafname itself (ie. no '.'s in it) leafname will be the same as filename Returns: leafname Errors: - SeeAlso: Desk_Filing_FindLeafname; Desk_Filing_GetPathname; */ char *Desk_Filing_FindLeafname( const char *filename); /* Purpose: Finds the leafname inside a full pathname Inputs: filename - the filename. If this is a NULL pointer nothing will happen Outputs: - Returns: a pointer to the leafname (this pointer will be inside filename). If filename is just a leafname (ie. no '.'s in it) the returned value will be filename itself Errors: - SeeAlso: Desk_Filing_GetLeafname; Desk_Filing_GetPathname; */ char *Desk_Filing_MakePath( char *newpath, const char *dirname, const char *leafname); /* Purpose: Constructs the full pathname from the directory and leafname Inputs: newpath - the string that will contain the full pathname dirname - the directory name leafname - the file leafname Outputs: newpath - the desired full pathname (ie. dirname+'.'+leafname) Returns: newpath Errors: - SeeAlso: - */ void Desk_Filing_CanonicalisePath( const char *pathname, char *buffer, int size, int *spare); /* Purpose: Converts a pathname to a canonicalised path (veneer for SWI Desk_OS_FSControl 37) Inputs: pathname - the pathname to convert buffer - pointer to the buffer where the canonicalised path will be stored size - the length of the buffer Outputs: spare - the number of spare bytes in the buffer Returns: Errors: - SeeAlso: - */ typedef Desk_os_error *(*Desk_filing_scan_startdirfn) ( const char *dirname, Desk_filing_fulldirentry *dirdata, void *reference); /* Purpose: The type of functions that are called by Desk_Filing_ScanDir (and similar functions) every time a new directory is scanned. If this functions returns a non-NULL pointer the scan will be aborted and Desk_Filing_ScanDir will return this error. If it returns Desk_filing_scan_PRUNE, the scan will skip the directory. Fields: dirname - the directory name dirdata - the data of the directory (only if available, see Desk_Filing_ScanDir and similar functions) reference - as passed to Desk_Filing_ScanDir. SeeAlso: Desk_Filing_ScanDir; */ typedef Desk_os_error *(*Desk_filing_scan_foundfilefn) ( const char *dirname, Desk_filing_fulldirentry *filedata, void *reference); /* Purpose: The type of functions that are called by Desk_Filing_ScanDir (and similar functions) at every file. If this functions returns a non-NULL pointer the scan will be aborted and Desk_Filing_ScanDir will return this error. Fields: dirname - the directory name filedata - the data of the current file inside the directory reference - as passed to Desk_Filing_ScanDir. SeeAlso: Desk_Filing_ScanDir; */ typedef Desk_os_error *(*Desk_filing_scan_enddirfn) ( const char *dirname, Desk_filing_fulldirentry *dirdata, void *reference); /* Purpose: The type of functions that are called by Desk_Filing_ScanDir (and similar functions) every time the scan of the directory is finished. If this functions returns a non-NULL pointer the scan will be aborted and Desk_Filing_ScanDir will return this error. Fields: dirname - the directory name dirdata - the data of the directory (only if available, see Desk_Filing_ScanDir and similar functions) reference - as passed to Desk_Filing_ScanDir. SeeAlso: Desk_Filing_ScanDir; */ #define Desk_filing_scan_PRUNE ( (Desk_os_error *) 1) /* A Desk_filing_scan_startdirfn should return this if the scan should go no deeper. */ void Desk_Filing_ScanDir( const char *dirname, Desk_filing_scan_startdirfn startdirproc, Desk_filing_scan_foundfilefn foundfileproc, Desk_filing_scan_enddirfn enddirproc, void *reference ); /* Purpose: Scans a directory tree calling the specified functions. This function is reentrant: you can call it from one of the functions it calls. Subdirectories may be scanned before the parent directory has been completely scanned, hence 'startdirproc' may be called more than once before the corresponding 'enddirproc' is called. If you need to end the scan of a directory before starting the scan of a new one you can use Desk_Filing_ScanDirByDir. Inputs: dirname - the directory name where the scan will start startdirproc - the function called every time a new directory is started, including the one specified by 'dirname' (ie. before the files contained in it are scanned). If this is NULL, no function will be called. foundfileproc - the function called every time a new file is found (including directories). If this is NULL, no function will be called. enddirproc - the function called every time a directory scan ends (ie. after all the files contained in it have been scanned). If this is NULL, no function will be called. reference - This is passed to the three functions startdirproc, foundfileproc, enddirproc. Outputs: - Returns: NULL if no error, otherwise the error (generated by RISC OS during the scan or returned by a function) Errors: - SeeAlso: Desk_Filing_ScanDir_StartDir; Desk_Filing_ScanDir_FoundFile; Desk_Filing_ScanDir_EndDir; Desk_Filing_ScanDirByDir; */ void Desk_Filing_ScanDirByDir( const char *dirname, Desk_filing_scan_startdirfn startdirproc, Desk_filing_scan_foundfilefn foundfileproc, Desk_filing_scan_enddirfn enddirproc, void *reference ); /* Purpose: Scans a directory tree calling the specified functions. This function is reentrant: you can call it from one of the functions it calls. When a directory is scanned, 'startdirproc' is called, then 'foundfileproc' is called for every file (including directories) contained in it and then 'enddirproc' is called. Finally, if the directory contained some subdirectory, they will be scanned. If you only need to scan directories and subdirectories in no particular order, see Desk_Filing_ScanDir since it is faster. Unlike Desk_Filing_Scandir, it is easy to prevent Desk_Filing_ScanDirByDir from recursively scan subdirectories: you should just return an error (eg (Desk_os_error *)-1) from 'enddirproc' so that only the files in the first directory will be scanned and then the error will be returned. Inputs: dirname - the directory name where the scan will start startdirproc - the function called every time a new directory is started, including the one specified by 'dirname' (ie. before the files contained in it are scanned). If this is NULL, no function will be called. foundfileproc - the function called every time a new file is found (including directories). If this is NULL, no function will be called. enddirproc - the function called every time a directory scan ends (ie. after all the files contained in it have been scanned). If this is NULL, no function will be called. reference - This is passed to the three functions startdirproc, foundfileproc, enddirproc. Outputs: - Returns: NULL if no error, otherwise the error (generated by RISC OS during the scan or returned by a function) Errors: - SeeAlso: Desk_Filing_ScanDir_StartDir; Desk_Filing_ScanDir_FoundFile; Desk_Filing_ScanDir_EndDir; Desk_Filing_ScanDir; */ int Desk_Filing_CompareDates( char date1[5], char date2[5]); /* Purpose: Compares two 5-byte dates as used in file date-stamps. Inputs: Pointers to two 5-char arrays, eg the 'date' fields from two Desk_filing_fulldirentry structures, or the 'fivebytedate' array filled-in by Desk_File_Date. Returns: +1 if date1 is later than date2. -1 if date1 is earlier than date2. 0 if date1 equals date2. */ #ifdef __cplusplus } #endif #endif