Fonction StgOpenStorage (coml2api.h)

Article
02/26/2024

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.

Note Les applications doivent utiliser la nouvelle fonction StgOpenStorageEx au lieu de StgOpenStorage pour tirer parti des fonctionnalités améliorées et du stockage structuré Windows. 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 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

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 prendre du temps, car l’appel StgOpenStorage doit effectuer une 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 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 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

Note Pour réduire les coûts liés à la copie d’un instantané, les applications peuvent ouvrir des objets de stockage en mode prioritaire (grfMode spécifie STGM_PRIORITY).

Le paramètre snbExclude spécifie un ensemble de noms d’éléments dans cet objet de stockage qui doivent être vidés à l’ouverture de l’objet de stockage : les flux sont définis sur une longueur de zéro ; tous leurs éléments ont été supprimés pour les objets de stockage. En excluant certains flux, les dépenses liées à la réalisation d’une copie instantané peuvent être considérablement réduites. Presque toujours, cette approche est utilisée après avoir d’abord ouvert l’objet de stockage en mode priorité, puis lu complètement les éléments désormais exclus dans la mémoire. Cette ouverture en mode priorité antérieure de l’objet de stockage doit être passée via le paramètre pstgPriority pour supprimer l’exclusion impliquée par le mode de priorité. L’application appelante est chargée de réécrire le contenu des éléments exclus avant la validation. Par conséquent, cette technique est probablement utile uniquement pour les applications dont les documents ne nécessitent pas un accès constant à leurs objets de stockage pendant qu’ils sont actifs.

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, &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

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

Voir aussi

IStorage

StgCreateDocfile

StgOpenStorageEx