Data Types

Summary

• IDL Data Types Summary
• Signed / Unsigned
• int / long
• char
• Visual Basic
• unsigned char/ byte
• char / wchar_t
• LPOLESTR / BSTR
• Enumerated Types
• Object References
• Structures
• typedef
• Properties
• Interface Inheritance
• Dispatch Interfaces

IDL Data TYPES SUMMARY

Because not all IDL data types have mappings into all implementation languages, care should be exercised in making type choices at interface design time.

Signed / Unsigned

Although these modifiers do not affect marshalling, their presence is important when they are are mapped to language-level types. 

int / long

Do not use data type int. Always use long.

char

Always qualify it explicitly with either signed or unsigned.

Visual Basic

Interfaces designed for use with VB must not use

• unsigned 16-bit integers (unsigned int, unsigned short)
• unsigned 32-bit integers (unsigned long)
• signed 8-bit integers (char c, small s)

unsigned char/ byte

When binary data needs to be transmitted always use byte instead of char.

char / wchar_t

wchar_t is preferred for single characters and strings, and byte data type should be used for transmitting binary data. Therefore, the char data type is of very limited use in COM  interfaces. Avoid using it if possible.

LPOLESTR / BSTR

• When developing interfaces for VB use the BSTR type. 
• For C++, ensure that interface methods that use BSTR do not get passed an LPOLESTR string.

Enumerated Types

• Always use [v1_enum] attribute to cause enums to be transmitted as 32 bits.
• Perform range checking at run-time inside the function implementation.

Object References

• If it is not possible to pass a strongly typed function parameter (because it may be unknown at design or compile time), use the [iid_is()] attribute and pass an  IUnknown pointer.
• Interfaces that use the Universal Marshaler, must either use strongly typed object  references, or force the method implementation to use QueryInterface().

Structures

• To use structures as method parameters, pass them by value if the interface will be used only by C++. 
• Pass them by reference if the interface will be used by VB and/or C++. This is because VB does not support passing user-defined data types (i.e., structures) by  value

Typedef

• Avoid the common C++ practice of defining type definitions for structures using tag<name>.
• Avoid adding a GUID to a typedef.

Properties

• To accomplish a read-only property omit the [propput] attribute, and to accomplish a write-only property omit the [propget] attribute.
• Property methods may have more than one parameter. The number and type of the parameters for [propget] must match those of [propput]. If [propget] takes more than on parameter, the last parameter for [propget] must be marked [out, retval], and all preceding parameters, if any, must be marked [in].
• [propputref] attribute is only applicable for object references and makes a real difference only for Visual Basic. A property annotated with [propputref] requires the use of the Set keyword in VB.

Interface Inheritance

When implementing interfaces in VB, interface inheritance should be avoided. VB cannot implement any interface that does not derive directly from IUnknown or IDispatch.

Dispatch Interfaces

The [dual] attribute indicates that an interface is callable through v-table and through IDispatch. The [dual] attribute also implies the [oleautomation] attribute, hence [dual] interfaces typically use the Universal Marshaler.

DETAILS

SIGNED / UNSIGNED

Whether a data type is signed or unsigned is irrelevant during marshalling. However, when IDL types are mapped to language-level types (C++ or VB), the presence of  signed / unsigned modifiers is important.

INT / LONG

Avoid the int data type and explicitly use long data type. Although the marshalling code treats an int as a long ,there is no guarantee that the C++ compiler will do the same.

CHAR

char data type should be used with care. Always qualify it explicitly with either signed or unsigned. MIDL compiler treats unqualified char in IDL as unsigned char when  generating C++ mappings. However, MIDL treats the unqualified char in IDL as signed char when generating the type library.

VISUAL BASIC

Interfaces designed for use with VB must not use the following data types (VB does not recognize them)

• unsigned 16-bit integers (unsigned int, unsigned short)
• unsigned 32-bit integers (unsigned long)
• signed 8-bit integers (char c, small s)

UNSIGNED CHAR / BYTE

In C++, unsigned char and byte are equivalent. In IDL, they are not. char data type is subject to format conversions on the wire, where as byte is not. Therefore, when binary data needs to be transmitted always use byte instead of char.

CHAR / WCHAR_T

32-bit implementations use UNICODE to represent strings. In IDL, wchar_t is used to represent a UNICODE character, and when coupled with [string] attribute, a wchar_t data type represents a UNICODE string. Therefore, given that wchar_t is preferred for single characters and strings, and that the byte data type should be used for transmitting binary data, the char data type is of very limited use in COM interfaces. Avoid using char data type if possible.

LPOLESTR / BSTR

