Função StgCreateDocfile (coml2api.h)

A função StgCreateDocfile cria um novo objeto de armazenamento de arquivos composto usando a implementação de arquivo composto fornecida por COM para a interface IStorage .

Sintaxe

HRESULT StgCreateDocfile(
  [in]  const WCHAR *pwcsName,
  [in]  DWORD       grfMode,
  [in]  DWORD       reserved,
  [out] IStorage    **ppstgOpen
);

Parâmetros

[in] pwcsName

Um ponteiro para um nome de cadeia de caracteres Unicode terminado em nulo para o arquivo composto que está sendo criado. Ele é passado sem interpretação para o sistema de arquivos. Pode ser um nome relativo ou NULL. Se NULL, um arquivo composto temporário será alocado com um nome exclusivo.

[in] grfMode

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] reserved

Reservado para uso futuro; deve ser zero.

[out] ppstgOpen

Um ponteiro para o local do ponteiro IStorage para o novo objeto de armazenamento.

Retornar valor

StgCreateDocfile também pode retornar quaisquer 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

A função StgCreateDocfile cria um novo objeto de armazenamento usando a implementação de arquivo composto fornecida por COM para a interface IStorage . O nome do arquivo composto aberto pode ser recuperado chamando o método IStorage::Stat .

StgCreateDocfile 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, consulte Constantes STGM.

Se o arquivo composto for aberto no modo transacionado (o parâmetro grfMode especifica STGM_TRANSACTED) e um arquivo com esse nome já existir, o arquivo existente não será alterado até que todas as alterações pendentes sejam confirmadas. Se o processo de chamada não tiver acesso de gravação ao arquivo existente (devido ao controle de acesso no sistema de arquivos), o parâmetro grfMode só poderá especificar STGM_READ e não STGM_WRITE ou STGM_READWRITE. O novo arquivo composto aberto resultante ainda pode ser gravado, mas uma operação de confirmação subsequente falhará (no modo transacionado, as permissões de gravação são impostas no momento da confirmação).

Especificar STGM_SIMPLE fornece uma implementação muito mais rápida de um objeto de arquivo composto em um caso limitado, mas usado com frequência. Isso pode ser usado por aplicativos que exigem uma implementação de arquivo composto com vários fluxos e nenhum armazenamento. O modo simples não dá suporte a todos os métodos no IStorage. Para obter mais informações, consulte Constantes STGM.

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 no 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 da criação do novo arquivo.

StgCreateDocfile pode ser usado 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 , provavelmente um que 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 .

Requisitos

Confira também

Constantes STGM

Stgcreatedocfileonilockbytes

StgCreateStorageEx