implementazione del file IPropertyStorage-Compound
L'implementazione COM dell'architettura di archiviazione strutturata è denominata file composti. Gli oggetti di archiviazione implementati nei file composti includono un'implementazione di IPropertyStorage, l'interfaccia che gestisce un singolo set di proprietà persistenti e IPropertySetStorage, l'interfaccia che gestisce i gruppi di set di proprietà persistenti. Per altre informazioni sull'interfaccia IPropertyStorage, vedere Considerazioni su IPropertyStorage e Archiviazione delle proprietà.
Per ottenere un puntatore all'implementazione del file composto di IPropertyStorage, chiamare StgCreateStorageEx per creare un nuovo oggetto file composto o StgOpenStorageEx per aprire un oggetto file composto creato in precedenza. Nel caso di StgCreateStorageEx, il parametro stgfmt deve essere impostato su STGFMT_STORAGE. Nel caso di StgOpenStorageEx, il parametro stgfmt deve essere impostato su STGFMT_STORAGE o STGFMT_ANY. In entrambi i casi, il parametro riid deve essere impostato su IID_IPropertySetStorage. Entrambe le funzioni forniscono un puntatore all'interfaccia IPropertySetStorage . Chiamando il metodo Create o Open di tale interfaccia, si otterrà un puntatore all'interfaccia IPropertyStorage , che è possibile usare per chiamare uno dei relativi metodi.
Un modo alternativo per ottenere un puntatore all'implementazione del file composto di IPropertySetStorage consiste nel chiamare la funzione StgCreateDocfile e StgOpenStorage oppure per specificare un parametro riid di IID_IStorage alla funzione StgCreateStorageEx o StgOpenStorageEx . In entrambi i casi viene restituito un puntatore all'interfaccia IStorage dell'oggetto. Con set di proprietà persistenti, chiamare QueryInterface per l'interfaccia IPropertySetStorage , specificando il nome definito dall'intestazione per l'identificatore di interfaccia (IID) IID_IPropertySetStorage.
Utilizzo
Usare IPropertyStorage per gestire le proprietà all'interno di un singolo set di proprietà. I metodi supportano la lettura, la scrittura e l'eliminazione sia delle proprietà che dei nomi di stringa facoltativi che possono essere associati agli identificatori di proprietà. Altri metodi supportano le operazioni di commit standard e ripristinano le operazioni di archiviazione. Esiste anche un metodo che consente di impostare i tempi associati all'archiviazione delle proprietà e un altro che consente l'assegnazione di un CLSID che può essere usato per associare altro codice, ad esempio il codice dell'interfaccia utente, al set di proprietà. La chiamata al metodo Enum fornisce un puntatore all'implementazione del file composto di IEnumSTATPROPSTG, che consente di enumerare le proprietà nel set.
Nota
Se si ottiene un puntatore a IPropertyStorage chiamando StgCreateDocfile, StgCreateStorageEx, StgOpenStorage o StgOpenStorageEx in un set di proprietà in modalità semplice, i metodi IPropertyStorage rispettano le regole dei flussi in modalità semplice. L'archiviazione del set di proprietà è semplice se è stata ottenuta per un file creato o aperto con il flag di STGM_SIMPLE. In questo caso, non è sempre possibile rendere il flusso sottostante più grande e non è possibile sostituire le proprietà esistenti con proprietà più grandi. Per altre informazioni, vedere Implementazione file composta IPropertySetStorage-Compound.
IPropertyStorage e memorizzazione nella cache
L'implementazione composta dei file di IPropertyStorage memorizza nella cache set di proprietà aperti in memoria per migliorare le prestazioni. Di conseguenza, le modifiche apportate a un set di proprietà non vengono scritte nel file composto finché non vengono chiamati i metodi Commit o Release (ultimo riferimento).
Set di proprietà modalità semplice
Un oggetto di archiviazione delle proprietà è in modalità semplice se viene creato da un oggetto di archiviazione della proprietà in modalità semplice. Ad esempio, un oggetto di archiviazione set di proprietà sarebbe in modalità semplice se ottenuto dalla funzione StgOpenStorageEx , con il flag STGM_SIMPLE impostato nel parametro grfMode . Si noti che la "modalità semplice" non è correlata a "set di proprietà semplici". Un set di proprietà è semplice se viene creato chiamando IPropertySetStorage::Create con il flag PROPSETFLAG_NONSIMPLE impostato nel parametro grfFlags . Per altre informazioni sui set di proprietà semplici e nonsimple, vedere Oggetti di archiviazione e flusso per un set di proprietà.
Quando viene creato un oggetto di archiviazione delle proprietà in modalità semplice, non esistono restrizioni sull'uso. Quando viene aperto un oggetto di archiviazione delle proprietà in modalità semplice esistente, l'oggetto di flusso sottostante che archivia il set di proprietà non può essere cresciuto. Di conseguenza, non è sempre possibile modificare tale oggetto di archiviazione delle proprietà se la modifica richiede un flusso di dimensioni maggiori.
Formati set di proprietà
L'implementazione di file composta di IPropertyStorage supporta sia i formati di serializzazione della versione 0 che del set di proprietà versione 1. Il formato 1 è supportato nei computer in esecuzione in Windows 2000. Per altre informazioni, vedere Serializzazione set di proprietà. I set di proprietà vengono creati in formato 0 e rimangono in tale formato, a meno che non vengano richieste nuove funzionalità. In questo caso, il formato viene aggiornato alla versione 1.
Ad esempio, se un set di proprietà viene creato con il flag di PROPSETFLAG_DEFAULT, il relativo formato è la versione 0. Purché i tipi di proprietà conformi al formato versione 0 vengano scritti in e letti da tale set di proprietà, il set di proprietà rimane in formato versione 0. Se un tipo di proprietà versione 1 viene scritto nel set di proprietà, il set di proprietà viene aggiornato automaticamente alla versione 1. Successivamente, tale set di proprietà non può più essere letto dalle implementazioni che riconoscono solo la versione 0.
Tipi IPropertyStorage e Variant
L'implementazione del file composto di IPropertyStorage non supporta i tipi varianti VT_UNKNOWN o VT_DISPATCH nel membro vt della struttura PROPVARIANT .
La tabella seguente elenca i tipi di varianti supportati in un oggetto SafeArray; ovvero, questi valori possono essere combinati con VT_ARRAY nel membro vt della struttura PROPVARIANT .
Tipi varianti supportati all'interno di SafeArray per implementazione di file composti di IPropertyStorage
VT_I1
VT_UI1
VT_I2
VT_UI2
VT_I4
VT_UI4
VT_INT
VT_UINT
VT_R4
VT_R8
VT_CY
VT_DATE
VT_BSTR
VT_BOOL
VT_DECIMAL
VT_ERROR
VT_VARIANT
Quando VT_VARIANT viene combinato con VT_ARRAY, SafeArray contiene strutture PROPVARIANT . Tuttavia, i tipi di questi elementi devono essere presi dall'elenco precedente, non possono essere VT_VARIANT e non possono includere i VT_VECTOR, VT_ARRAY o VT_BYREF indicatori.
Metodi IPropertyStorage
L'implementazione del file composto di IPropertyStorage supporta i metodi seguenti:
-
Legge le proprietà specificate nella matrice rgpspec e fornisce i valori di tutte le proprietà valide nella matrice rgvar di PROPVARIANTs. Nell'implementazione del file composto COM, gli identificatori di proprietà duplicati che fanno riferimento a tipi di flusso o archiviazione comportano più chiamate a IStorage::OpenStream o IStorage::OpenStorage e l'esito positivo o negativo di ReadMultiple dipende dalla capacità dell'implementazione di archiviazione sottostante di condividere le operazioni di apertura. Poiché in un file composto STGM_SHARE_EXCLUSIVE è forzato, più tentativi aperti avranno esito negativo. L'apertura dello stesso oggetto di archiviazione più di una volta dalla stessa risorsa di archiviazione padre non è supportata. È necessario specificare il flag STGM_SHARE_EXCLUSIVE.
Inoltre, per garantire un'operazione thread-safe se la stessa proprietà con valori di archiviazione o flusso viene richiesta più volte tramite lo stesso puntatore IPropertyStorage nell'implementazione del file composto COM, l'operazione aperta avrà esito positivo o negativo a seconda che la proprietà sia già aperta e se il file system sottostante gestisce più aperture di un flusso o di un archivio. Pertanto, l'operazione ReadMultiple in una proprietà con valori di flusso o archiviazione genera sempre una chiamata a IStorage::OpenStream o IStorage::OpenStorage, che passa l'accesso (STGM_READWRITE e così via) e condivide i flag (STGM_SHARE_EXCLUSIVE e così via) specificati quando il set di proprietà originale è stato aperto o creato.
Se il metodo ha esito negativo, i valori scritti in rgvar[] non sono definiti. Se alcune proprietà con valori di flusso o di archiviazione vengono aperte correttamente, ma prima del completamento dell'esecuzione, queste devono essere rilasciate prima che il metodo restituisca.
-
Scrive le proprietà specificate nella matrice rgpspec[] assegnandole i tag e i valori PROPVARIANT specificati in rgvar[]. Le proprietà già esistenti vengono assegnate ai valori PROPVARIANT specificati. Le proprietà che non esistono attualmente vengono create.
-
Elimina le proprietà specificate in rgpspec[].
-
Legge i nomi di stringa esistenti associati agli ID delle proprietà specificati nella matrice rgpropid[].
-
Assegna i nomi di stringa specificati nella matrice rglpwstrName agli ID delle proprietà specificati nella matrice rgpropid .
-
Elimina i nomi delle proprietà per le proprietà specificate nella matrice rgpropid[].
-
Imposta IL CLSID del flusso del set di proprietà. Nell'implementazione del file composto impostare CLSID su un set di proprietà nonsimple (una che può contenere legalmente proprietà con valori di archiviazione o di flusso, come descritto in IPropertySetStorage::Create) imposta anche CLSID sulla sottostorage sottostante in modo che possa essere ottenuta tramite una chiamata a IStorage::Stat.
-
Per set di proprietà semplici e nonsimple, scarica l'immagine di memoria impostata sulla risorsa di archiviazione sottostante. Inoltre, per i set di proprietà transacted-mode nonsimple, questo metodo esegue un commit (come in IStorage::Commit) nell'archiviazione che contiene il set di proprietà.
-
Solo per i set di proprietà nonsimple, chiama il metodo Revert dell'archiviazione sottostante e riapri il flusso "contenuto". Per i set di proprietà semplici, questa interfaccia restituisce sempre S_OK. I set di proprietà Nonsimple sono quelli creati usando il flag PROPSETFLAG_NONSIMPLE nel metodo IPropertySetStorage::Create . Per altre informazioni, vedere Archiviazione e flussi di oggetti per un set di proprietà .
-
Costruisce un'istanza di IEnumSTATPROPSTG, i metodi di cui è possibile chiamare per enumerare le strutture STATPROPSTG che forniscono informazioni su ognuna delle proprietà nel set. Questa implementazione crea una matrice in cui viene letto l'intero set di proprietà e che può essere condiviso quando viene chiamato IEnumSTATPROPSTG::Clone . Le modifiche apportate al set di proprietà non vengono riflesse in un'istanza di IEnumSTATPROPSTG aperta. Per visualizzare queste modifiche, è necessario costruire una nuova istanza di questo enumeratore.
-
Inserisce i membri di una struttura STATPROPSETSTG , che contiene i dati relativi al set di proprietà nel suo complesso. In caso di restituzione, fornisce un puntatore alla struttura. Per i set di archiviazione nonsimple, questa implementazione chiama IStorage::Stat (o IStream::Stat) per ottenere i tempi dall'archiviazione o dal flusso sottostante. Per i set di archiviazione semplici, non vengono mantenuti tempi.
-
Solo per i set di proprietà nonsimple, imposta i tempi supportati dall'archiviazione sottostante. L'implementazione dell'archiviazione file composta supporta tutte e tre: modifica, accesso e creazione. Questa implementazione di SetTimes chiama il metodo IStorage::SetElementTimes dell'archiviazione sottostante per recuperare questi tempi.
Argomenti correlati