Classe CAsyncMonikerFile

  • Articolo

Fornisce la funzionalità per l'utilizzo di moniker asincroni in controlli ActiveX (precedentemente controlli OLE).

Sintassi

class CAsyncMonikerFile : public CMonikerFile

Membri

Costruttori pubblici

Nome Descrizione
CAsyncMonikerFile::CAsyncMonikerFile Costruisce un oggetto CAsyncMonikerFile.

Metodi pubblici

Nome Descrizione
CAsyncMonikerFile::Close Chiude e rilascia tutte le risorse.
CAsyncMonikerFile::GetBinding Recupera un puntatore all'associazione di trasferimento asincrona.
CAsyncMonikerFile::GetFormatEtc Recupera il formato dei dati nel flusso.
CAsyncMonikerFile::Open Apre un file in modo asincrono.

Metodi protetti

Nome Descrizione
CAsyncMonikerFile::CreateBindStatusCallback Crea un oggetto COM che implementa IBindStatusCallback.
CAsyncMonikerFile::GetBindInfo Chiamato dalla libreria di sistema OLE per richiedere informazioni sul tipo di associazione da creare.
CAsyncMonikerFile::GetPriority Chiamato dalla libreria di sistema OLE per ottenere la priorità dell'associazione.
CAsyncMonikerFile::OnDataAvailable Chiamato per fornire i dati man mano che diventano disponibili per il client durante le operazioni di associazione asincrone.
CAsyncMonikerFile::OnLowResource Chiamato quando le risorse sono basse.
CAsyncMonikerFile::OnProgress Chiamato per indicare lo stato di avanzamento del processo di download dei dati.
CAsyncMonikerFile::OnStartBinding Chiamato all'avvio dell'associazione.
CAsyncMonikerFile::OnStopBinding Chiamato quando il trasferimento asincrono viene arrestato.

Osservazioni:

Derivato da CMonikerFile, che a sua volta è derivato da COleStreamFile, CAsyncMonikerFile usa l'interfaccia IMoniker per accedere a qualsiasi flusso di dati in modo asincrono, incluso il caricamento asincrono dei file da un URL. I file possono essere proprietà del percorso dati dei controlli ActiveX.

I moniker asincroni vengono usati principalmente nelle applicazioni abilitate per Internet e nei controlli ActiveX per fornire un'interfaccia utente reattiva durante i trasferimenti di file. Un esempio principale di questo è l'uso di CDataPathProperty per fornire proprietà asincrone per i controlli ActiveX. L'oggetto CDataPathProperty otterrà ripetutamente un callback per indicare la disponibilità di nuovi dati durante un lungo processo di scambio di proprietà.

Per altre informazioni su come usare moniker asincroni e controlli ActiveX nelle applicazioni Internet, vedere gli articoli seguenti:

Gerarchia di ereditarietà

CObject

Cfile

COleStreamFile

CMonikerFile

CAsyncMonikerFile

Requisiti

Intestazione: afxole.h

CAsyncMonikerFile::CAsyncMonikerFile

Costruisce un oggetto CAsyncMonikerFile.

CAsyncMonikerFile();

Osservazioni:

Non crea l'interfaccia IBindHost . IBindHost viene usato solo se viene specificato nella Open funzione membro.

Per una descrizione dell'interfaccia IBindHost , vedere Windows SDK.

CAsyncMonikerFile::Close

Chiamare questa funzione per chiudere e rilasciare tutte le risorse.

virtual void Close();

Osservazioni:

Può essere chiamato su file non aperti o già chiusi.

CAsyncMonikerFile::CreateBindStatusCallback

Crea un oggetto COM che implementa IBindStatusCallback.

virtual IUnknown* CreateBindStatusCallback(IUnknown* pUnkControlling);

Parametri

pUnkControlling
Puntatore al controllo sconosciuto (esterno ) o NULL se l'aggregazione IUnknownnon viene usata.

