CreateStreamOnHGlobal, fonction (combaseapi.h)
La fonction CreateStreamOnHGlobal crée un objet de flux qui utilise un handle de mémoire HGLOBAL pour stocker le contenu du flux. Cet objet est l’implémentation fournie par OLE de l’interface IStream .
L’objet stream retourné prend en charge la lecture et l’écriture, n’est pas traité et ne prend pas en charge le verrouillage de région. L’objet appelle la fonction GlobalReAlloc pour développer le bloc de mémoire en fonction des besoins.
Syntaxe
HRESULT CreateStreamOnHGlobal(
[in] HGLOBAL hGlobal,
[in] BOOL fDeleteOnRelease,
[out] LPSTREAM *ppstm
);
Paramètres
[in] hGlobal
Un handle de mémoire alloué par la fonction GlobalAlloc ou, si NULL , un nouveau handle doit être alloué à la place. Le handle doit être alloué comme pouvant être déplacé et nondiscardable.
[in] fDeleteOnRelease
Valeur qui indique si le handle sous-jacent de cet objet de flux doit être libéré automatiquement lorsque l’objet stream est libéré. Si la valeur est FALSE, l’appelant doit libérer le hGlobal après la version finale. Si la valeur est TRUE, la version finale libère automatiquement le handle sous-jacent. Consultez les remarques pour plus d’informations sur le cas où fDeleteOnRelease est FALSE.
[out] ppstm
Adresse de la variable de pointeur IStream* qui reçoit le pointeur d’interface vers le nouvel objet stream. Sa valeur ne peut pas être NULL.
Valeur retournée
Cette fonction prend en charge les valeurs de retour standard E_INVALIDARG et E_OUTOFMEMORY, ainsi que les éléments suivants.
Notes
Si hGlobal a la valeur NULL, la fonction alloue un nouveau handle de mémoire et le flux est initialement vide.
Si hGlobal n’a pas la valeur NULL, le contenu initial du flux est le contenu actuel du bloc de mémoire. Ainsi, CreateStreamOnHGlobal peut être utilisé pour ouvrir un flux existant en mémoire. Le handle de mémoire et son contenu ne sont pas perturbés par la création de l’objet stream.
La taille initiale du flux est la taille de hGlobal retournée par la fonction GlobalSize . En raison de l’arrondi, il ne s’agit pas nécessairement de la même taille qui a été allouée à l’origine pour le handle. Si la taille logique du flux est importante, suivez l’appel de cette fonction avec un appel à la méthode IStream::SetSize .
La position de recherche initiale du nouvel objet stream est le début du flux.
Après avoir créé l’objet stream avec CreateStreamOnHGlobal, appelez GetHGlobalFromStream pour récupérer le handle de mémoire associé à l’objet stream.
Si un handle de mémoire est passé à CreateStreamOnHGlobal ou si GetHGlobalFromStream est appelé, le handle de mémoire de cette fonction est directement accessible par l’appelant pendant qu’il est toujours utilisé par l’objet stream. La prudence appropriée doit être exercée dans l’utilisation de cette capacité et de ses implications :
- Ne libérez pas le handle de mémoire hGlobal pendant la durée de vie de l’objet stream. IStream::Release doit être appelé avant de libérer le handle de mémoire.
- N’appelez pas GlobalReAlloc pour modifier la taille du handle de mémoire pendant la durée de vie de l’objet de flux ou de ses clones. Cela peut entraîner des blocages d’application ou une altération de la mémoire. Évitez de créer plusieurs objets de flux de flux séparément sur le même handle de mémoire, car les méthodes IStream::Write et IStream::SetSize peuvent appeler en interne GlobalReAlloc. La méthode IStream::Clone peut être utilisée pour créer un objet stream basé sur le même handle de mémoire qui coordonnera correctement son accès avec l’objet stream d’origine.
- Si possible, évitez d’accéder au bloc de mémoire pendant la durée de vie de l’objet stream, car l’objet peut appeler GlobalReAlloc en interne et ne pas faire d’hypothèses sur sa taille et son emplacement. Si le bloc de mémoire doit être accessible, les appels d’accès à la mémoire doivent être entourés d’appels à GlobalLock et GlobalUnLock.
- Évitez d’appeler les méthodes de l’objet lorsque le handle de mémoire est verrouillé avec GlobalLock. Cela peut entraîner l’échec des appels de méthode de manière imprévisible.
Le handle de mémoire passé en tant que paramètre hGlobal doit être alloué en tant que mobile et nondiscardable, comme illustré dans l’exemple suivant :
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 accepte un handle de mémoire alloué avec GMEM_FIXED, mais cette utilisation n’est pas recommandée. Les valeurs HGLOBAL allouées avec GMEM_FIXED ne sont pas vraiment des handles et leur valeur peut changer lorsqu’elles sont réaffectées. Si le handle de mémoire a été alloué avec GMEM_FIXED et que fDeleteOnRelease a la valeur FALSE, l’appelant doit appeler GetHGlobalFromStream pour obtenir le handle correct afin de le libérer.
Avant Windows 7 et Windows Server 2008 R2, cette implémentation ne disposait pas de zéro mémoire lors de l’appel de GlobalReAlloc pour augmenter le bloc de mémoire. L’augmentation de la taille du flux avec IStream::SetSize ou en écrivant dans un emplacement au-delà de la fin actuelle du flux peut laisser des parties de la mémoire nouvellement allouée non initialisées.
Spécifications
| Client minimal pris en charge | Windows 2000 Professionnel [applications de bureau | Applications UWP] |
| Serveur minimal pris en charge | Windows 2000 Server [applications de bureau | Applications UWP] |
| Plateforme cible | Windows |
| En-tête | combaseapi.h |
| Bibliothèque | Ole32.lib |
| DLL | Ole32.dll |