Files and Folders

These routines assist your object in opening and saving files, as well as locating the user’s files in the Max search path. More...

Data Structures
struct	t_fileinfo
	Information about a file. More...
struct	t_path
	The path data structure. More...
struct	t_pathlink
	The pathlink data structure. More...
Defines
#define	MAX_PATH_CHARS   2048
	The size you should use when allocating strings for full paths.
#define	MAX_FILENAME_CHARS   512
	The size you should use when allocating strings for filenames.
Typedefs
typedef void *	t_filehandle
	A t_filehandle is a cross-platform way of referring to an open file.
Enumerations
enum	e_max_path_styles {   PATH_STYLE_MAX = 0,   PATH_STYLE_NATIVE,   PATH_STYLE_COLON,   PATH_STYLE_SLASH,   PATH_STYLE_NATIVE_WIN }
	Constants that determine the output of path_nameconform(). More...
enum	e_max_path_types {   PATH_TYPE_IGNORE = 0,   PATH_TYPE_ABSOLUTE,   PATH_TYPE_RELATIVE,   PATH_TYPE_BOOT,   PATH_TYPE_C74,   PATH_TYPE_PATH }
	Constants that determine the output of path_nameconform(). More...
enum	e_max_fileinfo_flags {   PATH_FILEINFO_ALIAS = 1,   PATH_FILEINFO_FOLDER = 2,   PATH_FILEINFO_PACKAGE = 4 }
	Flags used to represent properties of a file in a t_fileinfo struct. More...
enum	e_max_path_folder_flags {   PATH_REPORTPACKAGEASFOLDER = 1,   PATH_FOLDER_SNIFF = 2 }
	Flags used by functions such as path_foldernextfile() and path_openfolder(). More...
enum	e_max_openfile_permissions {   PATH_READ_PERM = 1,   PATH_WRITE_PERM = 2,   PATH_RW_PERM = 3 }
	Permissions or mode with which to open a file. More...
enum	e_max_sysfile_posmodes {   SYSFILE_ATMARK = 0,   SYSFILE_FROMSTART,   SYSFILE_FROMLEOF,   SYSFILE_FROMMARK }
	Modes used by sysfile_setpos(). More...
enum	e_max_sysfile_textflags {   TEXT_LB_NATIVE = 0x00000001L,   TEXT_LB_MAC = 0x00000002L,   TEXT_LB_PC = 0x00000004L,   TEXT_LB_UNIX = 0x00000008L,   TEXT_ENCODING_USE_FILE = 0x00000100L,   TEXT_NULL_TERMINATE = 0x00000200L }
	Flags used reading and writing text files. More...
Functions
short	path_getapppath (void)
	Retrieve the Path ID of the Max application.
short	locatefile (char *name, short *outvol, short *binflag)
	Find a Max document by name in the search path.
short	locatefiletype (char *name, short *outvol, long filetype, long creator)
	Find a Max document by name in the search path.
short	locatefile_extended (char *name, short *outvol, long *outtype, long *filetypelist, short numtypes)
	Find a Max document by name in the search path.
short	path_resolvefile (char *name, short path, short *outpath)
	Resolve a Path ID plus a (possibly extended) file name into a path that identifies the file’s directory and a filename.
short	path_fileinfo (char *name, short path, void *info)
	Retrive a t_fileinfo structure from a file/path combination.
short	path_topathname (short path, char *file, char *name)
	Create a fully qualified file name from a Path ID/file name combination.
short	path_frompathname (char *name, short *path, char *filename)
	Create a filename and Path ID combination from a fully qualified file name.
void	path_setdefault (short path, short recursive)
	Install a path as the default search path.
short	path_getdefault (void)
	Retrieve the Path ID of the default search path.
short	path_getmoddate (short path, unsigned long *date)
	Determine the modification date of the selected path.
short	path_getfilemoddate (char *filename, short path, unsigned long *date)
	Determine the modification date of the selected file.
void *	path_openfolder (short path)
	Prepare a directory for iteration.
short	path_foldernextfile (void *xx, long *filetype, char *name, short descend)
	Get the next file in the directory.
void	path_closefolder (void *x)
	Complete a directory iteration.
short	path_opensysfile (char *name, short path, t_filehandle *ref, short perm)
	Open a file given a filename and Path ID.
short	path_createsysfile (char *name, short path, long type, t_filehandle *ref)
	Create a file given a type code, a filename, and a Path ID.
short	path_nameconform (char *src, char *dst, long style, long type)
	Convert a source path string to destination path string using the specified style and type.
