就业培训     下载中心     Wiki     联络 登录   注册

---

注意

To delete a file see GeFKill() and the accompanying File Functions Manual .

Allocation/Deallocation

BaseFile objects are created with the usual tools, see Entity Creation and Destruction Manual (Classic) .

• BaseFile::Alloc() : Creates a new BaseFile 对象。
• BaseFile::Free() : Destroys a BaseFile 对象。

Opening and Closing

After allocating a BaseFile object, BaseFile::Open() needs to be called to bind it to a file in the filesystem (either an existing or a new one).

• BaseFile::Open() : Opens a file, several flags influence the mode, initial position of read/write pointer, error reporting behavior and certain system specific options.
  • Parameter "mode":
    • FILEOPEN::READ : The file is opened for reading, only. Read/write pointer is set to start of file. This is the default mode, if none gets specified.
    • FILEOPEN::WRITE : The file is opened for writing, only. Read/write pointer is set to start of file. Any existing file will be overwritten.
    • FILEOPEN::READWRITE : The file is opened for read and write access. Read/write pointer is set to start of file.
    • FILEOPEN::APPEND : The file is opened for writing, only. Read/write pointer is set to end of file.
  • Parameter "error_dialog":
    • FILEDIALOG::NONE : No dialog will be shown on error. To be used if working with files in a context, where no dialogs are allowed, or to implement a custom error notification for users.
    • FILEDIALOG::ANY : A dialog will be shown on every file error.
    • FILEDIALOG::IGNOREOPEN : A dialog will be shown on every file error, except if the file does not exist. This is the default option.
  • Parameter (byte-)"order":
    • The byte order comes into play, if for example numeric values wider than a byte get read or stored (e.g. ReadInt32() and WriteInt32()). Usually you don't have to care much about this. When dealing with your own files, just make sure to use the same byte order on writing and reading. When handling arbitrary 3rd party file types, the byte order usually gets specified in the format documentation. The byte order can also be changed after opening the file using BaseFile::SetOrder() .
    • BYTEORDER::V_MOTOROLA : Big endian byte order.
    • BYTEORDER::V_INTEL : Little endian byte order.
  • Parameter (file-)"type":
    • This parameter is only relevant for OSX and defines the type of file created.
  • Parameter (file-)"creator":
    • This parameter is only relevant for OSX and should be left at its default in most cases.
• BaseFile::Close() : Closes a file. In most cases this is not needed, as the file will be automatically closed, when the BaseFile object gets destroyed.

Read and Write

Most commonly the following functions are used to store data in a "BaseContainer"-like fashion, where one does not need to worry about the size of datatypes or positioning the read/write pointer.

A Typical Write Access

• Allocate a BaseFile object with BaseFile::Alloc() (or of course AutoAlloc ).
• Open a file using BaseFile::Open() , either creating a new one or opening an existing one.
• Simply write data into the file, see below. Cinema 4D will take care of the read/write pointer automatically.
• Close the file using BaseFile::Close() . This step is actually optional, as the file will also be closed when the BaseFile object gets destroyed.

注意

The order of write accesses will determine the order of read accesses (the order will need to be the same).

// Let user select a target directory. Filename fn; if (!fn. FileSelect ( FILESELECTTYPE::ANYTHING , FILESELECT::DIRECTORY , "Select a directory..." _s)) return maxon::OK ; fn += Filename { "myfile.dat" }; AutoAlloc<BaseFile> file; if (file == nullptr ) return maxon::OutOfMemoryError( MAXON_SOURCE_LOCATION );

// Create the file with the purpose of writing into it. // BEWARE: FILEOPEN_WRITE will create a new file, any existing file will be overwritten. if (!file-> Open (fn, FILEOPEN::WRITE , FILEDIALOG::ANY , BYTEORDER::V_INTEL , MACTYPE_CINEMA , MACCREATOR_CINEMA )) return PrintFileError(fn, file, "Failed to create file" _s);

// Write some data into the new file. // Note: The order of data being written needs to be the same, when reading. if (!file-> WriteInt32 (12345678)) return PrintFileError(fn, file, "Failed to write an Int32 into file" _s); if (!file-> WriteString ( "Hello World!" _s)) return PrintFileError(fn, file, "Failed to write a String into file" _s);

