Microsoft DirectX 8.0

IMediaLocator Interface

Provides methods for validating file names in Microsoft® DirectShow® Editing Services (DES). Use this interface to ensure that a given file name and path correspond to an existing file. This interface 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 media locator implements this interface. 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 media locator. For more information, see Using the Media Locator.

Requirements

Requires Qedit.h.

Methods in Vtable Order

IUnknown methodsDescription
QueryInterfaceRetrieves pointers to supported interfaces.
AddRefIncrements the reference count.
ReleaseDecrements the reference count.
IMediaLocator methodsDescription
FindMediaFileSearches for a file and, if successful, retrieves the path to the file.
AddFoundLocationAdds a directory to the directory cache.

IMediaLocator::AddFoundLocation

IMediaLocator Interface

Adds a directory to the directory cache.

Syntax

HRESULT AddFoundLocation(
    BSTR DirectoryName
);

Parameters

DirectoryName
Directory path to add to the cache.

Return Value

Returns S_OK if successful. Otherwise, returns an HRESULT value indicating the cause of the error.

Remarks

The media locator 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.

IMediaLocator::FindMediaFile

IMediaLocator Interface

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

Syntax

HRESULT FindMediaFile(
    BSTR Input,
    BSTR FilterString,
    BSTR *pOutput,
    long Flags
);

Parameters

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
BSTR 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. The value can be NULL if the Flags parameter does not include the SFN_VALIDATEF_POPUP flag.
pOutput
Pointer to a 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:

Return Value

Returns an HRESULT value. Possible values include the following.

S_FALSEFile was found in another location.
S_OKFile was found in the specified location.
E_FAILFailure.
E_INVALIDARGArgument is invalid.
E_POINTERNULL pointer argument.

Remarks

The filter string for the Open dialog, which is specified by the FilterString parameter, contains internal Null characters. For example, Video\0*.avi\0\0 is a valid filter string. You cannot use the SysAllocStr function to allocate the BSTR, because that function expects a Null-terminated string and will truncate the string at the first Null character. Therefore, use a function such as SysAllocStringLen, which includes an explicit parameter for the length:

BSTR filter = SysAllocStringLen(L"Video\0*.avi\0\0", 13);

If the user cancels the Open dialog, the method returns E_FAIL.

The method allocates memory for the BSTR in pOutput. The application must call SysFreeString to free the memory.