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;
}
Bool ShowInFinder(const Filename &fn, Bool open)
void MessageDialog(const maxon::String &str)
Manages file and path names.
Definition: c4d_file.h:94
Definition: string.h:1235
return OK
Definition: apibase.h:2747
#define MAXON_SOURCE_LOCATION
Definition: memoryallocationbase.h:67
const char const char * msg
Definition: object.h:438
// 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 { fnDestRenamed.GetString() };
const maxon::String moved { 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 { 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
String GetString() const
const Filename GetDirectory() const
const Filename GetFile() const
void SetFile(const Filename &str)
PyObject * src
Definition: abstract.h:305
#define C4D_PATH_DESKTOP
OS desktop directory.
Definition: c4d_file.h:1923
#define GE_FKILL_RECURSIVE
Delete the children of a directory.
Definition: c4d_file.h:1731
#define GE_FKILL_DIRECTORY
Delete directories.
Definition: c4d_file.h:1730
#define ApplicationOutput(formatString,...)
Definition: debugdiagnostics.h:210
const Filename GeGetC4DPath(Int32 whichpath)
Bool GeFExist(const Filename &name, Bool isdir=false)
Bool GeFCopyFile(const Filename &source, const Filename &dest, Int32 flags)
Bool GeFKill(const Filename &name, Int32 flags=0)
Bool GeFRename(const Filename &source, const Filename &dest)
Bool GeFCreateDirRec(const Filename &name)
Bool GeSearchFile(const Filename &directory, const Filename &name, Filename *found)
Bool GeFMove(const Filename &source, const Filename &dest)
#define iferr_return
Definition: resultbase.h:1521

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;
}
maxon::UInt32 UInt32
Definition: ge_sys_math.h:61
#define GE_FILE_ATTRIBUTE_GROUP_R
Group read file permission.
Definition: c4d_file.h:1751
#define GE_FILE_ATTRIBUTE_READONLY
File is read-only.
Definition: c4d_file.h:1745
#define GE_FILE_ATTRIBUTE_OWNER_W
Owner write file permission.
Definition: c4d_file.h:1749
#define GE_FILE_ATTRIBUTE_GROUP_X
Group execute file permission.
Definition: c4d_file.h:1753
#define GE_FILE_ATTRIBUTE_GROUP_W
Group write file permission.
Definition: c4d_file.h:1752
#define GE_FILE_ATTRIBUTE_PUBLIC_X
Public execute file permission.
Definition: c4d_file.h:1756
#define GE_FILE_ATTRIBUTE_PUBLIC_R
Public read file permission.
Definition: c4d_file.h:1754
#define GE_FILE_ATTRIBUTE_OWNER_X
Owner execute file permission.
Definition: c4d_file.h:1750
#define GE_FILE_ATTRIBUTE_HIDDEN
File is hidden.
Definition: c4d_file.h:1746
#define GE_FILE_ATTRIBUTE_LOCKED
File is locked (Mac only).
Definition: c4d_file.h:1747
#define GE_FILE_ATTRIBUTE_PUBLIC_W
Public write file permission.
Definition: c4d_file.h:1755
#define GE_FILE_ATTRIBUTE_OWNER_R
Owner read file permission.
Definition: c4d_file.h:1748
UInt32 GeFGetAttributes(const Filename &name)

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