Constantes STGM

As constantes STGM são sinalizadores que indicam condições para criar e excluir os modos de objeto e acesso do objeto. As constantes STGM são incluídas nas interfaces IStorage, IStream e IPropertySetStorage e nas funções StgCreateDocfile, StgCreateStorageEx, StgCreateDocfileOnILockBytes, StgOpenStorage e StgOpenStorageEx .

Esses elementos geralmente são combinados usando um operador OR. Eles são interpretados em grupos, conforme listado na tabela a seguir. Não é válido usar mais de um elemento de um único grupo.

Use um sinalizador do grupo de criação ao criar um objeto, como com StgCreateStorageEx ou IStorage::CreateStream.

Para obter mais informações sobre transações, consulte a seção Comentários.

STGM_READ

0x000000000L

Indica que o objeto é somente leitura, o que significa que as modificações não podem ser feitas. Por exemplo, se um objeto de fluxo for aberto com STGM_READ, o método ISequentialStream::Read poderá ser chamado, mas o método ISequentialStream::Write pode não ser. Da mesma forma, se um objeto de armazenamento aberto com STGM_READ, os métodos IStorage::OpenStream e IStorage::OpenStorage poderão ser chamados, mas os métodos IStorage::CreateStream e IStorage::CreateStorage podem não ser.

STGM_WRITE

0x00000001L

Permite que você salve alterações no objeto, mas não permite o acesso aos seus dados. As implementações fornecidas das interfaces IPropertyStorage e IPropertySetStorage não dão suporte a esse modo somente gravação.

STGM_READWRITE

0x00000002L

Habilita o acesso e a modificação de dados de objeto. Por exemplo, se um objeto de fluxo for criado ou aberto nesse modo, será possível chamar IStream::Read e IStream::Write. Lembre-se de que essa constante não é uma operação OR binária simples dos elementos STGM_WRITE e STGM_READ .

STGM_SHARE_DENY_NONE

0x00000040L

Especifica que as aberturas subsequentes do objeto não são negadas acesso de leitura ou gravação. Se nenhum sinalizador do grupo de compartilhamento for especificado, esse sinalizador será assumido.

STGM_SHARE_DENY_READ

0x00000030L

Impede que outras pessoas abram o objeto posteriormente no modo STGM_READ . Normalmente, ele é usado em um objeto de armazenamento raiz.

STGM_SHARE_DENY_WRITE

0x00000020L

Impede que outras pessoas abram posteriormente o objeto para acesso STGM_WRITE ou STGM_READWRITE . No modo transacionado, o compartilhamento de STGM_SHARE_DENY_WRITE ou STGM_SHARE_EXCLUSIVE pode melhorar significativamente o desempenho porque eles não exigem instantâneos. Para obter mais informações sobre transações, consulte a seção Comentários.

STGM_SHARE_EXCLUSIVE

0x00000010L

Impede que outras pessoas abram o objeto posteriormente em qualquer modo. Lembre-se de que esse valor não é uma operação OR bit a bit simples dos valores STGM_SHARE_DENY_READ e STGM_SHARE_DENY_WRITE . No modo transacionado, o compartilhamento de STGM_SHARE_DENY_WRITE ou STGM_SHARE_EXCLUSIVE pode melhorar significativamente o desempenho porque eles não exigem instantâneos. Para obter mais informações sobre transações, consulte a seção Comentários.

STGM_PRIORITY

0x00040000L

Abre o objeto de armazenamento com acesso exclusivo à versão confirmada mais recentemente. Portanto, outros usuários não podem confirmar alterações no objeto enquanto você o tiver aberto no modo de prioridade. Você obtém benefícios de desempenho para operações de cópia, mas impede que outras pessoas confirmem alterações. Limite o tempo em que os objetos estão abertos no modo de prioridade. Você deve especificar STGM_DIRECT e STGM_READ com o modo de prioridade e não pode especificar STGM_DELETEONRELEASE. STGM_DELETEONRELEASE só é válido ao criar um objeto raiz, como com StgCreateStorageEx. Não é válido ao abrir um objeto raiz existente, como com StgOpenStorageEx. Ele também não é válido ao criar ou abrir um subelemento, como com IStorage::OpenStorage.