short	path_topotentialname (short path, char *file, char *name, short check)
	Create a fully qualified file name from a Path ID/file name combination, regardless of whether or not the file exists on disk.
short	open_dialog (char *name, short *volptr, long *typeptr, long *types, short ntypes)
	Present the user with the standard open file dialog.
short	saveas_dialog (char *filename, short *path, short *binptr)
	Present the user with the standard save file dialog.
short	saveasdialog_extended (char *name, short *vol, long *type, long *typelist, short numtypes)
	Present the user with the standard save file dialog with your own list of file types.
void	open_promptset (char *s)
	Use open_promptset() to add a prompt message to the open file dialog displayed by open_dialog().
void	saveas_promptset (char *s)
	Use saveas_promptset() to add a prompt message to the open file dialog displayed by saveas_dialog() or saveasdialog_extended().
void *	filewatcher_new (t_object *owner, short path, char *filename)
	Create a new filewatcher.
void	fileusage_addfile (void *w, long flags, char *name, short path)
	Add a file to a collective.
long	sysfile_close (t_filehandle f)
	Close a file opened with sysfile_open().
long	sysfile_read (t_filehandle f, long *count, void *bufptr)
	Read a file from disk.
long	sysfile_readtohandle (t_filehandle f, char ***h)
	Read the contents of a file into a handle.
long	sysfile_readtoptr (t_filehandle f, char **p)
	Read the contents of a file into a pointer.
long	sysfile_write (t_filehandle f, long *count, const void *bufptr)
	Write part of a file to disk.
long	sysfile_seteof (t_filehandle f, long logeof)
	Set the size of a file handle.
long	sysfile_geteof (t_filehandle f, long *logeof)
	Get the size of a file handle.
long	sysfile_setpos (t_filehandle f, long mode, long offset)
	Set the current file position of a file handle.
long	sysfile_getpos (t_filehandle f, long *filepos)
	Get the current file position of a file handle.
long	sysfile_spoolcopy (t_filehandle src, t_filehandle dst, long size)
	Copy the contents of one file handle to another file handle.
long	sysfile_readtextfile (t_filehandle f, t_handle htext, long maxlen, long flags)
	Read a text file from disk.
long	sysfile_writetextfile (t_filehandle f, t_handle htext, long flags)
	Write a text file to disk.
short	sysfile_openhandle (char **h, long flags, t_filehandle *fh)
	Create a t_filehandle from a pre-existing handle.
short	sysfile_openptrsize (char *p, long length, long flags, t_filehandle *fh)
	Create a t_filehandle from a pre-existing pointer.

---

Detailed Description

These routines assist your object in opening and saving files, as well as locating the user’s files in the Max search path.

There have been a significant number of changes to these routines (as well as the addition of many functions), so some history may be useful in understanding their use.

Prior to version 4, Max used a feature of Mac OS 9 called "working directories" to specify files. When you used the locatefile() service routine, you would get back a file name and a volume number. This name (converted to a Pascal string) and the volume number could be passed to FSOpen() to open the located file for reading. The open_dialog() routine worked similarly.

In Mac OSX, working directories are no longer supported. In addition, the use of these "volume" numbers makes it somewhat difficult to port Max file routines to other operating systems, such as Windows XP, that specify files using complete pathnames (i.e., "C:\dir1\dir2\file.pat").

However, it is useful to be able to refer to the path and the name of the file separately. The solution involves the retention of the volume number (now called Path ID), but with a platform- independent wrapper that determines its meaning. There are now calls to locate, open, and choose files using C filename strings and Path IDs, as well as routines to convert between a "native" format for specifying a file (such as a full pathname on Windows or an FSRef on the Macintosh) to the C string and Path ID. As of Max version 5 FSSpecs, long ago deprecated by Apple, are no longer supported.

Now that paths in Max have changed to use the slash style, as opposed to the old Macintosh colon style (see the Max 4.3 documentation for a description of the file path styles), there is one function in particular that you will find useful for converting between the various ways paths can be represented, including operating system native paths. This function is path_nameconform(). Note that for compatibility purposes Path API functions accept paths in any number of styles, but will typically return paths, or modify paths inline to use the newer slash style. In addition to absolute paths, paths relative to the Max Folder, the "Cycling '74" folder and the boot volume are also supported. See the conformpath.help and ext_path.h files for more information on the various styles and types of paths. See the "filebyte" SDK example project for a demonstration of how to use the path functions to convert a Max name and path ref pair to a Windows native path for use with CreateFile().

There are a large number of service routine in the Max 4 kernel that support files, but only a handful will be needed by most external objects. In addition to the descriptions that follow, you should consult the movie, folder and filedate examples included with the SDK.

