Microsoft DirectX 8.0

MediaLocator Object

Provides methods for validating file names in Microsoft® DirectShow® Editing Services (DES). You can use the MediaLocator object to ensure that a given file name and path correspond to an existing file. This object also provides a way to search for the file at other locations, and to display an Open dialog box so that the user can locate the file.

The timeline and the render engine also support file name validation through the following methods:

Typically, a DES application will call these methods rather than directly create an instance of the MediaLocator object.

Methods

FindMediaFileSearches for a file and, if successful, retrieves the path to the file.
AddFoundLocationAdds a directory to the directory cache.

AddFoundLocation Method (MediaLocator Object)

MediaLocator Object

Adds a directory to the directory cache.

Syntax

object.AddFoundLocation( 
    DirectoryName As String
)

Parts

object
Object expression that evaluates to a MediaLocator object.
DirectoryName
Directory path to add to the cache.

Error Codes

If the method fails, an error is raised.

Remarks

The MediaLocator object keeps a cache of directory paths where it has successfully found files in past searches. When it successfully locates a file, it adds the directory to the cache.

FindMediaFile (MediaLocator Object)

MediaLocator Object

Searches for a file and, if successful, retrieves the path to the file.

Syntax

object.FindMediaFile(
    Input As String,
    FilterString As String,
    pOutput As String,
    Flags As Long
)

Parts

object
Object expression that evaluates to a MediaLocator object.
Input
File name, including path, where the file was last known to reside. For source objects in the timeline, use the current media name.
FilterString
String containing pairs of filter strings formatted as required by the lpstrFilter member of the Microsoft® Win32® OPENFILENAME structure. The media locator uses this filter if it displays an Open dialog box.
pOutput
Variable that receives the actual path to the file, if it differs from the value contained in Input and if the method successfully locates the file.
Flags
Bitwise combination of zero or more of the following flags:

Error Codes

If the method fails, an error is raised, and Err.Number can be set to one of the following values:

E_FAILFailure.
E_INVALIDARGArgument is invalid.
E_POINTERNULL pointer argument.

Remarks

If the SFN_VALIDATEF_POPUP flag is specified and the media locator cannot locate the file, this method displays an Open dialog box for the user to locate the file. If the user cancels the dialog box, the method raises an E_FAIL error. Your application should catch this error using an On Error statement:

If Err.Number = &H80004005 Then
    ' Did not locate the file.
End If

If the SFN_VALIDATEF_POPUP flag is not specified, and the media locator cannot locate the file, the method raises an E_FAIL error without displaying the dialog box.

The filter string for the Open dialog box, which is specified by the FilterString parameter, contains internal Null characters. For example, Video\0*.avi\0\0. You can use Chr(0) to specify the Null characters:

sNullStr = Chr(0)
sFilterStr = "Video" + sNullStr + "*.avi" + sNullStr + sNullStr