IMediaLocator::FindMediaFile

The FindMediaFile method 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:

• SFN_VALIDATEF_NOFIND
• SFN_VALIDATEF_POPUP
• SFN_VALIDATEF_TELLME
• SFN_VALIDATEF_USELOCAL

Return Value

Returns an HRESULT value. Possible values include the following.

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.

See Also

• IMediaLocator Interface
• Error and Success Codes