Dela via

STGM-konstanter

STGM-konstanterna är flaggor som anger villkor för att skapa och ta bort objekt- och åtkomstlägen för objektet. STGM-konstanterna ingår i gränssnitten IStorage, IStream och IPropertySetStorage och i funktionerna StgCreateDocfile, StgCreateStorageEx, StgCreateDocfileOnILockBytes, StgOpenStorage och StgOpenStorageEx .

Dessa element kombineras ofta med en OR-operator. De tolkas i grupper enligt listan i följande tabell. Det är inte giltigt att använda mer än ett element från en enda grupp.

Använd en flagga från skapandegruppen när du skapar ett objekt, till exempel med StgCreateStorageEx eller IStorage::CreateStream.

Mer information om transaktioner finns i avsnittet Anmärkningar.

Grupp Flagga Värde
Åtkomst STGM_READ 0x00000000L
STGM_WRITE 0x00000001L
STGM_READWRITE 0x00000002L
Delning STGM_SHARE_DENY_NONE 0x00000040L
STGM_SHARE_DENY_READ 0x00000030L
STGM_SHARE_DENY_WRITE 0x00000020L
STGM_SHARE_EXCLUSIVE 0x00000010L
STGM_PRIORITY 0x00040000L
Skapelse STGM_CREATE 0x00001000L
STGM_CONVERT 0x00020000L
STGM_FAILIFTHERE 0x00000000L
Transaktion STGM_DIRECT 0x00000000L
STGM_TRANSACTED 0x00010000L
Transaktionsprestanda STGM_NOSCRATCH 0x00100000L
STGM_NOSNAPSHOT 0x00200000L
Direkt SWMR och Enkel STGM_SIMPLE 0x08000000L
STGM_DIRECT_SWMR 0x00400000L
Ta bort vid lansering STGM_DELETEONRELEASE 0x04000000L

STGM_READ

0x00000000L

Anger att objektet är skrivskyddat, vilket innebär att ändringar inte kan göras. Om ett dataströmobjekt till exempel öppnas med STGM_READ kan metoden ISequentialStream::Read anropas, men metoden ISequentialStream::Write kanske inte gör det. Om ett lagringsobjekt öppnas med STGM_READ kan metoderna IStorage::OpenStream och IStorage::OpenStorage anropas, men metoderna IStorage::CreateStream och IStorage::CreateStorage kanske inte gör det.

STGM_WRITE

0x00000001L

Gör att du kan spara ändringar i objektet, men tillåter inte åtkomst till dess data. De angivna implementeringarna av gränssnitten IPropertyStorage och IPropertySetStorage stöder inte detta skrivskyddade läge.

STGM_READWRITE

0x00000002L

Möjliggör åtkomst och ändring av objektdata. Om ett stream-objekt till exempel skapas eller öppnas i det här läget kan du anropa både IStream::Read och IStream::Write. Tänk på att den här konstanten inte är en enkel binär ELLER-åtgärd för de STGM_WRITE - och STGM_READ elementen.

STGM_SHARE_DENY_NONE

0x00000040L

Anger att efterföljande öppningar av objektet inte nekas läs- eller skrivåtkomst. Om ingen flagga från delningsgruppen har angetts antas den här flaggan.

STGM_SHARE_DENY_READ

0x00000030L

Förhindrar att andra senare öppnar objektet i STGM_READ läge. Det används vanligtvis på ett rotlagringsobjekt.

STGM_SHARE_DENY_WRITE

0x00000020L

Förhindrar att andra senare öppnar objektet för STGM_WRITE eller STGM_READWRITE åtkomst. I transacted-läge kan delning av STGM_SHARE_DENY_WRITE eller STGM_SHARE_EXCLUSIVE avsevärt förbättra prestanda eftersom de inte kräver ögonblicksbilder. Mer information om transaktioner finns i avsnittet Anmärkningar.

STGM_SHARE_EXCLUSIVE

0x00000010L

Hindrar andra från att senare öppna objektet i valfritt läge. Tänk på att det här värdet inte är en enkel bitvis ELLER-åtgärd av STGM_SHARE_DENY_READ - och STGM_SHARE_DENY_WRITE-värdena . I transacted-läge kan delning av STGM_SHARE_DENY_WRITE eller STGM_SHARE_EXCLUSIVE avsevärt förbättra prestanda eftersom de inte kräver ögonblicksbilder. Mer information om transaktioner finns i avsnittet Anmärkningar.

