Classe CBindStatusCallback

  • Artigo

Essa classe implementa a interface IBindStatusCallback.

Importante

Essa classe e os respectivos membros não podem ser usados em aplicativos executados no Windows Runtime.

Sintaxe

template <class T,
    int nBindFlags = BINDF_ASYNCHRONOUS | BINDF_ASYNCSTORAGE | BINDF_GETNEWESTVERSION | BINDF_NOWRITECACHE>
class ATL_NO_VTABLE CBindStatusCallback : public CComObjectRootEx <T ::_ThreadModel::ThreadModelNoCS>,
    public IBindStatusCallbackImpl<T>

Parâmetros

T
Sua classe que contém a função que será chamada à medida que os dados forem recebidos.

nBindFlags
Especifica os sinalizadores de associação retornados por GetBindInfo. A implementação padrão define a associação como assíncrona, recupera a versão mais recente dos dados/objeto e não armazena dados recuperados no cache de disco.

Membros

Construtores públicos

Nome Descrição
CBindStatusCallback::CBindStatusCallback O construtor .
CBindStatusCallback::~CBindStatusCallback O destruidor.

Métodos públicos

Nome Descrição
CBindStatusCallback::Download Método estático que inicia o processo de download, cria um objeto CBindStatusCallback e chama StartAsyncDownload.
CBindStatusCallback::GetBindInfo Chamado pelo moniker assíncrono para solicitar informações sobre o tipo de associação a ser criado.
CBindStatusCallback::GetPriority Chamado pelo moniker assíncrono para obter a prioridade da operação de associação. A implementação da ATL retorna E_NOTIMPL.
CBindStatusCallback::OnDataAvailable Chamado para fornecer dados ao seu aplicativo à medida que ele se torna disponível. Lê os dados e chama a função passada para ele para usar os dados.
CBindStatusCallback::OnLowResource Chamado quando os recursos estão baixos. A implementação da ATL retorna S_OK.
CBindStatusCallback::OnObjectAvailable Chamado pelo moniker assíncrono para passar um ponteiro de interface de objeto para seu aplicativo. A implementação da ATL retorna S_OK.
CBindStatusCallback::OnProgress Chamado para indicar o progresso no processo de download de dados. A implementação da ATL retorna S_OK.
CBindStatusCallback::OnStartBinding Chamada quando a associação é iniciada.
CBindStatusCallback::OnStopBinding Chamada quando a transferência de dados assíncrona é parada.
CBindStatusCallback::StartAsyncDownload Inicializa os bytes disponíveis e os bytes lidos para zero, cria um objeto de fluxo de tipo push de um URL e chama OnDataAvailable sempre que os dados estão disponíveis.

Membros de Dados Públicos

Nome Descrição
CBindStatusCallback::m_dwAvailableToRead O número de bytes disponíveis para leitura.
CBindStatusCallback::m_dwTotalRead O número total de bytes lidos.
CBindStatusCallback::m_pFunc Ponteiro para a chamada de função quando os dados estão disponíveis.
CBindStatusCallback::m_pT Ponteiro para o objeto que solicita a transferência de dados assíncrona.
CBindStatusCallback::m_spBindCtx Ponteiro para a interface IBindCtx para a operação de associação atual.
CBindStatusCallback::m_spBinding Ponteiro para a interface IBinding para a operação de associação atual.
CBindStatusCallback::m_spMoniker Ponteiro para a interface IMoniker para o URL a ser usado.
CBindStatusCallback::m_spStream Ponteiro para a interface IStream para a transferência de dados.

Comentários

A classe CBindStatusCallback implementa a interface IBindStatusCallback. IBindStatusCallback deve ser implementado por seu aplicativo para que ele possa receber notificações de uma transferência de dados assíncrona. O moniker assíncrono fornecido pelo sistema usa métodos IBindStatusCallback para enviar e receber informações sobre a transferência de dados assíncrona de e para o objeto.

Normalmente, o objeto CBindStatusCallback está associado a uma operação de associação específica. Por exemplo, na amostra ASYNC, quando você define a propriedade URL, ela cria um objeto CBindStatusCallback na chamada para Download:

