structure BIND_OPTS3 (objidl.h)

Contient des paramètres utilisés pendant une opération de liaison de moniker.

Syntaxe

typedef struct tagBIND_OPTS3 {
  DWORD        cbStruct;
  DWORD        grfFlags;
  DWORD        grfMode;
  DWORD        dwTickCountDeadline;
  DWORD        dwTrackFlags;
  DWORD        dwClassContext;
  LCID         locale;
  COSERVERINFO *pServerInfo;
  HWND         hwnd;
} BIND_OPTS3, *LPBIND_OPTS3;

Membres

cbStruct

Taille de cette structure, en octets.

grfFlags

Indicateurs qui contrôlent les aspects des opérations de liaison de moniker. Cette valeur est n’importe quelle combinaison des indicateurs de bits dans l’énumération BIND_FLAGS . La fonction CreateBindCtx initialise ce membre à zéro.

grfMode

Indicateurs devant être utilisés lors de l'ouverture du fichier qui contient l'objet identifié par le moniker. Les valeurs possibles sont les constantes STGM. L’opération de liaison utilise ces indicateurs dans l’appel à IPersistFile ::Load lors du chargement du fichier. Si l’objet est déjà en cours d’exécution, ces indicateurs sont ignorés par l’opération de liaison. La fonction CreateBindCtx initialise ce champ pour STGM_READWRITE.

dwTickCountDeadline

Heure d’horloge à laquelle l’appelant souhaite que l’opération de liaison soit terminée, en millisecondes. Ce membre permet à l’appelant de limiter le temps d’exécution d’une opération lorsque la vitesse est de première importance. La valeur zéro indique qu’il n’y a pas d’échéance. Les appelants utilisent le plus souvent cette fonctionnalité lors de l’appel de la méthode IMoniker ::GetTimeOfLastChange , même si elle peut également être utilement appliquée à d’autres opérations. La fonction CreateBindCtx initialise ce champ à zéro.

Les délais classiques permettent quelques centaines de millisecondes d’exécution. Cette échéance est une recommandation, pas une exigence ; toutefois, les opérations qui dépassent leur échéance d’une grande quantité peuvent entraîner des retards pour l’utilisateur final. Chaque implémentation de moniker doit essayer de terminer son opération à l’échéance ou échouer avec l’erreur MK_E_EXCEEDEDDEADLINE.

Si une opération de liaison dépasse son échéance parce qu’un ou plusieurs objets dont elle a besoin ne sont pas en cours d’exécution, l’implémentation du moniker doit inscrire les objets responsables dans le contexte de liaison à l’aide de IBindCtx ::RegisterObjectParam. Les objets doivent être inscrits sous les noms de paramètres « ExceededDeadline », « ExceededDeadline1 », « ExceededDeadline2 », etc. Si l’appelant trouve ultérieurement l’objet dans la table d’objets en cours d’exécution, l’appelant peut réessayer l’opération de liaison.

La fonction GetTickCount indique le nombre de millisecondes depuis le démarrage du système et retourne à zéro après 2^31 millisecondes. Par conséquent, les appelants doivent faire attention à ne pas passer par inadvertance une valeur zéro (ce qui indique aucune échéance), et les implémentations de moniker doivent être conscientes des problèmes d’habillage d’horloge.

dwTrackFlags

Un moniker peut utiliser cette valeur lors du suivi des liens. Si les données persistantes d’origine référencées par le moniker ont été déplacées, le moniker peut tenter de rétablir le lien en recherchant les données d’origine à l’aide d’un mécanisme approprié. Ce membre fournit des informations supplémentaires sur la façon dont le lien doit être résolu. Consultez la documentation du paramètre fFlags dans IShellLink ::Resolve.

L’implémentation de moniker de fichier COM utilise le mécanisme de liaison de l’interpréteur de commandes pour rétablir les liens et passe ces indicateurs à IShellLink ::Resolve.

dwClassContext

Contexte de classe, tiré de l’énumération CLSCTX , qui doit être utilisé pour instancier l’objet. Les monikers transmettent généralement cette valeur au paramètre dwClsContext de CoCreateInstance.

locale

Valeur LCID indiquant la préférence du client pour les paramètres régionaux à utiliser par l’objet auquel ils se lient. Un moniker transmet cette valeur à IClassActivator ::GetClassObject.

pServerInfo

Pointeur vers une structure COSERVERINFO . Ce membre permet aux clients appelant IMoniker ::BindToObject de spécifier les informations du serveur. Les clients peuvent passer une structure BIND_OPTS2 à la méthode IBindCtx ::SetBindOptions . Si un nom de serveur est spécifié dans la structure COSERVERINFO , la liaison moniker est transférée à l’ordinateur spécifié. SetBindOptions copie uniquement les membres struct de BIND_OPTS2, pas la structure COSERVERINFO et les pointeurs qu’elle contient. Les appelants ne peuvent libérer aucun de ces pointeurs tant que le contexte de liaison n’est pas libéré. Le nouveau moniker de classe COM n’honore pas actuellement l’indicateur pServerInfo .

hwnd

Handle de la fenêtre qui devient le propriétaire de l’interface utilisateur d’élévation, le cas échéant. Si hwnd a la valeur NULL, COM appelle la fonction GetActiveWindow pour rechercher un handle de fenêtre associé au thread actif. Ce cas peut se produire si le client est un script, qui ne peut pas remplir une structure BIND_OPTS3 . Dans ce cas, COM essaie d’utiliser la fenêtre associée au thread de script.

Remarques

Une structure BIND_OPTS3 est stockée dans un contexte de liaison ; le même contexte de liaison est utilisé par chaque composant d’un moniker composite pendant la liaison, ce qui permet de passer les mêmes paramètres à tous les composants d’un moniker composite. Pour plus d’informations sur les contextes de liaison, consultez IBindCtx .

Les clients Moniker (utilisent un moniker pour acquérir un pointeur d’interface vers un objet) n’ont généralement pas besoin de spécifier des valeurs pour les membres de cette structure. La fonction CreateBindCtx crée un contexte de liaison avec les options de liaison définies sur des valeurs par défaut qui conviennent à la plupart des situations ; la fonction BindMoniker fait la même chose lors de la création d’un contexte de liaison à utiliser dans la liaison d’un moniker. Si vous souhaitez modifier les valeurs de ces options de liaison, vous pouvez le faire en passant une structure BIND_OPTS3 à la méthode IBindCtx ::SetBindOptions . Les implémenteurs Moniker peuvent passer une structure BIND_OPTS3 à la méthode IBindCtx ::GetBindOptions pour récupérer les valeurs de ces options de liaison.

Configuration requise

Voir aussi

CreateBindCtx

IBindCtx

IMoniker