LFile

Description File support
Header file LFile.h
Author Camil Demetrescu, Andrea Ribichini
Created Nov 17, 2001
Last updated Nov 29, 2003

 

Contents


Introduction

The component LFile provides support for file management. Operations include file creation, rename and destruction, read, write, etc.


Interface

Constants

LFile_ID
    
LFile_CANT_OPEN_FILE
LFile_IO_ERROR

LFile_CANT_REMOVE_FILE
LFile_CANT_RENAME_FILE
  
LFile_READ
LFile_WRITE
LFile_READ_WRITE
  
LFile_START
LFile_CURR
LFile_END
  
LFile_MAX_PATHNAME_LEN

Types

LFile
LFile_SearchHandle
LFile_Info {
    Bool  mIsDir;
    LTime mCreated;
    LTime mLastMod;
}
  
LFile_TOpenMode
LFile_TSeekMode

Functions

LFile*              LFile_Open          (const i1* inFileName, LFile_TOpenMode inMode);
void                LFile_Close         (LFile** ThisA);
  
void                LFile_Write         (LFile* This, const void* inData, ui4 inSize);
ui4                 LFile_Read          (LFile* This, void* outData, ui4 inSize);
  
void                LFile_WriteXPBlock  (LFile* This, LXPBlock* inBlock);
LXPBlock*           LFile_ReadXPBlock   (LFile* This, ui4 inSize);
  
void                LFile_WriteN1       (LFile* This, const void* inVal);
void                LFile_WriteN2       (LFile* This, const void* inVal);
void                LFile_WriteN4       (LFile* This, const void* inVal);
void                LFile_WriteN8       (LFile* This, const void* inVal);
  
void                LFile_ReadN1        (LFile* This, void* outVal);
void                LFile_ReadN2        (LFile* This, void* outVal);
void                LFile_ReadN4        (LFile* This, void* outVal);
void                LFile_ReadN8        (LFile* This, void* outVal);
  
void                LFile_WriteString   (LFile* This, i1* inBuf);
ui4                 LFile_ReadString    (LFile* This, i1* outBuf, ui4 inBufSize, i1* inTerminator);
  
Bool                LFile_Seek          (LFile* This, i4 inOffset, LFile_TSeekMode inMode);
ui4                 LFile_Tell          (LFile* This);
ui4                 LFile_GetSize       (LFile* This);
  
Bool                LFile_Exists        (const i1* inFileName);
void                LFile_Remove        (const i1* inFileName);
void                LFile_Rename        (const i1* inOldFileName, const i1* inNewFileName);
void                LFile_GetTempName   (i1* outFileName);
  
void                LFile_CutPath       (i1 thruPathName[LFile_MAX_PATHNAME_LEN]);
void                LFile_CutName       (i1 thruPathName[LFile_MAX_PATHNAME_LEN]);
void                LFile_CutPathNameExt(i1 thruPathName[LFile_MAX_PATHNAME_LEN]);
  
LFile_SearchHandle* LFile_FindFirst     (const i1* inSearchPath, i1* outFileName);
Bool                LFile_FindNext      (LFile_SearchHandle* inHandle, i1* outFileName);
void                LFile_FindClose     (LFile_SearchHandle** ThisA);
Bool                LFile_GetFileInfo   (const i1* inFileName, LFile_Info* outInfo);

Bool                LFile_CreateDir     (const i1* inCompletePath);
Bool                LFile_RemoveDir     (const i1* inCompletePath);


API Reference

Function Arguments Description Returns Throws
Open const i1* inFileName

Open file specified by the pathname inFileName with mode inMode. Open mode may be one of the following:

inMode Effect
READ open file for reading only. The file must exist.
WRITE open file for writing only. If the file does not exist, it is created.
READ_WRITE open file for both reading and writing. If the file does not exist, it is created.

The current file position after the operation is zero. The created object provides access to the open file. Caller is responsible of dellocating the created object using LFile_Close.

Pointer to newly created LFile object.

CANT_OPEN_FILE
if operation fails.
TOpenMode inMode
Close LFile** ThisA Close the file associated to the object *ThisA.*ThisA is set to NULL. - -
Write LFile* This Write to the file This the memory segment of size inSize pointed by inData. The current file position is advanced by inSize bytes after the operation. - IO_ERROR
if operation fails.

const void* inData

ui4 inSize
WriteXPBlock LFile* This Write content of cross platform block inBlock to file This.The current file position is advanced by inBlock->GetSize() bytes after the operation. - IO_ERROR
if operation fails.
LXPBlock* inBlock
Read

LFile* This