STDMETHOD(put_URL)(BSTR newVal)
{
   HRESULT hResult = E_UNEXPECTED;

   ATLTRACE(_T("IATLAsync::put_URL\n"));
   m_bstrURL = newVal;

   if (::IsWindow(m_EditCtrl.m_hWnd))
   {
      ::SendMessage(m_EditCtrl.m_hWnd, WM_SETTEXT, 0,  (LPARAM)_T(""));
      hResult = CBindStatusCallback<CATLAsync>::Download(this, &CATLAsync::OnData, 
         m_bstrURL, m_spClientSite, FALSE);
   }

   return hResult;
}

O moniker assíncrono usa a função de retorno de chamada OnData para chamar seu aplicativo quando ele tem dados. O moniker assíncrono é fornecido pelo sistema.

Hierarquia de herança

CComObjectRootBase

IBindStatusCallback

CComObjectRootEx

CBindStatusCallback

Requisitos

Cabeçalho: atlctl.h

CBindStatusCallback::CBindStatusCallback

O construtor .

CBindStatusCallback();

Comentários

Cria um objeto para receber notificações sobre a transferência de dados assíncrona. Normalmente, um objeto é criado para cada operação de associação.

O construtor também inicializa m_pT e m_pFunc para NULL.

CBindStatusCallback::~CBindStatusCallback

O destruidor.

~CBindStatusCallback();

Comentários

Libera todos os recursos alocados.

CBindStatusCallback::Download

Cria um objeto CBindStatusCallback e chama StartAsyncDownload para começar o download de dados de modo assíncrono do URL especificado.

static HRESULT Download(
    T* pT,
    ATL_PDATAAVAILABLE pFunc,
    BSTR bstrURL,
    IUnknown* pUnkContainer = NULL,
    BOOL bRelative = FALSE);

Parâmetros

pT
[in] Um ponteiro para o objeto que solicita a transferência de dados assíncrona. O objeto CBindStatusCallback é modelado na classe deste objeto.

pFunc
[in] Um ponteiro para a função que recebe os dados lidos. A função é um membro da classe de tipo T do objeto. Consulte StartAsyncDownload para obter sintaxe e um exemplo.

bstrURL
[in] O URL do qual obter dados. Pode ser qualquer URL ou nome de arquivo válido. Não pode ser NULL. Por exemplo:

CComBSTR mybstr =_T("http://somesite/data.htm")

pUnkContainer
[in] O IUnknown do contêiner. NULL por padrão.

bRelative
[in] Um sinalizador que indica se o URL é relativo ou absoluto. FALSE por padrão, o que significa que o URL é absoluto.

Valor de Devolução

Um dos valores HRESULT padrão.

Comentários

Toda vez que os dados estão disponíveis, eles são enviados para o objeto por meio de OnDataAvailable. OnDataAvailable lê os dados e chama a função apontada por pFunc (por exemplo, para armazenar os dados ou imprimi-los na tela).

CBindStatusCallback::GetBindInfo

Chamado para informar ao moniker como associar.

STDMETHOD(GetBindInfo)(
    DWORD* pgrfBSCF,
    BINDINFO* pbindinfo);

Parâmetros

pgrfBSCF
[out] Um ponteiro para valores de enumeração BINDF que indicam como a operação de associação deve ocorrer. Por padrão, defina com os seguintes valores de enumeração:

Download assíncrono BINDF_ASYNCHRONOUS.

OnDataAvailable BINDF_ASYNCSTORAGE retorna E_PENDING quando os dados ainda não estão disponíveis em vez de bloquear até que os dados estejam disponíveis.

A operação de associar BINDF_GETNEWESTVERSION deve recuperar a versão mais recente dos dados.

A operação de associar BINDF_NOWRITECACHE não deve armazenar dados recuperados no cache de disco.

pbindinfo
[in, out] Um ponteiro para a estrutura BINDINFO que fornece mais informações sobre como o objeto deseja que a associação ocorra.

Valor de Devolução

Um dos valores HRESULT padrão.

Comentários

A implementação padrão define a associação como assíncrona e o uso do modelo de push de dados. 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.

CBindStatusCallback::GetPriority

Chamado pelo moniker assíncrono para obter a prioridade da operação de associação.

STDMETHOD(GetPriority)(LONG* pnPriority);

Parâmetros

pnPriority
[out] Endereço da variável LONG que, com êxito, recebe a prioridade.

Valor de Devolução

Retorna E_NOTIMPL.

CBindStatusCallback::m_dwAvailableToRead

