Função CreateStreamOnHGlobal (combaseapi.h)
A função CreateStreamOnHGlobal cria um objeto de fluxo que usa um identificador de memória HGLOBAL para armazenar o conteúdo do fluxo. Esse objeto é a implementação fornecida pelo OLE da interface IStream .
O objeto de fluxo retornado dá suporte à leitura e à gravação, não é transacionado e não dá suporte ao bloqueio de região. O objeto chama a função GlobalReAlloc para aumentar o bloco de memória conforme necessário.
Sintaxe
HRESULT CreateStreamOnHGlobal(
[in] HGLOBAL hGlobal,
[in] BOOL fDeleteOnRelease,
[out] LPSTREAM *ppstm
);
Parâmetros
[in] hGlobal
Um identificador de memória alocado pela função GlobalAlloc ou se NULL um novo identificador deve ser alocado. O identificador deve ser alocado como movêvel e não confiável.
[in] fDeleteOnRelease
Um valor que indica se o identificador subjacente para esse objeto de fluxo deve ser liberado automaticamente quando o objeto de fluxo é liberado. Se definido como FALSE, o chamador deverá liberar o hGlobal após a versão final. Se definido como TRUE, a versão final liberará automaticamente o identificador subjacente. Confira os Comentários para obter mais discussões sobre o caso em que fDeleteOnRelease é FALSE.
[out] ppstm
O endereço da variável de ponteiro IStream* que recebe o ponteiro de interface para o novo objeto de fluxo. Seu valor não pode ser NULL.
Valor retornado
Essa função dá suporte aos valores de retorno padrão E_INVALIDARG e E_OUTOFMEMORY, bem como os seguintes.
Comentários
Se hGlobal for NULL, a função alocará um novo identificador de memória e o fluxo estará inicialmente vazio.
Se hGlobal não for NULL, o conteúdo inicial do fluxo será o conteúdo atual do bloco de memória. Assim, CreateStreamOnHGlobal pode ser usado para abrir um fluxo existente na memória. O identificador de memória e seu conteúdo não são perturbados com a criação do novo objeto de fluxo.
O tamanho inicial do fluxo é o tamanho de hGlobal , conforme retornado pela função GlobalSize . Devido ao arredondamento, esse não é necessariamente o mesmo tamanho que foi originalmente alocado para o identificador. Se o tamanho lógico do fluxo for importante, siga a chamada para essa função com uma chamada para o método IStream::SetSize .
A posição de busca inicial do novo objeto de fluxo é o início do fluxo.
Depois de criar o objeto de fluxo com CreateStreamOnHGlobal, chame GetHGlobalFromStream para recuperar o identificador de memória associado ao objeto de fluxo.
Se um identificador de memória for passado para CreateStreamOnHGlobal ou se GetHGlobalFromStream for chamado, o identificador de memória dessa função poderá ser acessado diretamente pelo chamador enquanto ele ainda estiver em uso pelo objeto de fluxo. A cautela apropriada deve ser exercida no uso dessa funcionalidade e suas implicações:
- Não libere o identificador de memória hGlobal durante o tempo de vida do objeto de fluxo. IStream::Release deve ser chamado antes de liberar o identificador de memória.
- Não chame GlobalReAlloc para alterar o tamanho do identificador de memória durante o tempo de vida do objeto de fluxo ou seus clones. Isso pode causar falhas no aplicativo ou corrupção de memória. Evite criar vários objetos de fluxo separadamente no mesmo identificador de memória, pois os métodos IStream::Write e IStream::SetSize podem chamar internamente GlobalReAlloc. O método IStream::Clone pode ser usado para criar um novo objeto de fluxo com base no mesmo identificador de memória que coordenará corretamente seu acesso com o objeto de fluxo original.
- Se possível, evite acessar o bloco de memória durante o tempo de vida do objeto de fluxo, pois o objeto pode chamar internamente GlobalReAlloc e não fazer suposições sobre seu tamanho e localização. Se o bloco de memória precisar ser acessado, as chamadas de acesso à memória deverão ser cercadas por chamadas para GlobalLock e GlobalUnLock.
- Evite chamar os métodos do objeto enquanto você tem o identificador de memória bloqueado com GlobalLock. Isso pode fazer com que as chamadas de método falhem de forma imprevisível.
O identificador de memória passado como o parâmetro hGlobal deve ser alocado como móvel e não confiável, conforme mostrado no exemplo a seguir:
HGLOBAL hMem = ::GlobalAlloc(GMEM_MOVEABLE,iSize);
if (!hMem)
AfxThrowMemoryException();
LPVOID pImage = ::GlobalLock(hMem);
... // Fill memory
::GlobalUnlock(hMem);
CComPtr<IStream> spStream;
HRESULT hr = ::CreateStreamOnHGlobal(hMem,FALSE,&spStream);
CreateStreamOnHGlobal aceitará um identificador de memória alocado com GMEM_FIXED, mas esse uso não é recomendado. HGLOBALs alocados com GMEM_FIXED não são realmente identificadores e seu valor pode mudar quando eles são realocados. Se o identificador de memória foi alocado com GMEM_FIXED e fDeleteOnRelease for FALSE, o chamador deverá chamar GetHGlobalFromStream para obter o identificador correto para liberá-lo.
Antes do Windows 7 e do Windows Server 2008 R2, essa implementação não tinha memória zero ao chamar GlobalReAlloc para aumentar o bloco de memória. Aumentar o tamanho do fluxo com IStream::SetSize ou gravando em um local após o final atual do fluxo pode deixar partes da memória recém-alocada não inicializada.
Requisitos
| 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 | combaseapi.h |
| Biblioteca | Ole32.lib |
| DLL | Ole32.dll |