The Sysfile API

The Sysfile API provides the means of reading and writing files opened by path_createsysfile() and similar. These functions all make use of an opaque structure, t_filehandle. See the path functions path_opensysfile() and path_createsysfile() described earlier in this chapter for more information. The Sysfile API is relatively similar to parts of the old Macintosh File Manager API, and not too different from Standard C library file functions. The "filebyte" example project in the SDK shows how to use these functions to read from a file. It is not safe to mix these routines with other file routines (e.g. don’t use fopen() to open a file and sysfile_close() to close it).

In addition to being able to use these routines to write cross-platform code in your max externals, another advantage of the Sysfile API is that it is able to read files stored in the collective file format on both Windows XP and Mac OSX.

Example: filebyte (notes from the IRCAM workshop)

Paths

• A number that specifies a file location
• Returned by locatefile_extended() and open_dialog()
• Supply a path when opening a file with path_opensysfile()
• Can convert path to and from pathname

t_filehandle

• Returned by path_opensysfile
• Refers to an open file you want to read or write using sysfile_read / sysfile_write
• Could refer to a file in a collective

File Names

• C string
• Max 5 filenames are UTF-8
• Max 5 supports long (unicode) filenames on both Mac and Windows

File Path Names

• Max uses a platform-independent path string format: volume:/path1/path2/filename returned by path_topathname
• Can convert to platform-specific format using path_nameconform (not needed if using path_opensysfile)
• Platform-independent format must be used with path_frompathname

Collectives and Fileusage

Use the fileusage routines to add files to a collective when a user chooses to build a collective. Your object can respond to a "fileusage" message, which is sent by Max when the collective builder is building a collective using the following:

    class_addmethod(c, (method)my_fileusage,    "fileusage", A_CANT, 0L);

Where my file usage has the prototype:

    void my_fileusage(t_myObject *x, void *w);

Then you can use fileusage_addfile() to add any requisite files to the collective.

Filewatchers

Your object can watch a file or folder and be notified of changes. Use filewatcher_new(), filewatcher_start(), and filewatcher_stop() to implement this functionality. You may wish to use filewatchers sparingly as they can potentially incur computational overhead in the background.

---

Define Documentation

#define MAX_FILENAME_CHARS   512

The size you should use when allocating strings for filenames.

At the time of this writing it supports up to 256 UTF chars

Definition at line 28 of file ext_path.h.

---

Typedef Documentation

typedef void* t_filehandle

A t_filehandle is a cross-platform way of referring to an open file.

It is an opaque structure, meaning you don’t have access to the individual elements of the data structure. You can use a t_filehandle only with the file routines in the Sysfile API. Do not use other platform- specific file functions in conjunction with these functions. The perm parameter can be either READ_PERM, WRITE_PERM, or RW_PERM.

Definition at line 15 of file ext_sysfile.h.

---

Enumeration Type Documentation

enum e_max_fileinfo_flags

Flags used to represent properties of a file in a t_fileinfo struct.

Enumerator:

PATH_FILEINFO_ALIAS	alias
PATH_FILEINFO_FOLDER	folder
PATH_FILEINFO_PACKAGE	package (Mac-only)

Definition at line 88 of file ext_path.h.

enum e_max_openfile_permissions

Permissions or mode with which to open a file.

Enumerator:

PATH_READ_PERM	Read mode.
PATH_WRITE_PERM	Write mode.
PATH_RW_PERM	Read/Write mode.

Definition at line 111 of file ext_path.h.

enum e_max_path_folder_flags

Flags used by functions such as path_foldernextfile() and path_openfolder().

Enumerator:

PATH_REPORTPACKAGEASFOLDER	if not true, then a Mac OS package will be reported as a file rather than a folder.
PATH_FOLDER_SNIFF	sniff

Definition at line 101 of file ext_path.h.

enum e_max_path_styles

Constants that determine the output of path_nameconform().

See also:

e_max_path_types

path_nameconform()

Enumerator:

PATH_STYLE_MAX	use PATH_STYLE_MAX_PLAT
PATH_STYLE_NATIVE	use PATH_STYLE_NATIVE_PLAT
PATH_STYLE_COLON	':' sep, "vol:" volume, ":" relative, "^:" boot
PATH_STYLE_SLASH	'/' sep, "vol:/" volume, "./" relative, "/" boot
PATH_STYLE_NATIVE_WIN	'\' sep, "vol:\\" volume, ".\\" relative, "\\" boot

Definition at line 45 of file ext_path.h.

enum e_max_path_types

Constants that determine the output of path_nameconform().

See also:

