IMoaPathName

Interface ID: IID_IMoaPathName
Pointer type: PIMoaPathName
Inheritance: IMoaUnknown
Header file: moapath.h

Description

The IMoaPathName interface provides various methods for the manipulation of pathnames.

Methods

InitFromString()
SetTempPath()
Resolve()
RemoveFinal()
AddFinal()
Concat()
SetVolumeName()
SetExtension()
SetScheme()
SetHostName()
SetPort()
SetUserID()
SetPassword()
SetParameters()
SetAnchor()
GetPath()
GetDisplayPath() not implemented in Director
GetDisplayFileName()
GetVolumeName()
GetExtension()
GetScheme()
GetHostName()
GetPort()
GetUserID()
GetPassword()
GetParameters()
GetAnchor()
IsEmpty()
IsAbsolute()
IsRelative()
IsCanonical()
AreEqual()
GetParentDirectory()
GetWorkingDirectory()
GetRelativePath() not implemented in Director
Clone()
InitFromFSSpec()

AddFinal()

Syntax

AddFinal(PIMoaPathName This, PMoaChar pFinalComponent)

Parameters

This

Pointer to the IMoaPathName interface

pFinalComponent

new path component

Returns

kMoaErr_NoErr

Success

Description

Adds the string passed in to the current pathname. The string can be either a directory or filename.

AreEqual()

Syntax

AreEqual(PIMoaPathName This, PIMoaPathName pIMoaPathName)

Parameters

This

Pointer to the IMoaPathName interface

pIMoaPathName

pointer to an IMoaPathName instance

Returns

MoaBoolParam

Description

Returns TRUE if the provided IMoaPathName instance is the same as the current instance.

Clone()

Syntax

Clone(PIMoaPathName This, PIMoaPathName FAR * ppIMoaPathName)

Parameters

This

Pointer to the IMoaPathName interface

ppIMoaPathName

on return contains a pointer to an IMoaPathName

Returns

kMoaErr_NoErr

Success or standard MOA QueryInterface errors

Description

Creates an IMoaPathName instance identical to the current instance. The client is responsible for releasing this interface when done.

Concat()

Syntax

Concat(PIMoaPathName This, PIMoaPathName pIMoaPathName)

Parameters

This

Pointer to the IMoaPathName interface

pIMoaPathName

pointer to an IMoaPathName instance

Returns

kMoaErr_NoErr	Success
kMoaErr_BadParam	You passed me a bogus argument

Description

Concatenates the pathname of the current instance with the instance passed in via pIMoaPathName.

GetAnchor()

Syntax

GetAnchor(PIMoaPathName This, PMoaChar pNameBuf, MoaLong nameBufSize)

Parameters

This

Pointer to the IMoaPathName interface

pNameBuf

buffer for returned anchor

nameBufSize

size of buffer

Returns

kMoaErr_NoErr	Success
kMoaPathErr_UnsupportedForCurrentDialect	Not supported for current dialect

Description

Returns the anchor component of the current pathname. This method has no effect on non-URL_STYLE paths.

GetDisplayFileName()

Syntax

GetDisplayFileName(PIMoaPathName This,

PMoaChar pNameBuf,
MoaLong nameBufSize,
MoaBoolParam bForMenu)

Parameters

This

Pointer to the IMoaPathName interface

pNameBuf

buffer for the returned filename

nameBufSize

length of buffer

bForMenu

for menu flag

Returns

kMoaErr_NoErr	Success
kMoaErr_BadParam	You passed me a bogus argument

Description

Returns the display filename for the current pathName. The display filename is formatted to properly fit within the buffer supplied. If the entire fileName cannot be fit in to the buffer, it is re-formatted. Example: foo.txt becomes foo The for menu boolean tells the method whether or not the path is going to be used within a menu, in which case, the formatting is altered.

GetDisplayPath()

Syntax

GetDisplayPath(PIMoaPathName This,

PMoaChar pNameBuf,
MoaLong nameBufSize,
MoaBoolParam bForMenu)

Parameters

This

Pointer to the IMoaPathName interface

pNameBuf

pointer to buffer for returned path

nameBufSize

size of buffer

bForMenu

for menu flag

Returns

kMoaErr_NotImplemented

No implementation for this in Director

Description

Returns the display path for the current pathName. The display path is formatted to properly fit within the buffer supplied. If the entire path cannot be fit in to the buffer, it is re-formatted. Example: The for menu boolean tells the method whether or not the path is going to be used within a menu, in which case, the formatting is altered.

GetExtension()

Syntax

GetExtension(PIMoaPathName This, PMoaChar pNameBuf, MoaLong nameBufSize)

Parameters

This

Pointer to the IMoaPathName interface

pNameBuf

buffer for the returned extension

nameBufSize

