IDispatchEx, interfaceIDispatchEx Interface

IDispatchEx, une extension de la IDispatch approprié à interface, les fonctionnalités de prise en charge pour les langages dynamiques tels que des langages de script.IDispatchEx, an extension of the IDispatch interface, supports features appropriate for dynamic languages such as scripting languages. Cette section décrit la IDispatchEx les différences entre l’interface elle-même, IDispatch et IDispatchExet la logique pour les extensions.This section describes the IDispatchEx interface itself, the differences between IDispatch and IDispatchEx, and the rationale for the extensions. Il est prévu que les lecteurs sont familiarisés avec IDispatch et avoir accès à la IDispatch documentation.It is expected that readers are familiar with IDispatch and have access to the IDispatch documentation.

NotesRemarks

IDispatchessentiellement, l’a été développé pour Microsoft Visual Basic.IDispatch was developed essentially for Microsoft Visual Basic. Le principal inconvénient de IDispatch est qu’elle suppose que les objets sont statiques.The primary limitation of IDispatch is that it assumes that objects are static. En d’autres termes, étant donné que les objets ne changent pas pendant l’exécution, les informations de type peuvent décrire entièrement les au moment de la compilation.In other words, since objects do not change during run time, type information can fully describe them at compile time. Les modèles d’exécution dynamiques qui sont trouvent dans des langages tels que Visual Basic Scripting Edition (VBScript) et JavaScriptJavaScript et modèles d’objet tels que HTML dynamiques requièrent une interface plus souple.Dynamic run-time models that are found in scripting languages such as Visual Basic Scripting Edition (VBScript) and JavaScriptJavaScript and object models such as Dynamic HTML require a more flexible interface.

IDispatchExa été développé pour fournir tous les services de IDispatch , ainsi que des extensions qui sont appropriées pour les langues à liaison tardive plus dynamiques tels que des langages de script.IDispatchEx was developed to provide all the services of IDispatch as well as some extensions that are appropriate for more dynamic late-bound languages such as scripting languages. Les fonctionnalités supplémentaires de IDispatchEx au-delà de celles fournies par IDispatch sont :The additional features of IDispatchEx beyond those provided by IDispatch are:

  • Ajouter de nouveaux membres à un objet (« expando »), utilisez GetDispID avec la fdexNameEnsure indicateur.Add new members to an object ("expando")—use GetDispID with the fdexNameEnsure flag.

  • Supprimer des membres d’un objet, utilisez DeleteMemberByName ou DeleteMemberByDispID.Delete members of an object—use DeleteMemberByName or DeleteMemberByDispID.

  • Les opérations de répartition qui respecte la casse, utilisez fdexNameCaseSensitive ou fdexNameCaseInsensitive.Case-sensitive dispatch operations—use fdexNameCaseSensitive or fdexNameCaseInsensitive.

  • Recherche d’un membre implicite portant — utilisez fdexNameImplicit.Search for member with implicit name—use fdexNameImplicit.

  • Énumérer les DISPID d’un objet, utilisez GetNextDispID.Enumerate DISPIDs of an object—use GetNextDispID.

  • Mappage entre les DISPID et nom de l’élément, utilisez GetMemberName.Map from DISPID to element name—use GetMemberName.

  • Obtenir les propriétés des membres de l’objet, utilisez GetMemberProperties.Obtain properties of object members—use GetMemberProperties.

  • L’appel de méthode avec this pointeur — utilisez InvokeEx avec DISPATCH_METHOD.Method invocation with this pointer—use InvokeEx with DISPATCH_METHOD.

  • Autoriser les navigateurs qui prennent en charge le concept d’espaces de noms pour obtenir le parent d’espace de nom d’un objet, utilisez GetNameSpaceParent.Allow browsers that support the concept of name spaces to obtain the name space parent of an object—use GetNameSpaceParent.

    Objets qui prennent en charge IDispatchEx peut prennent également en charge IDispatch pour la compatibilité descendante.Objects that support IDispatchEx might also support IDispatch for backward compatibility. La nature dynamique des objets qui prennent en charge IDispatchEx a certaines implications pour la IDispatch interface de ces objets.The dynamic nature of objects that support IDispatchEx has a few implications for the IDispatch interface of those objects. Par exemple, IDispatch part de l’hypothèse suivante :For example, IDispatch makes the following assumption:

  • Le membre et le paramètre DISPID doivent rester constantes pour la durée de vie de l’objet.The member and parameter DISPIDs must remain constant for the lifetime of the object. Cela permet au client obtenir les DISPID qu’une seule fois et de les mettre en cache pour une utilisation ultérieure.This allows a client to obtain DISPIDs once and cache them for later use.

    Étant donné que IDispatchEx permet l’ajout et la suppression de membres, le jeu de DISPID valides n’est pas constante.Since IDispatchEx allows the addition and deletion of members, the set of valid DISPIDs does not remain constant. Toutefois, IDispatchEx exige que le mappage entre les DISPID et nom de membre reste constante.However, IDispatchEx requires that the mapping between DISPID and member name remain constant. Cela signifie que si un membre est supprimé :This means that if a member is deleted:

  • Le DISPID ne peut pas être réutilisé jusqu'à ce qu’un membre portant le même nom est créé.The DISPID cannot be reused until a member with the same name is created.

  • Le DISPID doit rester valide pour GetNextDispID.The DISPID must remain valid for GetNextDispID.

  • Le DISPID doit être accepté normalement par un de la IDispatch ou IDispatchEx méthodes, ils doivent reconnaître le membre comme étant supprimé et retourner un code d’erreur approprié (généralement DISP_E_MEMBERNOTFOUND ou S_FALSE).The DISPID must be accepted gracefully by any of the IDispatch or IDispatchEx methods—they must recognize the member as deleted and return an appropriate error code (usually DISP_E_MEMBERNOTFOUND or S_FALSE).

