7 Appendix B: Product Behavior

The information in this specification is applicable to the following Microsoft products or supplemental software. References to product versions include updates to those products.

  • Windows NT operating system

  • Windows 2000 operating system

  • Windows XP operating system

  • Windows Server 2003 operating system

  • Windows Vista operating system

  • Windows Server 2008 operating system

  • Windows 7 operating system

  • Windows Server 2008 R2 operating system

  • Windows 8 operating system

  • Windows Server 2012 operating system

  • Windows 8.1 operating system

  • Windows Server 2012 R2 operating system

  • Windows 10 operating system

  • Windows Server 2016 operating system

  • Windows Server operating system

  • Windows Server 2019 operating system

Exceptions, if any, are noted in this section. If an update version, service pack or Knowledge Base (KB) number appears with a product name, the behavior changed in that update. The new behavior also applies to subsequent updates unless otherwise specified. If a product edition appears with the product version, behavior is different in that product edition.

Unless otherwise specified, any statement of optional behavior in this specification that is prescribed using the terms "SHOULD" or "SHOULD NOT" implies product behavior in accordance with the SHOULD or SHOULD NOT prescription. Unless otherwise specified, the term "MAY" implies that the product does not follow the prescription.

<1> Section 1.8: Windows uses only Windows Errors Codes, as specified in [MS-ERREF].

<2> Section 2.2.15: For type libraries that are generated by means of the Microsoft Interface Definition Language (MIDL), a parameter that has the [custom] attribute does not specify PARAMFLAG_FHASCUSTDATA. For type libraries that are generated by means of MkTypLib, a parameter that has the [custom] attribute always specifies PARAMFLAG_FHASCUSTDATA.

<3> Section 2.2.16: The TYPEFLAG_FDISPATCHABLE flag value is computed based on the presence of IDispatch. It is never set directly.

<4> Section 2.2.20: Type libraries generated by means of Microsoft Interface Definition Language (MIDL) always specify LIBFLAG_FHASDISKIMAGE.

<5> Section 2.2.28.2.1:  Windows uses IID_IRecordInfo as the IID of a local-only interface.

<6> Section 2.2.29.1: wReserved1 is not set to 0 by Windows automation clients.

<7> Section 2.2.29.1: wReserved2 is not set to 0 by Windows automation clients.

<8> Section 2.2.29.1: wReserved3 is not set to 0 by Windows automation clients.

<9> Section 2.2.29.2: Windows uses these data type names when defining the local Windows VARIANT data types, and another set of data types whose names are prefixed by "_wire", such as _wireVARIANT, to define the wire formats for these data types. Because the local Windows data types are not used on the network, the protocol specification uses the original data type names such as "VARIANT" when specifying wire format data type definitions for VARIANT data types".

<10> Section 2.2.30.10: Windows uses these data type names when defining the local Windows SAFEARRAY data types, and another set of data types whose names are prefixed by "_wire", such as _wireSAFEARRAY, to define the wire formats for these data types. Because the local Windows data types are not used on the network, the protocol specification uses the original data type names such as "SAFEARRAY" when specifying wire format data type definitions for SAFEARRAY data types.

<11> Section 2.2.30.10: The low word of cLocks represents the number of times the SAFEARRAY was "locked" using the SafeArrayAccessData API. For more information, see [MSDN-SafeArrayAccessData].

<12> Section 2.2.30.10: The consistency checks are not enforced in Windows NT, Windows 2000 and Windows XP without SP 2. If any of the consistency checks fails, the protocol implementation raises an RPC_X_BAD_STUB_DATA exception.

<13> Section 2.2.31: On Windows platforms, the type library that defines the UDT is registered on both the client and the server.

<14> Section 2.2.34: The wCode field is always set to 0.

<15> Section 2.2.34: The bstrSource field is set to a textual, human-readable name of the source of the exception, typically the application name of the server.

<16> Section 2.2.34: The Windows implementation of the protocol uses any value passed to it by higher-layer software.

<17> Section 2.2.34: bstrHelpFile can be set to the fully qualified path name of a Help file with more information about the error.

<18> Section 2.2.34: dwHelpContext can be set to a help context ID. For more information, see [MSDN-WinHelp].

<19> Section 2.2.34: pfnDeferredFillIn can be non-NULL when the automation server implementing IDispatch sets it to a non-NULL value. This function is meant to defer the need to fill in the rest of the structure until the client actually requests it. This value is bound to the server process address space. When the client and the server are not hosted in the same process, this value is ignored.

