Classe CAsyncMonikerFile
Fornece funcionalidade para o uso de monikers assíncronos em controles ActiveX (anteriormente, controles OLE).
Sintaxe
class CAsyncMonikerFile : public CMonikerFile
Membros
Construtores públicos
| Nome | Descrição |
|---|---|
| CAsyncMonikerFile::CAsyncMonikerFile | Constrói um objeto CAsyncMonikerFile. |
Métodos públicos
| Nome | Descrição |
|---|---|
| CAsyncMonikerFile::Close | Fecha e libera todos os recursos. |
| CAsyncMonikerFile::GetBinding | Recupera um ponteiro para a associação de transferência assíncrona. |
| CAsyncMonikerFile::GetFormatEtc | Recupera o formato dos dados no fluxo. |
| CAsyncMonikerFile::Open | Abre um arquivo de maneira assíncrona. |
Métodos protegidos
| Nome | Descrição |
|---|---|
| CAsyncMonikerFile::CreateBindStatusCallback | Cria um objeto COM que implementa IBindStatusCallback. |
| CAsyncMonikerFile::GetBindInfo | Chamado pela biblioteca do sistema OLE para solicitar informações sobre o tipo de associação a ser criado. |
| CAsyncMonikerFile::GetPriority | Chamado pela biblioteca do sistema OLE para obter a prioridade da associação. |
| CAsyncMonikerFile::OnDataAvailable | Chamado para fornecer dados conforme eles ficam disponíveis para o cliente durante operações de associação assíncrona. |
| CAsyncMonikerFile::OnLowResource | Chamado quando os recursos estão baixos. |
| CAsyncMonikerFile::OnProgress | Chamado para indicar o progresso no processo de download de dados. |
| CAsyncMonikerFile::OnStartBinding | Chamado quando a associação está iniciando. |
| CAsyncMonikerFile::OnStopBinding | Chamado quando a transferência assíncrona é interrompida. |
Comentários
Derivado de CMonikerFile, que por sua vez é derivado de COleStreamFile, CAsyncMonikerFile usa a interface IMoniker para acessar qualquer fluxo de dados de maneira assíncrona, incluindo o carregamento de arquivos de maneira assíncrona de uma URL. Os arquivos podem ser propriedades de caminho de dados (datapath) de controles ActiveX.
Os monikers assíncronos são usados principalmente em aplicativos habilitados para Internet e controles ActiveX para fornecer uma interface do usuário responsiva durante transferências de arquivos. Um exemplo primordial disso é o uso de CDataPathProperty para fornecer propriedades assíncronas a controles ActiveX. O objeto CDataPathProperty receberá repetidamente um retorno de chamada para indicar a disponibilidade de novos dados durante um longo processo de troca de propriedades.
Para obter mais informações sobre como usar monikers assíncronos e controles ActiveX em aplicativos da Internet, confira os seguintes artigos:
Hierarquia de herança
CAsyncMonikerFile
Requisitos
Cabeçalho: afxole.h
CAsyncMonikerFile::CAsyncMonikerFile
Constrói um objeto CAsyncMonikerFile.
CAsyncMonikerFile();
Comentários
Ele não cria a interface IBindHost. IBindHost será usado somente se você fornecê-lo na função membro Open.
Para obter uma descrição detalhada da interface IBindHost, consulte o SDK do Windows.
CAsyncMonikerFile::Close
Chame essa função para fechar e liberar todos os recursos.
virtual void Close();
Comentários
Pode ser chamado em arquivos não abertos ou já fechados.
CAsyncMonikerFile::CreateBindStatusCallback
Cria um objeto COM que implementa IBindStatusCallback.
virtual IUnknown* CreateBindStatusCallback(IUnknown* pUnkControlling);
Parâmetros
pUnkControlling
Um ponteiro para o controle desconhecido (o IUnknown externo) ou NULL se a agregação não estiver sendo usada.
Valor de Devolução
Se pUnkControlling não for NULL, a função retornará um ponteiro para o IUnknown interno em um novo objeto COM com suporte IBindStatusCallback. Se pUnkControlling for NULL, a função retornará um ponteiro para um IUnknown em um novo objeto COM com suporte IBindStatusCallback.
Comentários
CAsyncMonikerFile requer um objeto COM que implementa IBindStatusCallback. O MFC implementa um objeto como esse e é agregável. Você pode substituir CreateBindStatusCallback para retornar seu próprio objeto COM. Seu objeto COM pode agregar a implementação do MFC chamando CreateBindStatusCallback com o controle desconhecido do objeto COM. Objetos COM implementados usando o suporte COM CCmdTarget podem recuperar o controle desconhecido usando CCmdTarget::GetControllingUnknown.
Como alternativa, o objeto COM pode delegar à implementação do MFC chamando CreateBindStatusCallback( NULL ).
CAsyncMonikerFile::Open chama CreateBindStatusCallback.
Para obter mais informações sobre monikers assíncronos e associação assíncrona, consulte a interface IBindStatusCallback e Como funciona o armazenamento e a associação assíncrona. Para uma discussão sobre agregação, consulte Agregação. Todos os três tópicos estão no SDK do Windows.
CAsyncMonikerFile::GetBindInfo
Chamado do cliente de um moniker assíncrono para informar ao moniker assíncrono como quer associar.
virtual DWORD GetBindInfo() const;
Valor de Devolução
Recupera as configurações para IBindStatusCallBack. Para obter uma descrição detalhada da interface IBindStatusCallback, consulte o SDK do Windows.
Comentários
A implementação padrão define a associação como assíncrona, para usar um meio de armazenamento (um fluxo) e usar o modelo de push de dados. Substitua essa função caso você queira alterar o comportamento da associação.
Uma das razões para fazer isso seria associar o uso do modelo de pull de dados em vez do modelo de push de dados. Em um modelo de pull de dados, o cliente conduz a operação de associação e o moniker só fornece dados para o cliente quando ele é lido. Em um modelo de push de dados, o moniker conduz a operação de associação assíncrona e notifica continuamente o cliente sempre que novos dados ficam disponíveis.
CAsyncMonikerFile::GetBinding
Chame essa função para recuperar um ponteiro para a associação de transferência assíncrona.
IBinding* GetBinding() const;
Valor de Devolução
Um ponteiro para a interface IBinding fornecida quando a transferência assíncrona é iniciada. Retorna NULL se, por qualquer motivo, a transferência não puder ser feita de forma assíncrona.
Comentários
Isso permite controlar o processo de transferência de dados por meio da interface IBinding, por exemplo, com IBinding::Abort, IBinding::Pause e IBinding::Resume.
Para obter uma descrição detalhada da interface IBinding, consulte o SDK do Windows.
CAsyncMonikerFile::GetFormatEtc
Chame essa função para recuperar o formato dos dados no fluxo.
FORMATETC* GetFormatEtc() const;
Valor de Devolução
Um ponteiro para a estrutura do Windows FORMATETC do fluxo aberto no momento. Retorna NULL se o moniker não tiver sido associado, se não for assíncrono ou se a operação assíncrona não foi iniciada.
CAsyncMonikerFile::GetPriority
Chamado pelo cliente de um moniker assíncrono à medida que o processo de associação começa a receber a prioridade dada ao thread para a operação de associação.
virtual LONG GetPriority() const;
Valor de Devolução
A prioridade na qual a transferência assíncrona será realizada. Um dos sinalizadores de prioridade de thread padrão: THREAD_PRIORITY_ABOVE_NORMAL, THREAD_PRIORITY_BELOW_NORMAL, THREAD_PRIORITY_HIGHEST, THREAD_PRIORITY_IDLE, THREAD_PRIORITY_LOWEST, THREAD_PRIORITY_NORMAL e THREAD_PRIORITY_TIME_CRITICAL. Confira a função do Windows SetThreadPriority para ver uma descrição desses valores.
Comentários
GetPriority não deve ser chamado diretamente. THREAD_PRIORITY_NORMAL é retornado pela implementação padrão.
CAsyncMonikerFile::OnDataAvailable
Um moniker assíncrono chama OnDataAvailable para fornecer dados ao cliente à medida que ele fica disponível durante operações de associação assíncronas.
virtual void OnDataAvailable(DWORD dwSize, DWORD bscfFlag);
Parâmetros
dwSize
A quantidade cumulativa (em bytes) de dados disponíveis desde o início da associação. Pode ser zero, indicando que a quantidade de dados não é relevante para a operação ou que nenhum valor específico ficou disponível.
bscfFlag
Um valor de enumeração BSCF. Pode ser um ou mais dos seguintes valores:
BSCF_FIRSTDATANOTIFICATION identifica a primeira chamada para
OnDataAvailableem uma determinada operação de associação.BSCF_INTERMEDIATEDATANOTIFICATION identifica uma chamada intermediária para
OnDataAvailableem uma operação de associação.BSCF_LASTDATANOTIFICATION identifica a última chamada para
OnDataAvailableem uma operação de associação.
Comentários
A implementação padrão dessa função não faz nada. Confira o exemplo a seguir para ver uma implementação de exemplo.
Exemplo
void CMyMoniker::OnDataAvailable(DWORD dwSize, DWORD bscfFlag)
{
if ((bscfFlag & BSCF_FIRSTDATANOTIFICATION) != 0)
{
m_dwReadBefore = 0;
m_strText.Empty();
}
DWORD dwArriving = dwSize - m_dwReadBefore;
if (dwArriving > 0)
{
int nLen = m_strText.GetLength();
ASSERT((DWORD)nLen == m_dwReadBefore);
LPTSTR psz = m_strText.GetBuffer(nLen + dwArriving);
Read(psz + nLen, dwArriving);
m_strText.ReleaseBuffer(nLen + dwArriving);
m_dwReadBefore = dwSize;
}
}
CAsyncMonikerFile::OnLowResource
Chamado pelo moniker quando os recursos estão baixos.
virtual void OnLowResource();
Comentários
A implementação padrão chama GetBinding( )-> Abort( ).
CAsyncMonikerFile::OnProgress
Chamado pelo moniker repetidamente para indicar o progresso atual dessa operação de associação, normalmente em intervalos razoáveis durante uma operação demorada.
virtual void OnProgress(
ULONG ulProgress,
ULONG ulProgressMax,
ULONG ulStatusCode,
LPCTSTR szStatusText);
Parâmetros
ulProgress
Indica o progresso atual da operação de associação em relação ao máximo esperado indicado em ulProgressMax.
ulProgressMax
Indica o valor máximo esperado de ulProgress pela duração das chamadas para OnProgress nessa operação.
ulStatusCode
Fornece informações adicionais sobre o progresso da operação de associação. Os valores válidos são obtidos da enumeração BINDSTATUS. Consulte os Comentários para conhecer os valores possíveis.
szStatusText
Informações sobre o progresso atual, dependendo do valor de ulStatusCode. Consulte os Comentários para conhecer os valores possíveis.
Comentários
Os valores possíveis para ulStatusCode (e o szStatusText para cada valor) são:
| Valor | Descrição |
|---|---|
| BINDSTATUS_FINDINGRESOURCE | A operação de associação está encontrando o recurso que contém o objeto ou o armazenamento que está sendo associado. O szStatusText fornece o nome de exibição do recurso que está sendo pesquisado (por exemplo, "www.microsoft.com"). |
| BINDSTATUS_CONNECTING | A operação de associação está se conectando ao recurso que contém o objeto ou o armazenamento que está sendo associado. O szStatusText fornece o nome de exibição do recurso que está sendo conectado (por exemplo, um endereço IP). |
| BINDSTATUS_SENDINGREQUEST | A operação de associação está solicitando o objeto ou armazenamento que está sendo associado. O szStatusText fornece o nome de exibição do objeto (por exemplo, um nome de arquivo). |
| BINDSTATUS_REDIRECTING | A operação de associação foi redirecionada para um local de dados diferente. O szStatusText fornece o nome de exibição do novo local de dados. |
| BINDSTATUS_USINGCACHEDCOPY | A operação de associação está recuperando o objeto ou o armazenamento solicitado de uma cópia armazenada em cache. O szStatusText é NULL. |
| BINDSTATUS_BEGINDOWNLOADDATA | A operação de associação começou a receber o objeto ou o armazenamento que está sendo associado. O szStatusText fornece o nome de exibição do novo local de dados. |
| BINDSTATUS_DOWNLOADINGDATA | A operação de associação continua a receber o objeto ou o armazenamento que está sendo associado. O szStatusText fornece o nome de exibição do novo local de dados. |
| BINDSTATUS_ENDDOWNLOADDATA | A operação de associação terminou de receber o objeto ou o armazenamento que está sendo associado. O szStatusText fornece o nome de exibição do novo local de dados. |
| BINDSTATUS_CLASSIDAVAILABLE | Uma instância do objeto que está sendo associado está prestes a ser criada. O szStatusText fornece o CLSID do novo objeto no formato de cadeia de caracteres, oferecendo ao cliente a oportunidade de cancelar a operação de associação, se desejado. |
CAsyncMonikerFile::OnStartBinding
Substitua essa função nas classes derivadas para executar ações ao iniciar a associação.
virtual void OnStartBinding();
Comentários
Essa função é chamada de volta pelo moniker. A implementação padrão não tem ação.
CAsyncMonikerFile::OnStopBinding
Chamado pelo moniker no fim da operação de associação.
virtual void OnStopBinding(HRESULT hresult, LPCTSTR szError);
Parâmetros
hresult
Um HRESULT que é o valor de erro ou aviso.
szErrort
Uma cadeia de caracteres que descreve o erro.
Comentários
Substitua essa função para executar ações quando a transferência for interrompida. Por padrão, a função libera IBinding.
Para obter uma descrição detalhada da interface IBinding, consulte o SDK do Windows.
CAsyncMonikerFile::Open
Chame essa função membro para abrir um arquivo de maneira assíncrona.
virtual BOOL Open(
LPCTSTR lpszURL,
CFileException* pError = NULL);
virtual BOOL Open(
IMoniker* pMoniker,
CFileException* pError = NULL);
virtual BOOL Open(
LPCTSTR lpszURL,
IBindHost* pBindHost,
CFileException* pError = NULL);
virtual BOOL Open(
IMoniker* pMoniker,
IBindHost* pBindHost,
CFileException* pError = NULL);
virtual BOOL Open(
LPCTSTR lpszURL,
IServiceProvider* pServiceProvider,
CFileException* pError = NULL);
virtual BOOL Open(
IMoniker* pMoniker,
IServiceProvider* pServiceProvider,
CFileException* pError = NULL);
virtual BOOL Open(
LPCTSTR lpszURL,
IUnknown* pUnknown,
CFileException* pError = NULL);
virtual BOOL Open(
IMoniker* pMoniker,
IUnknown* pUnknown,
CFileException* pError = NULL);
Parâmetros
lpszURL
Um ponteiro para o arquivo a ser aberto de maneira assíncrona. O arquivo pode ser qualquer URL ou nome de arquivo válido.
pError
Um ponteiro para as exceções de arquivo. No caso de um erro, ele será definido como a causa.
pMoniker
Um ponteiro para a interface de moniker assíncrona IMoniker, um moniker preciso que é a combinação do próprio moniker do documento, que pode ser recuperado com IOleClientSite::GetMoniker(OLEWHICHMK_CONTAINER) e um moniker criado a partir do nome do caminho. O controle pode usar esse moniker para associar, mas esse não é o moniker que o controle deve salvar.
pBindHost
Um ponteiro para a interface IBindHost que será usada para criar o moniker a partir de um potencial nome de caminho relativo. Se o host de associação for inválido ou não fornecer um moniker, a chamada será o padrão Open(lpszFileName,pError). Para obter uma descrição detalhada da interface IBindHost, consulte o SDK do Windows.
pServiceProvider
Um ponteiro para a interface IServiceProvider. Se o provedor de serviços for inválido ou não fornecer o serviço para IBindHost, a chamada será o padrão Open(lpszFileName,pError).
pUnknown
Um ponteiro para a interface IUnknown. Se IServiceProvider for encontrado, a função consultará IBindHost. Se o provedor de serviços for inválido ou não fornecer o serviço para IBindHost, a chamada será o padrão Open(lpszFileName,pError).
Valor de Devolução
Não zero se o arquivo for aberto com êxito; caso contrário, 0.
Comentários
Essa chamada inicia o processo de associação.
Você pode usar uma URL ou um nome de arquivo para o parâmetro lpszURL. Por exemplo:
CMyMoniker *pMyMoniker = new CMyMoniker();
pMyMoniker->Open(_T("http://www.microsoft.com"));
- ou -
CMyMoniker *pMyMoniker = new CMyMoniker();
pMyMoniker->Open(_T("file:c:\\mydata.dat"));
Confira também
Classe CMonikerFile
Gráfico da hierarquia
Classe CMonikerFile
Classe CDataPathProperty
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