ExemplesExamples

Cela JavaScriptJavaScript code dans la fonction test() effectue les opérations suivantes :This JavaScriptJavaScript code in the function test() does the following:

  • Crée un objet en appelant le Object constructeur et assigne un pointeur vers le nouvel objet à l’objet de variable.Creates a new object by calling the Object constructor and assigns a pointer to the new object to the variable Obj.

  • Crée un élément nommé Elem dans l’objet et l’assigne à cet élément, un pointeur vers la cat (fonction).Creates a new element named Elem in the object and assigns to this element a pointer to the function cat.

  • Appelle cette fonction.Calls this function. Dans la mesure où il est appelé en tant que méthode, la this pointeur fait référence à l’objet obj. La fonction ajoute un nouvel élément, barre, à l’objet.Since it is being called as a method, the this pointer refers to the object Obj. The function adds a new element, Bar, to the object.

    Le code HTML complet est la suivante :The full HTML code is:

<html>  
<body>  
<script type="text/javascript">  
function cat()  
{  
   // Create new element and assign the value 10  
   this.Bar = 10;  
}  

function test()  
{  
   // Construct new object  
   Obj = new Object();  

   // Create new element and assign function pointer  
   Obj.Elem = cat;  

   // Call Elem method ("this" == Obj)  
   Obj.Elem();  

   // Obj.Bar now exists  
}  
test();  
</script>  
</body>  
</html>  

Un contrôle placé sur la même page Web peut obtenir un pointeur de répartition pour les moteurs de script à partir du navigateur.A control placed on this same Web page could obtain a dispatch pointer to the script engines from the browser. Le contrôle peut ensuite implémenter la fonction test() :The control could then implement the function test():

<html>  
<body>  
<script type="text/javascript">  
function cat()  
{  
   // Create new element and assign the value 10  
   this.Bar = 10;  
}  
</script>  
<object id="test" <CLASSID="CLSID:9417DB5D-FA2A-11D0-8CB3-00C04FC2B085">>  
</object>  
</body>  
</html>  

