Stałe STGM

Stałe STGM są flagami wskazującymi warunki tworzenia i usuwania obiektów i trybów dostępu dla obiektu. Stałe STGM są uwzględniane w interfejsach IStorage, IStream i IPropertySetStorage oraz w funkcjach StgCreateDocfile, StgCreateStorageEx, StgCreateDocfileOnILockBytes, StgOpenStorage i StgOpenStorageEx .

Te elementy są często łączone przy użyciu operatora OR. Są one interpretowane w grupach, jak pokazano w poniższej tabeli. Użycie więcej niż jednego elementu z jednej grupy jest nieprawidłowe.

Użyj flagi z grupy tworzenia podczas tworzenia obiektu, takiego jak StgCreateStorageEx lub IStorage::CreateStream.

Aby uzyskać więcej informacji na temat transakcji, zobacz sekcję Uwagi.

STGM_READ

0x000000000L

Wskazuje, że obiekt jest tylko do odczytu, co oznacza, że nie można wprowadzać modyfikacji. Jeśli na przykład obiekt strumienia jest otwierany przy użyciu STGM_READ, metoda ISequentialStream::Read może być wywoływana, ale metoda ISequentialStream::Write może nie. Podobnie, jeśli obiekt magazynu otwarty przy użyciu STGM_READ, metody IStorage::OpenStream i IStorage::OpenStorage mogą być wywoływane, ale metody IStorage::CreateStream i IStorage::CreateStorage mogą nie.

STGM_WRITE

0x00000001L

Umożliwia zapisywanie zmian w obiekcie, ale nie zezwala na dostęp do jego danych. Udostępnione implementacje interfejsów IPropertyStorage i IPropertySetStorage nie obsługują tego trybu tylko do zapisu.

STGM_READWRITE

0x00000002L

Umożliwia dostęp i modyfikację danych obiektu. Jeśli na przykład obiekt strumienia zostanie utworzony lub otwarty w tym trybie, możliwe jest wywołanie zarówno IStream::Read , jak i IStream::Write. Należy pamiętać, że ta stała nie jest prostą operacją binarną LUBelementów STGM_WRITE i STGM_READ .

STGM_SHARE_DENY_NONE

0x00000040L

Określa, że kolejne otwory obiektu nie są blokowane dostępu do odczytu ani zapisu. Jeśli nie określono flagi z grupy udostępniania, przyjmuje się tę flagę.

STGM_SHARE_DENY_READ

0x00000030L

Uniemożliwia innym osobom otwieranie obiektu w trybie STGM_READ . Jest on zwykle używany w głównym obiekcie magazynu.

STGM_SHARE_DENY_WRITE

0x00000020L

Uniemożliwia innym osobom otwieranie obiektu dla STGM_WRITE lub STGM_READWRITE dostępu. W trybie transakcyjnym udostępnianie STGM_SHARE_DENY_WRITE lub STGM_SHARE_EXCLUSIVE może znacznie zwiększyć wydajność, ponieważ nie wymagają migawek. Aby uzyskać więcej informacji na temat transakcji, zobacz sekcję Uwagi.

STGM_SHARE_EXCLUSIVE

0x00000010L

Uniemożliwia innym osobom otwieranie obiektu w dowolnym trybie. Należy pamiętać, że ta wartość nie jest prostą operacją bitową LUBwartości STGM_SHARE_DENY_READ i STGM_SHARE_DENY_WRITE . W trybie transakcyjnym udostępnianie STGM_SHARE_DENY_WRITE lub STGM_SHARE_EXCLUSIVE może znacznie zwiększyć wydajność, ponieważ nie wymagają migawek. Aby uzyskać więcej informacji na temat transakcji, zobacz sekcję Uwagi.

STGM_PRIORITY

0x00040000L

Otwiera obiekt magazynu z wyłącznym dostępem do ostatnio zatwierdzonej wersji. W związku z tym inni użytkownicy nie mogą zatwierdzać zmian w obiekcie, gdy jest otwarty w trybie priorytetu. Uzyskujesz korzyści z wydajności operacji kopiowania, ale uniemożliwiasz innym osobom zatwierdzanie zmian. Ogranicz czas otwierania obiektów w trybie priorytetu. Należy określić STGM_DIRECT i STGM_READ z trybem priorytetu i nie można określić STGM_DELETEONRELEASE. STGM_DELETEONRELEASE jest prawidłowy tylko podczas tworzenia obiektu głównego, takiego jak StgCreateStorageEx. Nie jest prawidłowy podczas otwierania istniejącego obiektu głównego, takiego jak StgOpenStorageEx. Jest on również nieprawidłowy podczas tworzenia lub otwierania podelementu, takiego jak IStorage::OpenStorage.

