Classe COleDispatchDriver
Implementa o lado do cliente da automação OLE.
Sintaxe
class COleDispatchDriver
Membros
Construtores públicos
| Nome | Descrição |
|---|---|
| COleDispatchDriver::COleDispatchDriver | Constrói um objeto COleDispatchDriver. |
Métodos públicos
| Nome | Descrição |
|---|---|
| COleDispatchDriver::AttachDispatch | Anexa uma conexão IDispatch ao objeto COleDispatchDriver. |
| COleDispatchDriver::CreateDispatch | Cria uma conexão IDispatch e a anexa ao objeto COleDispatchDriver. |
| COleDispatchDriver::DetachDispatch | Desanexa uma conexão IDispatch, sem liberá-la. |
| COleDispatchDriver::GetProperty | Obtém uma propriedade de automação. |
| COleDispatchDriver::InvokeHelper | Auxiliar para chamar métodos de automação. |
| COleDispatchDriver::ReleaseDispatch | Libera uma conexão IDispatch. |
| COleDispatchDriver::SetProperty | Define uma propriedade de automação. |
Operadores públicos
| Nome | Descrição |
|---|---|
| COleDispatchDriver::operator = | Copia o valor de origem no objeto COleDispatchDriver. |
| COleDispatchDriver::operator LPDISPATCH | Acessa o ponteiro IDispatch subjacente. |
Membros de Dados Públicos
| Nome | Descrição |
|---|---|
| COleDispatchDriver::m_bAutoRelease | Especifica se é devido liberar o IDispatch durante ReleaseDispatch ou a destruição de objeto. |
| COleDispatchDriver::m_lpDispatch | Indica o ponteiro para a interface IDispatch anexada a esse COleDispatchDriver. |
Comentários
COleDispatchDriver não tem uma classe base.
As interfaces de expedição OLE fornecem acesso aos métodos e propriedades de um objeto. Funções membro de COleDispatchDriver anexam, desanexam, criam e liberam uma conexão de expedição do tipo IDispatch. Outras funções de membro usam listas de argumentos variáveis para simplificar a chamada IDispatch::Invoke.
Essa classe pode ser usada diretamente, mas geralmente é usada somente por classes criadas pelo assistente Adicionar Classe. Quando você cria novas classes C++ importando uma biblioteca de tipos, as novas classes são derivadas de COleDispatchDriver.
Para obter mais informações sobre o uso de COleDispatchDriver, consulte os seguintes artigos:
Hierarquia de herança
COleDispatchDriver
Requisitos
Cabeçalho afxdisp.h
COleDispatchDriver::AttachDispatch
Chame a função membro AttachDispatch para anexar um ponteiro IDispatch ao objeto COleDispatchDriver. Para obter mais informações, confira Como implementar a interface IDispatch.
void AttachDispatch(
LPDISPATCH lpDispatch,
BOOL bAutoRelease = TRUE);
Parâmetros
lpDispatch
Ponteiro para um objeto IDispatch OLE que será anexado ao objeto COleDispatchDriver.
bAutoRelease
Especifica se a expedição deve ser liberada quando esse objeto sair do escopo.
Comentários
Essa função libera um ponteiro IDispatch que já está anexado ao objeto COleDispatchDriver.
Exemplo
void COleContainerView::OnAttachDispatch()
{
CLSID clsidWMP;
LPDISPATCH pWMPDispatch = NULL;
COleDispatchDriver oddWMP;
try
{
AfxCheckError(::CLSIDFromProgID(_T("WMPlayer.OCX"), &clsidWMP));
AfxCheckError(::CoCreateInstance(clsidWMP, NULL, CLSCTX_INPROC_SERVER,
IID_IDispatch, (LPVOID*)& pWMPDispatch));
oddWMP.AttachDispatch(pWMPDispatch, TRUE);
pWMPDispatch = NULL; // our COleDispatchDriver now owns the interface
CString strUIMode;
oddWMP.GetProperty(23, VT_BSTR, (void*)& strUIMode);
TRACE(_T("WMP uiMode is %s.\n"), strUIMode);
}
catch (COleException* pe)
{
pe->ReportError();
pe->Delete();
}
catch (CMemoryException* pe)
{
pe->ReportError();
pe->Delete();
}
// cleanup
if (NULL != pWMPDispatch)
{
pWMPDispatch->Release();
}
// COleDispatchDriver automatically releases the dispatch interface when
// it goes out of scope if m_bAutoRelease is TRUE.
}
COleDispatchDriver::COleDispatchDriver
Constrói um objeto COleDispatchDriver.
COleDispatchDriver();
COleDispatchDriver(LPDISPATCH lpDispatch, BOOL bAutoRelease = TRUE);
COleDispatchDriver(const COleDispatchDriver& dispatchSrc);
Parâmetros
lpDispatch
Ponteiro para um objeto IDispatch OLE que será anexado ao objeto COleDispatchDriver.
bAutoRelease
Especifica se a expedição deve ser liberada quando esse objeto sair do escopo.
dispatchSrc
Referência a um objeto COleDispatchDriver existente.
Comentários
O formulário COleDispatchDriver( LPDISPATCH lpDispatch, BOOL bAutoRelease = TRUE ) conecta a interface IDispatch.
O formulário COleDispatchDriver( const COleDispatchDriver& dispatchSrc ) copia um objeto COleDispatchDriver existente e incrementa a contagem de referência.
O formulário COleDispatchDriver( ) cria um objeto COleDispatchDriver, mas não conecta a interface IDispatch. Antes de usar COleDispatchDriver( ) sem argumentos, você deve conectar um IDispatch a ele usando COleDispatchDriver::CreateDispatch ou COleDispatchDriver::AttachDispatch. Para obter mais informações, confira Como implementar a interface IDispatch.
Exemplo
Confira o exemplo de COleDispatchDriver::CreateDispatch.
COleDispatchDriver::CreateDispatch
Cria um objeto de interface IDispatch e o anexa ao objeto COleDispatchDriver.
BOOL CreateDispatch(
REFCLSID clsid,
COleException* pError = NULL);
BOOL CreateDispatch(
LPCTSTR lpszProgID,
COleException* pError = NULL);
Parâmetros
clsid
ID de classe do objeto IDispatch de conexão que será criado.
pError
Ponteiro para um objeto de exceção OLE, que reterá o código de status resultante da criação.
lpszProgID
Ponteiro para o identificador programático, como "Excel.Document.5", do objeto de automação para o qual o objeto de expedição deve ser criado.
Valor de Devolução
Diferente de zero em caso de êxito. Caso contrário, 0.
Exemplo
void COleContainerView::OnCreateDispatch()
{
COleDispatchDriver disp;
COleException* pe = new COleException;
try
{
// Create instance of Microsoft System Information Control
// by using ProgID.
if (disp.CreateDispatch(_T("WMPlayer.OCX"), pe))
{
//Get uiMode.
CString strUIMode;
disp.InvokeHelper(23, DISPATCH_PROPERTYGET, VT_BSTR,
(void*)& strUIMode, NULL);
CString strMsg;
strMsg.Format(_T("WMP uiMode is %s."), strUIMode);
AfxMessageBox(strMsg);
}
else
{
throw pe;
}
}
//Catch control-specific exceptions.
catch (COleDispatchException* pe)
{
CString cStr;
if (!pe->m_strSource.IsEmpty())
cStr = pe->m_strSource + _T(" - ");
if (!pe->m_strDescription.IsEmpty())
cStr += pe->m_strDescription;
else
cStr += _T("unknown error");
AfxMessageBox(cStr, MB_OK,
(pe->m_strHelpFile.IsEmpty()) ? 0 : pe->m_dwHelpContext);
pe->Delete();
}
//Catch all MFC exceptions, including COleExceptions.
// OS exceptions will not be caught.
catch (CException* pe)
{
TRACE(_T("%s(%d): OLE Execption caught: SCODE = %x"),
__FILE__, __LINE__, COleException::Process(pe));
pe->Delete();
}
pe->Delete();
}
COleDispatchDriver::DetachDispatch
Desanexa a conexão IDispatch atual desse objeto.
LPDISPATCH DetachDispatch();
Valor de Devolução
Um ponteiro para o objeto IDispatch OLE anexado anteriormente.
Comentários
O IDispatch não foi liberado.
Para obter mais informações sobre o tipo LPDISPATCH, consulte Implementar a interface IDispatch no SDK do Windows.
Exemplo
LPDISPATCH CreateLPDispatch(LPCTSTR lpszProgId)
{
COleDispatchDriver disp;
disp.CreateDispatch(lpszProgId);
return disp.DetachDispatch();
}
COleDispatchDriver::GetProperty
Obtém a propriedade do objeto especificada por dwDispID.
void GetProperty(
DISPID dwDispID,
VARTYPE vtProp,
void* pvProp) const;
Parâmetros
dwDispID
Identifica a propriedade a ser recuperada.
vtProp
Especifica a propriedade que será recuperada. Para obter valores possíveis, consulte a seção Comentários para COleDispatchDriver::InvokeHelper.
pvProp
Endereço da variável que receberá o valor da propriedade. Ele deve corresponder ao tipo especificado por vtProp.
Exemplo
CString IMyComObject::GetString(DISPID dispid)
{
CString result;
GetProperty(dispid, VT_BSTR, (void*)& result);
return result;
}
COleDispatchDriver::InvokeHelper
Chama o método ou a propriedade do objeto especificado por dwDispID, no contexto especificado por wFlags.
void AFX_CDECL InvokeHelper(
DISPID dwDispID,
WORD wFlags,
VARTYPE vtRet,
void* pvRet,
const BYTE* pbParamInfo, ...);
Parâmetros
dwDispID
Identifica o método ou a propriedade que será invocada.
wFlags
Sinalizadores que descrevem o contexto da chamada de IDispatch::Invoke. . Para obter uma lista de valores possíveis, consulte o parâmetro wFlags em IDispatch::Invoke no SDK do Windows.
vtRet
Especifica o tipo de valor retornado. Para valores possíveis, consulte a seção Comentários.
pvRet
Endereço da variável que receberá o valor da propriedade ou o valor retornado. Ele deve corresponder ao tipo especificado por vtRet.
pbParamInfo
Ponteiro para uma cadeia de cadeia de caracteres de bytes com terminada em valor nulo que especifica os tipos dos parâmetros que seguem pbParamInfo.
...
Lista variável de parâmetros, de tipos especificados em pbParamInfo.
Comentários
O parâmetro pbParamInfo especifica os tipos dos parâmetros passados para o método ou propriedade. A lista variável de argumentos é representada por ... na declaração de sintaxe.
Os valores possíveis para o argumento vtRet são obtidos da enumeração VARENUM. Os valores possíveis são:
| Símbolo | Tipo de retorno |
|---|---|
| VT_EMPTY | void |
| VT_I2 | short |
| VT_I4 | long |
| VT_R4 | float |
| VT_R8 | double |
| VT_CY | CY |
| VT_DATE | DATE |
| VT_BSTR | BSTR |
| VT_DISPATCH | LPDISPATCH |
| VT_ERROR | SCODE |
| VT_BOOL | BOOL |
| VT_VARIANT | VARIANT |
| VT_UNKNOWN | LPUNKNOWN |
O argumento pbParamInfo é uma lista separada por espaços de constantes VTS_. Um ou mais desses valores, separados por espaços (não vírgulas), especifica a lista de parâmetros da função. Os valores possíveis são listados com a macro EVENT_CUSTOM.
Essa função converte os parâmetros em valores VARIANTARG e invoca o método IDispatch::Invoke. Se a chamada de Invoke falhar, essa função gerará uma exceção. Se o SCODE (código de status) retornado for IDispatch::Invoke DISP_E_EXCEPTION, essa função gerará um objeto COleException, caso contrário, ele gerará um COleDispatchException.
Para obter mais informações, consulte VARIANTARG, Implementar a interface do IDispatch, IDispatch::Invoke e a Estrutura de códigos de erro COM no SDK do Windows.
Exemplo
Confira o exemplo de COleDispatchDriver::CreateDispatch.
COleDispatchDriver::m_bAutoRelease
Se TRUE, o objeto COM acessado por m_lpDispatch será liberado automaticamente quando ReleaseDispatch for chamado ou quando esse objeto COleDispatchDriver for destruído.
BOOL m_bAutoRelease;
Comentários
Por padrão, m_bAutoRelease é definido como TRUE no construtor.
Para obter mais informações sobre como liberar objetos COM, consulte Implementar a contagem de referências e IUnknown::Release no SDK do Windows.
Exemplo
// Clean up by forcing Release to be called
// on COleDispatchDriver object and delete
if (bError)
{
pDisp->m_bAutoRelease = TRUE;
delete pDisp;
pDisp = NULL;
}
COleDispatchDriver::m_lpDispatch
O ponteiro para a interface IDispatch anexada a esse COleDispatchDriver.
LPDISPATCH m_lpDispatch;
Comentários
O membro de dados m_lpDispatch é uma variável pública do tipo LPDISPATCH.
Para saber mais, confira IDispatch no SDK do Windows.
Exemplo
Confira o exemplo de COleDispatchDriver::AttachDispatch.
COleDispatchDriver::operator =
Copia o valor de origem no objeto COleDispatchDriver.
const COleDispatchDriver& operator=(const COleDispatchDriver& dispatchSrc);
Parâmetros
dispatchSrc
Um ponteiro para um objeto COleDispatchDriver existente.
COleDispatchDriver::operator LPDISPATCH
Acessa o ponteiro IDispatch subjacente ao objeto COleDispatchDriver.
operator LPDISPATCH();
Exemplo
COleDispatchDriver disp;
if (disp.CreateDispatch(_T("WMPlayer.OCX")))
{
IDispatch* pDispatch = disp; //COleDispatchDriver::operator
//LPDISPATCH is called here
IUnknown* pUnkn = NULL;
HRESULT hr = pDispatch->QueryInterface(IID_IUnknown, (void**)& pUnkn);
if (SUCCEEDED(hr))
{
//Do something...
pUnkn->Release();
}
}
COleDispatchDriver::ReleaseDispatch
Libera a conexão IDispatch. Para obter mais informações, confira Implementar a interface do IDispatch
void ReleaseDispatch();
Comentários
Se a versão automática tiver sido definida para essa conexão, essa função chamará IDispatch::Release antes de liberar a interface.
Exemplo
Confira o exemplo de COleDispatchDriver::AttachDispatch.
COleDispatchDriver::SetProperty
Define a propriedade do objeto OLE especificada por dwDispID.
void AFX_CDECL SetProperty(
DISPID dwDispID,
VARTYPE vtProp, ...);
Parâmetros
dwDispID
Identifica a propriedade a ser definida.
vtProp
Especifica o tipo da propriedade que será definida. Para obter valores possíveis, consulte a seção Comentários para COleDispatchDriver::InvokeHelper.
...
Um único parâmetro do tipo especificado por vtProp.
Exemplo
void IMyComObject::SetString(DISPID dispid, LPCTSTR propVal)
{
SetProperty(dispid, VT_BSTR, propVal);
}
Confira também
CALCDRIV de exemplo do MFC
ACDUAL de exemplo do MFC
Gráfico da hierarquia
Classe CCmdTarget
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de