STGM_CREATE

0x00001000L

Indica que um objeto de armazenamento ou fluxo existente deve ser removido antes que o novo objeto o substitua. Um novo objeto será criado quando esse sinalizador for especificado somente se o objeto existente tiver sido removido com êxito.

Esse sinalizador é usado ao tentar criar:

• Um objeto de armazenamento em um disco, mas existe um arquivo com esse nome.
• Um objeto dentro de um objeto de armazenamento, mas existe um objeto com o nome especificado.
• Um objeto de matriz de bytes, mas um com o nome especificado existe.

Esse sinalizador não pode ser usado com operações abertas, como StgOpenStorageEx ou IStorage::OpenStream.

STGM_CONVERT

0x00020000L

Cria o novo objeto preservando os dados existentes em um fluxo chamado "Conteúdo". No caso de um objeto de armazenamento ou de uma matriz de bytes, os dados antigos são formatados em um fluxo, independentemente de a matriz de arquivo ou bytes existente atualmente contiver um objeto de armazenamento em camadas. Esse sinalizador só pode ser usado ao criar um objeto de armazenamento raiz. Ele não pode ser usado em um objeto de armazenamento; por exemplo, em IStorage::CreateStream. Também não é válido usar esse sinalizador e o sinalizador STGM_DELETEONRELEASE simultaneamente.

STGM_FAILIFTHERE

0x000000000L

Faz com que a operação de criação falhe se houver um objeto existente com o nome especificado. Nesse caso, STG_E_FILEALREADYEXISTS é retornado. Esse é o modo de criação padrão; ou seja, se nenhum outro sinalizador de criação for especificado, STGM_FAILIFTHERE estará implícito.

STGM_DIRECT

0x000000000L

Indica que, no modo direto, cada alteração em um elemento de armazenamento ou fluxo é gravada conforme ocorre. Esse será o padrão se nem STGM_DIRECT nem STGM_TRANSACTED forem especificados.

STGM_TRANSACTED

0x00010000L

Indica que, no modo transacionado, as alterações serão armazenadas em buffer e gravadas somente se uma operação de confirmação explícita for chamada. Para ignorar as alterações, chame o método Revert na interface IStream, IStorage ou IPropertyStorage . A implementação de arquivo composto COM do IStorage não dá suporte a fluxos transacionados, o que significa que os fluxos só podem ser abertos no modo direto e você não pode reverter alterações neles, no entanto, há suporte para armazenamentos transacionados. As implementações do arquivo composto, autônomo e do sistema de arquivos NTFS de IPropertySetStorage da mesma forma não dão suporte a conjuntos de propriedades simples transacionados porque esses conjuntos de propriedades são armazenados em fluxos. No entanto, há suporte para a transação de conjuntos de propriedades não simples, que podem ser criados especificando o sinalizador PROPSETFLAG_NONSIMPLE no parâmetro grfFlags de IPropertySetStorage::Create.

STGM_NOSCRATCH

0x00100000L

Indica que, no modo transacionado, um arquivo de rascunho temporário geralmente é usado para salvar modificações até que o método Commit seja chamado. Especificar STGM_NOSCRATCH permite que a parte não utilizada do arquivo original seja usada como espaço de trabalho em vez de criar um novo arquivo para essa finalidade. Isso não afeta os dados no arquivo original e, em determinados casos, pode resultar em um melhor desempenho. Não é válido especificar esse sinalizador sem especificar também STGM_TRANSACTED e esse sinalizador só pode ser usado em uma raiz aberta. Para obter mais informações sobre o modo NoScratch, consulte a seção Comentários.

STGM_NOSNAPSHOT

0x00200000L

