ICutListElement Interface

ICutListElement describes a base object, which represents an element in a cutlist. For a simpler interface that provides basic cutlist functionality, applications can use IFileClip to create an object that supports this interface.

See IStandardCutList for information about other cutlist interfaces.

When to Implement

Normally you don't need to implement this interface because DirectShow provides the CLSID_VideoFileClip and CLSID_AudioFileClip objects which can create an object that implements it for you. However, you can implement this interface in your application when you need to change the default behavior of this interface.

When to Use

Use this interface in your filter to get specific elements of a cutlist.

Methods in Vtable Order

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

ICutListElement methods Description
GetElementStartPosition Retrieves the media time of the start of the element in the time scale of the cutlist.
GetElementDuration Retrieves the duration of the cutlist element.
IsFirstElement Determines if the element is the first in the cutlist.
IsLastElement Determines if the element is the last in the cutlist.
IsNull Determines if the element is null.
ElementStatus Determines the status of the element.

ICutListElement::GetElementStartPosition

Retrieves the media time of the start of the element in the time scale of the cutlist.

HRESULT GetElementStartPosition(
REFERENCE_TIME *pmtStart
);

Parameters

pmtStart: [out] Pointer to the element time for the start of the element.

Return Values

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.

Value Meaning
E_FAIL Failure.
E_INVALIDARG Argument is invalid.
E_NOTIMPL Method is not supported.
E_POINTER Null pointer argument.
S_OK Success.

Remarks

Times retrieved by this method are relative to the time within the cutlist. For example, the first element in the cutlist starts at time zero (0).

ICutListElement::GetElementDuration

Retrieves the duration of the cutlist element.

HRESULT GetElementDuration(
REFERENCE_TIME *pmtDuration
);

Parameters

pmtDuration: [out] Duration of the element.

Return Values

Remarks

When you call IFileClip::CreateCut to create the element, the difference between two of its parameters (mtTrimOut minus mtTrimIn) determine the duration.

ICutListElement::IsFirstElement

Determines if the element is the first in the cutlist.

HRESULT IsFirstElement(void);

Return Values

ICutListElement::IsLastElement

Determines if the element is the last in the cutlist.

HRESULT IsLastElement(void);

Return Values

ICutListElement::IsNull

Determines if the element is null.

HRESULT IsNull(void);

Return Values

Remarks

NULL elements are not currently supported, so this method should always return S_FALSE.

ICutListElement::ElementStatus

Determines the status of the element.

HRESULT ElementStatus(
  DWORD *pdwStatus,
  DWORD dwTimeoutMs
  );

Parameters

pdwStatus: [in/out] Status. On input, if this parameter contains CL_WAIT_FOR_STATE and an additional state value from the CL_ELEM_STATUS enumerated data type, this method waits dwTimeoutMs milliseconds until the element is in that state before returning. On output, this is a logical combination of flags from the CL_ELEM_STATUS enumerated data type.
dwTimeoutMs: [in] Timeout value in milliseconds.

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

ICutListElement methods	Description
GetElementStartPosition	Retrieves the media time of the start of the element in the time scale of the cutlist.
GetElementDuration	Retrieves the duration of the cutlist element.
IsFirstElement	Determines if the element is the first in the cutlist.
IsLastElement	Determines if the element is the last in the cutlist.
IsNull	Determines if the element is null.
ElementStatus	Determines the status of the element.

Value	Meaning
E_FAIL	Failure.
E_INVALIDARG	Argument is invalid.
E_NOTIMPL	Method is not supported.
E_POINTER	Null pointer argument.
S_OK	Success.