Pode ser usado para armazenar o número de bytes disponíveis para leitura.

DWORD m_dwAvailableToRead;

Comentários

Inicializado como zero em StartAsyncDownload.

CBindStatusCallback::m_dwTotalRead

O total cumulativo de bytes lidos na transferência de dados assíncrona.

DWORD m_dwTotalRead;

Comentários

Incrementado sempre que OnDataAvailable é chamado pelo número de bytes realmente lidos. Inicializado como zero em StartAsyncDownload.

CBindStatusCallback::m_pFunc

A função apontada por m_pFunc é chamada por OnDataAvailable depois de ler os dados disponíveis (por exemplo, para armazenar os dados ou imprimi-los na tela).

ATL_PDATAAVAILABLE m_pFunc;

Comentários

A função apontada por m_pFunc um membro da classe do objeto e tem a seguinte sintaxe:

void Function_Name(
   CBindStatusCallback<T>* pbsc,
   BYTE* pBytes,
   DWORD dwSize
   );

CBindStatusCallback::m_pT

Um ponteiro para o objeto que solicita a transferência de dados assíncrona.

T* m_pT;

Comentários

O objeto CBindStatusCallback é modelado na classe deste objeto.

CBindStatusCallback::m_spBindCtx

Um ponteiro para uma interface IBindCtx que fornece acesso ao contexto de associação (um objeto que armazena informações sobre uma operação de associação de moniker específica).

CComPtr<IBindCtx> m_spBindCtx;

Comentários

Inicializado em StartAsyncDownload.

CBindStatusCallback::m_spBinding

Ponteiro para a interface IBinding para a operação de associação atual.

CComPtr<IBinding> m_spBinding;

Comentários

Inicializado em OnStartBinding e liberado em OnStopBinding.

CBindStatusCallback::m_spMoniker

Um ponteiro para a interface IMoniker para o URL a ser usado.

CComPtr<IMoniker> m_spMoniker;

Comentários

Inicializado em StartAsyncDownload.

CBindStatusCallback::m_spStream

Um ponteiro para a interface IStream para a operação de associação atual.

CComPtr<IStream> m_spStream;

Comentários

Inicializado em OnDataAvailable na estrutura STGMEDIUM quando o sinalizador BCSF é BCSF_FIRSTDATANOTIFICATION e liberado quando o sinalizador BCSF é BCSF_LASTDATANOTIFICATION.

CBindStatusCallback::OnDataAvailable

O moniker assíncrono fornecido pelo sistema chama OnDataAvailable para fornecer dados ao objeto conforme ele se torna disponível.

STDMETHOD(
    OnDataAvailable)(DWORD grfBSCF,
    DWORD dwSize,
    FORMATETC* /* pformatetc */,
    STGMEDIUM* pstgmed);

Parâmetros

grfBSCF
[in] Um valor de enumeração BSCF. Uma ou mais das seguintes opções: BSCF_FIRSTDATANOTIFICATION, BSCF_INTERMEDIARYDATANOTIFICATION ou BSCF_LASTDATANOTIFICATION.

dwSize
[in] 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 ou que nenhum valor específico ficou disponível.

pformatetc
[in] Ponteiro para a estrutura FORMATETC que contém o formato dos dados disponíveis. Se não houver formato, poderá ser CF_NULL.

pstgmed
[in] Ponteiro para a estrutura STGMEDIUM que contém os dados reais agora disponíveis.

Valor de Devolução

Um dos valores HRESULT padrão.

Comentários

OnDataAvailable lê os dados e chama um método da classe do objeto (por exemplo, para armazenar os dados ou imprimi-los na tela). Consulte CBindStatusCallback::StartAsyncDownload para obter detalhes.

CBindStatusCallback::OnLowResource

Chamado quando os recursos estão baixos.

STDMETHOD(OnLowResource)(DWORD /* dwReserved */);

Parâmetros

dwReserved
Reservado.

Valor de Devolução

Returns S_OK.

CBindStatusCallback::OnObjectAvailable

Chamado pelo moniker assíncrono para passar um ponteiro de interface de objeto para seu aplicativo.

STDMETHOD(OnObjectAvailable)(REFID /* riid */, IUnknown* /* punk */);

Parâmetros

riid
O identificador de interface da interface solicitada. Não utilizado.

punk
Endereço da interface IUnknown. Não utilizado.

Valor de Devolução

