Função StgCreateDocfileOnILockBytes (coml2api.h)

A função StgCreateDocfileOnILockBytes cria e abre um novo objeto de armazenamento de arquivos composto sobre um objeto de matriz de bytes fornecido pelo chamador. O objeto de armazenamento dá suporte à implementação de arquivo composto fornecida por COM para a interface IStorage .

Sintaxe

HRESULT StgCreateDocfileOnILockBytes(
  [in]  ILockBytes *plkbyt,
  [in]  DWORD      grfMode,
  [in]  DWORD      reserved,
  [out] IStorage   **ppstgOpen
);

Parâmetros

[in] plkbyt

Um ponteiro para a interface ILockBytes no objeto de matriz de bytes subjacente no qual criar um arquivo composto.

[in] grfMode

Especifica o modo de acesso a ser usado ao abrir o novo arquivo composto. Para obter mais informações, consulte Constantes STGM e a seção Comentários abaixo.

[in] reserved

Reservado para uso futuro; deve ser zero.

[out] ppstgOpen

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

Retornar valor

A função StgCreateDocfileOnILockBytes também pode retornar quaisquer erros do sistema de arquivos ou erros do sistema encapsulados em um HRESULT ou valores de retorno de erro de interface ILockBytes . Para obter mais informações, consulte Estratégias de tratamento de erros e tratamento de erros desconhecidos.

Comentários

A função StgCreateDocfileOnILockBytes cria um objeto de armazenamento sobre um objeto de matriz de bytes usando a implementação de arquivo composto fornecida por COM da interface IStorage . StgCreateDocfileOnILockBytes pode ser usado para armazenar um documento em um armazenamento de dados arbitrário, como memória ou um banco de dados relacional. A matriz de bytes (indicada pelo parâmetro pLkbyt , que aponta para a interface ILockBytes no objeto) é usada para o armazenamento subjacente no lugar de um arquivo de disco.

Exceto para especificar um objeto byte-array fornecido pelo programador, StgCreateDocfileOnILockBytes é semelhante à função StgCreateDocfile .

O arquivo composto recém-criado é aberto de acordo com os modos de acesso no parâmetro grfMode , sujeito às seguintes restrições:

O comportamento do modo de compartilhamento e o isolamento transacional dependem da implementação ILockBytes que dá suporte a LockRegion e UnlockRegion com semântica LOCK_ONLYONCE . As implementações podem indicar ao armazenamento estruturado que dão suporte a essa funcionalidade definindo o LOCK_ONLYONCE bit no membro grfLocksSupported do STATSTG. Se uma implementação ILockBytes não der suporte a essa funcionalidade, os modos de compartilhamento não serão impostos e as confirmações transacionais no nível raiz não serão coordenadas corretamente com outras instâncias transacionais abertas na mesma matriz de bytes. Os aplicativos que usam uma implementação ILockBytes que não dá suporte ao bloqueio de região, como a implementação CreateStreamOnHGlobal , devem evitar abrir várias instâncias simultâneas na mesma matriz de bytes.

StgCreateDocfileOnILockBytes não dá suporte ao modo simples. O sinalizador STGM_SIMPLE , se presente, é ignorado.

Para fins de conversão, o arquivo é considerado já existente. Como resultado, não é útil usar o valor STGM_FAILIFTHERE , pois faz com que um erro seja retornado. No entanto, tanto STGM_CREATE quanto STGM_CONVERT permanecem úteis.

A capacidade de criar um arquivo composto sobre um objeto de matriz de bytes é fornecida para dar suporte a ter os dados (sob uma estrutura de árvore IStorage e IStream ) em um espaço não persistente. Dada essa funcionalidade, não há nada impedindo que um documento armazenado em um arquivo use essa instalação. Por exemplo, um contêiner pode fazer isso para minimizar o impacto em seu formato de arquivo causado pela adoção de COM. No entanto, é recomendável que os documentos COM adotem a interface IStorage para seu próprio armazenamento de nível externo. Tem estas vantagens:

• A estrutura de armazenamento do documento é a mesma que sua estrutura de armazenamento quando é um objeto inserido, reduzindo o número de casos que o aplicativo precisa lidar.
• É possível escrever ferramentas para acessar os objetos OLE inseridos e vinculados no documento sem conhecimento especial do formato de arquivo do documento. Um exemplo dessa ferramenta é um utilitário de cópia que copia todos os documentos incluídos em um contêiner que contém objetos vinculados. Um utilitário de cópia como esse precisa de acesso aos links contidos para determinar a extensão dos arquivos a serem copiados.
• A implementação do IStorage resolve o problema de como confirmar as alterações no arquivo. Um aplicativo que usa a interface ILockBytes deve lidar com esses problemas em si.

Requisitos

Confira também

Stgcreatedocfile