Función CreateStreamOnHGlobal (combaseapi.h)
La función CreateStreamOnHGlobal crea un objeto de secuencia que usa un identificador de memoria HGLOBAL para almacenar el contenido de la secuencia. Este objeto es la implementación proporcionada por OLE de la interfaz IStream .
El objeto de flujo devuelto admite la lectura y escritura, no se realiza transacciones y no admite el bloqueo de regiones. El objeto llama a la función GlobalReAlloc para aumentar el bloque de memoria según sea necesario.
Sintaxis
HRESULT CreateStreamOnHGlobal(
[in] HGLOBAL hGlobal,
[in] BOOL fDeleteOnRelease,
[out] LPSTREAM *ppstm
);
Parámetros
[in] hGlobal
Identificador de memoria asignado por la función GlobalAlloc , o si null , se asignará un nuevo identificador en su lugar. El identificador debe asignarse como desplazable y no discardable.
[in] fDeleteOnRelease
Valor que indica si el identificador subyacente de este objeto de secuencia se debe liberar automáticamente cuando se libera el objeto de secuencia. Si se establece en FALSE, el autor de la llamada debe liberar hGlobal después de la versión final. Si se establece en TRUE, la versión final liberará automáticamente el identificador subyacente. Vea los comentarios para obtener más información sobre el caso en el que fDeleteOnRelease es FALSE.
[out] ppstm
Dirección de la variable de puntero IStream* que recibe el puntero de interfaz al nuevo objeto de secuencia. Su valor no puede ser NULL.
Valor devuelto
Esta función admite los valores devueltos estándar E_INVALIDARG y E_OUTOFMEMORY, así como lo siguiente.
Comentarios
Si hGlobal es NULL, la función asigna un nuevo identificador de memoria y la secuencia está inicialmente vacía.
Si hGlobal no es NULL, el contenido inicial de la secuencia es el contenido actual del bloque de memoria. Por lo tanto, CreateStreamOnHGlobal se puede usar para abrir una secuencia existente en la memoria. El identificador de memoria y su contenido no se modifican mediante la creación del nuevo objeto de secuencia.
El tamaño inicial de la secuencia es el tamaño de hGlobal tal como lo devuelve la función GlobalSize . Debido al redondeo, esto no es necesariamente el mismo tamaño que se asignó originalmente para el controlador. Si el tamaño lógico de la secuencia es importante, siga la llamada a esta función con una llamada al método IStream::SetSize .
La nueva posición de búsqueda inicial del objeto de secuencia es el principio de la secuencia.
Después de crear el objeto stream con CreateStreamOnHGlobal, llame a GetHGlobalFromStream para recuperar el identificador de memoria asociado al objeto stream.
Si se pasa un identificador de memoria a CreateStreamOnHGlobal o si se llama a GetHGlobalFromStream , el autor de la llamada puede acceder directamente al identificador de memoria de esta función mientras el objeto de secuencia lo sigue usando. Se debe tener precaución adecuada en el uso de esta funcionalidad y sus implicaciones:
- No libere el identificador de memoria hGlobal durante la duración del objeto de secuencia. Se debe llamar a IStream::Release antes de liberar el identificador de memoria.
- No llame a GlobalReAlloc para cambiar el tamaño del identificador de memoria durante la duración del objeto de secuencia o sus clones. Esto puede provocar bloqueos en la aplicación o daños en la memoria. Evite crear varios objetos de secuencia por separado en el mismo identificador de memoria, ya que los métodos IStream::Write e IStream::SetSize pueden llamar internamente a GlobalReAlloc. El método IStream::Clone se puede usar para crear un nuevo objeto de secuencia basado en el mismo identificador de memoria que coordinará correctamente su acceso con el objeto de secuencia original.
- Si es posible, evite tener acceso al bloque de memoria durante la duración del objeto de secuencia, ya que el objeto puede llamar internamente a GlobalReAlloc y no realizar suposiciones sobre su tamaño y ubicación. Si se debe tener acceso al bloque de memoria, las llamadas de acceso a la memoria deben estar rodeadas por llamadas a GlobalLock y GlobalUnLock.
- Evite llamar a los métodos del objeto mientras tiene el identificador de memoria bloqueado con GlobalLock. Esto puede hacer que las llamadas al método produzcan un error de forma impredecible.
El identificador de memoria pasado como parámetro hGlobal debe asignarse como extraíble y no discardable, como se muestra en el ejemplo siguiente:
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 aceptará un identificador de memoria asignado con GMEM_FIXED, pero no se recomienda este uso. Los HGLOBALs asignados con GMEM_FIXED no son realmente controladores y su valor puede cambiar cuando se reasignan. Si el identificador de memoria se asignó con GMEM_FIXED y fDeleteOnRelease es FALSE, el llamador debe llamar a GetHGlobalFromStream para obtener el identificador correcto para liberarlo.
Antes de Windows 7 y Windows Server 2008 R2, esta implementación no tenía ninguna memoria al llamar a GlobalReAlloc para aumentar el bloque de memoria. Aumentar el tamaño de la secuencia con IStream::SetSize o escribiendo en una ubicación situada más allá del final actual de la secuencia puede dejar partes de la memoria recién asignada sin inicializar.
Requisitos
| Cliente mínimo compatible | Windows 2000 Professional [aplicaciones de escritorio | Aplicaciones para UWP] |
| Servidor mínimo compatible | Windows 2000 Server [aplicaciones de escritorio | Aplicaciones para UWP] |
| Plataforma de destino | Windows |
| Encabezado | combaseapi.h |
| Library | Ole32.lib |
| Archivo DLL | Ole32.dll |
Consulte también
Comentarios
Próximamente: A lo largo de 2024 iremos eliminando gradualmente GitHub Issues como mecanismo de comentarios sobre el contenido y lo sustituiremos por un nuevo sistema de comentarios. Para más información, vea: https://aka.ms/ContentUserFeedback.
Enviar y ver comentarios de