Visual Basic stores strings as UNICODE and has its own internal string type, string, which maps directly to BSTR. Therefore, when developing interfaces for VB use the BSTR type. In C++, LPOLESTR is typedefd as BSTR which allows C++ to treat BSTR and LPOLESTR as synonyms. However, in C++, the BSTR data type is a pointer to the first character in the string; the 4-byte count still exists and consequently, BSTR should be managed using Win32 APIs: 

void TakeLPOLESTR( LPOLESTR pwsz); 
void TakeBSTR( BSTR bstr);

// pass a BSTR to LPOLESTR function 
TakeLPOLESTR( bstrName);

This works correctly as long as bstrName does not have a NULL embedded in it. However,

void TakeLPOLESTR( LPOLESTR pwsz); 
void TakeBSTR( BSTR bstr); 

// pass an LPOLESTR to a BSTR function 
TakeBSTR( pwszName); 

TakeBSTR() function expects BSTR which always has a 4-byte count that precedes the string. If TakeBSTR() uses any of the Win32 API to manage BSTR, then we'll get a crash simply because pwszName does not contain the 4-byte count. Therefore, ensure that interface methods that use BSTR do not get passed an LPOLESTR. string. 

ENUMERATED TYPES

• Constants defined in an enum may be qualified with an explicit value. If no starting value is supplied, then zero is assumed. Several constants can have the same value.

[v1_enum] enum RGB     // [v1_enum] explained below
{ 
    RED,             // implicitly 0
    GREEN = 0,
    BLUE,            // implicitly 1
};

• Enumerated types can appear inside a library block as a reference or as a definition. In either case the resulting typelib will contain the definition for the enum.

[v1_enum] enum RGB
{ 
    RED,             // implicitly 0
    GREEN = 0,
    BLUE,            // implicitly 1
}; 

[ . . . ]
library EnumLib
{
    enum RGB;        // enum defined outside the library block
}

• Enumerated types are always stored as 32 bits in memory, but by default they are represented by 16 bits when marshaled. This can result in loss of information. Therefore, always use [v1_enum] attribute to cause enums to be transmitted as 32 bits.

[v1_enum] enum RGB   // [v1_enum] explained below
{ 
    RED,             // implicitly 0
    GREEN = 0,
    BLUE,            // implicitly 1
};

• Enumerations are useful in designs when a particular parameter can have a limited number of possible values. Range checking can be problematic and must be addressed correctly. 

[v1_enum] enum RGB 
{
    RED,         // 0
    GREEN,       // 1
    BLUE         // 2
};

[ . . . ]
interface IColors : IUnknown 
{
    HRESULT SetColor( [in] enum RGB rgbColor );
}

A Visual Basic developer can pass any 32-bit value. A C++ developer can also pass an incorrect value using a cast. There are two ways to address this problem:

1. If interception code is used between client and object, use the [range] attribute. However, note that it can only be used if all of the following are true,
   
   • The parameter type is either an enum, 32-, or 16-, or 8-bit integer.
   • If the parameter is an enum, its values are contiguous,
   • The parameter is an [in] parameter. 
   • The OS is Windows 2000 or later.
   • Interception is done using proxy-stub DLL. [range] does not appear in type libraries, and hence cannot be used with the Universal Marshaler.
     
2. Because of those restrictions, the second and safest approach is to perform range checking at run-time inside the function call.

OBJECT REFERENCES

• Strongly Typed: Strongly type an object reference (interface pointer) if the interface type is known at  design time and at compile time.
  

// IDL
HRESULT TakeAnObjRef( [in] IAtom* );
HRESULT ReturnAnObjRef( [out, retval] IAtom** ppAtom );

// CPP
IAtom* pAtom;
// Init pAtom . . .
pOb->TakeAnObjRef( pAtom );

. . .

IAtom* pAtom2 = NULL;
pObj->ReturnAnObjRef( &pAtom );

• Untyped Object References: If it is not possible to pass a strongly typed parameter (because it may be unknown at design or compile time), use the [iid_is()] attribute and pass an IUnknown pointer. Effectively, this allows us to strongly type a parameter at run time because the interception code will QI through the object reference passed in IUnknown pointer for the IID passed in [iid_is()] 
  
  Assume a method can persist (save) an object using any of the IPersistXML, IPersistFile, and IPersistStorage interfaces.
  

// IDL 
HRESULT PersisteObject( [in] REFIID riid, [in, iid_is(riid)] IUnknown* pUnk );

// CPP Client
IPersistFile* pF;
IPersistXML* pX;
IPersistStorage* pS;

// pF, pS, pS initialized somewhere

PersistObject( __uuidof( pF), pF);     // persist a File
PersistObject( __uuidof( pX), pX);     // persist to XML 
PersistObject( __uuidof( pS), pS);     // persist to Storage