STGM_CREATE

0x00001000L

Wskazuje, że istniejący obiekt magazynu lub strumień powinny zostać usunięte przed zastąpieniem go przez nowy obiekt. Nowy obiekt jest tworzony, gdy ta flaga jest określona tylko wtedy, gdy istniejący obiekt został pomyślnie usunięty.

Ta flaga jest używana podczas próby utworzenia:

• Obiekt magazynu na dysku, ale istnieje plik o tej nazwie.
• Obiekt wewnątrz obiektu magazynu, ale istnieje obiekt o określonej nazwie.
• Obiekt tablicy bajtów, ale jeden z określoną nazwą istnieje.

Tej flagi nie można używać z otwartymi operacjami, takimi jak StgOpenStorageEx lub IStorage::OpenStream.

STGM_CONVERT

0x00020000L

Tworzy nowy obiekt przy zachowaniu istniejących danych w strumieniu o nazwie "Zawartość". W przypadku obiektu magazynu lub tablicy bajtów stare dane są sformatowane w strumieniu niezależnie od tego, czy istniejąca tablica plików lub bajtów zawiera obecnie obiekt magazynu warstwowego. Tej flagi można używać tylko podczas tworzenia głównego obiektu magazynu. Nie można go używać w obiekcie magazynu; na przykład w pliku IStorage::CreateStream. Ta flaga jest również nieprawidłowa i flaga STGM_DELETEONRELEASE jednocześnie.

STGM_FAILIFTHERE

0x000000000L

Powoduje niepowodzenie operacji tworzenia, jeśli istnieje istniejący obiekt o określonej nazwie. W takim przypadku zwracana jest STG_E_FILEALREADYEXISTS . Jest to domyślny tryb tworzenia; oznacza to, że jeśli nie określono innego flagi tworzenia, STGM_FAILIFTHERE jest implikowane.

STGM_DIRECT

0x000000000L

Wskazuje, że w trybie bezpośrednim każda zmiana elementu magazynu lub strumienia jest zapisywana w miarę jego wystąpienia. Jest to ustawienie domyślne, jeśli nie określono ani STGM_DIRECT , ani STGM_TRANSACTED .

STGM_TRANSACTED

0x00010000L

Wskazuje, że w trybie transacted zmiany są buforowane i zapisywane tylko wtedy, gdy wywoływana jest jawna operacja zatwierdzania. Aby zignorować zmiany, wywołaj metodę Revert w interfejsie IStream, IStorage lub IPropertyStorage . Implementacja pliku złożonego COM usługi IStorage nie obsługuje strumieni transakcyjnych, co oznacza, że strumienie można otwierać tylko w trybie bezpośrednim i nie można przywrócić ich zmian, jednak obsługiwane są magazyny transakcyjne. Implementacje plików złożonych, autonomicznych i NTFS systemu plików IPropertySetStorage podobnie nie obsługują transacted, prostych zestawów właściwości, ponieważ te zestawy właściwości są przechowywane w strumieniach. Jednak transakcje zestawów właściwości innych niżimple, które można utworzyć, określając flagę PROPSETFLAG_NONSIMPLE w parametrze grfFlagsIPropertySetStorage::Create, są obsługiwane.

STGM_NOSCRATCH

0x00100000L

Wskazuje, że w trybie transacted tymczasowy plik tymczasowy jest zwykle używany do zapisywania modyfikacji do momentu wywołania metody Commit . Określenie STGM_NOSCRATCH zezwala na nieużywaną część oryginalnego pliku do użycia jako miejsce pracy zamiast tworzenia nowego pliku w tym celu. Nie ma to wpływu na dane w oryginalnym pliku, a w niektórych przypadkach może to spowodować zwiększenie wydajności. Nie można określić tej flagi bez określania również STGM_TRANSACTED, a ta flaga może być używana tylko w otwartym katalogu głównym. Aby uzyskać więcej informacji na temat trybu NoScratch, zobacz sekcję Uwagi.

STGM_NOSNAPSHOT

0x00200000L

Ta flaga jest używana podczas otwierania obiektu magazynu z STGM_TRANSACTED i bez STGM_SHARE_EXCLUSIVE lub STGM_SHARE_DENY_WRITE. W takim przypadku określenie STGM_NOSNAPSHOT uniemożliwia implementacji dostarczonej przez system utworzenie kopii migawki pliku. Zamiast tego zmiany w pliku są zapisywane na końcu pliku. Nieużywane miejsce nie jest odzyskiwane, chyba że konsolidacja jest wykonywana podczas zatwierdzania i istnieje tylko jeden bieżący moduł zapisywania w pliku. Po otwarciu pliku w trybie migawki nie można wykonać innej operacji otwierania bez określania STGM_NOSNAPSHOT. Ta flaga może być używana tylko w operacji otwierania głównego. Aby uzyskać więcej informacji na temat trybu NoSnapshot, zobacz sekcję Uwagi.

