StgOpenStorage

9/8/2008

Essa função abre um objeto armazenamento raiz existente na sistema de arquivos. Você pode usar esta função para aberto arquivos compostos, mas você não pode usá-lo para aberto diretórios, arquivos ou catálogos de resumo. Objetos aninhados armazenamento só podem ser abertos usando do seu pai IStorage::OpenStorage método.

Syntax

WINOLEAPI StgOpenStorage( 
  const WCHAR* pwcsName, 
  IStorage* pstgPriority, 
  DWORD grfMode, 
  SNB snbExclude, 
  DWORD reserved, 
  IStorage** ppstgOpen 
); 

Parameters

• pwcsName
  [no] Ponteiro para o caminho do arquivo que contém o objeto armazenamento para aberto. Este parâmetro é ignorado se o pStgPriority parâmetro não é NULL.

• pstgPriority
  [no] Com mais freqüência NULL. Se não for NULL, este parâmetro é usado em vez das pwcsName parâmetro para especificar o ponteiro para o IStorage interface no objeto de armazenamento para aberto. Ele aponta para uma abertura anterior de um objeto armazenamento raiz, geralmente um que foi aberto no modo prioridade.

  Após a StgOpenStorage função retorna, o objeto armazenamento especificado na pStgPriority parâmetro na função entrada é inválido e pode não ser usado. Em vez disso, use aquela especificada na ppStgOpen parâmetro em vez disso.

• grfMode
  [no] Especifica o modo de acesso usar para o objeto armazenamento aberto.

• snbExclude
  [no] Se não for NULL, este parâmetro aponta para um bloco de elementos em de armazenamento que devem ser excluídos como o objeto armazenamento é aberto. A exclusão ocorre independentemente se copiar um instantâneo acontece no aberto. Pode ser NULL.

• Reservado
  [no] Reservado para uso futuro; definido como zero.

• ppstgOpen
  [out] Ponteiro para o IStoragevariável * pointer que recebe o ponteiro interface para o armazenamento aberto.

Return Value

Um dos valores descritos a seguinte tabela é retornada.

Valor	Descrição
S_OK	O objeto armazenamento foi aberto com êxito.
STG_E_FILENOTFOUND	O arquivo especificado não existe.
STG_E_ACCESSDENIED	O acesso foi negado porque o chamador tinha permissão insuficiente, ou outro chamador tinha o arquivo aberto e bloqueado.
STG_E_LOCKVIOLATION	O acesso foi negado porque outro chamador tivesse aberto o arquivo e bloqueado.
STG_E_SHAREVIOLATION	O acesso foi negado porque outro chamador tivesse aberto o arquivo e bloqueado.
STG_E_FILEALREADYEXISTS	O arquivo existe mas não é um objeto armazenamento.
STG_E_TOOMANYOPENFILES	O objeto armazenamento não foi aberto porque há muitos aberto arquivos.
STG_E_INSUFFICIENTMEMORY	O objeto armazenamento não foi aberto devido a uma falta de memória.
STG_E_INVALIDNAME	Há um incorreto nome in a pwcsName parâmetro.
STG_E_INVALIDPOINTER	Há um incorreto ponteiro in a snbExclude, pwcsName, pstgPriority, ou ppStgOpen parâmetro.
STG_E_INVALIDFLAG	Há um incorreto combinação sinalizador in a grfMode parâmetro.
STG_E_INVALIDFUNCTION	STGM_DELETEONRELEASE foi especificado na grfMode parâmetro.
STG_E_OLDFORMAT	O objeto armazenamento sendo aberto foi criado pelo provedor de armazenamento Beta 1. Esse formato é Não com suporte mais.
STG_E_NOTSIMPLEFORMAT	O sinalizador STGM_SIMPLE foi especificado na grfMode parâmetro e o objeto armazenamento que está sendo aberto não foi gravado no modo Simples.
STG_E_OLDDLL	O DLL que está sendo usado para este objeto armazenamento é uma versão prior to aquele usado para criá-lo aberto.
STG_E_PATHNOTFOUND	O caminho especificado não existe.