// Finally close the file. // Actually not needed, as the file will be closed on destruction of the BaseFile object. file-> 关闭 ();

// This example demonstrates appending typed data to a file.

// Note: The file created via the "BaseFile Create" example is expected in this example. // BEWARE: This code will append data to the file, so be careful, when choosing one.

// Let user select a file. Filename fn; if (!fn. FileSelect ( FILESELECTTYPE::ANYTHING , FILESELECT::LOAD , "Select the file from the BaseFile Create command..." _s)) return maxon::OK ; AutoAlloc<BaseFile> file; if (file == nullptr ) return maxon::OutOfMemoryError( MAXON_SOURCE_LOCATION );

// Open a file with the purpose of appending some data to it. if (!file-> Open (fn, FILEOPEN::APPEND , FILEDIALOG::ANY , BYTEORDER::V_INTEL , MACTYPE_CINEMA , MACCREATOR_CINEMA )) return PrintFileError(fn, file, "Failed to open the file for appending" _s);

// Write some more data into the file. // Note: The order of data being written needs to be the same, when reading. if (!file-> WriteVector64 ( 向量 (10.0, 20.0, 30.0))) return PrintFileError(fn, file, "Failed to write a vector into file" _s);

A Typical Read Access

• Allocate a BaseFile object with BaseFile::Alloc() (or of course AutoAlloc ).
• Open an existing file using BaseFile::Open() .
• Simply read data from the file in the same order it got written before, see below. Cinema 4D will take care of the read/write pointer automatically.
• Close the file using BaseFile::Close() . This step is actually optional, as the file will also be closed when the BaseFile object gets destroyed.

All of the following read/write functions automatically take care of the read/write pointer (i.e. advancing it by the correct amount of bytes depending on the access type) and are able to detect access with wrong data type. Internally this is achieved by not only writing the actual data to the file, but also an additional value header preceding each data, specifying the type and also (where needed) the amount of data.

注意

The order of read accesses has to match the order of write accesses.

These functions can not be used to read data from an arbitrary file, but only from files created by Cinema 4D , when data got written by the respective write functions.

It is not recommended to mix these functions with the byte access functions (see Byte Access ).

// Note: The file created via the "BaseFile Create" or "BaseFile Append" examples is expected in this example.

// Let user select a file. Filename fn; if (!fn. FileSelect ( FILESELECTTYPE::ANYTHING , FILESELECT::LOAD , "Select the file from the BaseFile Create or Append command..." _s)) return maxon::OK ; AutoAlloc<BaseFile> file; if (file == nullptr ) return maxon::OutOfMemoryError( MAXON_SOURCE_LOCATION );

// Open a file with the purpose of reading data from it. if (!file-> Open (fn, FILEOPEN::READ , FILEDIALOG::ANY , BYTEORDER::V_INTEL , MACTYPE_CINEMA , MACCREATOR_CINEMA )) return PrintFileError(fn, file, "Failed to open the file for reading" _s);

// Read data from file. // Note: The order needs to be the same as on write. Int32 value; if (!file-> ReadInt32 (&value)) return PrintFileError(fn, file, "Failed to read an Int32 from file" _s); if (value != 12345678) return PrintFileError(fn, file, "This is not the expected file" _s); ApplicationOutput ( "Int32 read from file: @" _s, value); maxon::String myText; if (!file-> ReadString (&myText)) return PrintFileError(fn, file, "Failed to read from string into file" _s); ApplicationOutput ( "String read from file: @" _s, myText); 向量 vec; if (!file-> ReadVector64 (&vec)) return PrintFileError(fn, file, "Failed to read Vector from file (maybe the append example hasn't been executed)" _s); ApplicationOutput ( "Vector read from file: @" _s, vec);

Char

• BaseFile::ReadChar() : Reads a signed character.
• BaseFile::WriteChar() : Writes a signed character.
• BaseFile::ReadUChar() : Reads an unsigned character.
• BaseFile::WriteUChar() : Writes an unsigned character.

另请参阅 Primitive Data Types Manual (Classic) on Char .

String

