File Functions Manual

About

Cinema 4D's API provides multiple utility functions to work with files.

// Small helper function demonstrating ShowInFinder().
static maxon::Result<void> InfoStop(const Filename& fn, const maxon::String& msg);
static maxon::Result<void> InfoStop(const Filename& fn, const maxon::String& msg)
{
if (!ShowInFinder(fn, false))
return maxon::UnknownError(MAXON_SOURCE_LOCATION);
return maxon::OK;
}
// A useless example to demonstrate a bunch of file functions.
// First get the desktop directory, this example will search for a testdocument.txt below the desktop.
Filename fnSrc;
// Search for a test file.
if (!GeSearchFile(fnDesktop, "testdocument.txt", &fnSrc))
{
ApplicationOutput("Error: Didn't find a file called \"testdocument.txt\" below the desktop directory."_s);
ApplicationOutput(" Please create one for this demo to work."_s);
return maxon::OK;
}
// Check if file exists (well, in this case it always does, as GeSearchFile() returned true).
if (!GeFExist(fnSrc, false))
{
const maxon::String errMsg = "Error: The selected file ("_s + src + ") doesn't exist."_s;
return maxon::UnexpectedError(MAXON_SOURCE_LOCATION, errMsg);
}
// Create a few sub-directories in the directory containing the "test file".
Filename fnNewDir = fnSrc.GetDirectory();
fnNewDir += "myDir";
fnNewDir += "mySubDir1";
fnNewDir += "mySubDir2";
if (!GeFCreateDirRec(fnNewDir)) // Note: GeFCreateDirRec() has to be used if several sub-directories are to be created in one step.
{
return maxon::UnexpectedError(MAXON_SOURCE_LOCATION, "Error: Failed to create directory: "_s + maxon::String(fnNewDir.GetString()));
}
InfoStop(fnNewDir, "New directory successfully created, watch opened Explorer/Finder"_s) iferr_return; // small helper function
// Copy the file into the sub-directory.
const Filename fnDest = fnNewDir + fnSrc.GetFile();
if (!GeFCopyFile(fnSrc, fnDest, 0))
{
const maxon::String dst = maxon::String(fnDest.GetString());
const maxon::String errMsg = "Error: Failed to copy file ("_s + src + ") to "_s + dst;
return maxon::UnexpectedError(MAXON_SOURCE_LOCATION, errMsg);
}
InfoStop(fnDest, "Source file successfully copied to new directory, watch opened Explorer/Finder"_s) iferr_return; // small helper function
// Rename the copy.
Filename fnDestRenamed = fnDest;
fnDestRenamed.SetFile("newName.test");
if (!GeFRename(fnDest, fnDestRenamed))
{
const maxon::String dest = maxon::String(fnDest.GetString());
const maxon::String renamed = maxon::String(fnDestRenamed.GetString());
const maxon::String errMsg = "Error: Failed to rename file ("_s + dest + ") to "_s + renamed;
return maxon::UnexpectedError(MAXON_SOURCE_LOCATION, errMsg);
}
InfoStop(fnDestRenamed, "File successfully renamed, watch opened Explorer/Finder"_s) iferr_return; // small helper function
// Move the renamed copy.
Filename fnDestMoved = fnSrc.GetDirectory();
fnDestMoved += "myDir";
fnDestMoved += fnDestRenamed.GetFile();
if (!GeFMove(fnDestRenamed, fnDestMoved))
{
const maxon::String renamed = maxon::String(fnDestRenamed.GetString());
const maxon::String moved = maxon::String(fnDestMoved.GetString());
const maxon::String errMsg = "Error: Failed to move file ("_s + renamed + ") to "_s + moved;
return maxon::UnexpectedError(MAXON_SOURCE_LOCATION, errMsg);
}
InfoStop(fnDestMoved, "File successfully moved, watch opened Explorer/Finder"_s) iferr_return; // small helper function
// Finally, remove the file and all created directories again.
Filename fnDelDir = fnSrc.GetDirectory();
fnDelDir += "myDir";
{
const maxon::String dir = maxon::String(fnDelDir.GetString());
const maxon::String errMsg = "Error: Failed to delete created directories and files ("_s + dir + ")"_s;
return maxon::UnexpectedError(MAXON_SOURCE_LOCATION, errMsg);
}
InfoStop(fnDestMoved, "Successfully deleted all directories/files created in this test, watch opened Explorer/Finder"_s) iferr_return; // small helper function

File Functions

All the usual functions to work with files (copy, rename, delete,...) are available in Cinema 4D's API:

Note
If a new file needs to be created from scratch, please see BaseFile Manual or HyperFile Manual.
Warning
Beware, GeFKill() deletes files permanently. The files will not be moved to system's trash can.
Note
For similar functions of the MAXON API see File Functions.

Folders/Directories

Creation

Default Paths

Note
For similar functions of the MAXON API see Application.

File Attributes

// Small helper function to decode file attributes into a string.
static maxon::Result<void> FileGetAttributesString(const Filename& fn, maxon::String &sAttr)
{
const UInt32 attr = GeFGetAttributes(fn);
sAttr = ""_s;
// Note: Depending on the platform (Win/OSX) not all flags make sense.
sAttr += "RO_"_s;
else
sAttr += "RW_"_s;
sAttr += "H_"_s;
else
sAttr += "__"_s;
sAttr += "L_"_s;
else
sAttr += "__"_s;
sAttr += "r"_s;
else
sAttr += "_"_s;
sAttr += "w"_s;
else
sAttr += "_"_s;
sAttr += "x"_s;
else
sAttr += "_"_s;
sAttr += "r"_s;
else
sAttr += "_"_s;
sAttr += "w"_s;
else
sAttr += "_"_s;
sAttr += "x"_s;
else
sAttr += "_"_s;
sAttr += "r"_s;
else
sAttr += "_"_s;
sAttr += "w"_s;
else
sAttr += "_"_s;
sAttr += "x"_s;
else
sAttr += "_"_s;
return maxon::OK;
}

File Execution

  • GeExecuteFile(): Opens the file as if the user double-clicked it. The default application for this file will open.
  • GeExecuteProgram(): Asynchronously executes an application.
  • GeOpenHTML(): Opens an URL in the user's default web browser.

Volumes/Drives

File Type Identification

Note
For similar function of the MAXON API see FileFormatHandlerInterface.

Documents

BaseDocument class contains functions to load documents from files (LoadDocument() and LoadFile()). See Disc I/O in the BaseDocument Manual for more information.

Images

BaseBitmap class contains functions to read/write images from/to files (BaseBitmap::Init() and BaseBitmap::Save()). Images can also be read/written from/to a HyperFile (HyperFile::ReadImage() and HyperFile::WriteImage()). See Disc I/O in the BaseBitmap Manual and BaseBitmap in HyperFile Manual for more information.

Sounds

Sound files can be loaded and saved with the respective functions (BaseSound::Load() and BaseSound::Save()) of the BaseSound class.

Miscellaneous

  • ShowInFinder(): Shows the file/path in the Finder (Mac) or Explorer (Windows).

Further Reading