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

Clone()

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.

CreateDirectory()

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.

CreateFile()

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.

Delete()

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.

EachFile()

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

GetAccess()

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

GetDates()

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

GetDirectory()

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.

GetFilename()

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.

GetPathnameSpec()

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.

GetSize()

Syntax

GetSize(MoaLong * pFileLen)

Parameters

pFileLen
MoaLong *

Returns

MoaError

Description

GetSize() returns the size, in bytes, of the data fork of a file.

GetStream()

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.

GetSysSpec()

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.

IsDirectory()

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.

IsExisting()

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.

IsSameFile()

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.

Rename()

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.

SetFilename()

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.

SetNewTempSpec()

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.

SetPathnameSpec()

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.

SetSize()

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.

SetSpec()

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

SetSysSpec()

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.

SwapFile()

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.