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. |
Accepts a cutlist element from the application and adds it to the cutlist.
HRESULT AddElement(
IAMCutListElement *pElement,
REFERENCE_TIME mtStart,
REFERENCE_TIME mtDuration
);
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. |
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.
Retrieves the first element you added to the cutlist.
HRESULT GetFirstElement(
IAMCutListElement **ppElement
);
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. |
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();
GetLastElement, IAMCutListElement
Retrieves the last element you added to the cutlist.
HRESULT GetLastElement(
IAMCutListElement **ppElement
);
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. |
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();
GetFirstElement, IAMCutListElement
Retrieves the clip's media type structure.
HRESULT GetMediaType(
AM_MEDIA_TYPE *pmt
);
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. |
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.
Retrieves the next element in the cutlist.
HRESULT GetNextElement(
IAMCutListElement **ppElement
);
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. |
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();
GetPreviousElement, IAMCutListElement
Retrieves the previous element in the cutlist.
HRESULT GetPreviousElement(
IAMCutListElement **ppElement
);
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. |
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();
GetNextElement, IAMCutListElement
Removes an element from a cutlist. (Not currently implemented.)
HRESULT RemoveElement(
IAMCutListElement *pElement
);
Sets the media type for all clips in the cutlist.
HRESULT SetMediaType(
AM_MEDIA_TYPE *pmt
);
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. |
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.
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.