Read from the file This inSize bytes and copy them in buffer pointed by outData. Caller must make sure that buffer is large enough to hold inSize bytes. The current file position is advanced by inSize bytes after the operation. Number of bytes read. -
void* outData
ui4 inSize
ReadXPBlock LFile* This Read from the file This inSize bytes and write them to a newly created LXPBlock object. The current file position is advanced by inSize bytes after the operation. Caller is responsible of deallocating the created LXPBlock object using LXPBlock_Delete. Pointer to a new LXPBlock object.

IO_ERROR
if read operation fails.

LMemory_OUT_OF_MEMORY
if memory allocation fails.

ui4 inSize
WriteN1
WriteN2
WriteN4
WriteN8
LFile* This

Write to the file This a number of size 1, 2, 4, or 8 bytes stored in buffer inVal. Numbers of size >1 byte are written to file in big endian format. The current file position is advanced by 1,2,4, or 8 bytes after the operation.

Use this function ... to write values of these types
WriteN1 i1, ui1
WriteN2 i2, ui2
WriteN4 i4, ui4, f4
WriteN8 f8
-

IO_ERROR
if operation fails.

const void* inVal
ReadN1
ReadN2
ReadN4
ReadN8
LFile* This

Read from the file This a number of size 1, 2, 4, or 8 bytes and copy it to buffer pointed by outVal.Caller must make sure that buffer is large enough to hold the value. Numbers of size >1 byte in the file are expected to be stored in big endian format. The current file position is advanced by 1,2,4, or 8 bytes after the operation.

Use this function ... to read values of these types
WriteN1 i1, ui1
WriteN2 i2, ui2
WriteN4 i4, ui4, f4
WriteN8 f8
-

IO_ERROR
if operation fails.

void* outVal
WriteString LFile* This Writes to file This the null-terminated C string pointed to by inBuf. The null terminator is not written to the file.The file position is advanced by the number of written bytes. - -
i1* inBuf
ReadString LFile* This

Reads from file This a sequence of characters until a character in the string inTerminator is reached. In any case, no more than inBufSize characters are read. The file position is advanced by the number of read bytes.

- -
i1* outBuf
ui4 inBufSize
i1* inTerminator
Seek LFile* This

Move current position in the file This by inOffsetbytes starting from the position specified by inMode:

inMode Position relative to
START beginning of the file
CURR current position in the file
END end of the file

true if resulting position is valid.

false otherwise.

-
i4 inOffset
TSeekMode inMode
Tell LFile* This - Current position in file This.

IO_ERROR
if operation fails.

GetSize LFile* This Compute the current size of file This. Size in bytes of the file This. -
Exists const i1* inFileName Check if a file inFileName exists. true if file exists, false otherwise. -
Remove const i1* inFileName Remove file inFileName. -

CANT_REMOVE_FILE
if operation fails.

Rename const i1* inOldFileName Change name of file inOldFileName to inNewFileName. -

CANT_RENAME_FILE
if operation fails.

const i1* inNewFileName
GetTempName i1* outFileName Copy to buffer outFileName a unique file name that can be used to create temporary files. The size of the buffer outFileName should be at least MAX_PATHNAME_LEN bytes. - -
CutPath i1 thruPathName
[LFile_MAX_PATHNAME_LEN]
Removes the path portion of a pathname, leaving only the file name, if any. The function modifies the passed buffer. - -
CutName i1 thruPathName
[LFile_MAX_PATHNAME_LEN]
Removes the file name portion of a pathname, leaving only the path portion, if any. The function modifies the passed buffer. - -
CutPathNameExt i1 thruPathName
[LFile_MAX_PATHNAME_LEN]
Removes the file extension, if any. The function modifies the passed buffer. - -
FindFirst const i1* inSearchPath Creates a new search handle (to be used in subsequent FindNext calls). inSearchPath allows the standard wildcard characters (* and ?). If the function doesn't return a NULL value, the name of the first file that matches the search path will be copied onto outFileName. LFile_SearchHandle* -
i1* outFileName
FindNext LFile_SearchHandle* inHandle If the function succeeds, it returns True and copies the name of the next file that matches inHandle's search path onto outFileName. Otherwise it returns False. Bool -
i1* outFileName
FindClose LFile_SearchHandle** ThisA Deletes a search handle. void -
GetFileInfo const i1* inFileName Fills a LFile_Info struct with a file's attributes (whether it's a file or a directory, its creation and last modification dates). If the function succeeds it returns True, otherwise it returns False. Bool -
LFile_Info* outInfo
CreateDir const i1* inCompletePath Creates a new directory. If the function succeeds it returns True, otherwise it returns False. Bool -
RemoveDir const i1* inCompletePath Removes an empty directory. If the function succeeds it returns True, otherwise it returns False. Bool -


Revision history