Classe CBindStatusCallback

La classe implementa l'interfaccia IBindStatusCallback.

Sintassi

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>

Parametri

T
Classe contenente la funzione che verrà chiamata come vengono ricevuti i dati.

nBindFlags
Specifica i flag di associazione restituiti da GetBindInfo. L'implementazione predefinita imposta l'associazione come asincrona, recupera la versione più recente dell'oggetto/dati e non archivia i dati recuperati nella cache del disco.

Membri

Costruttori pubblici

Nome	Descrizione
CBindStatusCallback::CBindStatusCallback	Costruttore.
CBindStatusCallback::~CBindStatusCallback	Distruttore.

Metodi pubblici

Nome	Descrizione
CBindStatusCallback::D ownload	Metodo statico che avvia il processo di download, crea un CBindStatusCallback oggetto e chiama StartAsyncDownload.
CBindStatusCallback::GetBindInfo	Chiamato dal moniker asincrono per richiedere informazioni sul tipo di binding da creare.
CBindStatusCallback::GetPriority	Chiamato dal moniker asincrono per ottenere la priorità dell'operazione di associazione. L'implementazione ATL restituisce E_NOTIMPL.
CBindStatusCallback::OnDataAvailable	Chiamato per fornire i dati all'applicazione non appena diventa disponibile. Legge i dati, quindi chiama la funzione passata per usare i dati.
CBindStatusCallback::OnLowResource	Chiamato quando le risorse sono basse. L'implementazione ATL restituisce S_OK.
CBindStatusCallback::OnObjectAvailable	Chiamato dal moniker asincrono per passare un puntatore dell'interfaccia oggetto all'applicazione. L'implementazione ATL restituisce S_OK.
CBindStatusCallback::OnProgress	Chiamato per indicare lo stato di avanzamento di un processo di download dei dati. L'implementazione ATL restituisce S_OK.
CBindStatusCallback::OnStartBinding	Chiamato all'avvio dell'associazione.
CBindStatusCallback::OnStopBinding	Chiamato quando il trasferimento asincrono dei dati viene arrestato.
CBindStatusCallback::StartAsyncDownload	Inizializza i byte disponibili e i byte letti su zero, crea un oggetto flusso di tipo push da un URL e chiama OnDataAvailable ogni volta che sono disponibili i dati.

Membri dati pubblici

Nome	Descrizione
CBindStatusCallback::m_dwAvailableToRead	Numero di byte disponibili per la lettura.
CBindStatusCallback::m_dwTotalRead	Numero totale di byte letti.
CBindStatusCallback::m_pFunc	Puntatore alla funzione chiamata quando i dati sono disponibili.
CBindStatusCallback::m_pT	Puntatore all'oggetto che richiede il trasferimento asincrono dei dati.
CBindStatusCallback::m_spBindCtx	Puntatore all'interfaccia IBindCtx per l'operazione di associazione corrente.
CBindStatusCallback::m_spBinding	Puntatore all'interfaccia per l'operazione IBinding di associazione corrente.
CBindStatusCallback::m_spMoniker	Puntatore all'interfaccia IMoniker per l'URL da usare.
CBindStatusCallback::m_spStream	Puntatore all'interfaccia IStream per il trasferimento dei dati.

Osservazioni:

La classe CBindStatusCallback implementa l'interfaccia IBindStatusCallback. IBindStatusCallback deve essere implementato dall'applicazione in modo che possa ricevere notifiche da un trasferimento asincrono dei dati. Il moniker asincrono fornito dal sistema usa IBindStatusCallback metodi per inviare e ricevere informazioni sul trasferimento asincrono dei dati da e verso l'oggetto.

In genere, l'oggetto CBindStatusCallback è associato a un'operazione di associazione specifica. Nell'esempio ASYNC , ad esempio, quando si imposta la proprietà URL, viene creato un CBindStatusCallback oggetto nella chiamata a 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;
}

Il moniker asincrono usa la funzione OnData di callback per chiamare l'applicazione quando contiene dati. Il moniker asincrono viene fornito dal sistema.

Gerarchia di ereditarietà

CComObjectRootBase

IBindStatusCallback

CComObjectRootEx

CBindStatusCallback

Requisiti

Intestazione: atlctl.h

CBindStatusCallback::CBindStatusCallback

Costruttore.

CBindStatusCallback();

Osservazioni:

Crea un oggetto per ricevere notifiche relative al trasferimento asincrono dei dati. In genere, viene creato un oggetto per ogni operazione di associazione.

Il costruttore inizializza anche m_pT e m_pFunc su NULL.

CBindStatusCallback::~CBindStatusCallback

Distruttore.

~CBindStatusCallback();

Osservazioni:

Libera tutte le risorse allocate.

CBindStatusCallback::D ownload

Crea un CBindStatusCallback oggetto e chiama StartAsyncDownload per iniziare a scaricare i dati in modo asincrono dall'URL specificato.

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

Parametri

