MOA Developer's Guide
MOA Interfaces | MOA Methods | MOA Types and Misc API
IMoaFile
Interface ID: IID_IMoaFile
Pointer type: PIMoaFile
Inheritance: IMoaUnknown
Header file: moafile.h
Description
-
The IMoaFile interface is the original file interface for Moa.
It has been superseded by the IMoaFile2 interface.
This interface provides platform-independent methods to represent a specific file in a directory structure.
MoaFile is packaged
as an independent Xtra, containing just the CMoaFile class. CMoaFile implements
the IMoaFile interface,
as well as an IMoaStream interface used in conjunction with IMoaFile (see the IMoaFile::GetStream() method for details).
Call the method IMoaCallback::MoaCreateInstance() using the arguments &CLSID_CMoaFile and &IID_IMoaFile to create a new instance of IMoaFile for your use. After creating it, use SetSpec(), SetSysSpec(), or SetPathnameSpec() to fill in the file information.
To access a stream to the given file, call the GetStream() method. Remember that both the MoaStream and the MoaFile belong
to you; you must release both. The MoaStream may or may not be an interface onto the same object as the MoaFile;
this is an implementation detail that is undefined.
See also
- IMoaFile types, IMoaFile constants, IMoaFile errors
Methods
File specification
- SetSpec()
SetNewTempSpec()
GetSysSpec()
SetSysSpec()
GetPathnameSpec()
SetPathnameSpec()
Creating and deleting files
- CreateFile()
CreateDirectory()
Delete()
Clone()
Exchanging files
- SwapFile()
Naming files
- GetFilename()
SetFilename()
Rename()
File information
- GetSize()
SetSize()
GetAccess()
GetDates()
GetDirectory()
IsDirectory()
IsExisting()
Comparing files
- IsSameFile()
Iterating
- EachFile()
Accessing file data
- GetStream()
Syntax
- Clone(struct IMoaFile ** ppFile)
Parameters
- ppFile
- struct IMoaFile **
Returns
- MoaError
Description
- Clone() returns
a copy of the MoaFile with the same file spec. It does NOT duplicate, copy, or modify
the underlying file in any way; it's just a utility method used
to make a new MoaFile and assign the same file spec to it. The caller must Release() the newly returned MoaFile when done.
Syntax
- CreateDirectory()
Parameters
Returns
- MoaError
Description
- Creates a directory matching the current spec. If a file or
directory matching that spec already exists, an error is returned.
Syntax
- CreateFile()
Parameters
Returns
- MoaError
Description
- Creates a file matching the current spec. If a file or directory
matching that spec already exists, an error is returned.
Syntax
- Delete()
Parameters
Returns
- MoaError
Description
- Deletes the file or directory matching the current spec. If
the spec is a directory, all files and directories contained will
be deleted. If there is no file or directory, an error is returned.
Syntax
-
- EachFile(MoaBoolParam resolveAlias, MoaFileEachProc proc, PMoaVoid refCon)
Parameters
resolveAlias
- MoaBoolParam
- proc
- MoaFileEachProc
- refCon
- PMoaVoid
Returns
- MoaError
Description
- EachFile() is
used to iterate the files and directories in a given directory.
If the file spec is a directory, the files and directories will
be enumerated. If the file spec is a file, just that file will
be enumerated. If resolveAlias is TRUE, all alias/shortcut files
will be resolved prior to passing them to the enumeration proc
(note that in this case, some enumerated files might not actually
be "in" the directory!).
Syntax
- GetAccess(MoaLong * pAccessPerm)
Parameters
- pAccessPerm
- MoaLong *
Returns
- MoaError
Description
- GetAccess() returns
the access privileges allowable for this file (in the form of
a bit mask).
Syntax
- GetDates(MoaWide * pCreate, MoaWide * pModify)
Parameters
- pCreate
- MoaWide *
- pModify
- MoaWide *
Returns
- MoaError
Description
- GetDates() returns
the creation and modification dates of this file. This method
does not operate on directories (an error is returned).
Syntax
- GetDirectory(struct IMoaFile ** pDir)
Parameters
- pDir
- struct IMoaFile * *
Returns
- MoaError
Description
- GetDirectory() returns a PIMoaFile for this file's parent directory. The caller must Release() it when done.
Syntax
- GetFilename(PMoaChar pNameBuf, MoaLong nameBufSize)
Parameters
- pNameBuf
- PMoaChar
- nameBufSize
- MoaLong
Returns
- MoaError
Description
- Returns the file/directory name from the current spec. SetFilename() changes the filename portion of the file spec without renaming
the file. In other words, you can use this call to change just
the "leaf" portion of the file spec. Note that this
call causes the MoaFile to refer to another file, while Rename() causes the MoaFile to rename the given file and refer to the file by the given name.
Syntax
- GetPathnameSpec(PMoaChar pNameBuf, MoaLong nameBufSize)
Parameters
- pNameBuf
- PMoaChar
- nameBufSize
- MoaLong
Returns
- MoaError
Description
- Takes the file description from a pathname on all platforms. GetPathnameSpec returns
the existing file description in similar form. SetPathnameSpec and GetPathnameSpec will return errors if directories in the path are missing, but
not if the file is missing.
Syntax
-
- GetSize(MoaLong * pFileLen)
Parameters
- pFileLen
- MoaLong *
Returns
- MoaError
Description
- GetSize() returns
the size, in bytes, of the data fork of a file.
Syntax
- GetStream(MoaLong bufferSize, PIMoaStream * ppStream)
Parameters
- bufferSize
- MoaLong
- ppStream
- PIMoaStream *
Returns
- MoaError
Description
- GetStream() creates
an IMoaStream to the
given file. If the spec is a directory, an error is returned.
The caller must Release() the stream when done.
Syntax
- GetSysSpec(PMoaSystemFileSpec pSpec, MoaLong specBufSize)
Parameters
- pSpec
- PMoaSystemFileSpec
- specBufSize
- MoaLong
Returns
- MoaError
Description
- Takes the file description from an FSSpec (Macintosh) or pathname
(Windows). It optionally resolves alias/shortcut files. GetSysSpec() returns the existing file description in a similar form.
Syntax
- IsDirectory()
Parameters
Returns
- MoaError
Description
- IsDirectory() is used to determine if the IMoaFile specifies a directory (vs. a file); kMoaErr_NoErr is returned if the spec is a directory.
Syntax
- IsExisting()
Parameters
Returns
- MoaError
Description
- IsExisting() is
used to determine if the IMoaFile specifies an existing file entity; kMoaErr_NoErr is returned if the spec exists.
Syntax
- IsSameFile(struct IMoaFile * pOther)
Parameters
- pOther
- struct IMoaFile *
Returns
- MoaError
Description
- IsSameFile() is
used to determine if to IMoaFiles refer to the same file entity;
kMoaErr_NoErr is returned if they do. The file entities need not exist for the
result to be valid.
Syntax
- Rename(ConstPMoaChar pNameBuf)
Parameters
- pNameBuf
- ConstPMoaChar
Returns
- MoaError
Description
-
Returns the file/directory name from the current spec.
SetFilename() changes the filename portion of the file spec without renaming
the file. In other words, you can use this call to change just
the "leaf" portion of the file spec. Note that this
call causes the MoaFile to refer to another file,
while Rename() causes the MoaFile to rename the given file
and refer to the file by the given name.
Rename() renames the file.
Note that this call will NOT move the file (ie, the argument is
a filename, not a pathname). The MoaFile's internal file spec is updated to reflect the new name.
Syntax
- SetFilename(ConstPMoaChar pNameBuf)
Parameters
- pNameBuf
- ConstPMoaChar
Returns
- MoaError
Description
- Returns the file/directory name from the current spec.
SetFilename() changes the filename portion of the file spec without renaming
the file. In other words, you can use this call to change just
the "leaf" portion of the file spec. Note that this
call causes the MoaFile to refer to another file,
while Rename() causes the MoaFile to rename the given file
and refer to the file by the given name.
Syntax
- SetNewTempSpec(struct IMoaFile * pDir)
Parameters
- pDir
- struct IMoaFile *
Returns
- MoaError
Description
- Creates a unique file description that matches no existing
file. It does not create the file itself. The file description
is in pDir, or an arbitrary directory if pDir is NULL.
Syntax
- SetPathnameSpec(ConstPMoaChar pNameBuf, MoaBoolParam resolveAlias)
Parameters
- pNameBuf
- ConstPMoaChar
- resolveAlias
- MoaBoolParam
Returns
- MoaError
Description
- Takes the file description from a pathname on all platforms. GetPathnameSpec returns
the existing file description in similar form. SetPathnameSpec
and GetPathnameSpec will return errors if directories in the path are missing, but
not if the file is missing.
Syntax
- SetSize(MoaLong fileLen)
Parameters
- fileLen
- MoaLong
Returns
- MoaError
Description
- SetSize() sets
the size, in bytes, of the data fork of a file; if the file is
shorter, enough space is reserved for the given number of bytes;
if the file is longer, all extra bytes are removed.
Syntax
- SetSpec(struct IMoaFile * pDir, ConstPMoaChar pFileName)
Parameters
- pDir
- struct IMoaFile *
- pFileName
- ConstPMoaChar
Returns
- MoaError
Description
- Takes the file description from a file name and directory
specifier; the directory is provided by another IMoaFile.
NULL can be passed for the directory spec, in which case the file
will be specified in the "current" directory (implementation
defined).
Syntax
- SetSysSpec(ConstPMoaSystemFileSpec pSpec, MoaBoolParam resolveAlias)
Parameters
- pSpec
- ConstPMoaSystemFileSpec
- resolveAlias
- MoaBoolParam
Returns
- MoaError
Description
- Takes the file description from an FSSpec (Macintosh) or pathname
(Windows). It optionally resolves alias/shortcut files.
GetSysSpec() returns the existing file description in a similar form.
Syntax
- SwapFile(struct IMoaFile * pOther)
Parameters
- pOther
- struct IMoaFile *
Returns
- MoaError
Description
- SwapFile(): If
this and other are both existing files (not directories), the
files are swapped such that the spec for "this" now
points to "other" and vice versa. If "this"
exists, but "other" does not, "this" is moved
(not copied) to "other". If this doesn't exist but other
does, it's an error. SwapFile() only works
if this and other are on the same volume. SwapFile()
doesn't work if either this or other are directories.
Copyright © 1995-2008 Adobe Macromedia Software LLC, Inc.