Função StgOpenStorageOnILockBytes (coml2api.h)

A função StgOpenStorageOnILockBytes abre um objeto de armazenamento existente que não reside em um arquivo de disco, mas tem uma matriz de bytes subjacente fornecida pelo chamador.

Sintaxe

HRESULT StgOpenStorageOnILockBytes(
  [in]  ILockBytes *plkbyt,
  [in]  IStorage   *pstgPriority,
  [in]  DWORD      grfMode,
  [in]  SNB        snbExclude,
  [in]  DWORD      reserved,
  [out] IStorage   **ppstgOpen
);

Parâmetros

[in] plkbyt

Ponteiro ILockBytes para o objeto de matriz de bytes subjacente que contém o objeto de armazenamento a ser aberto.

[in] pstgPriority

Um ponteiro para a interface IStorage que deve ser NULL. Se não for NULL, esse parâmetro será usado conforme descrito abaixo na seção Comentários.

Depois que StgOpenStorageOnILockBytes retornar, o objeto de armazenamento especificado em pStgPriority pode ter sido liberado e não deve mais ser usado.

[in] grfMode

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

[in] snbExclude

Pode ser NULL. Se não for NULL, esse parâmetro apontará para um bloco de elementos nesse armazenamento que devem ser excluídos à medida que o objeto de armazenamento é aberto. Essa exclusão ocorre independentemente de uma cópia instantâneo ocorrer ao ar livre.

[in] reserved

Indica reservado para uso futuro; deve ser zero.

[out] ppstgOpen

Aponta para o local de um ponteiro IStorage para o armazenamento aberto no retorno bem-sucedido.

Retornar valor

A função StgOpenStorageOnILockBytes também pode retornar erros do sistema de arquivos ou erros do sistema encapsulados em um HRESULT ou valores retornados de erro de interface ILockBytes . Consulte Estratégias de tratamento de erros e tratamento de erros desconhecidos.

Comentários

StgOpenStorageOnILockBytes abre o objeto de armazenamento raiz especificado. Um ponteiro para a interface IStorage no objeto de armazenamento aberto é fornecido por meio do parâmetro ppstgOpen .

O objeto de armazenamento deve ter sido criado anteriormente pela função StgCreateDocfileOnILockBytes .

Exceto para especificar um objeto byte-array fornecido pelo programador, StgOpenStorageOnILockBytes é semelhante à função StgOpenStorage . O objeto de armazenamento é 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 para o armazenamento estruturado que dão suporte a essa funcionalidade definindo o bit LOCK_ONLYONCE 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 os commits transacionais de nível raiz não serão coordenados 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 a abertura de várias instâncias simultâneas na mesma matriz de bytes.

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

O parâmetro pStgPriority destina-se como uma conveniência para os chamadores que substituem um objeto de armazenamento existente, geralmente um aberto no modo de prioridade, por um novo objeto de armazenamento aberto na mesma matriz de bytes. Ao contrário do parâmetro pStgPriority de StgOpenStorage, esse parâmetro não afeta a operação aberta executada por StgOpenStorageOnILockBytes e é simplesmente um objeto de armazenamento existente que o chamador gostaria de liberar. Os chamadores sempre devem passar NULL para esse parâmetro porque StgOpenStorageOnILockBytes libera o objeto em algumas circunstâncias e não o libera em outras circunstâncias. O uso do parâmetro pStgPriority pode ser duplicado pelo chamador de maneira mais segura liberando o objeto antes de chamar StgOpenStorageOnILockBytes, conforme mostrado no exemplo a seguir:

// Replacement for:
// HRESULT hr = StgOpenStorageOnILockBytes(
//         plkbyt, pStgPriority, grfMode, NULL, 0, &pstgNew);

pStgPriority->Release();
pStgPriority = NULL;
hr = StgOpenStorage(plkbyt, NULL, grfMode, NULL, 0, &pstgNew);
    

Para obter mais informações, consulte StgOpenStorage.

Requisitos

Confira também

Stgcreatedocfileonilockbytes

Stgopenstorage