Pt
[in] Puntatore all'oggetto che richiede il trasferimento asincrono dei dati. L'oggetto CBindStatusCallback viene templatizzato nella classe dell'oggetto.

pFunc
[in] Puntatore alla funzione che riceve i dati letti. La funzione è un membro della classe dell'oggetto di tipo T. Vedere StartAsyncDownload per la sintassi e un esempio.

bstrURL
[in] URL da cui ottenere i dati. Può essere qualsiasi URL o nome file valido. Non può essere NULL. Ad esempio:

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

pUnkContainer
[in] Oggetto IUnknown del contenitore. NULL per impostazione predefinita.

bRelative
[in] Flag che indica se l'URL è relativo o assoluto. FALSE per impostazione predefinita, ovvero l'URL è assoluto.

Valore restituito

Uno dei valori HRESULT standard.

Osservazioni:

Ogni volta che i dati sono disponibili, vengono inviati all'oggetto tramite OnDataAvailable. OnDataAvailable legge i dati e chiama la funzione a cui punta pFunc , ad esempio per archiviare i dati o stamparli sullo schermo.

CBindStatusCallback::GetBindInfo

Chiamato per indicare al moniker come eseguire l'associazione.

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

Parametri

pgrfBSCF
[out] Puntatore ai valori di enumerazione BINDF che indicano come deve verificarsi l'operazione di associazione. Per impostazione predefinita, impostare con i valori di enumerazione seguenti:

BINDF_ASYNCHRONOUS download asincrono.

OnDataAvailable BINDF_ASYNCSTORAGE restituisce E_PENDING quando i dati non sono ancora disponibili anziché bloccarli finché i dati non sono disponibili.

BINDF_GETNEWESTVERSION L'operazione di associazione deve recuperare la versione più recente dei dati.

BINDF_NOWRITECACHE L'operazione di associazione non deve archiviare i dati recuperati nella cache del disco.

pbindinfo
[in, out] Puntatore alla BINDINFO struttura che fornisce altre informazioni sul modo in cui l'oggetto desidera che si verifichi l'associazione.

Valore restituito

Uno dei valori HRESULT standard.

Osservazioni:

L'implementazione predefinita imposta l'associazione come asincrona e per l'uso del modello di push dei dati. Nel modello di push dei dati il moniker determina l'operazione di associazione asincrona e invia continuamente una notifica al client ogni volta che sono disponibili nuovi dati.

CBindStatusCallback::GetPriority

Chiamato dal moniker asincrono per ottenere la priorità dell'operazione di associazione.

STDMETHOD(GetPriority)(LONG* pnPriority);

Parametri

pnPriority
[out] Indirizzo della variabile LONG che, in caso di esito positivo, riceve la priorità.

Valore restituito

Restituisce E_NOTIMPL.

CBindStatusCallback::m_dwAvailableToRead

Può essere usato per archiviare il numero di byte disponibili per la lettura.

DWORD m_dwAvailableToRead;

Osservazioni:

Inizializzato su zero in StartAsyncDownload.

CBindStatusCallback::m_dwTotalRead

Totale cumulativo di byte letti nel trasferimento asincrono dei dati.

DWORD m_dwTotalRead;

Osservazioni:

Incrementato ogni volta OnDataAvailable che viene chiamato dal numero di byte effettivamente letti. Inizializzato su zero in StartAsyncDownload.

CBindStatusCallback::m_pFunc

La funzione a m_pFunc cui punta viene chiamata da OnDataAvailable dopo aver letto i dati disponibili, ad esempio per archiviare i dati o stamparli sullo schermo.

ATL_PDATAAVAILABLE m_pFunc;

Osservazioni:

La funzione a m_pFunc cui punta è un membro della classe dell'oggetto e ha la sintassi seguente:

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

CBindStatusCallback::m_pT

Puntatore all'oggetto che richiede il trasferimento asincrono dei dati.

T* m_pT;

Osservazioni:

L'oggetto CBindStatusCallback viene templatizzato nella classe dell'oggetto.

CBindStatusCallback::m_spBindCtx