STGM_SIMPLE

0x080000000L

Zapewnia szybszą implementację pliku złożonego w ograniczonym, ale często używanym przypadku. Aby uzyskać więcej informacji, zobacz sekcję Uwagi.

STGM_DIRECT_SWMR

0x00400000L

Obsługuje tryb bezpośredni dla operacji na plikach z pojedynczym zapisem i wielowątkowym. Aby uzyskać więcej informacji, zobacz sekcję Uwagi.

STGM_DELETEONRELEASE

0x04000000L

Wskazuje, że plik źródłowy ma zostać automatycznie zniszczony po wydaniu głównego obiektu magazynu. Ta funkcja jest najbardziej przydatna do tworzenia plików tymczasowych. Tej flagi można używać tylko podczas tworzenia obiektu głównego, takiego jak StgCreateStorageEx. Nie jest prawidłowy podczas otwierania obiektu głównego, takiego jak StgOpenStorageEx, lub podczas tworzenia lub otwierania podelementu, takiego jak IStorage::CreateStream. Ta flaga jest również nieprawidłowa i flaga STGM_CONVERT jednocześnie.

Uwagi

Można połączyć te flagi, ale można wybrać tylko jedną flagę z każdej grupy powiązanych flag. Zazwyczaj jedna flaga z każdej grupy dostępu i udostępniania musi być określona dla wszystkich funkcji i metod, które używają tych stałych. Flagi z innych grup są opcjonalne.

Tryb transakcji

Po określeniu flagi STGM_DIRECTmożna określić tylko jedną z następujących kombinacji flag z grup dostępu i udostępniania.

    STGM_READ      | STGM_SHARE_DENY_WRITE

    STGM_READWRITE | STGM_SHARE_EXCLUSIVE

    STGM_READ      | STGM_PRIORITY

Należy pamiętać, że tryb bezpośredni jest implikowany przez brak STGM_TRANSACTED. Oznacza to, że jeśli nie określono ani STGM_DIRECT , ani STGM_TRANSACTED , zakłada się, że STGM_DIRECT .

Po określeniu flagi STGM_TRANSACTED obiekty są tworzone lub otwierane w trybie transakcji. W tym trybie zmiany w obiekcie nie są utrwalane, dopóki nie zostaną zatwierdzone. Na przykład zmiany w obiekcie magazynu transakcyjnego nie są utrwalane do momentu wywołania metody IStorage::Commit . Zmiany w takim obiekcie magazynu zostaną utracone, jeśli obiekt magazynu zostanie zwolniony (wersja ostateczna) przed wywołaniem metody Commit lub jeśli zostanie wywołana metoda IStorage::Revert .

Po utworzeniu lub otwarciu obiektu w trybie transakcyjnym implementacja musi zachować zarówno oryginalne dane, jak i aktualizacje tych danych, aby w razie potrzeby można było przywrócić aktualizacje. Jest to zwykle wykonywane przez zapisywanie zmian w obszarze tymczasowym, dopóki nie zostaną zatwierdzone lub przez utworzenie kopii, nazywanej migawką, ostatnio zatwierdzonych danych.

Po otwarciu głównego obiektu magazynu w trybie transakcyjnym lokalizacja i zachowanie danych tymczasowych oraz kopie migawek można kontrolować w celu zoptymalizowania wydajności za pomocą flag STGM_NOSCRATCH i STGM_NOSNAPSHOT . (Obiekt magazynu głównego jest uzyskiwany z funkcji StgOpenStorageEx ; obiekt magazynu uzyskany z metody IStorage::OpenStorage jest obiektem podrzędnym). Zazwyczaj dane tymczasowe i migawki są przechowywane w plikach tymczasowych, niezależnie od magazynu.

Wpływ tych flag zależy od liczby czytelników i/lub autorów dostępu do magazynu głównego.