Valore restituito

Se pUnkControlling non è NULL, la funzione restituisce un puntatore all'oggetto interno IUnknown in un nuovo oggetto COM che supporta IBindStatusCallback. Se pUnkControlling è NULL, la funzione restituisce un puntatore a un IUnknown oggetto in un nuovo oggetto COM che supporta IBindStatusCallback.

Osservazioni:

CAsyncMonikerFile richiede un oggetto COM che implementa IBindStatusCallback. MFC implementa tale oggetto ed è aggregabile. È possibile eseguire l'override CreateBindStatusCallback per restituire il proprio oggetto COM. L'oggetto COM può aggregare l'implementazione di MFC chiamando CreateBindStatusCallback con il controllo sconosciuto dell'oggetto COM. Gli oggetti COM implementati tramite il CCmdTarget supporto COM possono recuperare il controllo sconosciuto tramite CCmdTarget::GetControllingUnknown.

In alternativa, l'oggetto COM può delegare all'implementazione di MFC chiamando CreateBindStatusCallback( NULL ).

CAsyncMonikerFile::Open chiama CreateBindStatusCallback.

Per altre informazioni sui moniker asincroni e sull'associazione asincrona, vedere l'interfaccia IBindStatusCallback e How Asynchronous Binding e Archiviazione Work. Per una descrizione dell'aggregazione, vedere Aggregazione. Tutti e tre gli argomenti sono disponibili in Windows SDK.

CAsyncMonikerFile::GetBindInfo

Chiamato dal client di un moniker asincrono per indicare al moniker asincrono come vuole eseguire l'associazione.

virtual DWORD GetBindInfo() const;

Valore restituito

Recupera le impostazioni per IBindStatusCallBack. Per una descrizione dell'interfaccia IBindStatusCallback , vedere Windows SDK.

Osservazioni:

L'implementazione predefinita imposta l'associazione come asincrona, per usare un supporto di archiviazione (un flusso) e per usare il modello di push dei dati. Eseguire l'override di questa funzione se si vuole modificare il comportamento dell'associazione.

Un motivo per eseguire questa operazione sarebbe associare usando il modello di pull dei dati anziché il modello di push dei dati. In un modello di pull dei dati, il client guida l'operazione di associazione e il moniker fornisce solo i dati al client quando viene letto. In un modello di push dati il moniker determina l'operazione di associazione asincrona e invia continuamente una notifica al client ogni volta che sono disponibili nuovi dati.

CAsyncMonikerFile::GetBinding

Chiamare questa funzione per recuperare un puntatore all'associazione di trasferimento asincrona.

IBinding* GetBinding() const;

Valore restituito

Puntatore all'interfaccia fornita all'inizio del IBinding trasferimento asincrono. Restituisce NULL se per qualsiasi motivo il trasferimento non può essere eseguito in modo asincrono.

Osservazioni:

In questo modo è possibile controllare il processo di trasferimento dei dati tramite l'interfaccia IBinding , ad esempio con IBinding::Abort, IBinding::Pausee IBinding::Resume.

Per una descrizione dell'interfaccia IBinding , vedere Windows SDK.

CAsyncMonikerFile::GetFormatEtc

Chiamare questa funzione per recuperare il formato dei dati nel flusso.

FORMATETC* GetFormatEtc() const;

Valore restituito

Puntatore alla struttura di Windows FORMATETC per il flusso attualmente aperto. Restituisce NULL se il moniker non è stato associato, se non è asincrono o se l'operazione asincrona non è iniziata.

CAsyncMonikerFile::GetPriority

Chiamato dal client di un moniker asincrono quando il processo di associazione inizia a ricevere la priorità assegnata al thread per l'operazione di associazione.

virtual LONG GetPriority() const;

Valore restituito

