// Asked to connect to a pin.
// A pin is always attached to an owning filter object
// so we always delegate our locking to that object.
//一个pin总是连接到一个拥有filter的对象，因此Connect函数总是把我们的
//锁委托给这个对象。
// We first of all retrieve a media type enumerator for the input pin
// and see if we accept any of the formats that it would ideally like,
// Connect函数首先检索输入pin的媒体类型枚举器来查看是否有任何这个
//函数能满意接受的格式，
// failing that we retrieve our enumerator and see if it will accept
// any of our preferred types.
//失败的话Connect函数检索我们的枚举器，查看我们是否有任何它能接受的
//首选类型。
#define CheckPointer(p,ret) {if((p)==NULL) return (ret);}
#define ValidateReadPtr(p,cb) \
{if(IsBadReadPtr((PVOID)p,cb) == TRUE) \
DbgBreak("Invalid read pointer");}
STDMETHODIMP
CBasePin::Connect(
IPin * pReceivePin,
const AM_MEDIA_TYPE *pmt // optional media type
)
{
CheckPointer(pReceivePin,E_POINTER);
ValidateReadPtr(pReceivePin,sizeof(IPin));
CAutoLock cObjectLock(m_pLock);
DisplayPinInfo(pReceivePin);
// See if we are already connected
if (m_Connected)
{
DbgLog((LOG_TRACE, CONNECT_TRACE_LEVEL, TEXT("Already connected")));
return VFW_E_ALREADY_CONNECTED;
}
// See if the filter is active，一半filter只能在停止状态连接
if (!IsStopped() && !m_bCanReconnectWhenActive)
{
return VFW_E_NOT_STOPPED;
}
// Find a mutually agreeable media type -
// Pass in the template media type. If this is partially specified,
// each of the enumerated media types will need to be checked against
// it. If it is non-null and fully specified, we will just try to connect
// with this.
//开始媒体类型检查，找出一种连接双方都支持的媒体类型。
const CMediaType * ptype = (CMediaType*)pmt;
HRESULT hr = AgreeMediaType(pReceivePin, ptype);
if (FAILED(hr))
{
DbgLog((LOG_TRACE, CONNECT_TRACE_LEVEL, TEXT("Failed to agree type")));
// Since the procedure is already returning an error code, there
// is nothing else this function can do to report the error.
EXECUTE_ASSERT( SUCCEEDED( BreakConnect() ) );
return hr;
}
DbgLog((LOG_TRACE, CONNECT_TRACE_LEVEL, TEXT("Connection succeeded")));
return NOERROR;
}
// This is called to make the connection,
// including the taask of finding a media type for the pin connection.
// pmt is the proposed推荐 media type from the Connect call:
// if this is fully specified指定, we will try that.
// Otherwise否则 we enumerate枚举 and
// try all the input pin's types first and if that fails we then enumerate
// and try all our preferred media types.
// For each media type we check it against pmt (if non-null and
// partially specified) as well as checking that both pins will accept it.
//首先检查指定媒体类型pmt的有效性，
//若是fully specified的则就用该类型调用内部函数AttemptConnection进行连接。
//若是不，输入pin和输出pin开始真正的类型协商过程，
//for循环2次,输出pin上成员变量m_bTryMyTypesFirst初始值为false即0，因此先pReceivePin->EnumMediaTypes(&pEnumMediaTypes);
//在输入pin上进行类型枚举试连接，如果不成功
//再到输出pin进行类型枚举试连接。
HRESULT CBasePin::AgreeMediaType(
IPin *pReceivePin,
const CMediaType *pmt)
{
ASSERT(pReceivePin);
IEnumMediaTypes *pEnumMediaTypes = NULL;
// if the media type is fully specified then use that.如果是pmt是完全指定的媒体类型，我们就用它做连接。
if ( (pmt != NULL) && (!pmt->IsPartiallySpecified())) {
// if this media type fails, then we must fail the connection
// since if pmt is nonnull we are only allowed to connect
// using a type that matches it.
return AttemptConnection(pReceivePin, pmt);
}
// Try the other pin's enumerator.尝试另外的pin枚举器
HRESULT hrFailure = VFW_E_NO_ACCEPTABLE_TYPES;
for (int i = 0; i < 2; i++)
{
HRESULT hr;
if (i == (int)m_bTryMyTypesFirst)
{
hr = pReceivePin->EnumMediaTypes(&pEnumMediaTypes);
}
else
{
hr = EnumMediaTypes(&pEnumMediaTypes);
}
if (SUCCEEDED(hr))
{
ASSERT(pEnumMediaTypes);
hr = TryMediaTypes(pReceivePin,pmt,pEnumMediaTypes);
pEnumMediaTypes->Release();
if (SUCCEEDED(hr))
{
return NOERROR;
}
else
{
// try to remember specific error codes if there are any
if ((hr != E_FAIL) &&
(hr != E_INVALIDARG) &&
(hr != VFW_E_TYPE_NOT_ACCEPTED))
{
hrFailure = hr;
}
}
}
}
return hrFailure;
}
// Given an enumerator we cycle循环 through all the media types it proposes and
// firstly suggest them to our derived pin class and if that succeeds try
// them with the pin in a ReceiveConnection call.
// This means that if our pin proposes a media type we still check in here that we can support it.
// This is deliberate so that in simple cases the enumerator can hold all of the
// media types even if some of them are not really currently available
HRESULT CBasePin::TryMediaTypes(
IPin *pReceivePin,
const CMediaType *pmt,
IEnumMediaTypes *pEnum)
{
/* Reset the current enumerator position */
HRESULT hr = pEnum->Reset();
if (FAILED(hr)) {
return hr;
}
CMediaType *pMediaType = NULL;
ULONG ulMediaCount = 0;
// attempt to remember a specific error code if there is one
HRESULT hrFailure = S_OK;
for (;;)
{
// Retrieve恢复 the next media type NOTE each time round the loop the
// numerator interface will allocate another AM_MEDIA_TYPE structure
// If we are successful then we copy it into our output object,
// if not then we must delete the memory allocated before returning
//枚举pin上提供的所有类型，然后全都进行连接
hr = pEnum->Next(1, (AM_MEDIA_TYPE**)&pMediaType,&ulMediaCount);
if (hr != S_OK)
{
if (S_OK == hrFailure)
{
hrFailure = VFW_E_NO_ACCEPTABLE_TYPES;
}
return hrFailure;
}
ASSERT(ulMediaCount == 1);
ASSERT(pMediaType);
// check that this matches the partial type (if any)
if ((pmt == NULL) ||
pMediaType->MatchesPartial(pmt))
{
hr = AttemptConnection(pReceivePin, pMediaType);
// attempt to remember a specific error code
if (FAILED(hr) &&
SUCCEEDED(hrFailure) &&
(hr != E_FAIL) &&
(hr != E_INVALIDARG) &&
(hr != VFW_E_TYPE_NOT_ACCEPTED))
{
hrFailure = hr;
}
}
else
{
hr = VFW_E_NO_ACCEPTABLE_TYPES;
}
DeleteMediaType(pMediaType);
if(S_OK == hr)
return hr;
}
}
// given a specific media type, attempt a connection (includes
// checking that the type is acceptable to this pin)
HRESULT
CBasePin::AttemptConnection(
IPin* pReceivePin, // connect to this pin
const CMediaType* pmt // using this type
)
{
// The caller should hold the filter lock becasue this function
// uses m_Connected. The caller should also hold the filter lock
// because this function calls SetMediaType(), IsStopped() and
// CompleteConnect().
//hold the filter lock.获取filter对象上是操作权
ASSERT(CritCheckIn(m_pLock));
// Check that the connection is valid -- need to do this for every
// connect attempt since BreakConnect will undo it.
HRESULT hr = CheckConnect(pReceivePin);
if (FAILED(hr)) {
DbgLog((LOG_TRACE, CONNECT_TRACE_LEVEL, TEXT("CheckConnect failed")));
// Since the procedure is already returning an error code, there
// is nothing else this function can do to report the error.
EXECUTE_ASSERT( SUCCEEDED( BreakConnect() ) );
return hr;
}
DisplayTypeInfo(pReceivePin, pmt);
//Check we will accept this media type
hr = CheckMediaType(pmt);
if (hr == NOERROR)
{
// Make ourselves look connected otherwise ReceiveConnection
// may not be able to complete the connection
m_Connected = pReceivePin;
m_Connected->AddRef();
hr = SetMediaType(pmt);
//把输入pin对象指针和其媒体类型保存在输出pin对象中。
if (SUCCEEDED(hr))
{
// See if the other pin will accept this type.
//输入pin询问连接对方是否也能接受当前连接类型
hr = pReceivePin->ReceiveConnection((IPin *)this, pmt);
if (SUCCEEDED(hr))
{
// Complete the connection.设置数据传输的内存分配以及管理工作
hr = CompleteConnect(pReceivePin);
if (SUCCEEDED(hr))
{
return hr;
}
else
{
DbgLog((LOG_TRACE,
CONNECT_TRACE_LEVEL,
TEXT("Failed to complete connection")));
pReceivePin->Disconnect();
}
}
}
}
else
{
// we cannot use this media type
// return a specific media type error if there is one
// or map a general failure code to something more helpful
// (in particular S_FALSE gets changed to an error code)
if (SUCCEEDED(hr) ||
(hr == E_FAIL) ||
(hr == E_INVALIDARG)) {
hr = VFW_E_TYPE_NOT_ACCEPTED;
}
}
// BreakConnect and release any connection here in case CheckMediaType
// failed, or if we set anything up during a call back during
// ReceiveConnection.
// Since the procedure is already returning an error code, there
// is nothing else this function can do to report the error.
EXECUTE_ASSERT( SUCCEEDED( BreakConnect() ) );
/* If failed then undo our state */
if (m_Connected) {
m_Connected->Release();
m_Connected = NULL;
}
return hr;
}
HRESULT
CBaseOutputPin::CompleteConnect(IPin *pReceivePin)
{
UNREFERENCED_PARAMETER(pReceivePin);
return DecideAllocator(m_pInputPin, &m_pAllocator);
}
//在DirectShow中，数据传输单元叫Sample(Sample也是一个COM组件，
//管理一块数据内存)；而Sample是由分配器(Allocator，也是一个COM)来管理的。
//连接双方必须使用同一个分配器,但是这个分配器到底由哪个pin创建也要协商。
HRESULT
CBaseOutputPin::DecideAllocator(IMemInputPin *pPin, IMemAllocator **ppAlloc)
{
HRESULT hr = NOERROR;
*ppAlloc = NULL;
ALLOCATOR_PROPERTIES prop;
ZeroMemory(&prop, sizeof(prop));
//询问输入pin对分配器的要求
pPin->GetAllocatorRequirements(&prop);
// if he doesn't care about alignment, then set it to 1
if (prop.cbAlign == 0) {
prop.cbAlign = 1;
}
//询问输入pin是否提供一个分配器
hr = pPin->GetAllocator(ppAlloc);
if (SUCCEEDED(hr)) {
//决定Sample使用的内存大小，一起分配器管理Sample的数量
hr = DecideBufferSize(*ppAlloc, &prop);
if (SUCCEEDED(hr)) {
//通知输入pin最终使用的分配器对象
hr = pPin->NotifyAllocator(*ppAlloc, FALSE);
if (SUCCEEDED(hr)) {
return NOERROR;
}
}
}
// If the GetAllocator failed we may not have an interface
if (*ppAlloc) {
(*ppAlloc)->Release();
*ppAlloc = NULL;
}
//Try the output pin's allocator by the same method
//创建一个输出pin上的分配器
hr = InitAllocator(ppAlloc);
if (SUCCEEDED(hr)) {
hr = DecideBufferSize(*ppAlloc, &prop);
if (SUCCEEDED(hr)) {
hr = pPin->NotifyAllocator(*ppAlloc, FALSE);
if (SUCCEEDED(hr)) {
return NOERROR;
}
}
}
//Likewise同样 we may not have an interface to release
if (*ppAlloc) {
(*ppAlloc)->Release();
*ppAlloc = NULL;
}
return hr;
}
//当pin上数据传输内存分配协商成功后，并没有马上分配给Sample内存。一般是在Filter Graph运行后输入pin调用Active时进行的。
HRESULT CBaseOutputPin::Active(void)
{
if(m_pAllocator == TRUE)
{
return VFW_E_NO_ALLOCATOR;
}
return m_pAllocator->Commit();
}
