From 99c144b6de1a967ee6f79a652db75a5b014972dc Mon Sep 17 00:00:00 2001 From: voroshil Date: Sun, 28 Jan 2007 16:53:33 +0000 Subject: Doxygen comments for used DirectShow methods. Info was got from DirectShow SDK. git-svn-id: svn://svn.mplayerhq.hu/mplayer/trunk@22046 b3059339-0415-0410-9bf9-f77b7e298cf2 --- loader/dshow/inputpin.c | 714 +++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 713 insertions(+), 1 deletion(-) (limited to 'loader/dshow/inputpin.c') diff --git a/loader/dshow/inputpin.c b/loader/dshow/inputpin.c index 88aa19b372..7ad56669ac 100644 --- a/loader/dshow/inputpin.c +++ b/loader/dshow/inputpin.c @@ -30,6 +30,21 @@ typedef struct GUID interfaces[2]; } CEnumPins; +/** + * \brief IEnumPins:Next (retrives a specified number of pins ) + * + * \param[in] This pointer to CEnumPins object + * \param[in] cMediaTypes number of pins to retrive + * \param[out] ppMediaTypes array of IPin interface pointers of size cMediaTypes + * \param[out] pcFetched address of variables that receives number of returned pins + * + * \return S_OK - success + * \return S_FALSE - did not return as meny pins as requested + * \return E_INVALIDARG Invalid argument + * \return E_POINTER Null pointer + * \return VFW_E_ENUM_OUT_OF_SYNC - filter's state has changed and is now inconsistent with enumerator + * + */ static long STDCALL CEnumPins_Next(IEnumPins* This, /* [in] */ unsigned long cMediaTypes, /* [size_is][out] */ IPin** ppMediaTypes, @@ -74,6 +89,17 @@ static long STDCALL CEnumPins_Next(IEnumPins* This, return 1; } +/** + * \brief IEnumPins::Skip (skips over a specified number of pins) + * + * \param[in] This pointer to CEnumPinss object + * \param[in] cMediaTypes number of pins to skip + * + * \return S_OK - success + * \return S_FALSE - skipped past the end of the sequence + * \return VFW_E_ENUM_OUT_OF_SYNC - filter's state has changed and is now inconsistent with enumerator + * + */ static long STDCALL CEnumPins_Skip(IEnumPins* This, /* [in] */ unsigned long cMediaTypes) { @@ -81,6 +107,14 @@ static long STDCALL CEnumPins_Skip(IEnumPins* This, return E_NOTIMPL; } +/** + * \brief IEnumPins::Reset (resets enumeration sequence to beginning) + * + * \param[in] This pointer to CEnumPins object + * + * \return S_OK - success + * + */ static long STDCALL CEnumPins_Reset(IEnumPins* This) { Debug printf("CEnumPins_Reset(%p) called\n", This); @@ -88,6 +122,19 @@ static long STDCALL CEnumPins_Reset(IEnumPins* This) return 0; } +/** + * \brief IEnumPins::Clone (makes a copy of enumerator, returned object + * starts at the same position as original) + * + * \param[in] This pointer to CEnumPins object + * \param[out] ppEnum address of variable that receives pointer to IEnumPins interface + * + * \return S_OK - success + * \return E_OUTOFMEMRY - Insufficient memory + * \return E_POINTER - Null pointer + * \return VFW_E_ENUM_OUT_OF_SYNC - filter's state has changed and is now inconsistent with enumerator + * + */ static long STDCALL CEnumPins_Clone(IEnumPins* This, /* [out] */ IEnumPins** ppEnum) { @@ -95,6 +142,12 @@ static long STDCALL CEnumPins_Clone(IEnumPins* This, return E_NOTIMPL; } +/** + * \brief CEnumPins destructor + * + * \param[in] This pointer to CEnumPins object + * + */ static void CEnumPins_Destroy(CEnumPins* This) { free(This->vt); @@ -103,6 +156,15 @@ static void CEnumPins_Destroy(CEnumPins* This) IMPLEMENT_IUNKNOWN(CEnumPins) +/** + * \brief CEnumPins constructor + * + * \param[in] p first pin for enumerator + * \param[in] pp second pin for enumerator + * + * \return pointer to CEnumPins object or NULL if error occured + * + */ static CEnumPins* CEnumPinsCreate(IPin* p, IPin* pp) { CEnumPins* This = (CEnumPins*) malloc(sizeof(CEnumPins)); @@ -139,8 +201,26 @@ static CEnumPins* CEnumPinsCreate(IPin* p, IPin* pp) /*********** * InputPin + * + * WARNING: + * This is implementation of OUTPUT pin in DirectShow's terms + * ***********/ +/** + * \brief IPin::Connect (connects pin to another pin) + * + * \param[in] This pointer to IPin interface + * \param[in] pReceivePin pointer to IPin interface of remote pin + * \param[in] pmt suggested media type for link. Can be NULL (any media type) + * + * \return S_OK - success. + * \return VFW_E_ALREADY_CONNECTED - pin already connected + * \return VFW_E_NOT_STOPPED - filter is active + * \return VFW_E_TYPE_NOT_ACCEPT - type is not acceptable + * \return Apropriate error code otherwise. + * + */ static long STDCALL CInputPin_Connect(IPin* This, /* [in] */ IPin* pReceivePin, /* [in] */ AM_MEDIA_TYPE* pmt) @@ -149,6 +229,25 @@ static long STDCALL CInputPin_Connect(IPin* This, return E_NOTIMPL; } +/** + * \brief IPin::ReceiveConnection (accepts a connection from another pin) + * + * \param[in] This pointer to IPin interface + * \param[in] pConnector connecting pin's IPin interface + * \param[in] pmt suggested media type for connection + * + * \return S_OK - success + * \return E_POINTER - Null pointer + * \return VFW_E_ALREADY_CONNECTED - pin already connected + * \return VFW_E_NOT_STOPPED - filter is active + * \return VFW_E_TYPE_NOT_ACCEPT - type is not acceptable + * + * \note + * When returning S_OK method should also do the following: + * - store media type and return the same type in IPin::ConnectionMediaType + * - store pConnector and return it in IPin::ConnectedTo + * + */ static long STDCALL CInputPin_ReceiveConnection(IPin* This, /* [in] */ IPin* pConnector, /* [in] */ const AM_MEDIA_TYPE *pmt) @@ -157,12 +256,37 @@ static long STDCALL CInputPin_ReceiveConnection(IPin* This, return E_NOTIMPL; } +/** + * \brief IPin::Disconnect (accepts a connection from another pin) + * + * \param[in] This pointer to IPin interface + * + * \return S_OK - success + * \return S_FALSE - pin was not connected + * \return VFW_E_NOT_STOPPED - filter is active + * + * \note + * To break connection you have to also call Disconnect on other pin + */ static long STDCALL CInputPin_Disconnect(IPin* This) { Debug unimplemented("CInputPin_Disconnect", This); return E_NOTIMPL; } +/** + * \brief IPin::ConnectedTo (retrieves pointer to the connected pin, if such exist) + * + * \param[in] This pointer to IPin interface + * \param[out] pPin pointer to remote pin's IPin interface + * + * \return S_OK - success + * \return E_POINTER - Null pointer + * \return VFW_E_NOT_CONNECTED - pin is not connected + * + * \note + * Caller must call Release on received IPin, when done + */ static long STDCALL CInputPin_ConnectedTo(IPin* This, /* [out] */ IPin** pPin) { @@ -170,6 +294,17 @@ static long STDCALL CInputPin_ConnectedTo(IPin* This, return E_NOTIMPL; } +/** + * \brief IPin::ConnectionMediaType (retrieves media type for connection, if such exist) + * + * \param[in] This pointer to IPin interface + * \param[out] pmt pointer to AM_MEDIA_TYPE, that receives connection media type + * + * \return S_OK - success + * \return E_POINTER - Null pointer + * \return VFW_E_NOT_CONNECTED - pin is not connected + * + */ static long STDCALL CInputPin_ConnectionMediaType(IPin* This, /* [out] */ AM_MEDIA_TYPE *pmt) { @@ -185,6 +320,19 @@ static long STDCALL CInputPin_ConnectionMediaType(IPin* This, return 0; } +/** + * \brief IPin::QueryPinInfo (retrieves information about the pin) + * + * \param[in] This pointer to IPin interface + * \param[out] pInfo pointer to PIN_INFO structure, that receives pin info + * + * \return S_OK - success + * \return E_POINTER - Null pointer + * + * \note + * If pInfo->pFilter is not NULL, then caller must call Release on pInfo->pFilter when done + * + */ static long STDCALL CInputPin_QueryPinInfo(IPin* This, /* [out] */ PIN_INFO *pInfo) { @@ -197,6 +345,16 @@ static long STDCALL CInputPin_QueryPinInfo(IPin* This, return 0; } +/** + * \brief IPin::QueryDirection (retrieves pin direction) + * + * \param[in] This pointer to IPin interface + * \param[out] pPinDir pointer to variable, that receives pin direction (PINDIR_INPUT,PINDIR_OUTPUT) + * + * \return S_OK - success + * \return E_POINTER - Null pointer + * + */ static long STDCALL CInputPin_QueryDirection(IPin* This, /* [out] */ PIN_DIRECTION *pPinDir) { @@ -205,6 +363,20 @@ static long STDCALL CInputPin_QueryDirection(IPin* This, return 0; } +/** + * \brief IPin::QueryId (retrieves pin identificator) + * + * \param[in] This pointer to IPin interface + * \param[out] Id adress of variable, that receives string with pin's Id. + * + * \return S_OK - success + * \return E_OUTOFMEMORY - Insufficient memory + * \return E_POINTER - Null pointer + * + * \note + * Pin's Id is not the same as pin's name + * + */ static long STDCALL CInputPin_QueryId(IPin* This, /* [out] */ unsigned short* *Id) { @@ -212,6 +384,16 @@ static long STDCALL CInputPin_QueryId(IPin* This, return E_NOTIMPL; } +/** + * \brief IPin::QueryAccept (determines can media type be accepted or not) + * + * \param[in] This pointer to IPin interface + * \param[in] pmt Media type to check + * + * \return S_OK - success + * \return S_FALSE - pin rejects media type + * + */ static long STDCALL CInputPin_QueryAccept(IPin* This, /* [in] */ const AM_MEDIA_TYPE* pmt) { @@ -219,6 +401,20 @@ static long STDCALL CInputPin_QueryAccept(IPin* This, return E_NOTIMPL; } +/** + * \brief IPin::EnumMediaTypes (enumerates the pin's preferred media types) + * + * \param[in] This pointer to IPin interface + * \param[out] ppEnum adress of variable that receives pointer to IEnumMEdiaTypes interface + * + * \return S_OK - success + * \return E_OUTOFMEMORY - Insufficient memory + * \return E_POINTER - Null pointer + * + * \note + * Caller must call Release on received interface when done + * + */ static long STDCALL CInputPin_EnumMediaTypes(IPin* This, /* [out] */ IEnumMediaTypes** ppEnum) { @@ -226,6 +422,18 @@ static long STDCALL CInputPin_EnumMediaTypes(IPin* This, return E_NOTIMPL; } +/** + * \brief IPin::QueryInternalConnections (retries pin's internal connections) + * + * \param[in] This pointer to IPin interface + * \param[out] apPin Array that receives pins, internally connected to this + * \param[in,out] nPint Size of an array + * + * \return S_OK - success + * \return S_FALSE - pin rejects media type + * \return E_NOTIMPL - not implemented + * + */ static long STDCALL CInputPin_QueryInternalConnections(IPin* This, /* [out] */ IPin** apPin, /* [out][in] */ unsigned long *nPin) @@ -234,6 +442,22 @@ static long STDCALL CInputPin_QueryInternalConnections(IPin* This, return E_NOTIMPL; } +/** + * \brief IPin::EndOfStream (notifies pin, that no data is expected, until new run command) + * + * \param[in] This pointer to IPin interface + * + * \return S_OK - success + * \return E_UNEXPECTED - The pin is output pin + * + * \note + * IMemoryInputPin::Receive,IMemoryInputPin::ReceiveMultiple, IMemoryInputPin::EndOfStream, + * IMemAllocator::GetBuffer runs in different (streaming) thread then other + * methods (application thread). + * IMemoryInputPin::NewSegment runs either in streaming or application thread. + * Developer must use critical sections for thread-safing work. + * + */ static long STDCALL CInputPin_EndOfStream(IPin * This) { Debug unimplemented("CInputPin_EndOfStream", This); @@ -241,6 +465,15 @@ static long STDCALL CInputPin_EndOfStream(IPin * This) } +/** + * \brief IPin::BeginFlush (begins a flush operation) + * + * \param[in] This pointer to IPin interface + * + * \return S_OK - success + * \return E_UNEXPECTED - The pin is output pin + * + */ static long STDCALL CInputPin_BeginFlush(IPin * This) { Debug unimplemented("CInputPin_BeginFlush", This); @@ -248,12 +481,34 @@ static long STDCALL CInputPin_BeginFlush(IPin * This) } +/** + * \brief IPin::EndFlush (ends a flush operation) + * + * \param[in] This pointer to IPin interface + * + * \return S_OK - success + * \return E_UNEXPECTED - The pin is output pin + * + */ static long STDCALL CInputPin_EndFlush(IPin* This) { Debug unimplemented("CInputPin_EndFlush", This); return E_NOTIMPL; } +/** + * \brief IPin::NewSegment (media sample received after this call grouped as segment with common + * start,stop time and rate) + * + * \param[in] This pointer to IPin interface + * \param[in] tStart start time of new segment + * \param[in] tStop end time of new segment + * \param[in] dRate rate at wich segment should be processed + * + * \return S_OK - success + * \return E_UNEXPECTED - The pin is output pin + * + */ static long STDCALL CInputPin_NewSegment(IPin* This, /* [in] */ REFERENCE_TIME tStart, /* [in] */ REFERENCE_TIME tStop, @@ -263,6 +518,12 @@ static long STDCALL CInputPin_NewSegment(IPin* This, return E_NOTIMPL; } +/** + * \brief CInputPin destructor + * + * \param[in] This pointer to CInputPin class + * + */ static void CInputPin_Destroy(CInputPin* This) { free(This->vt); @@ -271,6 +532,15 @@ static void CInputPin_Destroy(CInputPin* This) IMPLEMENT_IUNKNOWN(CInputPin) +/** + * \brief CInputPin constructor + * + * \param[in] amt media type for pin + * + * \return pointer to CInputPin if success + * \return NULL if error occured + * + */ CInputPin* CInputPinCreate(CBaseFilter* p, const AM_MEDIA_TYPE* amt) { CInputPin* This = (CInputPin*) malloc(sizeof(CInputPin)); @@ -326,24 +596,84 @@ static long STDCALL CBaseFilter_GetClassID(IBaseFilter * This, return E_NOTIMPL; } +/** + * \brief IMediaFilter::Stop (stops the filter) + * + * \param[in] This pointer to IBaseFilter interface + * + * \return S_OK success + * \return S_FALSE transition is not complete + * + * \remarks + * When filter is stopped it does onot deliver or process any samples and rejects any samples + * from upstream filter. + * Transition may be asynchronous. In this case method should return S_FALSE. + * Method always sets filter's state to State_Stopped even if error occured. + * + */ static long STDCALL CBaseFilter_Stop(IBaseFilter* This) { Debug unimplemented("CBaseFilter_Stop", This); return E_NOTIMPL; } +/** + * \brief IMediaFilter::Pause (pauses filter) + * + * \param[in] This pointer to IBaseFilter interface + * + * \return S_OK success + * \return S_FALSE transition is not complete + * + * \remarks + * When filter is paused it can receive, process and deliver samples. + * Live source filters do not deliver any samples while paused. + * Transition may be asynchronous. In this case method should return S_FALSE. + * Method always sets filter's state to State_Stopped even if error occured. + * + */ static long STDCALL CBaseFilter_Pause(IBaseFilter* This) { Debug unimplemented("CBaseFilter_Pause", This); return E_NOTIMPL; } +/** + * \brief IMediaFilter::Run (runs the filter) + * + * \param[in] This pointer to IBaseFilter interface + * \param[in] tStart Reference time corresponding to stream time 0. + * + * \return S_OK success + * \return S_FALSE transition is not complete + * + * \remarks + * When filter is running it can receive, process and deliver samples. Source filters + * generatesnew samples, and renderers renders them. + * Stream time is calculated as the current reference time minus tStart. + * Graph Manager sets tStart slightly in the future according to graph latency. + * + */ static long STDCALL CBaseFilter_Run(IBaseFilter* This, REFERENCE_TIME tStart) { Debug unimplemented("CBaseFilter_Run", This); return E_NOTIMPL; } +/** + * \brief IMediaFilter::GetState (retrieves the filter's state (running, stopped or paused)) + * + * \param[in] This pointer to IBaseFilter interface + * \param[in] dwMilliSecsTimeout Timeout interval in milliseconds. To block indifinitely pass + * INFINITE. + * \param[out] State pointer to variable that receives a member of FILTER_STATE enumeration. + * + * \return S_OK success + * \return E_POINTER Null pointer + * \return VFW_S_STATE_INTERMEDATE Intermediate state + * \return VFW_S_CANT_CUE The filter is active, but cannot deliver data. + * + */ static long STDCALL CBaseFilter_GetState(IBaseFilter* This, /* [in] */ unsigned long dwMilliSecsTimeout, // /* [out] */ FILTER_STATE *State) @@ -353,6 +683,16 @@ static long STDCALL CBaseFilter_GetState(IBaseFilter* This, return E_NOTIMPL; } +/** + * \brief IMediaFilter::SetSyncSource (sets the reference clock) + * + * \param[in] This pointer to IBaseFilter interface + * \param[in] pClock IReferenceClock interface of reference clock + * + * \return S_OK success + * \return apripriate error otherwise + * + */ static long STDCALL CBaseFilter_SetSyncSource(IBaseFilter* This, /* [in] */ IReferenceClock *pClock) { @@ -360,6 +700,17 @@ static long STDCALL CBaseFilter_SetSyncSource(IBaseFilter* This, return E_NOTIMPL; } +/** + * \brief IMediafilter::GetSyncSource (gets current reference clock) + * + * \param[in] This pointer to IBaseFilter interface + * \param[out] pClock address of variable that receives pointer to clock's + * IReferenceClock interface + * + * \return S_OK success + * \return E_POINTER Null pointer + * + */ static long STDCALL CBaseFilter_GetSyncSource(IBaseFilter* This, /* [out] */ IReferenceClock **pClock) { @@ -368,6 +719,17 @@ static long STDCALL CBaseFilter_GetSyncSource(IBaseFilter* This, } +/** + * \brief IBaseFilter::EnumPins (enumerates the pins of this filter) + * + * \param[in] This pointer to IBaseFilter interface + * \param[out] ppEnum address of variable that receives pointer to IEnumPins interface + * + * \return S_OK success + * \return E_OUTOFMEMORY Insufficient memory + * \return E_POINTER Null pointer + * + */ static long STDCALL CBaseFilter_EnumPins(IBaseFilter* This, /* [out] */ IEnumPins **ppEnum) { @@ -376,6 +738,21 @@ static long STDCALL CBaseFilter_EnumPins(IBaseFilter* This, return 0; } +/** + * \brief IBaseFilter::FindPin (retrieves the pin with specified id) + * + * \param[in] This pointer to IBaseFilter interface + * \param[in] Id constant wide string, containing pin id + * \param[out] ppPin address of variable that receives pointer to pin's IPin interface + * + * \return S_OK success + * \return E_POINTER Null pointer + * \return VFW_E_NOT_FOUND Could not find a pin with specified id + * + * \note + * Be sure to release the interface after use. + * + */ static long STDCALL CBaseFilter_FindPin(IBaseFilter* This, /* [string][in] */ const unsigned short* Id, /* [out] */ IPin **ppPin) @@ -384,6 +761,19 @@ static long STDCALL CBaseFilter_FindPin(IBaseFilter* This, return E_NOTIMPL; } +/** + * \brief IBaseFilter::QueryFilterInfo (retrieves information aboud the filter) + * + * \param[in] This pointer to IBaseFilter interface + * \param[out] pInfo pointer to FILTER_INFO structure + * + * \return S_OK success + * \return E_POINTER Null pointer + * + * \note + * If pGraph member of FILTER_INFO is not NULL, be sure to release IFilterGraph interface after use. + * + */ static long STDCALL CBaseFilter_QueryFilterInfo(IBaseFilter* This, // /* [out] */ FILTER_INFO *pInfo) void* pInfo) @@ -392,6 +782,22 @@ static long STDCALL CBaseFilter_QueryFilterInfo(IBaseFilter* This, return E_NOTIMPL; } +/** + * \brief IBaseFilter::JoinFilterGraph (notifies the filter that it has joined of left filter graph) + * + * \param[in] This pointer to IBaseFilter interface + * \param[in] pInfo pointer to graph's IFilterGraph interface or NULL if filter is leaving graph + * \param[in] pName pointer to wide character string that specifies a name for the filter + * + * \return S_OK success + * \return apropriate error code otherwise + * + * \remarks + * Filter should not call to graph's AddRef method. + * The IFilterGraph is guaranteed to be valid until graph manager calls this method again with + * the value NULL. + * + */ static long STDCALL CBaseFilter_JoinFilterGraph(IBaseFilter* This, /* [in] */ IFilterGraph* pGraph, /* [string][in] */ const unsigned short* pName) @@ -400,6 +806,20 @@ static long STDCALL CBaseFilter_JoinFilterGraph(IBaseFilter* This, return E_NOTIMPL; } +/** + * \brief IBaseFilter::QueryVendorInfo (retrieves a string containing vendor info) + * + * \param[in] This pointer to IBaseFilter interface + * \param[out] address of variable that receives pointer to a string containing vendor info + * + * \return S_OK success + * \return E_POINTER Null pointer + * \return E_NOTIMPL Not implemented + * + * \remarks + * Call to CoTaskMemFree to free memory allocated for string + * + */ static long STDCALL CBaseFilter_QueryVendorInfo(IBaseFilter* This, /* [string][out] */ unsigned short** pVendorInfo) { @@ -407,16 +827,38 @@ static long STDCALL CBaseFilter_QueryVendorInfo(IBaseFilter* This, return E_NOTIMPL; } +/** + * \brief CBaseFilter::GetPin (gets used pin) + * + * \param[in] This pointer to CBaseFilter object + * + * \return pointer to used pin's IPin interface + * + */ static IPin* CBaseFilter_GetPin(CBaseFilter* This) { return This->pin; } +/** + * \brief CBaseFilter::GetUnusedPin (gets used pin) + * + * \param[in] This pointer to CBaseFilter object + * + * \return pointer to unused pin's IPin interface + * + */ static IPin* CBaseFilter_GetUnusedPin(CBaseFilter* This) { return This->unused_pin; } +/** + * \brief CBaseFilter destructor + * + * \param[in] This pointer to CBaseFilter object + * + */ static void CBaseFilter_Destroy(CBaseFilter* This) { if (This->vt) @@ -430,6 +872,15 @@ static void CBaseFilter_Destroy(CBaseFilter* This) IMPLEMENT_IUNKNOWN(CBaseFilter) +/** + * \brief CBaseFilter constructor + * + * \param[in] type Pointer to media type for connection + * \param[in] parent Pointer to parent CBaseFilter2 object + * + * \return pointer to CBaseFilter object or NULL if error occured + * + */ CBaseFilter* CBaseFilterCreate(const AM_MEDIA_TYPE* type, CBaseFilter2* parent) { CBaseFilter* This = (CBaseFilter*) malloc(sizeof(CBaseFilter)); @@ -486,18 +937,64 @@ static long STDCALL CBaseFilter2_GetClassID(IBaseFilter* This, return E_NOTIMPL; } +/** + * \brief IMediaFilter::Stop (stops the filter) + * + * \param[in] This pointer to IBaseFilter interface + * + * \return S_OK success + * \return S_FALSE transition is not complete + * + * \remarks + * When filter is stopped it does onot deliver or process any samples and rejects any samples + * from upstream filter. + * Transition may be asynchronous. In this case method should return S_FALSE. + * Method always sets filter's state to State_Stopped even if error occured. + * + */ static long STDCALL CBaseFilter2_Stop(IBaseFilter* This) { Debug unimplemented("CBaseFilter2_Stop", This); return E_NOTIMPL; } +/** + * \brief IMediaFilter::Pause (pauses filter) + * + * \param[in] This pointer to IBaseFilter interface + * + * \return S_OK success + * \return S_FALSE transition is not complete + * + * \remarks + * When filter is paused it can receive, process and deliver samples. + * Live source filters do not deliver any samples while paused. + * Transition may be asynchronous. In this case method should return S_FALSE. + * Method always sets filter's state to State_Stopped even if error occured. + * + */ static long STDCALL CBaseFilter2_Pause(IBaseFilter* This) { Debug unimplemented("CBaseFilter2_Pause", This); return E_NOTIMPL; } +/** + * \brief IMediaFilter::Run (runs the filter) + * + * \param[in] This pointer to IBaseFilter interface + * \param[in] tStart Reference time corresponding to stream time 0. + * + * \return S_OK success + * \return S_FALSE transition is not complete + * + * \remarks + * When filter is running it can receive, process and deliver samples. Source filters + * generatesnew samples, and renderers renders them. + * Stream time is calculated as the current reference time minus tStart. + * Graph Manager sets tStart slightly in the future according to graph latency. + * + */ static long STDCALL CBaseFilter2_Run(IBaseFilter* This, REFERENCE_TIME tStart) { Debug unimplemented("CBaseFilter2_Run", This); @@ -505,6 +1002,20 @@ static long STDCALL CBaseFilter2_Run(IBaseFilter* This, REFERENCE_TIME tStart) } +/** + * \brief IMediaFilter::GetState (retrieves the filter's state (running, stopped or paused)) + * + * \param[in] This pointer to IBaseFilter interface + * \param[in] dwMilliSecsTimeout Timeout interval in milliseconds. To block indifinitely pass + * INFINITE. + * \param[out] State pointer to variable that receives a member of FILTER_STATE enumeration. + * + * \return S_OK success + * \return E_POINTER Null pointer + * \return VFW_S_STATE_INTERMEDATE Intermediate state + * \return VFW_S_CANT_CUE The filter is active, but cannot deliver data. + * + */ static long STDCALL CBaseFilter2_GetState(IBaseFilter* This, /* [in] */ unsigned long dwMilliSecsTimeout, // /* [out] */ FILTER_STATE *State) @@ -514,6 +1025,16 @@ static long STDCALL CBaseFilter2_GetState(IBaseFilter* This, return E_NOTIMPL; } +/** + * \brief IMediaFilter::SetSyncSource (sets the reference clock) + * + * \param[in] This pointer to IBaseFilter interface + * \param[in] pClock IReferenceClock interface of reference clock + * + * \return S_OK success + * \return apripriate error otherwise + * + */ static long STDCALL CBaseFilter2_SetSyncSource(IBaseFilter* This, /* [in] */ IReferenceClock* pClock) { @@ -521,6 +1042,17 @@ static long STDCALL CBaseFilter2_SetSyncSource(IBaseFilter* This, return E_NOTIMPL; } +/** + * \brief IMediafilter::GetSyncSource (gets current reference clock) + * + * \param[in] This pointer to IBaseFilter interface + * \param[out] pClock address of variable that receives pointer to clock's + * IReferenceClock interface + * + * \return S_OK success + * \return E_POINTER Null pointer + * + */ static long STDCALL CBaseFilter2_GetSyncSource(IBaseFilter* This, /* [out] */ IReferenceClock** pClock) { @@ -528,6 +1060,17 @@ static long STDCALL CBaseFilter2_GetSyncSource(IBaseFilter* This, return E_NOTIMPL; } +/** + * \brief IBaseFilter::EnumPins (enumerates the pins of this filter) + * + * \param[in] This pointer to IBaseFilter interface + * \param[out] ppEnum address of variable that receives pointer to IEnumPins interface + * + * \return S_OK success + * \return E_OUTOFMEMORY Insufficient memory + * \return E_POINTER Null pointer + * + */ static long STDCALL CBaseFilter2_EnumPins(IBaseFilter* This, /* [out] */ IEnumPins** ppEnum) { @@ -536,6 +1079,21 @@ static long STDCALL CBaseFilter2_EnumPins(IBaseFilter* This, return 0; } +/** + * \brief IBaseFilter::FindPin (retrieves the pin with specified id) + * + * \param[in] This pointer to IBaseFilter interface + * \param[in] Id constant wide string, containing pin id + * \param[out] ppPin address of variable that receives pointer to pin's IPin interface + * + * \return S_OK success + * \return E_POINTER Null pointer + * \return VFW_E_NOT_FOUND Could not find a pin with specified id + * + * \note + * Be sure to release the interface after use. + * + */ static long STDCALL CBaseFilter2_FindPin(IBaseFilter* This, /* [string][in] */ const unsigned short* Id, /* [out] */ IPin** ppPin) @@ -544,6 +1102,19 @@ static long STDCALL CBaseFilter2_FindPin(IBaseFilter* This, return E_NOTIMPL; } +/** + * \brief IBaseFilter::QueryFilterInfo (retrieves information aboud the filter) + * + * \param[in] This pointer to IBaseFilter interface + * \param[out] pInfo pointer to FILTER_INFO structure + * + * \return S_OK success + * \return E_POINTER Null pointer + * + * \note + * If pGraph member of FILTER_INFO is not NULL, be sure to release IFilterGraph interface after use. + * + */ static long STDCALL CBaseFilter2_QueryFilterInfo(IBaseFilter* This, // /* [out] */ FILTER_INFO *pInfo) void* pInfo) @@ -552,6 +1123,22 @@ static long STDCALL CBaseFilter2_QueryFilterInfo(IBaseFilter* This, return E_NOTIMPL; } +/** + * \brief IBaseFilter::JoinFilterGraph (notifies the filter that it has joined of left filter graph) + * + * \param[in] This pointer to IBaseFilter interface + * \param[in] pInfo pointer to graph's IFilterGraph interface or NULL if filter is leaving graph + * \param[in] pName pointer to wide character string that specifies a name for the filter + * + * \return S_OK success + * \return apropriate error code otherwise + * + * \remarks + * Filter should not call to graph's AddRef method. + * The IFilterGraph is guaranteed to be valid until graph manager calls this method again with + * the value NULL. + * + */ static long STDCALL CBaseFilter2_JoinFilterGraph(IBaseFilter* This, /* [in] */ IFilterGraph* pGraph, /* [string][in] */ @@ -561,6 +1148,20 @@ static long STDCALL CBaseFilter2_JoinFilterGraph(IBaseFilter* This, return E_NOTIMPL; } +/** + * \brief IBaseFilter::QueryVendorInfo (retrieves a string containing vendor info) + * + * \param[in] This pointer to IBaseFilter interface + * \param[out] address of variable that receives pointer to a string containing vendor info + * + * \return S_OK success + * \return E_POINTER Null pointer + * \return E_NOTIMPL Not implemented + * + * \remarks + * Call to CoTaskMemFree to free memory allocated for string + * + */ static long STDCALL CBaseFilter2_QueryVendorInfo(IBaseFilter* This, /* [string][out] */ unsigned short** pVendorInfo) @@ -569,11 +1170,25 @@ static long STDCALL CBaseFilter2_QueryVendorInfo(IBaseFilter* This, return E_NOTIMPL; } +/** + * \brief CBaseFilter2::GetPin (gets used pin) + * + * \param[in] This pointer to CBaseFilter2 object + * + * \return pointer to used pin's IPin interface + * + */ static IPin* CBaseFilter2_GetPin(CBaseFilter2* This) { return This->pin; } +/** + * \brief CBaseFilter2 destructor + * + * \param[in] This pointer to CBaseFilter2 object + * + */ static void CBaseFilter2_Destroy(CBaseFilter2* This) { Debug printf("CBaseFilter2_Destroy(%p) called\n", This); @@ -588,11 +1203,19 @@ IMPLEMENT_IUNKNOWN(CBaseFilter2) static GUID CBaseFilter2_interf1 = {0x76c61a30, 0xebe1, 0x11cf, {0x89, 0xf9, 0x00, 0xa0, 0xc9, 0x03, 0x49, 0xcb}}; +/// IID_IAMNetShowPreroll static GUID CBaseFilter2_interf2 = {0xaae7e4e2, 0x6388, 0x11d1, {0x8d, 0x93, 0x00, 0x60, 0x97, 0xc9, 0xa2, 0xb2}}; +/// IID_IAMRebuild static GUID CBaseFilter2_interf3 = {0x02ef04dd, 0x7580, 0x11d1, {0xbe, 0xce, 0x00, 0xc0, 0x4f, 0xb6, 0xe9, 0x37}}; +/** + * \brief CBaseFilter2 constructor + * + * \return pointer to CBaseFilter2 object or NULL if error occured + * + */ CBaseFilter2* CBaseFilter2Create() { CBaseFilter2* This = (CBaseFilter2*) malloc(sizeof(CBaseFilter2)); @@ -645,6 +1268,19 @@ CBaseFilter2* CBaseFilter2Create() *************/ +/** + * \brief IPin::ConnectedTo (retrieves pointer to the connected pin, if such exist) + * + * \param[in] This pointer to IPin interface + * \param[out] pPin pointer to remote pin's IPin interface + * + * \return S_OK - success + * \return E_POINTER - Null pointer + * \return VFW_E_NOT_CONNECTED - pin is not connected + * + * \note + * Caller must call Release on received IPin, when done + */ static long STDCALL CRemotePin_ConnectedTo(IPin* This, /* [out] */ IPin** pPin) { Debug printf("CRemotePin_ConnectedTo(%p) called\n", This); @@ -655,6 +1291,16 @@ static long STDCALL CRemotePin_ConnectedTo(IPin* This, /* [out] */ IPin** pPin) return 0; } +/** + * \brief IPin::QueryDirection (retrieves pin direction) + * + * \param[in] This pointer to IPin interface + * \param[out] pPinDir pointer to variable, that receives pin direction (PINDIR_INPUT,PINDIR_OUTPUT) + * + * \return S_OK - success + * \return E_POINTER - Null pointer + * + */ static long STDCALL CRemotePin_QueryDirection(IPin* This, /* [out] */ PIN_DIRECTION* pPinDir) { @@ -665,12 +1311,36 @@ static long STDCALL CRemotePin_QueryDirection(IPin* This, return 0; } +/** + * \brief IPin::ConnectionMediaType (retrieves media type for connection, if such exist) + * + * \param[in] This pointer to IPin interface + * \param[out] pmt pointer to AM_MEDIA_TYPE, that receives connection media type + * + * \return S_OK - success + * \return E_POINTER - Null pointer + * \return VFW_E_NOT_CONNECTED - pin is not connected + * + */ static long STDCALL CRemotePin_ConnectionMediaType(IPin* This, /* [out] */ AM_MEDIA_TYPE* pmt) { Debug unimplemented("CRemotePin_ConnectionMediaType", This); return E_NOTIMPL; } +/** + * \brief IPin::QueryPinInfo (retrieves information about the pin) + * + * \param[in] This pointer to IPin interface + * \param[out] pInfo pointer to PIN_INFO structure, that receives pin info + * + * \return S_OK - success + * \return E_POINTER - Null pointer + * + * \note + * If pInfo->pFilter is not NULL, then caller must call Release on pInfo->pFilter when done + * + */ static long STDCALL CRemotePin_QueryPinInfo(IPin* This, /* [out] */ PIN_INFO* pInfo) { CBaseFilter* lparent = ((CRemotePin*)This)->parent; @@ -682,6 +1352,12 @@ static long STDCALL CRemotePin_QueryPinInfo(IPin* This, /* [out] */ PIN_INFO* pI return 0; } +/** + * \brief CRemotePin destructor + * + * \param[in] This pointer to CRemotePin object + * + */ static void CRemotePin_Destroy(CRemotePin* This) { Debug printf("CRemotePin_Destroy(%p) called\n", This); @@ -691,6 +1367,15 @@ static void CRemotePin_Destroy(CRemotePin* This) IMPLEMENT_IUNKNOWN(CRemotePin) +/** + * \brief CRemotePin constructor + * + * \param[in] pt parent filter + * \param[in] rpin remote pin + * + * \return pointer to CRemotePin or NULL if error occured + * + */ CRemotePin* CRemotePinCreate(CBaseFilter* pt, IPin* rpin) { CRemotePin* This = (CRemotePin*) malloc(sizeof(CRemotePin)); @@ -732,6 +1417,19 @@ CRemotePin* CRemotePinCreate(CBaseFilter* pt, IPin* rpin) *************/ +/** + * \brief IPin::QueryPinInfo (retrieves information about the pin) + * + * \param[in] This pointer to IPin interface + * \param[out] pInfo pointer to PIN_INFO structure, that receives pin info + * + * \return S_OK - success + * \return E_POINTER - Null pointer + * + * \note + * If pInfo->pFilter is not NULL, then caller must call Release on pInfo->pFilter when done + * + */ static long STDCALL CRemotePin2_QueryPinInfo(IPin* This, /* [out] */ PIN_INFO* pInfo) { @@ -744,7 +1442,13 @@ static long STDCALL CRemotePin2_QueryPinInfo(IPin* This, return 0; } -// FIXME - not being released! +/** + * \brief CremotePin2 destructor + * + * \param This pointer to CRemotePin2 object + * + * FIXME - not being released! + */ static void CRemotePin2_Destroy(CRemotePin2* This) { Debug printf("CRemotePin2_Destroy(%p) called\n", This); @@ -754,6 +1458,14 @@ static void CRemotePin2_Destroy(CRemotePin2* This) IMPLEMENT_IUNKNOWN(CRemotePin2) +/** + * \brief CRemotePin2 contructor + * + * \param[in] p pointer to parent CBaseFilter2 object + * + * \return pointer to CRemotePin2 object or NULL if error occured + * + */ CRemotePin2* CRemotePin2Create(CBaseFilter2* p) { CRemotePin2* This = (CRemotePin2*) malloc(sizeof(CRemotePin2)); -- cgit v1.2.3