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... | |
Macros | |
| #define | MAX_PATH_CHARS |
| The size you should use when allocating strings for full paths. | |
| #define | MAX_FILENAME_CHARS |
| The size you should use when allocating strings for filenames. More... | |
Typedefs | |
| typedef t_filestruct * | t_filehandle |
| A t_filehandle is a cross-platform way of referring to an open file. More... | |
Functions | |
| short | path_getapppath (void) |
| Retrieve the Path ID of the Max application. More... | |
| short | locatefile (C74_CONST char *name, short *outvol, short *binflag) |
| Find a Max document by name in the search path. More... | |
| short | locatefiletype (C74_CONST char *name, short *outvol, t_fourcc filetype, t_fourcc creator) |
| Find a Max document by name in the search path. More... | |
| short | locatefile_extended (char *name, short *outvol, t_fourcc *outtype, C74_CONST t_fourcc *filetypelist, short numtypes) |
| Find a file by name. More... | |
| short | path_resolvefile (char *name, C74_CONST 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. More... | |
| short | path_fileinfo (C74_CONST char *name, C74_CONST short path, t_fileinfo *info) |
| Retrive a t_fileinfo structure from a file/path combination. More... | |
| 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. More... | |
| short | path_frompathname (C74_CONST char *name, short *path, char *filename) |
| Create a filename and Path ID combination from a fully qualified file name. More... | |
| void | path_setdefault (short path, short recursive) |
| Install a path as the default search path. More... | |
| short | path_getdefault (void) |
| Retrieve the Path ID of the default search path. More... | |
| short | path_getmoddate (short path, t_ptr_uint *date) |
| Determine the modification date of the selected path. More... | |
| short | path_getfilemoddate (C74_CONST char *filename, C74_CONST short path, t_ptr_uint *date) |
| Determine the modification date of the selected file. More... | |
| void * | path_openfolder (short path) |
| Prepare a directory for iteration. More... | |
| short | path_foldernextfile (void *xx, t_fourcc *filetype, char *name, short descend) |
| Get the next file in the directory. More... | |
| void | path_closefolder (void *x) |
| Complete a directory iteration. More... | |
| short | path_opensysfile (C74_CONST char *name, C74_CONST short path, t_filehandle *ref, short perm) |
| Open a file given a filename and Path ID. More... | |
| short | path_createsysfile (C74_CONST char *name, short path, t_fourcc type, t_filehandle *ref) |
| Create a file given a type code, a filename, and a Path ID. More... | |
| short | path_nameconform (C74_CONST char *src, char *dst, long style, long type) |
| Convert a source path string to destination path string using the specified style and type. More... | |
| short | path_topotentialname (C74_CONST short path, C74_CONST 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. More... | |
| t_max_err | path_toabsolutesystempath (const short in_path, const char *in_filename, char *out_filepath) |
| Translates a Max path+filename combo into a correct POSIX absolute path that can be used to pass to libraries and also handles multiple volumes correctly. More... | |
| t_max_err | path_absolutepath (t_symbol **returned_path, const t_symbol *s, const t_fourcc *filetypelist, short numtypes) |
| Convert a path to an absolutepath as done by the absolutepath object in Max. More... | |
| void | open_promptset (C74_CONST char *s) |
| Use open_promptset() to add a prompt message to the open file dialog displayed by open_dialog(). More... | |
| void | saveas_promptset (C74_CONST char *s) |
| Use saveas_promptset() to add a prompt message to the open file dialog displayed by saveas_dialog() or saveasdialog_extended(). More... | |
| void * | filewatcher_new (t_object *owner, C74_CONST short path, C74_CONST char *filename) |
| Create a new filewatcher. More... | |
| void | fileusage_addfile (void *w, long flags, C74_CONST char *name, C74_CONST short path) |
| Add a file to a collective. More... | |
| void | fileusage_addpackage (void *w, C74_CONST char *name, t_object *subfoldernames) |
| Add a package to a standalone. More... | |
| short | open_dialog (char *name, short *volptr, t_fourcc *typeptr, t_fourcc *types, short ntypes) |
| Present the user with the standard open file dialog. More... | |
| short | saveas_dialog (char *filename, short *path, short *binptr) |
| Present the user with the standard save file dialog. More... | |
| short | saveasdialog_extended (char *name, short *vol, t_fourcc *type, t_fourcc *typelist, short numtypes) |
| Present the user with the standard save file dialog with your own list of file types. More... | |
| BEGIN_USING_C_LINKAGE t_max_err | sysfile_close (t_filehandle f) |
| Close a file opened with sysfile_open(). More... | |
| t_max_err | sysfile_read (t_filehandle f, t_ptr_size *count, void *bufptr) |
| Read a file from disk. More... | |
| t_max_err | sysfile_readtohandle (t_filehandle f, char ***h) |
| Read the contents of a file into a handle. More... | |
| t_max_err | sysfile_readtoptr (t_filehandle f, char **p) |
| Read the contents of a file into a pointer. More... | |
| t_max_err | sysfile_write (t_filehandle f, t_ptr_size *count, const void *bufptr) |
| Write part of a file to disk. More... | |
| t_max_err | sysfile_seteof (t_filehandle f, t_ptr_size logeof) |
| Set the size of a file handle. More... | |
| t_max_err | sysfile_geteof (t_filehandle f, t_ptr_size *logeof) |
| Get the size of a file handle. More... | |
| t_max_err | sysfile_setpos (t_filehandle f, t_sysfile_pos_mode mode, t_ptr_int offset) |
| Set the current file position of a file handle. More... | |
| t_max_err | sysfile_getpos (t_filehandle f, t_ptr_size *filepos) |
| Get the current file position of a file handle. More... | |
| t_max_err | sysfile_spoolcopy (t_filehandle src, t_filehandle dst, t_ptr_size size) |
| Copy the contents of one file handle to another file handle. More... | |
| t_max_err | sysfile_readtextfile (t_filehandle f, t_handle htext, t_ptr_size maxlen, t_sysfile_text_flags flags) |
| Read a text file from disk. More... | |
| t_max_err | sysfile_writetextfile (t_filehandle f, t_handle htext, t_sysfile_text_flags flags) |
| Write a text file to disk. More... | |
| t_max_err | sysfile_openhandle (char **h, t_sysfile_flags flags, t_filehandle *fh) |
| Create a t_filehandle from a pre-existing handle. More... | |
| t_max_err | sysfile_openptrsize (char *p, t_ptr_size length, t_sysfile_flags flags, t_filehandle *fh) |
| Create a t_filehandle from a pre-existing pointer. More... | |
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 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.
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:
Where my file usage has the prototype:
Then you can use fileusage_addfile() to add any requisite files to the collective.
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 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 t_filestruct* 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.
| 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) |
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 |
| PATH_NOALIASRESOLUTION |
no alias resolution |
| enum e_max_path_styles |
Constants that determine the output of path_nameconform().
| enum e_max_path_types |
Constants that determine the output of path_nameconform().
| enum t_sysfile_pos_mode |
Modes used by sysfile_setpos()
| enum t_sysfile_text_flags |
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. |
| void fileusage_addfile | ( | void * | w, |
| long | flags, | ||
| C74_CONST char * | name, | ||
| C74_CONST short | path | ||
| ) |
Add a file to a collective.
| 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 fileusage_addpackage | ( | void * | w, |
| C74_CONST char * | name, | ||
| t_object * | subfoldernames | ||
| ) |
Add a package to a standalone.
| w | Handle for the standalone builder |
| name | The name of the package |
| subfoldernames | A t_atomarray containing symbols, each of which is a foldername in the package to include. Pass NULL to include the entire package contents. |
| void* filewatcher_new | ( | t_object * | owner, |
| C74_CONST short | path, | ||
| C74_CONST 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().
| 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. |
| 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
| 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. |
| short locatefile_extended | ( | char * | name, |
| short * | outvol, | ||
| t_fourcc * | outtype, | ||
| C74_CONST t_fourcc * | filetypelist, | ||
| short | numtypes | ||
| ) |
Find a file by name.
If a complete path is not specified, search for the name in the search path. This is the preferred method for file searching since its introduction in Max version 4.
| name | The file name for the search, receives actual filename upon return. |
| outvol | The Path ID of the file (if found). |
| outtype | The file type of the file (if found). |
| filetypelist | The file type(s) for which you are searching for, or NULL if any type is acceptable. |
| numtypes | The number of file types in the typelist array (1 if a single entry, 0 if any type is acceptable). |
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:
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.
| 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. |
| short open_dialog | ( | char * | name, |
| short * | volptr, | ||
| t_fourcc * | typeptr, | ||
| t_fourcc * | 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.
| 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. |
| void open_promptset | ( | C74_CONST 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().
| s | A C-string containing the prompt you wish to display in the dialog box. |
| t_max_err path_absolutepath | ( | t_symbol ** | returned_path, |
| const t_symbol * | s, | ||
| const t_fourcc * | filetypelist, | ||
| short | numtypes | ||
| ) |
Convert a path to an absolutepath as done by the absolutepath object in Max.
| returned_path | Address to a symbol pointer which will be filled-in upon successful return. |
| s | Incoming (non-absolute) path. |
| filetypelist | The first of an array of file types to limit the search. |
| numtypes | The number of entries in the filetypelist parameter. |
| void path_closefolder | ( | void * | x | ) |
Complete a directory iteration.
| x | The "folder state" value originally returned by path_openfolder(). |
| short path_createsysfile | ( | C74_CONST char * | name, |
| short | path, | ||
| t_fourcc | type, | ||
| t_filehandle * | ref | ||
| ) |
Create a file given a type code, a filename, and a Path ID.
| 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. |
| short path_fileinfo | ( | C74_CONST char * | name, |
| C74_CONST short | path, | ||
| t_fileinfo * | info | ||
| ) |
Retrive a t_fileinfo structure from a file/path combination.
| 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. |
| short path_foldernextfile | ( | void * | xx, |
| t_fourcc * | 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.
| 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. |
| short path_frompathname | ( | C74_CONST 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().
| name | The extended file path to be converted. |
| path | Contains the Path ID on return. |
| filename | Contains the file name on return. |
| short path_getapppath | ( | void | ) |
Retrieve the Path ID of the Max application.
| short path_getdefault | ( | void | ) |
Retrieve the Path ID of the default search path.
| short path_getfilemoddate | ( | C74_CONST char * | filename, |
| C74_CONST short | path, | ||
| t_ptr_uint * | date | ||
| ) |
Determine the modification date of the selected file.
| 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. |
| short path_getmoddate | ( | short | path, |
| t_ptr_uint * | date | ||
| ) |
Determine the modification date of the selected path.
| path | The Path ID of the directory to check. |
| date | The last modification date of the directory. |
| short path_nameconform | ( | C74_CONST char * | src, |
| char * | dst, | ||
| long | style, | ||
| long | type | ||
| ) |
Convert a source path string to destination path string using the specified style and type.
| 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 |
| void* path_openfolder | ( | short | path | ) |
Prepare a directory for iteration.
| path | The directory Path ID to open. |
| short path_opensysfile | ( | C74_CONST char * | name, |
| C74_CONST short | path, | ||
| t_filehandle * | ref, | ||
| short | perm | ||
| ) |
Open a file given a filename and Path ID.
| 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. |
| short path_resolvefile | ( | char * | name, |
| C74_CONST 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.
| 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. |
| 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.
| 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. |
| t_max_err path_toabsolutesystempath | ( | const short | in_path, |
| const char * | in_filename, | ||
| char * | out_filepath | ||
| ) |
Translates a Max path+filename combo into a correct POSIX absolute path that can be used to pass to libraries and also handles multiple volumes correctly.
| in_path | The Max path reference |
| in_filename | The name of the file in that path. |
| out_filepath | A string that is MAX_PATH_CHARS in length, which will receive the formatted absolute path upon return. |
| 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.
| path | The path to be used. |
| file | The file name to be used. |
| name | Loaded with the fully extended file name on return. |
| short path_topotentialname | ( | C74_CONST short | path, |
| C74_CONST 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.
| 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. |
| 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.
| 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. |
| void saveas_promptset | ( | C74_CONST 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().
| s | A C-string containing the prompt you wish to display in the dialog box. |
| short saveasdialog_extended | ( | char * | name, |
| short * | vol, | ||
| t_fourcc * | type, | ||
| t_fourcc * | 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:
| 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. |
| BEGIN_USING_C_LINKAGE t_max_err 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.
| f | The t_filehandle structure of the file the user wants to close. |
| t_max_err sysfile_geteof | ( | t_filehandle | f, |
| t_ptr_size * | 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?.
| f | The file's t_filehandle structure. |
| logeof | The file size in bytes is returned to this value. |
| t_max_err sysfile_getpos | ( | t_filehandle | f, |
| t_ptr_size * | 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".
| f | The file's t_filehandle structure. |
| filepos | The address of a variable to hold the current file position of file handle in bytes. |
| t_max_err sysfile_openhandle | ( | char ** | h, |
| t_sysfile_flags | flags, | ||
| t_filehandle * | fh | ||
| ) |
Create a t_filehandle from a pre-existing handle.
| h | A handle for some data, data is *not* copied and *not* freed on file close. |
| flags | Pass 0 (additional flags are private). |
| fh | The address of a t_filehandle which will be allocated. |
| t_max_err sysfile_openptrsize | ( | char * | p, |
| t_ptr_size | length, | ||
| t_sysfile_flags | flags, | ||
| t_filehandle * | fh | ||
| ) |
Create a t_filehandle from a pre-existing pointer.
| p | A pointer to some data. Data is *not* copied and *not* freed on file close. |
| length | The size of p. |
| flags | Pass 0 (additional flags are private). |
| fh | The address of a t_filehandle which will be allocated. |
| t_max_err sysfile_read | ( | t_filehandle | f, |
| t_ptr_size * | 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.
| 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. |
Referenced by jit_bin_read_chunk_info(), jit_bin_read_header(), and jit_bin_read_matrix().
| t_max_err sysfile_readtextfile | ( | t_filehandle | f, |
| t_handle | htext, | ||
| t_ptr_size | maxlen, | ||
| t_sysfile_text_flags | 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.
| 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 t_sysfile_text_flags. |
| t_max_err sysfile_readtohandle | ( | t_filehandle | f, |
| char *** | h | ||
| ) |
Read the contents of a file into a handle.
| f | The open t_filehandle structure to read into the handle. |
| h | The address of a handle into which the file will be read. |
| t_max_err sysfile_readtoptr | ( | t_filehandle | f, |
| char ** | p | ||
| ) |
Read the contents of a file into a pointer.
| f | The open t_filehandle structure to read into the handle. |
| p | The address of a pointer into which the file will be read. |
| t_max_err sysfile_seteof | ( | t_filehandle | f, |
| t_ptr_size | 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?.
| f | The file's t_filehandle structure. |
| logeof | The file size in bytes. |
| t_max_err sysfile_setpos | ( | t_filehandle | f, |
| t_sysfile_pos_mode | mode, | ||
| t_ptr_int | 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 t_sysfile_pos_mode.
| f | The file's t_filehandle structure. |
| mode | Mode from which the offset will be calculated, as defined in t_sysfile_pos_mode. |
| offset | The offset in bytes relative to the mode. |
Referenced by jit_bin_read_chunk_info(), jit_bin_read_header(), and jit_bin_write_header().
| t_max_err sysfile_spoolcopy | ( | t_filehandle | src, |
| t_filehandle | dst, | ||
| t_ptr_size | size | ||
| ) |
Copy the contents of one file handle to another file handle.
| 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. |
| t_max_err sysfile_write | ( | t_filehandle | f, |
| t_ptr_size * | 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.
| 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. |
Referenced by jit_bin_write_header(), and jit_bin_write_matrix().
| t_max_err sysfile_writetextfile | ( | t_filehandle | f, |
| t_handle | htext, | ||
| t_sysfile_text_flags | flags | ||
| ) |
Write a text file to disk.
This function writes a text handle to a text file performing linebreak translation if set in flags.
| 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 t_sysfile_text_flags. |
