Max 5 API Reference

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

t_filehandle

File Names

File Path Names

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


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.


Enumeration Type Documentation

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)

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.

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

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

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

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.

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.


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

Copyright © 2008, Cycling '74