e_max_path_styles

path_nameconform()

Enumerator:

PATH_TYPE_IGNORE	ignore
PATH_TYPE_ABSOLUTE	absolute path
PATH_TYPE_RELATIVE	relative path
PATH_TYPE_BOOT	boot path
PATH_TYPE_C74	Cycling '74 folder.
PATH_TYPE_PATH	path

Definition at line 67 of file ext_path.h.

enum e_max_sysfile_posmodes

Modes used by sysfile_setpos().

Enumerator:

SYSFILE_ATMARK	?
SYSFILE_FROMSTART	Calculate the file position from the start of the file.
SYSFILE_FROMLEOF	Calculate the file position from the logical end of the file.
SYSFILE_FROMMARK	Calculate the file position from the current file position.

Definition at line 20 of file ext_sysfile.h.

enum e_max_sysfile_textflags

Flags used reading and writing text files.

Enumerator:

TEXT_LB_NATIVE	Use the linebreak format native to the current platform.
TEXT_LB_MAC	Use Macintosh line breaks.
TEXT_LB_PC	Use Windows line breaks.
TEXT_LB_UNIX	Use Unix line breaks.
TEXT_ENCODING_USE_FILE	If this flag is not set then the encoding is forced to UTF8.
TEXT_NULL_TERMINATE	Terminate memory returned from sysfile_readtextfile() with a NULL character.

Definition at line 30 of file ext_sysfile.h.

---

Function Documentation

void fileusage_addfile	(	void *	w,
		long	flags,
		char *	name,
		short	path
	)

Add a file to a collective.

Parameters:

	w	Handle for the collective builder.
	flags	If flags == 1, copy this file to support folder of an app instead of to the collective in an app.
	name	The name of the file.
	path	The path of the file to add.

void* filewatcher_new	(	t_object *	owner,
		short	path,
		char *	filename
	)

Create a new filewatcher.

The file will not be actively watched until filewatcher_start() is called. The filewatcher can be freed using object_free().

Parameters:

	owner	Your object. This object will receive the message "filechanged" when the watcher sees a change in the file or folder.
	path	The path in which the file being watched resides, or the path of the folder being watched.
	filename	The name of the file being watched, or an empty string if you are simply watching the folder specified by path.

Returns:

A pointer to the new filewatcher.

Remarks:

The "filechanged" method should have the prototype:

    void myObject_filechanged(t_myObject *x, char *filename, short path);

short locatefile	(	char *	name,
		short *	outvol,
		short *	binflag
	)

Find a Max document by name in the search path.

This routine performs the same function as the routine path_getdefault(). locatefile() searches through the directories specified by the user for Patcher files and tables in the File Preferences dialog as well as the current default path (see path_getdefault) and the directory containing the Max application

Parameters:

	name	A C string that is the name of the file to look for.
	outvol	The Path ID containing the location of the file if it is found.
	binflag	If the file found is in binary format (it’s of type ‘maxb’) 1 is returned here; if it’s in text format, 0 is returned.

Returns:

If a file is found with the name specified by filename, locatefile returns 0, otherwise it returns non-zero.

Remarks:

filename and vol can then be passed to binbuf_read to read and open file the file. When using MAXplay, the search path consists of all subdirectories of the directory containing the MAXplay application. locatefile only searches for files of type ‘maxb’ and ‘TEXT.’

See also:

locatefile_extended()

short locatefile_extended	(	char *	name,
		short *	outvol,
		long *	outtype,
		long *	filetypelist,
		short	numtypes
	)

Find a Max document by name in the search path.

This is the preferred method for file searching since its introduction in Max version 4.

This routine performs the same function as the routine path_getdefault(). locatefile() searches through the directories specified by the user for Patcher files and tables in the File Preferences dialog as well as the current default path (see path_getdefault) and the directory containing the Max application

Version:

4.0

Parameters:

	name	The file name for the search, receives actual filename.
	outvol	The Path ID of the file (if found).
	outtype	The file type of the file (if found).
	filetypelist	The file type(s) that you are searching for.
	numtypes	The number of file types in the typelist array (1 if a single entry).

Returns:

If a file is found with the name specified by filename, locatefile returns 0, otherwise it returns non-zero.

Remarks:

The old file search routines locatefile() and locatefiletype() are still supported in Max 4, but the use of a new routine locatefile_extended() is highly recommended. However, locatefile_extended() has an important difference from locatefile() and locatefiletype() that may require some rewriting of your code. It modifies its name parameter in certain cases, while locatefile() and locatefiletype() do not. The two cases where it could modify the incoming filename string are 1) when an alias is specified, the file pointed to by the alias is returned; and 2) when a full path is specified, the output is the filename plus the path number of the folder it's in.

