Classe CBindStatusCallback

Esta classe implementa a IBindStatusCallback interface.

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
A sua classe contém a função que será chamada à medida que os dados forem recebidos.

nBindFlags
Especifica os flags de ligação que são devolvidos pelo GetBindInfo. A implementação padrão define a ligação como assíncrona, recupera a versão mais recente dos dados/objetos e não armazena os dados recuperados na cache do disco.

Membros

Construtores Públicos

Métodos Públicos

Membros de Dados Públicos

Observações

A classe CBindStatusCallback implementa a interface IBindStatusCallback. IBindStatusCallback deve ser implementado pela sua aplicação para que possa receber notificações de uma transferência de dados assíncrona. A designação assíncrona fornecida pelo sistema utiliza IBindStatusCallback métodos para enviar e receber informações sobre a transferência de dados assíncronas para e do seu objecto.

Normalmente, o CBindStatusCallback objeto está associado a uma operação específica de ligação. Por exemplo, no exemplo ASYNC , quando defines a propriedade URL, cria-se um CBindStatusCallback objeto 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 nome assíncrono utiliza a função OnData de callback para chamar a sua aplicação quando esta tem dados. O nome assíncrono é fornecido pelo sistema.

Hierarquia de herança

CComObjectRootBase

IBindStatusCallback

CComObjectRootEx

CBindStatusCallback

Requerimentos

Cabeçalho: atlctl.h

CBindStatusCallback::CBindStatusCallback

O construtor.

CBindStatusCallback();

Observações

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

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

CBindStatusCallback::~CBindStatusCallback

O destruidor.

~CBindStatusCallback();

Observações

Liberta todos os recursos alocados.

CBindStatusCallback::D ownload

Cria um CBindStatusCallback objeto e chama StartAsyncDownload para começar a descarregar dados de forma assíncrona a partir da URL especificada.

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

Parâmetros

pT
[dentro] Um ponteiro para o objeto que solicita a transferência assíncrona de dados. O CBindStatusCallback objeto está templatizado na classe desse objeto.

pFunc
[dentro] Um apontador para a função que recebe os dados que são lidos. A função é um membro da classe do seu objeto de tipo T. Veja StartAsyncDownload para sintaxe e um exemplo.

bstrURL
[dentro] A URL para obter dados. Pode ser qualquer URL ou nome de ficheiro válido. Não pode ser NULL. Por exemplo:

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

pUnkContainer
[dentro] O IUnknown do contentor. NULL por defeito.

bRelativo
[dentro] Uma bandeira que indica se a URL é relativa ou absoluta. FALSE por defeito, o que significa que a URL é absoluta.

Valor de retorno

Um dos valores padrão do HRESULT.

Observações

Sempre que há dados disponíveis, estes são enviados ao objeto através de OnDataAvailable. OnDataAvailable lê os dados e chama a função apontada pelo pFunc (por exemplo, para armazenar os dados ou imprimi-los no ecrã).

CBindStatusCallback::GetBindInfo

Liguei para dizer ao nome como se deve encadernar.

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

Parâmetros

pgrfBSCF
[fora] Um apontador para valores de enumeração BINDF que indicam como a operação de ligação deve ocorrer. Por defeito, defina com os seguintes valores de enumeração:

BINDF_ASYNCHRONOUS Download assíncrono.

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

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

BINDF_NOWRITECACHE A operação de ligação não deve armazenar os dados recuperados na cache do disco.

pbindinfo
[inspira, expira] Um apontador para a BINDINFO estrutura que dá mais informações sobre como o objeto quer que a ligação ocorra.

Valor de retorno

Um dos valores padrão do HRESULT.

Observações

A implementação padrão define a ligação como assíncrona e para usar o modelo de empurrar de dados. No 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.

CBindStatusCallback::GetPriority

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

STDMETHOD(GetPriority)(LONG* pnPriority);

Parâmetros

pnPriority
[fora] Endereço da variável LONG que, em caso de sucesso, recebe a prioridade.

Valor de retorno

Devolve E_NOTIMPL.

CBindStatusCallback::m_dwAvailableToRead

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

DWORD m_dwAvailableToRead;

Observações

Inicializado a zero em StartAsyncDownload.

CBindStatusCallback::m_dwTotalRead

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

DWORD m_dwTotalRead;

Observações

Incrementado cada vez OnDataAvailable é chamado pelo número de bytes realmente lidos. Inicializado a 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 no ecrã).

ATL_PDATAAVAILABLE m_pFunc;

Observações

A função apontada por m_pFunc é um membro da classe do seu 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 assíncrona de dados.

T* m_pT;

Observações

O CBindStatusCallback objeto está templatizado na classe desse objeto.

CBindStatusCallback::m_spBindCtx

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