size of the buffer

Returns

kMoaErr_NoErr	Success
kMoaErr_BadParam	You passed me a bogus argument

Description

Returns the extension of the current file.

GetHostName()

Syntax

GetHostName(PIMoaPathName This, PMoaChar pNameBuf, MoaLong nameBufSize)

Parameters

This

Pointer to the IMoaPathName interface

pNameBuf

buffer for the returned hostname

nameBufSize

size of buffer

Returns

kMoaErr_NoErr	Success
kMoaPathErr_UnsupportedForCurrentDialect	Not supported for current dialect

Description

Returns the hostname component of the current pathname. This method has no effect on non-URL_STYLE paths.

GetParameters()

Syntax

GetParameters(PIMoaPathName This, PMoaChar pNameBuf, MoaLong nameBufSize)

Parameters

This

Pointer to the IMoaPathName interface

pNameBuf

buffer for returned parameters

nameBufSize

size of buffer

Returns

kMoaErr_NoErr	Success
kMoaPathErr_UnsupportedForCurrentDialect	Not supported for current dialect

Description

Returns user defined components of the current pathname. This method has no effect on non-URL_STYLE paths.

GetParentDirectory()

Syntax

GetParentDirectory(PIMoaPathName This, PIMoaPathName FAR * ppIMoaPathName)

Parameters

This

Pointer to the IMoaPathName interface

ppIMoaPathName

on return contains a pointer to an IMoaPathName

Returns

kMoaErr_NoErr

Success or standard MOA QueryInterface errors

Description

Returns a PIMoaPathName that references the current instances parent directory. The client is responsible for releasing this interface when done.

GetPassword()

Syntax

GetPassword(PIMoaPathName This, PMoaChar pNameBuf, MoaLong nameBufSize)

Parameters

This

Pointer to the IMoaPathName interface

pNameBuf

buffer for returned password

nameBufSize

size of buffer

Returns

kMoaErr_NoErr	Success
kMoaPathErr_UnsupportedForCurrentDialect	Not supported for current dialect

Description

Returns the password component of the current pathname. This method has no effect on non-URL_STYLE paths.

GetPath()

Syntax

GetPath(PIMoaPathName This,

PMoaChar pNameBuf,
MoaLong nameBufSize)

Parameters

This

Pointer to the IMoaPathName interface

pNameBuf

pointer to buffer for returned path

nameBufSize

size of buffer

Returns

kMoaErr_NoErr

Success

Description

Returns a pointer to a string containing the current pathname.

GetPort()

Syntax

GetPort(PIMoaPathName This, MoaLong FAR * pPortNumber)

Parameters

This

Pointer to the IMoaPathName interface

pPortNumber

on return contains port number

Returns

kMoaErr_NoErr	Success
kMoaPathErr_UnsupportedForCurrentDialect	Not supported for current dialect

Description

Returns the port component of the current pathname. This method has no effect on non-URL_STYLE paths.

GetRelativePath()

Syntax

GetRelativePath(PIMoaPathName This,

PIMoaPathName pToPath,
PIMoaPathName FAR * ppRelPath)

Parameters

This

Pointer to the IMoaPathName interface

pToPath

pointer to the desination path

ppRelPath

on return contains a pointer to an IMoaPathName

Returns

kMoaErr_NotImplemented

No implementation for this in Director

Description

Returns a PIMoaPathName that contains the relative path from the current instance to the destination path in the pToPath instance. The client is responsible for releasing this interface when done.

GetScheme()

Syntax

GetScheme(PIMoaPathName This, PMoaChar pNameBuf, MoaLong nameBufSize)

Parameters

This

Pointer to the IMoaPathName interface

pNameBuf

buffer for the returned scheme

nameBufSize

size of buffer

Returns

kMoaErr_NoErr	Success
kMoaPathErr_UnsupportedForCurrentDialect	Not supported by current dialect

Description

Returns the scheme component of the current pathname. This method has no effect on non-URL_STYLE paths.

GetUserID()

Syntax

GetUserID(PIMoaPathName This, PMoaChar pNameBuf, MoaLong nameBufSize)

Parameters

This

Pointer to the IMoaPathName interface

pNameBuf

buffer for returned UserID

nameBufSize

size of buffer

Returns

kMoaErr_NoErr	Success
kMoaPathErr_UnsupportedForCurrentDialect	Not supported for current dialect

Description

Returns the userID component of the current pathname. This method has no effect on non-URL_STYLE paths.

GetVolumeName()

Syntax

GetVolumeName(PIMoaPathName This, PMoaChar pNameBuf, MoaLong nameBufSize)

Parameters

This

Pointer to the IMoaPathName interface

pNameBuf

buffer for the returned volume name

nameBufSize

size of the buffer

Returns