This is important because many people pass the s_name field of a t_symbol to locatefile(). If the name field of a t_symbol were to be modified, the symbol table would be corrupted. To avoid this problem, use strncpy_zero() to copy the contents of a t_symbol to a character string first, as shown below:

    char filename[MAX_FILENAME_CHARS]; 
    strncpy_zero(filename,str->s_name, MAX_FILENAME_CHARS); 
    result = locatefile_extended(filename,&path,&type,typelist,1); 

short locatefiletype	(	char *	name,
		short *	outvol,
		long	filetype,
		long	creator
	)

Find a Max document by name in the search path.

This function searches through the same directories as locatefile, but allows you to specify a type and creator of your own.

Parameters:

	name	A C string that is the name of the file to look for.
	outvol	The Path ID containing the location of the file if it is found.
	filetype	The filetype of the file to look for. If you pass 0L, files of all filetypes are considered.
	creator	The creator of the file to look for. If you pass 0L, files with any creator are considered.

Returns:

If a file is found with the name specified by filename, locatefile returns 0, otherwise it returns non-zero.

See also:

locatefile_extended()

short open_dialog	(	char *	name,
		short *	volptr,
		long *	typeptr,
		long *	types,
		short	ntypes
	)

Present the user with the standard open file dialog.

This function is convenient wrapper for using Mac OS Navigation Services or Standard File for opening files.

The mapping of extensions to types is configured in the C74:/init/max-fileformats.txt file. The standard types to use for Max files are ‘maxb’ for old-format binary files, ‘TEXT’ for text files, and 'JSON' for newer format patchers or other .json files.

Parameters:

	name	A C-string that will receive the name of the file the user wants to open. The C-string should be allocated with a size of at least MAX_FILENAME_CHARS.
	volptr	Receives the Path ID of the file the user wants to open.
	typeptr	The file type of the file the user wants to open.
	types	A list of file types to display. This is not limited to 4 types as in the SFGetFile() trap. Pass NULL to display all types.
	ntypes	The number of file types in typelist. Pass 0 to display all types.

Returns:

0 if the user clicked Open in the dialog box. If the user cancelled, open_dialog() returns a non-zero value.

See also:

saveasdialog_extended()

locatefile_extended()

void open_promptset

(

char *

s

)

Use open_promptset() to add a prompt message to the open file dialog displayed by open_dialog().

Calling this function before open_dialog() permits a string to displayed in the dialog box instructing the user as to the purpose of the file being opened. It will only apply to the call of open_dialog() that immediately follows open_promptset().

Parameters:

s

A C-string containing the prompt you wish to display in the dialog box.

Returns:

Ignore.

See also:

open_dialog()

void path_closefolder

(

void *

x

)

Complete a directory iteration.

Parameters:

x

The “folder state” value originally returned by path_openfolder().

short path_createsysfile	(	char *	name,
		short	path,
		long	type,
		t_filehandle *	ref
	)

Create a file given a type code, a filename, and a Path ID.

Parameters:

	name	The name of the file to be opened.
	path	The Path ID of the file to be opened.
	type	The file type of the created file.
	ref	A t_filehandle reference to the opened file will be returned in this parameter.

Returns:

An error code.

short path_fileinfo	(	char *	name,
		short	path,
		void *	info
	)

Retrive a t_fileinfo structure from a file/path combination.

Parameters:

	name	The file name to be queried.
	path	The Path ID of the file.
	info	The address of a t_fileinfo structure to contain the file information.

Returns:

Returns 0 if successful, otherwise it returns an OS-specific error code.

short path_foldernextfile	(	void *	xx,
		long *	filetype,
		char *	name,
		short	descend
	)

Get the next file in the directory.

In conjunction with path_openfolder() and path_closefolder(), this routine allows you to iterate through all of the files in a path.

Parameters:

	xx	The “folder state” value returned by path_openfolder().
	filetype	Contains the file type of the file type on return.
	name	Contains the file name of the next file on return.
	descend	Unused.

Returns:

Returns non-zero if successful, and zero when there are no more files.

See also:

e_max_path_folder_flags

short path_frompathname	(	char *	name,
		short *	path,
		char *	filename
	)

Create a filename and Path ID combination from a fully qualified file name.

Note that path_frompathname() does not require that the file actually exist. In this way you can use it to convert a full path you may have received as an argument to a file writing message to a form appropriate to provide to a routine such as path_createfile().

Parameters:

	name	The extended file path to be converted.
	path	Contains the Path ID on return.
	filename	Contains the file name on return.

