Função StgOpenStorage (coml2api.h)

  • Artigo

A função StgOpenStorage abre um objeto de armazenamento raiz existente no sistema de arquivos. Use essa função para abrir arquivos compostos. Não o use para abrir diretórios, arquivos ou catálogos de resumo. Os objetos de armazenamento aninhados só podem ser abertos usando o método IStorage::OpenStorage pai.

Nota Os aplicativos devem usar a nova função , StgOpenStorageEx, em vez de StgOpenStorage, para aproveitar os recursos avançados e do Armazenamento Estruturado do Windows. Essa função, StgOpenStorage, ainda existe para compatibilidade com aplicativos em execução no Windows 2000.
 

Sintaxe

HRESULT StgOpenStorage(
  [in]  const WCHAR *pwcsName,
  [in]  IStorage    *pstgPriority,
  [in]  DWORD       grfMode,
  [in]  SNB         snbExclude,
  [in]  DWORD       reserved,
  [out] IStorage    **ppstgOpen
);

Parâmetros

[in] pwcsName

Um ponteiro para o caminho do arquivo de cadeia de caracteres Unicode terminado em nulo que contém o objeto de armazenamento a ser aberto. Esse parâmetro será ignorado se o parâmetro pstgPriority não for NULL.

[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 StgOpenStorage 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.

[in] snbExclude

Se não for NULL, ponteiro para um bloco de elementos no armazenamento a ser excluído à medida que o objeto de armazenamento é aberto. A exclusão ocorre independentemente de uma cópia instantâneo ocorrer ao abrir. Pode ser NULL.

[in] reserved

Indica reservado para uso futuro; deve ser zero.

[out] ppstgOpen

Um ponteiro para uma variável de ponteiro IStorage* que recebe o ponteiro de interface para o armazenamento aberto.

Retornar valor

A função StgOpenStorage também pode retornar 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 StgOpenStorage abre o objeto de armazenamento raiz especificado de acordo com o modo de acesso no parâmetro grfMode e, se bem-sucedida, fornece um ponteiro IStorage para o objeto de armazenamento aberto no parâmetro ppstgOpen .

Para dar suporte ao modo simples para salvar um objeto de armazenamento sem subtorages, a função StgOpenStorage aceita uma das duas combinações de sinalizadores a seguir como modos válidos no parâmetro grfMode .

    STGM_SIMPLE | STGM_READWRITE | STGM_SHARE_EXCLUSIVE

    STGM_SIMPLE | STGM_READ | STGM_SHARE_EXCLUSIVE

Para dar suporte ao gravador único, multireader, modo direto, a primeira combinação de sinalizador é o parâmetro grfMode válido para o gravador. A segunda combinação de sinalizadores é válida para leitores.

    STGM_DIRECT_SWMR | STGM_READWRITE | STGM_SHARE_DENY_WRITE

    STGM_DIRECT_SWMR | STGM_READ | STGM_SHARE_DENY_NONE

No modo direto, uma das três combinações a seguir é válida.

    STGM_DIRECT | STGM_READWRITE | STGM_SHARE_EXCLUSIVE

    STGM_DIRECT | STGM_READ | STGM_SHARE_DENY_WRITE

    STGM_DIRECT | STGM_READ | STGM_SHARE_EXCLUSIVE
Nota Abrir um objeto de armazenamento no modo de leitura/gravação sem negar permissão de gravação a outras pessoas (o parâmetro grfMode especifica STGM_SHARE_DENY_WRITE) pode ser uma operação demorada porque a chamada StgOpenStorage deve fazer uma instantâneo de todo o objeto de armazenamento.
 
Os aplicativos geralmente tentam abrir objetos de armazenamento com as seguintes permissões de acesso. Se o aplicativo for bem-sucedido, ele nunca precisará fazer uma cópia instantâneo. 
STGM_READWRITE | STGM_SHARE_DENY_WRITE 
    // transacted versus direct mode omitted for exposition

O aplicativo pode reverter usar as permissões e fazer uma cópia instantâneo, se as permissões de acesso anteriores falharem. O aplicativo deve solicitar ao usuário antes de fazer uma cópia demorada.

STGM_READWRITE 
    // transacted versus direct mode omitted for exposition

Se a semântica de compartilhamento de documentos implícita pelos modos de acesso for apropriada, o aplicativo poderá tentar abrir o armazenamento da seguinte maneira. Nesse caso, se o aplicativo for bem-sucedido, uma cópia instantâneo não terá sido feita (porque STGM_SHARE_DENY_WRITE foi especificado, negando a outras pessoas acesso de gravação).

STGM_READ | STGM_SHARE_DENY_WRITE 
    // transacted versus direct mode omitted for exposition
Nota Para reduzir a despesa de fazer uma cópia instantâneo, os aplicativos podem abrir objetos de armazenamento no modo de prioridade (grfMode especifica STGM_PRIORITY).
 
O parâmetro snbExclude especifica um conjunto de nomes de elementos neste objeto de armazenamento que devem ser esvaziados à medida que o objeto de armazenamento é aberto: os fluxos são definidos como um comprimento de zero; os objetos de armazenamento têm todos os seus elementos removidos. Ao excluir determinados fluxos, a despesa de fazer uma cópia instantâneo pode ser significativamente reduzida. Quase sempre, essa abordagem é usada depois de abrir primeiro o objeto de armazenamento no modo de prioridade e, em seguida, ler completamente os elementos agora excluídos na memória. Essa abertura anterior do modo de prioridade do objeto de armazenamento deve ser passada pelo parâmetro pstgPriority para remover a exclusão implícita pelo modo de prioridade. O aplicativo de chamada é responsável por reescrever o conteúdo dos itens excluídos antes de confirmar. Portanto, essa técnica provavelmente é útil apenas para aplicativos cujos documentos não exigem acesso constante aos objetos de armazenamento enquanto estão ativos.

O parâmetro pstgPriority destina-se como uma conveniência para chamadores que substituem um objeto de armazenamento existente, geralmente um aberto no modo de prioridade, por um novo objeto de armazenamento aberto no mesmo arquivo, mas em um modo diferente. Quando pstgPriority não é NULL, ele é usado para especificar o nome do arquivo em vez de pwcsName, que é ignorado. No entanto, é recomendável que os aplicativos sempre passem NULL para pstgPriority porque StgOpenStorage libera o objeto em algumas circunstâncias e não o libera em outras circunstâncias. Em particular, se a função retornar um resultado de falha, não será possível que o chamador determine se o objeto de armazenamento foi liberado ou não.

A funcionalidade do parâmetro pstgPriority pode ser duplicada pelo chamador de maneira mais segura, conforme mostrado no exemplo a seguir:

// Replacement for:
// HRESULT hr = StgOpenStorage(
//         NULL, pstgPriority, grfMode, NULL, 0, &pstgNew);

STATSTG statstg;
HRESULT hr = pstgPriority->Stat(&statstg, 0);
pStgPriority->Release();
pStgPriority = NULL;
if (SUCCEEDED(hr))
{
    hr = StgOpenStorage(statstg.pwcsName, NULL, grfMode, NULL, 0, &pstgNew);
}

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 coml2api.h (inclua Objbase.h)
Biblioteca Ole32.lib
DLL Ole32.dll

Confira também

IStorage

Stgcreatedocfile

StgOpenStorageEx