Essa função também pode retornar qualquer erros sistema de arquivos Win32 ou ajustada em um HRESULT.

Remarks

O StgOpenStorage função abre o objeto armazenamento raiz especificado de acordo com o modo de acesso in a grfMode parâmetro, e, se bem-sucedido, fornece uma IStorage ponteiro para o objeto armazenamento aberto na ppstgOpen parâmetro.

Para suporte o modo Simple para salvar um objeto armazenamento com nenhuma substorages, o StgOpenStorage função aceita o seguinte sinalizador combinações como válido modos in a grfMode parâmetro: STGM_SIMPLE|STGM_READWRITE|STGM_SHARE_EXCLUSIVE e STGM_SIMPLE|STGM_READ|STGM_SHARE_EXCLUSIVE.

Para suporte a única-gravador, Multi-Reader, direcionar modo, a seguinte são combinações sinalizador válido modos na grfMode parâmetro: STGM_READWRITE|STGM_SHARE_DENY_WRITE e STGM_READ|STGM_SHARE_DENY_NONE.

Abrindo um objeto armazenamento no ler e / ou modo de gravação sem negar permissão para outras pessoas (o gravador grfMode parâmetro especifica STGM_SHARE_DENY_WRITE) pode ser uma operação demorada porque o StgOpenStorage chamar deve fazer um instantâneo do objeto armazenamento inteira.

Aplicativos geralmente tentam aberto objetos armazenamento com o seguinte acessar permissões.

STGM_READ_WRITE | STGM_SHARE_DENY_WRITE 
 // transacted vs. direct mode omitted for exposition 

Se o aplicativo for bem-sucedido, ele nunca precisará fazer copiar um instantâneo. Se ele falhar, o aplicativo pode reverter ao uso de permissões e tornar copiar um instantâneo.

STGM_READ_WRITE 
 // transacted vs. direct mode omitted for exposition 

Neste maiúsculas e minúsculas, o aplicativo deve prompt o usuário antes de fazer um demorado copiar. Como alternativa, se o documento semântica de compartilhamento implícita pelos modos acessar são apropriado, o aplicativo poderia tentar aberto o armazenamento usando a seguinte sintaxe.

STGM_READ | STGM_SHARE_DENY_WRITE 
 // transacted vs. direct mode omitted for exposition 

Neste maiúsculas e minúsculas, se o aplicativo for bem-sucedido, copiar um instantâneo será não foram feita porque STGM_SHARE_DENY_WRITE foi especificado, negando outras acesso de gravação.

Para reduzir a despesa de copiar um instantâneo, aplicativos pode aberto objetos armazenamento (modo prioridadegrfMode Especifica STGM_PRIORITY).

O snbExclude parâmetro especifica um conjunto de nomes elemento nesse objeto armazenamento que devem ser esvaziada como o objeto armazenamento é aberto: Fluxos estão definidos para um tamanho de zero; armazenamento objetos têm todos os seus elementos removidos. Excluindo determinados fluxos, a despesa de copiar um instantâneo pode ser reduzida significativamente. Quase sempre, esta abordagem é usada depois abrindo o objeto armazenamento no modo prioridade e, em seguida, completamente lendo os elementos agora-excluídos na memória. Este abertura modo prioridade anterior de objeto de armazenamento deve ser passada por meio de pstgPriority parâmetro para remover a exclusão implícita pela prioridade modo. O aplicativo chamado é responsável por reescrever o conteúdo de itens excluídos antes de confirmar. Portanto, essa técnica é provavelmente somente útil para aplicativos cujos documentos não requerem constante acessar aos seus objetos armazenamento enquanto eles estão ativo.

Passando para esta função qualquer inválido e, em algumas circunstâncias, NULL ponteiros resulta em terminação inesperada do aplicativo.

Para determinar se a plataforma oferece suporte a essa função, consulte Determinando suporte COM APIs.

Requirements

Header	objbase.h
Library	ole32.lib
Windows Embedded CE	Windows CE 2.0 and later
Windows Mobile	Windows Mobile Version 5.0 and later

See Also

Reference

IStorage::OpenStorage