Esse sinalizador é usado ao abrir um objeto de armazenamento com STGM_TRANSACTED e sem STGM_SHARE_EXCLUSIVE ou STGM_SHARE_DENY_WRITE. Nesse caso, especificar STGM_NOSNAPSHOT impede que a implementação fornecida pelo sistema crie uma cópia instantâneo do arquivo. Em vez disso, as alterações no arquivo são gravadas no final do arquivo. O espaço não utilizado não é recuperado, a menos que a consolidação seja executada durante o commit e haja apenas um gravador atual no arquivo. Quando o arquivo é aberto sem instantâneo modo, outra operação aberta não pode ser executada sem especificar STGM_NOSNAPSHOT. Esse sinalizador só pode ser usado em uma operação aberta raiz. Para obter mais informações sobre o modo NoSnapshot, consulte a seção Comentários.

STGM_SIMPLE

0x08000000L

Fornece uma implementação mais rápida de um arquivo composto em um caso limitado, mas usado com frequência. Para obter mais informações, consulte a seção Comentários.

STGM_DIRECT_SWMR

0x00400000L

Dá suporte ao modo direto para operações de arquivo multireader de gravador único. Para obter mais informações, consulte a seção Comentários.

STGM_DELETEONRELEASE

0x04000000L

Indica que o arquivo subjacente deve ser destruído automaticamente quando o objeto de armazenamento raiz é liberado. Esse recurso é mais útil para criar arquivos temporários. Esse sinalizador só pode ser usado ao criar um objeto raiz, como com StgCreateStorageEx. Não é válido ao abrir um objeto raiz, como com StgOpenStorageEx, ou ao criar ou abrir um subelemento, como com IStorage::CreateStream. Também não é válido usar esse sinalizador e o sinalizador STGM_CONVERT simultaneamente.

Comentários

Você pode combinar esses sinalizadores, mas só pode escolher um sinalizador de cada grupo de sinalizadores relacionados. Normalmente, um sinalizador de cada um dos grupos de acesso e compartilhamento deve ser especificado para todas as funções e métodos que usam essas constantes. Sinalizadores de outros grupos são opcionais.

Modo transacionado

Quando o sinalizador STGM_DIRECTé especificado, apenas uma das seguintes combinações de sinalizadores pode ser especificada dos grupos de acesso e compartilhamento.

    STGM_READ      | STGM_SHARE_DENY_WRITE

    STGM_READWRITE | STGM_SHARE_EXCLUSIVE

    STGM_READ      | STGM_PRIORITY

Lembre-se de que o modo direto está implícito pela ausência de STGM_TRANSACTED. Ou seja, se nem STGM_DIRECT nem STGM_TRANSACTED for especificado, STGM_DIRECT será assumida.

Quando o sinalizador STGM_TRANSACTED é especificado, os objetos são criados ou abertos no modo transacionado. Nesse modo, as alterações em um objeto não persistem até que sejam confirmadas. Por exemplo, as alterações em um objeto de armazenamento transacionado não são persistentes até que o método IStorage::Commit seja chamado. As alterações nesse objeto de armazenamento serão perdidas se o objeto de armazenamento for liberado (versão final) antes que o método Commit seja chamado ou se o método IStorage::Revert for chamado.

Quando um objeto é criado ou aberto no modo transacionado, a implementação deve manter os dados originais e as atualizações para esses dados, para que as atualizações possam ser revertidas, se necessário. Normalmente, isso é executado escrevendo alterações em uma área de zero até que elas sejam confirmadas ou criando uma cópia, chamada de instantâneo, dos dados confirmados mais recentemente.

Quando um objeto de armazenamento raiz é aberto no modo transacionado, o local e o comportamento dos dados de zero e as cópias de instantâneo podem ser controlados para otimizar o desempenho com os sinalizadores STGM_NOSCRATCH e STGM_NOSNAPSHOT. (Um objeto de armazenamento raiz é obtido de, por exemplo, a função StgOpenStorageEx ; um objeto de armazenamento obtido do método IStorage::OpenStorage é um objeto substorage.) Normalmente, os dados de zero e os instantâneos são armazenados em arquivos temporários, separados do armazenamento.

O efeito desses sinalizadores depende do número de leitores e/ou gravadores que acessam o armazenamento raiz.

