Função StgCreateStorageEx (coml2api.h)
A função
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 sem interpretação para o sistema de arquivos. Pode ser um nome relativo ou NULL. Se NULL, um arquivo temporário será alocado com um nome exclusivo. Se nãoNULL, o tamanho da cadeia de caracteres não deverá exceder MAX_PATH caracteres.
[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 de 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
[in] grfAttrs
Um valor que depende do valor do parâmetro stgfmt.
| Valores de parâmetro | 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 número inteiro múltiplo do tamanho do setor físico do disco subjacente, essa operação falhará. |
|
Deve ser 0. |
[in] pStgOptions
O parâmetro
[in] pSecurityDescriptor
Permite que as ACLs sejam definidas quando o arquivo é criado. Se não NULL, precisará ser um ponteiro para a estrutura de 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: Value deve ser NULL.
[in] riid
Um valor que especifica o IID (identificador de interface) do ponteiro de interface a ser retornado. Essa IID pode ser para a interface
[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 de retorno
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.
Observações
Quando um aplicativo modifica seu arquivo, ele geralmente cria uma cópia do original. A função
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 uma
de implementação de arquivo composto IStorage, uma implementação de arquivo composto IPropertySetStorage ou para obter uma implementação IPropertySetStorage NTFS.
Quando um novo arquivo é criado, a implementação de armazenamento usada depende do sinalizador especificado e do tipo de unidade no qual o arquivo é armazenado. Para obter mais informações, consulte a enumeração
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
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
Quando um arquivo é criado com essa função para acessar a implementação do conjunto de propriedades NTFS, as regras especiais de compartilhamento se aplicam. Para obter mais informações, consulte IPropertySetStorage-NTFSde Implementação.
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 que STGM_TRANSACTED se STGM_SIMPLE for especificado.
O modo simples não dá suporte a todos os métodos em IStorage. Especificamente, no modo simples, os métodos
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
Requisitos
| Requisito | Valor |
|---|---|
| de cliente com suporte mínimo | Windows 2000 Professional [aplicativos da área de trabalho | Aplicativos UWP] |
| servidor com suporte mínimo | Windows 2000 Server [aplicativos da área de trabalho | Aplicativos UWP] |
| da Plataforma de Destino |
Windows |
| cabeçalho | coml2api.h (inclua Objbase.h) |
| biblioteca | Ole32.lib |
| de DLL |
Ole32.dll |
Consulte também
StgCreateDocfile