STGM_PRIORITY

0x00040000L

Öppnar lagringsobjektet med exklusiv åtkomst till den senaste bekräftade versionen. Andra användare kan därför inte checka in ändringar i objektet medan du har det öppet i prioritetsläge. Du får prestandafördelar för kopieringsåtgärder, men du hindrar andra från att genomföra ändringar. Begränsa den tid då objekt är öppna i prioritetsläge. Du måste ange STGM_DIRECT och STGM_READ med prioritetsläge och du kan inte ange STGM_DELETEONRELEASE. STGM_DELETEONRELEASE är endast giltigt när du skapar ett rotobjekt, till exempel med StgCreateStorageEx. Det är inte giltigt när du öppnar ett befintligt rotobjekt, till exempel med StgOpenStorageEx. Det är inte heller giltigt när du skapar eller öppnar ett underelement, till exempel med IStorage::OpenStorage.

STGM_CREATE

0x00001000L

Anger att ett befintligt lagringsobjekt eller dataström ska tas bort innan det nya objektet ersätter det. Ett nytt objekt skapas när den här flaggan endast anges om det befintliga objektet har tagits bort.

Den här flaggan används när du försöker skapa:

  • Det finns ett lagringsobjekt på en disk, men det finns en fil med det namnet.
  • Det finns ett objekt i ett lagringsobjekt, men det finns ett objekt med det angivna namnet.
  • Ett bytematrisobjekt, men ett med det angivna namnet finns.

Den här flaggan kan inte användas med öppna åtgärder, till exempel StgOpenStorageEx eller IStorage::OpenStream.

STGM_CONVERT

0x00020000L

Skapar det nya objektet samtidigt som befintliga data bevaras i en ström med namnet "Innehåll". När det gäller ett lagringsobjekt eller en bytematris formateras de gamla data till en ström oavsett om den befintliga filen eller bytematrisen för närvarande innehåller ett lagerlagringsobjekt. Den här flaggan kan bara användas när du skapar ett rotlagringsobjekt. Det kan inte användas i ett lagringsobjekt. till exempel i IStorage::CreateStream. Det är inte heller giltigt att använda den här flaggan och flaggan STGM_DELETEONRELEASE samtidigt.

STGM_FAILIFTHERE

0x00000000L

Gör att skapandeåtgärden misslyckas om det finns ett befintligt objekt med det angivna namnet. I det här fallet returneras STG_E_FILEALREADYEXISTS . Det här är standardläget för skapande. om ingen annan skapa-flagga anges är STGM_FAILIFTHERE underförstådd.

STGM_DIRECT

0x00000000L

Anger att varje ändring i direktläge till ett lagrings- eller strömelement skrivs när det sker. Detta är standardvärdet om varken STGM_DIRECT eller STGM_TRANSACTED har angetts.

STGM_TRANSACTED

0x00010000L

Anger att ändringar i transacted-läge buffrats och skrivs endast om en explicit incheckningsåtgärd anropas. Om du vill ignorera ändringarna anropar du metoden Revert i gränssnittet IStream, IStorage eller IPropertyStorage . COM-sammansatt filimplementering av IStorage stöder inte transacted-strömmar, vilket innebär att strömmar endast kan öppnas i direktläge, och du kan inte återställa ändringar till dem, men transacted storages stöds. Den sammansatta filen, fristående och NTFS-filsystemimplementeringar av IPropertySetStorage stöder på liknande sätt inte transacted, enkla egenskapsuppsättningar eftersom dessa egenskapsuppsättningar lagras i strömmar. Transaktion av icke-exempelegenskapsuppsättningar, som kan skapas genom att ange flaggan PROPSETFLAG_NONSIMPLE i parametern grfFlags i IPropertySetStorage::Create, stöds.

STGM_NOSCRATCH

0x00100000L