<20> Section 2.2.39: The value, in bytes, of cBytes is the in-memory size of the PARAMDESCEX structure.

<21> Section 2.2.42: If a MIDL-generated type library has an [lcid] parameter following the [optional] parameters, cParamsOpt is set to 0. To count the optional parameters specified by the method, iterate through the members of the lprgelemdescParam array and evaluate the paramdesc.wParamFlags bit flags of each element. Each optional parameter must have the PARAMFLAG_FOPT bit flag set.

<22> Section 2.2.43:  For a per-instance field, _vdUnion specifies the offset of the field in memory relative to the starting address of the structure, or 0 if the VARDESC describes a member of a union.

<23> Section 2.2.44: The sizes of data-only types in Windows are specified in [MSDN]. The size of a structure is specified in [MSDN].

<24> Section 2.2.44: The sizes of data-only types in Windows are specified in [MSDN]. The size of a structure is specified in [MSDN].

<25> Section 2.2.44: The sizes of data-only types in Windows are specified in [MSDN]. The size of a structure is specified in [MSDN].

<26> Section 2.2.44: The sizes of data-only types in Windows are specified in [MSDN]. The size of a structure is specified in [MSDN].

<27> Section 2.2.44: Windows does not use the value of the cbAlignment field. Windows sets this value to the required byte alignment for an instance of the type, as in the following table.

Value

Meaning

0

Specifies alignment with a 64-KB boundary.

1

 Specifies byte alignment.

2

Specifies word alignment.

4

Specifies dword alignment.

<28> Section 2.2.49: There are two Windows compilers that process IDL specifications that contain automation definitions: mktyplib.exe and midl.exe. Mktyplib.exe has been deprecated, so do not use it. Mktyplib accepts only a subset of the following specified syntax and keywords, while midl.exe accepts all of them. The OLE Automation Protocol supports the entire range.

<29> Section 2.2.49.1.2: Connectable servers implement the following interfaces: IConnectionPointContainer, IConnectionPoint, IEnumConnectionPoints, and IEnumConnections as described in [MSDN-COM].

<30> Section 2.2.49.1.3: Clients implement IPropertyNotifySink::OnChanged to handle calls from bindable server properties that are compiled with the [bindable] attribute and IPropertyNotifySink::OnRequestEdit to handle calls from properties that are declared with the [requestedit] attribute. Both methods identify each property by its DISPID. The proposed replacement value is not available to IPropertyNotifySink::OnRequestEdit; so its use is limited to determining whether the existing value can be changed. The value cannot be used for data validation.

<31> Section 2.2.49.2: The value of the [helpcontext] attribute specifies a 32-bit context identifier that is used to associate the library, type, or type member with a topic in the Help file.

<32> Section 2.2.49.2: The value of the [helpfile] attribute specifies the fully qualified name of the Help file that is used by all types in the type library.

<33> Section 2.2.49.2: The value of the [helpstring] attribute provides a description of the element to which it is applied.

<34> Section 2.2.49.2: The value of the [helpstringcontext] attribute specifies a 32-bit identifier that is used to associate the library, type, or type member with a string resource in the DLL specified by the [helpstringdll] attribute.

<35> Section 2.2.49.2: The value of the [helpstringdll] attribute specifies the fully qualified name of a dynamic link library that contains localized Help resources.

<36> Section 2.2.49.2: Windows uses the [restricted] attribute to indicate that an interface or dispinterface cannot be available to macro languages. For libraries and modules, it is a visibility attribute with the same meaning as the [hidden] attribute: do not display to users.

<37> Section 2.2.49.3: There are two Windows compilers that process IDL specifications that contain automation definitions: mktyplib.exe and midl.exe. Mktyplib.exe has been deprecated, so do not use it anymore. Mktyplib accepts only a subset of the types specified earlier in this section, while midl.exe accepts all of them. The OLE Automation Protocol supports the entire range.

<38> Section 2.2.49.3: Windows uses the [restricted] attribute to indicate that an interface or dispinterface cannot be available to macro languages. For libraries and modules, it is a visibility attribute with the same meaning as the [hidden] attribute: do not display to users.

<39> Section 2.2.49.4: Windows uses the [proxy] attribute to specify that the code for marshaling the interface data is external to the type library.

<40> Section 2.2.49.5.1: Windows uses the [defaultcollelem] attribute to enable Visual Basic–specific optimizations, some of which treat the property as the default collection of the coclass that contains it. In cases where the application of the attribute is inconsistent (such as coclasses with multiple [defaultcollelem] assignments or an assignment to a property that returns objects that are not enumerable), some or all of the optimizations are not performed, and the attribute is ignored.