No caso do "gravador único", um objeto de armazenamento de modo transacionado é aberto para acesso de gravação e não pode haver nenhum outro acesso ao arquivo. Ou seja, o arquivo é aberto com STGM_TRANSACTED, acesso de STGM_WRITE ou STGM_READWRITE e compartilhamento de STGM_SHARE_EXCLUSIVE. Nesse caso, as alterações no objeto de armazenamento são gravadas na área de rascunho. Quando essas alterações são confirmadas, elas são copiadas para o armazenamento original. Portanto, se nenhuma alteração for realmente feita no objeto de armazenamento, não haverá transferência de dados desnecessária.

No caso do "gravador múltiplo", um objeto de armazenamento transacionado é aberto para acesso de gravação, mas é compartilhado de modo a permitir outros gravadores. Ou seja, o objeto de armazenamento é aberto com STGM_TRANSACTED, acesso de STGM_WRITE ou STGM_READWRITE e compartilhamento de STGM_SHARE_DENY_READ. Se o compartilhamento de STGM_SHARE_DENY_NONE for especificado, o caso será "vários gravadores, vários leitores". Nesses casos, uma instantâneo dos dados originais será feita durante a operação aberta. Portanto, mesmo que nenhuma alteração seja realmente feita no armazenamento e/ou ela não seja realmente aberta por outro gravador simultaneamente, a transferência de dados ainda será necessária durante a abertura. Como resultado, o melhor desempenho em tempo livre pode ser obtido abrindo o objeto de armazenamento em modos STGM_SHARE_DENY_WRITE ou STGM_SHARE_EXCLUSIVE . Para obter mais informações sobre como as alterações são confirmadas quando há vários gravadores, consulte IStorage::Commit.

No caso "gravador único, vários leitores", um objeto de armazenamento transacionado é aberto para acesso de gravação, mas é compartilhado com leitores. Ou seja, o objeto de armazenamento é aberto pelo gravador com STGM_TRANSACTED, acesso de STGM_READWRITE ou STGM_WRITE e compartilhamento de STGM_SHARE_DENY_WRITE. O armazenamento é aberto por leitores com STGM_TRANSACTED, acesso de STGM_READ e compartilhamento de STGM_SHARE_DENY_NONE. Nesse caso, o gravador usa a área de rascunho para armazenar alterações não confirmadas. Como nos casos acima, o leitor incorre em uma penalidade de desempenho em tempo livre enquanto uma cópia instantâneo dos dados é criada.

Normalmente, a área de rascunho é um arquivo temporário, separado dos dados originais. Quando as alterações são confirmadas no arquivo original, os dados devem ser transferidos do arquivo temporário. Para evitar essa transferência de dados, o sinalizador STGM_NOSCRATCHpode ser especificado. Quando esse sinalizador é especificado, partes do arquivo de objeto de armazenamento são usadas para a área de rascunho, em vez de um arquivo temporário separado. Como resultado, a confirmação de alterações pode ser executada rapidamente, pois pouca transferência de dados é necessária. A desvantagem é que o arquivo de armazenamento pode se tornar maior do que seria de outra forma, pois ele deve ser grande o suficiente para os dados originais e para a área de rascunho. Para consolidar os dados e remover essa área desnecessária, reabra o armazenamento raiz no modo transacionado, mas sem definir o sinalizador STGM_NOSCRATCH . Em seguida, chame IStorage::Commit com o sinalizador STGC_CONSOLIDATE definido.

A área instantâneo, como a área de rascunho, também é, normalmente, um arquivo temporário, e isso também pode ser afetado com um sinalizador STGM. Ao especificar o sinalizador STGM_NOSNAPSHOT, um arquivo instantâneo temporário separado não é criado. Em vez disso, os dados originais nunca são modificados, mesmo que haja um ou mais gravadores por objeto. Quando as alterações são confirmadas, elas são adicionadas ao arquivo, mas os dados originais permanecem intactos. Esse modo aumenta a eficiência porque reduz o tempo de execução eliminando o requisito de criar uma instantâneo durante a operação aberta. No entanto, o uso desse modo pode resultar em um arquivo de armazenamento muito grande porque os dados no arquivo nunca podem ser substituídos. Isso não é limite para o tamanho dos arquivos abertos no modo NoSnapshot.

