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 provided by the MoaFile Xtra. 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(PIMoaFileThis,
struct IMoaFile FAR * FAR *ppFile)
Parameters
-
This
- Pointer to the
IMoaFile
interface
ppFile
- struct IMoaFile FAR * FAR *
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(PIMoaFileThis)
Parameters
-
This
- Pointer to the
IMoaFile
interface
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(PIMoaFileThis)
Parameters
-
This
- Pointer to the
IMoaFile
interface
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(PIMoaFileThis)
Parameters
-
This
- Pointer to the
IMoaFile
interface
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(PIMoaFileThis,
MoaBoolParamresolveAlias,
MoaFileEachProcproc,
PMoaVoidrefCon)
Parameters
-
This
- Pointer to the
IMoaFile
interface
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(PIMoaFileThis,
MoaLong FAR *pAccessPerm)
Parameters
-
This
- Pointer to the
IMoaFile
interface
pAccessPerm
- MoaLong FAR *
Returns
-
MoaError
Description
-
- GetAccess() returns
the access privileges allowable for this file (in the form of
a bit mask).
Syntax
-
- GetDates(PIMoaFileThis,
MoaWide FAR *pCreate,
MoaWide FAR *pModify)
Parameters
-
This
- Pointer to the
IMoaFile
interface
pCreate
- MoaWide FAR *
pModify
- MoaWide FAR *
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(PIMoaFileThis,
struct IMoaFile FAR * FAR *pDir)
Parameters
-
This
- Pointer to the
IMoaFile
interface
pDir
- struct IMoaFile FAR * FAR *
Returns
-
MoaError
Description
-
- GetDirectory() returns a PIMoaFile for this file's parent directory. The caller must Release() it when done.
Syntax
-
- GetFilename(PIMoaFileThis,
PMoaCharpNameBuf,
MoaLongnameBufSize)
Parameters
-
This
- Pointer to the
IMoaFile
interface
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(PIMoaFileThis,
PMoaCharpNameBuf,
MoaLongnameBufSize)
Parameters
-
This
- Pointer to the
IMoaFile
interface
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(PIMoaFileThis,
MoaLong FAR *pFileLen)
Parameters
-
This
- Pointer to the
IMoaFile
interface
pFileLen
- MoaLong FAR *
Returns
-
MoaError
Description
-
- GetSize() returns
the size, in bytes, of the data fork of a file.
Syntax
-
- GetStream(PIMoaFileThis,
MoaLongbufferSize,
PIMoaStream FAR *ppStream)
Parameters
-
This
- Pointer to the
IMoaFile
interface
bufferSize
- MoaLong
ppStream
- PIMoaStream FAR *
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(PIMoaFileThis,
PMoaSystemFileSpecpSpec,
MoaLongspecBufSize)
Parameters
-
This
- Pointer to the
IMoaFile
interface
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(PIMoaFileThis)
Parameters
-
This
- Pointer to the
IMoaFile
interface
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(PIMoaFileThis)
Parameters
-
This
- Pointer to the
IMoaFile
interface
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(PIMoaFileThis,
struct IMoaFile FAR *pOther)
Parameters
-
This
- Pointer to the
IMoaFile
interface
pOther
- struct IMoaFile FAR *
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(PIMoaFileThis,
ConstPMoaCharpNameBuf)
Parameters
-
This
- Pointer to the
IMoaFile
interface
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(PIMoaFileThis,
ConstPMoaCharpNameBuf)
Parameters
-
This
- Pointer to the
IMoaFile
interface
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(PIMoaFileThis,
struct IMoaFile FAR *pDir)
Parameters
-
This
- Pointer to the
IMoaFile
interface
pDir
- struct IMoaFile FAR *
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(PIMoaFileThis,
ConstPMoaCharpNameBuf,
MoaBoolParamresolveAlias)
Parameters
-
This
- Pointer to the
IMoaFile
interface
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(PIMoaFileThis,
MoaLongfileLen)
Parameters
-
This
- Pointer to the
IMoaFile
interface
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(PIMoaFileThis,
struct IMoaFile FAR *pDir,
ConstPMoaCharpFileName)
Parameters
-
This
- Pointer to the
IMoaFile
interface
pDir
- struct IMoaFile FAR *
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(PIMoaFileThis,
ConstPMoaSystemFileSpecpSpec,
MoaBoolParamresolveAlias)
Parameters
-
This
- Pointer to the
IMoaFile
interface
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(PIMoaFileThis,
struct IMoaFile FAR *pOther)
Parameters
-
This
- Pointer to the
IMoaFile
interface
pOther
- struct IMoaFile FAR *
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-2007 Adobe Macromedia Software LLC, Inc.