CComPtr<IBindCtx> m_spBindCtx;

Observações

Inicializado em StartAsyncDownload.

CBindStatusCallback::m_spBinding

Um apontador para a IBinding interface da operação de ligação atual.

CComPtr<IBinding> m_spBinding;

Observações

Inicializado em OnStartBinding e libertado em OnStopBinding.

CBindStatusCallback::m_spMoniker

Um apontador para a interface IMoniker para o URL usar.

CComPtr<IMoniker> m_spMoniker;

Observações

Inicializado em StartAsyncDownload.

CBindStatusCallback::m_spStream

Um apontador para a interface IStream da operação de ligação atual.

CComPtr<IStream> m_spStream;

Observações

Inicializada a OnDataAvailable partir da STGMEDIUM estrutura quando a bandeira da BCSF é BCSF_FIRSTDATANOTIFICATION e libertada quando a bandeira da BCSF é BCSF_LASTDATANOTIFICATION.

CBindStatusCallback::OnDataDisponível

O nome assíncrono fornecido pelo sistema chama OnDataAvailable para fornecer dados ao objeto à medida que estes se tornam disponíveis.

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

Parâmetros

grfBSCF
[dentro] Um valor de enumeração BSCF. Um ou mais dos seguintes: BSCF_FIRSTDATANOTIFICATION, BSCF_INTERMEDIARYDATANOTIFICATION ou BSCF_LASTDATANOTIFICATION.

dwSize
[dentro] 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 ou que nenhuma quantidade específica ficou disponível.

pformatetc
[dentro] Apontador para a estrutura FORMATETC que contém o formato dos dados disponíveis. Se não houver formato, pode ser CF_NULL.

PSTGMED
[dentro] Apontador para a estrutura STGMEDIUM que contém os dados reais agora disponíveis.

Valor de retorno

Um dos valores padrão do HRESULT.

Observações

OnDataAvailable lê os dados e depois chama um método da classe do seu objeto (por exemplo, para armazenar os dados ou imprimi-los no ecrã). Consulte CBindStatusCallback::StartAsyncDownload para mais detalhes.

CBindStatusCallback::OnLowResource

Chamada quando os recursos estão baixos.

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

Parâmetros

dwReservado
Reservado.

Valor de retorno

Devolve S_OK.

CBindStatusCallback::OnObjectAvailable

Chamado pelo moniker assíncrono para passar um ponteiro de interface de objeto para a sua aplicação.

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

Parâmetros

riid
Identificador de interface da interface solicitada. Unused.

punk
Endereço da interface IUnknown. Unused.

Valor de retorno

Devolve S_OK.

CBindStatusCallback::OnProgress

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

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

Parâmetros

ulProgress
Inteiro longo sem sinal. Unused.

ulProgressMax
Inteiro longo sem sinal Não utilizado.

ulStatusCode
Inteiro longo sem sinal. Unused.

szStatusText
Endereço de um valor de cadeia. Unused.

Valor de retorno

Devolve S_OK.

CBindStatusCallback::OnStartBinding

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

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

Parâmetros

dwReservado
Reservado para uso futuro.

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

CBindStatusCallback::OnStopBinding

Liberta o IBinding ponteiro no membro de dados m_spBinding.

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

Parâmetros

hresult
Código de estado devolvido da operação de ligação.

szError
Endereço de um valor de cadeia. Unused.

Observações

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

CBindStatusCallback::StartAsyncDownload

Começa a descarregar dados de forma assíncrona a partir do URL especificado.

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

Parâmetros

pT
[dentro] Um ponteiro para o objeto que solicita a transferência assíncrona de dados. O CBindStatusCallback objeto está templatizado na classe desse objeto.

pFunc
[dentro] Um ponteiro para a função que recebe os dados a ser lidos. A função é um membro da classe do seu objeto de tipo T. Veja Observações para sintaxe e um exemplo.

bstrURL
[dentro] A URL para obter dados. Pode ser qualquer URL ou nome de ficheiro válido. Não pode ser NULL. Por exemplo:

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

pUnkContainer
[dentro] O IUnknown do contentor. NULL por defeito.

bRelativo
[dentro] Uma bandeira que indica se a URL é relativa ou absoluta. FALSE por defeito, o que significa que a URL é absoluta.

Valor de retorno

Um dos valores padrão do HRESULT.

Observações

Sempre que há dados disponíveis, estes são enviados ao objeto através de OnDataAvailable. OnDataAvailable lê os dados e chama a função apontada pelo pFunc (por exemplo, para armazenar os dados ou imprimi-los no ecrã).

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

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

No exemplo seguinte (retirado da amostra ASYNC ), a função OnData escreve os dados recebidos numa caixa de texto.

Example

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!!!"));
      }
   }
}

Consulte também

Visão geral da classe