Anger att i transacted-läge används vanligtvis en tillfällig scratch-fil för att spara ändringar tills commit-metoden anropas. Om du anger STGM_NOSCRATCH kan den oanvända delen av den ursprungliga filen användas som arbetsyta i stället för att skapa en ny fil för det ändamålet. Detta påverkar inte data i den ursprungliga filen och kan i vissa fall resultera i bättre prestanda. Det är inte giltigt att ange den här flaggan utan att ange STGM_TRANSACTED, och den här flaggan får endast användas i en rotöppning. Mer information om NoScratch-läge finns i avsnittet Kommentarer.

STGM_NOSNAPSHOT

0x00200000L

Den här flaggan används när du öppnar ett lagringsobjekt med STGM_TRANSACTED och utan STGM_SHARE_EXCLUSIVE eller STGM_SHARE_DENY_WRITE. I det här fallet förhindrar att du anger STGM_NOSNAPSHOT den systembaserade implementeringen från att skapa en ögonblicksbild av filen. I stället skrivs ändringar i filen till slutet av filen. Outnyttjat utrymme frigörs inte om inte konsolideringen utförs under incheckningen och det bara finns en aktuell skrivare i filen. När filen öppnas i inget ögonblicksbildsläge går det inte att utföra en annan öppen åtgärd utan att ange STGM_NOSNAPSHOT. Den här flaggan får endast användas i en rotöppningsåtgärd. Mer information om NoSnapshot-läge finns i avsnittet Kommentarer.

STGM_SIMPLE

0x08000000L

Ger en snabbare implementering av en sammansatt fil i ett begränsat, men ofta använt, ärende. Mer information finns i avsnittet Anmärkningar.

STGM_DIRECT_SWMR

0x00400000L

Stöder direktläge för filåtgärder med en skrivare och flera läsare. Mer information finns i avsnittet Anmärkningar.

STGM_DELETEONRELEASE

0x04000000L

Anger att den underliggande filen ska förstöras automatiskt när rotlagringsobjektet släpps. Den här funktionen är mest användbar för att skapa temporära filer. Den här flaggan kan bara användas när du skapar ett rotobjekt, till exempel med StgCreateStorageEx. Det är inte giltigt när du öppnar ett rotobjekt, till exempel med StgOpenStorageEx, eller när du skapar eller öppnar ett underelement, till exempel med IStorage::CreateStream. Det är inte heller giltigt att använda den här flaggan och flaggan STGM_CONVERT samtidigt.

Anmärkningar

Du kan kombinera dessa flaggor, men du kan bara välja en flagga från varje grupp med relaterade flaggor. Vanligtvis måste en flagga från var och en av åtkomst- och delningsgrupperna anges för alla funktioner och metoder som använder dessa konstanter. Flaggor från andra grupper är valfria.

Transacted Mode

När STGM_DIRECT-flaggananges kan endast en av följande kombinationer av flaggor anges från åtkomst- och delningsgrupperna.

    STGM_READ      | STGM_SHARE_DENY_WRITE

    STGM_READWRITE | STGM_SHARE_EXCLUSIVE

    STGM_READ      | STGM_PRIORITY

Tänk på att direktläget underförstås av avsaknaden av STGM_TRANSACTED. Om varken STGM_DIRECT eller STGM_TRANSACTED anges antas STGM_DIRECT .

När flaggan STGM_TRANSACTED anges skapas eller öppnas objekt i transacted-läge. I det här läget bevaras inte ändringar i ett objekt förrän de har checkats in. Ändringar i ett transacted storage-objekt sparas till exempel inte förrän metoden IStorage::Commit anropas. Ändringar i ett sådant lagringsobjekt går förlorade om lagringsobjektet släpps (slutlig version) innan metoden Commit anropas, eller om metoden IStorage::Revert anropas.

När ett objekt skapas eller öppnas i transacted-läge måste implementeringen behålla både ursprungliga data och uppdateringar av dessa data, så att uppdateringarna kan återställas om det behövs. Detta utförs vanligtvis genom att skriva ändringar till ett scratch-område tills de har checkats in, eller genom att skapa en kopia, kallad en ögonblicksbild, av de senast incheckade data.