Returns:

Returns 0 if successful, otherwise it returns an OS-specific error code.

short path_getapppath

(

void

)

Retrieve the Path ID of the Max application.

Returns:

The path id.

short path_getdefault

(

void

)

Retrieve the Path ID of the default search path.

Returns:

The path id of the default search path.

Referenced by jit_qt_movie_matrix_to_image(), jit_qt_utils_moviedataref_create(), and jit_qt_utils_tempmoviefile_create().

short path_getfilemoddate	(	char *	filename,
		short	path,
		unsigned long *	date
	)

Determine the modification date of the selected file.

Parameters:

	filename	The name of the file to query.
	path	The Path ID of the file.
	date	The last modification date of the file upon return.

Returns:

An error code.

short path_getmoddate	(	short	path,
		unsigned long *	date
	)

Determine the modification date of the selected path.

Parameters:

	path	The Path ID of the directory to check.
	date	The last modification date of the directory.

Returns:

An error code.

short path_nameconform	(	char *	src,
		char *	dst,
		long	style,
		long	type
	)

Convert a source path string to destination path string using the specified style and type.

Parameters:

	src	A pointer to source character string to be converted.
	dst	A pointer to destination character string.
	style	The destination filepath style, as defined in e_max_path_styles
	type	The destination filepath type, as defined in e_max_path_types

Returns:

An error code.

See also:

MAX_PATH_CHARS

Referenced by db_open(), and jit_qt_utils_tempfile().

void* path_openfolder

(

short

path

)

Prepare a directory for iteration.

Parameters:

path

The directory Path ID to open.

Returns:

The return value of this routine is an internal “folder state” structure used for further folder manipulation. It should be saved and used for calls to path_foldernextfile() and path_closefolder(). If the folder cannot be found or accessed, path_openfolder() returns 0.

short path_opensysfile	(	char *	name,
		short	path,
		t_filehandle *	ref,
		short	perm
	)

Open a file given a filename and Path ID.

Parameters:

	name	The name of the file to be opened.
	path	The Path ID of the file to be opened.
	ref	A t_filehandle reference to the opened file will be returned in this parameter.
	perm	The permission for the opened file as defined in e_max_openfile_permissions.

Returns:

An error code.

short path_resolvefile	(	char *	name,
		short	path,
		short *	outpath
	)

Resolve a Path ID plus a (possibly extended) file name into a path that identifies the file’s directory and a filename.

This routine converts a name and Path ID to a standard form in which the name has no path information and does not refer to an aliased file.

Parameters:

	name	A file name (which may be fully or partially qualified), will contain the file name on return.
	path	The Path ID to be resolved.
	outpath	The Path ID of the returned file name.

Returns:

Returns 0 if successful.

void path_setdefault	(	short	path,
		short	recursive
	)

Install a path as the default search path.

The default path is searched before the Max search path. For instance, when loading a patcher from a directory outside the search path, the patcher’s directory is searched for files before the search path. path_setdefault() allows you to set a path as the default.

Parameters:

	path	The path to use as the search path. If path is already part of the Max Search path, it will not be added (since, by default, it will be searched during file searches).
	recursive	If non-zero, all subdirectories will be installed in the default search list. Be very careful with the use of the recursive argument—it has the capacity to slow down file searches dramatically as the list of folders is being built. Max itself never creates a hierarchical default search path.

short path_topathname	(	short	path,
		char *	file,
		char *	name
	)

Create a fully qualified file name from a Path ID/file name combination.

Unlike path_topotentialname(), this routine will only convert a pathname pair to a valid path string if the path exists.

Parameters:

	path	The path to be used.
	file	The file name to be used.
	name	Loaded with the fully extended file name on return.

Returns:

Returns 0 if successful, otherwise it returns an OS-specific error code.

short path_topotentialname	(	short	path,
		char *	file,
		char *	name,
		short	check
	)

Create a fully qualified file name from a Path ID/file name combination, regardless of whether or not the file exists on disk.

Parameters:

	path	The path to be used.
	file	The file name to be used.
	name	Loaded with the fully extended file name on return.
	check	Flag to check if a file with the given path exists.

Returns:

Returns 0 if successful, otherwise it returns an OS-specific error code.

See also:

path_topathname()

short saveas_dialog	(	char *	filename,
		short *	path,
		short *	binptr
	)

Present the user with the standard save file dialog.

The mapping of extensions to types is configured in the C74:/init/max-fileformats.txt file. The standard types to use for Max files are ‘maxb’ for old-format binary files, ‘TEXT’ for text files, and 'JSON' for newer format patchers or other .json files.

