Classe CAsyncMonikerFile

Fornece funcionalidade para o uso de nomes assíncronos nos controlos ActiveX (anteriormente controlos OLE).

Sintaxe

class CAsyncMonikerFile : public CMonikerFile

Membros

Construtores Públicos

Métodos Públicos

Métodos Protegidos

Observações

Derivado do CMonikerFile, que por sua vez é derivado do COleStreamFile, CAsyncMonikerFile utiliza a interface IMoniker para aceder a qualquer fluxo de dados de forma assíncrona, incluindo carregar ficheiros de forma assíncrona a partir de uma URL. Os ficheiros podem ser propriedades do caminho de dados dos controlos ActiveX.

Os nomes assíncronos são usados principalmente em aplicações com acesso à Internet e controlos ActiveX para proporcionar uma interface de utilizador responsiva durante as transferências de ficheiros. Um exemplo claro disto é a utilização do CDataPathProperty para fornecer propriedades assíncronas para controlos ActiveX. O CDataPathProperty objeto receberá repetidamente um callback para indicar a disponibilidade de novos dados durante um longo processo de troca de propriedades.

Para mais informações sobre como usar nomes assíncronos e controlos ActiveX em aplicações na Internet, consulte os seguintes artigos:

• Primeiros Passos na Internet: Monikers Assíncronos

• Primeiros Passos na Internet: Controlos ActiveX

Hierarquia de herança

CObject

CFile

Ficheiro COleStream

CMonikerFile

CAsyncMonikerFile

Requerimentos

Cabeçalho: afxole.h

CAsyncMonikerFile::CAsyncMonikerFile

Constrói um CAsyncMonikerFile objeto.

CAsyncMonikerFile();

Observações

Não cria a IBindHost interface. IBindHost é usado apenas se for fornecido na Open função membro.

Para uma descrição da IBindHost interface, veja o SDK do Windows.

CAsyncMonikerFicheiro::Fechar

Chame esta função para encerrar e libertar todos os recursos.

virtual void Close();

Observações

Pode ser chamado em ficheiros não abertos ou já fechados.

CAsyncMonikerFile::CreateBindStatusCallback

Cria um objeto COM que implementa IBindStatusCallback.

virtual IUnknown* CreateBindStatusCallback(IUnknown* pUnkControlling);

Parâmetros

pUnkControlando
Um apontador para o desconhecido controlador (o exterior IUnknown) ou NULL se não estiver a ser usada agregação.

Valor de retorno

Se pUnkControlling não for NULL, a função devolve um ponteiro para o interior IUnknown num novo objeto COM que suporta IBindStatusCallback. Se pUnkControlling for NULL, a função devolve um ponteiro para um IUnknown num novo objeto COM que suporta IBindStatusCallback.

Observações

CAsyncMonikerFile requer um objeto COM que implemente IBindStatusCallback. O MFC implementa tal objeto, e é agregado. Podes sobrescrever CreateBindStatusCallback para devolver o teu próprio objeto COM. O seu objeto COM pode agregar a implementação do MFC chamando CreateBindStatusCallback com o desconhecido controlador do seu objeto COM. Os objetos COM implementados usando o CCmdTarget suporte COM podem recuperar o desconhecido controlador usando CCmdTarget::GetControllingUnknown.

Alternativamente, o seu objeto COM pode delegar à implementação do MFC chamando CreateBindStatusCallback( NULL ).

CAsyncMonikerFile::Open calls CreateBindStatusCallback.

Para mais informações sobre nomes assíncronos e ligação assíncrona, consulte a interface IBindStatusCallback e How Asynchronous Binding and Storage Work. Para uma discussão sobre agregação, veja Agregação. Os três tópicos estão no SDK do Windows.

CAsyncMonikerFile::GetBindInfo

Chamado do cliente de um moniker assíncrono para indicar ao moniker assíncrono como quer vincular.

virtual DWORD GetBindInfo() const;

Valor de retorno

Recupera as definições para IBindStatusCallBack. Para uma descrição da IBindStatusCallback interface, veja o SDK do Windows.

Observações

A implementação padrão define a ligação como assíncrona, para usar um meio de armazenamento (um fluxo) e para usar o modelo de empurrar de dados. Sobrepõe esta função se quiseres alterar o comportamento do binding.

Uma razão para fazer isto seria ligar usando o modelo de data pull em vez do modelo data-push. Num modelo de extração de dados, o cliente gere a operação de binding, e o nome só fornece dados ao cliente quando é lido. Num modelo data-push, o nome gere a operação de ligação assíncrona e notifica continuamente o cliente sempre que há novos dados disponíveis.

CAsyncMonikerFile::GetBinding

Chame esta função para recuperar um ponteiro para a ligação de transferência assíncrona.

IBinding* GetBinding() const;

Valor de retorno

Um apontador para a IBinding interface fornecido quando a transferência assíncrona começa. Retorna NULL se, por qualquer motivo, a transferência não puder ser feita de forma assíncrona.

Observações

Isto permite controlar o processo de transferência de dados através da IBinding interface, por exemplo, com IBinding::Abort, IBinding::Pause, e IBinding::Resume.

Para uma descrição da IBinding interface, veja o SDK do Windows.

CAsyncMonikerFicheiro::GetFormatEtc

Chame esta função para recuperar o formato dos dados no fluxo.

FORMATETC* GetFormatEtc() const;

