19    Automation

Automation provides a way to expose and access objects within an application in a late bound way. Automation defines the following dispatch interfaces and functions.

• IDispatch() interface--Exposes objects, methods, and properties to Automation programming tools and other applications.

• Dispatch API functions--Simplifies the implementation of the IDispatch() interface. Use these functions to generate an IDispatch() interface automatically.

• IEnumVARIANT interface--Provides a way for COM clients to iterate over collection objects. This is a dispatch interface.

19.1    Overview of the IDispatch Interface

The following table describes the member functions of the IDispatch() interface.

Table 19-1:  IDispatch Member Functions

19.1.1    Implementing the IDispatch Interface

IDispatch() is located in the Oleauto.h header file on 32-bit systems, and in Dispatch.h on 16-bit systems.

ActiveX or COM objects can implement the IDispatch() interface for access by ActiveX clients, such as Visual Basic. The object's properties and methods can be accessed using IDispatch::GetIDsOfNames() and IDispatch::Invoke().

The following examples show how to access a COM object through the IDispatch() interface. The code is abbreviated for brevity, and omits error handling.

// Declarations of variables used.
 DEFINE_GUID(CLSID_Hello,  // Portions omitted for brevity.
 HRESULT hresult;
 IUnknown() * punk;
 IDispatch() * pdisp;
 OLECHAR FAR* szMember = ``SayHello'';
 DISPID dispid;
 DISPPARAMS dispparamsNoArgs = {NULL, NULL, 0, 0};
 EXCEPINFO excepinfo;
 UINT nArgErr;

In the following code, the OleInitialize function loads the COM dynamic-link libraries (DLLs), and the CoCreateInstance() function initializes the COM object's class factory.

// Initialize OLE DLLs.
hresult = OleInitialize(NULL);
// OLE function CoCreateInstance() starts application using GUID.
hresult = CoCreateInstance(CLSID_Hello, NULL, CLSCTX_SERVER, IID_IUnknown, \
(void FAR* FAR*)&punk);

QueryInterface() checks whether the object supports IDispatch(). (As with any call to QueryInterface(), the returned pointer must be released when it is no longer needed.)

// Call QueryInterface() to see if object supports IDispatch().
hresult = punk->QueryInterface(IID_IDispatch, &pdisp);

GetIDsOfNames retrieves the DISPID for the indicated method or property, in this case, szMember.

// Retrieve the dispatch identifier for the SayHello method.
// Use defaults where possible.
hresult = pdisp->GetIDsOfNames(
 IID_NULL,
 &szMember,
 1,
 LOCALE_USER_DEFAULT,
 &dispid);

In the following call to Invoke, the DISPID indicates the property or method to invoke. The SayHello method does not take any parameters, so the fifth argument (&dispparamsNoArgs), contains a NULL and 0, as initialized at declaration.

To invoke a property or method that requires parameters, supply the parameters in the DISPPARAMS structure.

// Invoke the method. Use defaults where possible.
hresult = pdisp->Invoke(
 dispid,
 IID_NULL,
 LOCALE_SYSTEM_DEFAULT,
 DISPATCH_METHOD,
 &dispparamsNoArgs,
 NULL,
 NULL,
 NULL);

19.2    Registering the Object

These functions let you identify a running instance of an object.

When an application is started with the /Automation switch on its command-line, it should initialize its Application object as the active object by calling RegisterActiveObject().

Applications can also register other top-level objects as the active object. For example, an application that exposes a Document object may want to let COM clients retrieve and modify the currently active document.

19.3    National Language Support Functions

The National Language Support (NLS) functions provide support for applications that use multiple locales at one time, especially applications that support Automation. Locale information is passed to allow the application to interpret both the member names and the argument data in the proper locale context. The information in this appendix applies only to 16-bit Windows systems.

Table 19-2:  IDispatch Elements

For Automation, applications need to get locale information and to compare and transform strings into the proper format for each locale.

A locale is simply user-preference information, represented as a list of values describing the user's language and sublanguage. National language support incorporates several disparate definitions of a locale into one coherent model. This model is designed to be general enough at a low level to support multiple, distinct, high-level functions, such as the ANSI C locale functions.

A code page is the mapping between character glyphs (shapes) and the 1-byte or 2-byte numeric values that are used to represent them. Microsoft Windows uses one of several code pages, depending on the installed localized version of Windows. For example, the Russian version uses code page 1251 (Cyrillic), while the English U.S. and Western European versions use code page 1252 (Multilingual). For historical reasons, the Windows code page in effect is referred to as the ANSI code page.

Because only one code page is in effect at a time, it is impossible for a computer running English U.S. Windows to display or print data correctly from the Cyrillic code page. The fonts do not contain the Cyrillic characters. However, it can still manipulate the characters internally, and they will display correctly again if moved back to a machine running Russian Windows.

All NLS functions use the locale identifier (LCID) to identify which code page a piece of text is assumed to lie in. For example, when returning locale information (such as month names) for Russian, the returned string can be meaningfully displayed in the Cyrillic code page only, because other code pages do not contain the appropriate characters. Similarly, when attempting to change the case of a string with the Russian locale, the case-mapping rules assume the characters are in the Cyrillic code page.

These functions can be divided into two categories.

• String transformation--NLS functions support uppercasing, lowercasing, generating sort keys (all locale-dependent), and getting string type information.

• Locale manipulation--NLS functions return information about installed locales for use in string transformations.

19.3.1    Overview of Functions

The following table lists the NLS functions.

Table 19-3:  NLS Functions

19.3.2    Localized Member Names

An application may expose a set of objects whose members have names that differ across localized versions of a product. This poses a problem for programming languages that want to access such objects, because it means that late binding is sensitive to the locale of the application. The IDispatch() and virtual function table (VTBL) interfaces allow software developers a range of solutions that vary in cost of implementation and quality of national language support. All methods of the IDispatch() interface that are potentially sensitive to language are passed an LCID.

Following are some of the possible approaches a class implementation may take:

• Accept any LCID and use the same member names in all locales. This is acceptable if the interface will typically be accessed only by advanced users. For example, the member names for COM interfaces will never be localized.

• Simply return an error (DISP_E_UNKNOWNLCID) if the caller's LCID doesn't match the localized version of the class. This would prevent users from being able to write late-bound code which runs on machines with different localized implementations of the class.

• Recognize the particular version's localized names, as well as one language that is recognized in all versions. For example, a French version might accept French and English names, where English is the language supported in all versions. This would constrain users to use English when writing code that runs in all countries,.

• Accept all LCIDs supported by all versions of the product. This means that the implementation of GetIDsOfNames would need to interpret the passed array of names based on the given LCID. This is the preferred solution because users would be able to write code in their national language and run the code on any localized version of the application.

At the very least, the application must check the LCID before interpreting member names. Also note that the meaning of parameters passed to a member function may depend on the caller's national language. For example, a spreadsheet application might interpret the arguments to a SetFormula method differently, depending on the LCID.

19.3.3    Locale Identifier (LCID)

The IDispatch interface uses the 32-bit Windows definition of a LCID to identify locales. An LCID is a DWORD value that contains the LANGID in the lower word and a reserved value in the upper word.

This LCID has the components necessary to uniquely identify one of the installed system-defined locales.

/*
 * LCID creation/extraction macros:
 * MAKELCID - construct locale ID from language ID and country code.
 */
#define MAKELCID(l) ((DWORD)(((WORD)(l))|(((DWORD)((WORD)(0))) << 16)))

There are two predefined LCID values. LOCALE_SYSTEM_DEFAULT is the system default locale, and LOCALE_USER_DEFAULT is the current user's locale. However, when querying the NLS APIs for information, it is more efficient to query once for the current locale with GetSystemDefaultLCID() or GetUserDefaultLCID(), rather than using these constants.

19.3.4    Language Identifier (LANGID)

A LANGID is a 16-bit value that is the combination of a primary and sublanguage ID. Macros are provided for constructing a LANGID and extracting the fields.

LANGID creation/extraction macros include:

• MAKELANGID - construct LANGID from primary LANGID and sublanguage ID.

• PRIMARYLANGID - extract primary LANGID from a LANGID.

• SUBLANGID - extract sublanguage identifier (ID) from a LANGID.

• LANGIDFROMLCID - get the LANGID from an LCID.

#define MAKELANGID(p, s)            ((((USHORT)(s)) << 10) | (USHORT)(p))
#define PRIMARYLANGID(lgid)        ((USHORT)(lgid) & 0x3ff)
#define SUBLANGID(lgid)            ((USHORT)(lgid) >> 10)
#define LANGIDFROMLCID(lcid)        ((WORD)(lcid))

The following three combinations of primary and sublanguage IDs have special meanings:

Table 19-4:  Primary and Sublanguage ID Special Combinations

For primary language IDs, the range 0x200 to 0x3ff is user definable. The range 0x000 to 0x1ff is reserved for system use. The following table lists the primary LANGIDs supported by Automation:

Table 19-5:  Primary LANGIDs

For sublanguage IDs, the range 0x20 to 0x3f is user definable. The range 0x00 to 0x1f is reserved for system use. The following table lists the sublanguage IDs supported by Automation:

Table 19-6:  Sublanguage IDs Supported by Automation

The only difference between Spanish (Castilian) and Spanish (Modern) is the sort ordering. All of the LCType values are the same.

19.3.5    Locale Constants (LCTYPE)

An LCTYPE is a constant that specifies a particular piece of locale information. For example:

typedef  DWORD  LCTYPE;

The list of supported LCTYPES follows. All values are null-terminated, variable-length strings. Numeric values are expressed as strings of decimal digits, unless otherwise noted. The values in the brackets indicate the maximum number of characters allowed for the string (including the null termination). If no maximum is indicated, the string may be of variable length.

Table 19-7:  Supported LCTYPES

The following table shows the equivalence between LCTYPE values and the information stored in the [intl] section of Win.ini. These values are retrieved from Win.ini if information for the current system locale is queried. Values for LCTYPEs that are not in the following table do not depend on information stored in Win.ini.

Table 19-8:  Equivalence beteen LCTYPE Values and Win.ini [intl] Information

Unlike in Win.ini, values returned by LOCALE_SABBREVLANGNAME are always in uppercase.

19.4    Automation Interface Descriptions

19.4.1    IDispatch

IDispatch::GetIDsOfNames()

NAME

IDispatch::GetIDsOfNames() - Maps a single member and an optional set of argument names to a corresponding set of integer DISPIDs.

Synopsis

#include <Oaidl.h>

HRESULT GetIDsOfNames(
        REFIID riid,
        OLECHAR FAR * FAR * rgszNames,
        unsigned int cNames,
        LCID lcid,
        DISPID FAR * rgDispId );

Description

Maps a single member and an optional set of argument names to a corresponding set of integer DISPIDs, which can be used on subsequent calls to IDispatch::Invoke(). The dispatch function DispGetIDsOfNames() provides a standard implementation of GetIDsOfNames.

An IDispatch() implementation can associate any positive integer ID value with a given name. Zero is reserved for the default, or Value property; -1 is reserved to indicate an unknown name; and other negative values are defined for other purposes. For example, if GetIDsOfNames is called, and the implementation does not recognize one or more of the names, it returns DISP_E_UNKNOWNNAME, and the rgDispId array contains DISPID_UNKNOWN for the entries that correspond to the unknown names.

The member and parameter DISPIDs must remain constant for the lifetime of the object. This allows a client to obtain the DISPIDs once, and cache them for later use.

When GetIDsOfNames is called with more than one name, the first name (rgszNames[0]) corresponds to the member name, and subsequent names correspond to the names of the member's parameters.

The same name may map to different DISPIDs, depending on context. For example, a name may have a DISPID when it is used as a member name with a particular interface, a different ID as a member of a different interface, and different mapping for each time it appears as a parameter.

The IDispatch() interface binds to names at run time. To bind at compile time instead, an IDispatch() client can map names to DISPIDs by using the type information interfaces described in Chapter 18. This allows a client to bind to members at compile time and avoid calling GetIDsOfNames at run time. For a description of binding at compile time, see Section Section 18.1.

The implementation of GetIDsOfNames is case insensitive. Users that need case-sensitive name mapping should use type information interfaces to map names to DISPIDs, rather than call GetIDsOfNames.

Parameters

riid

Reserved for future use. Must be IID_NULL.

rgszNames

Passed-in array of names to be mapped.

cNames

Count of the names to be mapped.

lcid

The locale context in which to interpret the names.

rgDispId

Caller-allocated array, each element of which contains an identifier (ID) corresponding to one of the names passed in the rgszNames array. The first element represents the member name. The subsequent elements represent each of the member's parameters.

Return Values

The return value obtained from the returned HRESULT is one of the following:

S_OK

Success.

E_OUTOFMEMORY

Out of memory.

DISP_E_UNKNOWNNAME

One or more of the names were not known. The returned array of DISPIDs contains DISPID_UNKNOWN for each entry that corresponds to an unknown name.

DISP_E_UNKNOWNLCID

The locale identifier (LCID) was not recognized.

Examples

The following code from the Lines sample file Lines.cpp implements the GetIDsOfNames member function for the CLine class. The COM object uses the standard implementation, DispGetIDsOfNames().

STDMETHODIMP 
CLine::GetIDsOfNames(
        REFIID riid,
        OLECHAR FAR* FAR* rgszNames,
        UINT cNames,
        LCID lcid,
        DISPID FAR* rgDispId)
{
        return DispGetIDsOfNames(m_ptinfo, rgszNames, cNames, rgDispId);
}

The following code might appear in an ActiveX client that calls GetIDsOfNames to get the DISPID of the CLine Color property.

HRESULT hresult;
IDispatch() FAR* pdisp = (IDispatch() FAR*)NULL;
DISPID dispid;
OLECHAR FAR* szMember = ``color'';
// Code that sets a pointer to the dispatch (pdisp) is omitted.
hresult = pdisp->GetIDsOfNames(
    IID_NULL,
    &szMember,
    1, LOCALE_SYSTEM_DEFAULT,
    &dispid);

See Also

CreateStdDispatch(), DispGetIDsOfNames(), ITypeInfo::GetIDsOfNames  

IDispatch::GetTypeInfo()

NAME

IDispatch::GetTypeInfo() - Retrieves the type information for an object, which can then be used to get the type information for an interface.

Synopsis

#include <Oaidl.h>

HRESULT GetTypeInfo(
        unsigned int iTInfo,
        LCID lcid,
        ITypeInfo FAR * FAR * ppTInfo );

Parameters

iTInfo

The type information to return. Pass 0 to retrieve type information for the IDispatch() implementation.

lcid

The locale identifier for the type information. An object may be able to return different type information for different languages. This is important for classes that support localized member names. For classes that do not support localized member names, this parameter can be ignored.

ppTInfo

Receives a pointer to the requested type information object.

Return Values

The return value obtained from the returned HRESULT is one of the following:

S_OK

Success; the type information element exists.

DISP_E_BADINDEX

Failure; iTInfo argument was not 0.

TYPE_E_ELEMENTNOTFOUND

Failure; iTInfo argument was not 0.

Retrieves the type information for an object, which can then be used to get the type information for an interface.

Examples

The following code from the sample file Lines.cpp loads information from the type library and implements the member function GetTypeInfo:

// These lines are from CLines::Create load type information for the
// Lines collection from the type library. 
    hr = LoadTypeInfo(&pLines->m_ptinfo, IID_ILines);
    if (FAILED(hr))
        goto error;
// Additional code omitted for brevity.
// This function implements GetTypeInfo for the CLines collection.
STDMETHODIMP
CLines::GetTypeInfo(
        UINT iTInfo,
        LCID lcid,
        ITypeInfo() FAR* FAR* ppTInfo)
{
    *ppTInfo = NULL;
    if(iTInfo != 0)
        return ResultFromScode(DISP_E_BADINDEX);
    m_ptinfo->AddRef();
    *ppTInfo = m_ptinfo;
    return NOERROR;
}

See Also

CreateStdDispatch, CreateDispTypeInfo.  

IDispatch::GetTypeInfoCount()

NAME

IDispatch::GetTypeInfoCount() - Retrieves the number of type information interfaces that an object provides (either 0 or 1).

Synopsis

#include <Oaidl.h>

HRESULT GetTypeInfoCount(
        unsigned int FAR * pctinfo );

Description

Retrieves the number of type information interfaces that an object provides (either 0 or 1).

The function may return zero, which indicates that the object does not provide any type information. In this case, the object may still be programmable through IDispatch(), but does not provide type information for browsers, compilers, or other programming tools that access type information. This can be useful for hiding an object from browsers or for preventing early binding on an object.

Parameters

pctinfo

Points to a location that receives the number of type information interfaces provided by the object. If the object provides type information, this number is 1; otherwise the number is 0.

Return Values

The return value obtained from the returned HRESULT is one of the following:

S_OK

Success.

E_NOTIMPL

Failure.

Examples

This code from the Lines sample file Lines.cpp implements the GetTypeInfoCount member function for the CLines class (ActiveX or OLE object).

STDMETHODIMP
CLines::GetTypeInfoCount(UINT FAR* pctinfo)
{
    *pctinfo = 1;
    return NOERROR;
}

See Also

CreateStdDispatch()  

IDispatch::Invoke()

NAME

IDispatch::Invoke() - Provides access to properties and methods exposed by an object.

Synopsis

HRESULT Invoke(
        DISPID dispIdMember,
        REFIID riid,
        LCID lcid,
        WORD wFlags,
        DISPPARAMS FAR * pDispParams,
        VARIANT FAR * pVarResult,
        EXCEPINFO FAR * pExcepInfo,
        unsigned int FAR * puArgErr );

Description

Provides access to properties and methods exposed by an object. The dispatch function DispInvoke() provides a standard implementation of IDispatch::Invoke().

Generally, you should not implement Invoke directly. Instead, use the dispatch interface create functions CreateStdDispatch() and DispInvoke(). For details, refer to CreateStdDispatch and DispInvoke in this chapter, and Section Section 19.1.1.

If some application-specific processing needs to be performed before calling a member, the code should perform the necessary actions, and then call ITypeInfo::Invoke() to invoke the member. ITypeInfo::Invoke() acts exactly like IDispatch::Invoke(). The standard implementations of IDispatch::Invoke() created by CreateStdDispatch() and DispInvokedefer to ITypeInfo::Invoke().

In an ActiveX client, IDispatch::Invoke() should be used to get and set the values of properties, or to call a method of an ActiveX object. The dispIdMember argument identifies the member to invoke. The DISPIDs that identify members are defined by the implementor of the object and can be determined by using the object's documentation, the IDispatch::GetIDsOfNames() function, or the ITypeInfo() interface.

The information that follows addresses developers of ActiveX clients and others who use code to expose ActiveX objects. It describes the behavior that users of exposed objects should expect.

Returning Errors

Invoke returns DISP_E_MEMBERNOTFOUND if one of the following conditions occurs:

• A member or parameter with the specified DISPID and matching cArgs cannot be found, and the parameter is not optional.

• The member is a void function, and the caller did not set pVarResult to NULL.

• The member is a read-only property, and the caller set wFlags to DISPATCH_PROPERTYPUT or DISPATCH_PROPERTYPUTREF.

If Invoke finds the member, but uncovers errors in the argument list, it returns one of several other errors. DISP_E_BAD_PARAMCOUNT means that the DISPPARAMS structure contains an incorrect number of parameters for the property or method. DISP_E_NONAMEDARGS means that Invoke received named arguments, but they are not supported by the member.

DISP_E_PARAMNOTFOUND means that the correct number of parameters was passed, but the DISPID for one or more parameters was incorrect. If Invokecannot convert one of the arguments to the desired type, it returns DISP_E_TYPEMISMATCH. In these two cases, if it can identify which argument is incorrect, Invoke sets *puArgErr to the index within rgvarg of the argument with the error. For example, if an Automation method expects a reference to a double-precision number as an argument, but receives a reference to an integer, the argument is coerced. However, if the method receives a date, IDispatch::Invoke() returns DISP_E_TYPEMISMATCH and sets *puArgErr to the index of the integer in the argument array.

Automation provides functions to perform standard conversions of VARIANT, and these functions should be used for consistent operation. DISP_E_TYPEMISMATCH is returned only when these functions fail.

Raising Exceptions During Invoke

When you implement IDispatch::Invoke, errors can be communicated either through the normal return value or by raising an exception. An exception is a special situation that is normally handled by jumping to the nearest routine enclosing the exception handler.

To raise an exception, IDispatch::Invoke() returns DISP_E_EXCEPTION and fills the structure passed through pExcepInfo with information about the cause of the exception or error. You can use the information to understand the cause of the exception and proceed as necessary.

The exception information structure includes an error code number that identifies the kind of exception (a string that describes the error in a human-readable way). It also includes a Help file and a Help context number that can be passed to Windows Help for details about the error. At a minimum, the error code number must be filled with a valid number.

If you consider IDispatch() another way to call C++ methods in an interface, EXCEPINFO models the raising of an exception or longjmp() call by such a method.

Indexed Properties

When you invoke indexed properties of any dimension, you must pass the indexes as additional arguments. To set an indexed property, place the new value in the first element of the rgvarg[ ] vector, and the indexes in the subsequent elements. To get an indexed property, pass the indexes in the first n elements of rgvarg, and the number of indexes in cArg.Invoke returns the value of the property in pVarResult.

Automation stores array data in column-major order, which is the same ordering scheme used by Visual Basic and FORTRAN, but different from C, C++, and Pascal. If you are programming in C, C++, or Pascal, you must pass the indexes in the reverse order. The following example shows how to fill the DISPPARAMS structure in C++.

dispparams.rgvarg[0].vt = VT_I2;
dispparams.rgvarg[0].iVal = 99;
dispparams.rgvarg[1].vt = VT_I2;
dispparams.rgvarg[1].iVal = 2;
dispparams.rgvarg[2].vt = VT_I2;
dispparams.rgvarg[2].iVal = 1;
dispparams.rgdispidNamedArgs = DISPID_PROPERTYPUT;
dispparams.cArgs = 3;
dispparams.cNamedArgs = 1;

The example changes the value of Prop[1,2] to 99. The new property value is passed in rgvarg[0]. The right-most index is passed in rgvarg[1], and the next index in rgvarg[2]. The cArgs field specifies the number of elements of rgvarg[ ] that contain data, and cNamedArgs is 1, indicating the new value for the property.

Property collections are an extension of this feature.

Passing Parameters

Arguments to the method or property being invoked are passed in the DISPPARAMS structure. This structure consists of a pointer to an array of arguments represented as variants, a pointer to an array of DISPIDs for named arguments, and the number of arguments in each array.

typedef struct FARSTRUCT tagDISPPARAMS{
    VARIANTARG FAR* rgvarg;            // Array of arguments.
    DISPID FAR* rgdispidNamedArgs;     // Dispatch IDs of named arguments.
    unsigned int cArgs;                // Number of arguments.
    unsigned int cNamedArgs;         // Number of named arguments.
} DISPPARAMS;

The arguments are passed in the array rgvarg[ ], with the number of arguments passed in cArgs. The arguments in the array should be placed from last to first, so rgvarg[0] has the last argument and rgvarg[cArgs -1] has the first argument. The method or property may change the values of elements within the array rgvarg, but only if it has set the VT_BYREF flag. Otherwise, consider the elements as read-only.

A dispatch invocation can have named arguments as well as positional arguments. If cNamedArgs is 0, all the elements of rgvarg[ ] represent positional arguments. If cNamedArgs is not 0, each element of rgdispidNamedArgs[ ] contains the DISPID of a named argument, and the value of the argument is in the matching element of rgvarg[ ]. The DISPIDs of the named arguments are always contiguous in rgdispidNamedArgs, and their values are in the first cNamedArgs elements of rgvarg. Named arguments cannot be accessed positionally, and positional arguments cannot be named.

The DISPID of an argument is its zero-based position in the argument list. For example, the following method takes three arguments.

BOOL _export CDECL
CCredit::CheckCredit(BSTR bstrCustomerID,    // DISPID = 0.
                     BSTR bstrLenderID,      // DISPID = 1.
                     CURRENCY cLoanAmt)      // DISPID = 2.
{
// Code omitted.
}

If you include the DISPID with each named argument, you can pass the named arguments to Invoke in any order. For example, if a method is to be invoked with two positional arguments, followed by three named arguments (A, B, and C), using the following hypothetical syntax, then cArgs would be 5, and cNamedArgs would be 3.

object.method("arg1", "arg2", A := "argA", B := "argB", C := "argC")

The first positional argument would be in rgvarg[4]. The second positional argument would be in rgvarg[3]. The ordering of named arguments is not important to the IDispatch() implementation, but these arguments are generally passed in reverse order. The argument A would be in rgvarg[2], with the DISPID of A in rgdispidNamedArgs[2]. The argument B would be in rgvarg[1], with the corresponding DISPID in rgdispidNamedArgs[1]. The argument C would be in rgvarg[0], with the DISPID corresponding to C in rgdispidNamedArgs[0]. You can also use Invoke on members with optional arguments, but all optional arguments must be of type VARIANT. As with required arguments, the contents of the argument vector depend on whether the arguments are positional or named. The invoked member must ensure that the arguments are valid. Invoke merely passes the DISPPARAMS structure it receives.

Omitting named arguments is straightforward. You would pass the arguments in rgvarg and their DISPIDs in rgdispidNamedArgs. To omit the argument named B (in the preceding example) you would set rgvarg[0] to the value of C, with its DISPID in rgdispidNamedArgs[0]; and rgvarg[1] to the value of A, with its DISPID in rgdispidNamedArgs[1]. The subsequent positional arguments would occupy elements 2 and 3 of the arrays. In this case, cArgs is 4 and cNamedArgs is 2.

If the arguments are positional (unnamed), you would set cArgs to the total number of possible arguments, cNamedArgs to 0, and pass VT_ERROR as the type of the omitted arguments, with the status code DISP_E_PARAMNOTFOUND as the value. For example, the following code invokes ShowMe (,1).

VARIANT FAR *pVarResult;
EXCEPINFO FAR *pExcepInfo;
unsigned int FAR *puArgErr;
DISPPARAMS dispparams; 
// Code omitted for brevity.
szMember = ``ShowMe'';
hresult = pdisp->GetIDsOfNames(IID_NULL, &szMember, 1,
                                LOCALE_USER_DEFAULT, &dispid) ;
dispparams.rgvarg[0].vt = VT_I2;
dispparams.rgvarg[0].ival = 1;
dispparams.rgvarg[1].vt = VT_ERROR;
dispparams.rgvarg[1].scode = DISP_E_PARAMNOTFOUND;
dispparams.cArgs = 2;
dispparams.cNamedArgs = 0;
hresult = pdisp->Invoke(
        dispid,
        IID_NULL,
        LOCALE_USER_DEFAULT,
        DISPATCH_METHOD,
        &dispparams, pVarResult, pExcepInfo, puArgErr);

The example takes two positional arguments, but omits the first. Therefore, rgvarg[0] contains 1, the value of the last argument in the argument list, and rgvarg[1] contains VT_ERROR and the error return value, indicating the omitted first argument.

The calling code is responsible for releasing all strings and objects referred to by rgvarg[ ] or placed in *pVarResult. As with other parameters that are passed by value, if the invoked member must maintain access to a string after returning, you should copy the string. Similarly, if the member needs access to a passed-object pointer after returning, it must call the AddRef() function on the object. A common example occurs when an object property is changed to refer to a new object, using the DISPATCH_PROPERTYPUTREF flag.

For those implementing IDispatch::Invoke, Automation provides the DispGetParam() function to retrieve parameters from the argument vector and coerce them to the proper type. For details, see DispGetParam().

Getting and Setting Properties

Properties are accessed in the same way as methods, except you specify DISPATCH_PROPERTYGET or DISPATCH_PROPERTYPUT instead of DISPATCH_METHOD. Some languages can not distinguish between retrieving a property and calling a method. In this case, you should set the flags DISPATCH_PROPERTYGET and DISPATCH_METHOD.

The following example gets the value of a property named On. You can assume that the object has been created, and that its interfaces have been queried, as in the previous example.

VARIANT FAR *pVarResult;
// Code omitted for brevity.
szMember = ``On'';
hresult = pdisp->GetIDsOfNames(IID_NULL, &szMember, 1, 
                LOCALE_USER_DEFAULT, &dispid);
hresult = pdisp->Invoke(
        dispid,
        IID_NULL,
        LOCALE_USER_DEFAULT,
        DISPATCH_PROPERTYGET,
        &dispparamsNoArgs, pVarResult, NULL, NULL);

As in the previous example, the code calls GetIDsOfNames for the DISPID of the On property, and then passes the ID to Invoke. Then, Invoke returns the property's value in pVarResult. In general, the return value does not set VT_BYREF. However, this bit may be set and a pointer returned to the return value, if the lifetime of the return value is the same as that of the object.

To change the property's value, the call looks like this:

VARIANT FAR *pVarResult;
DISPPARAMS dispparams; 
DISPID mydispid = DISP_PROPERTYPUT
// Code omitted for brevity.
szMember = ``On'';
dispparams.rgvarg[0].vt = VT_BOOL;
dispparams.rgvarg[0].bool = FALSE;
dispparams.rgdispidNamedArgs = &mydispid;
dispparams.cArgs = 1;
dispparams.cNamedArgs = 1;
hresult = pdisp->GetIDsOfNames(IID_NULL, &szMember, 1, 
                LOCALE_USER_DEFAULT, &dispid); 
hresult = pdisp->Invoke(
        dispid,
        IID_NULL,
        LOCALE_USER_DEFAULT,
        DISPATCH_PROPERTYPUT,
        &dispparams, NULL, NULL, NULL);

The new value for the property (the Boolean value FALSE) is passed as an argument when the On property's Put function is invoked. The DISPID for the argument is DISPID_PROPERTYPUT. This DISPID is defined by Automation to designate the parameter that contains the new value for a property's Put function. The remaining details of the DISPPARAMS structure are described in the next section.

The DISPATCH_PROPERTYPUT flag in the previous example indicates that a property is being set by value. In Visual Basic, the following statement assigns the Value property (the default) of YourObj to the Prop property:

MyObj.Prop = YourObj

This statement should be flagged as a DISPATCH_PROPERTYPUT. Similarly, statements like the following assign the Value property of one object to the Value property of another object.

Worksheet.Cell(1,1) = Worksheet.Cell(6,6)
MyDoc.Text1 = YourDoc.Text1

These statements result in a PROPERTY_PUT operation on Worksheet.Cell(1,1) and MyDoc.Text1.

Use the DISPATCH_PROPERTYPUTREF flag to indicate a property or data member that should be set by reference. For example, the following Visual Basic statement assigns the pointer YourObj to the property Prop, and should be flagged as DISPATCH_PROPERTYPUTREF.

Set MyObj.Prop = YourObj

The Set statement causes a reference assignment, rather than a value assignment.

The parameter on the right side is always passed by name, and should not be accessed positionally.

Calling a Method With No Arguments

The simplest use of Invoke is to call a method that does not have any arguments. You only need to pass the DISPID of the method, a LCID, the DISPATCH_METHOD flag, and an empty DISPPARAMS structure. For example:

HRESULT hresult;
IUnknown FAR* punk;
IDispatch FAR* pdisp = (IDispatch FAR*)NULL;
OLECHAR FAR* szMember = ``Simple'';
DISPID dispid;
DISPPARAMS dispparamsNoArgs = {NULL, NULL, 0, 0};
hresult = CoCreateInstance(CLSID_CMyObject, NULL, CLSCTX_SERVER,
                IID_Unknown, (void FAR* FAR*)&punk);
hresult = punk->QueryInterface(IID_IDispatch,
                (void FAR* FAR*)&pdisp);
hresult = pdisp->GetIDsOfNames(IID_NULL, &szMember, 1,
                LOCALE_USER_DEFAULT, &dispid);
hresult = pdisp->Invoke(
        dispid,
        IID_NULL,
        LOCALE_USER_DEFAULT,
        DISPATCH_METHOD,
        &dispparamsNoArgs, NULL, NULL, NULL);

The example invokes a method named Simple on an object of the class CMyObject. First, it calls CoCreateInstance(), which instantiates the object and returns a pointer to the object's IUnknown() interface (punk). Next, it calls QueryInterface(), receiving a pointer to the object's IDispatch() interface (pdisp). It then uses pdisp to call the object's GetIDsOfNames function, passing the string Simple in szMember to get the DISPID for the Simple method. With the DISPID for Simple in dispid, it calls Invoke to invoke the method, specifying DISPATCH_METHOD for the wFlags parameter and using the system default locale.

To further simplify the code, the example declares a DISPPARAMS structure named dispparamsNoArgs that is appropriate to an Invoke call with no arguments.

Because the Simple method does not take any arguments and does not return a result, the puArgErr and pVarResult parameters are NULL. In addition, the example passes NULL for pExcepInfo, indicating that it is not prepared to handle exceptions and will handle only HRESULT errors.

Most methods, however, take one or more arguments. To invoke these methods, the DISPPARAMS structure should be filled in, as described in ``Passing Parameters'' below.

Automation defines special DISPIDs for invoking an object's Value property (the default), and the members _NewEnum, and Evaluate. See Chapter 18.

Parameters

dispIdMember

Identifies the member. Use GetIDsOfNames or the object's documentation to obtain the dispatch identifier.

riid

Reserved for future use. Must be IID_NULL.

lcid

The locale context in which to interpret arguments. The lcid is used by the GetIDsOfNames function, and is also passed to Invoke to allow the object to interpret its arguments specific to a locale.

Applications that do not support multiple national languages can ignore this parameter. For more information, refer to Section Section 19.3.

wFlags

Flags describing the context of the Invoke call, include:

1.  Invoke Context Flags

pDispParams

Pointer to a structure containing an array of arguments, an array of argument DISPIDs for named arguments, and counts for the number of elements in the arrays. See the Description section that follows for a description of the DISPPARAMS structure.

pVarResult

Pointer to the location where the result is to be stored, or NULL if the caller expects no result. This argument is ignored if DISPATCH_PROPERTYPUT or DISPATCH_PROPERTYPUTREF is specified.

pExcepInfo

Pointer to a structure that contains exception information. This structure should be filled in if DISP_E_EXCEPTION is returned. Can be NULL.

puArgErr

The index within rgvarg of the first argument that has an error. Arguments are stored in pDispParams->rgvarg in reverse order, so the first argument is the one with the highest index in the array. This parameter is returned only when the resulting return value is DISP_E_TYPEMISMATCH or DISP_E_PARAMNOTFOUND. For details, see Description.

Return Values

The return value obtained from the returned HRESULT is one of the following:

S_OK

Success.

DISP_E_BADPARAMCOUNT

The number of elements provided to DISPPARAMS is different from the number of arguments accepted by the method or property.

DISP_E_BADVARTYPE

One of the arguments in rgvarg is not a valid variant type.

DISP_E_EXCEPTION

The application needs to raise an exception. In this case, the structure passed in pExcepInfo should be filled in.

DISP_E_MEMBERNOTFOUND

The requested member does not exist, or the call to Invoke tried to set the value of a read-only property.

DISP_E_NONAMEDARGS

This implementation of IDispatch() does not support named arguments.

DISP_E_OVERFLOW

One of the arguments in rgvarg could not be coerced to the specified type.

DISP_E_PARAMNOTFOUND

One of the parameter DISPIDs does not correspond to a parameter on the method. In this case, puArgErr should be set to the first argument that contains the error.

DISP_E_TYPEMISMATCH

One or more of the arguments could not be coerced. The index within rgvarg of the first parameter with the incorrect type is returned in the puArgErr parameter.

DISP_E_UNKNOWNINTERFACE

The interface identifier passed in riid is not IID_NULL.

DISP_E_UNKNOWNLCID

The member being invoked interprets string arguments according to the LCID, and the LCID is not recognized. If the LCID is not needed to interpret arguments, this error should not be returned.

DISP_E_PARAMNOTOPTIONAL

A required parameter was omitted.

In 16-bit versions, you can define your own errors using the MAKE_SCODE value macro.

Examples

This code from the Lines sample file Lines.cpp implements the Invoke member function for the CLines class.

STDMETHODIMP
CLines::Invoke(
    DISPID dispidMember,
    REFIID riid,
    LCID lcid,
    WORD wFlags,
    DISPPARAMS FAR* pDispParams,
    VARIANT FAR* pVarResult,
    EXCEPINFO FAR* pExcepInfo,
    UINT FAR* puArgErr)
{ 
    return DispInvoke(
        this, m_ptinfo,
        dispidMember, wFlags, pDispParams,
        pVarResult, pExcepInfo, puArgErr); 
}

The next code example calls the CLines::Invoke member function to get the value of the Color property:

HRESULT hr;
EXCEPINFO excepinfo;
UINT nArgErr;
VARIANT vRet;
DISPPARAMS FAR* pdisp;
OLECHAR FAR* szMember;
DISPPARAMS dispparamsNoArgs = {NULL, NULL, 0, 0};
// Initialization code omitted for brevity.
szMember = ``Color'';
hr = pdisp->GetIDsOfNames(IID_NULL, &szMember, 1, LOCALE_USER_DEFAULT,
    &dispid);
// Get Color property.
hr = pdisp->Invoke(dispid, IID_NULL, LOCALE_SYSTEM_DEFAULT,
    DISPATCH_PROPERTYGET, &dispparams, &vRet, &excepinfo, &nArgErr);

See Also

CreateStdDispatch(), DispInvoke, DispGetParam(), ITypeInfo::Invoke

19.4.2    ICreateTypeInfo Interface

The ICreateTypeInfo() interface provides the tools for creating and administering the type information defined through the type description.  

ICreateTypeInfo::AddFuncDesc()

NAME

ICreateTypeInfo::AddFuncDesc() -

Synopsis

#include <Oaidl.h>

HRESULT AddFuncDesc(
        unsigned int index,
        FUNCDESC FAR* pFuncDesc );

Description

AddFuncDesc adds a function description to the type description.

The index specifies the order of the functions within the type information. The first function has an index of zero. If an index is specified that exceeds one less than the number of functions in the type information, an error is returned. Calling this function does not pass ownership of the FUNCDESC structure to ICreateTypeInfo(). Therefore, the caller must still de-allocate the FUNCDESC structure.

The passed-in virtual function table (VTBL) field (oVft) of the FUNCDESC is ignored. This attribute is set when ICreateTypeInfo::LayOut is called.

The function AddFuncDesc uses the passed-in member identifier (ID) fields within each FUNCDESC for classes with TYPEKIND = TKIND_DISPATCH or TKIND_INTERFACE. If the member IDs are set to MEMBERID_NIL, AddFuncDescassigns member IDs to the functions. Otherwise, the member ID fields within each FUNCDESC are ignored.

Any HREFTYPE fields in the FUNCDESC structure must have been produced by the same instance of ITypeInfo() for which AddFuncDesc is called.

The get and put accessor functions for the same property must have the same dispatch identifier (DISPID).

Parameters

index

Index of the new FUNCDESC in the type information.

pFuncDesc Pointer to a FUNCDESC structure that describes the function. The bstrIDLInfo field in the FUNCDESC should be set to NULL for future compatibility.

Return Values

The return value of the returned HRESULT is one of the following:

S_OK

Success.

STG_E_INSUFFICIENTMEMORY

Out of memory.

E_OUTOFMEMORY

Out of memory.

E_INVALIDARG

One or more of the arguments is invalid.

E_ACCESSDENIED

Cannot write to the destination.

TYPE_E_WRONGTYPEKIND

Type mismatch.

ICreateTypeInfo::AddImplType()

NAME

ICreateTypeInfo::AddImplType() - Specifies an inherited interface, or an interface implemented by a component object class (coclass).

Synopsis

#include <Oaidl.h>

HRESULT AddImplType(
        unsigned int index,
        HREFTYPE hRefType );

Description

To specify an inherited interface, use index = 0. For a dispinterface with Syntax 2, call ICreateTypeInfo::AddImplType() twice, once with nindex = 0 for the inherited IDispatch() and once with nindex = 1 for the interface that is being wrapped. For a dual interface, call ICreateTypeInfo::AddImplType() with nindex = -1 for the TKIND_INTERFACE type information component of the dual interface.

Parameters

index

Index of the implementation class to be added. Specifies the order of the type relative to the other type.

hRefType Handle to the referenced type description obtained from the AddRefType description.

Return Values

The return value of the returned HRESULT is one of the following:

S_OK

Success.

STG_E_INSUFFICIENTMEMORY

Out of memory.

E_OUTOFMEMORY

Out of memory.

E_ACCESSDENIED

Cannot write to the destination.

TYPE_E_WRONGTYPEKIND

Type mismatch.

ICreateTypeInfo::AddRefTypeInfo()

NAME

ICreateTypeInfo::AddRefTypeInfo() - Adds a type description to those referenced by the type description being created.

Synopsis

#include <Oaidl.h>

HRESULT AddRefTypeInfo(
        ITypeInfo FAR* pTInfo,
        HREFTYPE FAR* phRefType );

Description

The second parameter returns a pointer to the handle of the added type information. If AddRefTypeInfo has been called previously for the same type information, the index that was returned by the previous call is returned in phRefType. If the referenced type description is in the type library being created, its type information can be obtained by calling IUnknown::QueryInterface(IID_ITypeInfo, ...) on the ICreateTypeInfo() interface of that type description.

Parameters

pTInfo

Pointer to the type description to be referenced.

phRefType On return, pointer to the handle that this type description associates with the referenced type information.

Return Values

The return value of the returned HRESULT is one of the following:

S_OK

Success.

STG_E_INSUFFICIENTMEMORY

Out of memory.

E_OUTOFMEMORY

Out of memory.

E_INVALIDARG

One or more of the arguments is invalid.

E_ACCESSDENIED

Cannot write to the destination.

TYPE_E_WRONGTYPEKIND

Type mismatch.

ICreateTypeInfo::AddVarDesc()

NAME

ICreateTypeInfo::AddVarDesc() - Adds a variable or data member description to the type description.

Synopsis

#include <Oaidl.h>

HRESULT AddVarDesc(
        unsigned int index,
        VARDESC FAR* pVarDesc );

Description

The index specifies the order of the variables. The first variable has an index of zero. ICreateTypeInfo::AddVarDesc() returns an error if the specified index is greater than the number of variables currently in the type information. Calling this function does not pass ownership of the VARDESC structure to ICreateTypeInfo(). The instance field (oInst) of the VARDESC structure is ignored. This attribute is set only when ICreateTypeInfo::LayOut is called. Also, the member ID fields within the VARDESCs are ignored unless the TYPEKIND of the class is TKIND_DISPATCH.

Any HREFTYPE fields in the VARDESC structure must have been produced by the same instance of ITypeInfo() for which AddVarDesc is called.

AddVarDesc ignores the contents of the idldesc field of the ELEMDESC.

Parameters

index

Index of the variable or data member to be added to the type description.

pVarDesc Pointer to the variable or data member description to be added.

Return Values

The return value of the returned HRESULT is one of the following:

S_OK

Success.

STG_E_INSUFFICIENTMEMORY

Out of memory.

E_OUTOFMEMORY

Out of memory.

E_INVALIDARG

One or more of the arguments is invalid.

E_ACCESSDENIED

Cannot write to the destination.

TYPE_E_WRONGTYPEKIND

Type mismatch.

ICreateTypeInfo::DefineFuncAsDllEntry()

NAME

ICreateTypeInfo::DefineFuncAsDllEntry() - Associates a DLL entry point with the function that has the specified index.

Synopsis

#include <Oaidl.h>

HRESULT DefineFuncAsDllEntry(
        unsigned int index,
        OLECHAR FAR* szDllName,
        OLECHAR FAR* szProcName );

Description

If the high word of szProcName is zero, then the low word must contain the ordinal of the entry point; otherwise, szProcName points to the zero-terminated name of the entry point.

Parameters

index

Index of the function.

szDllName Name of the DLL that contains the entry point.

szProcName Name of the entry point or an ordinal (if the high word is zero).

Return Values

The return value of the returned HRESULT is one of the following:

S_OK

Success.

STG_E_INSUFFICIENTMEMORY

Out of memory.

E_OUTOFMEMORY

Out of memory.

E_INVALIDARG

One or more of the arguments is invalid.

TYPE_E_ELEMENTNOTFOUND

The element cannot be found.

TYPE_E_WRONGTYPEKIND

Type mismatch.

ICreateTypeInfo::LayOut()

NAME

ICreateTypeInfo::LayOut() - Assigns VTBL offsets for virtual functions and instance offsets for per-instance data members, and creates the two type descriptions for dual interfaces.

Synopsis

HRESULT LayOut(
         );

Description

LayOut also assigns member ID numbers to the functions and variables, unless the TYPEKIND of the class is TKIND_DISPATCH. Call LayOut after all members of the type information are defined, and before the type library is saved.

Use ICreateTypeLib::SaveAllChanges to save the type information after calling LayOut. Other members of the ICreateTypeInfo() interface should not be called after calling LayOut.

Different implementations of ICreateTypeInfo() or other interfaces that create type information are free to assign any member ID numbers, provided that all members (including inherited members), have unique IDs. For examples, see ICreateTypeInfo2.

Parameters

None.

Return Values

The return value of the returned HRESULT is one of the following:

S_OK

Success.

STG_E_INSUFFICIENTMEMORY

Out of memory.

E_OUTOFMEMORY

Out of memory.

E_ACCESSDENIED

Cannot write to the destination.

TYPE_E_UNDEFINEDTYPE

Bound to unrecognized type.

TYPE_E_INVALIDSTATE

The state of the type library is not valid for this operation.

TYPE_E_WRONGTYPEKIND

Type mismatch.

TYPE_E_ELEMENTNOTFOUND

The element cannot be found.

TYPE_E_AMBIGUOUSNAME

More than one item exists with this name.

TYPE_E_SIZETOOBIG

The type information is too long.

TYPE_E_TYPEMISMATCH

Type mismatch.

ICreateTypeInfo::SetAlignment()

NAME

ICreateTypeInfo::SetAlignment() - Specifies the data alignment for an item of TYPEKIND=TKIND_RECORD.

Synopsis

#include <Oaidl.h>

HRESULT SetAlignment(
         unsigned short cbAlignment );

Description

The alignment is the minimum of the natural alignment (for example, byte data on byte boundaries, word data on word boundaries, and so on), and the alignment denoted by cbAlignment.

Parameters

cbAlignment

Alignment method for the type. A value of 0 indicates alignment on the 64K boundary; 1 indicates no special alignment. For other values, n indicates alignment on byte n.

Return Values

The return value of the returned HRESULT is one of the following:

S_OK

Success.

STG_E_INSUFFICIENTMEMORY

Out of memory.

E_OUTOFMEMORY

Out of memory.

E_ACCESSDENIED

Cannot write to the destination.

TYPE_E_INVALIDSTATE

The state of the type library is not valid for this operation.

ICreateTypeInfo::SetDocString()

NAME

ICreateTypeInfo::SetDocString() - Sets the documentation string displayed by type browsers.

Synopsis

#include <Oaidl.h>

HRESULT SetDocString(
         OLECHAR FAR* pStrDoc );

Description

The documentation string is a brief description of the type description being created.

Parameters

pStrDoc

Pointer to the documentation string.

Return Values

The return value of the returned HRESULT is one of the following:

S_OK

Success.

STG_E_INSUFFICIENTMEMORY

Out of memory.

E_OUTOFMEMORY

Out of memory.

E_ACCESSDENIED

Cannot write to the destination.

TYPE_E_INVALIDSTATE

The state of the type library is not valid for this operation.

ICreateTypeInfo::SetFuncAndParamNames()

NAME

ICreateTypeInfo::SetFuncAndParamNames() - Sets the name of a function and the names of its parameters to the names in the array of pointers rgszNames.

Synopsis

#include <Oaidl.h>

HRESULT SetFuncAndParamNames(
        unsigned int index,
        OLECHAR FAR* FAR* rgszNames,
        unsigned int cNames );

Description

The function SetFuncAndParamNames needs to be used once for each property. The last parameter for put and putref accessor functions is unnamed.

Parameters

index

Index of the function whose function name and parameter names are to be set.

rgszNames Array of pointers to names. The first element is the function name. Subsequent elements are names of parameters.

cNames Number of elements in the rgszNames array.

Return Values

The return value of the returned HRESULT is one of the following:

S_OK

Success.

STG_E_INSUFFICIENTMEMORY

Out of memory.

E_OUTOFMEMORY

Out of memory.

E_INVALIDARG

One or more of the arguments is invalid.

E_ACCESSDENIED

Cannot write to the destination.

TYPE_E_ELEMENTNOTFOUND

The element cannot be found.

ICreateTypeInfo::SetFuncDocString()

NAME

ICreateTypeInfo::SetFuncDocString() - Sets the documentation string for the function with the specified index.

Synopsis

#include <Oaidl.h>

HRESULT SetFuncDocString(
        unsigned int index,
        OLECHAR FAR* szDocString );

Description

The documentation string is a brief description of the function intended for use by tools such as type browsers. SetFuncDocString only needs to be used once for each property, because all property accessor functions are identified by one name.

Parameters

index

Index of the function.

szDocString Pointer to the documentation string.

Return Values

The return value of the returned HRESULT is one of the following:

S_OK

Success.

STG_E_INSUFFICIENTMEMORY

Out of memory.

E_OUTOFMEMORY

Out of memory.

E_INVALIDARG

One or more of the arguments is invalid.

E_ACCESSDENIED

Cannot write to the destination.

TYPE_E_ELEMENTNOTFOUND

The element cannot be found.

ICreateTypeInfo::SetFuncHelpContext()

NAME

ICreateTypeInfo::SetFuncHelpContext() - Sets the Help context ID for the function with the specified index.

Synopsis

#include <Oaidl.h>

HRESULT SetFuncHelpContext(
        unsigned int index,
        unsigned long dwHelpContext );

Description

SetFuncHelpContext only needs to be set once for each property, because all property accessor functions are identified by one name.

Parameters

index

Index of the function.

dwHelpContext Help context ID for the Help topic.

Return Values

The return value of the returned HRESULT is one of the following:

S_OK

Success.

STG_E_INSUFFICIENTMEMORY

Out of memory.

E_OUTOFMEMORY

Out of memory.

E_ACCESSDENIED

Cannot write to the destination.

TYPE_E_ELEMENTNOTFOUND

The element cannot be found.

E_INVALIDARG

One or more of the arguments is invalid.

ICreateTypeInfo::SetGuid()

NAME

ICreateTypeInfo::SetGuid() - Sets the globally unique identifier (GUID) associated with the type description.

Synopsis

#include <Oaidl.h>

HRESULT SetGuid(
         REFGUID guid );

Description

For an interface, this is an interface ID (IID); for a coclass, it is a class ID (CLSID). For information on GUIDs, see Chapter 18.

Parameters

guid

Globally unique ID to be associated with the type description.

Return Values

The return value of the returned HRESULT is one of the following:

S_OK

Success.

STG_E_INSUFFICIENTMEMORY

Out of memory.

E_OUTOFMEMORY

Out of memory.

E_ACCESSDENIED

Cannot write to the destination.

ICreateTypeInfo::SetHelpContext()

NAME

ICreateTypeInfo::SetHelpContext() - Sets the Help context ID of the type information.

Synopsis

#include <Oaidl.h>

HRESULT SetHelpContext(
         unsigned long dwHelpContext );

Parameters

dwHelpContext

Handle to the Help context.

Return Values

The return value of the returned HRESULT is one of the following:

S_OK

Success.

STG_E_INSUFFICIENTMEMORY

Out of memory.

E_OUTOFMEMORY

Out of memory.

E_INVALIDARG

One or more of the arguments is invalid.

E_ACCESSDENIED

Cannot write to the destination.

ICreateTypeInfo::SetImplTypeFlags()

NAME

ICreateTypeInfo::SetImplTypeFlags() - Sets the attributes for an implemented or inherited interface of a type.

Synopsis

#include <Oaidl.h>

HRESULT SetImplTypeFlags(
        unsigned int index,
        int implTypeFlags );

Description

SetImplTypeFlags sets the IMPLTYPE flags for the indexed interface. See Chapter 18

Parameters

index

Index of the interface for which to set type flags.

implTypeFlags IMPLTYPE flags to be set.

Return Values

The return value of the returned HRESULT is one of the following:

S_OK

Success.

STG_E_INSUFFICIENTMEMORY

Out of memory.

E_OUTOFMEMORY

Out of memory.

E_INVALIDARG

One or more of the arguments is invalid.

E_ACCESSDENIED

Cannot write to the destination.

ICreateTypeInfo::SetMops()

NAME

ICreateTypeInfo::SetMops() - Sets the marshaling opcode string associated with the type description or the function.

Synopsis

#include <Oaidl.h>

HRESULT SetMops(
        unsigned int index,
        BSTR bstrMops );

Parameters

index

Index of the member for which to set the opcode string. If index is -1, sets the opcode string for the type description.

bstrMops The marshaling opcode string.

Return Values

The return value of the returned HRESULT is one of the following:

S_OK

Success.

STG_E_INSUFFICIENTMEMORY

Out of memory.

E_OUTOFMEMORY

Out of memory.

E_INVALIDARG

One or more of the arguments is invalid.

E_ACCESSDENIED

Cannot write to the destination.

ICreateTypeInfo::SetTypeDescAlias()

NAME

ICreateTypeInfo::SetTypeDescAlias() - Sets the type description for which this type description is an alias, if TYPEKIND=TKIND_ALIAS.

Synopsis

#include <Oaidl.h>

HRESULT SetTypeDescAlias(
         TYPEDESC FAR* pTDescAlias );

Description

To set the type for an alias, call SetTypeDescAlias for a type description whose TYPEKIND is TKIND_ALIAS.

Parameters

pTDescAlias

Pointer to a type description that describes the type for which this is an alias.

Return Values

The return value of the returned HRESULT is one of the following:

S_OK

Success.

STG_E_INSUFFICIENTMEMORY

Out of memory.

E_OUTOFMEMORY

Out of memory.

E_INVALIDARG

One or more of the arguments is invalid.

E_ACCESSDENIED

Cannot write to the destination.

TYPE_E_WRONGTYPEKIND

Type mismatch.

ICreateTypeInfo::SetTypeFlags()

NAME

ICreateTypeInfo::SetTypeFlags() - Sets type flags of the type description being created.

Synopsis

#include <Oaidl.h>

HRESULT SetTypeFlags(
         unsigned int uTypeFlags );

Description

Use SetTypeFlags to set the flags for the type description. For details, see Chapter 18.

Parameters

uTypeFlags

Settings for the type flags.

Return Values

The return value of the returned HRESULT is one of the following:

S_OK

Success.

STG_E_INSUFFICIENTMEMORY

Out of memory.

E_OUTOFMEMORY

Out of memory.

E_INVALIDARG

One or more of the arguments is invalid.

E_ACCESSDENIED

Cannot write to the destination.

TYPE_E_WRONGTYPEKIND

Type mismatch.

ICreateTypeInfo::SetVarDocString()

NAME

ICreateTypeInfo::SetVarDocString() - Sets the documentation string for the variable with the specified index.

Synopsis

#include <Oaidl.h>

HRESULT SetVarDocString(
        unsigned int index,
        OLECHAR FAR* szDocString );

Parameters

index

Index of the variable being documented.

szDocString The documentation string to be set.

Return Values

The return value of the returned HRESULT is one of the following:

S_OK

Success.

STG_E_INSUFFICIENTMEMORY

Out of memory.

E_OUTOFMEMORY

Out of memory.

E_ACCESSDENIED

Cannot write to the destination.

TYPE_E_ELEMENTNOTFOUND

The element was not found.

ICreateTypeInfo::SetVarHelpContext()

NAME

ICreateTypeInfo::SetVarHelpContext() - Sets the Help context ID for the variable with the specified index.

Synopsis

#include <Oaidl.h>

HRESULT SetVarHelpContext(
        unsigned int index,
        unsigned long dwHelpContext );

Parameters

index

Index of the variable described by the type description.

dwHelpContext Handle to the Help context ID for the Help topic on the variable.

Return Values

The return value of the returned HRESULT is one of the following:

S_OK

Success.

STG_E_INSUFFICIENTMEMORY

Out of memory.

E_OUTOFMEMORY

Out of memory.

E_ACCESSDENIED

Cannot write to the destination.

TYPE_E_ELEMENTNOTFOUND

The element cannot be found.

ICreateTypeInfo::SetVarName()

NAME

ICreateTypeInfo::SetVarName() - Sets the name of a variable.

Synopsis

#include <Oaidl.h>

HRESULT SetVarName(
        unsigned int index,
        OLECHAR FAR* szName );

Parameters

index

Index of the variable whose name is being set.

szName Name for the variable.

Return Values

The return value of the returned HRESULT is one of the following:

S_OK

Success.

STG_E_INSUFFICIENTMEMORY

Out of memory.

E_OUTOFMEMORY

Out of memory.

E_ACCESSDENIED

Cannot write to the destination.

TYPE_E_ELEMENTNOTFOUND

The element cannot be found.

ICreateTypeInfo::SetVersion()

NAME

ICreateTypeInfo::SetVersion() - Sets the major and minor version number of the type information.

Synopsis

#include <Oaidl.h>

HRESULT SetVersion(
        unsigned short wMajorVerNum,
        unsigned short wMinorVerNum );

Parameters

wMajorVerNum

Major version number for the type.

wMinorVerNum Minor version number for the type.

Return Values

The return value of the returned HRESULT is one of the following:

S_OK

Success.

E_ACCESSDENIED

Cannot write to the destination.

TYPE_E_INVALIDSTATE

The state of the type library is not valid for this operation.

19.4.3    ICreateTypeInfo2 Interface

The ICreateTypeInfo2 interface derives from ICreateTypeInfo(), and adds methods for deleting items that have been added through ICreateTypeInfo().

The ICreateTypeInfo::LayOut method provides a way for the creator of the type information to check for any errors. A call to QueryInterface() can be made to the ICreateTypeInfo() instance at any time for its ITypeInfo() interface. Calling any of the methods in the ITypeInfo() interface that require layout information lays out the type information automatically.

19.4.3.1    Examples

interface ICreateTypeInfo2 : ICreateTypeInfo

ICreateTypeInfo2::SetName()

NAME

ICreateTypeInfo2::SetName() - Sets the name of the typeinfo.

Synopsis

#include <Oaidl.h>

HRESULT SetName(
         OLECHAR FAR* szName );

Parameters

szName

Name to be assigned to the typeinfo.

Return Values

The return value of the returned HRESULT is one of the following:

S_OK

Success.

STG_E_INSUFFICIENTMEMORY

Out of memory.

E_OUTOFMEMORY

Out of memory.

E_INVALIDARG

One or more of the arguments is invalid.

TYPE_E_INVALIDSTATE

The state of the type info is not valid for this operation.

ICreateTypeInfo2::DeleteFuncDesc()

NAME

ICreateTypeInfo2::DeleteFuncDesc() - Deletes a function description specified by the index number.

Synopsis

#include <Oaidl.h>

HRESULT DeleteFuncDesc(
         unsigned int index );

Parameters

index

Index of the function whose description is to be deleted. The index should be in the range of 0 to 1 less than the number of functions in this type.

Return Values

The return value obtained from the returned HRESULT is one of the following:

S_OK

Success.

E_OUTOFMEMORY

Out of memory.

E_INVALIDARG

One or more of the arguments is invalid.

ICreateTypeInfo2::DeleteFuncDescByMemId()

NAME

ICreateTypeInfo2::DeleteFuncDescByMemId() - Deletes the function description (FUNCDESC) specified by memid.

Synopsis

#include <Oaidl.h>

HRESULT DeleteFuncDescByMemId(
        MEMBERID memid,
        INVOKEKIND invKind );

Parameters

memid

Member identifier of the FUNCDESC to delete.

invKind The type of the invocation.

Return Values

The return value obtained from the returned HRESULT is one of the following:

S_OK

Success.

E_OUTOFMEMORY

Out of memory.

E_INVALIDARG

One or more of the arguments is invalid.

ICreateTypeInfo2::DeleteVarDesc()

NAME

ICreateTypeInfo2::DeleteVarDesc() - Deletes the specified VARDESC structure.

Synopsis

#include <Oaidl.h>

HRESULT DeleteVarDesc(
         unsigned int index );

Parameters

index

Index number of the VARDESC structure.

Return Values

The return value obtained from the returned HRESULT is one of the following:

S_OK

Success.

E_OUTOFMEMORY

Out of memory.

E_INVALIDARG

One or more of the arguments is invalid.

TYPE_E_IOERROR

The function cannot read from the file.

TYPE_E_INVDATAREAD

The function cannot read from the file.

TYPE_E_UNSUPFORMAT

The type library has an old format.

TYPE_E_INVALIDSTATE

The type library cannot be opened.

Example ptypeinfo->DeleteVarDesc(index);

ICreateTypeInfo2::DeleteVarDescByMemId()

NAME

ICreateTypeInfo2::DeleteVarDescByMemId() - Deletes the specified VARDESC structure.

Synopsis

#include <Oaidl.h>

HRESULT DeleteVarDescByMemId(
         MEMBERID memid );

Parameters

memid

Member identifier of the VARDESC to be deleted.

Return Values

The return value obtained from the returned HRESULT is one of the following:

S_OK

Success.

E_OUTOFMEMORY

Out of memory.

E_INVALIDARG

One or more of the arguments is invalid.

TYPE_E_IOERROR

The function cannot read from the file.

TYPE_E_INVDATAREAD

The function cannot read from the file.

TYPE_E_UNSUPFORMAT

The type library has an older format.

TYPE_E_INVALIDSTATE

The type library cannot be opened.

ICreateTypeInfo2::DeleteImplType()

NAME

ICreateTypeInfo2::DeleteImplType() - Deletes the IMPLTYPE flags for the indexed interface.

Synopsis

#include <Oaidl.h>

HRESULT DeleteImplType(
         unsigned int index );

Parameters

index

Index of the interface for which to delete the type flags.

Return Values

The return value obtained from the returned HRESULT is one of the following:

S_OK

Success.

E_OUTOFMEMORY

Out of memory.

E_INVALIDARG

One or more of the arguments is invalid.

ICreateTypeInfo2::SetCustData()

NAME

ICreateTypeInfo2::SetCustData() - Sets a value for custom data.

Synopsis

#include <Oaidl.h>

HRESULT SetCustData(
        REFGUID guid,
        VARIANT * pVarVal );

Parameters

guid

Unique identifier that can be used to identify the data.

pVarVal The data to store (any variant except an object).

Return Values

The return value obtained from the returned HRESULT is one of the following:

S_OK

Success.

E_OUTOFMEMORY

Out of memory.

E_INVALIDARG

One or more of the arguments is invalid.

ICreateTypeInfo2::SetHelpStringContext()

NAME

ICreateTypeInfo2::SetHelpStringContext() - Sets the context number for the specified Help string.

Synopsis

#include <Oaidl.h>

HRESULT SetHelpStringContext(
         DWORD * dwHelpStringContext );

Parameters

dwHelpStringContext

Pointer to the Help string context number.

Return Values

The return value obtained from the returned HRESULT is one of the following:

S_OK

Success.

E_OUTOFMEMORY

Out of memory.

E_INVALIDARG

Argument is invalid.

ICreateTypeInfo2::SetFuncCustData()

NAME

ICreateTypeInfo2::SetFuncCustData() - Sets a value for a specified custom function.

Synopsis

#include <Oaidl.h>

HRESULT SetFuncCustData(
        unsigned int index,
        REFGUID guid,
        VARIANT * pVarVal );

Parameters

index

The index of the function for which to set the custom data.

guid Unique identifier used to identify the data.

pVarVal The data to store (any variant except an object).

Return Values

The return value obtained from the returned HRESULT is one of the following:

S_OK

Success.

E_OUTOFMEMORY

Out of memory.

E_INVALIDARG

One or more of the arguments is invalid.

ICreateTypeInfo2::SetFuncHelpStringContext()

NAME

ICreateTypeInfo2::SetFuncHelpStringContext() - Sets a Help context value for a specified custom function.

Synopsis

#include <Oaidl.h>

HRESULT SetFuncHelpStringContext(
        unsigned int index,
        DWORD dwHelpStringContext,
         );

Parameters

index

The index of the function for which to set the custom data.

dwHelpStringContext Help string context for a localized string

Return Values

The return value obtained from the returned HRESULT is one of the following:

S_OK

Success.

E_OUTOFMEMORY

Out of memory.

E_INVALIDARG

One or more of the arguments is invalid.

ICreateTypeInfo2::SetVarCustData()

NAME

ICreateTypeInfo2::SetVarCustData() - Sets a custom data variable.

Synopsis

#include <Oaidl.h>

HRESULT SetVarCustData(
        unsigned int index,
        REFGUID guid,
        VARIANT * pVarVal );

Parameters

index

Index of the variable for which to set the custom data.

guid Globally unique ID (GUID) used to identify the data.

pVarVal Data to store (any legal variant except an object).

Return Values

The return value obtained from the returned HRESULT is one of the following:

S_OK

Success.

E_OUTOFMEMORY

Out of memory.

E_INVALIDARG

One or more of the arguments is invalid.

ICreateTypeInfo2::SetParamCustData()

NAME

ICreateTypeInfo2::SetParamCustData() - Sets the specified parameter for the custom data.

Synopsis

#include <Oaidl.h>

HRESULT SetParamCustData(
        unsigned int indexFunc,
        unsigned int indexParam,
        REFGUID guid,
        VARIANT * pVarVal );

Parameters

indexFunc

Index of the function for which to set the custom data.

indexParam Index of the parameter of the function for which to set the custom data.

guid Globally unique identifier (GUID) used to identify the data.

pvarVal The data to store (any legal variant except an object).

Return Values

The return value obtained from the returned HRESULT is one of the following:

S_OK

Success.

E_OUTOFMEMORY

Out of memory.

E_INVALIDARG

One or more of the arguments is invalid.

ICreateTypeInfo2::SetImplTypeCustData()

NAME

ICreateTypeInfo2::SetImplTypeCustData() - Sets the implementation type for custom data.

Synopsis

#include <Oaidl.h>

HRESULT SetImplTypeCustData(
        unsigned int index,
        REFGUID guid,
        VARIANT * pVarVal,
         );

Parameters

index

Index of the variable for which to set the custom data.

guid Unique identifier used to identify the data.

pVarVal Reference to the value of the variable.

Return Values

The return value obtained from the returned HRESULT is one of the following:

S_OK

Success.

E_OUTOFMEMORY

Out of memory.

E_INVALIDARG

One or more of the arguments is invalid.

ICreateTypeInfo2::SetVarHelpStringContext()

NAME

ICreateTypeInfo2::SetVarHelpStringContext() - Sets a Help context value for a specified variable.

Synopsis

#include <Oaidl.h>

HRESULT SetVarHelpStringContext(
        unsigned int index,
        DWORD dwHelpStringContext,
         );

Parameters

index

The index of the variable.

dwHelpStringContext Help string context for a localized string

Return Values

The return value obtained from the returned HRESULT is one of the following:

S_OK

Success.

E_OUTOFMEMORY

Out of memory.

E_INVALIDARG

One or more of the arguments is invalid.

19.4.4    ICreateTypeLib Interface

The ICreateTypeLib interface provides the methods for creating and managing the component or file that contains type information. Type libraries are created from type descriptions using the MkTypLib utility or the MIDL compiler. These type libraries are accessed through the ITypeLib() interface.  

ICreateTypeLib::CreateTypeInfo()

NAME

ICreateTypeLib::CreateTypeInfo() - Creates a new type description instance within the type library.

Synopsis

#include <Oaidl.h>

HRESULT CreateTypeInfo(
        OLECHAR FAR* szName,
        TYPEKIND tkind,
        ICreateTypeInfo FAR* FAR* ppCTInfo );

Description

Use the function CreateTypeInfo to create a new type description instance within the library. An error is returned if the specified name already appears in the library. Valid tkind values are described in the Chapter 18. To get the type information of the type description that is being created, call IUnknown::QueryInterface(IID_ITypeInfo, ...) on the returned ICreateTypeInfo(). This type information can be used by other type descriptions that reference it by using ICreateTypeInfo::AddRefTypeInfo.

Parameters

szName

Name of the new type.

tkind TYPEKIND of the type description to be created.

ppCTInfo On return, contains a pointer to the type description.

Return Values

The return value of the returned HRESULT is one of the following:

S_OK

Success.

STG_E_INSUFFICIENTMEMORY

Out of memory.

E_OUTOFMEMORY

Out of memory.

E_INVALIDARG

One or more of the arguments is invalid.

TYPE_E_INVALIDSTATE

The state of the type library is not valid for this operation.

TYPE_E_NAMECONFLICT

The provided name is not unique.

TYPE_E_WRONGTYPEKIND

Type mismatch.

ICreateTypeLib::SaveAllChanges()

NAME

ICreateTypeLib::SaveAllChanges() - Saves the ICreateTypeLib instance following the layout of type information.

Synopsis

HRESULT SaveAllChanges(
         );

Description

You should not call any other ICreateTypeLib methods after calling SaveAllChanges.

Parameters

None.

Return Values

The return value of the returned HRESULT is one of the following:

S_OK

Success.

STG_E_INSUFFICIENTMEMORY

Out of memory.

E_OUTOFMEMORY

Out of memory.

E_INVALIDARG

One or more of the arguments is invalid.

TYPE_E_IOERROR

The function cannot write to the file.

TYPE_E_INVALIDSTATE

The state of the type library is not valid for this operation.

Other return codes

All FACILITY_STORAGE errors.

ICreateTypeLib::SetDocString()

NAME

ICreateTypeLib::SetDocString() - Sets the documentation string associated with the library.

Synopsis

#include <Oaidl.h>

HRESULT SetDocString(
         OLECHAR FAR* szDoc );

Description

The documentation string is a brief description of the library intended for use by type information browsing tools.

Parameters

szDoc

A documentation string that briefly describes the type library.

Return Values

The return value of the returned HRESULT is one of the following:

S_OK

Success.

STG_E_INSUFFICIENTMEMORY

Out of memory.

E_OUTOFMEMORY

Out of memory.

E_INVALIDARG

One or more of the arguments is invalid.

ICreateTypeLib::SetGuid()

NAME

ICreateTypeLib::SetGuid() - Sets the universal unique identifier (UUID) associated with the type library (Also known as the globally unique identifier (GUID)).

Synopsis

#include <Oaidl.h>

HRESULT SetGuid(
         REFGUID guid );

Description

Universal unique identifiers (UUIDs) are described in Chapter 18.

Parameters

guid

The globally unique identifier to be assigned to the library.

Return Values

The return value of the returned HRESULT is one of the following:

S_OK

Success.

STG_E_INSUFFICIENTMEMORY

Out of memory.

E_OUTOFMEMORY

Out of memory.

E_INVALIDARG

One or more of the arguments is invalid.

TYPE_E_INVALIDSTATE

The state of the type library is not valid for this operation.

ICreateTypeLib::SetHelpContext()

NAME

ICreateTypeLib::SetHelpContext() - Sets the Help context ID for retrieving general Help information for the type library.

Synopsis

#include <Oaidl.h>

HRESULT SetHelpContext(
         unsigned long dwHelpContext );

Description

Calling SetHelpContext with a Help context of zero is equivalent to not calling it at all, because zero indicates a NULL Help context.

Parameters

dwHelpContext

Help context ID to be assigned to the library.

Return Values

The return value of the returned HRESULT is one of the following:

S_OK

Success.

STG_E_INSUFFICIENTMEMORY

Out of memory.

E_OUTOFMEMORY

Out of memory.

E_INVALIDARG

One or more of the arguments is invalid.

TYPE_E_INVALIDSTATE

The state of the type library is not valid for this operation.

ICreateTypeLib::SetHelpFileName()

NAME

ICreateTypeLib::SetHelpFileName() - Sets the name of the Help file.

Synopsis

#include <Oaidl.h>

HRESULT SetHelpFileName(
         OLECHAR FAR* szHelpFileName );

Description

Each type library can reference a single Help file.

The GetDocumentation method of the created ITypeLib() returns a fully qualified path for the Help file, which is formed by appending the name passed into szHelpFileName to the registered Help directory for the type library. The Help directory is registered under: \TYPELIB\guid of library\Major.Minorversion\HELPDIR

Parameters

szHelpFileName

The name of the Help file for the library.

Return Values

The return value of the returned HRESULT is one of the following:

S_OK

Success.

STG_E_INSUFFICIENTMEMORY

Out of memory.

E_OUTOFMEMORY

Out of memory.

E_INVALIDARG

One or more of the arguments is invalid.

TYPE_E_INVALIDSTATE

The state of the type library is not valid for this operation.

ICreateTypeLib::SetLibFlags()

NAME

ICreateTypeLib::SetLibFlags() - Sets library flags, such as LIBFLAG_FRESTRICTED.

Synopsis

#include <Oaidl.h>

HRESULT SetLibFlags(
         unsigned int uLibFlags );

Parameters

uLibFlags

The flags to set for the library.

Return Values

The return value of the returned HRESULT is one of the following:

S_OK

Success.

STG_E_INSUFFICIENTMEMORY

Out of memory.

E_OUTOFMEMORY

Out of memory.

E_INVALIDARG

One or more of the arguments is invalid.

TYPE_E_INVALIDSTATE

The state of the type library is not valid for this operation.

ICreateTypeLib::SetLcid()

NAME

ICreateTypeLib::SetLcid() - Sets the binary Microsoft national language ID associated with the library.

Synopsis

#include <Oaidl.h>

HRESULT SetLcid(
         LCID lcid );

Description

For more information on national language IDs, see Section Section 19.3.

Parameters

lcid

Represents the locale ID for the type library.

Return Values

The return value of the returned HRESULT is one of the following:

S_OK

Success.

STG_E_INSUFFICIENTMEMORY

Out of memory.

E_OUTOFMEMORY

Out of memory.

E_INVALIDARG

One or more of the arguments is invalid.

TYPE_E_INVALIDSTATE

The state of the type library is not valid for this operation.

ICreateTypeLib::SetName()

NAME

ICreateTypeLib::SetName() - Sets the name of the type library.

Synopsis

#include <Oaidl.h>

HRESULT SetName(
         OLECHAR FAR* szName );

Parameters

szName

Name to be assigned to the library.

Return Values

The return value of the returned HRESULT is one of the following:

S_OK

Success.

STG_E_INSUFFICIENTMEMORY

Out of memory.

E_OUTOFMEMORY

Out of memory.

E_INVALIDARG

One or more of the arguments is invalid.

TYPE_E_INVALIDSTATE

The state of the type library is not valid for this operation.

ICreateTypeLib::SetVersion()

NAME

ICreateTypeLib::SetVersion() - Sets the major and minor version numbers of the type library.

Synopsis

#include <Oaidl.h>

HRESULT SetVersion(
        unsigned short wMajorVerNum,
        unsigned short wMinorVerNum );

Parameters

wMajorVerNum

Major version number for the library.

wMinorVerNum Minor version number for the library.

Return Values

The return value of the returned HRESULT is one of the following:

S_OK

Success.

TYPE_E_INVALIDSTATE

The state of the type library is not valid for this operation.

19.4.5    ICreateTypeLib2 Interface

ICreateTypeLib2() inherits from ICreateTypeLib, and has four member functions. The ICreateTypeInfo() instance returned from ICreateTypeLib can be accessed through a QueryInterface() call to ICreateTypeInfo2.

19.4.5.1    Examples

interface ICreateTypeLib2 : ICreateTypeLib

ICreateTypeLib2::SetName()

NAME

ICreateTypeLib2::SetName() - Sets the name of the type library.

Synopsis

#include <Oaidl.h>

HRESULT SetName(
         OLECHAR FAR* szName );

Parameters

szName

Name to be assigned to the library.

Return Values

The return value of the returned HRESULT is one of the following:

S_OK

Success.

STG_E_INSUFFICIENTMEMORY

Out of memory.

E_OUTOFMEMORY

Out of memory.

E_INVALIDARG

One or more of the arguments is invalid.

TYPE_E_INVALIDSTATE

The state of the type library is not valid for this operation.

ICreateTypeLib2::DeleteTypeInfo()

NAME

ICreateTypeLib2::DeleteTypeInfo() - Deletes a specified type information from the type library.

Synopsis

#include <Oaidl.h>

HRESULT DeleteTypeInfo(
         OLECHAR FAR* szName );

Parameters

szName

Name of the type information to remove.

Return Values

The return value obtained from the returned HRESULT is one of the following:

S_OK

Success.

E_OUTOFMEMORY

Out of memory.

E_INVALIDARG

One or more of the arguments is invalid.

ICreateTypeLib2::SetCustData()

NAME

ICreateTypeLib2::SetCustData() - Sets a value to custom data.

Synopsis

#include <Oaidl.h>

HRESULT SetCustData(
        REFGUID guid,
        VARIANT * pVarVal );

Parameters

guid

Unique identifier used to identify the data.

pVarVal The data to store (any variant except an object).

Return Values

The return value obtained from the returned HRESULT is one of the following:

S_OK

Success.

E_OUTOFMEMORY

Out of memory.

E_INVALIDARG

One or more of the arguments is invalid.

ICreateTypeLib2::SetHelpStringContext()

NAME

ICreateTypeLib2::SetHelpStringContext() - Sets the Help string context number.

Synopsis

#include <Oaidl.h>

HRESULT SetHelpStringContext(
         DWORD * dwHelpStringContext );

Parameters

DwHelpStringContext

The Help string context number.

Return Values

The return value obtained from the returned HRESULT is one of the following:

S_OK

Success.

E_OUTOFMEMORY

Out of memory.

E_INVALIDARG

One or more of the arguments is invalid.

ICreateTypeLib2::SetHelpStringDll()

NAME

ICreateTypeLib2::SetHelpStringDll() - Sets the DLL name to be used for Help string lookup (for localization purposes).

Synopsis

#include <Oaidl.h>

HRESULT SetHelpStringDll(
         LPOLESTR szFileName );

Parameters

szFileName

The DLL file name.

Return Values

The return value obtained from the returned HRESULT is one of the following:

S_OK

Success.

E_OUTOFMEMORY

Out of memory.

E_INVALIDARG

One or more of the arguments is invalid.

19.5    Automation API Descriptions

BstrFromVector()

NAME

BstrFromVector() - Returns a BSTR, assigning each element of the vector to a character in the BSTR.

Synopsis

#include <oleauto.h>

HRESULT BstrFromVector((
        SAFEARRAY FAR* psa,
        BSTR FAR* pbstr );

Parameters

psa

The vector to be converted to a BSTR.

pbstr

On exit, pbstr points to a BSTR, each character of which is assigned to an element from the vector.

Return Values

The return value obtained from the returned HRESULT is one of the following.

S_OK

Success.

E_OUTOFMEMORY

Out of memory.

E_INVALIDARG

The argument psa is NULL.

DISP_E_TYPEMISMATCH

The argument psa is not a vector (not an array of bytes).

Returns a BSTR, assigning each element of the vector to a character in the BSTR.  

CreateDispTypeInfo()

NAME

CreateDispTypeInfo() - Creates simplified type information for use in an implementation of IDispatch().

Synopsis

#include <oleauto.h>

HRESULT CreateDispTypeInfo((
        INTERFACEDATA pidata,
        LCID lcid,
        ITypeInfo FAR * FAR * pptinfo );

Description

Creates simplified type information for use in an implementation of IDispatch().

You can construct type information at run time by using CreateDispTypeInfo() and an INTERFACEDATA structure that describes the object being exposed.

The type information returned by this function is primarily designed to automate the implementation of IDispatch(). CreateDispTypeInfo() does not return all of the type information described in Chapter 18. The argument pidata is not a complete description of an interface. It does not include Help information, comments, optional parameters, and other type information that is useful in different contexts.

Accordingly, the recommended method for providing type information about an object is to describe the object using the Object Description Language (ODL), and to compile the object description into a type library using the Microsoft Interface Definition Language (MIDL) compiler or the MkTypLib utility.

To use type information from a type library, use the LoadTypeLib and GetTypeInfoOfGuid functions instead of CreateDispTypeInfo(). For more information, see Chapter 18.

Parameters

pidata

The interface description that this type information describes.

lcid

The locale identifier for the names used in the type information.

pptinfo

On return, pointer to a type information implementation for use in DispGetIDsOfNames() and DispInvoke().

Return Values

The return value obtained from the returned HRESULT is one of the following:

S_OK

The interface is supported.

E_INVALIDARG

Either the interface description or the LCID is invalid.

E_OUTOFMEMORY

Insufficient memory to complete the operation.

Examples

The code that follows creates type information from INTERFACEDATA to expose the CCalc object.

static METHODDATA NEARDATA rgmdataCCalc[] =
{
        PROPERTY(VALUE,  IMETH_ACCUM,    IDMEMBER_ACCUM,    VT_I4)
        PROPERTY(ACCUM,  IMETH_ACCUM,    IDMEMBER_ACCUM,    VT_I4)
        PROPERTY(OPND,   IMETH_OPERAND,  IDMEMBER_OPERAND,  VT_I4)
        PROPERTY(OP,     IMETH_OPERATOR, IDMEMBER_OPERATOR, VT_I2)
        METHOD0(EVAL,    IMETH_EVAL,     IDMEMBER_EVAL,     VT_BOOL)
        METHOD0(CLEAR,   IMETH_CLEAR,    IDMEMBER_CLEAR,    VT_EMPTY)
        METHOD0(DISPLAY, IMETH_DISPLAY,  IDMEMBER_DISPLAY,  VT_EMPTY)
        METHOD0(QUIT,    IMETH_QUIT,     IDMEMBER_QUIT,     VT_EMPTY)
        METHOD1(BUTTON,  IMETH_BUTTON,   IDMEMBER_BUTTON,   VT_BOOL)
};
INTERFACEDATA NEARDATA g_idataCCalc =
{
    rgmdataCCalc, DIM(rgmdataCCalc)
};
// Use Dispatch interface API functions to implement IDispatch.
CCalc FAR*
CCalc::Create()
{
    HRESULT hresult;
    CCalc FAR* pcalc;
    CArith FAR* parith;
    ITypeInfo FAR* ptinfo;
    IUnknown FAR* punkStdDisp;
extern INTERFACEDATA NEARDATA g_idataCCalc;
    if((pcalc = new FAR CCalc()) == NULL)
        return NULL;
    pcalc->AddRef();
    parith = &(pcalc->m_arith);
    // Build type information for the functionality on this object that
    // is being exposed for external programmability.
    hresult = CreateDispTypeInfo(
        &g_idataCCalc, LOCALE_SYSTEM_DEFAULT, &ptinfo);
    if(hresult != NOERROR)
        goto LError0;
    // Create an aggregate with an instance of the default
    // implementation of IDispatch that is initialized with 
    // type information.
    hresult = CreateStdDispatch(
        pcalc,                // Controlling unknown.
        parith,                // Instance to dispatch on.
        ptinfo,                // Type information describing the instance.
        &punkStdDisp);
    ptinfo->Release();
    if(hresult != NOERROR)
        goto LError0;
    pcalc->m_punkStdDisp = punkStdDisp;
    return pcalc;
LError0:;
    pcalc->Release();
    return NULL;
}

CreateStdDispatch()

NAME

CreateStdDispatch() - Creates a standard implementation of the IDispatch() interface through a single function call. This simplifies exposing objects through Automation.

Synopsis

#include <oleauto.h>

HRESULT CreateStdDispatch((
        IUnknown FAR * punkOuter,
        void FAR * pvThis,
        ITypeInfo FAR * ptinfo,
        IUnknown FAR * FAR * ppunkStdDisp );

Description

Creates a standard implementation of the IDispatch() interface through a single function call. This simplifies exposing objects through Automation.

You can use CreateStdDispatch() when creating an object instead of implementing the IDispatch() member functions for the object. However, the implementation that CreateStdDispatch() creates has these limitations:

• Supports only one national language.

• Supports only dispatch-defined exception codes returned from Invoke.

LoadTypeLib, GetTypeInfoOfGuid, and CreateStdDispatch() comprise the minimum set of functions that you need to call to expose an object using a type library. For more information on LoadTypeLib and GetTypeInfoOfGuid, see Chapter 18.

CreateDispTypeInfo() and CreateStdDispatch() comprise the minimum set of dispatch components you need to call to expose an object using type information provided by the INTERFACEDATA structure.

Parameters

punkOuter

Pointer to the object's IUnknown() implementation.

pvThis

Pointer to the object to expose.

ptinfo

Pointer to the type information that describes the exposed object.

ppunkStdDisp

This is the private unknown for the object that implements the IDispatch() interface QueryInterface() call. This pointer is NULL if the function fails.

Return Values

The return value obtained from the returned HRESULT is one of the following:

S_OK

Success.

E_INVALIDARG

One of the first three arguments is invalid.

E_OUTOFMEMORY

There was insufficient memory to complete the operation.

Examples

The following code implements the IDispatch interface for the CCalc class using CreateStdDispatch().

CCalc FAR*
CCalc::Create()
{
    HRESULT hresult;
    CCalc FAR* pcalc;
    CArith FAR* parith;
    ITypeInfo FAR* ptinfo;
    IUnknown FAR* punkStdDisp;
extern INTERFACEDATA NEARDATA g_idataCCalc;
    if((pcalc = new FAR CCalc()) == NULL)
        return NULL;
    pcalc->AddRef();
    parith = &(pcalc->m_arith);
    // Build type information for the functionality on this object that
    // is being exposed for external programmability.
    hresult = CreateDispTypeInfo(
        &g_idataCCalc, LOCALE_SYSTEM_DEFAULT, &ptinfo);
    if(hresult != NOERROR)
        goto LError0;
    // Create an aggregate with an instance of the default
    // implementation of IDispatch that is initialized with
    // type information.
    hresult = CreateStdDispatch(
        pcalc,                // Controlling unknown.
        parith,                // Instance to dispatch on.
        ptinfo,                // Type information describing the instance.
    &punkStdDisp);
    ptinfo->Release();
    if(hresult != NOERROR)
        goto LError0;
    pcalc->m_punkStdDisp = punkStdDisp;
    return pcalc;
LError0:;
    pcalc->Release();
    return NULL;
}

DispGetIDsOfNames()

NAME

DispGetIDsOfNames() - Uses type information to convert a set of names to DISPIDs. This is the recommended implementation of IDispatch::GetIDsOfNames().

Synopsis

#include <oleauto.h>

HRESULT DispGetIDsOfNames((
        ITypeInfo * ptinfo,
        OLECHAR FAR * FAR * rgszNames,
        unsigned int cNames,
        DISPID FAR * rgdispid );

Parameters

ptinfo

Pointer to the type information for an interface. This type information is specific to one interface and language code, so it is not necessary to pass an interface identifier (IID) or LCID to this function.

rgszNames

An array of name strings that can be the same array passed to DispInvoke() in the DISPPARAMS structure. If cNames is greater than 1, the first name is interpreted as a method name, and subsequent names are interpreted as parameters to that method.

cNames

The number of elements in rgszNames.

rgdispid

Pointer to an array of DISPIDs to be filled in by this function. The first ID corresponds to the method name. Subsequent IDs are interpreted as parameters to the method.

Return Values

The return value obtained from the returned HRESULT is one of the following:

S_OK

The interface is supported.

E_INVALIDARG

One of the arguments is invalid.

DISP_E_UNKNOWNNAME

One or more of the given names were not known. The returned array of DISPIDs contains DISPID_UNKNOWN for each entry that corresponds to an unknown name.

Other return codes

Any of the ITypeInfo::Invoke() errors can also be returned.

Uses type information to convert a set of names to DISPIDs. This is the recommended implementation of IDispatch::GetIDsOfNames().

Examples

This code from the Lines sample file Points.cpp implements the member function GetIDsOfNames for the CPoints class using DispGetIDsOfNames().

STDMETHODIMP
CPoints::GetIDsOfNames(
        REFIID riid,
        char FAR* FAR* rgszNames,
        UINT cNames,
        LCID lcid,
        DISPID FAR* rgdispid)
{
    return DispGetIDsOfNames(m_ptinfo, rgszNames, cNames, rgdispid);
}

See Also

CreateStdDispatch(), IDispatch::GetIDsOfNames  

DispGetParam()

NAME

DispGetParam() - Retrieves a parameter from the DISPPARAMS structure.

Synopsis

#include <oleauto.h>

HRESULT DispGetParam((
        DISPPARAMS FAR * pdispparams,
        unsigned int position,
        VARTYPE vtTarg,
        VARIANT FAR * pvarResult,
        unsigned int FAR * puArgErr );

Description

Retrieves a parameter from the DISPPARAMS structure, checking both named parameters and positional parameters, and coerces the parameter to the specified type.

The output parameter pvarResult must be a valid variant. Any existing contents are released in the standard way. The contents of the variant are freed with VariantFree.

If you have used DispGetParam() to get the right side of a property put operation, the second parameter should be DISPID_PROPERTYPUT. For example:

DispGetParam(&dispparams, DISPID_PROPERTYPUT, VT_BOOL, &varResult)

Named parameters cannot be accessed positionally, and vice versa.

Parameters

pdispparams

Pointer to the parameters passed to IDispatch::Invoke().

position

The position of the parameter in the parameter list. DispGetParam() starts at the end of the array, so if position is 0, the last parameter in the array is returned.

vtTarg

The type the argument should be coerced to.

pvarResult

Pointer to the variant to pass the parameter into.

puArgErr

On return, pointer to the index of the argument that caused a DISP_E_TYPEMISMATCH error. This pointer is returned to Invoke to indicate the position of the argument in DISPPARAMS that caused the error.

Return Values

The return value obtained from the HRESULT is one of the following:

S_OK

Success.

DISP_E_BADVARTYPE

The variant type vtTarg is not supported.

DISP_E_OVERFLOW

The retrieved parameter could not be coerced to the specified type.

DISP_E_PARAMNOTFOUND

The parameter indicated by position could not be found.

DISP_E_TYPEMISMATCH

The argument could not be coerced to the specified type.

E_INVALIDARG

One of the arguments was invalid.

E_OUTOFMEMORY

Insufficient memory to complete operation.

Examples

The following example uses DispGetParam() to set X and Y properties:

STDMETHODIMP
CPoint::Invoke(
    DISPID dispidMember,
    REFIID riid,
    LCID lcid,
    unsigned short wFlags,
    DISPPARAMS FAR* pdispparams,
    VARIANT FAR* pvarResult,
    EXCEPINFO FAR* pExcepInfo,
    unsigned int FAR* puArgErr)
{
    unsigned int uArgErr;
    HRESULT hresult;
    VARIANTARG varg0;
    VARIANT varResultDummy;
    UNUSED(lcid);
    UNUSED(pExcepInfo);
    // Make sure the wFlags are valid.
    if(wFlags & ~(DISPATCH_METHOD | DISPATCH_PROPERTYGET |
        DISPATCH_PROPERTYPUT | DISPATCH_PROPERTYPUTREF))
        return ResultFromScode(E_INVALIDARG);
    // This object only exposes a ``default'' interface.
    if(!IsEqualIID(riid, IID_NULL))
        return ResultFromScode(DISP_E_UNKNOWNINTERFACE);
    // It simplifies the following code if the caller
    // ignores the return value.
    if(puArgErr == NULL)
        puArgErr = &uArgErr;
    if(pvarResult == NULL)
        pvarResult = &varResultDummy;
    VariantInit(&varg0);
    // Assume the return type is void, unless otherwise is found.
    VariantInit(pvarResult);
    switch(dispidMember){
    case IDMEMBER_CPOINT_GETX:
        V_VT(pvarResult) = VT_I2;
        V_I2(pvarResult) = GetX();
        break;
    case IDMEMBER_CPOINT_SETX:
        hresult = DispGetParam(pdispparams, 0, VT_I2, &varg0, puArgErr);
        if(hresult != NOERROR)
            return hresult;
        SetX(V_I2(&varg0));
        break;
    case IDMEMBER_CPOINT_GETY:
        V_VT(pvarResult) = VT_I2;
        V_I2(pvarResult) = GetY();
        break;
    case IDMEMBER_CPOINT_SETY:
        hresult = DispGetParam(pdispparams, 0, VT_I2, &varg0, puArgErr);
        if(hresult != NOERROR)
            return hresult;
        SetY(V_I2(&varg0));
        break;
    default:
        return ResultFromScode(DISP_E_MEMBERNOTFOUND);
    }
    return NOERROR;
}

See Also

CreateStdDispatch(), IDispatch::Invoke()  

DispInvoke()

NAME

DispInvoke() - Automatically calls member functions on an interface.

Synopsis

#include <oleauto.h>

HRESULT DispInvoke((
        void FAR *_this,
        ITypeInfo FAR * ptinfo,
        DISPID dispidMember,
        unsigned short wFlags,
        DISPPARAMS FAR * pparams,
        VARIANT FAR * pvarResult,
        EXCEPINFO pexcepinfo,
        unsigned int FAR * puArgErr );

Description

Automatically calls member functions on an interface, given the type information for the interface. You can describe an interface with type information and implement IDispatch::Invoke() for the interface using this single call.

The parameter _this is a pointer to an implementation of the interface that is being deferred to. DispInvoke() builds a stack frame, coerces parameters using standard coercion rules, pushes them on the stack, and then calls the correct member function in the VTBL.

Parameters

_this

Pointer to an implementation of the IDispatch() interface described by

ptinfo.

ptinfo

Pointer to the type information that describes the interface.

dispidMember

Identifies the member. Use GetIDsOfNames or the object's documentation to obtain the DISPID.

wFlags

Flags describing the context of the Invoke call, as follows:

1.  Invoke Context Flags

pparams

Pointer to a structure containing an array of arguments, an array of argument DISPIDs for named arguments, and counts for number of elements in the arrays.

pvarResult

Pointer to where the result is to be stored, or NULL if the caller expects no result. This argument is ignored if DISPATCH_PROPERTYPUT or DISPATCH_PROPERTYPUTREF is specified.

pexcepinfo

Pointer to a structure containing exception information. This structure should be filled in if DISP_E_EXCEPTION is returned.

puArgErr

The index within rgvarg of the first argument that has an error. Arguments are stored in pdispparams->rgvarg in reverse order, so the first argument is the one with the highest index in the array. This parameter is returned only when the resulting return value is DISP_E_TYPEMISMATCH or DISP_E_PARAMNOTFOUND.

Return Values

The return value obtained from the returned HRESULT is one of the following:

S_OK

Success.

DISP_E_BADPARAMCOUNT

The number of elements provided in DISPPARAMS is different from the number of arguments accepted by the method or property.

DISP_E_BADVARTYPE

One of the arguments in DISPPARAMS is not a valid variant type.

DISP_E_EXCEPTION

The application needs to raise an exception. In this case, the structure passed in pexcepinfo should be filled in.

DISP_E_MEMBERNOTFOUND

The requested member does not exist.

DISP_E_NONAMEDARGS

This implementation of IDispatch() does not support named arguments.

DISP_E_OVERFLOW

One of the arguments in DISPPARAMS could not be coerced to the specified type.

DISP_E_PARAMNOTFOUND

One of the parameter IDs does not correspond to a parameter on the method. In this case, puArgErr is set to the first argument that contains the error.

DISP_E_PARAMNOTOPTIONAL

A required parameter was omitted.

DISP_E_TYPEMISMATCH

One or more of the arguments could not be coerced. The index of the first parameter with the incorrect type within rgvarg is returned in puArgErr.

E_INVALIDARG

One of the arguments is invalid.

E_OUTOFMEMORY

Insufficient memory to complete the operation.

Other return codes

Any of the ITypeInfo::Invoke() errors can also be returned.

Examples

The following code from the Lines sample file Lines.cpp implements IDispatch::Invoke() using DispInvoke(). This function uses m_bRaiseException to signal that an error occurred during the DispInvoke() call.

STDMETHODIMP
CLines::Invoke(
    DISPID dispidMember,
    REFIID riid,
    LCID lcid,
    WORD wFlags,
    DISPPARAMS FAR* pdispparams,
    VARIANT FAR* pvarResult,
    EXCEPINFO FAR* pexcepinfo,
    UINT FAR* puArgErr)
{
    return DispInvoke(
    this, m_ptinfo,
    dispidMember, wFlags, pdispparams,
    pvarResult, pexcepinfo, puArgErr); 
}

See Also

CreateStdDispatch(), IDispatch::Invoke()  

DosDateTimeToVariantTime()

NAME

DosDateTimeToVariantTime() - Converts the MS-DOS representation of time to the date and time representation stored in a variant.

Synopsis

#include <oleauto.h>

int DosDateTimeToVariantTime((
        unsigned short wDOSDate,
        unsigned short wDOSTime,
        double FAR* pvtime );

Description

Converts the MS-DOS representation of time to the date and time representation stored in a variant.

MS-DOS records file dates and times as packed 16-bit values. An MS-DOS date has the following format.

1.  MS-DOS Date Format

An MS-DOS time has the following format.

2.  MS-DOS Time Format

Parameters

wDOSDate

The MS-DOS date to convert.

wDOSTime

The MS-DOS time to convert.

pvtime

Pointer to the location to store the converted time.

Return Values

The return value obtained from the returned HRESULT is one of the following:

TRUE

Success.

FALSE

Failure.

GetActiveObject()

NAME

GetActiveObject() - Retrieves a pointer to a running object that has been registered with COM.

Synopsis

#include <oleauto.h>

HRESULT GetActiveObject((
        REFCLSID rclsid,
        void FAR * pvReserved,
        IUnknown FAR * FAR * ppunk );

Parameters

rclsid

Pointer to the class identifier (CLSID) of the active object from the COM registration database.

pvReserved

Reserved for future use. Must be NULL.

ppunk

On return, a pointer to the requested active object.

Return Values

The return value obtained from the returned HRESULT is one of the following:

S_OK

Success.

Other return codes

Failure.

Retrieves a pointer to a running object that has been registered with OLE.  

RegisterActiveObject()

NAME

RegisterActiveObject() - Registers an object as the active object for its class.

Synopsis

#include <oleauto.h>

HRESULT RegisterActiveObject((
        IUnknown FAR * punk,
        REFCLSID rclsid,
        DWORD dwFlags,
        Unsigned long FAR * pdwRegister );

Description

Registers an object as the active object for its class.

The RegisterActiveObject() function registers the object to which punkpoints as the active object for the class denoted by rclsid.Registration causes the object to be listed in the running object table (ROT) of COM, a globally accessible lookup table that keeps track of objects that are currently running on the computer. (For more information about the running object table, see the OLE Programmer's Reference.) The dwFlags parameter specifies the strength or weakness of the registration, which affects the way the object is shut down.

In general, ActiveX objects should behave in the following manner:

• If the object is visible, it should shut down only in response to an explicit user command (such as the Exit command on the File menu), or to the equivalent command from an ActiveX client (invoking the Quit or Exit method on the Application object).

• If the object is not visible, it should shut down only when the last external connection to it is gone.

Strong registration performs an AddRef() on the object, incrementing the reference count of the object (and its associated stub) in the running object table. A strongly registered object must be explicitly revoked from the table with RevokeActiveObject(). The default is strong registration (ACTIVEOBJECT_STRONG).

Weak registration keeps a pointer to the object in the running object table, but does not increment the reference count. Consequently, when the last external connection to a weakly registered object disappears, COM releases the object's stub, and the object itself is no longer available.

To ensure the desired behavior, consider not only the default actions of COM, but also the following:

• Even though code can create an invisible object, the object may become visible at some later time. Once the object is visible, it should remain visible and active until it receives an explicit command to shut down. This can occur after references from the code disappear.

• Other ActiveX clients may be using the object. If so, the code should not force the object to shut down.

To avoid possible conflicts, you should always register ActiveX objects with ACTIVEOBJECT_WEAK, and call CoLockObjectExternal, when necessary, to guarantee the object remains active. CoLockObjectExternal() adds a strong lock, thereby preventing the object's reference count from reaching zero. For detailed information about this function, refer to the OLE Programmer's Reference.

Most commonly, objects need to call CoLockObjectExternal() when they become visible, so they remain active until the user requests the object to shut down. The following procedure lists the steps your code should follow to shut down an object correctly.

To Shut Down an Active Object

1. When the object becomes visible, make the following call to add a lock for the user:

   CoLockObjectExternal(punk, TRUE, TRUE)
   

   The lock remains in effect until a user explicitly requests the object to be shut down, such as with a Quit or Exit command.

2. When the user requests the object to be shut down, call CoLockObjectExternal() again to free the lock, as follows:

   CoLockObjectExternal(punk, FALSE, TRUE)
   

3. Call RevokeActiveObject() to make the object inactive.

4. To end all connections from remote processes, call CoDisconnectObject() as follows:

   CoDisconnectObject(punk, 0)
   

This function is described in more detail in the OLE Programmer's Reference.

Parameters

punk

Pointer to the IUnknown() interface of the active object.

rclsid

Pointer to the CLSID of the active object.

dwFlags

Flags controlling registration of the object. Possible values are ACTIVEOBJECT_STRONG and ACTIVEOBJECT_WEAK.

pdwRegister

On return, a pointer to a handle. This handle must be passed to RevokeActiveObject() to end the object's active status.

Return Values

The return value obtained from the returned HRESULT is one of the following:

S_OK

Success.

Other return codes

Failure.

RevokeActiveObject()

NAME

RevokeActiveObject() - Ends an object's status as active.

Synopsis

#include <oleauto.h>

HRESULT RevokeActiveObject((
        Unsigned long dwRegister,
        void FAR * pvReserved );

Parameters

dwRegister

A handle previously returned by RegisterActiveObject().

pvReserved

Reserved for future use. Must be NULL.

Return Values

The return value obtained from the returned HRESULT is one of the following:

S_OK

Success.

Other return codes

Failure.

Ends an object's status as active.  

CompareString()

NAME

CompareString() - Compares two character strings of the same locale according to the supplied LCID.

Synopsis

#include <Winnls.h>

int CompareString((
        LCID lcid,
        DWORD dwCmpFlags,
        LPCWSTR lpString1,
        integer cchCount1,
        LPWSTR lpString2,
        integer cchCount2,
         );

Description

Compares two character strings of the same locale according to the supplied LCID.

When used without any flags, this function uses the same sorting algorithm as lstrcmp in the given locale. When used with NORM_IGNORECASE, the same algorithm as lstrcmpi is used.

For double-byte character set (DBCS) locales, the flag NORM_IGNORECASE has an effect on all the wide (two-byte) characters as well as the narrow (one-byte) characters. This includes the wide Greek and Cyrillic characters.

In Chinese Simplified, the sorting order used to compare the strings is based on the following sequence: symbols, digit numbers, English letters, and Chinese Simplified characters. The characters within each group sort in character-code order.

In Chinese Traditional, the sorting order used to compare the strings is based on the number of strokes in the characters. Symbols, digit numbers, and English characters are considered to have zero strokes. The sort sequence is symbols, digit numbers, English letters, and Chinese Traditional characters. The characters within each stroke-number group sort in character-code order.

In Japanese, the sorting order used to compare the strings is based on the Japanese 50-on sorting sequence. The Kanji ideographic characters sort in character-code order.

In Japanese, the flag NORM_IGNORENONSPACE has an effect on the daku-on, handaku-on, chou-on, you-on, and soku-on modifiers, and on the repeat kana/kanji characters.

In Korean, the sort order is based on the sequence: symbols, digit numbers, Jaso and Hangeul, Hanja, and English. Within the Jaso-Hangeul group, each Jaso character is followed by the Hangeuls that start with that Jaso. Hanja characters are sorted in Hangeul pronunciation order. Where multiple Hanja have the same Hangeul pronunciation, they are sorted in character-code order.

The NORM_IGNORENONSPACE flag only has an effect for the locales in which accented characters are sorted in a second pass from main characters. All characters in the string are first compared without regard to accents and (if the strings are equal) a second pass over the strings to compare accents is performed. In this case, this flag causes the second pass to not be performed. Some locales sort accented characters in the first pass, in which case this flag will have no effect.

If the return value is 2, the two strings are equal in the collation sense, though not necessarily identical (the case might be ignored, and so on).

If the two strings are of different lengths, they are compared up to the length of the shortest one. If they are equal to that point, the return value will indicate that the longer string is greater.

To maintain the C run-time convention of comparing strings, the value 2 can be subtracted from a non-zero return value. The meaning of < 0, == 0, and > 0 is then consistent with the C run-time conventions.

Parameters

lcid

Locale context for the comparison. The strings are assumed to be represented in the default ANSI code page for this locale.

dwCmpFlags

Flags that indicate the character traits to use or ignore when comparing the two strings. Several flags can be combined , or none can be used. (In the case of this function, there are no illegal combinations of flags.) Compare flags include the following.

1.  *** UNTITLED ***

lpString1 and lpString2

The two strings to be compared.

cchCount1 and cchCount2

The character counts of the two strings. The count does not include the NULL-terminator (if any). If either cchCount1 or cchCount2 is *1, the corresponding string is assumed to be NULL-terminated, and the length is calculated automatically.

Return Values

0

Failure.

1

lpString1 is less than lpString2.

2

lpString1 is equal to lpString2.

3

lpString1 is greater than lpString2.

LCMapString()

NAME

LCMapString() - Transforms the case or sort order of a string.

Synopsis

#include <Winnls.h>

int LCMapString((
        LCID lcid,
        DWORD dwMapFlags,
        LPCWSTR lpSrcStr,
        int cchSrc,
        LPWSTR lpDestStr,
        int cchDest,
         );

Description

Transforms the case or sort order of a string.

LCMapStringA maps one character string to another, performing the specified locale-dependent translation.

The flag LCMAP_UPPER produces the same result as AnsiUpper in the given locale. The flag LCMAP_LOWER produces the same result as AnsiLower. This function always maps a single character to a single character.

The mapped string is NULL-terminated if the source string is NULL-terminated.

When used with LCMAP_UPPER and LCMAP_LOWER, the lpSrcStr and lpDestStr may be the same to produce an in-place mapping. When LCMAP_SORTKEY is used, the lpSrcStr and lpDestStr pointers may not be the same. In this case, an error will result.

The LCMAP_SORTKEY transforms two strings so that when they are compared with the standard C library function strcmp (by strict numerical valuation of their characters), the same order will result, as if the original strings were compared with CompareStringA. When LCMAP_SORTKEY is specified, the output string is a string (without NULLs, except for the terminator), but the character values will not be meaningful display values. This is similar behavior to the ANSI C function strxfrm.

Parameters

lcid

Locale ID context for mapping. The strings are assumed to be represented in the default ANSI code page for this locale.

dwMapFlags

Flags that indicate what type of transformation is to occur during mapping. Several flags can be combined on a single transformation (though some combinations are illegal). Mapping options include the following.

1.  Mapping Options

The latter five options (LCMAP_IGNORECASE, LCMAP_IGNORENONSPACE, LCMAP_IGNOREWIDTH, LCMAP_IGNOREKANATYPE, and LCMAP_IGNORESYMBOLS) are normalization options that can only be used in combination with the LCMAP_SORTKEY conversion option.

Conversion options can be combined only when they are taken from the following three groups, and then only when there is no more than one option from each group:

• Casing options (LCMAP_LOWERCASE, LCMAP_UPPERCASE)

• Width options (LCMAP_HALFWIDTH, LCMAP_FULLWIDTH)

• Kana options (LCMAP_HIRAGANA, LCMAP_KATAKANA)

lpSrcStr

Pointer to the supplied string to be mapped.

cchSrc

Character count of the input string buffer. If *1, lpSrcStr is assumed to be NULL-terminated and the length is calculated automatically.

lpDestStr

Pointer to the memory buffer that stores the resulting mapped string.

cchDest

Character count of the memory buffer pointed to by lpDestStr. If cchDest is 0, then the return value of this function is the number of characters required to hold the mapped string. In this case, the lpDestStr pointer is not referenced.

Return Values

0

Failure.

The number of characters written to lpDestStr

Success.

If the function succeeds, and the value of cchDest is nonzero, the return value is the number of characters, or bytes if LCMAP_SORTKEY is specified, written to the buffer. This count includes room for a NULL terminator.

If the function succeeds, and the value of cchDest is zero, the return value is the size of the buffer in characters, or bytes if LCMAP_SORTKEY is specified, required to receive the translated string or sort key. This size includes room for a NULL terminator.

If the function fails, the return value is 0. To get extended error information, call GetLastError(). GetLastError() may return one of the following error codes:

• ERROR_INSUFFICIENT_BUFFER

• ERROR_INVALID_FLAGS

• ERROR_INVALID_PARAMETER

GetLocaleInfo()

NAME

GetLocaleInfo() - Retrieves locale information from the user's system.

Synopsis

int GetLocaleInfoA(
        LCID lcid,
        LCTYPE LCType,
        LPSTR lpLCData,
        int cchData,
         );

Description

Retrieves locale information from the user's system.

GetLocaleInfoA returns one of the various pieces of information about a locale by querying the stored locale database or Win.ini. The call also indicates how much memory is necessary to contain the desired information.

The information returned is always a NULL-terminated string. No integers are returned by this function and numeric values are returned as text. (See the format descriptions under LCTYPE).

Parameters

lcid

The locale ID. The returned string is represented in the default ANSI code page for this locale.

LCType

Flag that indicates the type of information to be returned by the call. See the listing of constant values defined in this chapter. LOCALE_NOUSEROVERRIDE | LCTYPE indicates that the desired information will always be retrieved from the locale database, even if the LCID is the current one and the user has changed some of the values in the Windows 95 Control Panel. If this flag is not specified, the values in Win.ini take precedence over the database settings when getting values for the current system default locale.

lpLCData

Pointer to the memory where GetLocaleInfoA will return the requested data. This pointer is not referenced if cchData is 0.

cchData

Character count of the supplied lpLCData memory buffer. If cchData is 0, the return value is the number of characters required to hold the string, including the terminating NULL character. In this case, lpLCData is not referenced.

Return Values

0

Failure.

The number of characters copied, including the terminating null character.

Success.

If the function succeeds, the return value is the number of bytes (ANSI version) or characters (Unicode version) written to the destination buffer, or, if the cchData parameter is zero, the number of bytes or characters required to hold the locale information.

If the function fails, the return value is zero. To get extended error information, call GetLastError(). GetLastError() may return one of the following error codes:

• ERROR_INSUFFICIENT_BUFFER

• ERROR_INVALID_FLAGS

• ERROR_INVALID_PARAMETER

GetStringType()

NAME

GetStringType() - Retrieves locale type information about each character in a string.

Synopsis

#include <winnls.h>

BOOL GetStringTypeA(
        LCID lcid,
        DWORD dwInfoType,
        LPCSTR lpSrcStr,
        int cchSrc,
        LPWORD lpCharType,
         );

Description

Retrieves locale type information about each character in a string.

The lpSrcStr and lpCharType pointers cannot be the same. In this case, the error ERROR_INVALID_PARAMETER results.

The character type bits are divided up into several levels. One level's information can be retrieved by a single call.

This function supports three character types:

• CT_CTYPE1

• CT_CTYPE2

• CT_CTYPE3

CT_CTYPE1 character types support ANSI C and POSIX character typing functions. A bitwise OR of these values is returned when dwInfoType is set to CT_CTYPE1. For DBCS locales, the CT_CTYPE1 attributes apply to both narrow characters and wide characters. The Japanese hiragana and katakana characters, and the kanji ideograph characters all have the C1_ALPHA attribute.

The following table lists the Ctype 1 character types.

1.  CT_CTYPE1 Character Types

The Windows version 3.1 functions IsCharUpper and IsCharLower do not always produce correct results for characters in the range 0x80-0x9f, so they may produce different results than this function for characters in that range. (For example, the German Windows version 3.1 language driver incorrectly reports 0x9a, lowercase s hacek, as uppercase).

CT_CTYPE2 character types support the proper layout of text. For DBCS locales, CT_CTYPE2 applies to both narrow and wide characters. The directional attributes are assigned so that the BiDi layout algorithm standardized by Unicode produces the correct results. For more information on the use of these attributes, see The Unicode Standard: Worldwide Character Encoding from Addison-Wesley publishers.

2.  CT_CTYPE2 Character Types

CT_CTYPE3 character types are general text-processing information. A bitwise OR of these values is returned when dwInfoType is set to CT_CTYPE3. For DBCS locales, the CT_CTYPE3 attributes apply to both narrow characters and wide characters. The Japanese hiragana and katakana characters, and the kanji ideograph characters all have the C3_ALPHA attribute.

3.  CT_CTYPE3 Character Types

Parameters

lcid

Locale context for the mapping. The string is assumed to be represented in the default ANSI code page for this locale.

dwInfoType

Type of character information to retrieve. The various types are divided into different levels. (See the Description section for a list of information included in each type). The options are mutually exclusive. The following types are supported:

• CT_CTYPE1

• CT_CTYPE2

• CT_CTYPE3

lpSrcStr

String for which character types are requested. If cchSrc is *1, lpSrcStr is assumed to be NULL-terminated.

cchSrc

Character count of lpSrcStr. If cchSrc is *1, lpSrcStr is assumed to be NULL-terminated. This must also be the character count of lpCharType.

lpCharType

Array of the same length as lpSrcStr (cchSrc). On output, the array contains one word corresponding to each character in lpSrcStr.

Return Values

0

Failure.

1

Success.

GetSystemDefaultLangID()

NAME

GetSystemDefaultLangID() - Retrieves the default LANGID from a user's system.

Synopsis

#include <Winnls.h>

LANGID GetSystemDefaultLangID((
         );

Description

Returns the system default LANGID. For information on how this value is determined, see GetSystemDefaultLCID().

Return Values

0

Failure.

System default LANGID

Success.

GetSystemDefaultLCID()

NAME

GetSystemDefaultLCID() - Retrieves the default LCID from a user's system.

Synopsis

#include <Winnls.h>

LCID GetSystemDefaultLCID((
         );

Description

Returns the system default LCID. The return value is determined by examining the values of sLanguage and iCountry in Win.ini, and comparing the values to those in the stored locale database. If no matching values are found, or the required values cannot be read from Win.ini, or if the stored locale database cannot be loaded, the value 0 is returned.

Return Values

0

Failure.

System default locale ID

Success.

GetUserDefaultLangID()

NAME

GetUserDefaultLangID() - Retrieves the default LANGID from a user's system.

Synopsis

#include <Winnls.h>

LANGID GetUserDefaultLangID((
         );

Description

Returns the user default LANGID. On single-user systems, the value returned from this function is always the same as that returned from GetSystemDefaultLangID().

Return Values

0

Failure.

User default LANGID

Success.

GetUserDefaultLCID()

NAME

GetUserDefaultLCID() - Retrieves the default LCID from a user's system.

Synopsis

#include <Winnls.h>

LCID GetUserDefaultLCID((
         );

Description

Returns the user default LCID. On single-user systems, the value returned by this function is always the same as that returned from GetSystemDefaultLCID().

Return Values

0

Failure.

User default locale ID

Success.

SafeArrayAccessData()

NAME

SafeArrayAccessData() - Increments the lock count of an array, and retrieves a pointer to the array data.

Synopsis

#include <oleauto.h>

HRESULT SafeArrayAccessData((
        SAFEARRAY FAR* psa,
        void HUGEP* FAR* ppvdata );

Parameters

psa

Pointer to an array descriptor created by SafeArrayCreate().

ppvdata

On exit, pointer to a pointer to the array data. Arrays may be larger than 64K, so very large pointers should be used only in Windows version 3.1 or later.

Return Values

The return value obtained from the returned HRESULT is one of the following.

S_OK

Success.

E_INVALIDARG

The argument psa was not a valid safe array descriptor.

E_UNEXPECTED

The array could not be locked.

Increments the lock count of an array, and retrieves a pointer to the array data.

Examples

The following example sorts a safe array of one dimension that contains BSTRs by accessing the array elements directly. This approach is faster than using SafeArrayGetElement() and SafeArrayPutElement().

long i, j, min;  
BSTR bstrTemp;
BSTR HUGEP *pbstr;
HRESULT hr;
// Get a pointer to the the elements of the array.
hr = SafeArrayAccessData(psa, (void HUGEP* FAR*)&pbstr);
if (FAILED(hr))
    goto error;
// Bubble sort.
cElements = lUBound-lLBound+1; 
for (i = 0; i < cElements-1; i++)
{
    min = i;
    for (j = i+1; j < cElements; j++)
    {
        if (wcscmp(pbstr[j], pbstr[min]) < 0)
            min = j; 
    }
    // Swap array[min] and array[i].
    bstrTemp = pbstr[min];
    pbstr[min] = pbstr[i];
    pbstr[i] = bstrTemp;
}
SafeArrayUnaccessData(psa);

SafeArrayAllocData()

NAME

SafeArrayAllocData() - Allocates memory for a safe array, based on a descriptor created with SafeArrayAllocDescriptor().

Synopsis

#include <oleauto.h>

HRESULT SafeArrayAllocData((
        SAFEARRAY FAR* psa );

Parameters

psa

Pointer to an array descriptor created by SafeArrayAllocDescriptor().

Return Values

The return value obtained from the returned HRESULT is one of the following.

S_OK

Success.

E_INVALIDARG

The argument psa was not a valid safe array descriptor.

E_UNEXPECTED

The array could not be locked.

Allocates memory for a safe array, based on a descriptor created with SafeArrayAllocDescriptor().

Examples

The following example creates a safe array using the SafeArrayAllocDescriptor() and SafeArrayAllocData() functions.

SAFEARRAY FAR* FAR*ppsa;
unsigned int ndim =  2;
HRESULT hresult = SafeArrayAllocDescriptor(ndim, ppsa);
if( FAILED(hresult))
    return ERR_OutOfMemory;
(*ppsa)->rgsabound[ 0 ].lLbound = 0;
(*ppsa)->rgsabound[ 0 ].cElements = 5;
(*ppsa)->rgsabound[ 1 ].lLbound = 1;
(*ppsa)->rgsabound[ 1 ].cElements = 4;
hresult = SafeArrayAllocData(*ppsa);
if( FAILED(hresult)) {
    SafeArrayDestroyDescriptor(*ppsa)
    return ERR_OutOfMemory;
}

See Also

SafeArrayAllocData(), SafeArrayDestroyData(), SafeArrayDestroyDescriptor()  

SafeArrayAllocDescriptor()

NAME

SafeArrayAllocDescriptor() - Allocates memory for a safe array descriptor.

Synopsis

#include <oleauto.h>

HRESULT SafeArrayAllocDescriptor((
        unsigned int cDims,
        SAFEARRAY FAR* FAR* ppsaOut );

Description

Allocates memory for a safe array descriptor.

This function allows the creation of safe arrays that contain elements with data types other than those provided by SafeArrayCreate(). After creating an array descriptor using SafeArrayAllocDescriptor(), set the element size in the array descriptor, an call SafeArrayAllocData() to allocate memory for the array elements.

Parameters

cDims

The number of dimensions of the array.

ppsaOut

Pointer to a location in which to store the created array descriptor.

Return Values

The return value obtained from the returned HRESULT is one of the following.

S_OK

Success.

E_INVALIDARG

The argument psa was not a valid safe array descriptor.

E_UNEXPECTED

The array could not be locked.

Examples

The following example creates a safe array using the SafeArrayAllocDescriptor() and SafeArrayAllocData() functions.

SAFEARRAY FAR* FAR*ppsa;
unsigned int ndim =  2;
HRESULT hresult = SafeArrayAllocDescriptor( ndim, ppsa );
if( FAILED( hresult ) )
    return ERR_OutOfMemory;
(*ppsa)->rgsabound[ 0 ].lLbound = 0;
(*ppsa)->rgsabound[ 0 ].cElements = 5;
(*ppsa)->rgsabound[ 1 ].lLbound = 1;
(*ppsa)->rgsabound[ 1 ].cElements = 4;
hresult = SafeArrayAllocData( *ppsa );
if( FAILED( hresult ) ) {
    SafeArrayDestroyDescriptor( *ppsa )
    return ERR_OutOfMemory;
}

See Also

SafeArrayAllocData(), SafeArrayDestroyData(), SafeArrayDestroyDescriptor()  

SafeArrayCopy()

NAME

SafeArrayCopy() - Creates a copy of an existing safe array.

Synopsis

#include <oleauto.h>

HRESULT SafeArrayCopy((
        SAFEARRAY FAR* psa,
        SAFEARRAY FAR* FAR* ppsaOut );

Description

Creates a copy of an existing safe array.

SafeArrayCopy() calls the string or variant manipulation functions if the array to copy contains either of these data types. If the array being copied contains object references, the reference counts for the objects are incremented.

Parameters

psa

Pointer to an array descriptor created by SafeArrayCreate().

ppsaOut

Pointer to a location in which to return the new array descriptor.

Return Values

The return value obtained from the returned HRESULT is one of the following.

S_OK

Success.

E_INVALIDARG

The argument psa was not a valid safe array descriptor.

E_OUTOFMEMORY

Insufficient memory to create the copy.