W przypadku "pojedynczego modułu zapisywania" obiekt magazynu w trybie transacted jest otwarty na potrzeby dostępu do zapisu i nie może mieć innego dostępu do pliku. Oznacza to, że plik jest otwierany przy użyciu STGM_TRANSACTED, dostępu do STGM_WRITE lub STGM_READWRITE oraz udostępniania STGM_SHARE_EXCLUSIVE. W takim przypadku zmiany w obiekcie magazynu są zapisywane w obszarze tymczasowym. Po zatwierdzeniu tych zmian zostaną one skopiowane do oryginalnego magazynu. W związku z tym, jeśli nie zostaną wprowadzone żadne zmiany w obiekcie magazynu, nie będzie niepotrzebny transfer danych.

W przypadku "wielu składników zapisywania" obiekt magazynu transakcyjnego jest otwarty na potrzeby dostępu do zapisu, ale jest udostępniany w taki sposób, aby umożliwić innym zapisom. Oznacza to, że obiekt magazynu jest otwierany przy użyciu STGM_TRANSACTED, dostępu do STGM_WRITE lub STGM_READWRITE oraz udostępniania STGM_SHARE_DENY_READ. Jeśli zamiast tego określono udostępnianie STGM_SHARE_DENY_NONE , przypadek to "multiple-writer, multiple-reader". W takich przypadkach podczas operacji otwierania zostanie wykonana migawka oryginalnych danych. W związku z tym nawet jeśli żadne zmiany nie zostaną wprowadzone do magazynu i/lub nie są one rzeczywiście otwierane przez innego składnika zapisywania jednocześnie, transfer danych jest nadal konieczny podczas otwierania. W rezultacie można uzyskać najlepszą wydajność w czasie otwierania, otwierając obiekt magazynu w trybach STGM_SHARE_DENY_WRITE lub STGM_SHARE_EXCLUSIVE . Aby uzyskać więcej informacji na temat sposobu zatwierdzania zmian w przypadku wielu składników zapisywania, zobacz IStorage::Commit.

W przypadku "pojedynczego modułu zapisywania, wielu czytelników" obiekt magazynu transakcyjnego jest otwarty w celu uzyskania dostępu do zapisu, ale jest udostępniany czytelnikom. Oznacza to, że obiekt magazynu jest otwierany przez składnik zapisywania za pomocą STGM_TRANSACTED, dostępu do STGM_READWRITE lub STGM_WRITE oraz udostępniania STGM_SHARE_DENY_WRITE. Magazyn jest otwierany przez czytelników z STGM_TRANSACTED, dostępem do STGM_READ i udostępnianiem STGM_SHARE_DENY_NONE. W takim przypadku moduł zapisywania używa obszaru tymczasowego do przechowywania niezatwierdzonych zmian. Tak jak w powyższych przypadkach, czytelnik ponosi karę za wydajność w czasie otwierania podczas tworzenia kopii migawki danych.

Zazwyczaj obszar tymczasowy jest plikiem tymczasowym, oddzielonym od oryginalnych danych. Gdy zmiany są zatwierdzane w oryginalnym pliku, dane muszą być przesyłane z pliku tymczasowego. Aby uniknąć tego transferu danych, można określić flagę STGM_NOSCRATCH. Po określeniu tej flagi fragmenty pliku obiektu magazynu są używane na potrzeby obszaru tymczasowego, a nie oddzielnego pliku tymczasowego. W związku z tym zatwierdzanie zmian można szybko wykonać, ponieważ wymagany jest niewielki transfer danych. Wadą jest to, że plik magazynu może stać się większy niż w przeciwnym razie, ponieważ musi być wystarczająco duży, aby zarówno oryginalne dane, jak i obszar tymczasowy. Aby skonsolidować dane i usunąć ten niepotrzebny obszar, otwórz ponownie magazyn główny w trybie transakcji , ale bez ustawiania flagi STGM_NOSCRATCH. Następnie wywołaj metodę IStorage::Commit z ustawionym flagą STGC_CONSOLIDATE .

Obszar migawki, taki jak obszar tymczasowy, jest również zazwyczaj plikiem tymczasowym i może to mieć wpływ na flagę STGM. Określając flagę STGM_NOSNAPSHOT , nie jest tworzony oddzielny plik migawki tymczasowej. Zamiast tego oryginalne dane nigdy nie są modyfikowane, nawet jeśli istnieje co najmniej jeden składnik zapisywania na obiekt. Po zatwierdzeniu zmian są one dodawane do pliku, ale oryginalne dane pozostają nienaruszone. Ten tryb zwiększa wydajność, ponieważ skraca czas wykonywania, eliminując wymaganie utworzenia migawki podczas operacji otwierania. Jednak użycie tego trybu może spowodować powstanie bardzo dużego pliku magazynu, ponieważ dane w pliku nigdy nie mogą być zastępowane. Nie jest to ograniczenie do rozmiaru plików otwartych w trybie NoSnapshot.

