# Creating a Custom Interface

Writing an application using a custom interface is similar to writing an OLE application using standard interfaces, with two important differences. First, in addition to registering the class identifier (CLSID) for your object, you also must register the unique interface identifier (IID) for your custom interface. Second, you must provide OLE with proxy and stub components capable of remoting the interface. In most cases, you will use the MIDL compiler to generate code to create the proxy/stub DLL for your custom interface. (For more information, see Files Generated for an OLE Interface in the Microsoft RPC documentation for the Win32 SDK.)

As an OLE developer, you should already be familiar with the concept of using CLSIDs and interface identifiers (IIDs) to uniquely identify class objects and interfaces. The MIDL compiler refers to universally unique identifiers (UUIDs) and uses UUIDs to uniquely represent its interfaces. In this case, a UUID is the same as an IID. Every custom interface must have a IID; the UUIDGEN.EXE tool provided with the toolkit can create one for you.

MIDL is a rich, complex language that allows you to define interface parameters carefully in terms of their direction and type. Although the MIDL compiler offers much, you will need only a small subset of its attributes to define your interface.

The IDL file consists of two parts: the interface header and the interface body. The interface header, delimited by brackets, contains information about the interface as a whole, such as its IID. A prerequisite to completing the interface header is running the RPC utility UUIDGEN.EXE to create the IID. Because IIDs must be unique, never reuse one of them by copying it from one IDL file to another. The header also contains the keyword object, indicating that this interface is a COM-style interface (that is, derived from IUnknown). Whereas standard RPC interfaces have the version attribute in their interface headers, object interfaces do not.

The following excerpt is from an IDL file:

    [
        object,
        uuid(7ACC12C3-C4BB-101A-BB6E-0000C09A6549),
        pointer_default(unique)
    ]

The uuid attribute precedes the unique identifier for the interface. The pointer_default attribute specifies the default IDL type for all pointers except for those included in parameter lists. Parameter list pointers must be explicitly declared with the pointer attribute. The default pointer type may either be unique, ref, or ptr. For more information on using IDL with pointers, see the RPC Programmer’s Guide and Reference.

The interface body contains declarations for data members, prototypes for all methods, and other information such as directives to the preprocessor and include statements for other IDL files. The following example is the interface body for ICustomInterface:

    interface ICustomInterface : IUnknown
    {
        import "unknwn.idl";

        HRESULT CustomReport(void);
    }

The import attribute allows an interface to reference constructs defined in other IDL files. Because ICustomInterface derives from IUnknown, the UNKNWN.IDL file must be included. ICustomInterface has only one method that takes no parameters; few interfaces will be this simple.