Método IStorage::CreateStorage (objidl.h)

  • Artigo

O método CreateStorage cria e abre um novo objeto de armazenamento aninhado dentro desse objeto de armazenamento com o nome especificado no modo de acesso especificado.

Sintaxe

HRESULT CreateStorage(
  [in]  const OLECHAR *pwcsName,
  [in]  DWORD         grfMode,
  [in]  DWORD         reserved1,
  [in]  DWORD         reserved2,
  [out] IStorage      **ppstg
);

Parâmetros

[in] pwcsName

Um ponteiro para uma cadeia de caracteres Unicode terminada em nulo largo que contém o nome do objeto de armazenamento recém-criado. O nome pode ser usado posteriormente para reabrir o objeto de armazenamento. O nome não deve exceder 31 caracteres de comprimento, não incluindo o terminador de cadeia de caracteres. Os caracteres de 000 a 01f, que servem como o primeiro caractere do nome do fluxo/armazenamento, são reservados para uso pelo OLE. Essa é uma restrição de arquivo composto, não uma restrição de armazenamento estruturado.

[in] grfMode

Um valor que especifica o modo de acesso a ser usado ao abrir o objeto de armazenamento recém-criado. Para obter mais informações e uma descrição dos valores possíveis, consulte Constantes STGM.

[in] reserved1

Reservado para uso futuro; deve ser zero.

[in] reserved2

Reservado para uso futuro; deve ser zero.

[out] ppstg

Um ponteiro, quando bem-sucedido, para o local do ponteiro IStorage para o objeto de armazenamento recém-criado. Esse parâmetro será definido como NULL se ocorrer um erro.

Retornar valor

Esse método pode retornar um desses valores.

Código de retorno Descrição
S_OK O objeto de armazenamento foi criado com êxito.
E_PENDING Somente armazenamento assíncrono: parte ou todos os dados necessários não estão disponíveis no momento.
STG_E_ACCESSDENIED Não há permissões suficientes para criar um objeto de armazenamento.
STG_E_FILEALREADYEXISTS O nome especificado para o objeto de armazenamento já existe no objeto de armazenamento e o parâmetro grfMode inclui o sinalizador STGM_FAILIFTHERE.
STG_E_INSUFFICIENTMEMORY O objeto de armazenamento não foi criado devido à falta de memória.
STG_E_INVALIDFLAG O valor especificado para o parâmetro grfMode< não é um valor de constante STGM válido. o valor especificado para o parâmetro grfMode não é válido
STG_E_INVALIDFUNCTION Não há suporte para a combinação especificada de sinalizadores no parâmetro grfMode .
STG_E_INVALIDNAME Não é um valor válido para pwcsName.
STG_E_INVALIDPOINTER O ponteiro especificado para o objeto de armazenamento não era válido.
STG_E_INVALIDPARAMETER Um dos parâmetros não era válido.
STG_E_REVERTED O objeto de armazenamento foi invalidado por uma operação de reverter acima dele na árvore de transações.
STG_E_TOOMANYOPENFILES O objeto de armazenamento não foi criado porque há muitos arquivos abertos.
STG_S_CONVERTED O fluxo existente com o nome especificado foi substituído por um novo objeto de armazenamento que contém um único fluxo chamado CONTENTS. O novo objeto de armazenamento será adicionado.

Comentários

Se um armazenamento com o nome especificado no parâmetro pwcsName já existir dentro do objeto de armazenamento pai e o parâmetro grfMode incluir o sinalizador STGM_CREATE, o armazenamento existente será substituído pelo novo. Se o parâmetro grfMode incluir o sinalizador STGM_CONVERT, o elemento existente será convertido em um objeto de fluxo chamado CONTENTS e o novo objeto de armazenamento será criado contendo o objeto de fluxo CONTENTS. A destruição do elemento antigo e a criação do novo objeto de armazenamento estão sujeitos ao modo de transação no objeto de armazenamento pai. Lembre-se de que você não pode usar STGM_CONVERT se também estiver usando STGM_CREATE.

A implementação de arquivo composto fornecida por COM do método IStorage::CreateStorage não dá suporte ao seguinte comportamento:

  • O sinalizador STGM_PRIORITY para armazenamentos não deroot.
  • Abrindo o mesmo objeto de armazenamento mais de uma vez do mesmo armazenamento pai. O sinalizador STGM_SHARE_EXCLUSIVE deve ser especificado.
  • O sinalizador STGM_DELETEONRELEASE. Se esse sinalizador for especificado, a função retornará STG_E_INVALIDFLAG.
Se já existir um objeto de armazenamento com o mesmo nome e grfMode estiver definido como STGM_FAILIFTHERE, esse método falhará com o valor retornado STG_E_FILEALREADYEXISTS.

Requisitos

Requisito Valor
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 objidl.h
Biblioteca Uuid.lib
DLL Ole32.dll

Confira também

IStorage – Implementação de arquivo composto

IStorage::OpenStorage