Direct Single-Writer, Multiple-Reader Mode

Conforme descrito, é possível ter um único gravador e vários leitores de um objeto de armazenamento, se esse objeto for aberto no modo transacionado. Também é possível obter o caso de gravador único, multireader no modo direto, especificando o sinalizador STGM_DIRECT_SWMR .

No modo STGM_DIRECT_SWMR , é possível que um chamador abra um objeto para acesso de leitura/gravação, enquanto outros chamadores simultaneamente têm o arquivo aberto para acesso somente leitura. Não é válido usar esse sinalizador em combinação com o sinalizador STGM_TRANSACTED . Nesse modo, o gravador abre o objeto com os seguintes sinalizadores:

| STGM_DIRECT_SWMR | STGM_READWRITE STGM_SHARE_DENYWRITE

e cada um dos leitores abre o objeto com estes sinalizadores:

| STGM_DIRECT_SWMR STGM_READ | STGM_SHARE_DENY_NONE

Nesse modo, para modificar o objeto de armazenamento, o gravador deve obter acesso exclusivo ao objeto . Isso é possível quando todos os leitores o fecharam. O gravador usa a interface IDirectWriterLock para obter esse acesso exclusivo.

Modo simples

O modo simples (STGM_SIMPLE) é útil para aplicativos que executam operações de salvamento completas. Ele é eficiente, mas tem as seguintes restrições:

• Não existe suporte para substorages.
• O objeto de armazenamento e os objetos de fluxo obtidos dele não podem ser empacotados.
• Cada fluxo tem um tamanho mínimo. Se menos de bytes mínimos forem gravados em um fluxo quando o fluxo for liberado, o fluxo será estendido para o tamanho mínimo. Por exemplo, o tamanho mínimo para uma implementação IStream específica é de 4 KB. Um fluxo é criado e 1 KB é gravado nele. Na versão final desse IStream, o tamanho do fluxo será automaticamente estendido para 4 KB. Posteriormente, abrir o fluxo e chamar o método IStream::Stat mostrará um tamanho de 4 KB.
• Nem todos os métodos de IStorage ou IStream terão suporte na implementação. Para obter mais informações, consulte IStorage – Implementação de arquivo composto e IStream – Implementação de arquivo composto.

Marshaling é o processo de empacotamento, descompactação e envio de parâmetros de método de interface entre limites de thread ou processo em uma RPC (Chamada de Procedimento Remoto). Para obter mais informações, consulte Marshaling Details and Interface Marshaling(Marshaling Details and Interface Marshaling).

Quando um objeto de armazenamento é obtido por uma operação Create no modo simples:

• Elementos de fluxo podem ser criados, mas não abertos.
• Quando um elemento de fluxo é criado chamando IStorage::CreateStream, não é possível criar outro fluxo até que esse objeto de fluxo seja liberado.
• Depois que todos os fluxos forem gravados, chame IStorage::Commit para liberar as alterações.

Quando um objeto de armazenamento é obtido por uma operação Open no modo simples:

• É possível abrir apenas um elemento de fluxo por vez.
• Não é possível alterar o tamanho de um fluxo chamando o método IStream::SetSize ou buscando ou gravando além do final do fluxo. No entanto, como todos os fluxos têm um tamanho mínimo, é possível usar o fluxo até esse tamanho, mesmo que menos dados sejam originalmente gravados nele. Para determinar o tamanho de um fluxo, use o método IStream::Stat .

Lembre-se de que, se um elemento de armazenamento for modificado por um objeto de armazenamento que não esteja no modo simples, não será possível, novamente, abrir esse elemento de armazenamento no modo simples.

Requisitos

Confira também

ISequentialStream::Read

IStorage

Stgcreatedocfile

Stgcreatedocfileonilockbytes

StgCreateStorageEx

Stgopenstorage

StgOpenStorageEx

StgOpenStorageOnILockBytes