There are created some classes to help you to read and/or write to files. They can be used on any kind of files. At the moment there are 3 kinds of file classes and they are: PFile, PCacheFile and PMemoryFile. The PFile class is the main class. It can read and write to a file direct on the disk. If you read some small pieces at the time, the PCacheFile is recommended. It will read a big chunk from the file at once and then memory copy from the cache to the buffer you supply. The last class, the PMemoryFile creates a virtual file in the memory. You can read and write to this file as you want.
The PFile class is the base class. The other two classes, the PCacheFile and PMemoryFile classes, derives from the PFile class. They override the read, write and some other important functions. That means, you can create a function that take a PFile pointer as argument and you can give any of the 3 types in. This is also true, if you want to call another function in the PolyKit package.
There are create some helper functions, so you can read and write big or little endian bytes very easy.
At the moment, the PCacheFile class only have cache on read operations. When you try to write to the file, the cache will be flushed.
Derived from: None
Declared in: PFile.h
PFile(void); PFile(PString fileName, uint16 openFlags); throw(PFileException);
The first version of the constructor will just initialize the class. You then need to call the Open() function to open a file.
The second version will initialize the class and open the file with the open flags you give. See the Open() function to find out what the flags can be.
~PFile()
virtual ~PFile(void);
Closes the file and cleanup.
virtual void Close(void);
This function will close the file you currently have open. You can then call the Open() function to open the same file or a new file.
FileExists()
static bool FileExists(PString fileName); throw(PFileException);
This function will test to see if the file given exists. It will return true if the file exists and false if it doesn't.
GetFileName()
virtual PString GetFileName(void) const; throw(PFileException);
If you have forgot which file you have opened, you can use this function :). It will return the filename without the path.
GetFilePath()
virtual PString GetFilePath(void) const; throw(PFileException);
This function return return the path of the file you have opened. If you have opened the file with a relative path, this function will expand the path, e.g. if the current directory is: /boot/home. If you then open a file with this path: ../MyDir/MyDir2/../MyFile.txt this function will return /boot/MyDir.
GetFileType()
virtual PString GetFileType(void) const; throw(PFileException);
This function return the file type of the file you have opened. The file type is different on the different platforms. On BeOS, the filetype is the mime-string on the file. The function will then return this string. On Windows, the filetype is the file extension. On Linux, it's ???????
GetFullPath()
virtual PString GetFullPath(void) const; throw(PFileException);
This function return return the full path of the file you have opened, which means both the path and filename. If you have opened the file with a relative path, this function will expand the path, e.g. if the current directory is: /boot/home. If you then open a file with this path: ../MyDir/MyDir2/../MyFile.txt this function will return /boot/MyDir/MyFile.txt.
virtual int32 GetLength(void) const; throw(PFileException);
This function will return the length of the file in bytes. It won't move the file pointer and read or write data to the file.
GetPosition()
virtual int32 GetPosition(void) const; throw(PFileException);
This function will return the current position of the file pointer.
IsEOF()
virtual bool IsEOF(void) const;
This function will check to see if you have reached the end of file mark. It will return true if you have and false if you haven't.
IsOpen()
virtual bool IsOpen(void);
This function will check to see if you have a file open. It will return true if you do and false if you don't.
virtual void Open(uint16 openFlags); throw(PFileException); virtual void Open(PString fileName, uint16 openFlags); throw(PFileException);
This function will try to open the file with the flags you give. The first version just open the file with the flags you give. You need to set the filename in the constructor or with the SetFilePath() function.
The second version takes both a filename and the flags to open the file with.
The flags in both functions, is splitted into two parts, an access and flag part. The access part can be one of these and only one:
|
|
pModeRead | Use this if you want to open the file as read only. |
pModeWrite | Use this if you want to open the file as write only. |
pModeReadWrite | Use this if you want to both read and write to the file. |
The flag part can be any of the flags. You just or them into the access part. Here is a list over the flags:
|
|
pModeCreate | If you open a file for writing and this flag is set, a new file is created. If the file already exists, the file will be deleted and an empty file will be created. |
pModeNoTruncate | Use this flag if you want to append to an existing file. When you open the file for writing with this flag set, and the file already exists, the current file is opened. If the file doesn't exists, a new file will be created. |
pModeFailIfExists | Use this flag if you don't want to overwrite an existing file. If this flag is set when you open the file for writing, and the file exists, the open call will fail and throw an exception. If the file doesn't exists, a new file will be created. |
Read()
virtual int32 Read(void *buffer, int32 count); throw(PFileException);
Use this function to read from the file. The arguments are a pointer to a buffer you have allocated by yourself and the size of the buffer. The function will read max the count argument number of bytes. The return value is the number of bytes actual read. This value will be the same as the count value or lower. If the return value is 0, you have reached the end of file mark.
ReadArray_B_UINT16s()
virtual void ReadArray_B_UINT16s(uint16 *buffer, int32 number); throw(PFileException);
This function will read an array of 16-bit numbers from the file and convert them from little big to host format. The arguments are a pointer to the buffer to receive the array and the number of elements in the array.
ReadArray_B_UINT32s()
virtual void ReadArray_B_UINT32s(uint32 *buffer, int32 number); throw(PFileException);
This function will read an array of 32-bit numbers from the file and convert them from big endian to host format. The arguments are a pointer to the buffer to receive the array and the number of elements in the array.
ReadArray_L_UINT16s()
virtual void ReadArray_L_UINT16s(uint16 *buffer, int32 number); throw(PFileException);
This function will read an array of 16-bit numbers from the file and convert them from little endian to host format. The arguments are a pointer to the buffer to receive the array and the number of elements in the array.
ReadArray_L_UINT32s()
virtual void ReadArray_L_UINT32s(uint32 *buffer, int32 number); throw(PFileException);
This function will read an array of 32-bit numbers from the file and convert them from little endian to host format. The arguments are a pointer to the buffer to receive the array and the number of elements in the array.
ReadLine()
virtual PString ReadLine(void); throw(PFileException);
This function is different than the ReadString() function. This function will read from the file until it reach the EOF code or it read a new-line code. The function can handle 0x0a and 0x0d, 0x0a codes. It will then return the string exclusive the new-line code. It can be used to read text files.
virtual void ReadString(char *buffer, int32 number); throw(PFileException); virtual PString ReadString(void); throw(PFileException);
You can read an ascii string with one of these methods. There is a big difference between them. If you use the first one, you need to know the size of the string you want to read. The arguments is a pointer to the buffer to receive the string and the size of the string. The buffer has to be one byte bigger than the size you give. This extra byte will be used to store the null-terminator. The function won't read the null-terminator from the file, so if you have one stored, remember to skip it.
The second version will read the string as it's stored in pascal format. The pascal format contains a 16-bit number with the length of the string and then the string itself without any null-terminator byte. The length number is stored in little endian. The function will read such a string and then return it in a PString object.
Read_B_UINT16()
virtual uint16 Read_B_UINT16(void); throw(PFileException);
This function will read a 16-bit number from the file and convert it from big endian to host format. It will then return the number in host format.
Read_B_UINT32()
virtual uint32 Read_B_UINT32(void); throw(PFileException);
This function will read a 32-bit number from the file and convert it from big endian to host format. It will then return the number in host format.
Read_L_UINT16()
virtual uint16 Read_L_UINT16(void); throw(PFileException);
This function will read a 16-bit number from the file and convert it from little endian to host format. It will then return the number in host format.
Read_L_UINT32()
virtual uint32 Read_L_UINT32(void); throw(PFileException);
This function will read a 32-bit number from the file and convert it from little endian to host format. It will then return the number in host format.
Read_UINT8()
virtual uint8 Read_UINT8(void); throw(PFileException);
This function will read one byte from the file and return it.
Remove()
static void Remove(PString fileName); throw(PFileException);
This function will remove a file. You don't need to create an instance of this class before you can use this function, because it's created as a static function. This means, you don't have to open the file you want to remove. The argument is the name of the file you want to remove.
Rename()
static void Rename(PString oldName, PString newName); throw(PFileException);
This function will rename a file. You don't need to create an instance of this class before you can use this function, because it's created as a static function. This means, you don't have to open the file you want to rename. You give in the name of the file you want to rename and what you want to call it. You can give a path in both the arguments and it the paths are different, the file will be moved. Note that, you can only move the file around on the same partition.
Seek()
virtual int32 Seek(int32 offset, PSeekFlags from); throw(PFileException);
This function will move the file pointer around in the file. The arguments is the number of bytes you want to move and where you want to move the file pointer from. The function will return the new position. The seek flags can be one of these values:
|
|
pSeekBegin | This flag means the offset is the number of bytes from the beginning of the file. |
pSeekCurrent | Use this flag to move the file pointer from it's current position. The offset can both be positive to move it forward and negative to move it backwards. |
pSeekEnd | If you use this flag, you will move the file pointer from the end of the file. The offset has to be a negative number. |
SeekToBegin()
void SeekToBegin(void); throw(PFileException);
This function will move the file pointer to the beginning of the file.
SeekToEnd()
void SeekToEnd(void); throw(PFileException);
This function will move the file pointer to the end of the file.
virtual void SetFilePath(PString newName); throw(PFileException);
This function will change the name in the class to the name you give as the argument. When you open the file, it will open the file you have set with this function. You can only call this function, when you don't have any file opened already.
SetFileType()
virtual void SetFileType(PString newType); throw(PFileException);
This function change the file type of the file you have opened. The file has to be opened with write access. The file type is different on the different platforms. On BeOS, the filetype is the mime-string on the file. The function will then change this string. On Windows, the filetype is the file extension and the function will then rename the file so it have the new extension. On Linux, it's ???????
SetLength()
virtual void SetLength(int32 newLength); throw(PFileException);
If you want to change the file size, you can do it with this function. You have to open the file with write access before you can do it. If you make the file bigger than the current file size, the file will be extended with garbage data. If you make the file smaller, the file will be truncated. The argument is the new file length in bytes.
Write()
virtual int32 Write(const void *buffer, int32 count); throw(PFileException);
Use this function to write some data to the file. The arguments are a pointer to the buffer with the data you want to write and the size of the buffer. The return value is the number of bytes actual written. This value will be the same as the count value or lower, but most of the times, it will be the same.
WriteArray_B_UINT16s()
virtual void WriteArray_B_UINT16s(const uint16 *buffer, int32 number); throw(PFileException);
This function will write an array of 16-bit numbers to the file. The numbers in the array will be converted them from host to big endian. The arguments are a pointer to the buffer with the numbers in host format and the number of elements in the array.
WriteArray_B_UINT32s()
virtual void WriteArray_B_UINT32s(const uint32 *buffer, int32 number); throw(PFileException);
This function will write an array of 32-bit numbers to the file. The numbers in the array will be converted them from host to big endian. The arguments are a pointer to the buffer with the numbers in host format and the number of elements in the array.
WriteArray_L_UINT16s()
virtual void WriteArray_L_UINT16s(const uint16 *buffer, int32 number); throw(PFileException);
This function will write an array of 16-bit numbers to the file. The numbers in the array will be converted them from host to little endian. The arguments are a pointer to the buffer with the numbers in host format and the number of elements in the array.
WriteArray_L_UINT32s()
virtual void WriteArray_L_UINT32s(const uint32 *buffer, int32 number); throw(PFileException);
This function will write an array of 32-bit numbers to the file. The numbers in the array will be converted them from host to little endian. The arguments are a pointer to the buffer with the numbers in host format and the number of elements in the array.
WriteLine()
virtual void WriteLine(PString line); throw(PFileException);
This function is different than the WriteString() function. This function will write the line given to the file. It will also write a new-line code right after the line. The new-line code is 0x0a on BeOS and Linux, but on Windows it's 0x0a, 0x0d.
virtual void WriteString(PString string); throw(PFileException);
This function will write a string in pascal format to the file. The pascal format contains a 16-bit number with the length of the string and then the string itself without any null-terminator byte. The length number is stored in little endian.
Write_B_UINT16()
virtual void Write_B_UINT16(uint16 num); throw(PFileException);
This function will write a 16-bit number to the file. The number will be converted from host to big endian format. The argument is the number in host format.
Write_B_UINT32()
virtual void Write_B_UINT32(uint32 num); throw(PFileException);
This function will write a 32-bit number to the file. The number will be converted from host to big endian format. The argument is the number in host format.
Write_L_UINT16()
virtual void Write_L_UINT16(uint16 num); throw(PFileException);
This function will write a 16-bit number to the file. The number will be converted from host to little endian format. The argument is the number in host format.
Write_L_UINT32()
virtual void Write_L_UINT32(uint32 num); throw(PFileException);
This function will write a 32-bit number to the file. The number will be converted from host to little endian format. The argument is the number in host format.
Write_UINT8()
virtual void Write_UINT8(uint8 num); throw(PFileException);
This function will write one byte to the file. The argument is the byte to write.
Derived from: PFile
Declared in: PFile.h
PCacheFile(uint32 size = 32768); PCacheFile(PString fileName, uint16 openFlags, uint32 size = 32768); throw(PFileException);
The first version of the constructor will just initialize the class. You then need to call the Open() function to open a file.
The second version will initialize the class and open the file with the open flags you give. See the Open() function to find out what the flags can be.
The size argument in both constructors, is the size of the cache in bytes. You can change this if you want. The default value is 32 kb.
~PCacheFile()
virtual ~PCacheFile(void);
Closes the file and cleanup.
Derived from: PFile
Declared in: PFile.h
PMemFile(uint32 growSize = 1024); PMemFile(uint8 *buffer, uint32 size, uint32 growSize = 0);
The first version of the constructor will just initialize the class.
The second version will initialize the class and attach a buffer. This buffer will be used as the file buffer. This can be used if you have a block of memory and you want to read from it as a file. You can then attach the memory block with the constructor or with the Attach() function. The arguments is a pointer to the buffer and the size of the buffer in bytes.
The growSize argument in both constructors, is how many bytes you want the file to grow by when you write to it. If this value is 0, the buffer won't grow and when the buffer is full, a disk full error will be thrown as an exception.
You don't need to call the Open() function, because the file will be opened automatic.
~PMemFile()
virtual ~PMemFile(void);
Closes the file and cleanup.
void Attach(uint8 *buffer, uint32 size, uint32 growSize = 0);
This function will attach a buffer and use it as the file data. You can't attach a buffer when there is a buffer already attached. When you have attached a buffer, this buffer will be freed with a delete[] call when you call the Close() function or when the object is destroyed. If you want to free the buffer by yourself, you need to detach the buffer with the Detach() function before you close the file.
uint8 *Detach(void);
This function will detach the file buffer from the class and return a pointer to it. You then have to free the buffer by yourself with a delete[] call. If you want the length of the buffer, you can call the GetLength() function before you detach the buffer.