Returns S_OK.

CBindStatusCallback::OnProgress

Chamado para indicar o progresso no processo de download de dados.

STDMETHOD(OnProgress)(
    ULONG /* ulProgress */,
    ULONG /* ulProgressMax */,
    ULONG /* ulStatusCode */,
    LPCWSTRONG /* szStatusText */);

Parâmetros

ulProgress
Inteiro longo não assinado. Não utilizado.

ulProgressMax
Inteiro longo não assinado não usado.

ulStatusCode
Inteiro longo não assinado. Não utilizado.

szStatusText
Endereço de um valor de cadeia de caracteres. Não utilizado.

Valor de Devolução

Returns S_OK.

CBindStatusCallback::OnStartBinding

Define o membro de dados m_spBinding para o ponteiro IBinding em pBinding.

STDMETHOD(OnStartBinding)(DWORD /* dwReserved */, IBinding* pBinding);

Parâmetros

dwReserved
Reservado para uso futuro.

pBinding
[in] Endereço da interface IBinding da operação de associação atual. Não pode ser NULL. O cliente deve chamar AddRef neste ponteiro para manter uma referência ao objeto de associação.

CBindStatusCallback::OnStopBinding

Libera o ponteiro IBinding no membro de dados m_spBinding.

STDMETHOD(OnStopBinding)(HRESULT hresult, LPCWSTR /* szError */);

Parâmetros

hresult
Código de status retornado da operação de associação.

szError
Endereço de um valor de cadeia de caracteres. Não utilizado.

Comentários

Chamado pelo moniker assíncrono fornecido pelo sistema para indicar o fim da operação de associação.

CBindStatusCallback::StartAsyncDownload

Inicia o download de dados de modo assíncrono do URL especificado.

HRESULT StartAsyncDownload(
    T* pT,
    ATL_PDATAAVAILABLE pFunc,
    BSTR bstrURL,
    IUnknown* pUnkContainer = NULL,
    BOOL bRelative = FALSE);

Parâmetros

pT
[in] Um ponteiro para o objeto que solicita a transferência de dados assíncrona. O objeto CBindStatusCallback é modelado na classe deste objeto.

pFunc
[in] Um ponteiro para a função que recebe os dados que estão sendo lidos. A função é um membro da classe de tipo T do objeto. Consulte Comentários para obter sintaxe e um exemplo.

bstrURL
[in] O URL do qual obter dados. Pode ser qualquer URL ou nome de arquivo válido. Não pode ser NULL. Por exemplo:

CComBSTR mybstr =_T("http://somesite/data.htm")

pUnkContainer
[in] O IUnknown do contêiner. NULL por padrão.

bRelative
[in] Um sinalizador que indica se o URL é relativo ou absoluto. FALSE por padrão, o que significa que o URL é absoluto.

Valor de Devolução

Um dos valores HRESULT padrão.

Comentários

Toda vez que os dados estão disponíveis, eles são enviados para o objeto por meio de OnDataAvailable. OnDataAvailable lê os dados e chama a função apontada por pFunc (por exemplo, para armazenar os dados ou imprimi-los na tela).

A função apontada por pFunc é um membro da classe do objeto e tem a seguinte sintaxe:

void Function_Name(
    CBindStatusCallback<T>* pbsc,
    BYTE* pBytes,
    DWORD dwSize);

No exemplo a seguir (obtido da amostra ASYNC), a função OnData grava os dados recebidos em uma caixa de texto.

Exemplo

void OnData(CBindStatusCallback<CATLAsync>* , BYTE* pBytes, DWORD /*cBytes*/)
{
   ATLTRACE(_T("OnData called\n"));

   m_bstrText.Append((LPCSTR)pBytes);
   if (::IsWindow(m_EditCtrl.m_hWnd))
   {
      USES_CONVERSION;
      _ATLTRY {
         ::SendMessage(m_EditCtrl.m_hWnd, WM_SETTEXT, 0, 
            (LPARAM)(LPCTSTR)COLE2CT((BSTR)m_bstrText));
      }
      _ATLCATCH( e ) {
         e; // unused
         // COLE2CT threw an exception!
         ::SendMessage(m_EditCtrl.m_hWnd, WM_SETTEXT, 0, 
            (LPARAM)_T("Could not allocate enough memory!!!"));
      }
   }
}

Confira também

Visão geral da classe