Méthode IMoniker ::BindToStorage (objidl.h)

  • Article

Lie au stockage de l’objet spécifié. Contrairement à la méthode IMoniker ::BindToObject , cette méthode n’active pas l’objet identifié par le moniker.

Syntaxe

HRESULT BindToStorage(
  [in]  IBindCtx *pbc,
  [in]  IMoniker *pmkToLeft,
  [in]  REFIID   riid,
  [out] void     **ppvObj
);

Paramètres

[in] pbc

Pointeur vers l’interface IBindCtx sur l’objet de contexte de liaison, qui est utilisé dans cette opération de liaison. Le contexte de liaison met en cache les objets liés pendant le processus de liaison, contient des paramètres qui s’appliquent à toutes les opérations utilisant le contexte de liaison et fournit les moyens par lesquels l’implémentation du moniker doit récupérer des informations sur son environnement.

[in] pmkToLeft

Si le moniker fait partie d’un moniker composite, pointez vers le moniker à gauche de ce moniker. Ce paramètre est principalement utilisé par les implémenteurs moniker pour permettre la coopération entre les différents composants d’un moniker composite. Les clients Moniker doivent utiliser la valeur NULL.

[in] riid

Référence à l’identificateur de l’interface de stockage demandée, dont le pointeur sera retourné dans ppvObj. Les interfaces de stockage couramment demandées incluent IStorage, IStream et ILockBytes.

[out] ppvObj

Adresse de la variable pointeur qui reçoit le pointeur d’interface demandé dans riid. Une fois le retour réussi, *ppvObj contient le pointeur d’interface demandé vers le stockage de l’objet identifié par le moniker. En cas de réussite, l’implémentation doit appeler AddRef sur le stockage. Il incombe à l’appelant d’appeler Release. Si une erreur se produit, *ppvObj doit avoir la valeur NULL.

Valeur retournée

Cette méthode peut retourner les valeurs de retour standard E_UNEXPECTED, ainsi que les valeurs suivantes.

Code de retour Description
S_OK
 L’opération de liaison a réussi.
MK_E_NOSTORAGE
 L’objet identifié par ce moniker n’a pas son propre stockage.
MK_E_EXCEEDEDDEADLINE
 L’opération de liaison n’a pas pu être effectuée dans le délai spécifié par la structure BIND_OPTS du contexte de liaison.
MK_E_CONNECTMANUALLY
 L’opération n’a pas pu se connecter au stockage, peut-être parce qu’un périphérique réseau n’a pas pu être connecté. Pour plus d’informations, consultez IMoniker ::BindToObject.
MK_E_INTERMEDIATEINTERFACENOTSUPPORTED
 Un objet intermédiaire a été trouvé, mais il ne prend pas en charge une interface requise pour terminer l’opération de liaison. Par exemple, un moniker d’élément retourne cette valeur si son conteneur ne prend pas en charge l’interface IOleItemContainer .
STG_E_ACCESSDENIED
 Impossible d’accéder à l’objet de stockage.
 

Cette méthode peut également retourner les erreurs associées à la méthode IOleItemContainer ::GetObject .

Remarques

Il existe une différence importante entre les méthodes BindToObject et BindToStorage . Si, par exemple, vous avez un moniker qui identifie un objet de feuille de calcul, l’appel de BindToObject permet d’accéder à l’objet de feuille de calcul lui-même, tandis que l’appel de BindToStorage permet d’accéder à l’objet de stockage dans lequel réside la feuille de calcul.

Remarques aux appelants

Bien qu’aucune des classes de moniker COM n’appelle cette méthode dans leurs opérations de liaison, il peut être approprié de l’appeler dans l’implémentation d’une nouvelle classe moniker. Vous pouvez appeler cette méthode dans une implémentation de BindToObject qui nécessite des informations à partir de l’objet identifié par le paramètre pmkToLeft et peut les obtenir à partir du stockage persistant de l’objet sans activation. Par exemple, si vos monikers sont utilisés pour identifier des objets qui peuvent être activés sans activer leurs conteneurs, vous pouvez trouver cette méthode utile.

Un client qui peut lire le stockage de l’objet que son moniker identifie peut également appeler cette méthode.

Remarques aux implémenteurs

Votre implémentation doit localiser le stockage persistant de l’objet identifié par le moniker actuel et retourner le pointeur d’interface souhaité. Certains types de monikers représentent des pseudo-objets, qui sont des objets qui n’ont pas leur propre stockage persistant. Ces objets comprennent une partie de l’état interne de son conteneur, par exemple une plage de cellules dans une feuille de calcul. Si votre classe moniker identifie ce type d’objet, votre implémentation de BindToStorage doit retourner l’erreur MK_E_NOSTORAGE.