kMoaErr_NoErr

Success

Description

Returns the volume name of the current pathname. For MAC_STYLE paths, this is the name of the volume. For MSDOS_STYLE paths, it is the drive letter of volume. This method has no effect on UNIX_STYLE or URL_STYLE paths.

GetWorkingDirectory()

Syntax

GetWorkingDirectory(PIMoaPathName This, PIMoaPathName FAR * ppIMoaPathName)

Parameters

This

Pointer to the IMoaPathName interface

ppIMoaPathName

on return contains a pointer to an IMoaPathName

Returns

kMoaErr_NoErr

Success or standard MOA QueryInterface errors

Description

Returns a PIMoaPathName that references the current working directory. The client is responsible for releasing this interface when done.

InitFromFSSpec()

Syntax

InitFromFSSpec(PIMoaPathName This, ConstPMoaVoid pFSSpec)

Parameters

This

Pointer to the IMoaPathName interface

pFSSpec

pointer to Macintosh FSSpec

Returns

kMoaErr_NoErr

Success

Description

Initializes the current instance from a Macintosh FSSpec.

InitFromString()

Syntax

InitFromString(PIMoaPathName This,

ConstPMoaChar pFileName,
MoaPathDialect pathDialect,
MoaBoolParam bResolve,
MoaBoolParam bUseDialog)

Parameters

This

Pointer to the IMoaPathName interface

pFileName

pointer to file name string

pathDialect

path dialect

bResolve

resolve flag

bUseDialog

use dialog flag

Returns

kMoaErr_NoErr

Success

Description

InitFromString() intializes the current IMoaPathName object from a path string. The pathDialect flag tells the object what the style of the supplied path is. Valid dialects are: kMoaPathDialect_LOCAL - Style is based on current platform, but checks for CANON and URL also. kMoaPathDialect_CANON_STYLE - Canonical style relative pathname kMoaPathDialect_MAC_STYLE - Macintosh style pathname. kMoaPathDialect_DOS_STYLE - MSDOS style pathname. kMoaPathDialect_UNIX_STYLE - Unix style pathname. kMoaPathDialect_URL_STYLE - URL(RFC 1738) style pathname. If LOCAL dialect is specified, InitFromString() will check if the supplied path is a URL or canonical pathname, if so the dialect will changed as such. The resolve flag determines whether or not a relative path or leaf should be resolved into a fully qualified pathname. The use dialog flag determines whether or not the host app should use a dialog to resolve a path/file that cannot be located. bUseDialog is not likely to be supported outside Director's implementation.

IsAbsolute()

Syntax

IsAbsolute(PIMoaPathName This)

Parameters

This

Pointer to the IMoaPathName interface

Returns

MoaBoolParam

Description

Returns TRUE if the current path is absolute.

IsCanonical()

Syntax

IsCanonical(PIMoaPathName This)

Parameters

This

Pointer to the IMoaPathName interface

Returns

MoaBoolParam

Description

Returns TRUE if the current path is canonical.

IsEmpty()

Syntax

IsEmpty(PIMoaPathName This)

Parameters

This

Pointer to the IMoaPathName interface

Returns

MoaBoolParam

Description

Returns TRUE if the current path is empty.

IsRelative()

Syntax

IsRelative(PIMoaPathName This)

Parameters

This

Pointer to the IMoaPathName interface

Returns

MoaBoolParam

Description

Returns TRUE if the current path is relative.

IsValid()

Description

Do not call this method.

RemoveFinal()

Syntax

RemoveFinal(PIMoaPathName This)

Parameters

This

Pointer to the IMoaPathName interface

Returns

kMoaErr_NoErr	Success
kMoaErr_BadParam	You passed me a bogus argument

Description

Removes the final component of the current pathname.

Resolve()

Syntax

Resolve(PIMoaPathName This, MoaBoolParam bUseDialog)

Parameters

This

Pointer to the IMoaPathName interface

bUseDialog

use dialog flag

Returns

kMoaErr_NoErr	Success
kMoaErr_NotImplemented	Environment does not support UseDialog
kMoaErr_BadParam	You passed me a bogus argument

Description

Resolves the current instance into a fully qualifed path. If the bUseDialog flag is set, the host app provides a dialog when the target cannot be found. bUseDialog is not likely to be supported outside Director's implementation. The bUseDialog feature is no longer supported in Director. If you pass in TRUE for this value, you will get an error return from this call.

SetAnchor()

Syntax

SetAnchor(PIMoaPathName This, ConstPMoaChar pNameBuf)

Parameters

This

Pointer to the IMoaPathName interface

pNameBuf

buffer containing anchor

Returns

kMoaErr_NoErr	Success
kMoaErr_BadParam	You passed me a bogus argument
kMoaPathErr_UnsupportedForCurrentDialect -	Not supported by current dialect