Parameters:

	filename	A C-string containing a default name for the file to save. If the user decides to save a file, its name is returned here. The C-string should be allocated with a size of at least MAX_FILENAME_CHARS.
	path	If the user decides to save the file, the Path ID of the location chosen is returned here.
	binptr	Pass NULL for this parameter. This parameter was used in Max 4 to allow the choice of saving binary or text format patchers.

Returns:

0 if the user choose to save the file. If the user cancelled, returns a non-zero value.

See also:

open_dialog()

saveasdialog_extended()

locatefile_extended()

void saveas_promptset

(

char *

s

)

Use saveas_promptset() to add a prompt message to the open file dialog displayed by saveas_dialog() or saveasdialog_extended().

Calling this function before saveasdialog_extended() permits a string to displayed in the dialog box instructing the user as to the purpose of the file being opened. It will only apply to the call of saveasdialog_extended() that immediately follows saveas_promptset().

Parameters:

s

A C-string containing the prompt you wish to display in the dialog box.

Returns:

Ignore.

See also:

open_dialog()

short saveasdialog_extended	(	char *	name,
		short *	vol,
		long *	type,
		long *	typelist,
		short	numtypes
	)

Present the user with the standard save file dialog with your own list of file types.

saveasdialog_extended() is similar to saveas_dialog(), but allows the additional feature of specifying a list of possible types. These will be displayed in a pop-up menu.

File types found in the typelist argument that match known Max types will be displayed with descriptive text. Unmatched types will simply display the type name (for example, "foXx" is not a standard type so it would be shown in the pop-up menu as foXx)

Known file types include:

• TEXT: text file
• maxb: Max binary patcher
• maxc: Max collective
• Midi: MIDI file
• Sd2f: Sound Designer II audio file
• NxTS: NeXT/Sun audio file
• WAVE: WAVE audio file.
• AIFF: AIFF audio file
• mP3f: Max preference file
• PICT: PICT graphic file
• MooV: Quicktime movie file
• aPcs: VST plug-in
• AFxP: VST effect patch data file
• AFxB: VST effect bank data file
• DATA: Raw data audio file
• ULAW: NeXT/Sun audio file

Parameters:

	name	A C-string containing a default name for the file to save. If the user decides to save a file, its name is returned here. The C-string should be allocated with a size of at least MAX_FILENAME_CHARS.
	vol	If the user decides to save the file, the Path ID of the location chosen is returned here.
	type	Returns the type of file chosen by the user.
	typelist	The list of types provided to the user.
	numtypes	The number of file types in typelist.

Returns:

0 if the user choose to save the file. If the user cancelled, returns a non-zero value.

See also:

open_dialog()

locatefile_extended()

Referenced by jit_qt_movie_matrix_to_image(), and jit_qt_utils_moviedataref_create().

long sysfile_close

(

t_filehandle

f

)

Close a file opened with sysfile_open().

This function is similar to FSClose() or fclose(). It should be used instead of system-specific file closing routines in order to make max external code that will compile cross-platform.

Parameters:

f

The t_filehandle structure of the file the user wants to close.

Returns:

An error code.

long sysfile_geteof	(	t_filehandle	f,
		long *	logeof
	)

Get the size of a file handle.

This function is similar to and should be used instead of GetEOF(). The function gets the size of file handle in bytes, and places it in “logeof”.

Parameters:

	f	The file's t_filehandle structure.
	logeof	The file size in bytes is returned to this value.

Returns:

An error code.

long sysfile_getpos	(	t_filehandle	f,
		long *	filepos
	)

Get the current file position of a file handle.

This function is similar to and should be used instead of GetFPos(). The function gets the current file position of file handle in bytes, and places it in "filepos".

Parameters:

	f	The file's t_filehandle structure.
	filepos	The address of a variable to hold the current file position of file handle in bytes.

Returns:

An error code.

short sysfile_openhandle	(	char **	h,
		long	flags,
		t_filehandle *	fh
	)

Create a t_filehandle from a pre-existing handle.

Parameters:

	h	A handle for some data.
	flags	Pass 0 (additional flags are private).
	fh	The address of a t_filehandle which will be allocated.

Returns:

An error code.

short sysfile_openptrsize	(	char *	p,
		long	length,
		long	flags,
		t_filehandle *	fh
	)

Create a t_filehandle from a pre-existing pointer.

Parameters:

	p	A pointer to some data.
	length	The size of p.
	flags	Pass 0 (additional flags are private).
	fh	The address of a t_filehandle which will be allocated.

Returns:

An error code.