// CPP COM Server
HRESULT PersistObject( REFIID riid, IUnknown* pUnk)
{
    if (riid == IID_IPersistFile) 
        IPersistFile* pF = (IPersistFile*)punk;
    else if (riid == IID_IPersistXML)
        IPersistXML* pX = (IPersistXML*)punk;
    else if (riid == IID_IPersistStorage)
        IPersistStorage* pS = (IPersistStorage*)punk;
    ...
}

Note that PersistObject never needs to call QueryInterface. Assume we did not  use [iid_is()] attribute; we would have to QI the passed parameter which requires  multiple round trips to the input object:

// IDL: Passing untyped object references without [iid_is]
HRESULT PersisteObject( [in] IUnknown* punk );

// CPP Client
IPersistFile* pF;
IPersistXML* pX;
IPersistStorage* pS;

// pF, pS, pS initialized somewhere

// Because all three interfaces are type-compatible with IUnknown each of them is a valid param to PersistObject()
PersistObject(pF);         // persist a File
PersistObject(pX);         // persist to XML 
PersistObject(pS);         // persist to Storage

// CPP COM Server
HRESULT PersistObject( REFIID riid, IUnknown* pUnk)
{
    // QI pUnk for IPersistFile. If failed,

    // QI pUnk for IPersistXML. If failed

    // QI pUnk for IPersistStorage.

    ...
}

• Untyped Object References (void*): The following signature for passing object references is useless. Do not use it as it  forces the client and the method implementation to use casting:

// IDL 
HRESULT PersisteObject( [in] REFIID riid, [in, iid_is(riid)] void* pUnk);

// CPP
PersistObject( __uuidof(pF), (void*)pF);     // NO!

• [iid_is] and Type Library: Information about [iid_is] is not present in the type library and must be avoided in interfaces defined with [oleautomation] or [dual]. In other words, do not use [iid_is] for interfaces that use the Universal Marshaler:
  

// IDL: Erroneous use of [oleautomation] and [iid_is] 
[
    uuid( . . . ),
    object,
    oleautomation
]
interface IVision : IUnknown
{
    HRESULT TakeObjRef( [in] REFIID riid, [in, iid_is(riid)] IUnknown* punk);
}

Therefore, interfaces that use the Universal Marshaler, must either use strongly typed  object references, or force the method implementation to use QueryInterface.

STRUCTURES

• With standard marshalling (proxy/stub DLL or Universal Marshaler) object references, as their name implies, are marshaled by reference; a round trip to the object is  required to retrieve any data, which is inefficient. 
  
  Structures are an efficient way to pass data. Because they are marshaled by value (MBV), rather than reference, the data is directly accessible and hence requires no extra round-trip to retrieve. 
  
  To use structures as method parameters, pass them by value if the interface will be used only by C++. Pass them by reference if the interface will be used by VB and/or  C++. This is because VB does not support passing user-defined data types (i.e.,  structures) by value.
  

// IDL: Passing a struct by reference - VB and VC compatible 

[
    uuid(),
    object,
    ...
]
interface IStruct : IUnknown
{
    // MyPoint is only seen by IStruct. Other interfaces wont see it 
    struct MyPoint
    {
        long x;     // almost used int instead of long! See rule 2
        long y;
    };

    HRESULT TakePoint( [in] struct MyPoint* pPt );
};

Note that a struct definition can be placed either outside the interlace definition block  or inside it. Placing a struct definition inside the interface definition means that only  that interface will see that definition. This helps to keep related types close to each other.  If the interface definition was later removed to a separate file, the struct  definitions will  automatically move with it.

• Structures in Variants: to pass a structure in a VARIANT, the struct  must first be described in the library block of the IDL.
  

// IDL: To pass a struct in a VARIANT, structs must be inside the library block

[ ... ]
library StructLib
{
    [ ... ]
    interface ITransform : IUnknown
    {
        HRESULT Transform( [in] VARIANT vtFirst, [in] VARIANT vtFirst, [out, retval] VARIANT* pvtOut );
    }
    struct MyPoint
    {
        int nX;
        int nY;
    };
}

Passing a structure in a VARIANT from C++ is non-trivial and involves the use of IRecordInfo. Luckily, the system provides an implementation of IRecordInfo that can be retrieved using either GetRecordInfoFromTypeInfo or GetRecrodInfoFromGuids APIs .

TYPEDEFS

• Care should taken when using typedef in IDL; the typedef that appears in the type library is based on the type name of the structure rather then the type name of  the alias:

// IDL: Be careful with typedef!

// Declare a structure
typdef struct MyPoint
{
    int nX;
    int nY;
} MYPOINT;

[ ... ]
library TypeDefLib
{
    [ ... ]
    interface ITrig : IUnknown
    {
        HRESULT AddPoint( [in] MYPOINT* pPt );
    }
}

// .H: generated from above IDL

typedef struct tagMyPoint     // in IDL this is MyPoint
{
    int nX;
    int nY;
} MyPoint;                    // in IDL, this is MYPOINT

