Contents
Previous Topic: SCRIPTTHREADSTATE
Next Topic: IDispatchEx Methods
| | |
| ||
| ||
IDispatchEx
IDispatchEx, an extension of the IDispatch interface, supports features appropriate for dynamic languages such as scripting languages. This section describes the IDispatchEx interface itself, the differences between IDispatch and IDispatchEx, and the rationale for the extensions. It is expected that readers are familiar with IDispatch and have access to the IDispatch documentation.
Description
IDispatch was developed essentially for Microsoft® Visual Basic®. The primary limitation of IDispatch is that it assumes objects are static, that is, they do not change during run time and thus can be fully described at compile time by type information. Dynamic run time models as found in scripting languages such as Visual Basic Scripting Edition (VBScript) and JScript and object models such as Dynamic HTML require a more flexible interface.
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. The additional features of IDispatchEx beyond those provided by IDispatch are:
- Add new members to an object ("expando")—use GetDispID with the fdexNameEnsure flag.
- Delete members of an object—use DeleteMemberByName or DeleteMemberByDispID.
- Case-sensitive dispatch operations—use fdexNameCaseSensitive or fdexNameCaseInsensitive.
- Search for member with implicit name—use fdexNameImplicit.
- Enumerate DISPIDs of an object—use GetNextDispID.
- Map from DISPID to element name—use GetMemberName.
- Obtain properties of object members—use GetMemberProperties.
- Method invocation with this pointer—use InvokeEx with DISPATCH_METHOD.
- Allow browsers that support the concept of name spaces to obtain the name space parent of an object—use GetNameSpaceParent.
Objects that support IDispatchEx might also support IDispatch for backward compatibility. The dynamic nature of objects that support IDispatchEx has a few implications for the IDispatch interface of those objects. For example, IDispatch assumes that "The member and parameter DISPIDs must remain constant for the lifetime of the object. This allows a client to obtain DISPIDs once, and cache them for later use." Since IDispatchEx allows the addition and deletion of members, the set of valid DISPIDs does not remain constant. However, IDispatchEx requires that the mapping between DISPID and member name remain constant. This means that if a member is deleted:
- The DISPID cannot be reused unless a member with the same name is created.
- The DISPID must remain valid for GetNextDispID.
- The DISPID must be accepted gracefully by any of the IDispatch/IDispatchEx methods—they must recognize the member as deleted and return an appropriate error code (usually DISP_E_MEMBERNOTFOUND or S_FALSE).
Top of Page
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.
Description