Bezpośredni pojedynczy składnik zapisywania, tryb Multiple-Reader

Jak opisano, istnieje możliwość posiadania pojedynczego składnika zapisywania i wielu czytników obiektu magazynu, jeśli ten obiekt jest otwarty w trybie transakcji. Istnieje również możliwość osiągnięcia przypadku pojedynczego modułu zapisującego, wielowątkowego w trybie bezpośrednim, określając flagę STGM_DIRECT_SWMR .

W trybie STGM_DIRECT_SWMR jeden obiekt wywołujący może otworzyć obiekt na potrzeby dostępu do odczytu/zapisu, podczas gdy inne osoby wywołujące jednocześnie mają otwarty plik w celu uzyskania dostępu tylko do odczytu. Ta flaga jest nieprawidłowa w połączeniu z flagą STGM_TRANSACTED . W tym trybie składnik zapisywania otwiera obiekt z następującymi flagami:

| STGM_DIRECT_SWMR | STGM_READWRITESTGM_SHARE_DENYWRITE

a każdy z czytelników otwiera obiekt z następującymi flagami:

| STGM_DIRECT_SWMR | STGM_READSTGM_SHARE_DENY_NONE

W tym trybie, aby zmodyfikować obiekt magazynu, składnik zapisywania musi uzyskać wyłączny dostęp do obiektu. Jest to możliwe, gdy wszyscy czytelnicy go zamknęli. Składnik zapisywania używa interfejsu IDirectWriterLock , aby uzyskać ten wyłączny dostęp.

Tryb prosty

Tryb prosty (STGM_SIMPLE) jest przydatny w przypadku aplikacji wykonujących pełne operacje zapisywania. Jest to wydajne, ale ma następujące ograniczenia:

• Obsługa podstorages nie istnieje.
• Obiekt magazynu i obiekty strumienia uzyskane z niego nie mogą być marshalowane.
• Każdy strumień ma minimalny rozmiar. Jeśli po wydaniu strumienia jest zapisywana mniejsza niż minimalna liczba bajtów, strumień zostanie rozszerzony do minimalnego rozmiaru. Na przykład minimalny rozmiar określonej implementacji IStream to 4 KB. Zostanie utworzony strumień i zapisano w nim 1 KB. W ostatniej wersji tego strumienia IStream rozmiar strumienia zostanie automatycznie rozszerzony do 4 KB. Następnie otwarcie strumienia i wywołanie metody IStream::Stat spowoduje wyświetlenie rozmiaru 4 KB.
• Nie wszystkie metody IStorage lub IStream będą obsługiwane przez implementację. Aby uzyskać więcej informacji, zobacz IStorage — implementacja plików złożonych i IStream — implementacja pliku złożonego.

Marshaling to proces pakowania, rozpakowywania i wysyłania parametrów metody interfejsu w granicach wątku lub procesu w ramach zdalnego wywołania procedury (RPC). Aby uzyskać więcej informacji, zobacz Marshaling Details (Szczegóły marshalingu) i Interface Marshaling (Marshaling interfejsu).

Gdy obiekt magazynu jest uzyskiwany przez operację Tworzenia w trybie prostym:

• Elementy strumienia można tworzyć, ale nie otwierać.
• Po utworzeniu elementu strumienia przez wywołanie metody IStorage::CreateStream nie można utworzyć innego strumienia, dopóki ten obiekt strumienia nie zostanie zwolniony.
• Po zapisaniu wszystkich strumieni wywołaj metodę IStorage::Commit , aby opróżnić zmiany.

Gdy obiekt magazynu jest uzyskiwany przez operację Otwórz w trybie prostym:

• Istnieje możliwość otwarcia tylko jednego elementu strumienia naraz.
• Nie można zmienić rozmiaru strumienia, wywołując metodę IStream::SetSize lub wyszukując lub pisząc poza końcem strumienia. Jednak ze względu na to, że wszystkie strumienie mają minimalny rozmiar, można użyć strumienia do tego rozmiaru, nawet jeśli pierwotnie zapisano w nim mniej danych. Aby określić rozmiar strumienia, użyj metody IStream::Stat .

Należy pamiętać, że jeśli element magazynu jest modyfikowany przez obiekt magazynu, który nie jest w trybie prostym, nie będzie można ponownie otworzyć tego elementu magazynu w trybie prostym.

Wymagania

Zobacz także

ISequentialStream::Read

IStorage

StgCreateDocfile

StgCreateDocfileOnILockBytes

StgCreateStorageEx

StgOpenStorage

StgOpenStorageEx

StgOpenStorageOnILockBytes