long sysfile_read	(	t_filehandle	f,
		long *	count,
		void *	bufptr
	)

Read a file from disk.

This function is similar to FSRead() or fread(). It should be used instead of these functions (or other system-specific file reading routines) in order to make max external code that will compile cross-platform. It reads “count” bytes from file handle at current file position into “bufptr”. The byte count actually read is set in “count”, and the file position is updated by the actual byte count read.

Parameters:

	f	The t_filehandle structure of the file the user wants to open.
	count	Pointer to the number of bytes that will be read from the file at the current file position. The byte count actually read is returned to this value.
	bufptr	Pointer to the buffer that the data will be read into.

Returns:

An error code.

Referenced by jit_bin_read_chunk_info(), jit_bin_read_header(), and jit_bin_read_matrix().

long sysfile_readtextfile	(	t_filehandle	f,
		t_handle	htext,
		long	maxlen,
		long	flags
	)

Read a text file from disk.

This function reads up to the maximum number of bytes given by maxlen from file handle at current file position into the htext handle, performing linebreak translation if set in flags.

Parameters:

	f	The t_filehandle structure of the text file the user wants to open.
	htext	Handle that the data will be read into.
	maxlen	The maximum length in bytes to be read into the handle. Passing the value 0L indicates no maximum (i.e. read the entire file).
	flags	Flags to set linebreak translation as defined in e_max_sysfile_textflags.

Returns:

An error code.

long sysfile_readtohandle	(	t_filehandle	f,
		char ***	h
	)

Read the contents of a file into a handle.

Parameters:

	f	The open t_filehandle structure to read into the handle.
	h	The address of a handle into which the file will be read.

Returns:

An error code.

Remarks:

You should free the pointer, when you are done with it, using sysmem_freehandle().

long sysfile_readtoptr	(	t_filehandle	f,
		char **	p
	)

Read the contents of a file into a pointer.

Parameters:

	f	The open t_filehandle structure to read into the handle.
	p	The address of a pointer into which the file will be read.

Returns:

An error code.

Remarks:

You should free the pointer, when you are done with it, using sysmem_freeptr().

long sysfile_seteof	(	t_filehandle	f,
		long	logeof
	)

Set the size of a file handle.

This function is similar to and should be used instead of SetEOF(). The function sets the size of file handle in bytes, specified by “logeof”.

Parameters:

	f	The file's t_filehandle structure.
	logeof	The file size in bytes.

Returns:

An error code.

long sysfile_setpos	(	t_filehandle	f,
		long	mode,
		long	offset
	)

Set the current file position of a file handle.

This function is similar to and should be used instead of SetFPos(). It is used to set the current file position of file handle to by the given number of offset bytes relative to the mode used, as defined in e_max_sysfile_posmodes.

Parameters:

	f	The file's t_filehandle structure.
	mode	Mode from which the offset will be calculated, as defined in e_max_sysfile_posmodes.
	offset	The offset in bytes relative to the mode.

Returns:

An error code.

Referenced by jit_bin_read_chunk_info(), jit_bin_read_header(), and jit_bin_write_header().

long sysfile_spoolcopy	(	t_filehandle	src,
		t_filehandle	dst,
		long	size
	)

Copy the contents of one file handle to another file handle.

Parameters:

	src	The file handle from which to copy.
	dst	The file handle to which the copy is written.
	size	The number of bytes to copy. If 0 the size of src will be used.

Returns:

An error code.

long sysfile_write	(	t_filehandle	f,
		long *	count,
		const void *	bufptr
	)

Write part of a file to disk.

This function is similar to FSWrite() or fwrite(). It should be used instead of these functions (or other system-specific file reading routines) in order to make max external code that will compile cross-platform. The function writes “count” bytes from “bufptr” into file handle at current file position. The byte count actually written is set in "count", and the file position is updated by the actual byte count written.

Parameters:

	f	The t_filehandle structure of the file to which the user wants to write.
	count	Pointer to the number of bytes that will be written to the file at the current file position. The byte count actually written is returned to this value.
	bufptr	Pointer to the buffer that the data will be read from.

Returns:

An error code.

Referenced by jit_bin_write_header(), and jit_bin_write_matrix().

long sysfile_writetextfile	(	t_filehandle	f,
		t_handle	htext,
		long	flags
	)

Write a text file to disk.

This function writes a text handle to a text file performing linebreak translation if set in flags.

Parameters:

	f	The t_filehandle structure of the text file to which the user wants to write.
	htext	Handle that the data that will be read from.
	flags	Flags to set linebreak translation as defined in e_max_sysfile_textflags.

Returns:

An error code.