Função StgOpenStorageEx (coml2api.h)

A função StgOpenStorageEx abre um objeto de armazenamento raiz existente no sistema de arquivos. Use essa função para abrir Arquivos Compostos e arquivos regulares. Para criar um novo arquivo, use a função StgCreateStorageEx .

Sintaxe

HRESULT StgOpenStorageEx(
  [in]      const WCHAR          *pwcsName,
  [in]      DWORD                grfMode,
  [in]      DWORD                stgfmt,
  [in]      DWORD                grfAttrs,
  [in, out] STGOPTIONS           *pStgOptions,
  [in]      PSECURITY_DESCRIPTOR pSecurityDescriptor,
  [in]      REFIID               riid,
  [out]     void                 **ppObjectOpen
);

Parâmetros

[in] pwcsName

Um ponteiro para o caminho do arquivo de cadeia de caracteres Unicode terminado em nulo que contém o objeto de armazenamento. Esse tamanho de cadeia de caracteres não pode exceder MAX_PATH caracteres.

Windows Server 2003 e Windows XP/2000: Ao contrário da função CreateFile , o limite de MAX_PATH não pode ser excedido usando o prefixo "\?".

[in] grfMode

Um valor que especifica o modo de acesso para abrir o novo objeto de armazenamento. Para obter mais informações, consulte Constantes STGM. Se o chamador especificar o modo transacionado junto com STGM_CREATE ou STGM_CONVERT, a substituição ou conversão ocorrerá quando a operação de confirmação for chamada para o armazenamento raiz. Se IStorage::Commit não for chamado para o objeto de armazenamento raiz, o conteúdo anterior do arquivo será restaurado. STGM_CREATE e STGM_CONVERT não podem ser combinados com o sinalizador STGM_NOSNAPSHOT, pois uma cópia instantâneo é necessária quando um arquivo é substituído ou convertido no modo transacionado.

Se o objeto de armazenamento for aberto no modo direto (STGM_DIRECT) com acesso a STGM_WRITE ou STGM_READWRITE, o modo de compartilhamento deverá ser STGM_SHARE_EXCLUSIVE a menos que o modo de STGM_DIRECT_SWMR seja especificado. Para obter mais informações, consulte a seção Comentários. Se o objeto de armazenamento for aberto no modo direto com acesso a STGM_READ, o modo de compartilhamento deverá ser STGM_SHARE_EXCLUSIVE ou STGM_SHARE_DENY_WRITE, a menos que STGM_PRIORITY ou STGM_DIRECT_SWMR seja especificado. Para obter mais informações, consulte a seção Comentários.

O modo no qual um arquivo é aberto pode afetar o desempenho da implementação. Para obter mais informações, consulte Limites de implementação de arquivo composto.

[in] stgfmt

Um valor que especifica o formato do arquivo de armazenamento. Para obter mais informações, consulte a enumeração STGFMT .

[in] grfAttrs

Um valor que depende do valor do parâmetro stgfmt .

STGFMT_DOCFILE deve ser zero (0) ou FILE_FLAG_NO_BUFFERING. Para obter mais informações sobre esse valor, consulte CreateFile. Se o tamanho do setor do arquivo, especificado em pStgOptions, não for um múltiplo inteiro do tamanho do setor físico do disco subjacente, essa operação falhará. Todos os outros valores de stgfmt devem ser zero.

[in, out] pStgOptions

Um ponteiro para uma estrutura STGOPTIONS que contém dados sobre o objeto de armazenamento aberto. O parâmetro pStgOptions só será válido se o parâmetro stgfmt estiver definido como STGFMT_DOCFILE. O membro usVersion deve ser definido antes de chamar StgOpenStorageEx. Para obter mais informações, consulte a estrutura STGOPTIONS .

[in] pSecurityDescriptor

Reservados; deve ser zero.

[in] riid

Um valor que especifica o GUID do ponteiro de interface a ser retornado. Também pode ser o valor especificado pelo cabeçalho para IID_IStorage obter a interface IStorage ou para IID_IPropertySetStorage obter a interface IPropertySetStorage .

[out] ppObjectOpen

O endereço de uma variável de ponteiro de interface que recebe um ponteiro para uma interface no objeto de armazenamento aberto; contém NULL se a operação falhou.

Retornar valor

Essa função também pode retornar erros do sistema de arquivos ou erros do sistema encapsulados em um HRESULT. Para obter mais informações, consulte Estratégias de tratamento de erros e tratamento de erros desconhecidos.

Comentários

StgOpenStorageEx é um superconjunto da função StgOpenStorage e deve ser usado pelo novo código. Melhorias futuras no armazenamento estruturado serão expostas por meio dessa função. Para obter mais informações sobre plataformas com suporte, consulte a seção Requisitos.

A função StgOpenStorageEx abre o objeto de armazenamento raiz especificado de acordo com o modo de acesso no parâmetro grfMode e, se bem-sucedida, fornece um ponteiro de interface para o objeto de armazenamento aberto no parâmetro ppObjectOpen . Essa função pode ser usada para obter uma implementação de arquivo composto IStorage, uma implementação de arquivo composto IPropertySetStorage ou uma
Implementação do sistema de arquivos NTFS de IPropertySetStorage.

Quando você abre um arquivo, o sistema seleciona uma implementação de armazenamento estruturado dependendo de qual sinalizador STGFMT você especificar no tipo de arquivo e no tipo de unidade em que o arquivo está armazenado.

Use a função StgOpenStorageEx para acessar o armazenamento raiz de um documento de armazenamento estruturado ou o armazenamento do conjunto de propriedades de qualquer arquivo que dê suporte a conjuntos de propriedades. Para obter mais informações sobre quais IIDs (identificadores de interface) têm suporte para os diferentes valores STGFMT , consulte STGFMT.

Quando um arquivo é aberto com essa função para acessar a implementação do conjunto de propriedades NTFS, se aplicam regras especiais de compartilhamento. Para obter mais informações, consulte Implementação de IPropertySetStorage-NTFS.

Se um arquivo composto for aberto no modo transacionado, especificando STGM_TRANSACTED e o modo somente leitura, especificando STGM_READ, é possível alterar o objeto de armazenamento retornado. Por exemplo, é possível chamar IStorage::CreateStream. No entanto, não é possível confirmar essas alterações chamando IStorage::Commit. Portanto, essas alterações serão perdidas.

Não é válido usar os sinalizadores STGM_CREATE, STGM_DELETEONRELEASE ou STGM_CONVERT no parâmetro grfMode para essa função.

Para dar suporte ao modo simples para salvar um objeto de armazenamento sem substorages, a função StgOpenStorageEx aceita uma das duas combinações de sinalizador a seguir como modos válidos no parâmetro grfMode :

    STGM_SIMPLE | STGM_READWRITE | STGM_SHARE_EXCLUSIVE

    STGM_SIMPLE | STGM_READ | STGM_SHARE_EXCLUSIVE

Para dar suporte ao gravador único, multireader, modo direto, a primeira combinação de sinalizador é o parâmetro grfMode válido para o gravador. A segunda combinação de sinalizadores é válida para leitores.

    STGM_DIRECT_SWMR | STGM_READWRITE | STGM_SHARE_DENY_WRITE

    STGM_DIRECT_SWMR | STGM_READ | STGM_SHARE_DENY_NONE

Para obter mais informações sobre modo simples e modos de gravador único/vários leitores, consulte Constantes STGM.

Requisitos

Confira também

arquivos compostos

IStorage

STGFMT

Constantes STGM

STGOPTIONS

Stgcreatedocfile

StgCreateStorageEx

Stgopenstorage