• BaseFile::ReadString() : Reads a String .
• BaseFile::WriteString() : Writes a String .

另请参阅 String Manual (Classic) .

Filename

• BaseFile::ReadFilename() : Reads a Filename .
• BaseFile::WriteFilename() : Writes a Filename .

另请参阅 Filename Manual .

Bool

• BaseFile::ReadBool() : Reads a boolean value.
• BaseFile::WriteBool() : Writes a boolean value.

另请参阅 Primitive Data Types Manual (Classic) on Bool .

整数

• BaseFile::ReadInt16() : Reads a signed 16-bit wide integer value.
• BaseFile::WriteInt16() : Writes a signed 16-bit wide integer value.
• BaseFile::ReadUInt16() : Reads an unsigned 16-bit wide integer value.
• BaseFile::WriteUInt16() : Writes an unsigned 16-bit wide integer value.
• BaseFile::ReadInt32() : Reads a signed 32-bit wide integer value.
• BaseFile::WriteInt32() : Writes a signed 32-bit wide integer value.
• BaseFile::ReadUInt32() : Reads an unsigned 32-bit wide integer value.
• BaseFile::WriteUInt32() : Writes an unsigned 32-bit wide integer value.
• BaseFile::ReadInt64() : Reads a signed 64-bit wide integer value.
• BaseFile::WriteInt64() : Writes a signed 64-bit wide integer value.
• BaseFile::ReadUInt64() : Reads an unsigned 64-bit wide integer value.
• BaseFile::WriteUInt64() : Writes an unsigned 64-bit wide integer value.

另请参阅 Primitive Data Types Manual (Classic) on 整数 .

Float

• BaseFile::ReadFloat32() : Reads a 32-bit wide floating point value.
• BaseFile::WriteFloat32() : Writes a 32-bit wide floating point value.
• BaseFile::ReadFloat64() : Reads a 64-bit wide floating point value.
• BaseFile::WriteFloat64() : Reads a 64-bit wide floating point value.

另请参阅 Primitive Data Types Manual (Classic) on Float .

向量

• BaseFile::ReadVector32() : Reads a vector composed of 32-bit wide floating point values.
• BaseFile::WriteVector32() : Writes a vector composed of 32-bit wide floating point values.
• BaseFile::ReadVector64() : Reads a vector composed of 64-bit wide floating point values.
• BaseFile::WriteVector64() : Writes a vector composed of 64-bit wide floating point values.

另请参阅 Vector Manual (Classic) .

矩阵

• BaseFile::ReadMatrix32() : Reads a matrix composed of 32-bit wide floating point values.
• BaseFile::WriteMatrix32() : Writes a matrix composed of 32-bit wide floating point values.
• BaseFile::ReadMatrix64() : Reads a matrix composed of 64-bit wide floating point values.
• BaseFile::WriteMatrix64() : Writes a matrix composed of 64-bit wide floating point values.

另请参阅 Matrix Manual (Classic) .

Byte Access

This is used to read or write files of arbitrary type/structure. For example, if a pure ASCII text file is supposed to be created, the above functions won't work, because no matter what is done (e.g. WriteString(), WriteChar()), there will always be the value headers prepended to the actual data. In such cases the byte access functions may be helpful.

A typical read or write looks like this:

• Allocate a BaseFile object with BaseFile::Alloc() (or of course AutoAlloc ).
• Open a file using BaseFile::Open() , either creating a new one or opening an existing one.
• Reposition the read/write pointer to the position of interest via BaseFile::Seek() .
• Read/Write an arbitrary number of bytes.
• Close the file using BaseFile::Close() . This step is actually optional, as the file will also be closed if the BaseFile gets destroyed.

警告

The byte sequences read or written are not platform independent. For example, when reading the four bytes of an Int32, one will need to know, if the most or the least significant byte is first.

// Typical first bytes of a Cinema 4D scene file (.c4d), just used as an example here. Nobody should rely on this! static const Char testBytes[] = { 'Q' , 'C' , '4' , 'D' , 'C' , '4' , 'D' }; const Int32 numBytes = sizeof (testBytes); Filename fn;