Valor de retorno

Um ponteiro para a estrutura do Windows, FORMAT, etc., para o fluxo atualmente aberto. Retorna NULL se o nome não tiver sido limitado, se não for assíncrono, ou se a operação assíncrona ainda não começou.

CAsyncMonikerFile::GetPriority

Chamada do cliente de um moniker assíncrono quando o processo de ligação começa a receber a prioridade dada ao thread para a operação de ligação.

virtual LONG GetPriority() const;

Valor de retorno

A prioridade em que a transferência assíncrona terá lugar. Uma das bandeiras padrão de prioridade de thread: 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. Consulte a função Windows SetThreadPriority para uma descrição destes valores.

Observações

GetPriority Não deve ser chamado diretamente. THREAD_PRIORITY_NORMAL é devolvido pela implementação padrão.

CAsyncMonikerFile::OnDataAvailable

Um nome assíncrono chama OnDataAvailable para fornecer dados ao cliente à medida que estes se tornam disponíveis, durante operações de ligação assíncrona.

virtual void OnDataAvailable(DWORD dwSize, DWORD bscfFlag);

Parâmetros

dwSize
A quantidade acumulada (em bytes) de dados disponíveis desde o início da ligação. Pode ser zero, indicando que a quantidade de dados não é relevante para a operação, ou que nenhuma quantidade específica 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 uma dada operação de lição.

• BSCF_INTERMEDIATEDATANOTIFICATION Identifica uma chamada intermédia para OnDataAvailable para uma operação de ligação.

• BSCF_LASTDATANOTIFICATION Identifica a última chamada para OnDataAvailable uma operação de ligação.

Observações

A implementação padrão desta função não faz nada. Veja o exemplo seguinte para um exemplo de implementação.

Example

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 apelido quando os recursos estão baixos.

virtual void OnLowResource();

Observações

A implementação padrão chama GetBinding( )-> Abort( ).

CAsyncMonikerFicheiro::OnProgress

Chamado repetidamente pelo nome para indicar o progresso atual desta operação de ligação, normalmente em intervalos razoáveis durante uma operação longa.

virtual void OnProgress(
    ULONG ulProgress,
    ULONG ulProgressMax,
    ULONG ulStatusCode,
    LPCTSTR szStatusText);

Parâmetros

ulProgress
Indica o progresso atual da operação de ligação em relação ao máximo esperado indicado no ulProgressMax.

ulProgressMax
Indica o valor máximo esperado do ulProgress durante a duração das chamadas para OnProgress esta operação.

ulStatusCode
Fornece informações adicionais sobre o progresso da operação de ligação. Os valores válidos são retirados da BINDSTATUS enumeração. Consulte Observações para possíveis valores.

szStatusText
Informação sobre o progresso atual, dependendo do valor do ulStatusCode. Consulte Observações para possíveis valores.

Observações

Os valores possíveis para ulStatusCode (e o szStatusText para cada valor) são:

CAsyncMonikerFile::OnStartBinding

Sobrepõe esta função nas tuas classes derivadas para realizar ações quando a ligação estiver a iniciar.

virtual void OnStartBinding();

Observações

Esta função é chamada de volta pelo nome. A implementação padrão não faz nada.

CAsyncMonikerFile::OnStopBinding

Chamado pelo nome no final da operação de ligação.

virtual void OnStopBinding(HRESULT hresult, LPCTSTR szError);

Parâmetros

hresult
Um HRESULT que é o valor de erro ou de aviso.

szErrort
Uma cadeia de caracteres que descreve o erro.

Observações

Substitua esta função para realizar ações quando a transferência for interrompida. Por defeito, a função liberta IBinding.

Para uma descrição da IBinding interface, veja o SDK do Windows.

CAsyncMonikerFicheiro::Open

Chame esta função membro para abrir um ficheiro de forma 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 um ficheiro a ser aberto assíncrono. O ficheiro pode ter qualquer URL ou nome válido.

pError
Um apontador para as exceções de ficheiros. Em caso de erro, será definido como a causa.

pMoniker
Um apontador para a interface IMonikerdo moniker assíncrono, 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 controlo pode usar este nome para vincular, mas este não é o nome que o controlo deve guardar.

pBindHost
Um apontador para a IBindHost interface que será usado para criar o nome a partir de um nome de caminho potencialmente relativo. Se o host de ligação for inválido ou não fornecer um moniker, a chamada passa por defeito a Open(lpszFileName,pError). Para uma descrição da IBindHost interface, veja o SDK do Windows.

pServiceProvider
Um apontador para a IServiceProvider interface. Se o fornecedor de serviços for inválido ou não fornecer o serviço para IBindHost, a chamada passa por defeito a Open(lpszFileName,pError).

pDesconhecido
Um apontador para a IUnknown interface. Se IServiceProvider for encontrado, a função consulta para IBindHost. Se o fornecedor de serviços for inválido ou não fornecer o serviço para IBindHost, a chamada passa por defeito a Open(lpszFileName,pError).

Valor de retorno

Diferente de zero se o ficheiro for aberto com sucesso; caso contrário, 0.

Observações

Esta chamada inicia o processo de ligação.

Pode usar uma URL ou um nome de ficheiro 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"));

Consulte também

Classe CMonikerFile
Gráfico de Hierarquia
Classe CMonikerFile
Classe de Propriedade CDataPath