Priorità in corrispondenza della quale verrà eseguito il trasferimento asincrono. Uno dei flag di priorità del thread standard: 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. Per una descrizione di questi valori, vedere la funzione Windows SetThreadPriority .

Osservazioni:

GetPriority non deve essere chiamato direttamente. THREAD_PRIORITY_NORMAL viene restituito dall'implementazione predefinita.

CAsyncMonikerFile::OnDataAvailable

Un moniker asincrono chiama OnDataAvailable per fornire dati al client non appena diventa disponibile, durante le operazioni di associazione asincrone.

virtual void OnDataAvailable(DWORD dwSize, DWORD bscfFlag);

Parametri

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

bscfFlag
Valore di enumerazione BSCF. Può essere uno o più dei valori seguenti:

  • BSCF_FIRSTDATANOTIFICATION Identifica la prima chiamata a OnDataAvailable per una determinata operazione di associazione.

  • BSCF_INTERMEDIATEDATANOTIFICATION Identifica una chiamata intermedia a OnDataAvailable per un'operazione di associazione.

  • BSCF_LASTDATANOTIFICATION Identifica l'ultima chiamata a OnDataAvailable per un'operazione di associazione.

Osservazioni:

L'implementazione predefinita di questa funzione non esegue alcuna operazione. Vedere l'esempio seguente per un'implementazione di esempio.

Esempio

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

Chiamato dal moniker quando le risorse sono basse.

virtual void OnLowResource();

Osservazioni:

L'implementazione predefinita chiama GetBinding( )-> Abort( ).

CAsyncMonikerFile::OnProgress

Chiamato ripetutamente dal moniker per indicare lo stato di avanzamento corrente di questa operazione di associazione, in genere a intervalli ragionevoli durante un'operazione lunga.

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

Parametri

ulProgress
Indica lo stato di avanzamento corrente dell'operazione di associazione rispetto al valore massimo previsto indicato in ulProgressMax.

ulProgressMax
Indica il valore massimo previsto di ulProgress per la durata delle chiamate a OnProgress per questa operazione.

ulStatusCode
Fornisce informazioni aggiuntive sullo stato di avanzamento dell'operazione di associazione. I valori validi vengono ricavati dall'enumerazione BINDSTATUS . Per i valori possibili, vedere la sezione Note.

szStatusText
Informazioni sullo stato di avanzamento corrente, a seconda del valore di ulStatusCode. Per i valori possibili, vedere la sezione Note.

Osservazioni:

I valori possibili per ulStatusCode (e szStatusText per ogni valore) sono:

Valore Descrizione
BINDSTATUS_FINDINGRESOURCE L'operazione di associazione trova la risorsa che contiene l'oggetto o l'archiviazione a cui è associato. SzStatusText fornisce il nome visualizzato della risorsa cercata, ad esempio "www.microsoft.com".
BINDSTATUS_CONNECTING L'operazione di associazione si connette alla risorsa a cui è associato l'oggetto o l'archiviazione. SzStatusText fornisce il nome visualizzato della risorsa a cui si è connessi, ad esempio un indirizzo IP.
BINDSTATUS_edizione Standard NDINGREQUEST L'operazione di associazione richiede l'associazione dell'oggetto o dell'archiviazione. SzStatusText fornisce il nome visualizzato dell'oggetto , ad esempio un nome file.
BINDSTATUS_REDIRECTING L'operazione di associazione è stata reindirizzata a un percorso di dati diverso. SzStatusText fornisce il nome visualizzato del nuovo percorso dati.
BINDSTATUS_USINGCACHEDCOPY L'operazione di associazione sta recuperando l'oggetto o l'archiviazione richiesti da una copia memorizzata nella cache. SzStatusText è NULL.
BINDSTATUS_BEGINDOWNLOADDATA L'operazione di associazione ha iniziato a ricevere l'oggetto o l'archiviazione a cui è associato. SzStatusText fornisce il nome visualizzato della posizione dei dati.
BINDSTATUS_DOWNLOADINGDATA L'operazione di associazione continua a ricevere l'oggetto o l'archiviazione a cui è associato. SzStatusText fornisce il nome visualizzato della posizione dei dati.
BINDSTATUS_ENDDOWNLOADDATA L'operazione di associazione ha terminato di ricevere l'oggetto o l'archiviazione a cui è associato. SzStatusText fornisce il nome visualizzato della posizione dei dati.
BINDSTATUS_CLASSIDAVAILABLE Un'istanza dell'oggetto a cui è associato sta per essere creata. SzStatusText fornisce il CLSID del nuovo oggetto in formato stringa, consentendo al client di annullare l'operazione di associazione, se necessario.