När ett rotlagringsobjekt öppnas i transacted-läge kan platsen och beteendet för scratch-data och ögonblicksbildkopior styras för att optimera prestanda med flaggorna STGM_NOSCRATCH och STGM_NOSNAPSHOT . (Ett rotlagringsobjekt hämtas från till exempel funktionen StgOpenStorageEx . Ett lagringsobjekt som hämtas från metoden IStorage::OpenStorage är ett underlagringsobjekt.) Vanligtvis lagras scratch-data och ögonblicksbilder i temporära filer, åtskilda från lagringen.

Effekten av dessa flaggor beror på antalet läsare och/eller författare som har åtkomst till rotlagringen.

I fallet "single-writer" öppnas ett lagringsobjekt i transacted-läge för skrivåtkomst och det kan inte finnas någon annan åtkomst till filen. Filen öppnas med STGM_TRANSACTED, åtkomst till STGM_WRITE eller STGM_READWRITE och delning av STGM_SHARE_EXCLUSIVE. I det här fallet skrivs ändringar i lagringsobjektet till scratch-området. När ändringarna checkas in kopieras de till den ursprungliga lagringen. Om inga ändringar faktiskt görs i lagringsobjektet blir det därför ingen onödig dataöverföring.

I fallet "multiple-writer" öppnas ett transacted storage-objekt för skrivåtkomst, men delas på ett sådant sätt att andra författare tillåts. Lagringsobjektet öppnas med STGM_TRANSACTED, åtkomst till STGM_WRITE eller STGM_READWRITE och delning av STGM_SHARE_DENY_READ. Om delning av STGM_SHARE_DENY_NONE anges i stället är ärendet "multiple-writer, multiple-reader". I dessa fall görs en ögonblicksbild av de ursprungliga data under den öppna åtgärden. Även om inga ändringar faktiskt görs i lagringen och/eller om den faktiskt inte öppnas av en annan skrivare samtidigt, är dataöverföring fortfarande nödvändig under öppningen. Därför kan du få bästa prestanda för öppen tid genom att öppna lagringsobjektet i STGM_SHARE_DENY_WRITE eller STGM_SHARE_EXCLUSIVE lägen. Mer information om hur ändringar utförs när det finns flera skrivare finns i IStorage::Commit.

I fallet "single-writer, multiple-reader" öppnas ett transacted storage-objekt för skrivåtkomst, men delas med läsarna. Lagringsobjektet öppnas alltså av skrivaren med STGM_TRANSACTED, åtkomst till STGM_READWRITE eller STGM_WRITE och delning av STGM_SHARE_DENY_WRITE. Lagringen öppnas av läsare med STGM_TRANSACTED, åtkomst till STGM_READ och delning av STGM_SHARE_DENY_NONE. I det här fallet använder skrivaren scratch-området för att lagra icke-bakåtkompatibla ändringar. Precis som i ovanstående fall ådrar sig läsaren en prestandaavgift för öppen tid medan en ögonblicksbild av data skapas.

Vanligtvis är scratch-området en tillfällig fil, separat från de ursprungliga data. När ändringar checkas in i den ursprungliga filen måste data överföras från den tillfälliga filen. För att undvika den här dataöverföringen kan flaggan STGM_NOSCRATCHanges. När den här flaggan anges används delar av lagringsobjektfilen för scratch-området i stället för en separat temporär fil. Därför kan incheckning av ändringar utföras snabbt, eftersom det krävs lite dataöverföring. Nackdelen är att lagringsfilen kan bli större än den annars skulle vara, eftersom den måste växa till att vara tillräckligt stor för både ursprungliga data och scratch-området. Om du vill konsolidera data och ta bort det här onödiga området öppnar du rotlagringen i transacted-läge, men utan att ange flaggan STGM_NOSCRATCH . Anropa sedan IStorage::Commit med flaggan STGC_CONSOLIDATE inställd.

Området för ögonblicksbilder, precis som scratch-området, är vanligtvis också en tillfällig fil, och även detta kan påverkas med en STGM-flagga. Genom att ange flaggan STGM_NOSNAPSHOT skapas inte en separat temporär ögonblicksbildfil. I stället ändras aldrig de ursprungliga data, även om det finns en eller flera skrivare per objekt. När ändringar checkas in läggs de till i filen, men de ursprungliga data förblir intakta. Det här läget ökar effektiviteten eftersom det minskar körningstiden genom att eliminera kravet på att skapa en ögonblicksbild under den öppna åtgärden. Om du använder det här läget kan det dock resultera i en mycket stor lagringsfil eftersom data i filen aldrig kan skrivas över. Det här är ingen gräns för storleken på filer som öppnas i NoSnapshot-läge.