// Let user select a file if (!fn. FileSelect ( FILESELECTTYPE::ANYTHING , FILESELECT::LOAD , "Select a C4D scene file..." _s)) return maxon::OK ; AutoAlloc<BaseFile> file; if (file == nullptr ) return maxon::OutOfMemoryError( MAXON_SOURCE_LOCATION );

// Open a file with the purpose of reading data from it. if (!file-> Open (fn, FILEOPEN::READ , FILEDIALOG::ANY , BYTEORDER::V_INTEL , MACTYPE_CINEMA , MACCREATOR_CINEMA )) return PrintFileError(fn, file, "Failed to open the file for reading" _s);

// Read data from file. Char readBytes[numBytes]; const Bool justTry = false ; // Throw an error, if the file is smaller than the number of requested bytes. if (!file-> ReadBytes (&readBytes, sizeof (readBytes), justTry)) return PrintFileError(fn, file, maxon::String ( "Failed to read @ bytes from file" _s + maxon::String::IntToString(numBytes) + " bytes from file" _s));

// Compare the read bytes. Bool ok = true ; for ( Int32 idxByte = 0; idxByte < numBytes; ++idxByte) { if (readBytes[idxByte] != testBytes[idxByte]) { ok = false ; break ; } } if (ok) ApplicationOutput ( "The file seems to be a C4D scene file." ); else ApplicationOutput ( "The file does not seem to be a C4D scene file." );

// This example demonstrates writing raw bytes to a file. const maxon::String text = "The quick brown cube jumps over the sphere." _s;

// Let user select a directory. Filename fn; if (!fn. FileSelect ( FILESELECTTYPE::ANYTHING , FILESELECT::DIRECTORY , "Select a directory for a new file..." _s)) return maxon::OK ; fn += Filename ( "myTextFile.txt" _s); AutoAlloc<BaseFile> file; if (file == nullptr ) return maxon::OutOfMemoryError( MAXON_SOURCE_LOCATION );

// Open a file with the purpose of writing data to it. if (!file-> Open (fn, FILEOPEN::WRITE , FILEDIALOG::ANY , BYTEORDER::V_INTEL , MACTYPE_CINEMA , MACCREATOR_CINEMA )) return PrintFileError(fn, file, "Failed to open the file for writing" _s);

// Get a byte representation of the string (commented lines for classic String). //const Int32 numBytes = text.GetCStringLen(); const Int numBytes = text.GetLength(); //Char* cText = text.GetCStringCopy(); //maxon::Block<Char> textBuffer[numBytes]; //text.GetCStringBlock(&textBuffer); maxon::BaseArray<Char> cText = text.GetCString() iferr_return ; if (!cText. GetFirst ()) return maxon::UnexpectedError( MAXON_SOURCE_LOCATION , "Error: Failed to get C string" _s);

// Write data to file if (!file-> WriteBytes (cText. GetFirst (), numBytes)) return PrintFileError(fn, file, "Failed to write " _s + maxon::String::IntToString(numBytes) + " bytes to file" _s);

//DeleteMem(cText); // Don't forget to free the memory of the C string.

// This example demonstrates seeking a position in a file.

// Let user select a file. Filename fn; if (!fn. FileSelect ( FILESELECTTYPE::ANYTHING , FILESELECT::LOAD , "Select the file from BaseFile Write example..." _s)) return maxon::OK ; AutoAlloc<BaseFile> file; if (file == nullptr ) return maxon::OutOfMemoryError( MAXON_SOURCE_LOCATION );

// Open a file with the purpose of reading/writing data from/to it. if (!file-> Open (fn, FILEOPEN::READWRITE , FILEDIALOG::ANY , BYTEORDER::V_INTEL , MACTYPE_CINEMA , MACCREATOR_CINEMA )) return PrintFileError(fn, file, "Failed to open the file for reading/writing" _s);

// Prove: After opening position is zero. // Note: This is different, if the file is opened with FILEOPEN::APPEND. ApplicationOutput ( "File opened with FILEOPEN_READWRITE, position: @" _s, file-> GetPosition ());

// Change read/write position. // Assuming the file from the BaseFile Write (RAW) example is used, skipping three bytes should point to the space before "quick". if (!file-> Seek (3)) return PrintFileError(fn, file, "Failed to seek position 3" _s); ApplicationOutput ( "Reading from position: @" _s, file-> GetPosition ());

