IStream

9/8/2008

O IStream interface oferece suporte a ler e gravar dados a transmitir objetos. Fluxo objetos contêm os dados em um objeto armazenamento estruturado, onde armazenamentos fornecem a estrutura.

Dados simples podem ser gravados diretamente para um transmitir, mas a maioria das freqüentes, os fluxos são elementos aninhados em um objeto armazenamento. Eles são semelhantes às padrão arquivos.

O IStream interface Define métodos semelhantes para as funções arquivo MS-DOS FAT. De exemplo, cada objeto transmitir tem seus próprios direitos acessar e um ponteiro de busca.

A principal diferença entre um objeto transmitir e um arquivo DOS é que Fluxos não são abertos usando uma identificador de arquivo, mas através de um IStream ponteiro interface.

Os métodos essa interface apresentam dados do seu objeto como um contíguo seqüência de bytes que você pode ler ou gravação.

Existem também métodos para confirmar e reverter alterações em fluxos aberto no modo de transação e métodos para restringir acessar para um intervalo de bytes na transmitir.

Fluxos podem permanecer aberto por longos períodos de tempo sem consumir recursos sistema de arquivos. O IStream::Release método é semelhante ao fechar função em um arquivo. Uma vez liberado, o objeto transmitir é não mais válido e não pode ser usado.

Clientes do assíncrono monikers podem escolher entre um dados-receber Ou dados-enviar modelo para conduzir um assíncrono IMoniker::BindToStorage operação e para o recebimento assíncrono notificações.

A seguinte tabela mostra uma comparação entre o comportamento do assíncrono ISequentialStream::Read método e IStream::Seek Chamadas retornados em IBindStatusCallback::OnDataAvailable Nos modelos dois baixar.

Chamar método IStream	Comportamento em dados-receber modelo	Comportamento em dados-enviar modelo
Leitura é chamado para ler dados parciais, that is, nem todos os disponível dados.	Retorna S_OK. O cliente deve continuar a ler disponível todos os dados antes de retornar a partir de IBindStatusCallback::OnDataAvailable método senão a operação de ligação estiver bloqueada, ou seja, ler até S_FALSE ou E_PENDING é retornado.	Retorna S_OK. Mesmo se o cliente retorna do IBindStatusCallback::OnDataAvailable Nesta apontar o operação de ligação continua e IBindStatusCallback::OnDataAvailable será chamado novamente repetidamente até que a ligação termina.
Leitura é chamado para ler todos os disponível dados.	Retorna E_PENDING se o operação de ligação não foi concluída, e IBindStatusCallback::OnDataAvailable será chamado novamente quando mais dados está disponível.	Mesmo que dados-modelo de recebimento.
Leitura é chamado para ler todos os disponível dados e o operação de ligação é sobre (Fim - de - arquivo).	Retorna S_FALSE. Haverá uma chamar subseqüente para IBindStatusCallback::OnDataAvailable Com o grfBSC sinalizador definido como BSCF_LASTDATANOTIFICATION.	Mesmo que dados-modelo de recebimento.
Busca é chamado.	Busca Não trabalho em dados-modelo de recebimento.	Busca Não trabalho em dados-enviar modelo.

Quando a implementar

Implementar IStream Em um aplicativo contêiner ou objeto quando você exigem funcionalidade não fornecida pela implementação de arquivo composto COM.

A especificação de IStream Define mais funcionalidade que suporta a implementação COM.

Se você estiver criando um objeto transmitir que é maior do que o heap no memória da sua máquina e você estiver usando um identificador global memória, a implementação arquivo composto chama o GlobalRealloc função internamente sempre que ele precisa mais memória, que pode ser extremamente ineficiente.

Neste maiúsculas e minúsculas, a solução preferencial é implementar um IStream que usa memória alocada pelo O VirtualAlloc função instead of GlobalAlloc.

Este pode reserva uma grande parte de espaço de endereço virtual e, em seguida, memória confirmação de que espaço de endereço como exigido. Nenhum copiando dados ocorre e memória é confirmada somente conforme ele é necessário.

Para obter mais informações, consulte IStream - de implementação de arquivo composto.

Observação

A maioria dos recipientes não implementar o ISequentialStream interface como um separar interface e você não é exigido para fornecê-lo separadamente even if você fornecer um IStream implementação.

Observação

De exemplo, a implementação arquivo composto de armazenamento estruturado não tiver êxito em um Falha de QueryInterface Para ISequentialStream Mas ele inclui o Leitura e Gravar Métodos através de IStream ponteiro interface.

Observação

O mesmo é verdadeiro para a implementação NTFS Native Structured Storage.

Quando usar

Chamar os métodos de IStream interface a partir de um contêiner ou aplicativo para ler e gravação de dados para um objeto. Como transmitir objetos podem ser empacotados para outros processos, os aplicativos podem compartilhar os dados no armazenamento objetos sem ter que usar memória global.

Métodos

A seguinte tabela mostra os métodos para esta interface no ordem alfabética.

Método	Descrição
Clone	Cria um novo objeto de fluxo com sua própria ponteiro buscar que cita o mesmo bytes como o original transmitir.
Confirmar	Garante que qualquer as alterações feitas a um objeto transmitir aberto no modo de transação são refletidas no objeto de armazenamento pai. Se o objeto transmitir é aberto no direcionar modo, este método não tem nenhum efeito Other Than liberando memória todos os buffers para o próximo nível objeto armazenamento. A implementação arquivo composto OLE de fluxos não não suporte abrindo fluxos em modo transacionado.
CopyTo	Copia um número especificado de bytes do atual ponteiro buscar na transmitir para o atual ponteiro buscar em transmitir outro.
LockRegion	Restringe acessar para um intervalo especificado de bytes na transmitir. Suporte a essa funcionalidade é opcional, pois alguns sistemas arquivo não fornecem-lo.
Leitura	Lê um número especificado de bytes a partir de objeto de fluxo em memória, começando a atual ponteiro buscar.
Reverter	Descarta todas as alterações que foram feitas para transmitir um transacionado desde o último IStream::Commit chamar. Este método não tem nenhum efeito no aberto fluxos em direcionar fluxos usando a OLE e modo composto implementação arquivo de IStream::Revert.
Busca	Altera o ponteiro de busca para um nova localidade relativo para o atual busca ponteiro ou o início ou final da transmitir.
SetSize	Redimensiona do objeto transmitir.
STAT	Recupera o STATSTG estrutura para este objeto transmitir.
UnlockRegion	Remove a restrição acessar em um intervalo de bytes anteriormente restringidos com IStream::LockRegion.
Gravar	Grava um número especificado de bytes para o objeto transmitir começando a atual ponteiro buscar.

Remarks

Para determinar se a plataforma oferece suporte a esta interface, consulte Determinando suporte COM APIs.

Requisitos

Header	objidl.h, objidl.idl
Library	ole32.lib, uuid.lib
Windows Embedded CE	Windows CE 2.0 and later
Windows Mobile	Windows Mobile Version 5.0 and later