StgOpenStorage, fonction (coml2api.h)

Article
09/27/2022
5 minutes de lecture

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écapitulatives. Les objets de stockage imbriqués ne peuvent être ouverts qu’à l’aide de leur méthode IStorage::OpenStorage parente.

Note Les applications doivent utiliser la nouvelle fonction, StgOpenStorageEx, au lieu de StgOpenStorage, pour tirer parti des fonctionnalités de stockage structuré Windows et améliorées. Cette fonction, StgOpenStorage, existe toujours pour la compatibilité avec les applications s’exécutant sur Windows 2000.

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 d’accès 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’est pas NULL.

[in] pstgPriority

Pointeur vers l’interface IStorage qui doit être NULL. Si ce paramètre n’est pas NULL, ce paramètre est utilisé comme décrit ci-dessous dans la section Remarques.

Une fois que StgOpenStorage est 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 du stockage à exclure lorsque l’objet de stockage est ouvert. L’exclusion se produit indépendamment du fait qu’une copie d’instantané se produise sur l’ouverture. Peut être NULL.

[in] reserved

Indique réservé à une utilisation ultérieure ; doit être 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 toutes les erreurs du système de fichiers ou les erreurs système encapsulées dans un HRESULT. Pour plus d’informations, consultez Stratégies de gestion des erreurs et gestion des erreurs inconnues.

Notes

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 à l’objet de stockage ouvert dans le paramètre ppstgOpen .

Pour prendre en charge le mode simple pour l’enregistrement d’un objet de stockage sans sous-historiques, 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 l’enregistreur unique, le mode multireader, le mode direct, 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

Note L’ouverture d’un objet de stockage en mode lecture/écriture sans refuser l’autorisation d’écriture à d’autres personnes (le paramètre grfMode spécifie STGM_SHARE_DENY_WRITE) peut être une opération fastidieuse, car l’appel StgOpenStorage doit effectuer un instantané de l’ensemble de l’objet de stockage.

Les applications essaient souvent d’ouvrir des objets de stockage avec les autorisations d’accès suivantes. Si l’application réussit, elle n’a jamais besoin d’effectuer une copie d’instantané.

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 d’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 implicite 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 d’instantané n’a pas été effectuée (car STGM_SHARE_DENY_WRITE a été spécifiée, refusant à d’autres utilisateurs l’accès en écriture).

STGM_READ | STGM_SHARE_DENY_WRITE 
    // transacted versus direct mode omitted for exposition

Note Pour réduire le coût de création d’une copie d’instantané, les applications peuvent ouvrir des objets de stockage en mode priorité (grfMode spécifie STGM_PRIORITY).

Le paramètre snbExclude spécifie un ensemble de noms d’éléments dans cet objet de stockage à vider lorsque l’objet de stockage est ouvert : les flux sont définis sur une longueur de zéro ; les objets de stockage ont tous leurs éléments supprimés. En excluant certains flux, les dépenses liées à la création d’une copie d’instantané peuvent être considérablement réduites. Presque toujours, cette approche est utilisée après l’ouverture de l’objet de stockage en mode priorité, puis la lecture complète des éléments désormais exclus dans la mémoire. Cette ouverture en mode priorité antérieure de l’objet de stockage doit être transmise via le paramètre pstgPriority pour supprimer l’exclusion implicite par le mode priorité. L’application appelante est chargée de réécrire le contenu des éléments exclus avant de valider. Ainsi, cette technique est très probablement utile uniquement aux applications dont les documents n’ont pas besoin d’un accès constant à leurs objets de stockage pendant qu’ils sont actifs.

Le paramètre pstgPriority est conçu comme une commodité pour les appelants remplaçant un objet de stockage existant, souvent ouvert en mode priorité, avec un nouvel objet de stockage ouvert sur le même fichier, mais en mode différent. Lorsque pstgPriority n’est pas 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 NULL pour pstgPriority , car StgOpenStorage libère l’objet dans certaines circonstances et ne la 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ûre, comme illustré dans l’exemple suivant :

// Replacement for:
// HRESULT hr = StgOpenStorage(
//         NULL, pstgPriority, grfMode, NULL, 0, &amp;pstgNew);

STATSTG statstg;
HRESULT hr = pstgPriority-&gt;Stat(&amp;statstg, 0);
pStgPriority-&gt;Release();
pStgPriority = NULL;
if (SUCCEEDED(hr))
{
    hr = StgOpenStorage(statstg.pwcsName, NULL, grfMode, NULL, 0, &amp;pstgNew);
}

Configuration requise


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 (include Objbase.h)
Bibliothèque	Ole32.lib
DLL	Ole32.dll

Voir aussi

IStorage

StgCreateDocfile

StgOpenStorageEx