Função StgCreateStorageEx (coml2api.h)
A função StgCreateStorageEx cria um novo objeto de armazenamento usando uma implementação fornecida para as interfaces IStorage ou IPropertySetStorage . Para abrir um arquivo existente, use a função StgOpenStorageEx .
Os aplicativos escritos para Windows 2000, Windows Server 2003 e Windows XP devem usar StgCreateStorageEx em vez de StgCreateDocfile para aproveitar os recursos aprimorados do Armazenamento Estruturado do Windows 2000 e do Windows XP.
Sintaxe
HRESULT StgCreateStorageEx(
[in] const WCHAR *pwcsName,
[in] DWORD grfMode,
[in] DWORD stgfmt,
[in] DWORD grfAttrs,
[in] STGOPTIONS *pStgOptions,
[in] PSECURITY_DESCRIPTOR pSecurityDescriptor,
[in] REFIID riid,
[out] void **ppObjectOpen
);
Parâmetros
[in] pwcsName
Um ponteiro para o caminho do arquivo a ser criado. Ele é passado desinterpretado para o sistema de arquivos. Pode ser um nome relativo ou NULL. Se FOR NULL, um arquivo temporário será alocado com um nome exclusivo. Se não for NULL, o tamanho da cadeia de caracteres não deverá exceder MAX_PATH caracteres.
Windows 2000: Ao contrário da função CreateFile , você não pode exceder o limite de MAX_PATH usando o prefixo "\?".
[in] grfMode
Um valor que especifica o modo de acesso a ser usado ao 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.
[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 .
| Valores dos parâmetros | Significado |
|---|---|
|
0 ou FILE_FLAG_NO_BUFFERING. Para obter mais informações, 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á. |
|
Deve ser 0. |
[in] pStgOptions
O parâmetro pStgOptions só será válido se o parâmetro stgfmt estiver definido como STGFMT_DOCFILE. Se o parâmetro stgfmt estiver definido como STGFMT_DOCFILE, pStgOptions apontará para a estrutura STGOPTIONS , que especifica os recursos do objeto de armazenamento, como o tamanho do setor. Esse parâmetro pode ser NULL, que cria um objeto de armazenamento com um tamanho de setor padrão de 512 bytes. Se não for NULL, o membro ulSectorSize deverá ser definido como 512 ou 4096. Se definido como 4096, STGM_SIMPLE pode não ser especificado no parâmetro grfMode . O membro usVersion deve ser definido antes de chamar StgCreateStorageEx. Para obter mais informações, consulte STGOPTIONS.
[in] pSecurityDescriptor
Permite que as ACLs sejam definidas quando o arquivo é criado. Se não for NULL, precisará ser um ponteiro para a estrutura SECURITY_ATTRIBUTES . Consulte CreateFile para obter informações sobre como definir ACLs em arquivos.
Windows Server 2003, Windows 2000 Server, Windows XP e Windows 2000 Professional: O valor deve ser NULL.
[in] riid
Um valor que especifica o IID (identificador de interface) do ponteiro de interface a ser retornado. Esse IID pode ser para a interface IStorage ou para a interface IPropertySetStorage .
[out] ppObjectOpen
Um ponteiro para uma variável de ponteiro de interface que recebe um ponteiro para uma interface no novo objeto de armazenamento; contém NULL se a operação falhou.
Valor retornado
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
Quando um aplicativo modifica seu arquivo, ele geralmente cria uma cópia do original. A função StgCreateStorageEx é uma maneira de criar uma cópia. Essa função funciona indiretamente com a API de duplicação do EFS (Encrypting File System). Ao usar essa função, você precisará definir as opções para o armazenamento de arquivos na estrutura STGOPTIONS .
StgCreateStorageEx é um superconjunto da função StgCreateDocfile e deve ser usado pelo novo código. Melhorias futuras no Armazenamento Estruturado serão expostas por meio da função StgCreateStorageEx . Consulte a seção Requisitos a seguir para obter informações sobre plataformas com suporte.
A função StgCreateStorageEx cria um novo objeto de armazenamento usando uma das implementações de armazenamento estruturado fornecidas pelo sistema. Essa função pode ser usada para obter um
Implementação de arquivo composto IStorage, uma implementação de arquivo composto IPropertySetStorage ou para obter uma implementação de NTFS IPropertySetStorage.
Quando um novo arquivo é criado, a implementação de armazenamento usada depende do sinalizador que você especifica e do tipo de unidade no qual o arquivo é armazenado. Para obter mais informações, consulte a enumeração STGFMT .
StgCreateStorageEx criará o arquivo se ele não existir. Se existir, o uso dos sinalizadores STGM_CREATE, STGM_CONVERT e STGM_FAILIFTHERE no parâmetro grfMode indicará como proceder. Para obter mais informações sobre esses valores, consulte Constantes STGM. Não é válido, no modo direto, especificar o modo STGM_READ no parâmetro grfMode (o modo direto é indicado por não especificar o sinalizador STGM_TRANSACTED). Essa função não pode ser usada para abrir um arquivo existente; em vez disso, use a função StgOpenStorageEx .
Você pode usar a função StgCreateStorageEx para obter acesso ao armazenamento raiz de um documento de armazenamento estruturado ou ao armazenamento do conjunto de propriedades de qualquer arquivo que dê suporte a conjuntos de propriedades. Consulte a documentação do STGFMT para obter informações sobre quais IIDs têm suporte para diferentes valores STGFMT .
Quando um arquivo é criado 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 criado no modo transacionado (especificando STGM_TRANSACTED) e no modo somente leitura (especificando STGM_READ), será possível fazer alterações no 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.
Especificar STGM_SIMPLE fornece uma implementação muito mais rápida de um objeto de arquivo composto em um caso limitado, mas frequentemente usado envolvendo aplicativos que exigem uma implementação de arquivo composto com vários fluxos e nenhum armazenamento. Para obter mais informações, consulte Constantes STGM. Não é válido especificar esse STGM_TRANSACTED se STGM_SIMPLE for especificado.
O modo simples não dá suporte a todos os métodos no IStorage. Especificamente, no modo simples, os métodos IStorage com suporte são CreateStream, Commit e SetClass , bem como os métodos COM IUnknown de QueryInterface, AddRef e Release. Além disso, o SetElementTimes tem suporte com um nome NULL , permitindo que os aplicativos definam horários em um armazenamento raiz. Todos os outros métodos do IStorage retornam STG_E_INVALIDFUNCTION.
Se o parâmetro grfMode especificar STGM_TRANSACTED e nenhum arquivo ainda existir com o nome especificado pelo parâmetro pwcsName , o arquivo será criado imediatamente. Em um sistema de arquivos controlado pelo acesso, o chamador deve ter permissões de gravação para o diretório do sistema de arquivos no qual o arquivo composto é criado. Se STGM_TRANSACTED não for especificado e STGM_CREATE for especificado, um arquivo existente com o mesmo nome será destruído antes de criar o novo arquivo.
Você também pode usar StgCreateStorageEx para criar um arquivo composto temporário passando um valor NULL para o parâmetro pwcsName . No entanto, esses arquivos são temporários apenas no sentido de que eles têm um nome exclusivo fornecido pelo sistema – um que provavelmente não tem sentido para o usuário. O chamador é responsável por excluir o arquivo temporário quando concluído com ele, a menos que STGM_DELETEONRELEASE tenha sido especificado para o parâmetro grfMode . Para obter mais informações sobre esses sinalizadores, consulte Constantes STGM.
Requisitos
| Cliente mínimo com suporte | Windows 2000 Professional [aplicativos da área de trabalho | Aplicativos UWP] |
| Servidor mínimo com suporte | Windows 2000 Server [aplicativos da área de trabalho | Aplicativos UWP] |
| Plataforma de Destino | Windows |
| Cabeçalho | coml2api.h (inclua Objbase.h) |
| Biblioteca | Ole32.lib |
| DLL | Ole32.dll |
Confira também
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de