IFileClip Interface

The IFileClip interface provides a simple way for an application to create one or more cuts from a single media file, or to create blank cuts. Blank (empty or null) cuts are useful to either stop playback for a specified time, or to make a placeholder for a cut that the cutlist can't play.

For more information, see About Cutlists and Using Cutlists.

Do not implement this interface. Microsoft® DirectShow® implements it for you.

Use this interface in your application when you want to provide cutlist functionality to the user.

When compiling a cutlist application, you must explicitly include the cutlist header file as follows:

#include <cutlist.h>

Methods in Vtable Order

IUnknown methods Description
QueryInterface Retrieves pointers to supported interfaces.
AddRef Increments the reference count.
Release Decrements the reference count.

IFileClip methods Description

SetFileAndStream Initializes the clip object with the specified media file and stream number or makes an empty clip for producing null elements.
CreateCut Creates a cutlist element.
GetMediaType Retrieves the clip's media type structure.

IUnknown methods	Description
QueryInterface	Retrieves pointers to supported interfaces.
AddRef	Increments the reference count.
Release	Decrements the reference count.
IFileClip methods	Description
SetFileAndStream	Initializes the clip object with the specified media file and stream number or makes an empty clip for producing null elements.
CreateCut	Creates a cutlist element.
GetMediaType	Retrieves the clip's media type structure.

IFileClip::CreateCut

IFileClip Interface

Creates a cutlist element.

Syntax

HRESULT CreateCut(
    IAMCutListElement **ppElement,
    REFERENCE_TIME mtTrimIn,
    REFERENCE_TIME mtTrimOut,
    REFERENCE_TIME mtOrigin,
    REFERENCE_TIME mtLength,
    REFERENCE_TIME mtOffset
);

Parameters

ppElement
[out] Address of a pointer to the IAMCutListElement interface of the created cutlist element.
mtTrimIn
[in] Trimin (beginning) position for the cut.
mtTrimOut
[in] Trimout (ending) position for the cut.
mtOrigin
[in] Clip origin. Must be zero.
mtLength
[in] Length of clip. Must be mtTrimOut minus mtTrimIn.
mtOffset
[in] Offset of clip. Must be zero.

Return Value

Returns an HRESULT value that depends on the implementation of the interface. HRESULT can include one of the following standard constants, or other values not listed.

E_FAIL Failure.
E_INVALIDARG Argument is invalid.
E_NOTIMPL Method is not supported.
E_OUTOFMEMORY Could not allocate required memory.
S_OK Success.

Remarks

All of the times specified in this method are relative to the media clip rather than to the cutlist.
To make an empty cut, first create an empty (null) clip by calling the IFileClip::SetFileAndStream method as illustrated by the following code fragment. Then, create a cut of the desired duration (n) to indicate you want to do nothing for n units of time.
IAMCutListElement *pElement;

SetFileAndStream(NULL, -1);
CreateCut(&pElement, 0, n, 0, n, 0);
For more information about using cutlists and the cutlist interfaces from an application, see Using Cutlists.

IFileClip::GetMediaType

IFileClip Interface

Retrieves the clip's media type structure.

Syntax

HRESULT GetMediaType(
    AM_MEDIA_TYPE *pmt
);

Parameters

pmt
[out] Pointer to the AM_MEDIA_TYPE structure describing the video clip.

Return Value

Returns an HRESULT value that depends on the implementation of the interface. HRESULT can include one of the following standard constants, or other values not listed.

E_FAIL Failure.
E_INVALIDARG Argument is invalid.
E_NOTIMPL Method is not supported.
E_OUTOFMEMORY Could not allocate required memory.
S_OK Success.

IFileClip::SetFileAndStream

IFileClip Interface

Initializes the clip object with the specified media file and stream number or makes an empty clip for producing null elements.

Syntax

HRESULT SetFileAndStream(
    LPWSTR wstrFileName,
    DWORD streamNum
);

Parameters

wstrFileName
[in] Name of the file from which to initialize the clip. Must be an .avi or a .wav file. Specify NULL to make an empty (null) clip.
streamNum
[in] Stream number (.avi files only) within the specified file from which to initialize the clip. Must be zero. AVI files with more than one stream of any type are not supported; clips must be from the first stream (stream 0). Specify –1 for empty elements.

Return Value

Returns an HRESULT value that depends on the implementation of the interface. HRESULT can include one of the following standard constants, or other values not listed.

E_FAIL Failure.
E_INVALIDARG Argument is invalid.
E_NOTIMPL Method is not supported.
E_OUTOFMEMORY Could not allocate required memory.
E_UNSUPPORTED_FORMAT (0x80041018) The .wav file format is unsupported (for example, it's compressed).
S_OK Success.

Remarks

This method opens the file to verify the format and media type (which you can find by using the IFileClip::GetMediaType method).
Use the following call to make an empty clip.
SetFileAndStream(NULL, -1);

E_FAIL	Failure.
E_INVALIDARG	Argument is invalid.
E_NOTIMPL	Method is not supported.
E_OUTOFMEMORY	Could not allocate required memory.
S_OK	Success.