À partir du contrôle de code, tester, produit la même chose que le JavaScriptJavaScript fonction test().Code from the control, test, does the same thing as the JavaScriptJavaScript function test(). Notez que ces appels de distribution sont transformés en l’exécutant JavaScriptJavaScript moteur et de modifier l’état du moteur :Note that these dispatch calls are made into the running JavaScriptJavaScript engine and change the state of the engine:

  • Obtient le pointeur de dispatch pour la fonction cat en utilisant GetDispID().Obtains the dispatch pointer to the cat function using GetDispID().

  • Obtient le pointeur de dispatch pour la fonction d’objet à l’aide GetDispID().Obtains the dispatch pointer to the Object function using GetDispID().

  • Construit un objet en appelant la fonction de l’objet avec InvokeEx() et obtient un pointeur de dispatch vers l’objet qui vient d’être construit.Constructs an object by calling the Object function with InvokeEx() and obtains a dispatch pointer to the newly constructed object.

  • Crée un nouvel élément, Elem, dans l’objet en utilisant GetDispID() avec la fdexNameEnsure indicateur.Creates a new element, Elem, in the object using GetDispID() with the fdexNameEnsure flag.

  • Place le pointeur de la répartition par cat dans l’élément à l’aide de InvokeEx().Puts the dispatch pointer to cat in the element using InvokeEx().

  • Appelle le pointeur de la répartition par cat en tant que méthode en appelant InvokeEx() et en passant le pointeur de répartition à l’objet construit en tant que le this pointeur.Calls the dispatch pointer to cat as a method by calling InvokeEx() and passing in the dispatch pointer to the constructed object as the this pointer.

  • La méthode cat crée un nouvel élément, barre, dans le courant this objet.The cat method creates a new element, Bar, on the current this object.

  • Vérifie que le nouvel élément, à barres, a été créé dans l’objet construit par les éléments à l’aide de l’énumération GetNextDispID().Verifies that the new element, Bar, was created in the constructed object by enumerating through the elements using GetNextDispID().

    Le code pour le contrôle de test :The code for the test control:

   BOOL test(IDispatchEx *pdexScript)  
   {  
      HRESULT hr;  
      VARIANT var;  
      DISPID dispid, putid;  
      BOOL retval = FALSE;  
      BSTR bstrName = NULL;  
      IDispatch   *pdispObj = NULL, *pdispCat = NULL;  
      IDispatchEx *pdexObj = NULL;  
      DISPPARAMS dispparams, dispparamsNoArgs = {NULL, NULL, 0, 0};  

      // Get dispatch pointer for "cat"  
      bstrName = SysAllocString(OLESTR("cat"));  
         if (bstrName == NULL) goto LDone;  
      hr = pdexScript->GetDispID(bstrName, 0, &dispid);  
         if (FAILED(hr)) goto LDone;  
      SysFreeString(bstrName);  
         bstrName = NULL;  
      hr = pdexScript->InvokeEx(dispid, LOCALE_USER_DEFAULT,   
         DISPATCH_PROPERTYGET, &dispparamsNoArgs,   
         &var, NULL, NULL);  
         if (FAILED(hr)) goto LDone;  
      pdispCat = var.pdispVal;  

      // Create object by calling "Object" constructor  
      bstrName = SysAllocString(OLESTR("Object"));  
         if (NULL == bstrName) goto LDone;  
      hr = pdexScript->GetDispID(bstrName, 0, &dispid);  
         if (FAILED(hr)) goto LDone;  
      SysFreeString(bstrName);  
         bstrName = NULL;  
      hr = pdexScript->InvokeEx(dispid, LOCALE_USER_DEFAULT,   
         DISPATCH_CONSTRUCT, &dispparamsNoArgs,   
         &var, NULL, NULL);  
         if (FAILED(hr)) goto LDone;  
      pdispObj = var.pdispVal;  
      hr = pdispObj->QueryInterface(IID_IDispatchEx, (void **)&pdexObj);  
         if (FAILED(hr)) goto LDone;  

      // Create new element in object  
      bstrName = SysAllocString(OLESTR("Elem"));  
         if (NULL == bstrName) goto LDone;  
      hr = pdexObj->GetDispID(bstrName, fdexNameEnsure, &dispid);  
         if (FAILED(hr)) goto LDone;  
      SysFreeString(bstrName);  
         bstrName = NULL;  

      // Assign "cat" dispatch pointer to element  
      putid = DISPID_PROPERTYPUT;  
      var.vt = VT_DISPATCH;  
      var.pdispVal = pdispCat;  
      dispparams.rgvarg = &var;  
      dispparams.rgdispidNamedArgs = &putid;  
      dispparams.cArgs = 1;  
      dispparams.cNamedArgs = 1;  
      hr = pdexObj->InvokeEx(dispid, LOCALE_USER_DEFAULT,   
         DISPATCH_PROPERTYPUTREF, &dispparams,  
         NULL, NULL, NULL);  
         if (FAILED(hr)) goto LDone;  

      // Invoke method with "this" pointer  
      putid = DISPID_THIS;  
      var.vt = VT_DISPATCH;  
      var.pdispVal = pdispObj;  
      dispparams.rgvarg = &var;  
      dispparams.rgdispidNamedArgs = &putid;  
      dispparams.cArgs = 1;  
      dispparams.cNamedArgs = 1;  
      hr = pdexObj->InvokeEx(dispid, LOCALE_USER_DEFAULT,  
         DISPATCH_METHOD, &dispparams,  
            NULL, NULL, NULL);  
         if (FAILED(hr)) goto LDone;  

      // Confirm that new element "Bar" is in object  
      hr = pdexObj->GetNextDispID(fdexEnumAll, DISPID_STARTENUM, &dispid);  
      while (hr == NOERROR)  
      {  
            hr = pdexObj->GetMemberName(dispid, &bstrName);  
            if (FAILED(hr)) goto LDone;  
            retval = !wcscmp(bstrName, OLESTR("Bar"));  
            SysFreeString(bstrName);  
            bstrName = NULL;  
            if (retval) goto LDone;  
         hr = pdexObj->GetNextDispID(fdexEnumAll, dispid, &dispid);  
      }  
LDone:  
   SysFreeString(bstrName);  
   if (pdispCat != NULL)  
      pdispCat->Release();  
   if (pdispObj != NULL)  
      pdispObj->Release();  
   if (pdexObj != NULL)  
      pdexObj->Release();  

   return retval;  
   }  

MéthodesMethods

Méthodes IDispatchExIDispatchEx Methods