Direct Single-Writer, Multiple-Reader Mode

Som beskrivs är det möjligt att ha en enskild skrivare och flera läsare av ett lagringsobjekt, om objektet öppnas i transacted-läge. Det är också möjligt att uppnå fallet med en skrivare, multireader i direktläge, genom att ange flaggan STGM_DIRECT_SWMR .

I STGM_DIRECT_SWMR läge är det möjligt för en anropare att öppna ett objekt för läs-/skrivåtkomst, medan andra anropare samtidigt har filen öppen för skrivskyddad åtkomst. Det är inte giltigt att använda den här flaggan i kombination med flaggan STGM_TRANSACTED . I det här läget öppnar skrivaren objektet med följande flaggor:

| STGM_DIRECT_SWMR | STGM_READWRITESTGM_SHARE_DENYWRITE

och var och en av läsarna öppnar objektet med dessa flaggor:

| STGM_DIRECT_SWMR | STGM_READSTGM_SHARE_DENY_NONE

Om du vill ändra lagringsobjektet i det här läget måste skrivaren få exklusiv åtkomst till objektet. Detta är möjligt när alla läsare har stängt den. Skrivaren använder IDirectWriterLock-gränssnittet för att få den här exklusiva åtkomsten.

Enkelt läge

Enkelt läge (STGM_SIMPLE) är användbart för program som utför fullständiga sparåtgärder. Det är effektivt, men har följande begränsningar:

  • Det finns inget stöd för underlagringar.
  • Det går inte att konvertera lagringsobjektet och strömma objekt som hämtats från det.
  • Varje ström har en minsta storlek. Om färre än de minsta byteen skrivs till en ström när strömmen släpps utökas strömmen till den minsta storleken. Till exempel är den minsta storleken för en viss IStream-implementering 4 KB. En ström skapas och 1 KB skrivs till den. Vid den slutliga versionen av IStream utökas strömstorleken automatiskt till 4 KB. Om du öppnar strömmen och anropar metoden IStream::Stat visas en storlek på 4 KB.
  • Alla metoder för IStorage eller IStream stöds inte av implementeringen. Mer information finns i IStorage – Sammansatt filimplementering och IStream – Sammansatt filimplementering.

Marshaling är processen för att paketera, packa upp och skicka gränssnittsmetodparametrar över tråd- eller processgränser inom ett RPC (Remote Procedure Call). Mer information finns i Marskalkningsinformation och gränssnittsmarsering.

När ett lagringsobjekt hämtas av en skapa-åtgärd i enkelt läge:

  • Stream-element kan skapas men inte öppnas.
  • När ett stream-element skapas genom att anropa IStorage::CreateStream går det inte att skapa en annan ström förrän dataströmsobjektet har släppts.
  • När alla strömmar har skrivits anropar du IStorage::Commit för att tömma ändringarna.

När ett lagringsobjekt hämtas av en Open-åtgärd i enkelt läge:

  • Du kan bara öppna ett stream-element i taget.
  • Det går inte att ändra storleken på en dataström genom att anropa metoden IStream::SetSize eller genom att söka efter eller skriva utanför strömmens slut. Men eftersom alla strömmar är av en minsta storlek är det möjligt att använda strömmen upp till den storleken, även om mindre data ursprungligen skrevs till den. Om du vill fastställa storleken på en ström använder du metoden IStream::Stat .

Tänk på att om ett lagringselement ändras av ett lagringsobjekt som inte är i enkelt läge, kommer det återigen inte att vara möjligt att öppna lagringselementet i enkelt läge.

Kravspecifikation

Krav Värde
Lägsta klient som stöds
 Windows 2000 Professional [endast skrivbordsappar]
Lägsta server som stöds
 Windows 2000 Server [endast skrivbordsappar]
Rubrik
ObjBase.h

Se även

ISequentialStream::Read

IStorage

StgCreateDocfile

StgCreateDocfileOnILockBytes

StgCreateStorageEx

StgOpenStorage

StgOpenStorageEx

StgOpenStorageOnILockBytes