// Read a few bytes // Assuming the file from the BaseFile Write (RAW) example is used, reading six bytes should read " quick" (including preceding space). Char word[7]; // Have buffer one byte larger than needed. if (!file-> ReadBytes (word, sizeof (word) - 1, false )) return PrintFileError(fn, file, "Failed to read six bytes" _s); word[6] = 0; // Assure zero terminated string.

// Now, change position to the end of the file in order to append the word just read. if (!file-> Seek (file-> GetLength (), FILESEEK::START )) // using absolute position in file return PrintFileError(fn, file, "Failed to seek end of file" _s); ApplicationOutput ( "Writing \"@\"to end of file, position: @" _s, word, file-> GetPosition ());

// Write the read word at the end of the file. if (!file-> WriteBytes (word, sizeof (word))) return PrintFileError(fn, file, "Failed to append bytes to the end of file" _s);

• BaseFile::ReadBytes() : Reads a block of bytes from the file. By default throwing an error, if there are less bytes in the file than requested.
• BaseFile::TryReadBytes() : Reads a block of bytes from the file, without throwing an error, if there are less bytes in the file than requested. Basically the same as BaseFile::ReadBytes(data, len, true).
• BaseFile::WriteBytes() : Writes a block of bytes to the file.
• BaseFile::GetPosition() : Returns the current position of the read/write pointer.
• BaseFile::Seek() : Sets the read/write pointer to another position.
  • Parameter "mode":
    • FILESEEK::START : Seek position is relative to the start of the file.
    • FILESEEK::RELATIVE_ : Seek position is relative to the current position.

注意

It is possible to seek beyond the end of a file. When writing to this position, the skipped parts of the file will be filled with zeroes. A read from such position will end up in an error.

Utility

These utility functions provide some information on the file. Especially BaseFile::GetError() is frequently used to get information, what went wrong, if an error occured with one of the above functions.

• BaseFile::GetError() : Returns the last error that occurred.
• BaseFile::SetError() : Sets the error manually. Useful to reset the error.
• BaseFile::SetOrder() : Sets the byte order of data in the file.
• BaseFile::GetLength() : Returns the size of the file in bytes.
• BaseFile::GetLocation() : Returns the location of the file.
  • Return value:
    • LOCATION::DISK : The file is stored on disk.
    • LOCATION::IPCONNECTION : File is stored on an IP connection.
    • LOCATION::MEMORY : The file is located in memory, see also MemoryFileStruct Manual .

// Let user select a file. Filename fn; if (!fn. FileSelect ( FILESELECTTYPE::ANYTHING , FILESELECT::LOAD , "Select a C4D scene file..." _s)) return maxon::OK ; AutoAlloc<BaseFile> file; if (file == nullptr ) return maxon::OutOfMemoryError( MAXON_SOURCE_LOCATION );

// Open the file if (!file-> Open (fn, FILEOPEN::READ , FILEDIALOG::ANY , BYTEORDER::V_INTEL , MACTYPE_CINEMA , MACCREATOR_CINEMA )) return PrintFileError(fn, file, "Failed to open the file for reading" _s);

// Print some infos about the file. const Int64 fileSize = file-> GetLength (); const LOCATION fileLocation = file-> GetLocation (); ApplicationOutput ( "File size: @bytes" _s, fileSize); switch (fileLocation) { case LOCATION::DISK : ApplicationOutput ( "File is located on disk" _s); break ; case LOCATION::IPCONNECTION : ApplicationOutput ( "File is located on a network device" _s); // Note: This is a special case, that can't occur in this situation. break ; case LOCATION::MEMORY : ApplicationOutput ( "File is located in memory" _s); // Note: This is a special case, see MemoryFileStruct manuals and examples. break ; }

延伸阅读

• 文件 & 媒体
• Classic API Files & Media
• Filename Manual
• HyperFile Manual
• BrowseFiles Manual
• File Functions Manual
• FileMonitor Manual
• BaseDocument Manual on Disc I/O for loading and saving of Cinema 4D scenefiles
• BaseBitmap Manual on Disc I/O for loading and saving of images