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 { 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

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

GE_FILE_ATTRIBUTE_GROUP_R
#define GE_FILE_ATTRIBUTE_GROUP_R
Group read file permission.
Definition: c4d_file.h:1736
MessageDialog
void MessageDialog(const maxon::String &str)
GE_FILE_ATTRIBUTE_HIDDEN
#define GE_FILE_ATTRIBUTE_HIDDEN
File is hidden.
Definition: c4d_file.h:1731
GeFCreateDirRec
Bool GeFCreateDirRec(const Filename &name)
Filename::GetFile
const Filename GetFile(void) const
GeFExist
Bool GeFExist(const Filename &name, Bool isdir=false)
GE_FILE_ATTRIBUTE_GROUP_W
#define GE_FILE_ATTRIBUTE_GROUP_W
Group write file permission.
Definition: c4d_file.h:1737
UInt32
maxon::UInt32 UInt32
Definition: ge_sys_math.h:61
maxon::String
Definition: string.h:1213
GE_FILE_ATTRIBUTE_PUBLIC_W
#define GE_FILE_ATTRIBUTE_PUBLIC_W
Public write file permission.
Definition: c4d_file.h:1740
Filename
Manages file and path names.
Definition: c4d_file.h:93
maxon::OK
return OK
Definition: apibase.h:2546
GE_FILE_ATTRIBUTE_OWNER_R
#define GE_FILE_ATTRIBUTE_OWNER_R
Owner read file permission.
Definition: c4d_file.h:1733
C4D_PATH_DESKTOP
#define C4D_PATH_DESKTOP
OS desktop directory.
Definition: c4d_file.h:1908
iferr_return
#define iferr_return
Definition: resultbase.h:1465
MAXON_SOURCE_LOCATION
#define MAXON_SOURCE_LOCATION
Definition: memoryallocationbase.h:66
GeFRename
Bool GeFRename(const Filename &source, const Filename &dest)
GeFKill
Bool GeFKill(const Filename &name, Int32 flags=0)
GeSearchFile
Bool GeSearchFile(const Filename &directory, const Filename &name, Filename *found)
Filename::GetString
String GetString(void) const
GE_FKILL_DIRECTORY
#define GE_FKILL_DIRECTORY
Delete directories.
Definition: c4d_file.h:1715
maxon::src
const T & src
Definition: apibase.h:2539
maxon::Result< void >
GeGetC4DPath
const Filename GeGetC4DPath(Int32 whichpath)
Filename::SetFile
void SetFile(const Filename &str)
Filename::GetDirectory
const Filename GetDirectory(void) const
GeFGetAttributes
UInt32 GeFGetAttributes(const Filename &name)
ShowInFinder
Bool ShowInFinder(const Filename &fn, Bool open)
GE_FKILL_RECURSIVE
#define GE_FKILL_RECURSIVE
Delete the children of a directory.
Definition: c4d_file.h:1716
ApplicationOutput
#define ApplicationOutput(formatString,...)
Definition: debugdiagnostics.h:208
GE_FILE_ATTRIBUTE_OWNER_W
#define GE_FILE_ATTRIBUTE_OWNER_W
Owner write file permission.
Definition: c4d_file.h:1734
GeFCopyFile
Bool GeFCopyFile(const Filename &source, const Filename &dest, Int32 flags)
GE_FILE_ATTRIBUTE_READONLY
#define GE_FILE_ATTRIBUTE_READONLY
File is read-only.
Definition: c4d_file.h:1730
GE_FILE_ATTRIBUTE_OWNER_X
#define GE_FILE_ATTRIBUTE_OWNER_X
Owner execute file permission.
Definition: c4d_file.h:1735
GE_FILE_ATTRIBUTE_PUBLIC_X
#define GE_FILE_ATTRIBUTE_PUBLIC_X
Public execute file permission.
Definition: c4d_file.h:1741
GeFMove
Bool GeFMove(const Filename &source, const Filename &dest)
GE_FILE_ATTRIBUTE_GROUP_X
#define GE_FILE_ATTRIBUTE_GROUP_X
Group execute file permission.
Definition: c4d_file.h:1738
GE_FILE_ATTRIBUTE_PUBLIC_R
#define GE_FILE_ATTRIBUTE_PUBLIC_R
Public read file permission.
Definition: c4d_file.h:1739
GE_FILE_ATTRIBUTE_LOCKED
#define GE_FILE_ATTRIBUTE_LOCKED
File is locked (Mac only).
Definition: c4d_file.h:1732