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:

• Primeiras etapas da Internet: monikers assíncronos

• Primeiras etapas da Internet: controles ActiveX

Hierarquia de herança

CObject

CFile

COleStreamFile

CMonikerFile

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 retorno

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 retorno

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 retorno

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 retorno

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 retorno

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 OnDataAvailable em uma determinada operação de associação.

• BSCF_INTERMEDIATEDATANOTIFICATION identifica uma chamada intermediária para OnDataAvailable em uma operação de associação.

• BSCF_LASTDATANOTIFICATION identifica a última chamada para OnDataAvailable em 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 retorno

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