Main Index : Reference :

BaseFile

Description

Definition

class BaseFile
{
public:
  BaseFile();

  [bool] Open([Filename] fn, [[int] mode = GE_READ], 
              [[int] err_dlg = FILE_IGNOREOPEN], [[int] order = GE_MOTOROLA], 
              [[int] type = 'C4DC'], [[int] creator = 'C4D1']);
  
  [int] GetPosition();
  [int] GetLength();
  [int] GetError();

  [bool] ReadBytes([bytes] mem, [int] n);
  [bool] WriteBytes([bytes] mem, [int] n);
  
  [string] ReadString([int] n, [[int] mode = GE_XBIT]);
  [bool] WriteString([string] str, [[int] mode = GE_XBIT]);

  [int] ReadChar();
  [int] ReadUChar();
  [int] ReadWord();
  [int] ReadUWord();
  [int] ReadLong();
  [int] ReadULong();
  [float] ReadReal();
  [float] ReadLReal();

  [bool] WriteChar([int] c);
  [bool] WriteUChar([int] c);
  [bool] WriteWord([int] w);
  [bool] WriteUWord([int] w);
  [bool] WriteLong([int] l);
  [bool] WriteULong([int] l);
  [bool] WriteReal([float] f);
  [bool] WriteLReal([float] f);

  [bool] Seek([int] position, [bool] relative);
}

Explanation

This class gives direct access for reading and writing bytes on a disk. For convenience there are functions like SetReal() or GetUWord(). For reading and writing ASCII files one can use Read/WriteString(). This function converts the internal Unicode representation into ASCII file chars. As default one should always use GE_XBIT which guarantees compatibility with foreign languages like Chinese or Japanese. Only for special file formats that are not able to handle unicode (like DXF) one should use the other options.

Members

Open( fn, [mode], [err_dlg], [order], [type], [creator] )

[bool] Open([Filename] fn, [[int] mode = GE_READ], 
            [[int] err_dlg = FILE_IGNOREOPEN], [[int] order = GE_MOTOROLA], 
            [[int] type = 'C4DC'], [[int] creator = 'C4D1']);

Opens the file specified by the file name fn. The file mode is given by the mode parameter. Possible values are:

Mode	Explanation
GE_READ	Opens the file for reading.
GE_WRITE	Creates a new file for writing. If the file name points to an existing file, it will be overwritten!
GE_APPEND	Opens an existing file for writing and sets the position to the end of that file.

Normally, CINEMA 4D shows an error dialog if anything went wrong when opening the file. One can change that behaviour with the err_dlg parameter. The possible options are:

Mode	Explanation
FILE_NODIALOG	Never shows an error dialog.
FILE_DIALOG	Shows an error dialog for all errors.
FILE_IGNOREOPEN	Doesn't show an error dialog if the file doesn't exist, otherwise like FILE_DIALOG.

The byte ordering is specified by the order parameter:

Value	Platform	Byte ordering
GE_MOTOROLA	Motorola	big endian
GE_INTEL	Intel	little endian

Finally, if opening a file for writing on the mac, one can specify the file creator and file type. This option has no effect on other platforms, so by specifying these parameters one can make sure that one's plugin works everywhere.

The function returns TRUE if the file was successfully opened.

GetPosition()

Returns the current position within the file.

GetLength()

Returns the length of the opened file.

GetError()

If any of the other member functions return FALSE, one can use this function to see what went wrong. Possible return values are:

Value	Explanation
FILEERROR_NONE	No error.
FILEERROR_OPEN	Problems opening the file.
FILEERROR_CLOSE	Problems closing the file.
FILEERROR_READ	Problems reading from the file.
FILEERROR_WRITE	Problems writing to the file.
FILEERROR_SEEK	Problems while seeking in the file.
FILEERROR_INVALID	Invalid operation, e.g. writing in read mode.
FILEERROR_MEMORY	Not enough memory.

ReadBytes( mem, n )

