StgOpenStorageOnILockBytes, fonction (coml2api.h)
La fonction StgOpenStorageOnILockBytes ouvre un objet de stockage existant qui ne réside pas dans un fichier disque, mais qui a un tableau d’octets sous-jacent fourni par l’appelant.
Syntaxe
HRESULT StgOpenStorageOnILockBytes(
[in] ILockBytes *plkbyt,
[in] IStorage *pstgPriority,
[in] DWORD grfMode,
[in] SNB snbExclude,
[in] DWORD reserved,
[out] IStorage **ppstgOpen
);
Paramètres
[in] plkbyt
Pointeur ILockBytes vers l’objet de tableau d’octets sous-jacent qui contient l’objet de stockage à ouvrir.
[in] pstgPriority
Pointeur vers l’interface IStorage qui doit être NULL. S’il n’est pas NULL, ce paramètre est utilisé comme décrit ci-dessous dans la section Notes.
Après le retour de StgOpenStorageOnILockBytes , l’objet de stockage spécifié dans pStgPriority peut avoir été libéré et ne doit plus être utilisé.
[in] grfMode
Spécifie le mode d’accès à utiliser pour ouvrir l’objet de stockage. Pour plus d’informations, consultez Constantes STGM et la section Remarques ci-dessous.
[in] snbExclude
Peut être NULL. S’il n’est pas NULL, ce paramètre pointe vers un bloc d’éléments dans ce stockage qui doivent être exclus à mesure que l’objet de stockage est ouvert. Cette exclusion se produit indépendamment du fait qu’une copie instantané se produit à l’ouverture.
[in] reserved
Indique réservé pour une utilisation ultérieure ; doit être égal à zéro.
[out] ppstgOpen
Pointe vers l’emplacement d’un pointeur IStorage vers le stockage ouvert en cas de retour réussi.
Valeur retournée
La fonction StgOpenStorageOnILockBytes peut également retourner des erreurs de système de fichiers ou des erreurs système encapsulées dans une erreur HRESULT ou une erreur d’interface ILockBytes . Consultez Stratégies de gestion des erreurs et Gestion des erreurs inconnues.
Remarques
StgOpenStorageOnILockBytes ouvre l’objet de stockage racine spécifié. Un pointeur vers l’interface IStorage sur l’objet de stockage ouvert est fourni via le paramètre ppstgOpen .
L’objet de stockage doit avoir été créé précédemment par la fonction StgCreateDocfileOnILockBytes .
À l’exception de la spécification d’un objet de tableau d’octets fourni par le programmeur, StgOpenStorageOnILockBytes est similaire à la fonction StgOpenStorage . L’objet de stockage est ouvert en fonction des modes d’accès dans le paramètre grfMode , sous réserve des restrictions suivantes :
Le comportement du mode de partage et l’isolation transactionnelle dépendent de l’implémentation ILockBytes prenant en charge LockRegion et UnlockRegion avec LOCK_ONLYONCE sémantique. Les implémentations peuvent indiquer au stockage structuré qu’elles prennent en charge cette fonctionnalité en définissant le bit LOCK_ONLYONCE dans le membre grfLocksSupported de STATSTG. Si une implémentation ILockBytes ne prend pas en charge cette fonctionnalité, les modes de partage ne sont pas appliqués et les validations transactionnelles au niveau racine ne se coordonnent pas correctement avec d’autres instances transactionnelles ouvertes sur le même tableau d’octets. Les applications qui utilisent une implémentation ILockBytes qui ne prend pas en charge le verrouillage de région, comme l’implémentation CreateStreamOnHGlobal , doivent éviter d’ouvrir plusieurs instances simultanées sur le même tableau d’octets.
StgOpenStorageOnILockBytes ne prend pas en charge le mode simple. L’indicateur STGM_SIMPLE, s’il est présent, est ignoré.
Le paramètre pStgPriority est destiné à des raisons pratiques pour les appelants qui remplacent un objet de stockage existant, souvent ouvert en mode prioritaire, par un nouvel objet de stockage ouvert sur le même tableau d’octets. Contrairement au paramètre pStgPriority de StgOpenStorage, ce paramètre n’affecte pas l’opération d’ouverture effectuée par StgOpenStorageOnILockBytes et est simplement un objet de stockage existant que l’appelant souhaite libérer. Les appelants doivent toujours passer null pour ce paramètre, car StgOpenStorageOnILockBytes libère l’objet dans certaines circonstances et ne le libère pas dans d’autres circonstances. L’utilisation du paramètre pStgPriority peut être dupliquée par l’appelant de manière plus sûre en libérant plutôt l’objet avant d’appeler StgOpenStorageOnILockBytes, comme illustré dans l’exemple suivant :
// Replacement for:
// HRESULT hr = StgOpenStorageOnILockBytes(
// plkbyt, pStgPriority, grfMode, NULL, 0, &pstgNew);
pStgPriority->Release();
pStgPriority = NULL;
hr = StgOpenStorage(plkbyt, NULL, grfMode, NULL, 0, &pstgNew);
Pour plus d’informations, consultez StgOpenStorage.
Configuration requise
| Condition requise | Valeur |
|---|---|
| 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 | coml2api.h (inclure Objbase.h) |
| Bibliothèque | Ole32.lib |
| DLL | Ole32.dll |