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);
 
  MessageDialog(msg);
 
  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.
  const Filename fnDesktop = GeGetC4DPath(C4D_PATH_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 src = maxon::String(fnSrc.GetString());
    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 src = maxon::String(fnSrc.GetString());
    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";
  if (!GeFKill(fnDelDir, GE_FKILL_DIRECTORY | GE_FKILL_RECURSIVE))
  {
    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:

GeFExist(): Checks if a file or directory exists.
GeSearchFile(): Recursively searches for a file in a given directory.
GeFKill(): Deletes a file or directory.
- Parameter "flags", delete flags:
  - GE_FKILL_DIRECTORY: Delete directories.
  - GE_FKILL_RECURSIVE: Delete the children of a directory.
  - GE_FKILL_FORCE: Delete write-protected files.
GeFCopyFile(): Copies a file. Copy Flags:
- Parameter "flags", copy flags:
  - GE_FCOPY_OVERWRITE: Force a file overwrite, even if a file already exists under that name.
  - GE_FCOPY_DONTCOPYREADONLY: Do not copy an existing read-only flag.
GeFRename(): Renames a file.
GeFMove(): Moves a file.

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

GeFCreateDir(): Creates a directory.
GeFCreateDirRec(): Creates a directory even if the directories in the path do not exist.

Default Paths

GeGetStartupPath(): Gets the path for the main folder of Cinema 4D.
GeGetStartupApplication(): Gets the complete path of the host application (Cinema 4D, BodyPaint 3D, NET).
GeGetStartupWritePath(): Gets the writeable startup directory. This is the directory where all user data (preferences, libraries etc.) are stored.
GeGetPluginPath(): Gets the path for a plugin's main folder.
GeGetPluginResourcePath(): Gets the resource path for a plugin's main folder.
GeGetC4DPath(): Gets one of the Cinema 4D paths.
- Parameter "whichpath", path types:
  - C4D_PATH_PREFS: Cinema 4D preferences directory.
  - C4D_PATH_RESOURCE: Cinema 4D resource directory.
  - C4D_PATH_LIBRARY: Cinema 4D library directory (built-in).
  - C4D_PATH_LIBRARY_USER: Cinema 4D library path (different if multi-user mode is enabled).
  - C4D_PATH_ONLINE_HELP: Cinema 4D online help directory.
  - C4D_PATH_DESKTOP: OS desktop directory.
  - C4D_PATH_HOME: OS home directory (returns the same as C4D_PATH_MYDOCUMENTS on Windows).
  - C4D_PATH_STARTUPWRITE: Writeable startup directory (same as GeGetStartupWritePath()).
  - C4D_PATH_MYDOCUMENTS: The user's documents directory.
  - C4D_PATH_APPLICATION: OS application directory.

Note: For similar functions of the MAXON API see Application.

File Attributes

GeFGetAttributes(): Gets the attributes of a file.
GeFSetAttributes(): Sets the attributes for a file.
Return value (get) or parameter "flags" (set), file atribute flags:
- GE_FILE_ATTRIBUTE_READONLY: File is read-only.
- GE_FILE_ATTRIBUTE_HIDDEN: File is hidden.
- GE_FILE_ATTRIBUTE_LOCKED: File is locked (Mac only).
- GE_FILE_ATTRIBUTE_OWNER_R: Owner read file permission.
- GE_FILE_ATTRIBUTE_OWNER_W: Owner write file permission.
- GE_FILE_ATTRIBUTE_OWNER_X: Owner execute file permission.
- GE_FILE_ATTRIBUTE_GROUP_R: Group read file permission.
- GE_FILE_ATTRIBUTE_GROUP_W: Group write file permission.
- GE_FILE_ATTRIBUTE_GROUP_X: Group execute file permission.
- GE_FILE_ATTRIBUTE_PUBLIC_R: Public read file permission.
- GE_FILE_ATTRIBUTE_PUBLIC_W: Public write file permission.
- GE_FILE_ATTRIBUTE_PUBLIC_X: Public execute file permission.
- GE_FILE_ATTRIBUTS_UNIX_MASK: UNIX file attributes mask.

// 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.
  if (attr & GE_FILE_ATTRIBUTE_READONLY)
    sAttr += "RO_"_s;
  else
    sAttr += "RW_"_s;
  if (attr & GE_FILE_ATTRIBUTE_HIDDEN)
    sAttr += "H_"_s;
  else
    sAttr += "__"_s;
  if (attr & GE_FILE_ATTRIBUTE_LOCKED)
    sAttr += "L_"_s;
  else
    sAttr += "__"_s;
  if (attr & GE_FILE_ATTRIBUTE_OWNER_R)
    sAttr += "r"_s;
  else
    sAttr += "_"_s;
  if (attr & GE_FILE_ATTRIBUTE_OWNER_W)
    sAttr += "w"_s;
  else
    sAttr += "_"_s;
  if (attr & GE_FILE_ATTRIBUTE_OWNER_X)
    sAttr += "x"_s;
  else
    sAttr += "_"_s;
  if (attr & GE_FILE_ATTRIBUTE_GROUP_R)
    sAttr += "r"_s;
  else
    sAttr += "_"_s;
  if (attr & GE_FILE_ATTRIBUTE_GROUP_W)
    sAttr += "w"_s;
  else
    sAttr += "_"_s;
  if (attr & GE_FILE_ATTRIBUTE_GROUP_X)
    sAttr += "x"_s;
  else
    sAttr += "_"_s;
  if (attr & GE_FILE_ATTRIBUTE_PUBLIC_R)
    sAttr += "r"_s;
  else
    sAttr += "_"_s;
  if (attr & GE_FILE_ATTRIBUTE_PUBLIC_W)
    sAttr += "w"_s;
  else
    sAttr += "_"_s;
  if (attr & GE_FILE_ATTRIBUTE_PUBLIC_X)
    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

GeFGetDiskFreeSpace(): Retrieves information about the amount of space that is available on a disk volume. For a code example on the use of GeFGetDiskFreeSpace() see BrowseVolumes Manual.

File Type Identification

GeIdentifyFile(): Identifies the type of a file.
- Parameter "recognition", identification flags:
  - IDENTIFYFILE::NONE : None, will be returned if identification failed
  - IDENTIFYFILE::SCENE : Scene file
  - IDENTIFYFILE::IMAGE : Image file
  - IDENTIFYFILE::MOVIE : Movie file
  - IDENTIFYFILE::SKIPQUICKTIME : Skip files that require QuickTime.
  - IDENTIFYFILE::SCRIPT : Script file
  - IDENTIFYFILE::SOUND : Sound file
  - IDENTIFYFILE::LAYOUT : Layout file
  - IDENTIFYFILE::PYTHON : Python file
IdentifyImage(): Identifies the type of an image file.
- Return value, image types:
  - FILTER_TIF: TIFF
  - FILTER_TGA: TGA
  - FILTER_BMP: BMP
  - FILTER_IFF: IFF
  - FILTER_JPG: JPEG
  - FILTER_PICT: PICT
  - FILTER_PSD: PSD
  - FILTER_RLA: RLA
  - FILTER_RPF: RPF
  - FILTER_B3D: BodyPaint 3D
  - FILTER_TIF_B3D: TIFF BodyPaint 3D
  - FILTER_PSB: PSB
  - FILTER_AVI: AVI Movie
  - FILTER_MOVIE: QuickTime Movie
  - FILTER_HDR: HDR
  - FILTER_EXR_LOAD: EXR (Load)
  - FILTER_EXR: EXR
  - FILTER_PNG: PNG
  - FILTER_IES: IES
  - FILTER_B3DNET: BodyPaint 3D NET (Private!)
  - FILTER_DPX: DPX
GeGetMovieInfo(): Retrieves information from a movie file.

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).

Table of Contents