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.

File Path Names

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:

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

The size you should use when allocating strings for filenames.

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

Typedef Documentation

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.

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

(

C74_CONST 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.'

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:

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.

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.

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

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

(

C74_CONST short

path,

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

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.

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.

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.

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.

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.