Reads n bytes from the current position in the file into the byte array mem. Returns TRUE if successful.

WriteBytes( mem, n )

Writes n bytes from the byte array mem to the current position in the file. Returns TRUE if successful.

ReadString( n, [mode] )

Reads n characters from the current position in the file and returns them in a string. One can control how the text is interpreted with the mode parameter. The possible options are:

Mode	Explanation
GE_XBIT	Reads UTF-8 encoded Unicode text. Each character can be either one or two bytes long.
GE_8BIT	Reads the text as 8-bit ASCII. Discards Unicode information
GE_7BIT	Reads the text as 7-bit ASCII. Doesn't understand any international characters, for example åäüö.
GE_7BITHEX	Reads the text as 7-bit ASCII, but translates any 16-bit characters encoded in the text, for example as "\uEFA0".

WriteString( str, [mode] )

Writes the string str at the current position in the file. One can control how special characters are handled with the mode parameter. The possible options are:

Mode	Explanation
GE_XBIT	Writes UTF-8 encoded Unicode text. Each character can be either one or two bytes long.
GE_8BIT	Writes the text as 8-bit ASCII. Any Unicode information in the original string is lost, for example Chinese characters.
GE_7BIT	Writes the text as 7-bit ASCII. Any international characters in the string, for example åäüö, are lost as well.
GE_7BITHEX	Reads the text as 7-bit ASCII, but encodes any 16-bit characters in the string as text, for example "\uEFA0".

ReadChar()

Reads an 8-bit char from the current position in the file and returns it as an integer.

ReadUChar()

Reads an unsigned 8-bit char from the current position in the file and returns it as an integer.

ReadWord()

Reads a 16-bit word from the current position in the file and returns it as an integer.

ReadUWord()

Reads an unsigned 16-bit word from the current position in the file and returns it as an integer.

ReadLong()

Reads a 32-bit long from the current position in the file and returns it as an integer.

ReadULong()

Reads an unsigned 32-bit long from the current position in the file and returns it as an integer.

ReadReal()

Reads a 32-bit real from the current position in the file and returns it as a float.

ReadLReal()

Reads a 64-bit long real from the current position in the file and returns it as a float.

WriteChar( c )

Writes the integer c at the current position in the file as an 8-bit char. Returns TRUE if successful.

WriteUChar( c )

Writes the integer c at the current position in the file as an unsigned 8-bit char. Returns TRUE if successful.

WriteWord( w )

Writes the integer w at the current position in the file as a 16-bit word. Returns TRUE if successful.

WriteUWord( w )

Writes the integer w at the current position in the file as an unsigned 16-bit word. Returns TRUE if successful.

WriteLong( l )

Writes the integer l at the current position in the file as a 32-bit long. Returns TRUE if successful.

WriteULong( l )

Writes the integer l at the current position in the file as an unsigned 32-bit long. Returns TRUE if successful.

WriteReal( f )

Writes the float f at the current position in the file as a 32-bit real. Returns TRUE if successful.

WriteLReal( f )

Writes the float f at the current position in the file as a 64-bit long real. Returns TRUE if successful.

Seek( position, relative )

Seeks (i.e. changes the position within the file) to position. If relative is TRUE, the position is given relative to the current position. Returns TRUE if successful.

Remember: This function is very slow when used intensively and should therefore be avoided. It's never a good idea jumping around in a file and making the disk cache useless. Unfortunately some file formats (like DXF or TIF) need this feature.

Example

// Creates a filename that points to "foo.txt" in the plugin's directory
var filename = GeGetRootFilename();
filename->RemoveLast();
filename->Add("foo.txt");

// Creates the file and writes a string to it
var file = new(BaseFile);
file->Open(filename, GE_WRITE);
file->WriteString("Hello World!");

// Opens the same file and reads it
var file = new(BaseFile);
file->Open(filename, GE_READ);
var myString = file->ReadString(file->GetLength());