CAsyncMonikerFile::OnStartBinding

Eseguire l'override di questa funzione nelle classi derivate per eseguire azioni all'avvio dell'associazione.

virtual void OnStartBinding();

Osservazioni:

Questa funzione viene richiamata dal moniker. L'implementazione predefinita non esegue alcuna operazione.

CAsyncMonikerFile::OnStopBinding

Chiamato dal moniker alla fine dell'operazione di associazione.

virtual void OnStopBinding(HRESULT hresult, LPCTSTR szError);

Parametri

hresult
HRESULT che rappresenta il valore di errore o avviso.

szErrort
Stringa di caratteri che descrive l'errore.

Osservazioni:

Eseguire l'override di questa funzione per eseguire azioni quando il trasferimento viene arrestato. Per impostazione predefinita, la funzione rilascia IBinding.

Per una descrizione dell'interfaccia IBinding , vedere Windows SDK.

CAsyncMonikerFile::Open

Chiamare questa funzione membro per aprire un file in modo asincrono.

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);

Parametri

lpszURL
Puntatore al file da aprire in modo asincrono. Il file può essere qualsiasi URL o nome file valido.

pError
Puntatore alle eccezioni del file. In caso di errore, verrà impostato sulla causa.

pMoniker
Puntatore all'interfaccia IMonikerdel moniker asincrona , un moniker preciso che è la combinazione del moniker del documento, che è possibile recuperare con IOleClientSite::GetMoniker(OLEWHICHMK_CONTAINER)e un moniker creato dal nome del percorso. Il controllo può utilizzare questo moniker per eseguire l'associazione, ma questo non è il moniker che il controllo deve salvare.

pBindHost
Puntatore all'interfaccia IBindHost che verrà usata per creare il moniker da un pathname potenzialmente relativo. Se l'host di associazione non è valido o non fornisce un moniker, per impostazione predefinita la chiamata è Open(lpszFileName,pError). Per una descrizione dell'interfaccia IBindHost , vedere Windows SDK.

pServiceProvider
Puntatore all'interfaccia IServiceProvider. Se il provider di servizi non è valido o non riesce a fornire il servizio per IBindHost, per impostazione predefinita la chiamata a Open(lpszFileName,pError).

pUnknown
Puntatore all'interfaccia IUnknown. Se IServiceProvider viene trovato, la funzione esegue una query per IBindHost. Se il provider di servizi non è valido o non riesce a fornire il servizio per IBindHost, per impostazione predefinita la chiamata a Open(lpszFileName,pError).

Valore restituito

Diverso da zero se il file viene aperto correttamente; in caso contrario, 0.

Osservazioni:

Questa chiamata avvia il processo di associazione.

È possibile usare un URL o un nome file per il parametro lpszURL . Ad esempio:

CMyMoniker *pMyMoniker = new CMyMoniker();
pMyMoniker->Open(_T("http://www.microsoft.com"));

- oppure -

CMyMoniker *pMyMoniker = new CMyMoniker();
pMyMoniker->Open(_T("file:c:\\mydata.dat"));

Vedi anche

Classe CMonikerFile
Grafico della gerarchia
Classe CMonikerFile
Classe CDataPathProperty