HRESULT AddPoint([in] MyPoint* pPt);     // in IDL, MYPOINT

Therefore, the common C++ practice of defining type definitions for structures using tag<name> should be avoided. If it is important that the type library name and the C++ name be identical, and hence in VB be the same, consider using an identical name in both places

// IDL: Avoiding different struct name and struct alias
typedef struct MYPOINT
{
    int nX;
    int nY;
} MYPOINT;

• typedef can be annotated with a GUID:

// IDL: typedefs can have GUIDs. Avoid!

[
    uuid(A7A4DDB4-84CC-11d5-8068-00D0B79F36F8 ),
    public
]
typedef struct MyPoint
{
    int nX;
    int nY;
} MYPOINT;

There is a bug in the compiler that causes a DECLSPEC_UUID to be emitted in the wrong  place. The workaround in complicated and unintuitive. Avoid adding GUIDs to typedefs.

PROPERTIES

• To describe a property in IDL, an interface method is annotated with either [propput], [propget] or [proprputref]. Typically properties are read/write. To  accomplish a read-only property omit [propput], to accomplish a write-only property omit [propget].

// IDL: read/write, read-only, and write-only attributes

[ ... ]
interface IAtom : IUnknown
{
    // Read/Write property
    [propput] Name( [in] BSTR name );
    [propget] Name( [out, retval] BSTR *pName );

    // Read-only property - no [propput]
    [propget] Weight( [out, retval] float *pfWeight );
}

• Properties may have one more than one parameter. However, for [propget] to appear in a type library:
  • The number and type of the parameters for [propget] must match those of [propput].
  • The last parameter for [propget] must be marked [out, retval], and all preceding parameters, if any, must be marked [in].

// IDL: propput and propget with multiple params

[proput] HRESULT Name( [in] BSTR bstr1, [in] BSTR bstr2, [in] BSTR bstr3);

[propget] HRESULT Name([in] BSTR bstr1, [in] BSTR bstr2, [out, retval] BSTR *pbstr3);

• [propputref] attribute is only applicable for object references and makes a real difference only for Visual Basic. Also note that a property annotated with  [propputref] requires the use of the Set keyword in VB, whereas a property annotated with [propput] does not.

// IDL: propputref

[ ... ]
interface IAtomeOfMoleculre : IUnknown
{
    [propget] HRESULT Atom( [in] short nPosition, 
                            [out, retval] IAtom** ppAtom);

    [propput] HRESULT Atom( [in] short nPositon,
                            [in] IAtom* pAtom);

    [propputref] HRESULT Atom( [in] short nPosition,
                               [in] IAtom* pAtom);
}

// VB: [propputref] requires Set

Dim atom1 as IAtom;
Set atom1 = Ob.Atom( 1 )     ' [propget]

Ob.Atom( 1 ) = atom1         ' [propput]

Set Ob.Atom(1) = atom1       ' [propoutref]

INTERFACE INHERITANCE

IDL supports interface inheritance. However, when/if implementing COM classes in Visual Basic, interface inheritance should be avoided because VB cannot implement any interface  that does not derive directly from IUnknown or IDispatch. This is a limitation of VB runtime.

DISPATCH INTERFACES

• The [dual] attribute indicates that an interface is callable through v-table and through IDispatch. The [dual] attribute also implies the [oleautomation] attribute, hence [dual] interfaces typically use the Universal Marshaler.
• When an object exposes more than one v-table interface, and it is required that all of them be supported as an IDispatch interface, define an extra v-table interface that provides the union of all v-table interfaces on the object.

// IDL: A dispatch interface based on a union interface

// Interface 1: v-table
[ ... ]
interface IMechanialClock : IUnknown
{
    [propput] HRESULT Hours( [in] long lHrs );
    [propget] HRESULT Hours( [out, retval] long *plHrs );
};

// Interface 2: v-table
[ ... ]
interface IDigiatalClock : IUnknown
{
    [propput] HRESULT Luminosity( [in] long lLum );
};

// Interface 3: union of all other v-table interfaces
[
    ...
    hidden
]
interface _IHiddenUnion : IUnknown
{
    // Methods of IMechanicalClock
    [propput] HRESULT Hours( [in] long lHrs );
    [propget] HRESULT Hours( [out, retval] long

    // Methods of IDigiatal Clock
    [propput] HRESULT Luminosity( [in] long lLum );
};

// Dispatch interface: All v-table interfaces are supported
[ ... ]
dispinterface _IClock
{
    interface _IHiddenUnion;
};

// Note that the hidden interface does not appear in any coclass statement in IDL or in the
// QI implementation for the class
[ ... ]
coclass Clock
{
    interface IMechanicalClock;
    interface IDigitalClock;
    interface _IClock;
};