<41> Section 2.2.49.5.1: MIDL does not enforce a restriction on the number of properties with the [defaultcollelem] attribute, but some Visual Basic–specific optimizations are not applied if a type has more than one property.

<42> Section 2.2.49.5.1: Windows type libraries do not use the replaceable attribute.

<43> Section 2.2.49.5.2: Windows uses the [immediatebind] attribute to distinguish between controls such as check boxes (in which the bound data source is updated every time the control state changes), and list boxes (in which the bound data source is updated only when the control is saved or loses focus).

<44> Section 2.2.49.8: Windows type browsers distinguish between COM components that explicitly support a windowed user interface and components that do not. Non-visual type browsers do not display components with the control attribute to users.

<45> Section 2.2.49.8: By default, Windows type browsers do not display elements with the hidden attribute to users.

<46> Section 2.2.49.8: Coclasses defined with the [licensed] attribute can be instantiated using only the IClassFactory2 interface.

<47> Section 2.2.49.8: Coclasses defined with the [noncreatable] attribute cannot be instantiated using IClassFactory::CreateInstance, CoCreateInstance, or OleCreate.

<48> Section 2.2.49.9: The FUNCFLAG_FUSESGETLASTERROR bit flag indicates that the method was declared with the [usesgetlasterror] attribute and supports the GetLastError method (see [MSDN-ErrorHandling]). The GetLastError method is local-only and this flag has no effect on the wire.

<49> Section 2.2.49.9: The cdecl, stdcall, and pascal calling conventions are specified in [MSDN-CALLCONV].

<50> Section 2.2.49.10: The string specified in an importlib statement specifies the fully qualified name of a compiled type library (*.tlb) file.

<51> Section 2.2.51: Windows uses the hash value to quickly reject names that do not correspond to any entities defined in the automation type library.

<52> Section 2.2.51: If the hash value is zero, Windows computes a new hash value before evaluating the name.

<53> Section 3.1.1: Windows automation servers can generate the mappings on the fly according to the requirements of the application.

<54> Section 3.1.4.3: The range restriction is not present for Windows NT, Windows 2000, Windows XP, or Windows Server 2003.

<55> Section 3.1.4.3: The default implementation of Automation performs this mapping; however, any automation server can override this behavior by providing its own implementation for IDispatch::GetIDsOfNames.

<56> Section 3.1.4.4.3: Windows automation clients use the value specified in the defaultvalue parameter.

<57> Section 3.1.4.4.4: The default Automation implementation does attempt to convert the actual arguments to the formal parameters' type, as declared in the IDL of the method or property. If no such conversion exists, the default Automation implementation returns DISP_E_TYPEMISMATCH. However, any automation server can choose to implement IDispatch::Invoke and exhibit different behavior

<58> Section 3.7.1.1: The implementation-specific documentation values correspond to the values declared with the [helpstring], [helpcontext], and [helpfile] attributes. If the server also implements ITypeInfo2, the documentation values include the values declared with the [helpstringcontext] and [helpstringdll] attributes.

<59> Section 3.7.4.8: If the library, type, or type member was declared without the [helpstring] attribute and the Type information server implements ITypeInfo2, the GetDocumentation method attempts to return the localized value specified by the pBstrHelpString parameter of ITypeInfo2::GetDocumentation2, using an LCID of 0.

<60> Section 3.9.4.10: pbstrHelpString is set to the value of the string resource that is contained in the DLL specified by pBstrHelpStringDll and that is associated with the resource handle specified by pdwHelpStringContext and LocaleID specified by lcid, or is set to NULL if no such resource exists.

<61> Section 3.11.4.7: If the library or type was declared without the [helpstring] attribute and the Type library server implements ITypeLib2, the GetDocumentation method attempts to return the localized value specified by the pBstrHelpString parameter of ITypeLib2::GetDocumentation2, using an LCID of 0.

<62> Section 3.11.4.9: Matching members of the binding member table of a reference dispinterface that are defined outside the automation scope are included in the ppTInfo and rgMemId arrays if the automation scope includes at least two named non-parameter elements whose names match szNameBuf.

<63> Section 3.13.4.3:  pBstrHelpString is set to the value of the string resource contained in the DLL specified by pBstrHelpStringDll and associated with the resource handle specified by pdwHelpStringContext and LocaleID specified by lcid, or NULL if no such resource exists.