Si la structure BIND_OPTS du contexte de liaison spécifie l’indicateur de BINDFLAGS_JUSTTESTEXISTENCE, votre implémentation a la possibilité de retourner NULL dans ppvObj (bien que vous puissiez également ignorer l’indicateur et effectuer l’opération de liaison complète).

Notes spécifiques à l’implémentation

Implémentation Notes
Anti-moniker Cette méthode retourne E_NOTIMPL.
Moniker de classe Cette méthode est transmise au bindToObject du moniker de classe.
Moniker de fichier Cette méthode ouvre le fichier spécifié par le chemin d’accès représenté par le moniker et retourne un pointeur IStorage vers ce fichier. La méthode prend en charge la liaison à l’interface IStorage uniquement ; si IStream ou ILockBytes est demandé dans riid, la méthode retourne E_UNSPEC et, si d’autres interfaces sont demandées, cette méthode renvoie E_NOINTERFACE. Sauf si pmkToLeft est un moniker de classe, pmkToLeft doit être NULL, comme dans l’implémentation de IMoniker ::BindToObject.
Moniker composite générique Cette méthode appelle de manière récursive BindToStorage sur le composant le plus à droite du composite, en passant le reste du composite en tant que paramètre pmkToLeft pour cet appel.
Moniker d’élément Si pmkToLeft a la valeur NULL, cette méthode retourne E_INVALIDARG. Sinon, la méthode appelle IMoniker ::BindToObject sur le paramètre pmkToLeft , en demandant un pointeur d’interface IOleItemContainer . La méthode appelle ensuite IOleItemContainer ::GetObjectStorage pour l’interface demandée.
MONIKER OBJREF Cette méthode obtient un pointeur marshalé vers l’interface demandée sur le stockage qui contient l’objet en cours d’exécution. Étant donné que le moniker OBJREF représente un objet en cours d’exécution, aucune activation n’a lieu. Si l’objet représenté n’est plus en cours d’exécution, BindToStorage échoue avec E_UNEXPECTED.
Moniker de pointeur Cette méthode interroge le pointeur encapsulé pour l’interface demandée.
Moniker d’URL L’implémentation système des monikers d’URL prend en charge BindToStorage pour les objets de flux sur toutes les URL et pour les objets de stockage dans le cas où la ressource désignée est un fichier composé.

Étant donné que le moniker d’URL prend en charge la liaison asynchrone, la valeur de retour réelle de son BindToStorage peut varier en fonction des paramètres d’objet établis dans le contexte de liaison. Toutefois, la sémantique de l’opération de liaison est identique quelle que soit l’utilisation synchrone ou asynchrone, comme suit :

  • Le moniker d’URL extrait des informations supplémentaires pour l’opération de liaison à partir du contexte de liaison. Par exemple, le moniker peut obtenir des pointeurs vers les interfaces IBindStatusCallback et IEnumFORMATETC inscrites dans le contexte de liaison. D’autres informations peuvent inclure des options de liaison supplémentaires spécifiées dans le contexte de liaison via IBindCtx ::SetBindOptions, telles que le paramètre dwTickCountDeadline ou la valeur grfFlags de BIND_MAYBOTHERUSER. Le moniker interroge ensuite le client en appelant IBindStatusCallback ::GetBindInfo , lance l’opération de liaison avec le transport et transmet l’IBinding résultant au client en appelant IBindStatusCallback ::OnStartBinding.
  • Si l’appelant a demandé un IStream ou un IStorage asynchrone en spécifiant l’indicateur BINDF_ASYNCSTORAGE dans la structure BINDINFO récupérée à partir de IBindStatusCallback ::GetBindInfo, la méthode moniker d’URL retourne l’objet dès que possible. Les appels à ces objets IStorage ou IStream qui référencent des données qui ne sont pas encore disponibles retournent E_PENDING.
  • Si l’appelant ne spécifie pas IStream ou IStorage asynchrone comme décrit ci-dessus, le moniker d’URL renvoie toujours un objet via la méthode IBindStatusCallback ::OnDataAvailable dès que possible. Toutefois, les appels à ces objets qui référencent des données qui ne sont pas encore disponibles sont bloqués jusqu’à ce que les données soient disponibles. Pour certaines applications, cela nécessite la moindre modification de leur code d’E/S existant, mais peut néanmoins entraîner une amélioration des performances en fonction de leurs modèles d’accès.

Configuration requise

Condition requise Valeur
Client minimal pris en charge Windows 2000 Professionnel [applications de bureau uniquement]
Serveur minimal pris en charge Windows 2000 Server [applications de bureau uniquement]
Plateforme cible Windows
En-tête objidl.h

Voir aussi

IMoniker