Fonction StgOpenStorage (coml2api.h)
La fonction StgOpenStorage ouvre un objet de stockage racine existant dans le système de fichiers. Utilisez cette fonction pour ouvrir des fichiers composés. Ne l’utilisez pas pour ouvrir des répertoires, des fichiers ou des catalogues récapitulatifs. Les objets de stockage imbriqués ne peuvent être ouverts qu’à l’aide de leur méthode IStorage ::OpenStorage parente.
Syntaxe
HRESULT StgOpenStorage(
[in] const WCHAR *pwcsName,
[in] IStorage *pstgPriority,
[in] DWORD grfMode,
[in] SNB snbExclude,
[in] DWORD reserved,
[out] IStorage **ppstgOpen
);
Paramètres
[in] pwcsName
Pointeur vers le chemin du fichier de chaîne Unicode terminé par null qui contient l’objet de stockage à ouvrir. Ce paramètre est ignoré si le paramètre pstgPriority n’a pas la valeur NULL.
[in] pstgPriority
Pointeur vers l’interface IStorage qui doit avoir la valeur NULL. S’il n’est pas NULL, ce paramètre est utilisé comme décrit ci-dessous dans la section Remarques.
Une fois stgOpenStorage retourné, 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.
[in] snbExclude
Si ce n’est pas NULL, pointeur vers un bloc d’éléments dans le stockage à exclure lorsque l’objet de stockage est ouvert. L’exclusion se produit, qu’une copie instantané se produise ou non à l’ouverture. Peut être NULL.
[in] reserved
Indique réservé pour une utilisation future ; doit être égal à zéro.
[out] ppstgOpen
Pointeur vers une variable de pointeur IStorage* qui reçoit le pointeur d’interface vers le stockage ouvert.
Valeur retournée
La fonction StgOpenStorage peut également retourner des erreurs de système de fichiers ou des erreurs système encapsulées dans un HRESULT. Pour plus d’informations, consultez Stratégies de gestion des erreurs et Gestion des erreurs inconnues.
Remarques
La fonction StgOpenStorage ouvre l’objet de stockage racine spécifié en fonction du mode d’accès dans le paramètre grfMode et, si elle réussit, fournit un pointeur IStorage vers l’objet de stockage ouvert dans le paramètre ppstgOpen .
Pour prendre en charge le mode simple d’enregistrement d’un objet de stockage sans sous-stockage, la fonction StgOpenStorage accepte l’une des deux combinaisons d’indicateurs suivantes comme modes valides dans le paramètre grfMode .
STGM_SIMPLE | STGM_READWRITE | STGM_SHARE_EXCLUSIVE
STGM_SIMPLE | STGM_READ | STGM_SHARE_EXCLUSIVE
Pour prendre en charge le mode direct à écriture unique, multilecteur, la première combinaison d’indicateurs est le paramètre grfMode valide pour l’enregistreur. La deuxième combinaison d’indicateurs est valide pour les lecteurs.
STGM_DIRECT_SWMR | STGM_READWRITE | STGM_SHARE_DENY_WRITE
STGM_DIRECT_SWMR | STGM_READ | STGM_SHARE_DENY_NONE
En mode direct, l’une des trois combinaisons suivantes est valide.
STGM_DIRECT | STGM_READWRITE | STGM_SHARE_EXCLUSIVE
STGM_DIRECT | STGM_READ | STGM_SHARE_DENY_WRITE
STGM_DIRECT | STGM_READ | STGM_SHARE_EXCLUSIVE
STGM_READWRITE | STGM_SHARE_DENY_WRITE
// transacted versus direct mode omitted for exposition
L’application peut revenir à l’utilisation des autorisations et effectuer une copie instantané, si les autorisations d’accès précédentes échouent. L’application doit inviter l’utilisateur avant d’effectuer une copie fastidieuse.
STGM_READWRITE
// transacted versus direct mode omitted for exposition
Si la sémantique de partage de documents impliquée par les modes d’accès est appropriée, l’application peut essayer d’ouvrir le stockage comme suit. Dans ce cas, si l’application réussit, une copie instantané n’aura pas été effectuée (car STGM_SHARE_DENY_WRITE a été spécifié, refusant à d’autres personnes l’accès en écriture).
STGM_READ | STGM_SHARE_DENY_WRITE
// transacted versus direct mode omitted for exposition
Le paramètre pstgPriority est destiné à faciliter la tâche des appelants qui remplacent un objet de stockage existant, souvent ouvert en mode prioritaire, par un nouvel objet de stockage ouvert sur le même fichier, mais dans un autre mode. Lorsque pstgPriority n’a pas la valeur NULL, il est utilisé pour spécifier le nom de fichier au lieu de pwcsName, qui est ignoré. Toutefois, il est recommandé que les applications passent toujours la valeur NULL pour pstgPriority , car StgOpenStorage libère l’objet dans certaines circonstances et ne le libère pas dans d’autres circonstances. En particulier, si la fonction retourne un résultat d’échec, il n’est pas possible pour l’appelant de déterminer si l’objet de stockage a été libéré ou non.
Les fonctionnalités du paramètre pstgPriority peuvent être dupliquées par l’appelant de manière plus sécurisée, comme illustré dans l’exemple suivant :
// Replacement for:
// HRESULT hr = StgOpenStorage(
// NULL, pstgPriority, grfMode, NULL, 0, &pstgNew);
STATSTG statstg;
HRESULT hr = pstgPriority->Stat(&statstg, 0);
pStgPriority->Release();
pStgPriority = NULL;
if (SUCCEEDED(hr))
{
hr = StgOpenStorage(statstg.pwcsName, NULL, grfMode, NULL, 0, &pstgNew);
}
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 |