IStandardCutList Interface

The IStandardCutList interface provides a simple way for an application to feed a cutlist into a cutlist provider (filter).

The IStandardCutList::AddElement method provides the primary functionality of this interface, by taking a pointer to a cutlist element and adding it to the list. The first clip added to a cutlist determines the media type. All other clips must be of the same media type. Removing clips from the cutlist is not supported.

The filter graph must be stopped when you call many of the methods on this interface.

See About Cutlists and Using Cutlists for more information.

When to Implement

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

When to Use

Use this interface in your application when you need to create a whole cutlist out of individual cuts (elements).

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.

IStandardCutList methods	Description
AddElement	Accepts a cutlist element from the application and adds it to the cutlist.
RemoveElement	Removes an element from a cutlist. (Not currently implemented.)
GetFirstElement	Retrieves the first element you added to cutlist.
GetLastElement	Retrieves the last element you added to cutlist.
GetNextElement	Retrieves the next element in the cutlist.
GetPreviousElement	Retrieves the previous element in the cutlist.
GetMediaType	Retrieves the clip's media type structure.
SetMediaType	Sets the media type for all clips in the cutlist.

---

IStandardCutList::AddElement

IStandardCutList Interface

Accepts a cutlist element from the application and adds it to the cutlist.

HRESULT AddElement(
  IAMCutListElement *pElement,
  REFERENCE_TIME mtStart,
  REFERENCE_TIME mtDuration
  );

Parameters

pElement

[in] Pointer to the cutlist element to be added to the cutlist.

mtStart

[in] Relative position of the cut in the cutlist. Must be CL_DEFAULT_TIME (indicating that the relative position is the end of the current cutlist).

mtDuration

[in] Length of the cut. Must be CL_DEFAULT_TIME (indicating the duration is defined by 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_OUTOFMEMORY	Could not allocate the element descriptor.
S_OK	Success.

Remarks

This method adds a clip to the end of the clip list. The cutlist will play in the order you add the clips.

You can't call AddElement on this cutlist after you have given the cutlist to the graph builder by calling ICutListGraphBuilder::AddCutList. The AddElement call will be ignored. Make sure you have called AddElement as many times as you need to before calling ICutListGraphBuilder::AddCutList.

Removing clips from the cutlist is not supported.

The first clip added to a cutlist determines the media type. All other clips must be of the same media type.

See Also

IAMCutListElement

---

IStandardCutList::GetFirstElement

IStandardCutList Interface

Retrieves the first element you added to the cutlist.

HRESULT GetFirstElement(
  IAMCutListElement **ppElement
  );

Parameters

ppElement

[out] Address of a pointer to the first element in the cutlist.

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_OUTOFMEMORY	Could not allocate required memory.
S_OK	Success.

Remarks

You can only call this method when the graph is stopped. If you call this method while the graph is playing or paused, unpredictable behavior will result, including corrupting the cutlist that is playing.

This method increments the reference count on the cutlist element object. Be sure to decrement the cutlist element's reference count by calling its Release method as follows.

   *ppElement->Release();

See Also

GetLastElement, IAMCutListElement

---

IStandardCutList::GetLastElement

IStandardCutList Interface

Retrieves the last element you added to the cutlist.

HRESULT GetLastElement(
  IAMCutListElement **ppElement
  );

Parameters

ppElement

[out] Address of a pointer to the last element you added to the cutlist.

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_OUTOFMEMORY	Could not allocate required memory.
S_OK	Success.

Remarks

You can only call this method when the graph is stopped. If you call this method while the graph is playing or paused, unpredictable behavior will result, including corrupting the cutlist that is playing.

This method increments the reference count on the cutlist element object. Be sure to decrement the cutlist element's reference count by calling its Release method as follows.

   *ppElement->Release();

See Also

GetFirstElement, IAMCutListElement

---

IStandardCutList::GetMediaType

IStandardCutList Interface

Retrieves the clip's media type structure.

HRESULT GetMediaType(
  AM_MEDIA_TYPE *pmt
  );

Parameters

pmt

[in] Pointer to the AM_MEDIA_TYPE structure describing the clip.

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_OUTOFMEMORY	Could not allocate required memory.
S_OK	Success.

Remarks

This method retrieves the media type of all clips in the cutlist.

The first clip added to a cutlist determines the media type. All other clips must be of the same media type.

---

IStandardCutList::GetNextElement

IStandardCutList Interface

Retrieves the next element in the cutlist.

HRESULT GetNextElement(
  IAMCutListElement **ppElement
  );

Parameters

ppElement

[out] Address of a pointer to the next cutlist 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. You must call GetFirstElement or GetLastElement.
E_INVALIDARG	Argument is invalid.
E_NOTIMPL	Method is not supported.
E_OUTOFMEMORY	Could not allocate required memory.
S_FALSE	There is no next element.
S_OK	Success.

Remarks

You can only call this method when the graph is stopped. If you call this method while the graph is playing or paused, unpredictable behavior will result, including corrupting the cutlist that is playing.

You must call GetFirstElement or GetLastElement before this method will succeed.

This method increments the reference count on the cutlist element object. Be sure to decrement the cutlist element's reference count by calling its Release method as follows.

   *ppElement->Release();

See Also

GetPreviousElement, IAMCutListElement

---

IStandardCutList::GetPreviousElement

IStandardCutList Interface

Retrieves the previous element in the cutlist.

HRESULT GetPreviousElement(
  IAMCutListElement **ppElement
  );

Parameters

ppElement

[out] Address of a pointer to the previous cutlist 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. You must call GetFirstElement or GetLastElement.
E_INVALIDARG	Argument is invalid.
E_NOTIMPL	Method is not supported.
E_OUTOFMEMORY	Could not allocate required memory.
S_FALSE	There is no previous element.
S_OK	Success.

Remarks

You can only call this method when the graph is stopped. If you call this method while the graph is playing or paused, unpredictable behavior will result, including corrupting the cutlist that is playing.

You must call GetFirstElement or GetLastElement before this method will succeed.

This method increments the reference count on the cutlist element object. Be sure to decrement the cutlist element's reference count by calling its Release method as follows.

   *ppElement->Release();

See Also

GetNextElement, IAMCutListElement

---

IStandardCutList::RemoveElement

IStandardCutList Interface

Removes an element from a cutlist. (Not currently implemented.)

HRESULT RemoveElement(
  IAMCutListElement *pElement
  );

Parameters

pElement

[in] Pointer to the element to be removed.

---

IStandardCutList::SetMediaType

IStandardCutList Interface

Sets the media type for all clips in the cutlist.

HRESULT SetMediaType(
  AM_MEDIA_TYPE *pmt
  );

Parameters

pmt

[in] Pointer to the AM_MEDIA_TYPE structure describing the clip.

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_UNEXPECTED	Too late to set the media type.
S_OK	Success.

Remarks

This method tells a cutlist what media type all of the elements in the cutlist must have. If you do not call this method, the first non-NULL element given to the cutlist through IStandardCutList::AddElement will determine the media type of the cutlist. All subsequent calls to AddElement must be of the same media type.

If you call this method, you must do so before ever calling AddElement. This method limits the elements that can be added to elements of the specified media type.

© 1998 Microsoft Corporation. All rights reserved. Terms of Use.

Top of Page