MF II Developer's Guide
MF II Interfaces | MF II Methods | MF II Types and Misc API
This document contains the following sections:
IMoaFile2
provides a consistent way to access files
via standard paths: either file paths for local file access or
URLs for http and ftp file access. IMoaFile2
supersedes IMoaFile
, which is still used by the MoaFile Xtra
supplied with Director. IMoaFile2
has many of the same methods as, but doesn't inherit from, IMoaFile
.
IMoaPathName
provides a cross-platform representation
of paths, both for local access by filename and for http or ftp
file access via URL. It supports expressing path name strings
in the dialects of various host platforms.
IMoaStream2
, which inherits from IMoaStream
,
provides methods for accessing streams of bytes from a file. To
read or write data to a file, you acquire an IMoaStream2
interface from an instance of IMoaFile2
, then invoke
the data access methods of the stream.
IMoaIOAttributes
is an interface provided by an instance
of IMoaFile2
to represent its behavior. The IO attributes
let you determine information about the file itself, and how to
handle the IMoaStream2
interfaces you acquire from
it. IMoaIOAttributes
is a synonym for IMoaDict
.
IMoaFile2
is implemented in Director for local file
access. To acquire this interface, you call IMoaCallback::CreateInstance()
,
passing the class id CLSID_CMoaFile2
and the interface
id IID_IMoaFile2
.
IMoaFile2
is implemented for URL access to HTTP and
FTP files through the NetFile2 Xtra This Xtra is named NetFile.x32
on Windows, and NetFile PPC on the Macintosh. This Xtra is
shipped with Director. In addition to
this Xtra, you also need the INetURL Xtra, also shipped with the
applications. This Xtra is named INetUrl.x32 on the Windows
and INetUrl PPC on the Power Mac. On PPC
Macintoshes, you also need NetManage WinSock Library.
Note that in Director, the IMoaFile2
interface provided
by the NetFile Xtra can also do local file access--it does so
by working with the built-in implementation of the interface.
For Xtras running in Shockwave, Netscape Navigator and Microsoft
Internet Explorer both provide the standard Net Xtras for URL
access (See the Director Shockwave documentation for more).
IMoaFile2 provides three methods to get and set a file
object's path name. GetPathName() and SetPathName()use
the IMoaPathName interface. GetPathName() returns
a pointer to an instance of the IMoaPathName interface.
It can be used to set the file name path and other details of
the target file using the SetPathName() method. SetPathName() sets the MoaFile object's underlying path name using
a previously resolved IMoaPathName object. The given IMoaPathName interface is cloned so the client doesn't
have a reference to the same interface as the MoaFile2 implementation.
SetPathSpec() sets the MoaFile object's underlying
path name to a specified string.
You can retrieve information about files using four methods: EnumFiles(), IsDirectory(), IsExisting(), IsSameFile().
EnumFiles() lists all entries in the current directory.
For each entry in the current directory, the following data is
returned: the IMoaPathName interface to the current file,
whether or not the file is a directory, the last date the file
was modified, the file type, and the client data passed into EnumFiles().
IsDirectory() returns TRUE if the underlying path name
points to a directory. IsExisting() returns TRUE if the
object pointed to by the underlying path name exists. IsSameFile() returns TRUE if the current IMoaFile instance and an
instance pointer point to the same file or directory.
You can retrieve and set the following file attributes: size,
access privileges, dates (create, modify, and access), and cache
priority.
The GetSize() and SetSize() methods retrieve
and set the file size. GetAccess() and SetAccess() return and set the file access permissions. GetDates() and SetDates() return and set the creation, last modification,
last access dates, or any combination of these dates. If the file
is remote, you can call the GetCachePriority() and SetCachePriority() methods to return and set the following cache priorities:
Always, If You Can, or Never.
You can also use the GetMoaIOAttributeDict() to get an IMoaIOAttribute interface. With this interface, you can
access the various file attributes of the object pointed to by
the underlying path name. See the header file (MOAFILE2.H) for
specific information on GetMoaIOAttributeDict().
You can create, delete, swap, rename, and clone files and directories. CreateFile() creates a new file. CreateDirectory() creates a new directory. Delete() deletes the file or
directory specified by the underlying path name. SwapFile() exchanges two files specified by IMoaFile2 instances. Rename() changes the name of the file or directory pointed
to by the underlying path name. Clone() creates a new IMoaFile2 object identical to the current instance.
You can use two methods to initialize paths: InitFromString() and SetTempPath(). InitFromString() intializes the current IMoaPathName object from a path string. SetTempPath() creates a temporary path instance with a unique name.
You can change path names with a variety of methods. Resolve() resolves the current instance into a fully qualified path. RemoveFinal() removes the final component of the current path name, while AddFinal() adds the string (representing either a directory
or file name) passed in to the current path name. Concat() concatenates the path name of the current instance with a
specified instance. SetExtension() sets the extension
of the current file name.
SetVolumeName() sets the volume name of the current path
name. For the Macintosh, this is the name of the target volume.
For MS-DOS, it is the drive letter of the target volume.
There are several methods that deal specifically with URL-style
paths; these methods have no effect on non-URL paths. SetScheme() sets the scheme component of the path name. SetHostName() sets the host name component of the path name. SetPort() sets the port component of the path name. SetUserID() sets the user ID component of the path name. SetPassword() sets the password component of the path name. SetParameters() sets any miscellaneous components of the path name. SetAnchor() sets the anchor component of the path name.
You can find out whether or not a path is empty, absolute, relative,
canonical, or equal to another path using the following methods: IsEmpty(), IsAbsolute(), IsRelative(), IsCanonical(), and AreEqual().
You can also use the following methods to retrieve other information. GetPath() returns a pointer to a string containing the
current path name. GetDisplayPath() returns the display
path for the path. GetDisplayFileName() returns the display
file name for the path. GetExtension() returns the extension
of the current file.
GetVolumeName() returns the volume name of the current
path name. For the Macintosh, this is the name of the volume.
For MS-DOS, it is the drive letter of the volume.
There are several methods that deal specifically with URL-style
paths; these methods have no effect on non-URL paths. GetScheme() returns the scheme component of the path name. GetHostName() returns the host name component of the path name. GetPort() returns the port component of the path name. GetUserID() returns the user ID component of the path name. GetPassword() returns the password component of the path name. GetParameters() returns user-defined components of the path name. GetAnchor() returns the anchor component of the path name.
You can retrieve related paths using the GetParentDirectory(), GetWorkingDirectory(), GetRelativePath(), and Clone() methods.
GetParentDirectory() returns a PIMoaPathName that
references the current instance's parent directory. GetWorkingDirectory() returns a PIMoaPathName that references the current
working directory. GetRelativePath() returns a PIMoaPathName that contains the relative path from the current instance
to the destination path in the specified instance. Clone() creates an IMoaPathName instance identical to the
current instance.
You can use the InitFromFSSpec() and GetFSSpec() for Macintosh-specific operations.
The IMoaIOAttributes
interface provides a mechanism
for getting information about the behavior of a stream or file.
This interface is a synonym for the IMoaDict
interface
used to register Xtras. Each implementation of IMoaFile2
and IMoaStream2
can provide an instance of the IMoaIOAttributes
interface to specify its behavior. The following entries can
be found in this dictionary. A list of constants associated with these entries is available
in Moa File Access II Types and Miscellaneous API.
IMoaStream2 Attributes | Type | Entry Size (bytes) | Value |
Flags | PMoaLong | 4 | logical OR of 0 or more of: kMoaStreamFlag_HasAsyncIO , kMoaStreamFlag_HasBufferredIO , kMoaStreamFlag_HasDirectBufferAccess |
AccessMode | PMoaLong | 4 | One of kMoaStreamOpenAccess_ReadOnly, kMoaStreamOpenAccess_ReadWrite, kMoaStreamOpenAccess_WriteOnly |
BufferSize | PMoaLong | 4 | Buffer size in bytes |
DataRate | PMoaLong | 4 | |
End | PMoaLong | 4 | End of stream in bytes |
CurrentLength | PMoaLong | 4 | Length of stream in bytes |
Position | PMoaLong | 4 | Current position in stream in bytes |
PositionType | PMoaLong | 4 | One of kMoaStreamSetPositionType_None, kMoaStreamSetPositionType_Expensive, kMoaStreamSetPositionType_Cheap |
IMoaFile2 Attributes | Type | Size (bytes) |
Values |
Flags | PMoaLong | 4 | Logical OR of 0 or more of: kMoaFileFlag_IsExistant, |
AccessPerm | PMoaLong | 4 | One of kMoaFileAccessPerm_Read, kMoaFileAccessPerm_Write |
Length | PMoaLong | 4 | Length of file in bytes |
Type | PMoaChar | N/A | |
Encoding | PMoaChar | N/A | |
Creator | PMoaChar | N/A | |
CreateDate | PMoaWide | 8 | |
ModifyDate | PMoaWide | 8 | |
AccessDate | PMoaWide | 8 | |
CachePriority | PMoaLong | 4 |
Volume Attributes | Type | Size (bytes) | Values |
Flags | PMoaLong | 4 | Logical OR of kMoaVolFlag_IsRemovable, kMoaVolFlag_IsCDROM, kMoaVolFlag_IsHardDisk, kMoaVolFlag_IsNetworkDrive |
BlockSize | PMoaLong | 4 | File system block size in bytes |
SectorSize | PMoaLong | 4 | File system sector size in bytes |
FreeSpace | PMoaLong | 4 | Remaining space in bytes |