Puntatore a un'interfaccia IBindCtx che fornisce l'accesso al contesto di associazione (un oggetto che archivia informazioni su un'operazione di associazione moniker specifica).

CComPtr<IBindCtx> m_spBindCtx;

Osservazioni:

Inizializzato in StartAsyncDownload.

CBindStatusCallback::m_spBinding

Puntatore all'interfaccia IBinding dell'operazione di associazione corrente.

CComPtr<IBinding> m_spBinding;

Osservazioni:

Inizializzato in OnStartBinding e rilasciato in OnStopBinding.

CBindStatusCallback::m_spMoniker

Puntatore all'interfaccia IMoniker per l'URL da usare.

CComPtr<IMoniker> m_spMoniker;

Osservazioni:

Inizializzato in StartAsyncDownload.

CBindStatusCallback::m_spStream

Puntatore all'interfaccia IStream dell'operazione di associazione corrente.

CComPtr<IStream> m_spStream;

Osservazioni:

Inizializzato in OnDataAvailable dalla STGMEDIUM struttura quando il flag BCSF viene BCSF_FIRSTDATANOTIFICATION e rilasciato quando il flag BCSF è BCSF_LASTDATANOTIFICATION.

CBindStatusCallback::OnDataAvailable

Il moniker asincrono fornito dal sistema chiama OnDataAvailable per fornire dati all'oggetto non appena diventa disponibile.

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

Parametri

grfBSCF
[in] Valore di enumerazione BSCF. Una o più delle opzioni seguenti: BSCF_FIRSTDATANOTIFICATION, BSCF_INTERMEDIARYDATANOTIFICATION o BSCF_LASTDATANOTIFICATION.

dwSize
[in] Quantità cumulativa (in byte) di dati disponibili dall'inizio dell'associazione. Può essere zero, a indicare che la quantità di dati non è rilevante o che non è stata resa disponibile alcuna quantità specifica.

pformatetc
[in] Puntatore alla struttura FORMATETC che contiene il formato dei dati disponibili. Se non è presente alcun formato, può essere CF_NULL.

pstgmed
[in] Puntatore alla struttura STGMEDIUM che contiene i dati effettivi ora disponibili.

Valore restituito

Uno dei valori HRESULT standard.

Osservazioni:

OnDataAvailable legge i dati, quindi chiama un metodo della classe dell'oggetto (ad esempio, per archiviare i dati o stamparli sullo schermo). Per informazioni dettagliate, vedere CBindStatusCallback::StartAsyncDownload .

CBindStatusCallback::OnLowResource

Chiamato quando le risorse sono basse.

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

Parametri

dwReserved
Riservato.

Valore restituito

Restituisce S_OK.

CBindStatusCallback::OnObjectAvailable

Chiamato dal moniker asincrono per passare un puntatore dell'interfaccia oggetto all'applicazione.

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

Parametri

riid
Identificatore di interfaccia dell'interfaccia richiesta. Non utilizzato.

Punk
Indirizzo dell'interfaccia IUnknown. Non utilizzato.

Valore restituito

Restituisce S_OK.

CBindStatusCallback::OnProgress

Chiamato per indicare lo stato di avanzamento di un processo di download dei dati.

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

Parametri

ulProgress
Intero long senza segno. Non utilizzato.

ulProgressMax
Intero long senza segno inutilizzato.

ulStatusCode
Intero long senza segno. Non utilizzato.

szStatusText
Indirizzo di un valore stringa. Non utilizzato.

Valore restituito

Restituisce S_OK.

CBindStatusCallback::OnStartBinding

Imposta il membro dati m_spBinding sul IBinding puntatore in pBinding.

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

Parametri

dwReserved
Riservato a un uso futuro.

pBinding
[in] Indirizzo dell'interfaccia IBinding dell'operazione di associazione corrente. Non può essere NULL. Il client deve chiamare AddRef su questo puntatore per mantenere un riferimento all'oggetto di associazione.

CBindStatusCallback::OnStopBinding

Rilascia il IBinding puntatore nel membro dati m_spBinding.

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

Parametri

hresult
Codice di stato restituito dall'operazione di associazione.

szError
Indirizzo di un valore stringa. Non utilizzato.

Osservazioni:

Chiamato dal moniker asincrono fornito dal sistema per indicare la fine dell'operazione di associazione.

CBindStatusCallback::StartAsyncDownload

Avvia il download asincrono dei dati dall'URL specificato.

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

Parametri

Pt
[in] Puntatore all'oggetto che richiede il trasferimento asincrono dei dati. L'oggetto CBindStatusCallback viene templatizzato nella classe dell'oggetto.

pFunc
[in] Puntatore alla funzione che riceve i dati letti. La funzione è un membro della classe dell'oggetto di tipo T. Vedere La sezione Osservazioni per la sintassi e un esempio.

bstrURL
[in] URL da cui ottenere i dati. Può essere qualsiasi URL o nome file valido. Non può essere NULL. Ad esempio:

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

pUnkContainer
[in] Oggetto IUnknown del contenitore. NULL per impostazione predefinita.

bRelative
[in] Flag che indica se l'URL è relativo o assoluto. FALSE per impostazione predefinita, ovvero l'URL è assoluto.

Valore restituito

Uno dei valori HRESULT standard.

Osservazioni:

Ogni volta che i dati sono disponibili, vengono inviati all'oggetto tramite OnDataAvailable. OnDataAvailable legge i dati e chiama la funzione a cui punta pFunc , ad esempio per archiviare i dati o stamparli sullo schermo.

La funzione a cui punta pFunc è un membro della classe dell'oggetto e ha la sintassi seguente:

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

Nell'esempio seguente (tratto dall'esempio ASYNC ), la funzione OnData scrive i dati ricevuti in una casella di testo.

Esempio

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

Vedi anche

Cenni preliminari sulla classe