Description

Sets the anchor component of the current URL_STYLE pathname. This method has no effect on non URL_STYLE pathnames.

SetExtension()

Syntax

SetExtension(PIMoaPathName This, ConstPMoaChar pNameBuf)

Parameters

This

Pointer to the IMoaPathName interface

pNameBuf

buffer containing the extension

Returns

kMoaErr_NoErr	Success
kMoaErr_BadParam	You passed me a bogus argument

Description

Sets the extension of the current filename.

SetHostName()

Syntax

SetHostName(PIMoaPathName This, ConstPMoaChar pNameBuf)

Parameters

This

Pointer to the IMoaPathName interface

pNameBuf

buffer containing the hostname

Returns

kMoaErr_NoErr	Success
kMoaErr_BadParam	You passed me a bogus argument
kMoaPathErr_UnsupportedForCurrentDialect -	Not supported by current dialect

Description

Sets the hostname component of the current URL_STYLE pathname. This method has no effect on non URL_STYLE pathnames.

SetParameters()

Syntax

SetParameters(PIMoaPathName This, ConstPMoaChar pNameBuf)

Parameters

This

Pointer to the IMoaPathName interface

pNameBuf

buffer containing user defined parameters

Returns

kMoaErr_NoErr	Success
kMoaErr_BadParam	You passed me a bogus argument
kMoaPathErr_UnsupportedForCurrentDialect -	Not supported by current dialect

Description

Sets any miscelleaneous components of the current URL_STYLE pathname. This method has no effect on non URL_STYLE pathnames.

SetPassword()

Syntax

SetPassword(PIMoaPathName This, ConstPMoaChar pNameBuf)

Parameters

This

Pointer to the IMoaPathName interface

pNameBuf

buffer containing the password

Returns

kMoaErr_NoErr	Success
kMoaErr_BadParam	You passed me a bogus argument
kMoaPathErr_UnsupportedForCurrentDialect -	Not supported by current dialect

Description

Sets the password component of the current URL_STYLE pathname. This method has no effect on non URL_STYLE pathnames.

SetPort()

Syntax

SetPort(PIMoaPathName This, MoaLong portNumber)

Parameters

This

Pointer to the IMoaPathName interface

portNumber

MoaLong specifying the port number

Returns

kMoaErr_NoErr	Success
kMoaErr_BadParam	You passed me a bogus argument
kMoaPathErr_UnsupportedForCurrentDialect -	Not supported by current dialect

Description

Sets the port component of the current URL_STYLE pathname. This method has no effect on non URL_STYLE pathnames.

SetScheme()

Syntax

SetScheme(PIMoaPathName This, ConstPMoaChar pNameBuf)

Parameters

This

Pointer to the IMoaPathName interface

pNameBuf

buffer containing the URL scheme

Returns

kMoaErr_NoErr	Success
kMoaErr_BadParam	You passed me a bogus argument
kMoaPathErr_UnsupportedForCurrentDialect -	Not supported by current dialect

Description

Sets the scheme component of the current URL_STYLE pathname. This method has no effect on non URL_STYLE pathnames.

SetTempPath()

Syntax

SetTempPath(PIMoaPathName This, PIMoaPathName pIDir)

Parameters

This

Pointer to the IMoaPathName interface

pIDir

you must pass in NULL for this argument

Returns

kMoaErr_NoErr	Success
kMoaErr_FileNotFound	File not found

Description

Determines a unique name for a temporary file and replaces the current value of the pathname instance with that name. This routine does not actually create the file.

SetUserID()

Syntax

SetUserID(PIMoaPathName This, ConstPMoaChar pNameBuf)

Parameters

This

Pointer to the IMoaPathName interface

pNameBuf

buffer containing the userID

Returns

kMoaErr_NoErr	Success
kMoaErr_BadParam	You passed me a bogus argument
kMoaPathErr_UnsupportedForCurrentDialect -	Not supported by current dialect

Description

Sets the user ID component of the current URL_STYLE pathname. This method has no effect on non URL_STYLE pathnames.

SetVolumeName()

Syntax

SetVolumeName(PIMoaPathName This, ConstPMoaChar pNameBuf)

Parameters

This

Pointer to the IMoaPathName interface

pNameBuf

string containing the new volume name

Returns

kMoaErr_NoErr	Success
kMoaErr_BadParam	You passed me a bogus argument
kMoaPathErr_UnsupportedForCurrentDialect -	Not supported by current dialect

Description

Used to set the volume name of the current pathname. For the MAC_STYLE dialect, this is the name of the target volume. For the MSDOS_STYLE dialect it is the drive letter of the target volume. This method has no effect with UNIX_STYLE or URL_STYLE pathnames.