QuickTime and File System Pathnames

Dispatch 4

Operating systems typically use pathnames to indicate the location of files, directories and volumes. The MacOS, on the other hand, doesn't use pathnames to describe the location of files and directories. Instead it uses a structure called a FSSpec to describe a file or directory's current location. QuickTime, owing in part to its origins on the Macintosh, also uses FSSpecs to describe locations of files.

Because those parts of the QuickTime API that expect files take FSSpecs as parameters, native pathnames must be converted to FSSpecs for use with those APIs. Likewise, developers may find it necessary to convert from a FSSpec to a pathname for use with an OS service. To that end, on platforms other than the Macintosh, QuickTime provides two API functions to convert from native pathname strings to FSSpecs and back.

EXTERN_API(OSErr) NativePathNameToFSSpec( const char * pathname,
   FSSpecPtr theFile, long flags );

Given a C string pathname from the operating system, this function updates FSSpec theFile to describe the same file. Currently, there are no flags defined so pass 0 for now. In the future, this function may accept additional options and flags will then accept new values. If the file doesn't currently exist, the error fnfErr is returned but the FSSpec is still a valid FSSpec for creating the file.

EXTERN_API(OSErr) FSSpecToNativePathName( FSSpecPtr theFile,
  char * pathname,
  UInt16 pathnameMaxBufferSize,
  long flags )
   

Sometimes developers need to convert a FSSpec returned by QuickTime APIs to a native pathname to be passed onto the current operating system. FSSpecToNativePathName accepts a FSSpec and fills in the buffer pathname whose maximum size is pathnameMaxBufferSize with the equivalent pathname string. This size must also include the size necessary to hold the string terminator. So, if the maximum length in characters was 115, the buffer size would need to be 116 (= 115 + 1).

Three flags are defined for FSSpecToNativePathName:

kFullNativePath--This indicates that the full pathname should be returned.

kFileNameOnly--Only the part of the pathname corresponding to the file should be returned. This might be useful to return a string for a window's title.

kDirectoryPathOnly--The full pathname up to and including the enclosing directory but not the filename should be returned. This can be useful to get a path for the enclosing directory that might be used to find related files in the same directory.

As an example, consider the following Windows full path:

D:\Media\My Movies\Really Cool Movies\Tasty Fish.mov

If we have an FSSpec for this path, we can extract either the whole path or portions of the path using one of the above flags. For the above path and the each flag, the resulting strings are:

kFullNativePath gives

  D:\Media\My Movies\Really Cool Movies\Tasty Fish.mov

kFileNameOnly gives

  Tasty Fish.mov

kDirectoryPathOnly gives

  D:\Media\My Movies\Really Cool Movies
   

NOTE: Before these functions were introduced to the QuickTime API, the recommended way to convert from native pathnames to FSSpecs was to convert the pathname into a Pascal string using c2pstr and then pass that string to FSpMakeFSSpec. While it is still possible to use FSpMakeFSSpec to generate FSSpecs on these platforms, developers are discouraged from doing so. The new calls have a number of advantages:

• These calls don't convert the string in place and so don't need a temporary buffer.
• Pascal strings can only be 255 characters so very long paths can get truncated by c2pstr before being passed onto FSpMakeFSSpec.
• These routines have flags to perform other useful operations

See Also

QuickTime for Windows Programming Guide - Utility functions

QuickTime 3 Reference

Change History

4/16/98 - clf - First published