Metodo IPropertyStorage::WriteMultiple (propidlbase.h)

Il metodo WriteMultiple scrive un gruppo specificato di proprietà nel set di proprietà corrente. Se esiste già una proprietà con un nome o un identificatore di proprietà specificato, viene sostituita, anche quando i tipi precedenti e nuovi per il valore della proprietà sono diversi. Se non esiste una proprietà con un nome o un ID di proprietà specificato, viene creata.

Sintassi

HRESULT WriteMultiple(
  [in] ULONG                cpspec,
  [in] const PROPSPEC []    rgpspec,
  [in] const PROPVARIANT [] rgpropvar,
  [in] PROPID               propidNameFirst
);

Parametri

[in] cpspec

Numero di proprietà impostate. Il valore di questo parametro può essere impostato su zero; tuttavia, questo sconfigge lo scopo del metodo perché non vengono scritte proprietà.

[in] rgpspec

Matrice degli ID delle proprietà (PROPSPEC) a cui sono impostate le proprietà. Questi elementi non devono essere in un ordine specifico e possono contenere duplicati, ma l'ultimo ID proprietà specificato è quello che ha effetto. È consentita una combinazione di ID di proprietà e nomi di stringa.

[in] rgpropvar

Matrice (di dimensioni cpspec) di strutture PROPVARIANT che contengono i valori delle proprietà da scrivere. La matrice deve essere la dimensione specificata da cpspec.

[in] propidNameFirst

Valore minimo per gli ID di proprietà che il metodo deve assegnare se il parametro rgpspec specifica le proprietà con nome stringa per cui non esistono ID di proprietà. Se tutte le proprietà con nome stringa specificate esistono già in questo set e pertanto hanno già ID proprietà, questo valore viene ignorato. Se non viene ignorato, questo valore deve essere maggiore o uguale a due e minore di 0x80000000. Gli ID di proprietà 0 e 1 e maggiori di 0x80000000 sono riservati per uso speciale.

Valore restituito

Questo metodo supporta il valore restituito standard E_UNEXPECTED, oltre ai seguenti:

Questa funzione può anche restituire eventuali errori del file system o errori Win32 di cui è stato eseguito il wrapping in un tipo di dati HRESULT . Per altre informazioni, vedere Strategie di gestione degli errori.

Commenti

Se esiste già una proprietà specificata, il relativo valore viene sostituito con quello specificato in rgpspec, anche quando i tipi precedenti e nuovi per il valore della proprietà sono diversi. Se la proprietà specificata non esiste già, tale proprietà viene creata. Le modifiche non vengono rese persistenti nell'archiviazione sottostante fino a quando non viene chiamato IPropertyStorage::Commit .

I nomi delle proprietà vengono archiviati in una sezione speciale del dizionario del set di proprietà, che esegue il mapping di tali nomi agli ID di proprietà. Tutte le proprietà hanno un ID, ma i nomi sono facoltativi. Viene specificato un nome stringa specificando PRSPEC_LPWSTR nel membro ulKind della struttura PROPSPEC . Se viene specificato un nome stringa per una proprietà e il nome non esiste già nel dizionario, il metodo allocherà un ID proprietà e aggiungerà l'ID proprietà e il nome al dizionario. L'ID proprietà viene allocato in modo che non sia in conflitto con altri ID nel set di proprietà. Il valore dell'ID proprietà non è minore del valore specificato dal parametro propidNameFirst . Se il parametro rgpspec specifica le proprietà con nome stringa per cui non esistono ID di proprietà, il parametro propidNameFirst specifica il valore minimo per gli ID di proprietà che il metodo WriteMultiple deve assegnare.

Quando viene creato un nuovo set di proprietà, le proprietà della tabella codici speciale (ID proprietà 1) e l'ID impostazioni locali (ID proprietà 0x80000000) vengono scritte automaticamente nella proprietà impostata. Queste proprietà possono essere lette successivamente, usando il metodo IPropertyStorage::ReadMultiple , specificando rispettivamente gli ID delle proprietà con i valori di PID_CODEPAGE e PID_LOCALE definiti dall'intestazione. Se un set di proprietà non è vuoto, ha una o più proprietà oltre alle proprietà id tabella codici e ID impostazioni locali o ha uno o più nomi nel relativo dizionario, le proprietà speciali della tabella codici e dell'ID impostazioni locali non possono essere modificate chiamando IPropertyStorage::WriteMultiple. Tuttavia, se il set di proprietà è vuoto, è possibile modificare una o entrambe queste proprietà speciali.

Se un elemento nella matrice rgspec viene impostato con un valore PRSPEC_PROPID di 0xffffffff (PID_ILLEGAL), il valore corrispondente nella matrice rgvar viene ignorato da IPropertyStorage::WriteMultiple. Ad esempio, se questo metodo viene chiamato con il parametro cspec impostato su 3, ma rgpspec[1].prspec è impostato su PRSPEC_PROPID e rgpspec[1].propid è impostato su PID_ILLEGAL, verranno scritte solo due proprietà. L'elemento rgpropvar[1] viene ignorato automaticamente.

Utilizzare la macro PropVariantInit per inizializzare le strutture PROPVARIANT .

I set di proprietà, non inclusi i dati per le proprietà nonsimple, sono limitati a 256 KB per Windows NT 4.0 e versioni precedenti. Per Windows 2000, Windows XP e Windows Server 2003, i set di proprietà OLE sono limitati a 1 MB. Se questi limiti vengono superati, l'operazione ha esito negativo e il chiamante riceve un messaggio di errore. Non è possibile che si verifichi una perdita di memoria o un sovraccarico. Per altre informazioni, vedere Gestione dei set di proprietà.

A meno che non venga passato PROPSETFLAG_CASE_SENSITIVE a IPropertySetStorage::Create, i nomi dei set di proprietà non fanno distinzione tra maiuscole e minuscole. Se si specifica una proprietà in base al nome in IPropertyStorage::WriteMultiple , verrà eseguita una ricerca senza distinzione tra maiuscole e minuscole dei nomi nel set di proprietà. Per confrontare stringhe senza distinzione tra maiuscole e minuscole, è necessario conoscere le impostazioni locali delle stringhe. Per altre informazioni, vedere IPropertyStorage::WritePropertyNames.

Per altre informazioni, vedere Considerazioni sull'archiviazione delle proprietà.

Requisiti

Vedi anche

IPropertySetStorage::Create

IPropertyStorage

IPropertyStorage::ReadMultiple

Gestione dei set di proprietà

PROPVARIANT

Esempi

Esempio stgCreatePropSetStg

Esempio WriteRead