Microsoft Interface Definition Language (MIDL)

MIDL Start Page

Microsoft Interface Definition Language

Purpose

The Microsoft® Interface Definition Language (MIDL) defines interfaces between client and server programs. Microsoft Corporation includes the MIDL compiler with the Platform SDK to enable developers to create the interface definition language (IDL) files and application configuration files (ACF) required for remote procedure call RPC interfaces, and COM/DCOM interfaces. MIDL also supports generation of type libraries for OLE Automation.

Where Applicable

MIDL can be used in all client/server applications based on Microsoft Windows® 98 and Windows 2000 operating systems. It can also be used to create client and server programs for heterogeneous network environments that include such operating systems as Unix and Apple. Microsoft supports the Open Group (formerly known as the Open Software Foundation) DCE standard for RPC interoperability.

Developer Audience

When using MIDL with RPC, familiarity with C/C++ programming and the RPC paradigm is required. When using MIDL with COM, familiarity with C++ programming and the RPC paradigm as it applies to COM is required, or alternatively, familiarity with OLE Automation model scripting and type libraries is required.

Run-time Requirements

The appropriate run-time libraries for using MIDL are included with Windows 95/98 and Windows NT®/2000. The MIDL compiler and the components of the RPC development environment are installed when you install the Platform SDK. For details, see Using The MIDL Compiler and Installing the RPC Programming Environment.

See Also

Remote Procedure Calls (RPC) Start Page

Overview

General information about MIDL and the MIDL compiler.

Reference

Documentation of the MIDL compiler command line switches and the MIDL language reference.

Feedback

Make error reports and feature requests directly to Microsoft.

Microsoft Platform SDK, February 2001 Edition.
This content last built on Thursday, February 01, 2001.


Legal Information

MIDL Programmer's Reference

Information in this document, including URL and other Internet web site references, is subject to change without notice. Unless otherwise noted, the example companies, organizations, products, people and events depicted herein are fictitious and no association with any real company, organization, product, person or event is intended or should be inferred. Complying with all applicable copyright laws is the responsibility of the user. Without limiting the rights under copyright, no part of this document may be reproduced, stored in or introduced into a retrieval system, or transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or otherwise), or for any purpose, without the express written permission of Microsoft Corporation.

Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. Except as expressly provided in any written license agreement from Microsoft, the furnishing of this document does not give you any license to these patents, trademarks, copyrights, or other intellectual property.

© 1992-2001 Microsoft Corporation. All rights reserved.

Microsoft, Windows, Windows NT, and Win32 are either registered trademarks or trademarks of Microsoft Corporation in the U.S.A. and/or other countries.

Portions of this documentation are provided under license from Digital Equipment Corporation. Copyright © 1990, 1992 Digital Equipment Corporation. All rights reserved.

The names of actual companies and products mentioned herein may be the trademarks of their respective owners.


About this Guide

This book is a reference for the Microsoft Interface Definition Language (MIDL) and a user's guide for the MIDL compiler, which generates C-language files from IDL files.

The Using the MIDL Compiler section lists the requirements for the C-compiler and pre-processor with which MIDL must interoperate. This section also describes the files that the MIDL compiler generates for RPC stubs, DCOM stubs and OLE Automation type libraries.

The Interface Definitions and Type Libraries section provides information about how to create Interface Definition (IDL) and Application Configuration (ACF) files for MIDL, including reference pages for IDL and ACF attributes. There is also information about how to import files and type libraries, and importing system header files.

The MIDL Command-Line Reference section contains reference information for each command-line switch and switch option recognized by the MIDL Compiler.

The MIDL Language Reference section contains a reference entry for each keyword in the Microsoft Interface Definition Language.

The MIDL Compiler Errors and Warnings section lists the error and warning messages that the MIDL compiler can generate.


Using the MIDL Compiler

The MIDL compiler is automatically installed as part of the Platform SDK setup. The following topics describe the MIDL C compiler and C preprocessor requirements, the link libraries that are part of the Remote Procedure Call (RPC) product, and the files that MIDL generates for DCOM interfaces, RPC interfaces, and OLE Automation type library interfaces.

  • Invoking the MIDL Compiler
  • Response Files
  • C-Preprocessor Requirements for MIDL
  • C/C++-Compiler Considerations
  • Using the __midl Predefined Constant
  • MIDL and RPC
  • MIDL and COM
  • MIDL and ODL

For more information about the files that make up the RPC product, see Installing the RPC Programming Environment.


Invoking the MIDL Compiler

The MIDL compiler can generate code for different platforms and system releases. Consult the /target switch to learn more about suggested switches and how to generate code optimized for a given release, such as Microsoft® Windows 2000®.

Run the MIDL compiler from the command line using the following command:

midl <options> filename.idl

where <options> represents the command-line options you want to use, and Filename.idl is the name of the MIDL file to compile.

A complete listing of MIDL compiler switches and options is available when you use the MIDL compiler /help and /? switches. The switches are organized by categories. For details, see the MIDL Command-Line Reference.


Response Files

As an alternative to placing all the options on the command line, the MIDL compiler accepts response files that contain switches and arguments. A response file is a text file containing one or more MIDL compiler command-line options. Unlike a command line, a response file allows multiple lines of options and file names. This may be useful due to limitations of your build environment or as a convenience for your build process. You can specify a MIDL response file as:

midl @filename
filename
Specifies the name of the response file. The response file name must immediately follow the @ character with no white space between the @ character and the response file name.

Options in a response file are interpreted as if they were present at that place in the MIDL command line. Each argument in a response file must begin and end on the same line. You cannot use the backslash character (\) to concatenate lines.

MIDL supports command-line arguments that include one or more response files, combined with other command-line switches:

midl -Oicf @midl1.rsp -env win32 @midl2.rsp itf.idl

The MIDL compiler does not support nested response files.


Using C/C++-Preprocessor with MIDL

The MIDL compiler does not preprocess source files. Rather, the MIDL compiler uses an available preprocessor to prepare the input stream for parsing. By default, MIDL uses the preprocessor for the Microsoft C/C++ compiler from the same building environment as MIDL. The user can indicate a different preprocessor to be used by MIDL, if needed.

MIDL spawns separate preprocessor runs for top-level IDL and ACF files, and for each file imported with the MIDL import directive. Files included with the #include directive are handled by the preprocessor directly.

The following topics describe various aspects of MIDL-preprocessor interactions:

  • C-Preprocessor Requirements for MIDL
  • Verifying Preprocessor Options
  • Saving Preprocessor Output
  • Dealing with #defines in IDL Files


C-Preprocessor Requirements for MIDL

This page applies only to developers who have specific reasons to replace the Microsoft C/C++ preprocessor as the preprocessor used by MIDL, or to developers who must specify customized preprocessor switches. The MIDL switches /cpp_cmd, /cpp_opt, and /no_cpp are used to override the default behavior of the compiler. There is typically no reason to replace the Microsoft C/C++ preprocessor, nor to specify customized preprocessor switches.

The MIDL compiler uses a C preprocessor during initial processing of the IDL file. The build environment used when compiling the IDL files is associated with a default C/C++ preprocessor. If a different preprocessor is to be used, the MIDL compiler switch /cpp_cmd enables an override of the default C/C++-preprocessor name:

midl /cpp_cmd preprocessor_name filename
preprocessor_name
Specifies the name of the preprocessor to be used by MIDL. May be specified with a path to the binary. The .exe extension is optional.
Filename
Specifies the name of the IDL file.

The MIDL compiler expects any preprocessor to observe the following conventions:

  • The input file is specified as the last argument on the command line.
  • The preprocessor must redirect output to the standard output device, stdout.
  • In the output stream of the preprocessor, the #line directives are present to enable better diagnostic messages.
  • The line directives are the only preprocessor directives in the output stream.

MIDL assumes that the spawned preprocessor has removed all preprocessor directives from the input stream of the compiler, with the exception of the occurrences of the line directive necessary for pinpointing source location in compiler messages. When indicating a preprocessor different from the Microsoft C/C++ preprocessor, or when specifying preprocessor options with the /cpp_opt switch, specifying an appropriate preprocessor option that puts the line directives in the input stream of the compiler is required. For example, for the Microsoft C/C++ preprocessor the /E option would have to be used:

midl /cpp_cmd cl.exe /cpp_opt "/E" file.idl

The #line directive is accepted by MIDL in one of the following forms:

#line digit-sequence "filename" new-line

# digit-sequence "filename" new-line

For a complete description of the line directive and other preprocessor directives, see the documentation for the C-compiler being used.

MIDL accepts only the line preprocessor directive. Therefore, if the /no_cpp switch is used, the input file must not have other preprocessor directives, or the input file must have been processed prior to invoking MIDL.

For more information, see Dealing with #defines in IDL Files.


Dealing with #defines in IDL Files

This page describes why symbols defined with a #define disappear from the MIDL compiler generated H files, and what can be done about it. This explanation applies to any files processed by MIDL, such as *.idl, *.acf, *.h files.

The disappearance of #define symbols is a result of MIDL delegating the preprocessing of input files to a preprocessor. By default, the preprocessor is a C/C++ preprocessor from the build environment. After preprocessing, the input stream MIDL receives has only #line preprocessor directives. In particular, the preprocessor unrolls all macro definitions in input files, and therefore, MIDL cannot detect their presence. Consequently, when MIDL replicates type definitions from an input file to the generated H file, the #defines are not replicated. Therefore, do not use #defines directly in IDL files if they are to be used later from the generated H file.

The following four workarounds are recommended:

  • Use the const declaration specification.
  • Use separate header files that are imported or included in the IDL file, and later included in the C-source code.
  • Use enumeration constants in the IDL file.
  • Use cpp_quote to reproduce #define in the generated header file.

You can reproduce manifest constants using the IDL constant-declaration syntax. Note that the const in the IDL constant-declaration is different from C/C++ const semantics, and simply introduces a named constant for an IDL compilation. For example:

const short ARRSIZE = 10

This example specifies that ARRSIZE is a constant with a value of 10. Named constants can be used in IDL array declarators and other places where a C programmer would use a manifest defines. In addition, this syntax results in the following line being generated in the header file:

#define ARRSIZE 10

Another way to handle #define statements is to package them in a separate header file, either into a file devoted to #define statements or into a file that contains only type definitions. A file that contains only preprocessor directives may be safely included both by the IDL file and the C-source files. Although the directives will not be available in the header file generated by the MIDL compiler, the C-source program can include the separate header file. In a similar fashion, a header file with #define statements and regular type definitions can be imported from your IDL file. This approach encapsulates the #define and typedef statements by using them in an H file such that the #define symbols are not used in the importing IDL file directly. Importing a header or IDL file to another IDL file prevents the typedef statements from being replicated to the H file generated by MIDL (which is in contrast to #include statements). This approach allows the original header file to be safely referenced from the C code along the generated H file without having a problem with duplicated definitions.

Use of enumeration constants in the IDL file is also effective. These constants can be used in constant expressions in IDL, for example, in array declarators. Enumeration constants are not removed during the early phases of MIDL compilation by the C-compiler preprocessor, so enumeration constants are available in the header file generated by the MIDL compiler. Consider the following statement:

typedef enum midlworkaround { MAXSTRINGCOUNT = 300 };

This statement will not be removed during MIDL compilation by the C preprocessor and the typedef will be replicated to the generated H file. The constant MAXSTRINGCOUNT is available to C-source programs that include the header file generated by the MIDL compiler.

Finally, the cpp_quote directive of MIDL can be used to write out an arbitrary string directly into the generated H file. For example, to get the manifest constant used previously on this page with cpp_quote, the following statement can be used:

cpp_quote ("#define ARRSIZE 10");

This statement results in the following line being generated in the header file:

#define ARRSIZE 10


Verifying Preprocessor Options

The MIDL compiler implicitly invokes the preprocessor and does not display its preprocessor switches. In the absence of the MIDL /cpp_opt switch, the preprocessor command line is composed of all the /I, /D and /U switches used in the MIDL command line, as well as /E and /nologo switches. To see the switches passed on to the preprocessor, use the compiler's /confirm switch.

For example, the following line

midl.exe -D_WIN32_WINNT=0x501 -robust -DNTENV=1 -Id:\nt\public\sdk\inc -confirm -Oicf -env win32 -out x86 stub.idl

produces the following output:

32 bit arguments
          input file -  stub.idl
          app_config -  No
               c_ext -  Yes
              client -  stub
                char -  signed
             confirm -  Yes
             cpp_cmd -  cl.exe
             cpp_opt -  -Id:\nt\public\sdk\inc -D_WIN32_WINNT=0x501 -DNTENV=1  -
E -nologo
             msc_ver -  1100
               cstub -  i386\stub_c.c
                   D -  -D_WIN32_WINNT=0x501 -DNTENV=1
                 env -  win32
            append64 -  No
               rpcss -  No
             use_epv -  No
      no_default_epv -  No
               error -  allocation ref bounds_check enum stub_data
              header -  i386\stub.h
                   I -  -Id:\nt\public\sdk\inc
              nologo -  No
              ms_ext -  Yes
            ms_union -  No
       no_format_opt -  No
            oldnames -  No
                 out -  i386\
              server -  stub
               sstub -  i386\stub_s.c
                   O -  interpreted stubs
                   W -  1
                  Zp -  8


Saving Preprocessor Output

Viewing preprocessor output can be an effective troubleshooting method, such as when invalid IDL, C, or C-preprocessor syntax occurs, or when bogus -D values on the MIDL command line result in MIDL reporting arcane errors. Developers may also want to examine preprocessor output to determine which files and definitions were present in the compiler input stream, such as when a difficult case of type redefinition conflict must be resolved. Or less commonly, certain developers may want to force private switches on the preprocessor with /cpp_opt, or may want to see how the switches work.

The easiest and the least obtrusive way to obtain the preprocessed files from a MIDL compile run is to use the -savePP switch. The -savePP switch simply prevents MIDL from deleting the temporary files that the preprocessor passes back to MIDL. Consider the following:

midl -savePP -Id:\nt\public\sdk\inc -DNTENV=1 -Oicf -env win32 stub.idl

This directive compiles Stub.idl, yet preserves all preprocessor files.

Note MIDL spawns separate preprocessor runs for IDL and ACF file (if present) as well as for every imported file.

For a DCOM compile, several preprocessor files are typically produced, even though they are processed by MIDL as a virtual contiguous input stream. In a typical Windows programming environment, the temporary files can be found in the Temp directory as file names such as MID*.tmp. If preserving preprocessor output, it is good practice to watch for recent files in the Temp directory to identify which files are associated with which preprocessor run.

In simple cases, such as when the compiled IDL file does not import other files directly or indirectly, or when examining the top-level file, the preprocessor can be invoked directly. Executing C/C++ preprocessor directly can reveal errors masked or confused by MIDL. For example, the following two preprocessor command lines can be used for the previously quoted MIDL line:

cl /E /nologo -Id:\nt\public\sdk\inc -DNTENV=1 stub.idl > stub.pp
cl /E /P -Id:\nt\public\sdk\inc -DNTENV=1 stub.idl

In the first of these two examples, /E /nologo are the switches that MIDL adds when invoking the preprocessor. The preprocessor output is sent to stdout (the screen), and therefore requires redirection to a file for examination. In the second of these examples, /P directs the preprocessor to redirect the output to a *.i file; in this case a Stub.i file would be created in the current directory.

The /cpp_opt switch can also be used to obtain a preprocessed file, but is difficult and inferior to the previously mentioned methods. The following example also produces a Stub.i file, as did the previous example. The quotes in the following example are essential:

Midl -Oicf -win32 -cpp_opt "/E /P -Id:\nt\public\sdk\inc -DNTENV=1" stub.idl


C/C++-Compiler Considerations

The MIDL compiler must interoperate with the C compiler and C preprocessor. MIDL does not accept C++ syntax on input. The generated .h file has both C-styple and C++-style definitions for interfaces. The following topics describe the requirements for the C compiler.

  • C-Compiler Packing Issues
  • C-Compiler Definitions for Proxy/Stubs


C-Compiler Packing Issues

Packing levels affect the memory layout of types for both MIDL and the Microsoft C/C++ compiler in the same way. In Microsoft build environments, such as the build environment defined by VC++ or the Platform SDK, the default packing level for MIDL and C/C++ compilers is the same; the default packing level for the 32-bit and 64-bit Windows build environments is 8.

Natural Alignment

For types in memory, the default alignment is the same as its natural alignment.

  • A base type, such as short, float and __int64, and a pointer is aligned naturally if its representation starts at an address that is modulo its size. All the currently supported base types have sizes of 1, 2, 4 or 8. Pointers have a size of 4 in 32-bit environments and 8 in 64-bit environments.
  • A compound type is aligned naturally if each of its components is aligned naturally relative to the beginning of the type, and if there are no unnecessary gaps (padding) between components. Compound components, such as fields or elements, are recursed to pointer or base type components.

A simple rule to help remember this behavior is that the natural alignment of a type is equal to the biggest alignments of its components.

There is a connection between alignment and memory size of a type in languages like C or C++ and IDL as expressed by the operator sizeof(). The size is a multiple of the alignment (the minimal multiple spanning the type). This follows from an array representation in memory.

Natural alignment is important because accessing misaligned data may cause an exception on some systems. Data can be marked for a safe manipulation when misaligned, but typically that involves a speed penalty that may be substantial on some platforms.

Note In memory, objects of types with a natural alignment of n are guaranteed to be aligned properly when placed at addresses that are a multiple of n.

Packing versus Alignment

Specifying a packing level larger than the natural alignment of a type does not change the type alignment. Specifying a packing level smaller than the natural alignment reduces the type alignment to the packing level. As a result, the packed types may be placed in memory at addresses that are a multiple of the packing level (the reduced alignment) without causing a misalignment. This affects both simple types and component types. For compound types, the internal layout of the type may be affected, because the reduced alignment of the components may change the size of padding necessary for the proper alignment of the components, thus reducing the size of the type.

A simple rule to help remember this behavior is that the new alignment of a packed type is the smaller of the packing level and its natural alignment. The size of the type is a multiple of the new alignment. The sizeof() operator returns the reduced size for packed types.

For example, with packing level 2 a long becomes aligned at 2, and therefore may be placed at any even address, not only at the addresses that are a multiple of 4 as would be the case with natural alignment. A structure with a short and a long, packed at 2, does not need the internal gap between the short and the following long that was necessary for the natural alignment; hence, not only is the structure now aligned at 2, it also has its size reduced from 8 to 6.

As an example, consider a compound type consisting of a 1-byte character, an integer 4 bytes long, and a 1-byte character:

struct mystructtype
{
    char c1;  /* requires 1 byte  */
              /* 3 bytes of padding with natural alignment only */
    long l2;  /* requires 4 bytes */
    char c3;  /* requires 1 byte  */
              /* 3 bytes of padding with natural alignment only */
 } mystruct;

This structure is naturally aligned at 4 and has the natural size of 12.

For packing level 4 or greater, the structure mystruct is aligned at 4 and sizeof(struct mystructtype) is equal to 12. The structure will be misaligned if located in memory at an address that is not a multiple of 4.

For packing level 2, the structure is aligned at 2 and its size is 8. The structure packed with level 2 will be misaligned if located in memory at an address that is not a multiple of 2.

For packing level 1, the structure is aligned at 1 and its size is 6. The structure packed with level 1 can be placed anywhere without causing a misalignment fault.


C-Compiler Definitions for Proxy/Stubs

The header file Rpcproxy.h includes the following macro definitions, each of which may be convenient when building distributed COM application. These macros are invoked with the /D (or -D) preprocessor switch at the C-compile time.

MACRO | Description
REGISTER_PROXY_DLL | Generates DllMain, DllRegisterServer, and DllUnregisterServer functions for automatically registering a proxy DLL.
PROXY_CLSID=<clsid> | Specifies a class identifier for the server. If this macro is not defined, the default CLSID is the first interface identifier that the MIDL compiler encounters in the IDL specification for the Proxy/Stub server.
PROXY_CLSID_IS={0x8hexdigits, 0x4hexdigits,0x4hexdigits, {0x2hexdigits,0x2hexdigits, 0x2hexdigits,0x2hexdigits, 0x2hexdigits,0x2hexdigits, 0x2hexdigits,0x2hexdigits,}} | Specifies the value of the server's class identifier in binary hex format.

By defining the REGISTER_PROXY_DLL macro when compiling Dlldata.c, your proxy/stub marshaling DLL will automatically include default definitions for the DllMain, DllRegisterServer, and DllUnregisterServer functions. You can use these functions to self-register your proxy DLL in the system registry.

This default registration code uses the GUID of the first interface encountered as the CLSID for registering the entire proxy/stub DLL server. COM later uses this CLSID to locate and load the compiled proxy/stub server for the marshaling of any of the interfaces the server is registered to handle. When an application makes an interface method call that crosses thread, process, or computer boundaries, COM uses the interface identifier registry entry to locate the CLSID registry entry for the proxy/stub marshaling server. It then uses this CLSID to load the server (if it isn't already loaded) so that the interface call can then be marshaled.

Use the PROXY_CLSID=<clsid> macro when you want to explicitly specify the proxy/stub server's CLSID rather than rely on the default CLSID. For example, if you are building a standard marshaling DLL as your own in-process COM server, or if you need to define your own DllMain to handle DLL_PROCESS_ATTACH.

Use PROXY_CLSID_IS= macro instead of PROXY_CLSID to define the value of the CLSID in the binary hexadecimal format that the DEFINE_GUID macro uses.

Also note that when the default DllRegisterServer function runs, it registers the server with ThreadingModel=Both.

The following makefile example uses the REGISTER_PROXY_DLL and PROXY_CLSID= macros:

example.h example.tlb example_p.c example_i.c dlldata.c : example.idl
    midl example.idl
dlldata.obj : dlldata.c
    CL /c /DWIN32 /DREGISTER_PROXY_DLL dlldata.c
example.obj : example_p.c
    CL /c /DWIN32 /DREGISTER_PROXY_DLL \
    /DPROXY_CLSID=7a98c250-6808-11cf-b73b-00aa00b677a7
example_p.c
iids.obj : example_i.c
PROXYSTUBOBJS = dlldata.obj example.obj iids.obj
PROXYSTUBLIBS = kernel32.lib rpcndr.lib rpcns4.lib rpcrt4.lib uuid.lib
proxy.dll : $(PROXYSTUBOBJX) example.def
    link /dll /out:proxy.dll /def:example.def
        $(PROXYSTUBOBJS) $(ORIXYSTUBLIBS)
    regsvr32 /s proxy.dll

For more information on the /D preprocessor option, see your C compiler documentation.


Using the __midl Predefined Constant

When the MIDL compiler processes the input IDL and ACF files, __midl is defined by default and is used for conditional compilation to attain consistency throughout the build. This phases out the use of define statements in the header files, such as MIDL_PASS, and replaces them with a consistent flag. The value of the __midl constant indicates the compiler version major.minor according to the formula major * 100 + minor; for example MIDL ver. 6.0.x has the __midl defined as 600.

If you choose, you can override this default by specifying the following on the command line:

/U__midl

For more information, see /U.


MIDL and RPC

When you develop an RPC application, you use a text editor to create an IDL file that defines the interface between the client and the server. You use the MIDL compiler to generate source files that your client and server programs require. The following topics present information on the use of the MIDL compiler for RPC applications:

  • Files Generated for an RPC Interface
  • Targeting Stubs for Specific 32-bit or 64-bit Platforms

For more information, see Building RPC Applications.


Files Generated for an RPC Interface

The MIDL compiler generates the C-language stub and header files necessary to create the interface between the client application and the server application. The following topics describe each of the files generated for an RPC interface:

  • The Client Stub
  • The Server Stub
  • The Header File

For more information on defining and implementing an RPC interface see The Microsoft RPC Programmer's Guide and Reference.


The Client Stub

The client stub module provides surrogate entry points on the client for each of the operations defined in the input IDL file.

When the client application makes a call to the remote procedure, its call first goes to the surrogate routine in the client stub file. The client stub routine performs the following functions:

  • Marshals arguments. The client stub packages input arguments into a form that can be transmitted to the server.
  • Calls the client run-time library to transmit arguments to the remote address space and invokes the remote procedure in the server address space.
  • Unmarshals output arguments. The client stub unpacks output arguments and returns to the caller.

The MIDL compiler switches /client, /cstub, and /out affect the client stub file.


The Server Stub

The server stub provides surrogate entry points on the server for each of the operations defined in the input IDL file.

When a server stub routine is invoked by the RPC run-time library, it performs the following functions:

  • Unmarshals input arguments (unpacks the arguments from their transmitted formats).
  • Calls the actual implementation of the procedure on the server.
  • Marshals output arguments (packages the arguments into the transmitted forms).

The MIDL compiler switches /server, /sstub, and /out affect the server stub file.


The Header File

The header file contains definitions of all data types and operations declared in the IDL file, as well as all data types and operations declared in the files included with the #include directive. Data types from the files imported with the import directive are not replicated to the header file; instead the generated header file contains an include line to the H file generated from the imported file.. The header file must be included by all application modules that call the defined operations, implement the defined operations, or manipulate the defined types.

The MIDL compiler switches /header and /out affect the header file.


Targeting Stubs for Specific 32-bit or 64-bit Platforms

Some of the features of Microsoft RPC and the MIDL 3.0 and later compilers are platform-specific and intended for implementation in distributed applications that run only on Windows NT® 4.0 or Windows 2000. Some features are supported in Windows NT 3.51 and Windows® 95, as well as in later versions, but are not supported on older platforms.

As a precaution, the MIDL 3.0 and later compilers generate guards that facilitate compatibility checking during the C-compilation phase. MIDL generates two types of guards: a platform-dependent guard (32-bit versus 64-bit) and a release-dependent guard (feature set dependency). For example, MIDL generates the following guard to prevent C-compiling of a 32-bit stub for other platforms:

#if !defined(__RPC_WIN32__)
#error  Invalid build platform for this stub.
#endif

The release-dependent guard is triggered by a set of features found in the processed IDL file(s) and by the /target switch. For example, if the interface uses features supported only on Windows NT 4.0, Windows 2000, or later, MIDL generates a guard with the TARGET_IS_NT40_OR_LATER macro. If supported features require Windows NT 3.51 or Windows 95/98, MIDL generates a TARGET_IS_NT351_OR_WIN95_OR_LATER macro:

#if !(TARGET_IS_NT40_OR_LATER)
#error You need a Windows NT 4.0 or later to run this stub because it uses these eatures:
#error   -Oif or -Oicf.
#error However, your C/C++ compilation flags indicate you intend to run this app on earlier systems.
#error This app will die there with the RPC_X_WRONG_STUB_VERSION error.
#endif

Other guard macros that can be used are TARGET_IS_NT50_OR_LATER and TARGET_IS_NT351_OR_WIN95_OR_LATER macro. These macros, defined in Rpcndr.h, depend on the environment variables winver and _win32_winnt and are evaluated by the C/C++ compiler.

If, at C-compile time, you get an error message indicating that you need a specific platform to run a stub, first check to make sure you have not used a feature that is not available on this platform. The features triggering a particular guard are listed in the body of the guard. In the previous example, the -Oicf compiler switch triggered the guard. Notable features of this kind include the /robust switch and the [async] attribute available on Windows 2000 and later, the pipe type constructor, the /Oif compiler option, and the [user_marshal] and [wire_marshal] attributes available on Windows NT 4.0 and later. Stubs using these features will not run on earlier systems.

Also, the technology needed to use OLE and OLE Automation data types (for example, BSTR or STGMEDIUM) in remote operations is present only on Windows NT 4.0. Therefore, you cannot develop a custom interface that uses these data types in a remote procedure call to run on earlier platforms.

Note Feature sets evolve and grow differently on Windows NT/Windows 2000 than they do for Windows 95/98/Me. Review the description of the /target switch for exact mapping between the two product lines.

If you know that your target platform is correct for the features you are using and still receive an error, you may need to set the environment variables appropriately.

To build for Windows NT 3.51, Windows 95, or later releases

Add this line to your makefile:

CFLAGS = $(CFLAGS) -DWINVER=0x400

To build for Windows NT 4.0, Windows 2000, or later releases

Add this line to your makefile:

CFLAGS = $(CFLAGS) -D_WIN32_WINNT=0x400

Note that this target control is not in effect when you are building for MS-DOS®, 16-bit Windows, or Macintosh platforms.

To build for Windows 2000 or later releases

Add this line to your makefile:

CFLAGS = $(CFLAGS) -D_WIN32_WINNT=0x500

See Also

/target, /robust, async, async_uuid, /Oi, pipe, wire_marshal, user_marshal, and Marshaling OLE Data Types


MIDL and COM

All COM objects implement one or more interfaces. When you create a custom COM object, you must describe the interface or interfaces in an IDL file. The topics in this section present information on using MIDL to define COM interfaces:

  • Files Generated for a COM Interface
  • Marshaling OLE Data Types

For more information on defining COM interfaces with MIDL, see Defining COM Interfaces. For more information on building generated files for various platforms, see Targeting Stubs for Specific 32-bit or 64-bit Platforms.


Files Generated for a COM Interface

For COM interfaces, the MIDL compiler combines all client and object server auxiliary routines and data into a single interface proxy file. This file includes the surrogate entry points for both clients and servers. In addition, the MIDL compiler generates an interface header file, an interface UUID file and an interface registration file. You will use all these files when creating a proxy DLL that contains the code to support the use of the interface by both client applications and object servers. You will also use the interface header file and the interface UUID file when creating the executable file for a client application that uses the interface.

The following topics describe each of the files generated for a custom COM interface, which you identify by including the [object] attribute in the interface attribute list of the IDL file:

  • The Interface Proxy File
  • The Header Files
  • The Interface UUID File
  • The Interface Registration File

For more information, see Application Configuration File (ACF), /app_config, Interface Definition (IDL) File, and Building and Registering a Proxy DLL.


The Interface Proxy File

The interface proxy file (U_p.c) is a C file that contains routines equivalent to those in the client stub and server stub files of an object (COM) interface. This file contains implementations of the surrogate routines for client and server in the inline mode of the compiler or equivalent data and thunks in the interpreted modes, as well as other appropriate COM glue data, such as the proxy and stub Vtables.

The interface proxy file includes the supporting routines and data only for methods of the interfaces defined in the current IDL file. To clarify this behavior, an extended example is used throughout this section. When compiling an IDL file with an interface such as IFoo that inherits from IBar, IFoo related auxiliary data and routines are generated to the current proxy file, while the base interface IBar related auxiliary data and routines are found in the proxy generated from the IDL file containing the IBar definition. The compiler generates all data necessary to identify the surrogates of the base interface, and to delegate to them when needed to support the IBar methods used through IFoo interface.

For every method in an interface in the current IDL file, the proxy file contains two surrogate methods (or an equivalent interpreter data):

  • The client-side surrogate, such as IFoo_Method_Proxy in this example.

    This client-side surrogate is the virtual entry point to which the client, for example IFoo::Method, dispatches. It marshals the input arguments into a transmittable form, transmits the marshaled arguments along with information that identifies the interface and the operation, and then unmarshals the return value and any output arguments when the invoked operation returns.

  • The server-side surrogate, for example, IFoo_Method_Stub .

    This server-side surrogate is the virtual entry point that the underlying runtime dispatches to at the server to emulate the client. It unmarshals the input arguments to replicate the client data, invokes the server's implementation of the interface function, and then marshals and transmits the return value and any output arguments back to the client side.

The default name for a proxy file generated from a file.idl is file_p.c.Use the /proxy MIDL compiler switch to override the default name of the interface proxy file. The /env and /out switches affect this file.


The Header Files

The interface header file (Name.h) contains type definitions and function declarations based on the interface definition in the current IDL file, as well as all the data types and operations declared in the files included with the #include directive. Data types from the files imported with the import directive are not replicated to the header file; instead, the generated header file contains an include line to the H file generated from the imported file.

Include this file in the source files for the proxy DLL and for client applications that use the interface.

The default name for a header file generated from a file.idl is File.h. The /header MIDL compiler switch overrides the default name of the interface header file.


The Interface UUID File

The interface UUID file collects the definitions of the interface identifiers from all interfaces in the processed IDL file. Similar to the stub file and the header file, the input stream closure is defined by the current IDL file and the included files. For example, for Interface IFoo, the compiler generates a constant IID_IFoo and initializes it to the interface's UUID specified in the IDL file. Client applications and the proxy DLL use this constant to identify the interface.

The default name for an interface IID file generated from a file.idl is File_i.c. The /iid MIDL compiler switch overrides the default name of the interface UUID file.


The Interface Registration File

The interface registration file collects information that helps in the registration of COM interfaces packaged into a DLL or EXE file. The interface registration file is different from other generated files because it can gather information from compiling several different IDL files. Each MIDL compiler run for COM interfaces looks for an existing dlldata.c file first, and if the file is not found, a new dlldata.c file is created. If a dlldata.c file is found, information about the current IDL is added (if absent) or replaced.

The interface registration file is safely generated or updated in a multiprocessor environment because parallel MIDL compiles are prevented from writing to the file at the same time. Because any dlldata.c file can be marked as read-only by either the build environment or the user, the MIDL compiler implements a timeout approach to waiting on a file it cannot open, and issues an appropriate error message if the timeout expires.

The default name for the interface registration file generated from an input file is dlldata.c. The /dlldata MIDL compiler switch can be used to override the default name of the file. Overriding the default name of the interface registration file is especially useful when some IDL files packaged to a common binary reside in different directories.

See Also

Building and Registering a Proxy DLL


Marshaling OLE Data Types

To make it easier to use certain Automation and OLE data types, as well as some system handles frequently used in COM, typedefs for these data types and their related helper functions are available by importing Win32 IDL files and linking to the OLE and Automation DLL files. These files are automatically installed on your system with Microsoft Windows NT/Windows 2000 or with the DCOM package for Windows 9x on Windows 95/98/Me.

  • To use the BSTR data type in remote procedure calls, import the wtypes.idl file into your interface definition (IDL) file and link to Oleaut32.lib when building your distributed application. This will let your stubs use the ready-made helper functions BSTR_UserSize, BSTR_UserMarshal, BSTR_UserUnmarshal, and BSTR_UserFree.
  • To use other Automation data types, such as VARIANT and SAFEARRAY, or types that use those types (for example, DISPPARAMS and EXCEPINFO), import the objidl.idl file into your IDL file and link to the oleaut32.lib at build time. This will allow you to use the appropriate helper routines.
  • To use OLE data types (such as CLIPFORMAT, SNB, STGMEDIUM, ASYNC_STGMEDIUM), or system handles (such as HMETAFILE_PICT, HENHMETAFILE, HMETAFILE, HBITMAP, HPALETTE, and HGLOBAL), import the objidl.idl file into your interface definition file and link to the ole32.lib at build time.
  • The following OLE handles are also defined with the [wire_marshal] attribute, but only as handles within a computer since they cannot be used in remote procedure calls to other computers at this time: HWND, HMENU, HACCEL, HDC, HFONT, HICON, HBRUSH. Import the objidl.idl file into your IDL file and link to ole32.lib at build time to use these handles in interprocess communication on a single computer. The helper routines for these data types may change to include support for remote marshaling in a future release.

Note The technology needed to support these data types, namely the [wire_marshal] attribute support, is part of Windows NT 4.0 and later releases of the Windows NT product line, such as Windows 2000 and Whistler. This support is not present in Windows NT 3.51, Windows 95/98 (without the DCOM for Windows 9x package), or earlier versions of Windows. Therefore any application developed on Windows NT 4.0 or later that uses these data types in remote procedure calls will not run on an earlier platform. For DCOM based applications this is not an issue, since the DCOM release for Windows 95/98 includes this support. This restriction does not apply to type libraries generated with MIDL 3.0 or later for Automation/dual interfaces.

For more information, see The wire_marshal Attribute, The type_UserSize Function, The type_UserMarshal Function, The type_UserUnmarshal Function, The type_UserFree Function, and Targeting Stubs for Specific 32-bit or 64-bit Platforms.


MIDL and ODL

The Microsoft Interface Definition Language (MIDL) now includes the complete Object Definition Language (ODL) syntax. This allows you to use the 32-bit MIDL compiler instead of Mktyplib.exe to generate a type library and optional header files for a COM application.

Note When the documentation refers to an ODL file, it is referring to a file that Mktyplib.exe can parse. When it refers to an IDL file, it is referring to a file that the MIDL compiler can parse. This is strictly a naming convention. The MIDL compiler will parse an input file regardless of its file name extension.

The topics in this section discuss using the MIDL compiler and IDL files containing both IDL and ODL statements to generate type libraries:

  • Generating a Type Library With MIDL
  • Additional Files Required To Generate a Type Library
  • Differences Between MIDL and MkTypLib
  • ODL Language Features in MIDL
  • Generating a Proxy DLL and a Type Library From a Single IDL File


Generating a Type Library with MIDL

The top-level element of the ODL syntax is the library statement (library block). Every other ODL statement, with the exception of the attributes that are applied to the library statement, must be defined within the library block. When the MIDL compiler sees a library block, it generates a type library in much the same way that MkTypLib does. With a few exceptions, described in Differences Between MIDL and MKTYPLIB, the statements within the library block should follow the same syntax as in the ODL language and MkTypLib.

You can apply ODL attributes to elements that are defined either inside or outside the library block. These attributes have no effect outside the library block unless the element they are applied to is referenced from within the library block. Statements inside the library block can reference an outside element either by using it as a base type, inheriting from it, or by referencing it on a line as shown:

<some IDL definitions including definitions for interface IFace and struct bar>
[<some attributes>]
library a
{
    interface IFace;
    struct this_struct;
...
};

If an element defined outside the library block is referenced within the library block, then its definition will be put into the generated type library. The MIDL compiler treats the statements outside of a library block as a typical IDL file and parses those statements as it has always done. Normally, this means generating C-language stubs for an RPC application.

For more information about the general syntax for an ODL file see ODL File Syntax.


Additional Files Required to Generate a Type Library

In order to compile an IDL file that contains a library statement, the OLE and OLE Automation DLL files must be on your system. These files are automatically installed with Windows NT/Windows 2000™ or Windows® 95.

Effective with Windows NT 4.0, Oleaut32.dll supports a richer format for 32-bit type libraries. MIDL looks for this DLL on the build computer; if the new version is present, MIDL generates a new-format type library, otherwise it generates an old-format type library.


Differences Between MIDL and MkTypLib

There are a few key areas in which the MIDL compiler differs from MkTypLib. Most of these differences arise because MIDL is oriented more toward C-syntax than MkTypLib.

In general, you will want to use the MIDL syntax in your IDL files. However, if you need to compile an existing ODL file, or otherwise maintain compatibility with MkTypLib, use the /mktyplib203 MIDL compiler option to force MIDL to behave like Mkktyplib.exe, version 2.03. (This is the last release of the MkTypLib tool.) Specifically, the /mktyplib203 option resolves these differences:

  • typedef syntax for complex data types

    In MkTypLib, both of the following definitions generate a TKIND_RECORD for "this_struct" in the type library. The tag "struct_tag" is optional and, if used, will not show up in the type library.

    typedef struct struct_tag { ... } this_struct;
typedef struct { ... } that_struct;

    If an optional tag is missing, MIDL will generate it, effectively adding a tag to the definition supplied by the user. Since the first definition has a tag, MIDL will generate a TKIND_RECORD for "this_struct" and a TKIND_ALIAS for "this_struct" (defining "this_struct" as an alias for "struct_tag"). Because the tag is missing in the second definition, MIDL will generate a TKIND_RECORD for a mangled name, internal to MIDL, that is not meaningful to the user and a TKIND_ALIAS for "that_struct".

    This has potential implications for type library browsers that simply show the name of a record in their user interface. If you expect a TKIND_RECORD to have a real name, unrecognizable names could appear in the user interface. This behavior also applies to union and enum definitions, with the MIDL compiler generating TKIND_UNIONs and TKIND_ENUMs, respectively.

    MIDL also allows C-style struct, union, and enum definitions. For example, the following definition is legal in MIDL:

    struct my_struct { ... };
typedef struct my_struct your_struct;
  • Boolean data types

    In MkTypLib, the Boolean base type and the MkTypLib data type BOOL equate to VT_BOOL, which maps to VARIANT_BOOL, and which is defined as a short. In MIDL, the Boolean base type is equivalent to VT_UI1, which is defined as an unsigned char, and the BOOL data type is defined as a long. This leads to difficulties if you mix IDL syntax and ODL syntax in the same file while still trying to maintain compatibility with MkTypLib. Because the data types are different sizes, the marshaling code will not match what is described in the type information. If you want a VT_BOOL in your type library, you should use the VARIANT_BOOL data type.

  • GUID definitions in header files

    In MkTypLib, GUIDs are defined in the header file with a macro that can be conditionally compiled to generate either a GUID predefinition or an instantiated GUID. MIDL normally puts GUID predefinitions in its generated header files and GUID instantiations only in the file generated by the /iid switch.

The following differences in behavior cannot be resolved by using the /mktyplib203 switch:

  • Case sensitivity

    MIDL is case sensitive, OLE Automation is not.

  • Scope of symbols in an enum declaration

    In MkTypLib the scope of symbols in an enum is local. In MIDL, the scope of symbols in an enum is global, as it is in C. For example, the following code will compile in MkTypLib, but will generate a duplicate name error in MIDL:

    typedef struct { ... } a;
enum {a=1, b=2, c=3};
  • Scope of public attribute

    If you apply the public attribute to an interface block, MkTypLib treats every typedef inside that interface block as public. MIDL requires that you explicitly apply the public attribute to those typedefs that you want public.

  • Importlib search order

    If you import more than one type library, and if these libraries contain duplicate references, MkTypLib resolves this by using the first reference that it finds. MIDL will use the last reference that it finds. For example, given the following ODL syntax, library C will use the GOO typedef from library A if you compile with MkTypLib, and the GOO typedef from library B if you compile with MIDL:

    [...]library A
{
    typedef struct tagMOO
    {...}MOO
}

[...]library B
{
    typedef struct tagMOO
    {...} MOO
}

[...]library C
{
    importlib (A.TLB)
    importlib (B.TLB)
    typedef struct tagBAA
    {MOO y;}BAA
}

    The appropriate workaround for this is to qualify each such reference with the correct import library name, like this:

    typedef struct tagBAA
    {A.MOO y;}BAA
  • VOID data type not recognized

    MIDL recognizes the C-language void data type and does not recognize the OLE Automation VOID data type. If you have an ODL file that uses VOID, place this definition at the top of the file:

    #define VOID void
  • Exponential notation

    MIDL requires that values expressed in exponential notation be contained within quotation marks. For example, "-2.5E+3"

  • LCID values and constants

    Normally MIDL does not consider the LCID when parsing files. To force this behavior for a value, or if you need to use locale-specific notation when defining a constant, enclose the value or constant in quotation marks.

For more information, see /mktyplib203, /iid, and Marshaling OLE Data Types.


ODL Language Features in MIDL

The following topics list the Object Description Language (ODL) attributes, keywords, statements, and directives that are now part of the Microsoft Interface Definition Language (MIDL):

  • ODL Attributes
  • ODL Keywords, Statements, and Directives

ODL Attributes

[appobject] | [bindable]
[control] | default ]
[defaultvalue] | [displaybind]
[dllname] | [dual]
[entry] | [helpcontext]
[helpstring] | [helpfile]
[hidden] | [id]
[immediatebind] | [in]
[lcid] | [licensed]
[nonextensible] | [odl]
[oleautomation] | [optional]
[out] | [propget]
[propput] | [propputref]
[public] | [readonly]
[requestedit] | [restricted]
[retval] | [source]
[uuid] | [vararg]
[version] |

ODL Keywords, Statements, and Directives

coclass
dispinterface
enum
[importlib]
interface
library
module
struct
typedef
union

For information on how to marshal OLE Automation types, such as BSTR, VARIANT, and SAFEARRAY, see Marshaling OLE Data Types.


Generating a Proxy DLL and a Type Library from a Single IDL File

You can use a single IDL file to generate both the proxy stubs and header files for marshaling code, and a type library. You do this by defining an interface outside the library block and then referencing that interface from inside the library block, as shown in this example:

//file: AllKnown.idl

[
    object, uuid(. . .), <other interface attributes>
]
interface IKnown : IUnknown
{
    import "unknwn.idl";
    <declarations, etc. for IKnown interface go here>
};

[
    <library attributes>
]
library KnownLibrary
{

    //reference interface IKnown:
    interface IKnown;

    //or create a new class:
    [
        <coclass attributes>
    ]
    coclass KnowMore
    {
       interface IKnown;
    };
};

For more information, see Marshaling OLE Data Types and Additional Files Required To Generate a Type Library.


Interface Definitions and Type Libraries

This section presents information about how to create interface definition language (IDL) files and application configuration files (ACF) for MIDL, including reference pages for IDL and ACF attributes. There is also information about how to import files, type libraries, and system header files.

  • Interfaces in Distributed Objects
  • COM, DCOM, and Type Libraries
  • Interface Definition (IDL) File
  • IDL Attributes
  • Application Configuration File (ACF)
  • ACF Attributes
  • MIDL Data Types
  • Importing Files and Type Libraries
  • Importing System Header Files

For related information on creating COM interfaces, see Defining COM Interfaces. For information on creating RPC interfaces, see Developing the Interface and Data and Language Features.


Interfaces in Distributed Objects

In distributed computing, an interface is a collection of definitions and remote functions that enables two or more programs to interoperate between different contexts. In an RPC application, an interface specifies:

  • How client and server applications identify themselves to each other.
  • How data is transmitted between client and server.
  • Remote procedures that the client application can call.
  • Data types for the parameters and return values of the remote procedures.

The Microsoft® Interface Definition Language (MIDL) is for implementing interfaces used in distributed applications. With MIDL, an application can have one interface or many. Each interface specifies a unique distributed contract between the client and server programs. Applications based on remote procedure calls (RPC), Component Object Model (COM), and Distributed Component Object Model (DCOM) specify their interfaces using MIDL.

MIDL resembles C and C++ in many ways. For an overview of writing MIDL interfaces, see Developing the Interface.


COM, DCOM, and Type Libraries

Component Object Model (COM) and Distributed Component Object Model (DCOM) use Remote Procedure Calls (RPC) to enable distributed component objects to communicate with each other. Thus, a COM or DCOM interface defines the identity and external characteristics of a COM object. It forms the means by which clients can gain access to an object's methods and data. With DCOM, this access is possible regardless of whether the objects exist in the same process, different processes on the same machine, or on different machines. As with RPC client/server interfaces, a COM or DCOM object can expose its functionality in a number of different ways and through multiple interfaces.

Type Library

A type library (.tlb) is a binary file that stores information about a COM or DCOM object's properties and methods in a form that is accessible to other applications at runtime. Using a type library, an application or browser can determine which interfaces an object supports, and invoke an object's interface methods. This can occur even if the object and client applications were written in different programming languages. The COM/DCOM run-time environment can also use a type library to provide automatic cross-apartment, cross-process, and cross-machine marshaling for interfaces described in type libraries.

Characteristics of an Interface

You define the characteristics of an interface in an interface definition (IDL) file and an optional application configuration file (ACF):

  • The IDL file specifies the characteristics of the application's interfaces on the wire — that is, how data is to be transmitted between client and server, or between COM objects.
  • The ACF file specifies interface characteristics, such as binding handles, that pertain only to the local operating environment. The ACF file can also specify how to marshal and transmit a complex data structure in a machine-independent form.

For more information on IDL and ACF files, see The IDL and ACF Files.

The IDL and ACF files are scripts written in Microsoft® Interface Definition Language (MIDL), which is the Microsoft implementation and extension of the OSF-DCE interface definition language (IDL). The Microsoft extensions to the IDL language enable you to create COM interfaces and type libraries. The compiler, Midl.exe, uses these scripts to generate C-language stubs and header files as well as type library files.

The MIDL Compiler

Depending on the contents of your IDL file, the MIDL compiler will generate any of the following files.

A C-language proxy/stub file, an interface identifier file, a DLL data file, and a related header file for a custom COM interface. The MIDL compiler generates these files when it encounters the object attribute in an interface attribute list. For more detailed information on these files, see Files Generated for a COM Interface.

A compiled type library (.tlb) file and related header file. MIDL generates these files when it encounters a library statement in the IDL file. For general information about type libraries, see Contents of a Type Library, in the Automation Programmer's Reference.

C/C++-language client and server stub files and related header file for an RPC interface. These files are generated when there are interfaces in the IDL file that do not have the object attribute. For an overview of the stub and header files, see General Build Procedure. For more detailed information, see Files Generated for an RPC Interface.


Interface Definition (IDL) File

By convention, the file that contains interface and type library definitions is called an IDL file, and has an .idl file name extension. In reality, the MIDL compiler will parse an interface definition file regardless of its extension. An interface is identified by the keyword interface.

Each interface consists of a header and a body. The interface header contains attributes that apply to the entire interface. The body of the interface contains the remaining interface definitions. For an overview of interfaces and IDL files, see The Interface Definition Language (IDL) File. For a summary of attributes that can be used in an interface header, see IDL Attributes.


Data Types in the Interface Body

The interface body, which is enclosed in braces ({ }), contains the data types that will be used in remote procedure calls and prototypes for the functions that will be executed remotely. An interface body can contain imports, pragmas, constant declarations, type declarations, and function declarations. Except in OSF-compatibility mode, the MIDL compiler also allows implicit declarations in the form of variable definitions.

Note that the OSF-DCE specification for RPC interfaces does not allow multiple interfaces in a single IDL file. Therefore, if you are compiling in MIDL's OSF-compatibility mode (/osf), your IDL file can contain only one interface.

For details on using the MIDL compiler to produce type libraries, see Generating a Type Library with MIDL.

In Microsoft® RPC, an IDL file can contain multiple interfaces and these interfaces can be forward declared (within the IDL file that defines them). For example:

interface ITwo; //forward declaration
interface IOne
{
...uses ITwo...
}
interface ITwo
{
...uses IOne...
}


Type Definitions, Construct Declarations, and Imports

Type definitions, construct declarations, and imports can occur outside of the interface body. All definitions from the main IDL file will appear in the generated header file, and all the procedures from all the interfaces in the main IDL file will generate stub routines. This enables applications that support multiple interfaces to merge IDL files into a single, combined IDL file.

As a result, it requires less time to compile the files and also allows MIDL to reduce redundancies in the generated stubs. This can significantly improve object interfaces through the ability to share common code for base interfaces and derived interfaces. For non-object interfaces, the procedure names must be unique across all the interfaces. For object interfaces, the procedure names need to be unique only within an interface. Note that multiple interfaces are not permitted when you use the /osf switch.

Declarative Constructs

The syntax for declarative constructs in the IDL file is similar to that for C. MIDL supports all Microsoft C/C++ declarative constructs except the following:

  • Older style declarators that allow a declarator to be specified without a type specifier, such as:
    x (y)
short x (y)
  • Declarations with initializers (MIDL only accepts declarations that conform to the MIDL const syntax).

The import keyword specifies the names of one or more IDL files to import. The import directive is similar to the C include directive, except that only data types are assimilated into the importing IDL file.

Constant Declaration

The constant declaration specifies Boolean, integer, character, wide-character, string, and void * constants. For more information, see const.

General Declaration

A general declaration is similar to the C typedef statement with the addition of IDL type attributes. Except in /osf mode, the MIDL compiler also allows an implicit declaration in the form of a variable definition.

Function Declaration

The function declarator is a special case of the general declaration. You can use IDL attributes to specify the behavior of the function return type and each of the parameters.

Examples

[
    uuid(12345678-1234-1234-1234-123456789ABC),
    version(3.1),
    pointer_default(unique)
]
interface IdlGrammarExample
{
    import "windows.idl", "other.idl";
    const wchar_t * NAME = L"Example Program";
    typedef char * PCHAR;

    HRESULT DictCheckSpelling(
        [in, string] PCHAR   word,     // word to look up
        [out]        short * isPresent // 0 if not present
    );
}


IDL Attributes

Attributes are keywords that specify the characteristics of an interface and of the data and methods within that interface. The set of attributes that applies to a single interface is enclosed in square brackets ([ ]). The following topics present the categories of attributes that can be used in an IDL file.

  • Field Attributes
  • Aliasing and Marshaling Attributes
  • Asynchronous Attributes
  • Array and Sized-Pointer Attributes
  • Data Type Attributes
  • Directional Attributes
  • Function Call Attributes
  • Interface Header Attributes
  • Performance Attributes
  • Pointer Type Attributes
  • Structure and Union Attributes
  • Type Library Attributes


Aliasing and Marshaling Attributes

Distributed applications almost always pass data between client and server programs when they call interface procedures. Developers use MIDL to describe the data that client and server programs pass in a standard way. The MIDL compiler creates application stub, or proxy, programs for the client and the server that convert the data into a standardized form that can be sent over a network. This format, the Network Data Representation (NDR) format, is often called the wire format of the data. The stubs must convert data from its native format in the program's memory space to NDR. This conversion is termed marshaling the data. When a client or server program receives data, it must convert the data from NDR to the native format for that program. This is called unmarshaling the data.

Use aliasing and marshaling attributes to control how your data is packaged into NDR format and transmitted over the network.

Attribute | Usage
call_as | Maps a nonremotable function to a remote procedure call.
iid_is | Provides the interface identifier of the COM interface that is the object of the pointer.
transmit_as | Converts a data type to a simpler type for transmission over a network.
wire_marshal | Similar to transmit_as but you implement the routines to size, marshal, unmarshal, and free the data.

See Also

Type Conversion and Marshaling ACF Attributes


Asynchronous Attributes

When a program invokes a procedure in an interface, the procedure may execute synchronously or asynchronously. A synchronous procedure causes the calling program to wait until the procedure returns before the program can proceed. An asynchronous procedure returns immediately without waiting for results. The calling program must later resynchronize with the interface procedure to receive data. For more information, see Asynchronous RPC.

You can use the following attributes to provide support for asynchronous remote procedure calls.

Attribute | Usage
async | When applied to a function parameter, defines a handle that allows the caller to make an asynchronous call and return immediately without waiting for results, and later resynchronize with the called function to receive data after the call completes. The async attribute is also used in ACF files to define an asynchronous handle for a procedure or an entire interface.
async_uuid | Directs the MIDL compiler to define both synchronous and asynchronous versions of a COM interface.
maybe | The client making this remote procedure call does not expect any response indicating delivery or completion of the call, and delivery is not guaranteed. This is in contrast to message operations where no response is expected but the delivery is guaranteed.
message | The remote procedure call is to be treated as an asynchronous message from the client to the server. The client makes the call and returns immediately, while the actual call is handled by the message-queuing transport (ncadg_mq).


Array and Sized-Pointer Attributes

MIDL provides a rich set of features for passing arrays of data and pointers to data. You can use these attributes to specify characteristics of arrays and multiple levels of pointers.

Attribute | Usage
size_is | Specifies the amount of memory to be allocated for sized pointers, sized pointers to sized pointers, and single- or multidimensional arrays.
max_is | The maximum value for an array index.
length_is | The number of array elements to be transmitted.
first_is | The index of the first array element to be transmitted.
last_is | Gives the index of the last array element to be transmitted.
string | Indicates that the one-dimensional char, wchar_t, byte (or equivalent) array, or the pointer to such an array, is to be handled as a string.
range | Specifies a range of allowable values for arguments or fields whose values are set at runtime.

MIDL supports three kinds of pointers: reference pointers, unique pointers, and full pointers. These pointers are specified by the pointer attributes ref, unique, and ptr.

A pointer attribute can be applied as a type attribute; as a field attribute that applies to a structure member, union member, or parameter; or as a function attribute that applies to the function return type. The pointer attribute can also appear with the pointer_default keyword.

To allow a pointer parameter to change in value during a remote function, you must provide another level of indirection by supplying multiple pointer declarators. The explicit pointer attribute applied to the parameter affects only the rightmost pointer declarator for the parameter. When there are multiple pointer declarators in a parameter declaration, the other declarators default to the pointer attribute specified by the pointer_default attribute. To apply different pointer attributes to multiple pointer declarators, you must define intermediate types that specify the explicit pointer attributes.

Default Pointer-Attribute Values

When no pointer attribute is associated with a pointer that is a parameter, the pointer is assumed to be a ref pointer.

When no pointer attribute is associated with a pointer that is a member of a structure or union, the MIDL compiler assigns pointer attributes using the following priority rules (1 is highest):

  1. Attributes explicitly applied to the pointer type
  2. Attributes explicitly applied to the pointer parameter or member
  3. Pointer_default attribute in the IDL file that defines the type
  4. Pointer_default attribute in the IDL file that imports the type
  5. Ptr (osf mode); unique (Microsoft® RPC default mode)

When the IDL file is compiled in default mode, imported files can inherit pointer attributes from importing files. This feature is not available when you compile using the /osf switch. For more information, see import.

Function Return Types

A pointer returned by a function must be a unique pointer or a full pointer. The MIDL compiler reports an error if a function result is a reference pointer, either explicitly or by default. The returned pointer always indicates new storage.

Functions that return a pointer value can specify a pointer attribute as a function attribute. If a pointer attribute is not present, the function-result pointer uses the value provided as the pointer_default attribute.

Pointer Attributes in Type Definitions

When you specify a pointer attribute at the top level of a typedef statement, the specified attribute is applied to the pointer declarator, as expected. When no pointer attribute is specified, pointer declarators at the top level of a typedef statement inherit the pointer attribute type when used.

DCE IDL does not allow the same pointer attribute to be explicitly applied twice—for example, in both the typedef declaration and the parameter attribute list. When you use the default (Microsoft extensions) mode of the MIDL compiler, this constraint is relaxed.

For a discussion of using MIDL arrays and pointers in remote procedure calls, see Arrays and Pointers.


Data Type Attributes

You can apply these attributes to data types in a typedef statement to further define the usage or effect of the data type.

Attribute | Usage
context_handle | Identifies a binding handle that maintains state (context) information on a particular server between remote procedure calls from a particular client. Not valid for object interface functions.
handle | Specifies a custom handle type specific to the application.
ms_union | Controls the NDR alignment of nonencapsulated unions. Use on typedefs for backward compatibility with interfaces built with MIDL 1.0 or 2.0.
pipe | Allows transmission of an open-ended stream of typed data across a remote procedure call. An in pipe parameter allows the server to pull the data stream from the client during a remote procedure call. An out pipe parameter allows the server to push the data stream back to the client.
transmit_as | Specifies how a data type will be transmitted over a network, used for custom marshaling.
v1_enum | Directs that the specified enumerated type be transmitted as a 32-bit entity, rather than the 16-bit default.
wire_marshal | Similar to transmit_as but you implement the routines to size, marshal, unmarshal, and free the data.


Directional Attributes

Apply directional attributes to parameters to indicate the direction that data is being passed. Both attributes can be applied to a single parameter, but doing so increases the overhead associated with a call.

Attribute | Usage
in | The parameter is being passed from the caller to the called function.
out | The parameter is being passed from the called function to the caller.


Function Call Attributes

Programs can use these attributes on individual functions within the interface, and affect only that function.

Attribute | Usage
message | The remote procedure call is to be treated as an asynchronous message from the client to the server. The client makes the call and returns immediately, while the actual call is handled by the message-queuing transport (ncadg_mq).
maybe | The client making this remote procedure call does not expect any response indicating delivery or completion of the call. This is in contrast to message operations where no response is expected but the delivery is guaranteed.
broadcast | The remote procedure call is to be sent to all of the servers on the network. The client accepts the first return, subsequent replies from other servers are discarded.
idempotent | The call does not change state and returns the same information each time it is called with the same input parameters.
callback | Designates a function that resides in the client application, which the server can call to obtain information from the client.
call_as | Maps a nonremotable function to a remote procedure call.
local | Designates a local procedure for which MIDL does not generate stub code. Not valid for object interface functions.

On non-object interfaces, you can also apply the string, ptr, and context_handle attributes to a function to specify characteristics of the return value.


Interface Header Attributes

Incorporate these attributes in the interface header to convey information about the entire interface.

Attribute | Usage
async_uuid | Directs the MIDL compiler to define both synchronous and asynchronous versions of a COM interface.
uuid | Designates a 128-bit value that distinguishes a particular interface from all others. The actual value may represent a GUID, a CLSID, or an IID.
local | Directs the MIDL compiler to generate header files only. An interface must have either a uuid or a local attribute.
ms_union | Controls the NDR alignment of nonencapsulated unions. Use for backward compatibility with interfaces built on MIDL 1.0 or 2.0.
object | Identifies the interface as a COM interface and directs the MIDL compiler to generate proxy/stub code instead of RPC client and server stubs.
version | Identifies a particular version of an interface in cases where multiple versions of the interface exist. Because COM interfaces are immutable, you cannot use the version attribute on an object interface.
pointer_default | Specifies the default pointer type for all pointers except for those included in parameter lists. The default type can be unique, ref, or ptr.
endpoint | Specifies a static (well-known) endpoint on which a server application will listen for remote procedure calls.

See Type Library Attributes for interface attributes, such as dual and oleautomation, that are specific to interfaces defined or referenced inside a library statement.


Performance Attributes

Use the following attributes in an IDL file to reduce the size of the stub code or otherwise improve performance.

Attribute | Usage
ignore | Designates that a pointer contained in a structure or union and the object indicated by the pointer is not to be transmitted.
local | Designates a function that is local to the application for which MIDL does not need to generate stub code.
wire_marshal | Defines a data type as a simpler type for transmission over a network and allows you to implement marshaling and unmarshaling routines for the type.

See Also

Memory Management ACF Attributes, Stub Optimization ACF Attributes


Pointer Type Attributes

The following attributes specify the characteristics of pointers.

Attribute | Usage
ptr | Designates a pointer as a full pointer, with all the capabilities of a C-language pointer, including aliasing.
ref | Designates the simplest type of pointer in MIDL—one that simply provides the address of some data. Reference pointers can never be null.
unique | Lets a pointer be null, but does not support aliasing.
pointer_default | Applied to an interface to specify the default pointer type for all pointers in that interface, except for top-level parameter pointers, which automatically default to ref pointers.
iid_is | Provides the interface identifier of the COM interface that is the object of the pointer.
string | Specifies that the pointer points to a string.


Structure and Union Attributes

Use the switch_* attributes to specify the characteristic of a union in a remote procedure call. Use the ignore attribute to designate certain structure or union members as local to the client application.

Attribute | Usage
switch | Selects the discriminant for an encapsulated union.
switch_is | Identifies the discriminant for a nonencapsulated union.
switch_type | Identifies the type of the discriminant for a nonencapsulated union.
ignore | Designates that a pointer contained in a structure or union and the object indicated by the pointer is not to be transmitted.

You can also use the array and sized pointer attributes to specify characteristics of structure or union members.


Type Library Attributes

The following keywords specify type library information within the context of a library statement in an IDL file.

Attribute | Usage
aggregatable | Defines the coclass as supporting objects that can directly expose another object's interface pointer.
appobject | Identifies the coclass as an application object, which is associated with a full EXE application.
bindable | Indicates that the property supports data binding. This allows the client to be notified whenever a property has changed value.
coclass | Provides a listing of the supported interfaces for a component object.
control | Identifies a coclass or library as a COM control, from which a container site will derive additional type libraries or component object classes.
custom | Defines a custom attribute (one not defined in MIDL).
default | Indicates that the interface or dispinterface, defined within a coclass, represents the default interface.
defaultbind | Indicates the single, bindable property that best represents the object.
defaultcollelem | Flags the property as an accessor function for an element of the default collection. Used for Microsoft® Visual Basic® code optimization.
defaultvalue | Allows specification of a default value for a typed optional parameter.
defaultvtable | Allows an object to have two different source interfaces.
dispinterface | Defines a set of properties and methods on which you can call IDispatch::Invoke.
displaybind | Indicates a property that should be displayed to the user as bindable.
dllname(str) | Defines the name of the DLL that contains the entry points for a module.
dual | Identifies an interface that exposes properties and methods both through IDispatch and directly through the Vtable.
entry | Specifies an exported function or constant in a module by identifying the entry point in the DLL.
helpcontext | Specifies a context identifier that lets the user view information about this element in the Help file.
helpfile | Sets the name of the Help file for a type library.
helpstring | Specifies a character string that is used to describe the element to which it applies.
helpstringdll | Sets the name of the DLL to use to perform the document string lookup.
hidden | Indicates that the item exists but should not be displayed in a user-oriented browser.
id | Specifies a DISPID for a member function (either a property or a method, in an interface or dispinterface).
immediatebind | Indicates that the database will be notified immediately of all changes to a property of a data-bound object.
lcid | When applied to the library statement, along with a localeID argument, identifies the locale for a type library or for a function argument and lets you use international characters inside the library block. Within a library statement, from the point where the lcid attribute is used, MIDL will accept input localized according to the specified locale.
library | Instructs the MIDL compiler to generate type library information for the interfaces and classes referenced inside the statement.
licensed | Indicates that the coclass to which it applies is licensed, and instances must be created using IClassFactory2.
nonbrowsable | Indicates that the property appears in an object browser (which does not show property values), but does not appear in a properties browser (which does show property values).
noncreatable | Prevents a client from using the default class factory to create instances of an object interface.
nonextensible | Specifies that the IDispatch implementation includes only the properties and methods listed in the interface description and cannot be extended with additional members at runtime.
oleautomation | Indicates that an interface is compatible with automation.
optional | Specifies an optional parameter for a member function.
propget | Specifies a property accessor function.
propput | Specifies a property-setting function.
propputref | Specifies a property-setting function that uses a reference instead of a value.
public | Ensures that an alias declared with typedef becomes part of the type library.
readonly | Prohibits assigning a new value to a variable.
requestedit | Indicates that the property supports the OnRequestEdit notification.
restricted | Specifies that a library, or member of a module, interface, or dispinterface cannot be called arbitrarily.
retval | Designates the parameter that receives the return value of the member.
source | Indicates that a member of a coclass, property, or method is a source of events.
string | Indicates that the one-dimensional char, wchar_t, byte (or equivalent) array or the pointer to such an array must be treated as a string.
uidefault | Indicates that the type information member is the default member for display in the user interface.
usesgetlasterror | Specifies that a module entry point uses SetLastError to return error codes and that a caller can then call GetLastError to retrieve the error code if there is an error on entering a function.
uuid | Designates a unique identifier for a type library, coclass, or interface.
vararg | Specifies that the function takes a variable number of arguments.
version | Identifies a particular version of a type library.

See Also

ODL File Syntax, ODL File Example, Generating a Type Library With MIDL, Differences Between MIDL and MKTYPLIB


Application Configuration File (ACF)

There may be aspects of your distributed application that affect one component, but have nothing to do with another component. For example, an object may contain a large, complex data structure and pass the contents of this data structure to another object. The exact layout of this data structure may be meaningless to the receiving application. Also, the structure may contain data types that the MIDL compiler does not recognize and cannot generate marshaling and unmarshaling code. Client applications may share the same interface but run on different platforms; they may each need their own set of marshaling routines. Finally, individual clients may not always need the same set of functions. It's inefficient to generate stub code for functions that will never be implemented in a particular client application.

By defining these local aspects of your interface in an application configuration file (ACF), you can separate the differences between the client interfaces from their network representation, allowing the server to send and receive data in a consistent format, and making your stub code more compact and efficient.

The structure and syntax of an ACF interface definition are identical to the IDL definition:

[ interface-attribute-list] interface interface-name {. . .}

By default, the ACF interface name must match its name in the IDL definition. However, when you use the MIDL compiler option /acf to explicitly specify an ACF file name, the interface names do not have to match. This feature allows several interfaces to share a single ACF specification.


ACF Attributes

This section categorizes the ACF attributes and describes their use, in the following topics:

  • Binding ACF Attributes
  • Stub Optimization ACF Attributes
  • Type-Conversion and Marshaling ACF Attributes
  • Memory Management ACF Attributes
  • Error and Exception Handling ACF Attributes
  • Using ACF Attributes in an IDL File


Binding ACF Attributes

Specify how the client connects to the server for remote procedure calls with the attributes listed in the following table.

Attribute | Usage
async | Defines a handle that allows the caller to make an asynchronous call and return immediately without waiting for results, and then resynchronize with the called function to receive data after the call completes.
auto_handle | Tells MIDL to let the stub code control the binding automatically. This is the default if you don't specify any binding handle.
context_handle_noserialize | Guarantees that a context handle will never be serialized, regardless of the application's default behavior.
context_handle_serialize | Guarantees that a context handle will always be serialized, regardless of the application's default behavior
explicit_handle | Lets the client application control the binding with an explicit parameter in each procedure.
implicit_handle | Specifies a handle for procedures that do not have an explicit handle parameter. The client application still controls the binding.
strict_context_handle | Guarantees that the methods in the interface will only accept context handles that were created by a method of that interface.


Stub Optimization ACF Attributes

These attributes enable you to optimize the size and speed of your stub code.

Attribute | Usage
code nocode | Use the code and nocode attributes together to avoid generating stub code for unused functions. Apply the nocode attribute to the interface header, and apply the code attribute to those procedures that the client application will implement. Client stub code will be generated only for the selected procedures.
optimize | Lets you fine-tune the level of optimization that the MIDL compiler performs when generating stub code, by specifying that data is to be marshaled by either the mixed-mode or interpreted method. You can apply the optimize attribute to an interface or to selected functions within the interface. In either case, its use will override the command-line optimizations and any pre-existing defaults.


Type-Conversion and Marshaling ACF Attributes

Use these attributes to control how your data is transmitted over the network.

Attribute | Usage
encode decode | Instructs MIDL to expose the type or procedure serialization (pickling) routines it generates for the stubs. Your client application can call those routines to marshal data by value.
represent_as | Specifies how a data type will be represented on the wire, when the exact nature of a client's data type is unimportant to the server (because it only needs the data itself and not the actual structure), or the actual client type is unknown to MIDL at compile time. For example, if your client application uses a linked list of floating-point numbers, you could specify that the wire-representation of that list be an array of type float.
user_marshal | Controls how data is transmitted over the wire by implementing your own marshaling routines. This attribute is useful if you have a data type that is unknown to MIDL or if you are passing information between big-endian and little-endian platforms.

The DCE marshaling attributes in_line and out_of_line are not implemented in Microsoft RPC. The MIDL compiler automatically marshals complex data types out-of-line.


Memory Management ACF Attributes

The attributes listed in the following table enable you to perform memory management from the client side.

Attribute | Usage
allocate | Specifies the way the client application and stub allocate and release memory for pointers. This attribute is particularly useful when you want certain pointer structures to remain accessible to the server application after the remote procedure call returns to the client. You can also use the allocate attribute to direct the stub to compute the size of all memory referenced through the pointer of the specified type and to make a single call to midl_user_allocate.
byte_count | Enables you to create a persistent, contiguous block of memory that can be reused over multiple remote procedure calls. This frees the client application from the overhead of repeatedly allocating and releasing memory that may include multiple pointers and other complex data structures.
enable_allocate | Specifies that the server stub code should enable the stub memory-management environment.


Error and Exception Handling ACF Attributes

Use the following attributes for error handling.

Attribute | Usage
comm_status fault_status | Let your client application handle exceptions gracefully by causing communication and server errors to be returned to the client as parameter values. The client application can then call the RPC run-time function DceErrorInqText to relay an error message to the user.

See Also

Importing Files and Type Libraries


Using ACF Attributes in an IDL File

You can use the /app_config MIDL compiler option to specify binding handle attributes in the IDL file rather than in a separate ACF file. Specifically, you can apply the auto_handle, implicit_handle, and explicit_handle attributes to the header of an RPC interface in an IDL file. Consider using this option if your RPC application doesn't require other ACF attributes, and if you don't require strict OSF-DCE compatibility.


MIDL Data Types

MIDL provides a plethora of data types and language constructs for creating data types. Both are discussed in the following topics:

  • MIDL Base Types
  • MIDL Arrays
  • MIDL Type Definitions
  • MIDL Enumerated Types
  • MIDL Structures
  • MIDL Unions
  • MIDL Binding Handles


MIDL Base Types

To be transmitted over a network, all data types must resolve to a MIDL base type or predefined type. This section presents the predefined and base types that MIDL defines:

  • MIDL Predefined and Base Types
  • Signed vs. Unsigned Types
  • Other MIDL Data Types


MIDL Predefined and Base Types

MIDL supports the following base and predefined types.

Data type | Description | Default sign
Boolean | 8 bits. Not compatible with oleautomation interfaces; use VARIANT_BOOL instead. | Unsigned
byte | 8 bits. | (not applicable)
char | 8 bits. | Unsigned
double | 64-bit floating point number. | (not applicable)
error_status_t | 32-bit unsigned integer for returning status values for error handling. | Unsigned
float | 32-bit floating point number. | (not applicable)
handle_t | Primitive handle type for binding. | (not applicable)
hyper | 64-bit integer. | Signed
int | 32-bit integer. On 16-bit platforms, cannot appear in remote functions without a size qualifier such as short, small, long or hyper. | Signed
__int32 | 32-bit integer. Equivalent to long. |
__int3264 | An integer that is 32-bit on 32-bit platforms, and is 64-bit on 64-bit platforms. | Signed
__int64 | 64-bit integer. Equivalent to hyper. |
long | 32-bit integer. | Signed
short | 16-bt integer. | Signed
small | 8-bit integer. | Signed
void | Indicates that the procedure does not return a value. | (not applicable)
void * | 32-bit pointer for context handles only. | (not applicable)
wchar_t | 16-bit predefined type for wide characters. | Unsigned


Signed vs. Unsigned Types

Compilers that use different defaults for signed and unsigned types can cause software errors in your distributed application. You can avoid these problems by explicitly declaring your character types as signed or unsigned. Note that DCE IDL compilers do not recognize the keyword signed. Therefore, this feature is not available when you use the MIDL compiler /osf switch.

MIDL defines the small type to take the same default sign as the char type in the target C compiler. If the compiler assumes that char is unsigned, small will also be defined as unsigned. Many C compilers let you change the default as a command-line option. For example, in the Microsoft® Visual C++® development environment, the /J command-line option changes the default sign of char from signed to unsigned.

You can also control the sign of variables of type char and small with the MIDL compiler command-line switch /char. This switch allows you to specify the default sign used by your compiler. The MIDL compiler explicitly declares the sign of all char types that do not match your C-compiler default type in the generated header file.


Other MIDL Data Types

MIDL recognizes a number of COM and Automation data types, such as BSTR, VARIANT, and SAFEARRAY, and COM handles, such as HMETAFILE_PICT, HENHMETAFILE, HMETAFILE, HBITMAP, HPALETTE, and HGLOBAL. For more information, including the names of the import files needed to use these types, see Marshaling OLE Data Types.


MIDL Arrays

Array declarators appear in the interface body of the IDL file as one of the following:

  • Part of a general declaration
  • A member of a structure or union declarator
  • A parameter to a remote procedure call

The syntax for the general form of a MIDL array is described in arrays.

The bounds of each dimension of the array are expressed inside a separate pair of square brackets. An expression that evaluates to n signifies a lower bound of zero and an upper bound of n – 1. If the square brackets are empty or contain a single asterisk (*), the lower bound is zero and the upper bound is determined at runtime.

The array can also contain two values separated by an ellipsis that represent the lower and upper bounds of the array, as in [lower...upper]. Microsoft RPC requires a lower bound of zero. The MIDL compiler does not recognize constructs that specify nonzero lower bounds.

Arrays can be associated with the field attributes size_is, max_is, length_is, first_is, and last_is to specify the size of the array or the part of the array that contains valid data. These field attributes identify the parameter, structure field, or constant that specifies the array dimension or index.

The array must be associated with the identifier specified by the field attribute in the following way: When the array is a parameter, the identifier must also be a parameter to the same function; when the array is a structure field, the identifier must be another structure field of that same structure.

An array is called "conformant" if the upper bound of any dimension is determined at runtime.(Only upper bounds can be determined at runtime.) To determine the upper bound, the array declaration must include a size_is or max_is attribute.

An array is called "varying" when its bounds are determined at compile time, but the range of transmitted elements is determined at runtime. To determine the range of transmitted elements, the array declaration must include a length_is, first_is, or last_is attribute.

A conformant varying array (also called "open") is an array whose upper bound and range of transmitted elements are determined at runtime. At most, one conformant or conformant varying array can be nested in a C structure and must be the last element of the structure. In contrast, nonconformant varying arrays can occur anywhere in a structure.

Examples

/* IDL file interface body */
#define MAX_INDEX 10

typedef char  ATYPE[MAX_INDEX];
typedef short BTYPE[];        // Equivalent to [*];
typedef long  CTYPE[*][10];   // [][10]
typedef float DTYPE[0..10];   // Equivalent to [11]
typedef float ETYPE[0..(MAX_INDEX)];

typedef struct
{
    unsigned short size;
    unsigned short length;
    [size_is(size), length_is(length)] char string[*];
} counted_string;

HRESULT MyFunction(
     [in, out] short * pSize,
     [in, out, string, size_is(*pSize)] char a[0..*]
);

For more information, see Arrays and Pointers.

Multidimensional Arrays

The user can declare types that are arrays and then declare arrays of objects of such types. The semantics of m-dimensional arrays of n-dimensional array types are the same as the semantics of m+n-dimensional arrays.

For example, the type RECT_TYPE can be defined as a two-dimensional array and the variable rect can be defined as an array of RECT_TYPE. This is equivalent to the three-dimensional array equivalent_rect:

typedef short int RECT_TYPE[10][20];
RECT_TYPE rect[15];
short int equivalent_rect[15][10][20];  // ~RECT_TYPE rect[15]

Microsoft RPC is C oriented. Following C-language conventions, only the first dimension of a multidimensional array can be determined at runtime. Interoperation with DCE IDL arrays that support other languages is limited to:

  • Multidimensional arrays with constant (compile-time-determined) bounds.
  • Multidimensional arrays with all constant bounds except the first dimension. The upper bound and range of transmitted elements of the first dimension are dependent on runtime.
  • Any one-dimensional arrays with a lower bound of zero.

When the [string] attribute is used on multidimensional arrays, the attribute applies to the rightmost array.

Arrays of Pointers

Reference pointers must point to valid data. The client application must allocate all memory for an [in] or [in, out] array of reference pointers, especially when the array is associated with [in], or [in, out], [length_is], or [last_is] values. The client application must also initialize all array elements before the call. Before returning to the client, the server application must verify that all array elements in the transmitted range point to valid storage.

On the server side, the stub allocates storage for all array elements, regardless of the [length_is] or [last_is] value at the time of the call. This feature can affect the performance of your application.

No restrictions are placed on arrays of unique pointers. On both the client and the server, storage is allocated for null pointers. When pointers are non-null, data is placed in preallocated storage.

An optional pointer declarator can precede the array declarator.

When embedded reference pointers are [out]-only parameters, the server-manager code must assign valid values to the array of reference pointers. For example:

typedef [ref] short * ARefPointer;
typedef ARefPointer ArrayOfRef[10];
HRESULT proc1( [out] ArrayOfRef Parameter );

The generated stubs allocate the array and assign null values to all pointers embedded in the array.


MIDL Type Definitions

Type definition statements in MIDL follow the semantics of the C and C++ programming languages.


MIDL Enumerated Types

The enum declaration is not translated by the MIDL compiler into #define statements, as it is by some DCE compilers. It is reproduced as a C-language enum declaration in the generated header file.


MIDL Structures

Normal C semantics apply to the fields of base types. Fields of more complex types, such as pointers, arrays, and other constructed types, can be modified by type or field_attributes. For more information, see struct.


MIDL Unions

The Microsoft Interface Definition Language supports a superset of the C/C++ union statement. MIDL provides two varieties of unions. They are discussed in the following topics:

  • Encapsulated Unions
  • Nonencapsulated Unions


Encapsulated Unions

A union that is contained with its discriminant in a structure within is an encapsulated union. The encapsulated union is indicated by the presence of the switch keyword. This type of union is so named because the MIDL compiler automatically encapsulates the union and its discriminant in a structure for transmission during a remote procedure call.

If the union tag is missing (U1_TYPE in the example above), the compiler will generate the structure with the union field named tagged_union.

The shape of unions must be the same across platforms to ensure interconnectivity.

For a description of the form of an encapsulated union, see union.

Examples

typedef union _S1_TYPE switch (long l1) U1_TYPE
{
    case 1024:
        float f1;
    case 2048:
        double d2;
} S1_TYPE;

/* in generated header file */
typedef struct _S1_TYPE
{
    long l1;
    union
    {
        float f1;
        double d2;
    } U1_TYPE;
} S1_TYPE;

For related information, see MIDL Base Types, char, [context_handle], enum, [first_is], [handle], [ignore], int, [ignore], [last_is], [length_is], [max_is], [ms_union], Nonencapsulated Unions, [ptr], [ref], [size_is], [string], struct, switch, [switch_is], [switch_type], [transmit_as], union, and [unique]


Nonencapsulated Unions

A nonencapsulated union is a union which is not contained in a structure with its discriminant. The nonencapsulated union is indicated by the presence of the type attribute [switch_type] and the field attribute [switch_is].

For a description of the form of an nonencapsulated union, see union.

The shape of unions must be the same across platforms to ensure interconnectivity.

For more information, see Encapsulated Unions, union, [switch_is] and [switch_type].


MIDL Binding Handles

Binding handles are data objects that represent the binding between the client and the server.

MIDL supports the base type handle_t. Handles of this type are known as "primitive handles."

You can define your own handle types using the [handle] attribute. Handles defined in this way are known as "user-defined" or "customized" or "generic" handles.

You can also define a handle that maintains state information using the [context_handle] attribute. Handles defined in this way are known as "context" handles.

If no state information is needed and you do not choose to call the RPC run-time libraries to manage the handle, you can request that the run-time libraries provide automatic binding. This is done by using the ACF keyword [auto_handle].

You can specify a global variable as the binding handle by using the ACF keyword [implicit_handle]. The [explicit_handle] keyword is used to state that each remote function has an explicitly specified handle.

For more information, see Binding and Handles.


Importing Files and Type Libraries

The MIDL keywords include, import , and importlib let you reuse code by referencing existing header, IDL, and object definition language (ODL) files, and compiled type libraries.

The ACF include directive lets you specify in an ACF file one or more C-language header files to be included in the MIDL-generated stub code. The generated file will have a line with a #include C-preprocessor directive with the indicated header file. Use this include directive to bring in header files that are specific to a particular operating environment and that do not contain information necessary for the interface between client and server. Do not use include for header files containing data types that you want available to the IDL file; instead, use the import directive.

Example

[
  auto_handle
]
interface X86PC
{
  include "gendefs.h", "protos.h", "myfile.h";
  //interface typdefs and function declarations here
}

The IDL import directive is the standard method for bringing type and interface definitions from other IDL (or ODL) files and header files into your IDL file. All IDL statements in the imported file, such as typedefs, const declarations, and interface definitions become available to the importing IDL file.

Like the C-language preprocessor directive #include, the import directive tells the compiler to include data types that were defined in the imported IDL files. Unlike the #include directive, the import directive ignores procedure prototypes, since no stubs are generated for anything in the imported file. Because the preprocessor is invoked separately for the imported file, preprocessor directives (such as #define) do not carry over to the importing IDL file.

For additional information on using import to include system header files in an IDL file, see Importing System Header Files.

Example

[
  uuid(. . .), object
]
interface IKnown : IUnknown
{
  import "base.idl", "unknwn.idl", "helper.idl";
  //remainder of interface definition
}

The ODL importlib directive lets you reference a compiled type library in your IDL or ODL file. The importlib directive must be inside a library statement, and must precede other type descriptions in the library. The imported library, as well as the generated library, must be available to the application at runtime.

Example

library NewBrowser
{
  importlib("stdole32.tlb");
  importlib("legacy.tlb");
  //remainder of library definition
};

You can also use the C-preprocessor #include directive to include headers and other files in your IDL or ODL file. Be aware, however, that this directive will literally include the entire contents of the specified file. If a header file contains prototypes that you do not need or want in the MIDL-generated stub files, or if it contains nonremotable type definitions, you should use the MIDL import directive instead of the #include directive.

See Also

import, importlib, include, Importing System Header Files


Importing System Header Files

While it is often possible to use the #include directive to include header files in your IDL file, it is not recommended. The MIDL compiler will generate stubs for all functions defined in the IDL file being compiled. Usually a header file contains a number of prototypes that you neither need nor want to include in your stub files, and a #include effectively puts all those definitions into your main IDL file. Furthermore, if there are nonremotable types defined in the header file, the IDL file may not compile.

There are two ways to include type definitions from header files in an IDL file:

  • Use the import directive to include data types defined in a header file. Unlike the C-language #include directive, the import directive only picks up type and constant definitions and ignores procedure prototypes. This approach will work as long as your main IDL file does not reference any nonremotable types defined in the header file.
  • Create a helper IDL file with a dummy interface that includes the header files. Then, use the import directive to include the helper file. In this way, only the typedefs will appear in the compiled stubs. For example:
    //in helper.idl:
interface dummy
{
  #include "kitchensink.h"
  #include "system.h"
}

//in main.idl:
import "helper.idl";


MIDL Command-Line Reference

This section contains reference information for each command-line switch and switch option recognized by the Microsoft RPC MIDL compiler. Switch entries are arranged in alphabetical order. General MIDL Command-line Syntax describes the general command-line syntax.

The MIDL compiler can generate code for different platforms and system releases. Consult the /target switch to learn more about suggested switches and how to generate code optimized for a given release, such as Microsoft Windows 2000.

Note that the minus sign (–) may be substituted for the slash (/) in all MIDL command-line switches that begin with a slash (/). The following example demonstrates the equivalence of the – and the / when invoking the MIDL compiler.

Example

midl /acf my_acf.acf filename.idl
midl -acf my_acf.acf filename.idl


General MIDL Command-line Syntax

The MIDL compiler processes an IDL file and an optional application configuration file (ACF) to generate a set of output files. The attributes specified in the IDL file's interface attribute list determine whether the compiler generates source files for an RPC interface or for a custom OLE interface.

Switch Options

midl [command-line-switch [switch-options ]] filename
command-line-switch
Specifies MIDL compiler command-line switches. Switches can appear in any sequence.
switch-options
Specifies options associated with each switch. Valid options are described in the reference entry for each MIDL compiler switch.
filename
Specifies the name of the IDL file. This file usually has the extension .idl, but it can have another or none.

Remarks

The following lists show the default names of the files generated for an IDL file named Name.idl. You can use command-line switches to override these default names. Note that the name of the IDL file can have an extension other than .idl, or no extension at all.

By default (that is, if the interface attribute list does not contain the object or local attribute), the compiler generates the following files for an RPC interface:

  • Client stub (name_c.c)
  • Server stub (name_s.c)
  • Header file (name.h)

When the object attribute appears in the interface attribute list, the compiler generates the following files for a COM interface:

  • Interface proxy file (name_p.c)
  • Interface header file (name.h)
  • Interface UUID file (name_I.c)

When the local attribute appears in the interface attribute list, the compiler generates only the interface header file, Name.h.

The MIDL compiler provided with Microsoft RPC invokes the C preprocessor as needed to process the IDL file. It does not automatically invoke the C compiler to compile generated files.

Note The MIDL compiler provided with Microsoft RPC uses a different command-line syntax than does the DCE IDL compiler.

The MIDL compiler switches /env, /server, /sstub, and /out affect the server stub file.

The Header File

The header file contains definitions of all the data types and operations declared in the IDL file. The header file must be included by all application modules that call the defined operations, implement the defined operations, or manipulate the defined types.

The MIDL compiler switches /header and /out affect the header file.


The Response File Command

A response file is a text file containing one or more MIDL compiler command-line options. Unlike a command line, a response file allows multiple lines of options and file names. This may be useful due to limitations of you build environment, or as a convenience for your build process.

Switch Options

midl @response_file
response_file
Specifies the name of a response file. The response file name must immediately follow the @ character. No white space is allowed between the @ character and the response file name.

Remarks

As an alternative to placing all the options associated with a switch on the command line, the MIDL compiler accepts response files that contain switches and arguments. Options in a response file are interpreted as if they are present in that location in the MIDL command line.

Each argument in a response file must begin and end on the same line. The backslash character (\) cannot be used to concatenate lines. When it is part of a quoted string in the response file, the backslash character can only be used before another backslash or before a double quotation mark character ("). When it is not part of a quoted string, the backslash character can only be used before a double quotation mark character.

MIDL supports command-line arguments that include one or more response files combined with other command-line switches. The MIDL compiler does not support nested response files.

Examples

midl @midl.rsp

midl -Oicf @midl1.rsp -env win32 @midl2.rsp itf.idl

See Also

General MIDL Command-line Syntax


/acf

The /acf switch allows the user to supply an explicit ACF file name. The switch also allows the use of different interface names in the IDL and ACF files.

Switch Options

midl /acf acf_filename
acf_filename
Specifies the name of the ACF. White space may or may not be present between the /acf switch and the file name.

Example

midl /acf bar.acf filename.idl

Remarks

By default, the MIDL compiler constructs the name of the ACF by replacing the IDL file name extension (usually .idl) with .acf. When the /acf switch is present, the ACF takes its name from the specified file name. The /acf switch applies only to the IDL file specified on the MIDL compiler command line. It does not apply to imported files.

When the /acf switch is used, the interface name in the ACF need not match the MIDL interface name. This feature allows interfaces to share an ACF specification.

When an absolute path to an ACF is not specified, the MIDL compiler searches in the current directory, directories supplied by the /I option, and directories in the INCLUDE path. If the ACF is not found, the MIDL compiler assumes there is no ACF for this interface. For more information about the sequence of directories, see the reference entries for the /I and /no_def_idir switches. For more information relating to /acf, see Interface Definition (IDL) File.

See Also

/I, General MIDL Command-line Syntax, /no_def_idir


/align

The /align switch is functionally the same as the MIDL /Zp option and is recognized by the MIDL compiler solely for backward compatibility with MkTypLib.

Switch Options

midl /align:alignment
alignment
Specifies the alignment for types in the library. The alignment value can be 1, 2, 4, or 8. The value 1 indicates natural alignment; n indicates alignment on byte n. When you do not specify the /align switch, the default is 8.

Example

midl /align:4 filename.idl

Remarks

If you are generating a new makefile, use the /Zp switch.

The alignment value corresponds to the /Zp option value used by the Microsoft C/C++ compiler. Be sure that you specify the same alignment when you invoke the C compiler as when you invoke the MIDL compiler. For more information, see your Microsoft C/C++ programming documentation.

For a discussion of the potential dangers in using nonstandard packing levels, see the /Zp help topic.

See Also

General MIDL Command-line Syntax, /Zp


/app_config

The /app_config switch selects application-configuration mode, which allows you to use some ACF keywords in the IDL file. With this MIDL compiler switch, you can omit the ACF and specify an interface in a single IDL file.

Switch Options

midl /app_config

Examples

midl /app_config filename.idl

Remarks

This release of Microsoft RPC supports use of the following ACF attributes in the IDL file:

  • Implicit_handle
  • Auto_handle
  • Explicit_handle

Future releases of Microsoft RPC may support the use of other ACF attributes in the IDL file. The /app_config option represents a Microsoft extension to the OSF-DCE specification and, as such, is mutually exclusive with the /osf option.

For more information related to the /app_config switch, see Application Configuration File (ACF) and Interface Definition (IDL) File.

See Also

General MIDL Command-line Syntax


/c_ext

This switch is obsolete as of version 3.0 of the MIDL compiler. However, using the switch will not generate a compiler error, so you do not have to remove references to /ms_ext or /c_ext from an existing makefile.

Switch Options

midl /c_ext

Remarks

The following features are now available by default:

  • Many existing header files define types with qualifiers, such as far and stdcall, that are not part of the DCE IDL. Those compilers (and the MIDL compiler in DCE-compatibility mode) generate errors when they attempt to process these qualifiers. The MIDL compiler allows you to compile IDL files that contain these qualifiers. The type qualifiers do not affect the way the data is transmitted on the network.
  • You can omit directional attributes such as [in] or [out].

The following C-language extensions are supported in default mode:

  • Bit fields in structures and unions
  • Comments that start with two slash characters (//)
  • External declarations
  • Procedures with ellipses in the parameter list (…)
  • On 32-bit platforms, int is a native 32-bit base type; on 16-bit platforms, int is recognized but is not a remotable type
  • Type void * that is not used in remote operations
  • Type qualifiers — including the form with the ANSI-conformant prefix — contain two underscore characters: _ _cdecl, cdecl, _ _const, const, _ _export, export, _ _far, far, _ _loadds, loadds, _ _near, near, _ _pascal, pascal, _ _stdcall, stdcall, _ _volatile, and volatile.

For more information about declaration qualifiers, see your Microsoft C/C++ documentation.

See Also

/app_config, /osf, General MIDL Command-line Syntax


/caux

This switch is obsolete and, if used, results in an error.


/char

The /char switch helps to ensure that the MIDL compiler and C compiler operate together correctly for all char and small types.

Switch Options

midl /char { signed | unsigned | ascii7 }
signed
Specifies that the default C-compiler type for char is signed. All occurrences of char not accompanied by a sign specification are generated as unsigned char.
unsigned
Specifies that the default C-compiler type for char is unsigned. All uses of small not accompanied by a sign specification are generated as signed small.
ascii7
Specifies that all char values are to be passed into the generated files without a specific sign keyword. All uses of small not accompanied by a sign specification are generated as small.

Remarks

By definition, MIDL char is unsigned. Small is defined in terms of char (#define small char), and MIDL small is signed.

The /char switch directs the MIDL compiler to specify explicit signed or unsigned declarations in the generated files when the C-compiler sign declaration conflicts with the MIDL default for that type.

Remember that the MIDL compiler generates the stubs as C source code, which you must compile as part of your client and server programs. Some compilers use a signed char everywhere char data is specified in the source code. The stub source code that the MIDL compiler generates treats all char data as unsigned char. If the MIDL compiler simply generated all char data in the IDL file as char data in the stubs, compilers that use a signed char for char data would cause a conflict in the stub source code.

The purpose of the /char command line switch is to resolve these potential conflicts. It preserves all data specified as char in the IDL file as unsigned char in the stub source code. It also maintains small data as signed.

The following table summarizes the generated types.

midl /char option | Generated char type | Generated small type
midl /char signed | unsigned char | small
midl /char unsigned | char | signed small
midl /char ascii7 | char | small

The /char signed option indicates that the C-compiler char and small types are signed. To match the MIDL default for char, the MIDL compiler must convert all uses of char not accompanied by a sign specification to unsigned char. The small type is not modified because this C-compiler default matches the MIDL default for small.

The /char unsigned option indicates that the C-compiler char type is unsigned. The MIDL compiler converts all uses of small not accompanied by a sign specification to signed small.

The ascii7 option indicates that no explicit sign specification is added to char types. The type small is generated as small.

To avoid confusion, you should use explicit sign specifications for char and small types whenever possible in the IDL file. Note that the use of explicitly signed char types in your IDL file is not supported by DCE IDL. Therefore, this feature is not available when you compile with the MIDL /osf switch.

For more information related to /char, see small.

Examples

midl /char signed filename.idl
midl /char unsigned filename.idl
midl /char ascii7 filename.idl

See Also

char, General MIDL Command-line Syntax, /osf, small


/client

The /client switch directs the MIDL compiler to generate client-side C source files for an RPC interface.

Switch Options

midl /client { stub | none }
stub
Generates the client-side files.
none
Does not generate any client-side files.

Remarks

When the /client switch is not specified, the MIDL compiler generates the client stub file. This switch does not affect OLE interfaces.

The /client switch takes precedence over the /cstub switch.

Examples

midl /client none filename.idl
midl /client stub filename.idl

See Also

/cstub, /server, General MIDL Command-line Syntax


/confirm

The /confirm switch instructs the compiler to display all MIDL compiler options without processing the input IDL (and optional ACF) files.

Switch Options

midl /confirm

Examples

midl /confirm
midl /confirm @response.rsp filename.idl

See Also

/help, General MIDL Command-line Syntax


/cpp_cmd

The /cpp_cmd switch specifies the preprocessor that the MIDL compiler uses to preprocess the input files.

Switch Options

midl /cpp_cmd "C_preprocessor_binary"
C_preprocessor_binary
Specifies the command that invokes the preprocessor. This command allows developers to override the default preprocessor. By default, MIDL invokes the Microsoft C/C++ compiler from the build machine's build environment.

Remarks

The C_preprocessor_binary argument to the switch may specify the full path. The exe suffix and quotes are optional. Typically, developers use the switch to choose a particular version of the Microsoft C/C++ preprocessor or equivalent in the build environment. If so, it is not necessary to use the /cpp_opt switch with /cpp_cmd.

When using a non-Microsoft preprocessor, especially when the specified preprocessor does not direct its output to stdout, the C compiler switch that redirects output to stdout as part of the MIDL compiler /cpp_opt switch must be specified. See C-Preprocessor Requirements for MIDL for details

The preprocessor is invoked by a command string that is formed from the information provided to the MIDL compiler by /cpp_cmd, /cpp_opt, /D, /I, and /U switches. The following table summarizes how the command string is constructed for each combination of /cpp_cmd and /cpp_opt switches.

When the /cpp_cmd switch is not specified, the MIDL compiler invokes the Microsoft C/C++ compiler. MIDL will use a cl.exe binary found in the build environment.

When the /cpp_opt switch is not present, the MIDL compiler concatenates the string specified by the /cpp_cmd switch with the information specified by the MIDL /I, /D and /U options. The string /E is also concatenated to the C-compiler invocation string to indicate that the C/C++ compiler should perform preprocessing only. The /nologo switch is added to suppress the C/C++ compiler banner. The MIDL compiler uses the concatenated string to invoke the C preprocessor for top level IDL as well as imported IDL files and also for the corresponding ACF files, if present.

When the /cpp_opt switch is present, which should be a rare case for the current 32b and 64b platforms, the MIDL compiler concatenates the string specified by the /cpp_cmd switch with the string specified by the /cpp_opt switch. The MIDL compiler uses the concatenated string to invoke the indicated preprocessor binary in lieu of the default preprocessor. When the /cpp_opt switch is present, neither the MIDL compiler options specified by the /I, /D, and /U switches nor the C compiler switch /E is concatenated with the string. You must supply the /E option, or equivalent, as part of the string.

/cpp_cmd present? | /cpp_opt present? | Description
No (default) | No (default) | Invokes the default Microsoft C/C++ compiler with settings obtained from MIDL /I, /D and /U switches. Adds the preprocessor switches /E and /nologo.
Yes | No | Invokes the indicated preprocessor binary with the same switches as above.
No | Yes | Invokes Microsoft C compiler with specified options. Does not use MIDL /I, /D, /U options. You must supply /E as part of /cpp_opt .
Yes | Yes | Invokes the specified preprocessor binary with specified options only. Use quotes.

Examples

midl /cpp_cmd d:\nt\tools\ia64\cl.exe /DFLAG=TRUE /Ic:\inc filename.idl
midl /cpp_cmd "mycpp" /DFLAG=TRUE /Ic:\inc filename.idl
midl /cpp_opt "/E /DFLAG=TRUE /Ic:\inc" filename.idl
midl /cpp_cmd "cl"  /cpp_opt "/E /DFLAG=TRUE /Ic:\inc" filename.idl

See Also

/savePP, /cpp_opt, General MIDL Command-line Syntax, /no_cpp, C-Preprocessor Requirements for MIDL


/cpp_opt

The /cpp_opt switch specifies options to pass to the C/C++ preprocessor.

Switch Options

midl /cpp_opt "C_preprocessor_option" file.idl
C_preprocessor_option
Specifies command-line option associated with the invoked preprocessor. For the Microsoft C/C++ preprocessors you must supply the /E switch as part of the C_preprocessor_option string. Quotes are required when more than one option is used, and for spaces.

Remarks

Do not use this switch unless there is a specific reason for doing so. Consult C-Preprocessor Requirements for MIDL for important information regarding preprocessing.

The /cpp_opt switch can be used with or without the /cpp_cmd switch. Consult /cpp_cmd for details of how the preprocessor command line is constructed in either case.

Examples

midl /cpp_cmd d:\nt\tools\ia64\cl.exe /DFLAG=TRUE /Ic:\inc filename.idl
midl /cpp_cmd "mycpp" /DFLAG=TRUE /Ic:\inc filename.idl
midl /cpp_opt "/E /DFLAG=TRUE /Ic:\inc" filename.idl
midl /cpp_cmd "cl"  /cpp_opt "/E /DFLAG=TRUE /Ic:\inc" filename.idl

See Also

/savePP, /cpp_cmd, General MIDL Command-line Syntax, /no_cpp, C-Preprocessor Requirements for MIDL


/cstub

The /cstub switch specifies the name of the client stub file for an RPC interface.

Switch Options

midl /cstub stub_file_name
stub_file_name
Specifies a file name that overrides the default client stub file name. File names can be explicitly quoted using double quotes (") to prevent the shell from interpreting the special characters.

Remarks

The specified file name replaces the default file name. By default, the file name is obtained by adding the extension _c.c to the name of the IDL file. This switch does not affect OLE interfaces.

When you are importing files, the specified file name applies to only one stub file — the stub file that corresponds to the IDL file specified on the command line.

If stub_file_name does not include an explicit path, the file is written to the current directory or the directory specified by the /out switch. An explicit path in stub_file_name overrides the /out switch specification.

The /client none switch takes precedence over the /cstub switch.

Example

midl /cstub my_cstub.c filename.idl

See Also

/header, General MIDL Command-line Syntax, /out, /sstub


/D

The /D switch defines a name and an optional value to be passed to the C preprocessor as if by a #define directive. Multiple /D directives can be used in a command line.

Switch Options

midl /D name=definition
name
Specifies a defined name that is passed to the C preprocessor when the /cpp_cmd switch is present and the /cpp_opt switch is not present.
definition
Specifies a value associated with the defined name.

Remarks

White space between the /D switch and the defined name is optional.

When the /cpp_cmd switch is present and the /cpp_opt switch is not, the MIDL compiler concatenates the string specified by the /cpp_cmd switch with the /I, /D, and /U options and uses this concatenated string to invoke the C preprocessor for each IDL and ACF source file.

The MIDL compiler switch /D is ignored when the MIDL compiler switch /no_cpp or /cpp_opt is specified.

Example

midl -DUNICODE filename.idl

See Also

/cpp_cmd, /cpp_opt, /I, General MIDL Command-line Syntax, /no_cpp, /U


/dlldata

The /dlldata switch is used to specify the file name for the generated dlldata file for a proxy DLL. The default file name Dlldata.c is used if the /dlldata switch is not specified.

Switch Options

midl /dlldata file-name
file-name
The name of the C source file the MIDL compiler will generate for the proxy DLL.

Remarks

The file specified by file-name must be linked to the proxy DLL. The dlldata file contains entry points and data structures required by the class factory for the proxy DLL. These data structures specify the object interfaces contained in the proxy DLL. The dlldata file also specifies the class identifier of the class factory for the proxy DLL. This is always the UUID (IID) of the first interface of the first proxy file (by alphabetical order).

The same dlldata file should be specified when invoking MIDL on all the IDL files that will go into a particular proxy DLL. The dlldata file is created or updated during each MIDL compilation, incrementally building a list of the interfaces that will go into the proxy DLL.

Example

midl /dlldata data.c

See Also

General MIDL Command-line Syntax


/env

The /env switch selects the environment in which the application runs.

Switch Options

midl /env { win32 | win64 }
win32
Directs the MIDL compiler to generate stub files, or a type library file, for a 32-bit environment – Windows 95, Windows NT, or Windows 2000.
win64
Directs the MIDL compiler to generate stub files, or a type library file, for a 64-bit environment – Windows 2000.

Remarks

The /env switch primarily affects the packing level used for structures in that environment. Be sure you specify the same packing-level setting for both the MIDL compiler and the C compiler.

The /env switch determines the packing level and other settings as follows:

  • When you specify win32, generated stubs use C-compiler packing-level 8 for all types involved in remote operations. The long and int data types are both 32 bits. Pointers are 32 bits.
  • When you specify win64, the MIDL compiler runs in a cross-compiler mode for a 64-bit platform. The generated stubs use C-compiler packing-level 8 for all types involved in remote operations. The long and int data types are 32 bits. Pointers are 64 bits.

The /align, /pack, and /Zp switches take precedence over the /env settings.

For more information on 64 bit support for MIDL and RPC see Designing 64-bit-Compatible Interfaces.

Examples

midl /env win32 filename.idl
midl /env win64 filename.idl

See Also

General MIDL Command-line Syntax, /pack, /Zp


/error

The /error switch determines the types of error checking that the generated stubs will perform at run time.

Switch Options

midl /error { allocation | stub_data | ref | bounds_check | none | all }
allocation
Checks whether midl_user_allocate returns a NULL value, indicating an out-of-memory error.
stub_data
Generates a stub that catches unmarshaling exceptions on the server side and propagates them back to the client.
ref
Generates code that runs a check at run time to ensure that no NULL reference pointers are being passed to the client stubs and raises an RPC_X_NULL_REF_POINTER exception if it finds any.
bounds_check
Checks size of conformant-varying and varying arrays against transmission length specification.
none
Performs no error checking.
all
Performs all error checking. Effective with MIDL version 5.0, this is a default compiler switch.

Remarks

The /error switch selects the number of error checks that the generated stub files will perform. Effective with MIDL version 5.0, the default setting is /error all.

The enum errors that are checked (by default in all versions of MIDL) are truncation errors caused when converting between long enum types (32-bit integers) and short enum types (the network-data representation of enum), and the number of identifiers in an enumeration exceeding 32,767.

The memory-access error checking (also by default in all versions of MIDL) is for pointers that exceed the end of the buffer in marshaling code and for conformant arrays whose size is less than zero. Use the /ERROR BOUNDS_CHECK flag to check for other invalid array bounds.

When you specify /error allocate, the stubs include code that raises an exception when midl_user_allocate returns 0.

The /error stub_data option prevents client data from crashing the server during unmarshaling, effectively providing a more robust method of handling the unmarshaling operation.

Effective with Windows 2000, the underlying run-time NDR marshaling engine performs most of these checks. This means that if you are using one of the fully-interpreted modes (/Oi, /Oif) of stub generation, choosing different error checking options will not have a marked effect on performance.

Examples

midl /error allocation filename.idl
midl /error none filename.idl

See Also

General MIDL Command-line Syntax, /robust


/h

The /h option is functionally equivalent to the /header option.

Switch Options

midl /h filename
filename
Specifies a header file name that overrides the default header file name. File names can be explicitly quoted using double quotes (") to prevent the shell from interpreting special characters.

Remarks

The /h switch specifies filename as the name for a header file that contains all the definitions contained in the IDL file, without the IDL syntax. This file can be used as a C or C++ header file.

Examples

midl /h tlibhead.h filename.idl

midl /h "midl.h" filename.idl

See Also

General MIDL Command-line Syntax, /header


/header

The /header switch specifies the name of the header file.

Switch Options

midl /header filename
filename
Specifies a header file name that overrides the default header file name. File names can be explicitly quoted using double quotes (") to prevent the shell from interpreting special characters.

Remarks

The specified file name replaces the default file name. The default file name is obtained by replacing the IDL file name extension (usually .idl) with the file name extension .h. For OLE interfaces, the /header switch overrides the default name of the interface header file.

When you are importing files, the specified file name applies to only one header file — the header file that corresponds to the IDL file specified on the command line.

If filename does not include an explicit path, the file is written to the current directory or the directory specified by the /out switch. An explicit path in file name overrides the /out switch specification.

Example

midl /header "bar.h" filename.idl

See Also

General MIDL Command-line Syntax, /h, /cstub, /out, /sstub, /proxy


/help (/?)

The /help (/?) switch instructs the compiler to display a usage message detailing all available MIDL command-line switches and options.

The /confirm switch displays the MIDL compiler switch settings selected by the user.

Switch Options

midl /help
midl /?

Example

midl /help

See Also

General MIDL Command-line Syntax, /confirm


/I

The /I switch specifies directories to be searched for imported IDL files, included header files, and ACF files.

Switch Options

midl /I include_path
include_path
Specifies one or more directories that contain import, include, and ACF files. White space between the /I switch and include_path is optional. Separate multiple directories with a semicolon character (;).

Remarks

More than one directory can appear with each /I switch, and more than one /I switch can appear with each MIDL compiler invocation. Directories are searched in the order they are specified.

The /I switch setting is also passed by the MIDL compiler to the C compiler's C preprocessor. When the /cpp_cmd switch is present and the /cpp_opt switch is not, the MIDL compiler concatenates the string specified by the /cpp_cmd switch with the /I, /D, and /U options and uses this concatenated string to invoke the C preprocessor for each IDL and ACF source file. The MIDL compiler switch /I is not passed to the preprocessor when the MIDL compiler switch /no_cpp or /cpp_opt is specified.

In Microsoft operating-system environments (64-bit Windows, 32-bit Windows, 16-bit Windows, and MS-DOS), directories are searched in the following sequence:

  1. Current directory
  2. Directories specified by the /I switch (in the order they follow the switch)
  3. Directories specified by the INCLUDE environment variable

When directories are specified with the /I switch, the /no_def_idir switch instructs the MIDL compiler to ignore the current directory, ignore the directories specified by the INCLUDE environment variable, and search only the specified directories.

When no directories are specified with the /I switch, the /no_def_idir switch instructs the MIDL compiler to search only the current directory.

Example

midl /I c:\include;c:\include\h /I\include2 filename.idl

See Also

General MIDL Command-line Syntax, /acf, /cpp_cmd, /cpp_opt, /no_def_idir


/iid

The /iid switch specifies the name of the interface identifier file for a COM interface, overriding the default name obtained by adding _i.c to the IDL file name.

Switch Options

midl /iid filename
filename
Specifies an interface identifier file name that overrides the default interface identifier file name for a COM interface. File names can be explicitly quoted using double quotes (") to prevent the shell from interpreting the special characters.

Remarks

The /iid switch does not affect RPC interfaces.

If filename does not include an explicit path, the file is written to the current directory or to the directory specified by the /out switch. An explicit path in filename overrides the /out switch specification.

Example

midl /iid "my_iid.c" filename.idl

See Also

General MIDL Command-line Syntax, /header, /out, /proxy


/import

This switch is obsolete and, if used, results in an error.


/lcid

The /lcid MIDL compiler option lets you use international characters in your input files, file names, and directory paths.

Switch Options

midl /lcid localeID
localeID
Specifies the 32-bit locale identifier used in Win32 National Language Support. The locale identifier should be specified in decimal.

Remarks

Within the input files, you can use localized comments, strings, helpstrings and identifiers. In particular, the /lcid switch provides full DBCS support, to represent Asian languages such as Japanese, Chinese, and Korean. For more information on National Language Support (NLS) see Locales and Double-byte Character Sets in the International Features section of the Windows Base Services online documentation.

Note The /lcid switch is available with MIDL version 3.01.75 and later.

Example

midl /lcid 1041 iface.idl

See Also

General MIDL Command-line Syntax, lcid


/mktyplib203

The /mktyplib203 switch forces the MIDL compiler to parse the input file in much the same manner as Mktyplib.exe, version 2.03, would handle the file.

Switch Options

midl /mktyplib203

Remarks

In order to use this switch, the input file must follow the ODL syntax exactly — you cannot place any statements outside of the library block. Specifically, using the /mktyplib203 switch resolves the following discrepancies between MkTypLib and MIDL:

  • MkTypLib typdef syntax is required for struct, union, and enum data types.
  • GUIDs in the header files are defined with a macro that can be conditionally compiled to generate either a GUID predefinition or an instantiated GUID.
  • The base type BOOL is represented as a VARIANT_BOOL, which is defined as a short.

See Differences Between MIDL and MkTypLib for a more detailed description of these differences and a discussion of the differences between MkTypLib and MIDL that cannot be resolved by using the /mktyplib203 switch.

Examples

midl /mktyplib203 myoldodl.odl
midl /mktyplib203 oldhabit.idl

See Also

General MIDL Command-line Syntax, Generating a Type Library With MIDL, Differences Between MIDL and MkTypLib


/ms_ext

Effective with MIDL version 3.0, the features enabled by the ms_ext switch are now the default mode for the MIDL compiler.

Switch Options

midl /ms_ext

Remarks

Using the switch will not generate a compiler error, so you do not have to remove references to /ms_ext or /c_ext from an existing makefile.

The following Microsoft extensions to OSF DCE are now available by default:

  • Interface definitions for OLE objects. For more information on the files generated for OLE interfaces, see Files Generated for a COM Interface
  • A [callback] attribute specifying a static callback function on the client
  • cpp_quote(quoted_string) and #pragma midl_echo
  • wchar_t wide-character types, constants, and strings
  • enum initialization (sparse enumerators)
  • Expressions as size and discriminator specifiers
  • Handle extensions
  • Pointer-attribute type inheritance
  • Multiple interfaces
  • Definitions outside of the interface block
  • You can omit directional attributes [in, out]

See Also

General MIDL Command-line Syntax, Pointer-Attribute Type Inheritance, /app_config, /osf


/ms_union

The /ms_union switch controls the NDR alignment of nonencapsulated unions.

Switch Options

midl /ms_union

Remarks

The MIDL compiler mirrors the behavior of the OSF-DCE IDL compiler for nonencapsulated unions. However, because earlier versions of the MIDL compiler did not do so, the /ms_union switch provides compatibility with interfaces built on previous versions of the MIDL compiler.

The ms_union feature can be used as a command-line switch (/ms_union), an IDL interface attribute, or as an IDL-type attribute.

Example

midl /ms_union file.idl

See Also

General MIDL Command-line Syntax, Interface Definition (IDL) File


/msc_ver

The /msc_ver switch is used to allow MIDL to generate code that includes optimizations for different versions of Microsoft C/C++ compilers.

Switch Options

midl /msc_ver version_number
version_number
Specifies an integer version number of the Microsoft Visual C++ compiler that will be used to compile the client and server stubs of the distributed application. The default version number is 1100, which corresponds to VC++ version 5.0. The version number 1200 corresponds to VC++ version 6.0, and so on.

Remarks

In particular, version values of 1100 or greater cause the MIDL compiler to generate code utilizing the __declspec(uuid()) directive. It also activates macros that use the __declspec(selectany) and __declspec(novtable) directives.


/new

This switch is obsolete and has been replaced by the /newtlb option.


/newtlb

This is the default setting for choosing a type library format.

Switch Options

midl /newtlb <other-options> filename

Remarks

Effective with Windows NT 4.0, there is a new version of Oleaut32.dll that supports a richer format for 32-bit type libraries. MIDL looks for this DLL on the build machine; if the new version is present, MIDL generates a new-format type library, otherwise it generates an old-format type library. Thus, if the new Oleaut32.dll is present, this switch does nothing. If the new Oleaut32.dll is not present, specifying this switch in the MIDL command line will generate an error.

Examples

midl /newtlb filename.idl
midl filename.idl

See Also

General MIDL Command-line Syntax, /oldtlb


/no_cpp, /nocpp

The /no_cpp switch specifies that the MIDL compiler does not call the C preprocessor to preprocess the IDL file.

The /no_cpp switch takes precedence over the /cpp_cmd and /cpp_opt switches.

Switch Options

midl /no_cpp
midl /nocpp

Example

midl /no_cpp filename.idl

See Also

General MIDL Command-line Syntax, /cpp_cmd, /cpp_opt, /D, /I, /U


/no_default_epv

The /no_default_epv switch directs the MIDL compiler not to generate a default entry-point vector (epv).

Switch Options

midl /no_default_epv

Remarks

In this case, the application must register an epv with the RpcServerRegisterIf call. Compare this switch with the /use_epv switch.

Example

midl /no_default_epv filename.idl

See Also

General MIDL Command-line Syntax, Interface Definition (IDL) File, /use_epv, RpcServerRegisterIf


/no_def_idir

When directories are specified with the /I switch, the /no_def_idir switch instructs the MIDL compiler to search only the directories specified with the /I switch, ignoring the current directory as well as the directories specified by the INCLUDE environment variable.

Switch Options

midl /no_def_idir

Remarks

When no directories are specified with the /I switch, the /no_def_idir switch instructs the MIDL compiler to search only the current directory.

Examples

; search only the current directory
midl /no_def_idir filename.idl
; search only the specified directories
midl /no_def_idir /I c:\c700\include filename.idl

See Also

General MIDL Command-line Syntax, /acf, /I


/no_format_opt

The /no_format_opt switch changes the way MIDL optimizes type and procedure descriptors.

Switch Options

midl /no_format_opt

Remarks

By default, MIDL eliminates duplicate type and procedure descriptors in order to reduce the size of the generated stub code. Using the /no_format_opt switch turns off this optimizing behavior.

Example

midl /no_format_opt mylean.idl

See Also

General MIDL Command-line Syntax, /Oi


/nologo

The /nologo switch disables the display of the copyright banner.

Switch Options

midl /nologo

See Also

General MIDL Command-line Syntax


/notlb

The /notlb switch prevents the MIDL compiler from generating a type library (TLB) file.

Switch Options

midl /notlb

Remarks

By default, the MIDL compiler will generate a TLB file whenever it encounters a LIBRARY statement. This switch overrides the default behavior.

When the /notlb option is specified, all other stubs, headers, etc. are generated as usual.

See Also

/tlb


/no_warn

The /no_warn switch directs the MIDL compiler to suppress warning messages.

Switch Options

midl /no_warn

Remarks

The use of the /no_warn switch is equivalent to /W0.

Examples

midl /no_warn filename.idl
midl /W0 filename.idl

See Also

General MIDL Command-line Syntax, /W, /WX


/o

The /o switch redirects output, such as error messages and warnings, from standard output to the specified file.

Switch Options

midl /o outputfile
outputfile
Specifies the name of the file to which the MIDL compiler will redirect output such as error messages and warnings.

See Also

General MIDL Command-line Syntax


/Oi

The /Oi switch directs the MIDL compiler to use a fully-interpreted marshaling method. The /Oic and /Oicf switches provide additional performance enhancements.

Switch Options

midl /{Oi | Oic | Oif | Oicf}
/Oi
Specifies the fully-interpreted method for marshaling stub code passed between client and server. This switch is obsolete. Use /Oif or /Oicf instead.
/Oic
Specifies the codeless proxy method of marshaling that provides all the features of /Oi and also further reduces the size of the client stub code for object interfaces.
/Oif or /Oicf
Specifies the codeless proxy method of marshaling that includes all the features provided by /Oi and /Oic but uses a new interpreter (fast format strings) that provides better performance than /Oi or /Oic.

Please note the restrictions related to supporting platforms.

Remarks

The MIDL 3.0 compiler provides two methods for marshaling code: fully-interpreted (/Oi, /Oic and /Oif) and mixed-mode (/Os). Mixed-mode is the default. Some language features are not supported in some modes. In this case, the compiler automatically switches to the appropriate mode and issues a warning.

If performance is a concern, the mixed-mode (/Os) method can be the best approach. In this mode, the compiler chooses to marshal some parameters inline in the generated stubs. While this results in larger stub size, it offers increased performance.

The fully-interpreted method marshals data completely offline. This considerably reduces the size of the stub code, but results in decreased performance. Also, with the fully-interpreted method, there is a limit of 16 parameters for each procedure. Any procedure containing more than 16 parameters will automatically be processed in /Os mode. Among the interpreted modes, /Oif offers the best performance and /Oi offers the best backward compatibility.

If your application uses OLE object interfaces and if it will never run on a version of Microsoft Windows NT earlier than 3.51, you can reduce the size of your client stub code for object interfaces by using the /Oic option. With this option the MIDL compiler does not generate any client-side stub code. Since object interface calls are through vtable pointers, the compiler generates the proper vtable structures and the application calls the stubs through them.

If your application will be run only on Microsoft Windows NT 4.0 or later, you can use the faster /Oif option. Specifically, you may want to use the /Oif option if your application uses MIDL features that were introduced with MIDL 3.0, such as the [wire_marshal] and [user_marshal] attributes. If your application uses pipes you must use the /Oif option; if you specify another mode, the MIDL compiler will switch to /Oif.

To fine-tune the way your stub code is marshaled, Microsoft RPC provides an ACF [optimize] attribute. This attribute is used as an interface attribute or operation attribute to select the marshaling mode for individual interfaces or for individual operations.

Calling Conventions

Stubs generated by the MIDL compiler in the interpreted method using the /Oi, /Oic, or /Oif switches must be compiled as either a stdcall or a cdecl procedure during the C compilation. A PASCAL or Fastcall calling convention will not work. Additionally, the server stub must be compiled as stdcall.

Supporting Platforms

/Oi is supported on Windows NT 3.5 or later and Windows 95 or later.
/Oic is supported on Windows NT 3.51 or later and Windows 95 or later.
/Oif is supported on Windows NT 4.0.

Examples

midl /Oi filename.idl
midl /Oic filename.idl
midl /Oif filename.idl

See Also

General MIDL Command-line Syntax, /Os, optimize, /no_format_opt


/old

This switch is obsolete and has been replaced by the /oldtlb option.


/oldtlb

The /oldtlb switch directs the MIDL compiler to generate an old-format type library.

Switch Options

midl /oldtlb

Remarks

Effective with Windows NT 4.0, there is a new version of Oleaut32.dll that supports a richer format for 32-bit type libraries. MIDL looks for this DLL on the build machine; if the new version is present, MIDL generates a new-format type library. Otherwise, it generates an old-format type library. The /oldtlb switch overrides this default and directs the MIDL compiler to generate old-format type libraries even if the newer version of Oleaut32.dll is present.

Examples

midl /oldtlb filename.idl
midl /oldtlb myoldodl.odl

See Also

General MIDL Command-line Syntax, /newtlb


/oldnames

The /oldnames switch directs the MIDL compiler to generate interface names that do not include the version number.

Switch Options

midl /oldnames

Remarks

The MIDL compiler incorporates the version number of the interface into the interface name that is generated in the stub (for example, iface_v1_0_ServerIfHandle). This naming format is consistent with the format used by the OSF DCE IDL compiler. However, it differs from the naming format used by the MIDL 1.0 compiler. The MIDL 1.0 compiler did not include version numbers in interface names (for example, iface_ServerIfHandle). The /oldnames switch allows you to instruct the MIDL compiler to generate interface names which do not include the version number. In this way, the format is consistent with names generated by the MIDL 1.0 compiler.

If you have server application code that was written for use with a stub generated by the MIDL 1.0 compiler and it refers to the MIDL-generated interface name (for example, in a call to RpcServerRegisterIf), you should change it to reference the style of interface name supported by version 2.0 or later of the MIDL compiler. Alternately, you can use the /oldnames switch when invoking the MIDL compiler.

Example

midl /oldnames filename.idl

See Also

General MIDL Command-line Syntax, Interface Definition (IDL) File


/Os

The /Os switch specifies the mixed-mode method to marshal stub code passed between client and server.

Switch Options

midl /Os

Remarks

There are important issues to consider before deciding on the method for marshaling code. These issues concern size and performance. The MIDL compiler provides two methods for marshaling code: mixed-mode (/Os) and fully-interpreted (/Oi). The fully-interpreted method marshals data completely offline. This reduces the size of the stub code considerably, but it also results in decreased performance.

If performance is an important concern, the mixed-mode method (/Os) can be the best approach. In this mode, the compiler marshals some parameters inline in the generated stubs. While this results in larger stub size, it also offers increased performance. Because mixed-mode is the default, you do not need to explicitly select the /Os switch to accomplish mixed-mode marshaling.

MIDL provides full support for multidimensional arrays and multidimensional-sized pointers only in /Oicf mode. In /Os and /Oi modes, the compiler supports simple cases, such as fixed-size arrays. Using multidimensional arrays in /Os or /Oi modes can result in parameters that are not marshaled correctly. Microsoft recommends that you use the /Oicf command line switch when your interface defines parameters that are multidimensional arrays or multidimensional-sized pointers.

To further define the level of gradiation in how data is marshaled, this version of RPC provides an [optimize] attribute. This attribute is used as an ACF interface attribute or operation attribute to select the marshaling mode.

Examples

midl /Os filename.idl

See Also

General MIDL Command-line Syntax, /Oi, optimize, /no_format_opt


/osf

The /osf switch forces strict compatibility with OSF DCE.

Switch Options

midl /osf

Remarks

Use this switch if your application requires strict compatibility with OSF DCE for portability reasons.

In /osf mode, the RpcSs package is automatically enabled when you use full pointers, the arguments require memory allocation, or when you use the enable_allocate attribute. This means that you do not have to supply the midl_user_allocate and midl_user_free functions in your client and server application.

The following Microsoft-extended features are not available when you compile with the /osf switch:

  • Abstract declarators (unnamed parameters) in the IDL file.
  • Interface definitions for COM objects.
  • Interface names with more than 17 characters.
  • MIDL-only attributes, such as wire_marshal, user_marshal, and the typelib (ODL)extensions.
  • Using ACF keywords in an IDL file (the MIDL /app_config option).
  • Static callback functions on the client.
  • cpp_quote and #pragma midl_echo.
  • wchar_t wide-character types, constants, and strings.
  • enum initialization (sparse enumerators).
  • out-only size specification.
  • Mixed sized-pointers and sized arrays.
  • Expressions used for size and discriminator specifiers.
  • Explicit handle parameters in any position in the argument list. In /osf mode, the MIDL compiler looks for an explicit binding handle as the first parameter. When the first parameter is not a binding handle and one or more context handles are specified, the leftmost context handle is used as the binding handle. When the first parameter is not a handle and there are no context handles, the procedure uses implicit binding using the ACF attribute implicit_handle or auto_handle.
  • Pointer-attribute type inheritance. OSF DCE does not allow unattributed pointers. Therefore, in /osf mode each IDL file must define attributes for its pointers. If any pointer does not have an explicit attribute, the IDL file must have a pointer_default specification to set the pointer type.
  • Multiple interfaces in an IDL file.
  • Definitions outside of the interface block.
  • Type qualifiers such as far and stdcall.
  • Omitting directional attributes.

The following C/C++ language extensions are not available when you compile with the /osf switch:

  • Bit fields in structures and unions.
  • Single line comments delimited with two slash characters (//).
  • External declarations.
  • Procedures with ellipses in the parameter list.
  • Type int.
  • Type void * (except with the context_handle attribute).
  • Type qualifiers, including the form with the ANSI-conformant prefix, contain two underscore characters: _ _cdecl, cdecl, _ _const, const, _ _export, export, _ _far, far, _ _loadds, loadds, _ _near, near, _ _pascal, pascal, _ _stdcall, stdcall, _ _volatile, and volatile.
  • Any #pragma warning or #pragma comment.
  • Type serialization.
  • The __int3264 data type.
  • The /protocol switch, and ndr64 transfer syntax.

Examples

midl /osf filename.idl
midl /osf /app_config filename.idl

See Also

General MIDL Command-line Syntax, /app_config, /ms_ext, Rpcss Memory Management Package


/out

The /out switch specifies the default directory where the MIDL compiler writes output files.

Switch Options

midl /out path-specification
path-specification
Specifies the path to the directory in which the stub, header, and switch files are generated. A drive specification, an absolute directory path, or both can be specified. Paths can be explicitly quoted using double quotes (") to prevent the shell from interpreting the special characters.

Remarks

The output directory can be specified with a drive letter, an absolute path name, or both. The /out option can be used with any of the switches that enable individual output file specification.

When the /out switch is not specified, files are written to the current directory.

The default directory specified by the /out switch can be overridden by an explicit path name specified as part of the /cstub, /header, /proxy, or /sstub switch.

Examples

midl /out c:\mydir\mysubdir\subdir2 deeper filename.idl
midl /out c:  filename.idl
midl /out \mydir\mysubdir\another filename.idl

See Also

General MIDL Command-line Syntax, /cstub, /header, /proxy, /sstub


/pack

The /pack switch is the same as the /Zp option.

Switch Options

midl /pack packing_level
packing_level
Specifies the packing level of structures in the target system. The packing-level value can be set to 1, 2, 4, or 8.

Remarks

The /pack switch designates the packing level of structures in the target system. The packing-level value corresponds to the /Zp option value used by the Microsoft C/C++ version 7.0 compiler. For more information, see your Microsoft C/C++ programming documentation.

Specify the same packing level when you invoke the MIDL compiler and the C compiler. The default packing level used when neither the /Zp nor /pack switch is specified is 8, in both Win32 and Win64 build environments.

For a discussion of the potential dangers in using nonstandard packing levels, see the /Zp help topic.

Examples

midl /pack 2 filename.idl
midl /pack 8 bar.idl

See Also

General MIDL Command-line Syntax, /env, /Zp


/prefix

The /prefix switch directs the MIDL compiler to add prefix strings to the client and/or server stub routine names. This can be used to allow a single program to be both a client and server of the same interface, without having the client- and server-side routine names conflict with each other.

Switch Options

midl /prefix { client | server | switch | all }
client
Affects only the client stub routine names.
server
Affects only the routine names called by the server stub routine.
switch
Affects an extra prototype added to the header file.
all
Affects both the client and server stub routine names.

Remarks

If the prefix for the client-side routines is different from the prefix for the server-side routines, the generated header file will have both client-side routine prototypes and server-side routine prototypes.

The /prefix switch is useful when a single header file will be used with stubs from multiple runs of the MIDL compiler. This forces additional routine prototypes in the header file.

In all cases, the client, server, and switch prefixes will override an all prefix.

Examples

midl /prefix client "c_" server "s_"
midl /prefix all "moo_"
midl /prefix client "bark_"

See Also

General MIDL Command-line Syntax


/protocol

The /protocol switch specifies which wire protocol is supported by the generated stub.

Switch Options

midl /protocol (dce|ndr64|all)
dce
The generated stub supports DCE protocol only.
ndr64
The generated stub supports Microsoft NDR64 protocol only.
all
The generated stub supports all available protocols for a given environment.

Remarks

RPC marshals and unmarshals data according to a strict wire protocol, also called transfer syntax, that defines data wire representation such as the order in which data members are marshaled, the alignment of data on the wire, additional information included with the data, among others. Microsoft RPC is compatible with OSF DCE's NDR (network data representation) protocol. In the 64-bit release of Whistler, Microsoft introduces an experimental protocol NDR64 that is optimized for transferring 64-bit data. NDR64 is not backward compatible with the DCE protocol.

The dce protocol is compatible with OSF DEC's NDR transfer syntax. This protocol is optimized for transferring 32-bit data.

The ndr64 protocol is currently supported only when used in conjunction with the /win64 switch. If a ndr64 only client tries to connect to a dce-only server, or vice versa, the call is rejected with RPC_S_UNSUPPORTED_TRANS_SYN.

The all option creates a stub that may use any available protocol. For 32-bit stubs, the only protocol currently available is dce. For 64-bit stubs, created using the /win64 switch, both dce and ndr64 are available.

Example

midl /protocol all /win64 filename.idl

See Also

/<system>


/proxy

The /proxy switch specifies the name of the interface proxy file for a COM interface.

Switch Options

midl /proxy proxy_file_name
proxy_file_name
Specifies a file name that overrides the default interface proxy file name. File names can be explicitly quoted using double quotes (") to prevent the shell from interpreting the special characters.

Remarks

The specified file name replaces the default file name obtained by adding _P.C to the name of the IDL file. The /proxy switch does not affect RPC interfaces.

If proxy_file_name does not include an explicit path, the file is written to the current directory or to the directory specified by the /out switch. An explicit path in proxy_file_name overrides the /out switch specification.

For a more detailed description of the interface proxy file and other files generated by the MIDL compiler, see General MIDL Command-line Syntax.

Example

midl /proxy my_proxy.c filename.idl

See Also

General MIDL Command-line Syntax, /header, /iid, /out


/robust

The /robust switch tells the MIDL compiler to generate additional error-checking information, which the NDR engine uses to perform integrity checks at run time.

midl /robust {/Oicf | /Oif }

Switch Options

/Oicf
/Oif
These switches are identical in their functionality. They specify the codeless proxy method of marshaling and use fast format strings for improved performance. See /Oi.

Remarks

Using the /robust switch generates additional information that allows the Network Data Representation (NDR) engine to perform run-time error checking on correlated arguments in dynamic arrays, unions, and in out interface pointers in DCOM applications. The /robust switch is only available under Windows 2000.

A correlated argument is an argument that uses any of the attributes that allow the size of a data object to be determined at run time: size_is, length_is, first_is, last_is, max_is, switch_is, and iid_is. In accordance with the OSF-DCE specification for the wire representation, this correlated argument appears in two different places. For example, consider a typical usage of the size_is attribute:

HRESULT Func1([in] long Size,
              [in, size_is(Size)]BAR_TYPE *pBarType);

In this example, the client passes a long that specifies the size of a block of BAR_TYPEs (in terms of number of BAR_TYPES elements), and a pointer to the actual block of BAR_TYPEs. The Size argument correlates with the pBarType argument. In accordance with the OSF-DCE specification, the Size argument is represented twice on the wire—first as itself and then with the array of BAR_TYPE elements that represent the pBarType argument. Each argument is unmarshaled independently, according to its own wire representation. Normally, the Size argument and its copy, which is used to represent part of the other argument, have the same values. However, if the Size argument becomes corrupted (for example, when the block of BAR_TYPES is larger than what was allocated), the server application may stop responding, because it uses the value of the Size argument to measure incoming data.

The /robust switch is required to implement valid range checking with the range attribute.

Example

midl /robust /Oicf filename.idl

See Also

General MIDL Command-line Syntax, /robust, /Oi, range


/rpcss

The /rpcss switch, when specified, acts as though the enable_allocate attribute was specified on all operations of the interface.

Switch Options

midl /rpcss

Remarks

In default mode, the RpcSs package is enabled only if either the procedure or interface has the enable_allocate attribute or the /rpcss switch is specified on the command line. In /osf mode, the server-side stub enables the RpcSs allocation package.

Example

midl /rpcss filename.idl

See Also

General MIDL Command-line Syntax, Interface Definition (IDL) File, enable_allocate, /osf


/saux

This switch is obsolete and, if used, results in an error.


/savePP

When the /savePP directive is specified, the MIDL compiler does not delete the output of the C/C++ preprocessor.

midl /savePP

Switch Options

Remarks

This switch enables developers to discern what is being parsed by the MIDL compiler, and is useful for debugging. The output of the preprocessor is written to one or more temporary files in the directory indicated by the TEMP environment variable. The name of the output file, or files, follows a naming convention of MID*.tmp. Note that a single compile may generate several preprocessed input streams; this is because importing an IDL file, as opposed to using #include, causes a separate preprocessor run.

See Also

/cpp_cmd, /cpp_opt, /nocpp, /no_cpp


/server

The /server switch directs the MIDL compiler to generate server-side C source files for an RPC interface.

midl /server { stub | none }
stub
Generates the server-side files.
none
Does not generate server-side files.

Remarks

When the /server switch is not specified, the MIDL compiler generates the server stub file. This switch does not affect OLE interfaces.

The none option causes no files to be generated.

The /server switch takes precedence over the /sstub switch.

Examples

midl /server none
midl /server stub

See Also

General MIDL Command-line Syntax, /client, /sstub


/sstub

The /sstub switch specifies the name of the server stub file for an RPC interface.

Switch Options

midl /sstub stub_file_name
stub_file_name
Specifies a file name that overrides the default server stub file name. File names can be explicitly quoted using double quotes (") to prevent the shell from interpreting the special characters.

Remarks

The specified file name replaces the default file name. By default, the file name is obtained by adding _S.C to the name of the IDL file. This switch does not affect OLE interfaces.

When you are importing files, the specified file name applies to only one stub file — the stub file that corresponds to the IDL file specified on the command line.

If stub_file_name does not include an explicit path, the file is written to the current directory or the directory specified by the /out switch. An explicit path in stub_file_name overrides the /out switch specification.

The /server none switch takes precedence over the /sstub switch.

Example

midl /sstub my_sstub.c filename.idl

See Also

General MIDL Command-line Syntax, /cstub, /header, /out


/syntax_check

The /syntax_check switch indicates that the compiler checks only syntax and does not generate output files.

Switch Options

midl /syntax_check
midl /Zs

Remarks

This switch overrides all other switches that specify information about output files.

You can also specify syntax-checking mode with the MIDL compiler option /Zs.

Examples

midl /Zs filename.idl
midl /syntax_check filename.idl

See Also

General MIDL Command-line Syntax, /Zs


/<system>

The /<system> switch directs the MIDL compiler to generate a type library for the specified system. The default is the current operating system.

Switch Options

midl /<system>
system
Can be one of the following.
System specifier | Operating system(s)
win32 | Windows 9x, Windows NT, Windows 2000
win64 | 64 bit Windows

Remarks

The /<system> switch is functionally the same as the MIDL /env option and is recognized by the MIDL compiler solely for backward compatibility with MkTypLib. If you are generating a new makefile, use the /env switch.

Example

midl /win32 filename.idl

See Also

General MIDL Command-line Syntax, /env


/target

The /target switch enables the MIDL compiler to enable optimizations available only on recent versions of Windows. The /target switch automatically activates additional switches.

Switch Options

midl /target level
level
Specifies the target level, such as NT40, NT50, or NT51.

Remarks

The /target switch automatically activates additional switches, based on the operating system, as specified in the following table:

Operating system | /target level | Switches Activated
Windows NT 4.0 | NT40 | /Oicf /error all /env win32
Windows 2000 | NT50 | /Oicf /error all /robust
Whistler | NT51 | /Oicf /error all /robust /protocol all

When targeting Windows 95 (with DCOM installed), Windows 98, or Windows Millennium, use the following:

/target NT40

To ensure a stub runs on the system specified by the /target switch, MIDL issues an error when a feature available only on a more recent version of Windows is present. The following table specifies the minimum /target level required to enable the feature. Higher target levels include all features from lower target levels.

Minimum required /target level | Features
NT40 | The /Oicf optimization mode [user_marshal] pipes Floating point types in /Oi mode.
NT50 | /robust [message] [async] [async_uuid] [notify] in /Oi or /Oicf mode. [encode] or [decode] in /Oicf mode.
NT51 | /protocol ndr64 64-bit support [partial_ignore]

Example

midl /target NT50

See Also

General MIDL Command-line Syntax, /osf


/tlb

The /tlb switch specifies a file name for the type library generated by the MIDL compiler.

Switch Options

midl /tlb filename
filename
Specifies filename as the name of the output type library (TLB) file. By default, if the /tlb switch is not used, the TLB file has the same name as the IDL file, with the extension .TLB.

Example

midl /tlb newname.tlb

See Also

General MIDL Command-line Syntax, /notlb


/U

The /U switch removes any previous definition of a name by passing the name to the C preprocessor as if by a #undefine directive.

Switch Options

midl /Uname
name
Specifies a defined name to be passed to the C preprocessor as if by a #undefine directive. The name is predefined by the C preprocessor or previously defined by the user.

Remarks

Multiple /U directives can be used in a command line. White space between the /U switch and the undefined name is optional.

When the /cpp_cmd switch is present and the /cpp_opt switch is not, the MIDL compiler concatenates the string specified by the /cpp_cmd switch with the /I, /D, and /U options and uses this concatenated string to invoke the C preprocessor for each IDL and ACF source file. The MIDL compiler switch /U is ignored when the MIDL compiler switch /no_cpp or /cpp_opt is specified.

Example

midl /UUNICODE filename.idl

See Also

General MIDL Command-line Syntax, /cpp_cmd, /cpp_opt, /D, /I, /no_cpp


/use_epv

The /use_epv switch directs the MIDL compiler to generate server stub code that calls the server application routine through an entry-point vector (epv), rather than by a static call.

Switch Options

midl /use_epv

Remarks

Typically, applications require static linkage to the server application routine. The MIDL compiler generates such a call by default. However, if an application requires the server stub to call the server application routine by using the epv, the /use_epv switch must be specified. When the /use_epv switch is specified, the MIDL compiler generates a default epv. This default epv is then used if the application does not register another epv through the RpcServerRegisterIf call.

Example

midl /use_epv filename.idl

See Also

General MIDL Command-line Syntax, Interface Definition (IDL) File, /no_default_epv, RpcServerRegisterIf


/version_stamp

The /version_stamp switch suppresses the generation of macros that specify the minimum required version number of the RPC header file, Rpcndr.h.

New MIDL features might require additional definitions to compile the stub correctly, so the stub has macros that check compatibility between MIDL binary files and the build environment. You might need to use this switch if you move MIDL to a different build environment than the one in which you first installed the MIDL binary files.

Note that mixing build environments is not supported.

Switch Options

midl /version_stamp


/W

The /W switch specifies the warning level of the MIDL compiler. The warning level indicates the severity of the warning.

Switch Options

midl /Wlevel
level
Specifies the warning level, an integer in the range 0 through 4. There is no space between the /W switch and the digit indicating the warning-level value.

Remarks

Warning levels range from 1 to 4, with a value of zero meaning to display no warning information. The highest-severity warning is level 1. The following table describes the warnings for each warning level.

Warning level | Description | Example
W0 | No warnings. |
W1 | Severe warnings that can cause application errors. | No binding handle specified, unattributed pointers, conflicting switches.
W2 | May cause problems in the user's operating environment. | Identifier length exceeds 31 characters. No default union arm specified.
W3 | Reserved. |
W4 | Lowest warning level. | Non-ANSI C constructs.

Warnings are different from errors. Errors cause the MIDL compiler to halt processing of the IDL file. Warnings cause the MIDL compiler to emit an informational message and continue processing the IDL file.

The warning level set by the /W switch can be used with the /WX switch to cause the MIDL compiler to halt processing of the IDL file.

The /W switch behaves the same as the /warn switch.

Examples

midl /W2 filename.idl
midl /W4 bar.idl

See Also

General MIDL Command-line Syntax, /warn


/warn

The /warn switch specifies the warning level of the MIDL compiler.

Switch Options

midl /warnlevel
level
Specifies the warning level, an integer in the range 0 through 4. There is no space between the /warn switch and the digit indicating the warning-level value.

Remarks

The warning level indicates the severity of the warning. Warning levels range from 1 to 4, with a value of zero meaning to display no warning information. The highest severity warning is level 1. The following table describes the warnings for each warning level.

Warning level | Description | Example
0 | No warnings. |
1 | Severe warnings that can cause application errors. | No binding handle specified, unattributed pointers, conflicting switches.
2 | May cause problems in the user's operating environment. | Identifier length exceeds 31 characters. No default union arm specified.
3 | Reserved. |
4 | Lowest warning level. | Non-ANSI C constructs.

Warnings are different from errors. Errors cause the MIDL compiler to halt processing of the IDL file. Warnings cause the MIDL compiler to emit an informational message and continue processing the IDL file.

The warning level set by the /warn switch can be used with the WX switch to cause the MIDL compiler to halt processing of the IDL file.

The /warn switch behaves the same as the /W switch.

Examples

midl /warn2 filename.idl
midl /warn4 bar.idl

See Also

General MIDL Command-line Syntax


/WX

The /WX switch instructs the MIDL compiler to handle all errors at the given warning level as errors.

Switch Options

midl /WX

Remarks

If the /WX switch is specified and the /Wn switch is not specified, all warnings at the default level, level 1, are treated as errors.

The /Wn switch directs the compiler to display all warnings at level n and /WX directs the compiler to handle all warnings as errors. The combination of these two switches directs the compiler to handle all warnings at level n as errors.

Errors are different from warnings. Errors cause the MIDL compiler to halt processing of the IDL file. Warnings cause the MIDL compiler to emit an informational message and continue processing the IDL file.

Warning-level zero (0) directs the MIDL compiler to suppress warning information. When the /W0 and /WX switches are combined, the MIDL compiler suppresses all warning information. In this case, the /WX switch has no effect.

Examples

midl /WX filename.idl
midl /W3 /WX filename.idl

See Also

General MIDL Command-line Syntax, /W


/Zp

The /Zp switch is the same as the /pack option.

Switch Options

midl /Zp packing_level
packing_level
Specifies the packing level of structures in the target system. The packing-level value can be set to 1, 2, 4, or 8.

Remarks

The /Zp switch designates the packing level of structures in the target system. The packing-level value corresponds to the /Zp option value used by the Microsoft C/C++ compiler. For more information, see your Microsoft C/C++ programming documentation.

Specify the same packing level when you invoke the MIDL compiler and the C compiler.

The default packing level used when neither the /Zp nor /pack switch is specified is 8, in both Win32 and Win64 build environments..

Note Do not use /Zp1 or /Zp2 on MIPS or Alpha platforms and do not use /Zp4 or /Zp8 on 16-bit platforms. Depending on the data type and memory location assigned by the C compiler at run time, this can result in a data misalignment exception on MIPS and Alpha platforms. On MS-DOS platforms, the C compiler will not ensure the alignment at 4 or 8, and so the application may terminate.

Example

midl /Zp4 filename.idl

See Also

General MIDL Command-line Syntax, /pack


/Zs

The /Zs switch indicates that the compiler only checks syntax and does not generate output files.

Switch Options

midl /Zs
midl /syntax_check

Remarks

This switch overrides all other switches that specify information about output files.

You can also specify syntax-checking mode with the MIDL compiler switch /syntax_check.

Examples

midl /Zs filename.idl
midl /syntax_check filename.idl

See Also

General MIDL Command-line Syntax, /syntax_check


MIDL Language Reference

This section provides a reference entry for each keyword in the Microsoft® Interface Definition Language (MIDL). Reference entries are also included for important language productions and concepts.

The reference entries are arranged in alphabetical order, and each entry includes syntax, examples, descriptions, and cross-references.

aggregatable | helpstringcontext | nonextensible
allocate | helpstringdll | notify
appobject | hidden | object
arrays | hyper | odl
async | id | oleautomation
async_uuid | idempotent | optimize
auto_handle | ignore | optional
bindable | iid_is | out
Boolean | immediatebind | out_of_line
broadcast | implicit_handle | partial_ignore
byte | import | pipe
byte_count | importlib | pointer_default
call_as | in | pragma
callback | include | propget
char | in_line | propput
coclass | int | propputref
code | __int3264 | ptr
comm_status | __int64 | public
const | interface | range
context_handle | last_ise | readonly
context_handle_noserialize | lcid | ref
context_handle_serialize | length_is | represent_as
control | library | requestedit
cpp_quote | licensed | restricted
custom | local | retval
decode | long | shape
default | max_is | short
defaultbind | maybe | signed
defaultcollelem | message | size_is
defaultvalue | midl_pragma warning | small
defaultvtable | midl_user_allocate | source
dispinterface | midl_user_free | strict_context_handle
displaybind | min_is | string
dllname(str) | module | struct
double | ms_union | switch
dual | ncacn_at_dsp | switch_is
enable_allocate | ncacn_dnet_nsp | switch_type
encode | ncacn_http | transmit_as
endpoint | ncacn_ip_tcp | typedef
entry | ncacn_nb_ipx | union
enum | ncacn_nb_nb | uidefault
error_status_t | ncacn_nb_tcp | unique
explicit_handle | ncacn_np | unsigned
fault_status | ncacn_spx | user_marshal
first_is | ncacn_vns_spp | usesgetlasterror
float | ncadg_ip_udp | uuid
force_allocate | ncadg_ipx | v1_enum
handle | ncadg_mq | vararg
handle_t | ncalrpc | version
heap | nocode | void
helpcontext | nonbrowsable | wchar_t
helpfile | noncreatable | wire_marshal
helpstring |  |


Mixed Mode Serialization of Context Handles

[This is preliminary documentation and subject to change.]

In Whistler, a single interface can accommodate both serialized and nonserialized context handles, enabling one method on an interface to access a context handle exclusively (serialized), while other methods access that context handle in shared mode (nonserialized). For more information about context handles, see the following attributes:

  • context_handle
  • context_handle_serialize
  • context_handle_noserialize

Serialized and shared mode access capabilities are comparable to read/write locking mechanisms; methods using a serialized context handle are exclusive users (writers), whereas methods using a nonserialized context handle are shared users (readers). Methods that destroy or modify the state of a context handle must be serialized. Methods that do not modify the state of a context handle, such as those methods that simply read from a context handle, can be nonserialized. Using a context handle in mixed mode can substantially improve the scalability of a server, especially when multiple threads make simultaneous calls to the same context handle.

RPC does not enforce "write lock" on methods using a context handle in shared mode, which means applications must ensure that shared mode context handles are not modified. Modification of a context handle used in shared mode can result in subtle corruptions of context handle contents, which are impossible to debug.

Changing the serialization logic of a context handle affects only the server. Also, changing the serialization logic of a context handle does not affect the wire format, and therefore, changes to serialization logic on a server do not affect existing clients' capability to interact with the server.

Using only nonserialized context handles is not recommended. Servers that use nonserialized handles are should switch to serialized access for the method that closes the context handle.

Context handles that are [out]-only are typically used by creation methods, and do not require any serialization. Therefore, any serialization attribute applied to [out]-only context handles, such as context_handle_serialize or context_handle_noserialize, is ignored by RPC.

Note Creation methods are implicitly serialized.

Examples

The following two examples show how to enable mixed mode serialization of context handles.

The first example shows how to do so in the IDL file:

typedef [context_handle] void *TestContextHandleExclusive;
typedef [context_handle] TestContextHandleExclusive TestContextHandleShared;

void
UseShared(...
          [in] TestContextHandleShared *Ctx,
          ...);

void
UseExclusive(...
             [in, out] TestContextHandleExclusive *Ctx,
             ...);

The second example shows how to enable mixed mode serialization of context handles in the ACF file:

typedef [context_handle_serialize] TestContextHandleExclusive;

typedef [context_handle_noserialize] TestContextHandleShared;

See Also

context_handle, context_handle_serialize, context_handle_noserialize


aggregatable

The [aggregatable] attribute indicates that the class supports aggregation.

[
    coclass-attribute-list,
    aggregatable
]
coclass coclass-name
{
    coclass-interface-list
}

Parameters

coclass-attribute-list
Other attributes that apply to the class.
coclass-name
The name of the class.
coclass-interface-list
A list of interfaces for the class.

Remarks

Use the [aggregatable] attribute on a coclass statement to let users know that the class supports aggregations. That is, the class allows its interfaces to be exposed by a container class as if these interfaces were the container's own interfaces.

The typeflag representation for this attribute is TYPEFLAG_FAGGREGATABLE.

Example

[
    uuid(1e196b20-1f3c-1069-996b-00dd010fe676),
    aggregatable
]
coclass Form
{
    [default] interface IForm;
    [default, source] interface IFormEvents;
}

See Also

coclass, Generating a Type Library With MIDL, ODL File Example, ODL File Syntax


allocate

The ACF type attribute [allocate] lets you customize memory allocation and deallocation for a type defined in the IDL file.

typedef [allocate (allocate-option-list) [, type-attribute-list] ] type-name;

Parameters

allocate-option-list
Specifies one or more memory-allocation options. Select one of either single_node or all_nodes, or one of either free or dont_free, or one from each pair. When you specify more than one option, separate the options with commas.
type-attribute-list
Specifies other optional ACF-type attributes. When you specify more than one type attribute, separate the options with commas.
type-name
Specifies a type defined in the IDL file.

Remarks

The [allocate] attribute has the following valid options.

Option | Description
all_nodes | Makes one call to allocate and free memory for all nodes.
Single_node | Makes many individual calls to allocate and free each node of memory.
Free | Frees memory on return from the server stub.
Dont_free | Does not free memory on return from the server stub.

By default, the stubs may allocate storage for data referenced by a unique or full pointer by calling midl_user_allocate and midl_user_free individually for each pointer.

You can optimize the speed of your application by specifying the option all_nodes. This option directs the stub to compute the size of all memory referenced through the pointer of the specified type and to make a single call to midl_user_allocate. The stub releases the memory by making one call to midl_user_free.

The dont_free option directs the MIDL compiler to generate a server stub that does not call midl_user_free for the specified type. The dont_free option allows the pointer structures to remain accessible to the server application after the remote procedure call has completed and returned to the client.

The [allocate] attribute will cause any [in, out] parameter that is a pointer to a type qualified with the all_nodes option to reallocate memory when the data is unmarshaled. It is the responsibility of the application to free the memory allocated previously for this parameter. For example:

typedef struct thistype
{
    [string] char * PTHISTYPE;
} * PTHISTYPE
HRESULT proc1 ( [in,out] PTHISTYPE * ppthistype);

The data type PTHISTYPE will be reallocated in the [out] direction by the stub before unmarshaling. Therefore, the application must free the memory it previously allocated for this parameter's data, or a memory leak will occur.

Examples

/* ACF file */
typedef [allocate(all_nodes, dont_free)] PTYPE1;
typedef [allocate(all_nodes)] PTYPE2;
typedef [allocate(dont_free)] PTYPE3;

See Also

Application Configuration File (ACF), [in], midl_user_allocate, midl_user_free, [out], typedef


appobject

The [appobject] attribute identifies the coclass as an application object, which is associated with a full EXE application.

[
    uuid(uuid-number),
    appobject
    [, coclass-attribute-list]
]
coclass classname
{
    [coclass definition]
}

Parameters

uuid-number
Specifies a universally unique identification number for the coclass.
coclass-attribute-list
Specifies zero or more attributes that apply to the coclass statement. Allowable coclass attributes are [helpstring], [helpcontext], [licensed], [version], [control], and [hidden].
classname
Specifies the name by which the component object is known in the type library.
coclass definition
Specifies statements that make up the coclass definition.

Remarks

The [appobject] attribute also indicates that the functions and properties of the coclass are globally available in the current type library.

The typeflag representation for this attribute is TYPEFLAG_FAPPOBJECT

Example

[
    uuid(1e196b20-1f3c-1069-996b-00dd010fe676),
    helpstring("Hello Class"),
    appobject
]
coclass Hello
{
    [default] interface IHello : IUnknown;
    interface IDispatch;
}

See Also

coclass, [control], Generating a Type Library With MIDL, [helpstring], [helpcontext], [hidden], [licensed], ODL File Example, ODL File Syntax, TYPEFLAGS, version


arrays

Arrays are homogenous collections of data accessed by an index or element number.

typedef [ [type-attr-list] ] type-specifier [pointer-decl] array-declarator;

typedef [ [type-attr-list] ] struct [ tag ]
{
    [ [ field-attribute-list ] ] type-specifier [pointer-decl] array-declarator;
    ...
};

typedef [ [type-attr-list] ] union [ tag ]
{
    [ case (limited-expression [ , ... ] ) ]
        [ [ field-attribute-list ] ] type-specifier [pointer-decl] array-declarator;
    [ [ default ]
        [ [ field-attribute-list ] ] type-specifier [pointer-decl] array-declarator;
    ]
};

[[ [function-attribute-list] ]] type-specifier [[pointer-decl]] function-name(
        [[ [param-attr-list] ]] type-specifier [[pointer-decl]] array-declarator
        , ...);

Parameters

type-attr-list
Specifies zero or more attributes that apply to the type. Valid type attributes include [handle], [switch_type], [transmit_as]; the pointer attribute [ref], [unique], or [ptr]; and the usage attributes [context_handle], [string], and [ignore]. Separate multiple attributes with commas.
type-specifier
Specifies the type identifier, base type, struct, union, or enum type. The type specification can include an optional storage specification.
pointer-decl
Specifies zero or more pointer declarators. A pointer declarator is the same as the pointer declarator used in C, constructed from the * designator, modifiers such as far, and the qualifier const.
array-declarator
Specifies the name of the array, followed by one of the following constructs for each dimension of the array: "[ ]", "[*]", "[const1]", or "[lower...upper]" where lower and upper are constant values that represent the lower and upper bounds. The constant lower must evaluate to zero.
tag
Specifies an optional tag for the structure or union.
field-attribute-list
Specifies zero or more field attributes that apply to the structure, union member, or function parameter. Valid field attributes include [first_is], [last_is], [length_is], [max_is], [size_is]; the usage attributes [string], and [ignore]; the pointer attributes [ref], [unique], and [ptr]; and the union attribute [switch_type]. Separate multiple field attributes with commas. Note that of the attributes listed above, [first_is], [last_is], and [ignore] are not valid for unions.
limited-expression
Specifies a C-language expression. The MIDL compiler supports conditional expressions, logical expressions, relational expressions, and arithmetic expressions. MIDL does not allow function invocations in expressions and does not allow increment and decrement operators.
function-attribute-list
Specifies zero or more attributes that apply to the function. Valid function attributes are [callback], [local]; the pointer attribute [ref], [unique], or [ptr]; and the usage attributes [string], and [context_handle].
function-name
Specifies the name of the remote procedure.
param-attr-list
Specifies the directional attributes and one or more optional field attributes that apply to the array parameter. Valid field attributes include [max_is], [size_is], [length_is], [first_is], and [last_is].

Remarks

Arrays in MIDL use a style similar to but not exactly the same as C and C++. For more information, see MIDL Arrays.

See Also

[callback], const, [context_handle], enum, [first_is], [handle], Interface Definition (IDL) File, [ignore], [last_is], [length_is], [local], [max_is], [ptr], [ref], [size_is], [string], struct, [switch_type], [transmit_as], union, [unique]


async

The [async] attribute defines a remote procedure call as an asynchronous operation.

[async, opt-acf-attributes] function-name (param-list)

Parameters

opt-acf-attributes
Specifies optional application configuration attributes.
function-name
Specifies the name of the function in the IDL file.
param-list
Specifies an optional parameter list.

Remarks

The use of this attribute requires Windows 2000.

To declare an RPC function as asynchronous, first declare the function as part of an interface definition in an IDL file. Then modify that function declaration, within the application configuration file (ACF), by applying the [async] attribute. Note that the function declaration makes no mention of the asynchronous handle and that the binding handle is the first parameter. Applying the [async] attribute in the ACF file generates the appropriate code so that when this function is called, the asynchronous server expects to receive an asynchronous handle before the other parameters.

Example:

//file:Xasync.idl
interface AsyncIface
{
    HRESULT MyAsyncFunc (
        handle_t hBinding,
        [in] int a,
        [in] int b,
        [out] int *c) ;
//other interface definitions
}
//end XAsync.idl

// file: Xasync.acf
interface AsyncIface
{
    [async] MyAsyncFunc () ;
    //any other ACF definitions
}
//end Xasync.acf

See Also

Application Configuration File (ACF), Asynchronous RPC


async_uuid

The [async_uuid] interface attribute directs the MIDL compiler to define both synchronous and asynchronous versions of a COM interface.

[
    object,
    uuid(string-uuid1),
    async_uuid(string-uuid2)[ [, interface-attribute-list]
]
interface interface-name : base-interface
{
    interface-definition
}

Parameters

string-uuid1
A UUID string, generated by the uuidgen utility, which identifies the synchronous version of the interface.
string-uuid2
A UUID string, generated by the uuidgen utility, which identifies the asynchronous version of the interface.
interface-attribute-list
Other attributes that apply to the interface as a whole. You cannot use the [version] attribute in a COM interface.
interface-name
The name of the interface.
base-interface
The interface from which this interface derives. The base interface must be IUnknown or an asynchronous interface that derives, either directly or indirectly, from IUnknown..
interface-definition
Specifies IDL statements that form the definition of the interface.

Remarks

The use of this attribute requires Windows 2000.

When you apply the [async_uuid] attribute to a COM interface (that is, an interface that has the [object] attribute), the MIDL compiler generates an asynchronous definition of the interface, in addition to the traditional, synchronous version. The asynchronous interface will have the same names as the synchronous interface, but with an "Async" prefix. The interface identifier (IID) will be the UUID specified as a parameter to the [async_uuid] attribute.

For the asynchronous interface, MIDL splits each method into separate begin and finish methods. The begin method has the synchronous method name with a "Begin_" prefix and includes all of the [in] parameters from the synchronous method. The finish method has the synchronous method's name with a "Finish_" prefix and includes all of the [out] parameters from the synchronous method. If the synchronous method has any [in, out] parameters they will be included in both the begin and finish asynchronous methods.

If an asynchronous interface method has the [call_as] attribute, MIDL will generate declarations for the begin and the finish methods. You must implement both methods.

Each asynchronous interface is a modifier on a synchronous interface and, as such, does not have a separate inheritance graph. This means that you cannot define a synchronous interface from an asynchronous interface (other than IUnknown). Nor can synchronous interfaces inherit from asynchronous interfaces. The MIDL compiler will issue an error message if you attempt either one.

Example

[
    object,
    uuid(0c733a30-2a1c-11ce-ade5-00aa0044773d),
    async_uuid(1c733a30-2a1c-11ce-ade5-00aa0044773d),
    pointer_default(unique)
]
interface IMyInterface : IUnknown
{
    /* Interface definition goes here*/
}

See Also

call_as, Defining COM Interfaces, Interface Definition (IDL) File, iid_is, in, local, object, [out], version


auto_handle

The ACF attribute [auto_handle] directs the stub to automatically establish the binding for a function that does not have an explicit binding-handle parameter.

[
    auto_handle [, interface-attribute-list]
]
interface interface-name
{
    interface-definition
}

Parameters

interface-attribute-list
Specifies zero or more attributes that apply to the interface as a whole, such as code or nocode. Separate interface attributes with commas.
interface-name
Specifies the name of the interface.
interface-definition
Specifies IDL statements that form the definition of the interface.

Remarks

The [auto_handle] attribute appears in the interface header of the ACF. It also appears in the interface header of the IDL file when you specify the MIDL compiler switch /app_config.

When the client calls a function that uses automatic binding and no binding to a server exists, the stub automatically establishes the binding. The binding is reused for subsequent calls to other functions in the interface that use automatic binding. The client application program does not have to declare or perform any processing relating to the binding handle.

When the ACF is not present or does not include the [implicit_handle] attribute, the MIDL compiler uses [auto_handle] and issues an informational message. The MIDL compiler also uses [auto_handle], if needed, to establish the initial binding for a [context_handle].

The [auto_handle] attribute can occur only if the [implicit_handle] or [explicit_handle] attribute does not occur. The [auto_handle] attribute can occur in the ACF or IDL interface header at most once.

Note You cannot use automatic binding (either with the [auto_handle] attribute, or by default) if you are processing data through pipes.

Examples

[
    auto_handle
]
interface MyInterface
{
    /* Interface definition goes here*/
}
[
    auto_handle,
    code
]
interface MyInterface
{
    /* Interface definition goes here*/
}

See Also

Application Configuration File (ACF), /app_config, [code], [explicit_handle], [context_handle], [implicit_handle], [nocode]


bindable

The [bindable] attribute indicates that the property supports data binding.

[
    interface-attribute-list
]
interface | dispinterface interface-name
{
    [bindable[, attribute-list]] returntype function-name(params)
}

Parameters

interface-attribute-list
Specifies a list of zero or more IDL attributes that apply to the interface as a whole. When two or more interface attributes are present, they must be separated by commas.
interface-name
Specifies the name of the interface.
attribute-list
Specifies zero or more attributes that apply to the function prototype for a property or a method in an interface or dispinterface. The following attributes are valid: [helpstring], [helpcontext], [string], [defaultbind], [displaybind], [immediatebind], [propget], [propput], [propputref], and [vararg]. If vararg is specified, the last parameter must be a safe array of type VARIANT. Separate multiple attributes with commas.
returntype
Specifies the return type of the function.
function-name
Specifies the name of the function to which the [bindable] attribute will be applied.
params
Function parameter list.

Remarks

By supporting data binding, the [bindable] attribute allows the client to be notified whenever a property has changed value. (If you want the client to be notified of impending changes to a property, use the [requestedit] attribute.)

Because the [bindable]attribute refers to the property as a whole, it must be specified wherever the property is defined. Therefore, you need to specify the attribute on both the property-accessing function and the property-setting function.

Flags

FUNCFLAG_FBINDABLE, VARFLAG_FBINDABLE

Examples

[
    uuid(1e196b20-1f3c-1069-996b-00dd010fe676)
]
dispinterface MyObject
{
    properties:
    methods:
        [id(1), propget, bindable, defaultbind, displaybind] long x();
        [id(1), propput, bindable,
        defaultbind, displaybind] HRESULT x(long rhs);
}

See Also

[defaultbind], dispinterface ], [displaybind], Generating a Type Library With MIDL, [helpstring], [helpcontext], [immediatebind], interface, ODL File Example, ODL File Syntax, [propget], [propput, [propputref], [requestedit], [string], Syntax, TYPEFLAGS, [vararg]


Boolean

The keyword Boolean indicates that the expression or constant expression associated with the identifier takes only the values TRUE and FALSE.

Boolean identifier-name;

Parameters

identifier-name
Specifies a valid MIDL identifier. Valid MIDL identifiers consist of up to 31 alphanumeric and/or underscore characters and must start with an alphabetic or underscore character.

Remarks

The Boolean type is one of the base types of the IDL language. The Boolean type can appear as a type specifier in const declarations, typedef declarations, general declarations, and function declarators (as a function-return-type specifier and as a parameter-type specifier). For the context in which type specifiers appear, see Interface Definition (IDL) File.

Note The Boolean base type is not compatible with the oleautomation attribute. Use VARIANT_BOOL in your Automation-compatible interfaces.

See Also

MIDL Base Types, const, Interface Definition (IDL) File, oleautomation, typedef


broadcast

The keyword [broadcast] specifies that remote procedure calls be sent to all servers on a local network.

[
    interface-attribute-list
]
interface interface-name
{
    [broadcast [, attribute-list]] returntype function-name(params)
}

Parameters

interface-attribute-list
Specifies a list of zero or more IDL attributes that apply to the interface as a whole. When two or more interface attributes are present, they must be separated by commas.
interface-name
Specifies the name of the interface.
attribute-list
Specifies additional attributes to be applied to the function. Separate multiple attributes with commas.
returntype
Specifies the return type of the function.
function-name
Specifies the name of the function to which the [broadcast] attribute will be applied.
params
Function parameter list.

Remarks

The [broadcast] keyword spcifies that the routine is always broadcasted to all the servers on the network, rather than being delivered to one particular server.The client receives output from the first reply to return successfully, while subsequent replies are discarded.

An operation with the [broadcast] attribute is implicitly an [idempotent] operation. However, the [broadcast] attribute specifies additional properties that functions with the [idempotent] attribute don't have. Specifically, functions using the [broadcast] attribute specify that the routine can be called multiple times as the result of one remote procedcure call. At the same time, they can be sent to multiple servers. This is different from the [idempotent] attribute, which specifies only that a call can be retried if it is not completed.

If a remote procedure broadcasts its call to all hosts on a local network, it must use either the ncadg_ip_udp or the ncadg_ipx protocol sequence. Note that the size of a [broadcast] packet is determined by the datagram service in use.

See Also

idempotent, Interface Definition (IDL) File, [maybe], ncadg_ip_udp, ncadg_ipx


byte

The byte keyword specifies an 8-bit data item.

byte identifier-name;

Parameters

identifier-name
Specifies a valid MIDL identifier. Valid MIDL identifiers consist of up to 31 alphanumeric and/or underscore characters and must start with an alphabetic or underscore character.

Remarks

A byte data item does not undergo any conversion for transmission on the network as a char type might.

The byte type is one of the base types of the interface definition language (IDL). The byte type can appear as a type specifier in const declarations, typedef declarations, general declarations, and function declarators (as a function-return-type specifier and as a parameter-type specifier). For the context in which type specifiers appear, see Interface Definition (IDL) File.

See Also

MIDL Base Types, char, const, Interface Definition (IDL) File, typedef


byte_count

The [byte_count] attribute is a parameter attribute that associates a size, in bytes, with the memory area indicated by the pointer.

[ function-attribute-list ] function-name(
    [byte_count(length-variable-name)] parameter-name);
    ...);

Parameters

function-attribute-list
Specifies zero or more ACF function attributes.
function-name
Specifies the name of the function defined in the IDL file. The function name is required.
length-variable-name
Specifies the name of the [in]-only parameter that specifies the size, in bytes, of the memory area referenced by parameter-name.
parameter-name
Specifies the name of the [out]-only pointer parameter defined in the IDL file.

Remarks

The ACF attribute [byte_count] represents a Microsoft extension to DCE IDL. Therefore, this attribute is not available when you use the MIDL compiler switch /osf.

Memory referenced by the pointer parameter is contiguous and is not allocated or freed by the client stubs. This feature of the [byte_count] attribute lets you create a persistent buffer area in client memory that can be reused during more than one call to the remote procedure.

The ability to turn off the client stub memory allocation lets you tune the application for efficiency. For example, the [byte_count] attribute can be used by service-provider functions that use Microsoft RPC. When a user application calls the service-provider API and sends a pointer to a buffer, the service provider can pass the buffer pointer on to the remote function. The service provider can reuse the buffer during multiple remote calls without forcing the user to reallocate the memory area.

The memory area can contain complex data structures that consist of multiple pointers. Because the memory area is contiguous, the application does not have to make several calls to individually free each pointer and structure. Instead, it can allocate or free the memory area with one call to the memory allocation or free routine.

The buffer must be an [out]-only parameter, while the buffer length in bytes must be an [in]-only parameter.

Note Specify a buffer that is large enough to contain all the [out] parameters. Because of hidden padding, use overestimates rather than exact counts. For example, pointers are unmarshaled on a 4-byte aligned boundary on 32-bit platforms and on an 8-byte boundary on 64-bit platforms. Therefore, the alignment padding the stubs will perform must be accounted for in the space for the buffer. In addition, packing levels used during C-language compilation can vary. Use a byte count value that accounts for additional packing bytes added for the packing level used during C-language compilation. A safe practice that covers both 32 bit platforms and 64 bit platforms is to assume that each object going into the big memory block starts at an address that is a multiple of 8.

Examples

/* IDL file */
HRESULT proc1([in] unsigned long length,
              [out] struct my_struct * pMyStruct);

/* ACF file */
proc1([byte_count(length)] pMyStruct);

See Also

Application Configuration File (ACF), [in], [length_is], /osf, [out], [size_is]


call_as

The [call_as] attribute enables you to map a function that cannot be called remotely to a remote function.

[call_as (local-proc), [ , operation-attribute-list ] ] operation-name ;

Parameters

local-proc
Specifies an operation-defined routine.
operation-attribute-list
Specifies one or more attributes that apply to the operation. Separate multiple attributes with commas.
operation-name
Specifies the named operation presented to the application.

Remarks

The ability to map a function that cannot be called remotely to a remote function is particularly helpful in interfaces that have numerous parameter types that cannot be transmitted across the network. Rather than using many [represent_as] and [transmit_as] types, you can combine all the conversions using [call_as] routines. You supply the two [call_as] routines (client side and server side) to bind the routine between the application calls and the remote calls.

The [call_as] attribute can be used for object interfaces. In this case, the interface definition can be used for local calls as well as remote calls because [call_as] allows an interface that can't be accessed remotely to be transparently mapped to a remote interface. The [call_as] attribute cannot be used with /osf mode.

For example, assume that the routine f1 in object interface IFace requires numerous conversions between the user calls and what is actually transmitted. The following examples describe the IDL and ACF files for interface IFace:

In the IDL file for interface IFace:

[local] HRESULT f1 ( <users parameter list> )
[call_as( f1 )] long Remf1( <remote parameter list> );

In the ACF for interface IFace:

[call_as( f1 )] Remf1();

This causes the generated header file to define the interface using the definition of f1, yet it also provides stubs for Remf1.

The MIDL compiler will generate the following Vtable in the header file for interface IFace:

struct IFace_vtable
{
    HRESULT ( * f1) ( <users parameter list> );
    /* Other vtable functions. */
};

The client-side proxy would then have a typical MIDL-generated proxy for Remf1, while the server side stub for Remf1 would be the same as the typical MIDL-generated stub:

HRESULT IFace_Remf1_Stub ( <parameter list> )
{
    // Other function code.

    /* instead of IFace_f1 */
    invoke IFace_f1_Stub ( <remote parameter list> );

    // Other function code.
}

Then, the two [call_as] bond routines (client side and server side) must be manually coded:

HRESULT f1_Proxy ( <users parameter list> )
{
    // Other function code.

    Remf1_Proxy ( <remote parameter list> );

    // Other function code.
}

long IFace_f1_Stub ( <remote parameter list> )
{
    // Other function code.

    IFace_f1 ( <users parameter list> );

    // Other function code.
    }

For object interfaces, these are the prototypes for the bond routines.

For client side:

<local_return_type>  <interface>_<local_routine>_proxy(
    <local_parameter_list> );

For server side:

<remote_return_type>  <interface>_<local_routine>_stub(
    <remote_parameter_list> );

For nonobject interfaces, these are the prototypes for the bond routines.

For client side:

<local_return_type>  <local_routine> ( <local_parameter_list> );

For server side:

<local_return_type>  <interface>_v<maj>_<min>_<local_routine> (
    <remote_parameter_list> );

See Also

/osf, represent_as, transmit_as


callback

The [callback] attribute declares a static callback function that exists on the client side of the distributed application. Callback functions provide a way for the server to execute code on the client.

[callback [ , function-attr-list] ] type-specifier [ptr-declarator] function-name(
        [ [attribute-list] ] type-specifier [declarator]
        , ...);

Parameters

function-attr-list
Specifies zero or more attributes that apply to the function. Valid function attributes are [local]; the pointer attribute [ref], [unique], or [ptr]; and the usage attributes [string], [ignore], and [context_handle]. Separate multiple attributes with commas.
type-specifier
Specifies a base_type, struct, union, enum type, or type identifier. An optional storage specification can precede type-specifier.
ptr-declarator
Specifies zero or more pointer declarators. A pointer declarator is the same as the pointer declarator used in C; it is constructed from the * designator, modifiers such as far, and the qualifier const.
function-name
Specifies the name of the remote procedure.
attribute-list
Specifies zero or more directional attributes, field attributes, usage attributes, and pointer attributes appropriate for the specified parameter type. Separate multiple attributes with commas.
declarator
Specifies a standard C declarator such as identifiers, pointer declarators, and array declarators. For more information, see Array and Sized-Pointer Attributes, arrays, and Arrays and Pointers. The parameter-name identifier is optional.

Remarks

The [callback] function is useful when the server must obtain information from the client. If server applications were supported on Windows 3.x, the server could make a call to a remote procedure on the Windows 3.x server to obtain the needed information. The callback function accomplishes the same purpose and lets the server query the client for information in the context of the original call.

Callbacks are special cases of remote calls that execute as part of a single thread. A callback is issued in the context of a remote call. Any remote procedure defined as part of the same interface as the static callback function can call the callback function.

Only the connection-oriented and local-protocol sequences support the callback attribute. If an RPC interface uses a connectionless (datagram) protocol sequence, calls to procedures with the callback attribute will fail.

Handles cannot be used as parameters in callback functions. Because callbacks always execute in the context of a call, the binding handle used by the client to make the call to the server is also used as the binding handle from the server to the client.

Callbacks can nest to any depth.

Example

[callback] HRESULT DisplayString([in, string] char * p1);

See Also

arrays, MIDL Base Types, const, [context_handle], enum, Interface Definition (IDL) File, [ignore], [local], /osf, [ref], [ptr], [string], struct, union, [unique]


char

The char keyword specifies an 8-bit data item.

char identifier-name;

Parameters

identifier-name
Specifies a valid MIDL identifier. Valid MIDL identifiers consist of up to 31 alphanumeric and/or underscore characters and must start with an alphabetic or underscore character.

Remarks

The keyword char identifies a data item that has 8 bits. To the MIDL compiler, a char is unsigned by default and is synonymous with unsigned char.

In this version of Microsoft RPC, the character translation tables that convert between ASCII and EBCDIC are built into the run-time libraries and cannot be changed by the user.

The char type is one of the base types of the interface definition language (IDL). The char type can appear as a type specifier in const declarations, typedef declarations, general declarations, and function declarators (as a function-return-type specifier and a parameter-type specifier). For the context in which type specifiers appear, see Interface Definition (IDL) File.

DCE IDL compilers do not accept the keyword signed applied to char types. Therefore, this feature is not available when you use the MIDL compiler /osf switch.

See Also

MIDL Base Types, byte, /char, const, Interface Definition (IDL) File, /osf, signed, [string], typedef, unsigned, wchar_t


coclass

The coclass statement provides a listing of the supported interfaces for a component object.

[
    coclass-attribute-list
]
coclass classname
{
    [
        interface-attributes
    ]
    [interface | dispinterface] interfacename
    {
        . . .
    }
}

Parameters

coclass-attribute-list
The [uuid] attribute is required on a coclass. This is the same [uuid] that is registered as a CLSID in the system registration database. The [helpstring], [helpcontext], [licensed], [version], [control], [hidden], and [appobject] attributes are accepted, but not required, before a coclass definition.
classname
Name by which the common object is known in the type library.
interface-attributes
Optional attributes for the interface or dispinterface. The [source], [default], and [restricted] attributes are accepted on an interface or dispinterface within a coclass.
interfacename
Either an interface declared with the interface keyword, or a dispinterface declared with the dispinterface keyword.

Remarks

The Microsoft® Component Object Model defines a class as an implementation that allows QueryInterface between a set of interfaces.

Examples

[
    uuid(1e196b20-1f3c-1069-996b-00dd010fe676),
    version(1.0),
    helpstring("A class"),
    helpcontext(2481), appobject
]
coclass myapp
{
    [source] interface IMydocfuncs : IUnknown;
    dispinterface DMydocfuncs;
};

[
    uuid(12345678-1234-1234-1234-123456789ABC)
]
coclass mycoclass
{
    [restricted] interface iface1;
    interface iface2;
}

See Also

[appobject], [control], [default], dispinterface, Generating a Type Library With MIDL, ODL File Example, [helpstring], [helpcontext], [hidden], [interface], [licensed], ODL File Syntax, [restricted], [source], TYPEFLAGS, [uuid], [version]


code

The [code] attribute causes client stub code to be generated for remote functions.

[
    code [ , ACF-interface-attributes ]
]
interface interface-name
{
    [ include filename-list ; ]
    [ typedef [type-attribute-list] typename; ]
    [ [code [ , ACF-function-attributes ]] function-name (
            [ ACF-parameter-attributes ] parameter-name,
        ...);
    ]
    ...
}

Parameters

ACF-interface-attributes
Specifies a list of one or more attributes that apply to the interface as a whole. Valid attributes include either [auto_handle] or [implicit_handle] and either [code], [nocode], or [optimize]. When two or more interface attributes are present, they must be separated by commas.
interface-name
Specifies the name of the interface.
filename-list
Specifies a list of one or more C-header file names, separated by commas. You must supply the full file name, including the extension.
type-attribute-list
Specifies a list of one or more attributes, separated by commas, that apply to the specified type. Valid type attributes include [allocate] and [represent_as].
typename
Specifies a type defined in the IDL file. Type attributes in the ACF can be applied only to types previously defined in the IDL file.
ACF-function-attributes
Specifies zero or more attributes that apply to the function as a whole, such as [comm_status]. Function attributes are enclosed in square brackets. Separate multiple function attributes with commas.
function-name
Specifies the name of the function as defined in the IDL file.
ACF-parameter-attributes
Specifies ACF attributes that apply to a parameter. Note that zero, one, or more attributes can be applied to the parameter. Separate multiple parameter attributes with commas. ACF parameter attributes are enclosed in square brackets.
parameter-name
Specifies a parameter of the function as defined in the IDL file. Each parameter for the function must be specified in the same sequence and with the same name as defined in the IDL file.

Remarks

The [code] attribute can appear in the ACF header or be applied to an individual function.

When the [code] attribute appears in the ACF header, client stub code is generated for all remote functions that do not have the [nocode] function attribute. You can override the [code] attribute in the header for an individual function by specifying the [nocode] attribute as a function attribute.

When the [code] attribute appears in the remote function's attribute list, client stub code is generated for the function. Client stub code is not generated when:

  • The ACF header includes the [nocode] attribute.
  • The [nocode] attribute is applied to the function.
  • The [local] attribute applies to the function in the interface file.

Either [code] or [nocode] can appear in the interface or function attribute list, but the one you choose can appear only once in the list.

See Also

Application Configuration File (ACF), [allocate], [auto_handle], [code], [comm_status], [implicit_handle], [local], [nocode], [optimize], [represent_as]


comm_status

The [comm_status] attribute causes an error code to be returned when a communication error occurs during the execution of a function.

[comm_status [ , ACF-function-attributes ] ]
    error_status_t function-name(
        [ [ ACF-parameter-attributes ] ] parameter-name
        , ...);

[ [ ACF-function-attributes ] ] function-name(
    [comm_status [ , ACF-parameter-attributes ] ] error_status_t name
    , ...);

Parameters

ACF-function-attributes
Specifies zero or more ACF function attributes, such as [comm_status] and [nocode]. Function attributes are enclosed in square brackets. Zero or more attributes can be applied to a function. Separate multiple function attributes with commas. Note that if [comm_status] appears as a function attribute, it cannot also appear as a parameter attribute.
function-name
Specifies the name of the function as defined in the IDL file.
ACF-parameter-attributes
Specifies attributes that apply to a parameter. Note that zero, one, or more attributes can be applied to the parameter. Separate multiple parameter attributes with commas. Parameter attributes are enclosed in square brackets. IDL parameter attributes, such as directional attributes, are not allowed in the ACF. Note that if [comm_status] appears as a parameter attribute, it cannot also appear as a function attribute.
parameter-name
Specifies the parameter for the function as defined in the IDL file. Each parameter for the function must be specified in the same sequence, using the same name as defined in the IDL file.

Remarks

The [comm_status] attribute can be used as either a function attribute or as a parameter attribute, but it can appear only once per function. It can be applied either to the function or to one parameter in each function.

The [comm_status] attribute can be applied only to functions that return the type error_status_t. When a communication error occurs during the execution of the function, an error code is returned.

When [comm_status] is used as a parameter attribute, the parameter must be defined in the IDL file and must be an [out] parameter of type error_status_t. When a communication error occurs during the execution of the function, the parameter is set to the error code. When the remote call is completed successfully, the procedure sets the value.

It is possible for both the [comm_status] and [fault_status] attributes to appear in a single function, either as function attributes or parameter attributes. If both attributes are function attributes or if they apply to the same parameter and no error occurs, the function or parameter has the value error_status_ok. Otherwise, it contains the appropriate [comm_status] or [fault_status] value. Because values returned for [comm_status] are different from the values returned for [fault_status], the returned values are readily interpreted.

See Also

Application Configuration File (ACF), error_status_t, [fault_status], [nocode], [out]


const

The const keyword modifies the type of a type declaration or the type of a function parameter, preventing the value from varying.

const const-type identifier = const-expression ;

[ typedef [ , type-attribute-list ] ] const const-type declarator-list;

[ typedef [ , type-attribute-list ] ] pointer-type const declarator-list;

[ [ function-attr-list ] ] type-specifier [ ptr-decl ] function-name(
    [ [ parameter-attribute-list ] ] ) const;

const-type [declarator], [ [ parameter-attribute-list ] ] pointer-type const [declarator], ...);

Parameters

const-type
Specifies a valid MIDL integer, character, string, or Boolean type. Valid MIDL types include small, short, long, char, char *, wchar_t, wchar_t *, byte, byte *, and void *. The integer and character types can be signed or unsigned.
identifier
Specifies a valid MIDL identifier. Valid MIDL identifiers consist of up to 31 alphanumeric and/or underscore characters and must start with an alphabetic or underscore character.
const-expression
Specifies an expression, identifier, or numeric or character constant appropriate for the specified type: constant integer literals or constant integer expressions for integer constants; Boolean expressions that can be computed at compilation for Boolean types; single-character constants for char types; and string constants for [string] types. The void * type can be initialized only to NULL.
type-attribute-list
Specifies one or more attributes that apply to the type.
pointer-type
Specifies a valid MIDL pointer type.
declarator and declarator-list
Specifies standard C declarators, such as identifiers, pointer declarators, and array declarators. For more information, see Array and Sized-Pointer Attributes, arrays, and Arrays and Pointers. The declarator-list consists of one or more declarators, separated by commas. The parameter-name identifier in the function declarator is optional.
function-attr-list
Specifies zero or more attributes that apply to the function. Valid function attributes are [callback], [local]; the pointer attribute [ref], [unique], or [ptr]; and the usage attributes [string], [ignore], and [context_handle].
type-specifier
Specifies a base_type, struct, union, enum type, or type identifier. An optional storage specification can precede type-specifier.
ptr-decl
Specifies zero or more pointer declarators. A pointer declarator is the same as the pointer declarator used in C. It is constructed from the * designator, modifiers such as far, and the qualifier const.
function-name
Specifies the name of the remote procedure.
parameter-attribute-list
Specifies zero or more directional attributes, field attributes, usage attributes, and pointer attributes appropriate for the specified parameter type. Separate multiple attributes with commas.

Remarks

MIDL allows you to declare constant integer, character, string, and Boolean types in the interface body of the IDL file. Const type declarations are reproduced in the generated header file as #define directives.

DCE IDL compilers do not support constant expressions. Therefore, this feature is not available when you use the MIDL compiler /osf switch.

A previously defined constant can be used as the assigned value of a subsequent constant. The value of a constant integral expression is automatically converted to the respective integer type in accordance with C conversion rules.

The value of a character constant must be a single-quoted ASCII character. When the character constant is the single-quote character itself ('), the backslash character (\) must precede the single-quote character, as in \'.

The value of a character-string constant must be a double-quoted string. Within a string, the backslash (\) character must precede a literal double-quote character ( " ), as in \". Within a string, the backslash character (\) represents an escape character. String constants can consist of up to 255 characters.

The value NULL is the only valid value for constants of type void *. Any attributes associated with the const declaration are ignored.

The MIDL compiler does not check for range errors in const initialization. For example, when you specify "const short x = 0xFFFFFFFF;" the MIDL compiler does not report an error and the initializer is reproduced in the generated header file.

Examples

const void *  p1        = NULL;
const char    my_char1  = 'a';
const char    my_char2  = my_char1;
const wchar_t my_wchar3 = L'a';
const wchar_t * pszNote = L"Note";
const unsigned short int x = 123;

typedef [string] const char *LPCSTR;

HRESULT GetName([out] wchar_t * const pszName );

See Also

arrays, MIDL Base Types, Boolean, byte, [callback], char, const, [context_handle], enum, Interface Definition (IDL) File, [ignore], [local], long, /osf, [ptr], [ref], short, signed, small, [string], struct, union, [unique], unsigned, void, wchar_t


context_handle

The [context_handle] attribute identifies a binding handle that maintains context, or state information, on the server between remote procedure calls.

typedef [context_handle [ , type-attribute-list ] ] type-specifier declarator-list;

[context_handle [, function-attr-list ] ] type-specifier [ptr-decl] function-name(
    [ [parameter-attribute-list] ] type-specifier [declarator], ...);

[ [ function-attr-list ] ] type-specifier [ ptr-decl ] function-name(
    [context_handle [ , parameter-attribute-list ] ] type-specifier [declarator], ...);

[ void __RPC_USER context-handle-type_rundown (
    context-handle-type); ]

Parameters

type-attribute-list
Specifies one or more attributes that apply to the type.
type-specifier
Specifies a pointer type or a type identifier. An optional storage specification can precede type-specifier.
declarator and declarator-list
Specifies standard C declarators, such as identifiers, pointer declarators, and array declarators. The declarator for a context handle must include at least one pointer declarator. For more information, see Array and Sized-Pointer Attributes, arrays, and Arrays and Pointers. The declarator-list consists of one or more declarators, separated by commas. The parameter-name identifier in the function declarator is optional.
function-attr-list
Specifies zero or more attributes that apply to the function. Valid function attributes are [callback], [local]; the pointer attribute [ref], [unique], or [ptr]; and the usage attributes [string], [ignore], and [context_handle].
ptr-decl
Specifies zero or more pointer declarators. A pointer declarator is the same as the pointer declarator used in C; it is constructed from the * designator, modifiers such as far, and the qualifier const.
function-name
Specifies the name of the remote procedure.
parameter-attribute-list
Specifies zero or more directional attributes, field attributes, usage attributes, and pointer attributes appropriate for the specified parameter type. Separate multiple attributes with commas.
context-handle-type
Specifies the identifier that specifies the context handle type as defined in a typedef declaration that takes the [context_handle] attribute. The rundown routine is optional.

Note Whistler: A single interface can accommodate both serialized and nonserialized context handles, enabling one method on an interface to access a context handle exclusively (serialized), while other methods access that context handle in shared mode (nonserialized). These access capabilities are comparable to read/write locking mechanisms; methods using a serialized context handle are exclusive users (writers), whereas methods using a nonserialized context handle are shared users (readers). Methods that destroy or modify the state of a context handle must be serialized. Methods that do not modify the state of a context handle, such as those methods that simply read from a context handle, can be nonserialized. Note that creation methods are implicitly serialized.

Remarks

The [context_handle] attribute can appear as an IDL typedef type attribute, as a function return type attribute, or as a parameter attribute. When you apply the [context_handle] attribute to a type definition, you must also provide a context rundown routine. See Server Context Rundown Routine for details.

When you use the MIDL compiler in default (/ms_ext) mode, a context handle can be any pointer type selected by the user, as long as it complies with the requirements for context handles described here. The data associated with such a context handle type is not transmitted on the network and should only be manipulated by the server application. DCE IDL compilers restrict context handles to pointers of type void *. Therefore this feature is not available when you use the MIDL compiler /osf switch.

As with other handle types, the context handle is opaque to the client application, and any data associated with it is not transmitted. On the server, the context handle serves as a handle on active context, and all data associated with the context handle type is accessible.

To create a context handle, the client passes to the server an [out], [ref] pointer to a context handle. (The context handle itself can have a NULL or non-NULL value—as long as its value is consistent with its pointer attributes. For example, when the context handle type has the [ref] attribute applied to it, it cannot have a NULL value.) Another binding handle must be supplied to accomplish the binding until the context handle is created. When no explicit handle is specified, implicit binding is used. When no [implicit_handle] attribute is present, an auto handle is used.

The remote procedure on the server creates an active context handle. The client must use that context handle as an [in] or [in, out] parameter in subsequent calls. An [in]-only context handle can be used as a binding handle, so it must have a non-NULL value. An [in]-only context handle does not reflect state changes on the server.

On the server, the called procedure can interpret the context handle as needed. For example, the called procedure can allocate heap storage and use the context handle as a pointer to this storage.

To close a context handle, the client passes the context handle as an [in], [out] argument. The server must return a NULL context handle when it is no longer maintaining context on behalf of the caller. For example, if the context handle represents an open file and the call closes the file, the server must set the context handle to NULL and return it to the client. A NULL value is invalid as a binding handle on subsequent calls.

A context handle is only valid for one server. When a function has two handle parameters and the context handle is not NULL, the binding handles must refer to the same address space.

When a function has an [in] or an [in, out] context handle, its context handle can be used as the binding handle. In this case, implicit binding is not used and the [implicit_handle] or [auto_handle] attribute is ignored.

The following restrictions apply to context handles:

  • Context handles cannot be array elements, structure members, or union members. They can only be parameters.
  • Context handles cannot have the [transmit_as] or [represent_as] attribute.
  • Parameters that are pointers to [out] context handles must be [ref] pointers.
  • An [in] context handle can be used as the binding handle and cannot be NULL.
  • An [in, out context handle can be NULL on input, but only if the procedure has another explicit handle parameter. If there are no other explicit non-NULL context handle parameters, the [in, out] context handle cannot be NULL.
  • A context handle cannot be used with callbacks.

Example

typedef [context_handle] void * PCONTEXT_HANDLE_TYPE;
short RemoteFunc1([out] PCONTEXT_HANDLE_TYPE * pCxHandle);
short RemoteFunc2([in, out] PCONTEXT_HANDLE_TYPE * pCxHandle);
void __RPC_USER PCONTEXT_HANDLE_TYPE_rundown (PCONTEXT_HANDLE_TYPE);

See Also

arrays, [auto_handle], [callback], Client Context Reset, const, Context Handles, [handle], Binding and Handles, [ignore], [implicit_handle, [in], [local], Multi-threaded Clients and Context Handles, /ms_ext, [out], [ptr], [ref], [represent_as, RpcSsDestroyClientContext, Server Context Rundown Routine, [string], [transmit_as], typedef, [unique], void


context_handle_noserialize

The [context_handle_noserialize] attribute guarantees that a context handle will never be serialized, regardless of the application's default behavior.

typedef [context_handle_noserialize [ , type-acf-attribute-list ] ] context-handle-type

[context_handle_noserialize [, function-acf-attribute-list ] ] function-name( );

function-name(
    [context_handle_noserialize
    [ , parameter-acf-attribute-list ] ] param-name );

Parameters

type-acf-attribute-list
Any other ACF attributes that apply to the type.
context-handle-type
The identifier that specifies the context handle type, as defined in a typedef declaration. This is the type that receives the [context_handle] attribute in the IDL file.
function-acf-attribute-list
Any additional ACF attributes that apply to the function.
function-name
The name of the function as defined in the IDL file.
parameter-acf-attribute-list
Any other ACF attributes that apply to the parameter.
param-name
The name of the parameter as defined in the IDL file.

Remarks

The IDL [context_handle] attribute identifies a binding handle that maintains context, or state information, on the server between remote procedure calls. The attribute can appear as an IDL typedef type attribute, as a function return type attribute, or as a parameter attribute.

By default, calls on context handles are serialized. An application can call RpcSsDontSerializeContext to override this default behavior. Using the [context_handle_noserialize] attribute in an ACF file guarantees that calls on this particular context handle will not be serialized, regardless of the calling application's behavior. Providing a context rundown routine is optional.

This attribute is available in MIDL version 5.0.

Note Whistler: A single interface can accommodate both serialized and nonserialized context handles, enabling one method on an interface to access a context handle exclusively (serialized), while other methods access that context handle in shared mode (nonserialized). These access capabilities are comparable to read/write locking mechanisms; methods using a serialized context handle are exclusive users (writers), whereas methods using a nonserialized context handle are shared users (readers). Methods that destroy or modify the state of a context handle must be serialized. Methods that do not modify the state of a context handle, such as those methods that simply read from a context handle, can be nonserialized. Note that creation methods are implicitly serialized.

Example

typedef [context_handle_noserialize] PCONTEXT_HANDLE_TYPE;
HRESULT RemoteFunc([context_handle_noserialize] pCxHandle);

See Also

ACF Attributes, [context_handle_serialize], [context_handle], Context Handles, RpcSsDontSerializeContext, Server Context Rundown Routine, Multi-threaded Clients and Context Handles, typedef


context_handle_serialize

The [context_handle_serialize] attribute guarantees that a context handle will always be serialized, regardless of the application's default behavior.

typedef [context_handle_serialize [ , type-acf-attribute-list ] ] context-handle-type;

[context_handle_serialize [, function-acf-attribute-list ] ] function-name( );

function-name(
    [context_handle_serialize [ , parameter-acf-attribute-list ] ] param-name );

Parameters

type-acf-attribute-list
Any other ACF attributes that apply to the type.
context-handle-type
The identifier that specifies the context handle type, as defined in a typedef declaration. This is the type that receives the [context_handle] attribute in the IDL file.
function-acf-attribute-list
Any additional ACF attributes that apply to the function.
function-name
The name of the function as defined in the IDL file.
parameter-acf-attribute-list
Any other ACF attributes that apply to the parameter.
param-name
The name of the parameter as defined in the IDL file.

Remarks

The IDL [context_handle] attribute identifies a binding handle that maintains context or state information on the server between remote procedure calls. The attribute can appear as an IDL typedef type attribute, as a function return type attribute, or as a parameter attribute.

By default, calls on context handles are serialized, but an application can call RpcSsDontSerializeContext to override this default behavior. Using the [context_handle_serialize] attribute in an ACF file guarantees that calls on this particular context handle will be serialized, even if the calling application has overridden the default serialization. A context rundown routine is optional.

This attribute is available in MIDL version 5.0.

Note Whistler: A single interface can accommodate both serialized and nonserialized context handles, enabling one method on an interface to access a context handle exclusively (serialized), while other methods access that context handle in shared mode (nonserialized). These access capabilities are comparable to read/write locking mechanisms; methods using a serialized context handle are exclusive users (writers), whereas methods using a nonserialized context handle are shared users (readers). Methods that destroy or modify the state of a context handle must be serialized. Methods that do not modify the state of a context handle, such as those methods that simply read from a context handle, can be nonserialized. Note that creation methods are implicitly serialized.

Example

typedef [context_handle_serialize] PCONTEXT_HANDLE_TYPE;
HRESULT RemoteFunc([context_handle_serialize] pCxHandle);

See Also

Application Configuration File (ACF), ACF Attributes, [context_handle_noserialize], [context_handle], Context Handles, RpcSsDontSerializeContext, Server Context Rundown Routine, Multi-threaded Clients and Context Handles, typedef


control

The [control] attribute identifies a coclass or library as a COM control, from which a container site will derive additional type libraries or component object classes.

[
    uuid,
    control
    [, attribute-list]
]
library | coclass lib-or-coclassname
{
    definitions
}

Parameters

attribute-list
Specifies zero or more attributes that apply to the library or coclass statement. Separate multiple attributes with commas.
lib-or-coclassname
Specifies the name of the library or coclass.
definitions
MIDL statements that specify the members of the library or coclass.

Remarks

This attribute allows you to mark type libraries that describe controls so they will not be displayed in type browsers intended for nonvisual objects.

Flags

TYPEFLAG_FCONTROL, LIBFLAG_FCONTROL

Example

[
    uuid(12345678-1234-1234-1234-123456789ABC),
    helpstring("Hello 2.1 COM Control Library"),
    control,version(2.1)
]
library Hello
{
    /* library definitions */
}

See Also

ODL File Syntax, ODL File Example, Generating a Type Library With MIDL, TYPEFLAGS, coclass, library


cpp_quote

The cpp_quote keyword instructs MIDL to emit the specified string, without the quote characters, into the generated header file.

cpp_quote("string")

Parameters

string
Specifies a quoted string that is emitted in the generated header file. The string must be quoted to prevent expansion by the C preprocessor.

Remarks

C-language preprocessing directives that appear in the IDL file are processed by the C compiler's preprocessor. The #define directives in the IDL file are available during MIDL compilation but are not available to the C compiler.

For example, when the preprocessor encounters the directive "#define WINDOWS 4", the preprocessor replaces all occurrences of "WINDOWS" in the IDL file with "4". The symbol "WINDOWS" is not available during C-language compilation.

To allow the C-preprocessor macro definitions to pass through the MIDL compiler to the C compiler, use the #pragma midl_echo or cpp_quote directive. These directives instruct the MIDL compiler to generate a header file that contains the parameter string with the quotation marks removed. The #pragma midl_echo and cpp_quote directives are equivalent.

The MIDL compiler places the strings specified in the cpp_quote and pragma directives into the header file in the sequence in which they are specified in the IDL file, and relative to other interface components in the IDL file. The strings should usually appear in the IDL file interface body section after all import operations.

Examples

cpp_quote("#include \"myfile.h\" ")
cpp_quote("#define UNICODE")

See Also

Interface Definition (IDL) File, import, pragma


custom

The [custom] attribute creates a user-defined attribute.

[custom(attribute-id, attribute-value),attribute-list] element-type element-name

Parameters

attribute-id
The GUID for the custom attribute.
attribute-value
The value that the attribute holds. The value must be one that can be put into a VARIANT type.
attribute-list
Other attributes, such as [uuid] and [helpstring], that apply to this element.
element-type
The type of element to which the custom attribute apples. This can be a library statement, type information, a variable, a function, or a parameter. You cannot use a custom attribute on a member of a coclass.
element-name
The name of the element.

Remarks

Use the [custom] attribute to define your own attribute. For example, you might create a string-valued attribute that gives the ProgID for a class.

To retrieve a custom attribute value call one of the following:

  • ITypeLib2::GetCustData(rguid, pvarVal)
  • ITypeInfo2::GetCustData(rguid, pvarVal)
  • ITypeInfo2::GetFuncCustData(index, rguid, pvarVal)
  • ITypeInfo2::GetVarCustData(index, rguid, pvarval)
  • ITypeInfo2::GetParamCustData(indexFunc, indexParam, rguid, pvarVal)

See Also

Generating a Type Library With MIDL, [helpstring], library, ODL File Example, ODL File Syntax, [uuid]


decode

The [decode] attribute specifies that a procedure or a type needs de-serialization support.

[
    decode
    [ , interface-attribute-list]
]
interface interface-name
{
    interface-definition
}

[ decode [ , op-attribute-list] ] proc-name(...);

typedef [decode [ , type-attribute-list] ] type-name;

Parameters

interface-attribute-list
Specifies other attributes that apply to the interface as a whole.
interface-name
Specifies the name of the interface.
interface-definition
Specifies IDL statements which form the definition of the interface.
op-attribute-list
Specifies other operational attributes that apply to the procedure such as [encode].
proc-name
Specifies the name of the procedure.
type-attribute-list
Specifies other attributes such as [encode] and [allocate].
type-name
Specifies a type defined in the IDL file.

Remarks

The [decode] attribute causes the MIDL compiler to generate code that an application can use to retrieve serialized data from a buffer. The [encode] attribute provides serialization support, generating the code to serialize data into a buffer.

Use the [encode] and [decode] attributes in an ACF to generate serialization code for procedures or types defined in the IDL file of an interface. When used as an interface attribute, [decode] applies to all types and procedures defined in the IDL file. When used as a type attribute, [decode] applies only to the specified type. When used as an operational attribute, [decode] applies only to that procedure.

For more information about using this serialization support, see Serialization Services and [encode].

See Also

[allocate], [encode]


default

The [default] attribute Indicates that the interface or dispinterface, defined within a coclass, represents the default programmability interface. This attribute is intended for use by macro languages.

[
    uuid(uuid-number)
    [, attribute-list]
]
coclass coclass-name
{
    [ default [, optional-interface-attribute] ];
    interface | dispinterface interface-name;
}

Parameters

uuid-number
Specifies a universally unique identification number for the coclass.
attribute-list
Specifies additional coclass attributes. Separate multiple attributes with commas.
coclass-name
Specifies the name by which other software components can reference this coclass.
optional-interface-attribute
The [source] attribute, which specifies that an interface or dispinterface is outgoing, is the only other attribute that can be used here.
interface-name
Specifies the name of the interface.

Remarks

A coclass may have at most two [default] members. One represents the outgoing (source) interface or dispinterface, and the other represents the incoming (sink) interface or dispinterface. If the [default] attribute is not specified for any member of the coclass or cotype, the first outgoing and incoming members that do not have the [restricted] attribute are treated as the defaults.

Flags

IMPLTYPEFLAG_FDEFAULT

Example

[
    uuid(12345678-1234-1234-1234-123456789ABC),
    helpstring("Hello Class"),appobject
]
coclass Hello
{
    [default] interface IHello:IUnknown;
    interface IDispatch;
};

See Also

coclass, TYPEFLAGS, ODL File Syntax, ODL File Example, Generating a Type Library With MIDL, [restricted], [source]


defaultbind

The [defaultbind] attribute indicates the single, bindable property that best represents the object.

[
    interface-attribute-list
]
interface | dispinterface interface-name
{
    [bindable, defaultbind [, attribute-list]] returntype function-name(params)
}

Parameters

interface-attribute-list
Specifies a list of one or more attributes that apply to the interface as a whole. When two or more interface attributes are present, they must be separated by commas.
interface-name
Specifies the name of the interface.
attribute-list
Specifies a list of one or more attributes that apply to the function. When two or more interface attributes are present, they must be separated by commas.
returntype
Specifies the return type of the function.
function-name
Specifies the name of the function to which the [defaultbind] attribute will be applied.
params
Function parameter list.

Remarks

Properties that have the [defaultbind] attribute must also have the [bindable] attribute. Only one property in an interface or dispinterface can have the [defaultbind] attribute.

This attribute is used by containers that have a user model involving binding to an object rather than binding to a property of an object. An object can support data binding but not have this attribute.

Flags

FUNCFLAG_FDEFAULTBIND, VARFLAG_FDEFAULTBIND

Example

[
    uuid(12345678-1234-1234-1234-123456789ABC)
]
interface MyObject : IUnknown
{
    properties:
    methods:
        [id(1), propget, bindable,
         defaultbind, displaybind] long Size(void);

        [id(1), propput, bindable,
         defaultbind, displaybind] HRESULT Size([in]long lSize);
}

See Also

[bindable], Generating a Type Library With MIDL, ODL File Example, ODL File Syntax, TYPEFLAGS


defaultcollelem

The [defaultcollelem] attribute flags a property as an accessor function for an element of the default collection.

[property-attribute-list, defaultcollelem] return-type property-name(prop-param-list)

Parameters

property-attribute-list
Other attributes that apply to the property.
return-type
Specifies the return type of the function.
property-name
The name of the property.
prop-param-list
A list of zero or more parameters associated with the property.

Remarks

The [defaultcollelem] attribute is used for Visual Basic® code optimization. If a member of an interface or dispinterface is flagged as an accessor function, then the call will go directly to that member.

Use of [defaultcollelem] must be consistent for a property. For example, if you use the attribute on a Get property, it must also be present on a Let property.

Typeflags Representation

The presence of FUNCFLAG_FDEFAULTCOLLELEM or VARFLAG_FDEFAULTCOLLELEM.

Example

//A form has a button on it named Button1.
//To enable use of the property syntax and efficient use of the !
//syntax, the form describes itself in type info this way.
[
    dual,
    uuid(12345678-1234-1234-1234-123456789ABC),
    helpstring("This is IForm"),
    restricted
]
interface IForm1: IForm
{
    [propget, defaultcollelem] HRESULT Button1(
        [out, retval] Button *Value);
}

//User code may access the button using property syntax or ! syntax.

Sub Test()
Dim f as Form1
Dim b1 As Button
Dim b2 As Button

Set f = Form1

Set b1 = f.Button1        ' Property syntax
Set b = f!Button1        ' ! syntax
End Sub

See Also

ODL File Syntax, ODL File Example, Generating a Type Library With MIDL


defaultvalue

The [defaultvalue] attribute allows you to specify a default value for a typed optional parameter.

interface interface-name
{
    return-type function-name(
        mandatory-param-list,
        [[attribute-list,] defaultvalue(value)] param-type param-name
        [ , optional-param-list]);
}

Parameters

interface-name
Specifies the name of the interface.
return-type
Specifies the return type of the function.
function-name
Specifies the name of the function to which the [defaultvalue] attribute will be applied.
mandatory-param-list
Specifies on or more required parameters.
attribute-list
Specifies a list of one or more attributes, separated by commas, that apply to the parameter.
param-type
Indicates the type of the optional parameter.
param-name
Specifies the name of the optional parameter.
optional-param-list
Specifies zero or more additional parameters, each of which must have a default value.

Remarks

The default value you specify for the parameter can be any constant, or an expression that resolves to a constant, that can be represented by a VARIANT. Specifically, you cannot apply the [defaultvalue] attribute to a parameter that is a structure, an array, or a SAFEARRAY.type.

The MIDL compiler accepts the following parameter ordering (from left-to-right):

  1. Required parameters (parameters that do not have the [defaultvalue] or [optional] attributes),
  2. optional parameters with or without the [defaultvalue] attribute,
  3. parameters with the [optional] attribute and without the [defaultvalue] attribute,
  4. [lcid] parameter, if any,
  5. [retval] parameter

Examples

interface IFace : IUnknown
{
    HRESULT Ex1([defaultvalue(44)] LONG i);
    HRESULT Ex2([defaultvalue(44)] SHORT i);
    HRESULT Ex3([defaultvalue("Hello")] BSTR i);
...
};

interface QueryDef : IUnknown
{
    HRESULT OpenRecordset( [in, defaultvalue(DBOPENTABLE)]
    LONG Type,
    [out,retval] Recordset **pprst);
}
//  Type is now known to be a LONG type (good for browser in VBA and
//  good for a C/C++ programmer) and has a default value of
//  DBOPENTABLE

See Also

dispinterface, Generating a Type Library With MIDL, interface, [lcid], [optional], ODL File Example, ODL File Syntax, [retval], TYPEFLAGS


defaultvtable

The [defaultvtable] attribute defines an interface as the default Vtable interface

[
    coclass-attribute-list,
    defaultvtable
]
coclass coclass-name
{
    coclass-interface-list
}

Parameters

coclass-attribute-list
Other attributes that apply to the class. The [source] and [uuid] attributes are required.
coclass-name
The name of the class.
coclass-interface-list
A list of interfaces for the class.

Remarks

A default Vtable interface cannot be a dispinterface—it must be a dual or Vtable or interface. If the interface is a dual interface, then sinks can assume that they will receive events through Vtable.

A class can be both a default source interface and a default Vtable source interface as shown in the example. In this case an advise sink should use IID_IDISPATCH to receive dispatch events and use the interface identifier to receive Vtable events.

Typeflag Representation

The presence of IMPLTYPEFLAG_FDEFAULTVTABLE.

Example

[
    dual,
    uuid(12345678-1234-1234-1234-123456789ABC),
    restricted
]
interface IForm: IDispatch
{
    [propget]HRESULT Backcolor([out, retval] long *Value);
    [propput] HRESULT Backcolor([in] long Value);
    [propget] HRESULT Name([out, retval] BSTR *Value);
    [propput] HRESULT Name([in] BSTR Value);}

[
    dual,
    uuid(1e196b20-1f3c-1069-996b-00dd010fe676),
    restricted
]
interface IFormEvents: IDispatch
{
    HRESULT Click();
    HRESULT Resize();}

    [
        uuid(1e123456-1f3c-1069-996b-123456789ABC)
    ]
    coclass Form
    {
        [default] interface IForm;
        [default, defaultvtable, source] interface IFormEvents;
    }
}

See Also

coclass, ODL File Syntax, ODL File Example, Generating a Type Library With MIDL, [source], [uuid]


dispinterface

The dispinterface statement defines a set of properties and methods on which you can call IDispatch::Invoke. A dispinterface may be defined by explicitly listing the set of supported methods and properties (Syntax 1), or by listing a single interface (Syntax 2).

[
    [attributes]
]
dispinterface dispinterface-name
{
    properties:
        property-list
    methods:
        method-list
};

[
    [attributes]
]
dispinterface dispinterface-name
{
    interface interface-name
};

Parameters

attributes
Specifies attributes that apply to the entire dispinterface. The following attributes are accepted: [helpstring], [helpcontext], [helpfile], [hidden], [nonextensible], [oleautomation], [restricted], [uuid], and [version].
dispinterface-name
The name by which the dispinterface is known in the type library. This name must be unique within the type library.
property-list
(Syntax 1) An optional list of properties supported by the object, declared in the form of variables. This is the short form for declaring the property functions in the methods list. See the comments section for details.
method-list
(Syntax 1) A list comprising a function prototype for each method and property in the dispinterface. Any number of function definitions can appear in methlist. A function in methlist has the following form:

[attributes] returntype methname(params);

The following attributes are accepted on a method in a dispinterface: [helpstring], [helpcontext], [propget], [propput], [propputref], [string], and [vararg]. If [vararg] is specified, the last parameter must be a safe array of VARIANT type.

The parameter list is a comma-delimited list, each element of which has the following form:

[attributes] type paramname

The type can be any declared or built-in type, or a pointer to any type. Attributes on parameters are:

[in], [out], [optional], [string]

interface-name
(Syntax 2) The name of the interface to declare as an IDispatch interface.

The MIDL compiler accepts the following parameter ordering (from left-to-right):

  1. Required parameters (parameters that do not have the [defaultvalue] or [optional] attributes),
  2. optional parameters with or without the [defaultvalue] attribute,
  3. parameters with the [optional] attribute and without the [defaultvalue] attribute,
  4. [lcid] parameter, if any,
  5. [retval] parameter

Remarks

Method functions are specified exactly as described in the reference page for module except that the [entry] attribute is not allowed. Note that STDOLE32.TLB (STDOLE.TLB on 16-bit systems) must be imported, because a dispinterface inherits from IDispatch.

You can declare properties in either the properties or methods lists. Declaring properties in the properties list does not indicate the type of access the property supports (that is, get, put, or putref). Specify the [readonly] attribute for properties that don't support put or putref. If you declare the property functions in the methods list, functions for one property all have the same identifier.

Using the first syntax, the properties: and methods: tags are required. The [id] attribute is also required on each member. For example:

properties:
    [id(0)] int Value;    // Default property.
methods:
    [id(1)] HRESULT Show();

Unlike interface members, dispinterface members cannot use the retval attribute to return a value in addition to an HRESULT error code. The [lcid] attribute is likewise invalid for dispinterfaces, because IDispatch::Invoke passes an LCID. However, it is possible to redeclare an interface that uses these attributes.

Using the second syntax, interfaces that support IDispatch and are declared earlier in an ODL script can be redeclared as IDispatch interfaces as follows:

dispinterface helloPro
{
    interface hello;
};

The preceding example declares all the members of hello and all the members that hello inherits as supporting IDispatch. In this case, if hello were declared earlier with [lcid] and [retval] members that returned HRESULTs, MkTypLib would remove each [lcid] parameter and HRESULT return type, and instead mark the return type as that of the [retval] parameter.

The properties and methods of a dispinterface are not part of the VTBL of the dispinterface. Consequently, CreateStdDispatch and DispInvoke cannot be used to implement IDispatch::Invoke. The dispinterface is used when an application needs to expose existing non-VTBL functions through Automation. These applications can implement IDispatch::Invoke by examining the dispidMember parameter and directly calling the corresponding function.

Examples

[
    uuid(1e196b20-1f3c-1069-996b-00dd010fe676),
    version(1.0),
    helpstring("Useful help string."),
    helpcontext(2480)
]
dispinterface MyDispatchObject
{
    properties:
        [id(1)] int x;    //An integer property named x
        [id(2)] BSTR y;   //A string property named y
    methods:
        [id(3)] HRESULT show();    //No arguments, no result
        [id(11)] int computeit(int inarg, double *outarg);
};

[
    uuid(1e123456-1f3c-1069-996b-00dd010fe676)
]
dispinterface MyObject
{
    properties:
    methods:
        [id(1), propget, bindable, defaultbind, displaybind] long x();

        [id(1), propput, bindable, defaultbind,
         displaybind] HRESULT x(long rhs);
}

See Also

[bindable], [defaultbind], [displaybind], [helpcontext], [helpfile], [helpstring], [hidden], [in], interface, TYPEFLAGS, ODL File Syntax, ODL File Example, Generating a Type Library With MIDL, [optional], [out], [nonextensible], [propget], [propput], [propputref], [oleautomation], [restricted], [string], [uuid], [vararg], [version]


displaybind

The [displaybind] attribute indicates a property that should be displayed to the user as bindable.

[
    [interface-attribute-list]
]
interface | dispinterface interface-name
{
    [bindable, displaybind [ , attribute-list]] returntype function-name(params)
}

Parameters

interface-attribute-list
Specifies an optional list of interface attributes.
interface-name
The name of the interface.
attribute-list
Specifies a list of one or more attributes, separated by commas, that apply to the function-return type.
returntype
Specifies the return type of the function.
function-name
Specifies the name of the function to which the [displaybind] attribute will be applied.
params
Function parameter list.

Remarks

Properties that have the [displaybind] attribute must also have the [bindable] attribute. An object can support data binding but not have this attribute.

Flags

FUNCFLAG_FDISPLAYBIND, VARFLAG_FDISPLAYBIND

Example

[
    uuid(1e196b20-1f3c-1069-996b-00dd010fe676)
]
interface MyObject : IUnknown
{
    properties:
    methods:
        [id(1), propget, bindable, defaultbind,
         displaybind] long Size(void);

        [id(1), propput, bindable, defaultbind,
         displaybind] HRESULT Size([in]long lSize);
}

See Also

[bindable], TYPEFLAGS, ODL File Syntax, ODL File Example, Generating a Type Library With MIDL


dllname(str)

The [dllname] attribute defines the name of the DLL that contains the entry points for a module.

[
    uuid(uuid-number),
    dllname("filename")
    [, optional-attribute-list]
]
module modulename
{
    elementlist
};

Parameters

uuid-number
Specifies a universally unique identification number for the module.
filename
Specifies a NULL-terminated string which contains the full path to the Dll file.
optional-attribute-list
Specifies a list of zero or more MIDL interface attributes.
modulename
Specifies the name which other software components can use to refer to the module.
elementlist
Specifies one or more module element definition statements.

Remarks

The [dllname] attribute is required on a module.

Examples

[
    uuid(1e196b20-1f3c-1069-996b-00dd010fe676),
    helpstring("A meaningful comment"),
    dllname("HANDY.DLL")
]
module HandyStuff
{
    /* Module content definitions */
};

See Also

module, [entry], ODL File Syntax, ODL File Example, Generating a Type Library With MIDL


double

The double keyword designates a 64-bit floating-point number.

double identifier-name;

Parameters

identifier-name
Specifies a valid MIDL identifier. Valid MIDL identifiers consist of up to 31 alphanumeric and/or underscore characters and must start with an alphabetic or underscore character.

Remarks

The double type is one of the base types of the interface definition language (IDL). This type can appear as a type specifier in typedef declarations, general declarations, and function declarators (as a function-return-type specifier and a parameter-type specifier). For the context in which type specifiers appear, see Interface Definition (IDL) File.

The double type cannot appear in const declarations.

See Also

MIDL Base Types, const, float, Interface Definition (IDL) File, typedef


dual

The [dual] attribute identifies an interface that exposes properties and methods through IDispatch and directly through the VTBL.

[
    uuid(uuid-number),
    oleautomation,
    dual
    [ , optional-attribute-list]
]
interface interface-name
{
    . . .
};

Parameters

uuid-number
Specifies a universally unique identification number for the interface
optional-attribute-list
Specifies a list of zero or more additional MIDL attributes.
interface-name
The name of the interface to which the [dual] attribute will be applied.

Remarks

Interfaces identified by the [dual] attribute must be compatible with Automation and be derived from IDispatch. This attribute is not allowed on dispinterfaces.

The [dual] attribute creates an interface that is both a IDispatch interface and a Component Object Model (COM) interface. The first seven entries of the VTBL for a dual interface are the seven members of IDispatch, and the remaining entries are for direct access to members of the dual interface. All the parameters and return types specified for members of a dual interface must be Automation-compatible types.

All members of a dual interface must pass an HRESULT as the function return value. Members, such as property accessor functions, that need to return other values, should specify the last parameter as [out], [retval], indicating an output parameter that returns the value of the function. In addition, members that need to support multiple locales should pass an [lcid parameter].

A dual interface provides for both the speed of direct VTBL binding and the flexibility of IDispatch binding. For this reason, dual interfaces are recommended whenever possible.

Note If your application accesses object data by casting the this pointer within the interface call, you should check the VTBL pointers in the object against your own VTBL pointers to ensure that you are connected to the appropriate proxy.

Specifying [dual] on an interface implies that the interface is compatible with Automation, and therefore causes both the TYPEFLAG_FDUAL and TYPEFLAG_FOLEAUTOMATION flags to be set.

Flags

TYPEFLAG_FDUAL, TYPEFLAG_FOLEAUTOMATION

Example

[
    uuid(1e196b20-1f3c-1069-996b-00dd010fe676),
    oleautomation, dual
]
interface IHello : Idispatch
{
    //diverse and sundry properties and methods defined here
};

See Also

Generating a Type Library With MIDL, interface, [lcid], [oleautomation], ODL File Syntax, ODL File Example, [out], [retval]


enable_allocate

When the keyword [enable_allocate] appears in an ACF, it specifies that the server stub code should enable the stub memory management environment.

[
    enable_allocate
    [ , optional-attribute-list]
]
interface interface-name
{
    . . .
};

Parameters

optional-attribute-list
Specifies a list of zero or more additional MIDL attributes.
interface-name
The name of the interface to which the [dual] attribute will be applied.

Remarks

In default mode, the server stub enables the memory environment only when the [enable_allocate] attribute is used. The memory management environment must be enabled before memory can be allocated using RpcSmAllocate. In osf mode (when you compile using the /osf switch), the stub enables this environment automatically when the remote operation includes full pointers or pointers that provide for the stub or the user to allocate memory, or on request when the [enable_allocate] attribute is used.

The client side stub may be sensitive to the Rpcss memory management environment. If a sensitive client stub is executed when the Rpcss package is disabled, the default user allocator/deallocators are called (for example, midl_user_allocate/midl_user_free). When enabled, the Rpcss package uses the allocator/deallocator pair from the package. In the default mode, the client is sensitive only when the [enable_allocate] attribute is used. Typically, the client side stub operates in the disabled environment. In osf mode (when you compile using the /osf switch), the client is always sensitive to the Rpcss memory management environment and, therefore, the [enable_allocate] attribute will not affect the client stubs.

See Also

Application Configuration File (ACF), midl_user_allocate, midl_user_free, /osf, RpcSmDisableAllocate, RpcSmEnableAllocate, RpcSmFree


encode

The [encode] attribute specifies that a procedure or a data type needs serialization support.

[
    encode
    [ , interface-attribute-list]
]
interface interface-name
{
    interface-definition
}

[ encode [ , op-attribute-list] ] proc-name

typedef [encode [ , type-attribute-list] ] type-name

Parameters

interface-attribute-list
Specifies other attributes that apply to the interface as a whole.
interface-name
Specifies the name of the interface.
interface-definition
Specifies IDL statements which form the definition of the interface.
op-attribute-list
Specifies other operational attributes that apply to the procedure such as [decode].
proc-name
Specifies the name of the procedure.
type-attribute-list
Specifies other attributes that apply to the type such as [decode] and [allocate].
typename
Specifies a type defined in the IDL file.

Remarks

The [encode] attribute causes the MIDL compiler to generate code that an application can use to serialize data into a buffer. The [decode] attribute generates the code for unmarshaling data from a buffer.

Use the [encode] and [decode] attributes in an ACF to generate serialization code for procedures or types defined in the IDL file of an interface. When used as an interface attribute, [encode] applies to all the types and procedures defined in the IDL file. When used as an operational attribute, [encode] applies only to the specified procedure. When used as a type attribute, [encode] applies only to the specified type.

When the [encode] or [decode] attribute is applied to a procedure, the MIDL compiler generates a serialization stub in a similar fashion as remote stubs are generated for remote routines. A procedure can be either a remote or a serializing procedure, but it cannot be both. The prototype of the generated routine is sent to the STUB.H file while the stub itself goes into the STUB_C.C file.

The MIDL compiler generates two functions for each type the [encode] attribute applies to, and one additional function for each type the [decode] attribute applies to. For example, for a user-defined type named MyType, the compiler generates code for the MyType_Encode, MyType_Decode, and MyType_AlignSize functions. For these functions, the compiler writes prototypes to STUB.H and source code to STUB_C.C.

For additional information about serialization handles and encoding or decoding data, see Serialization Services.

Examples

/*
    ACF file example;
    Assumes MyType1, MyType2, MyType3, MyProc1, MyProc2, MyProc3 defined
    in IDL file
    MyType1, MyType2, MyProc1, MyProc2 have encode and decode
    serialization support
    MyType3 and MyProc3 have encode serialization support only
*/
[
    encode,
    implicit_handle(handle_t bh)
]
interface regress
{
    typedef [ decode ] MyType1;
    typedef [ encode, decode ] MyType2;
    [ decode ] MyProcc1();
    [ encode ] MyProc2();
}

See Also

[allocate], [decode]


endpoint

The [endpoint] attribute specifies a well-known port or ports (communication endpoints) on which servers of the interface listen for calls.

endpoint("protocol-sequence:[endpoint-port]" [ , ...] )

Parameters

protocol-sequence
Specifies a character string that represents a valid combination of an RPC protocol (such as "ncacn"), a transport protocol (such as "tcp"), and a network protocol (such as "ip"). For a list of valid protocol sequences, see Protocol Sequence Constants.
endpoint-port
Specifies a string that represents the endpoint designation for the specified protocol family. The syntax of the port string is specific to each protocol sequence.

Remarks

The [endpoint] attribute specifies a transport family such as the TCP/IP connection-oriented protocol, a NetBIOS connection-oriented protocol, or the named-pipe connection-oriented protocol. Use of the [endpoint] attribute is consistent with other methods for adding an endpoint, and does not provide additional or special services for the endpoint; it simply provides a shortcut for calling the API.

Note Specifying an endpoint in the .IDL interface definition does not restrict access to the interface to the specified endpoint. Adding an endpoint to the .IDL interface definition allows the interface to be called through any endpoint in that process, and allows the endpoint to be used to call other interfaces in that process.

The protocol-sequence value determines the valid values for the endpoint-port. The MIDL compiler checks only general syntax for the endpoint-port entry. Port specification errors are reported by the run-time libraries. For information about the allowed values for each protocol sequence, see the Protocol Sequence Constants.

The following protocol sequences specified by DCE are not supported by the MIDL compiler provided with Microsoft RPC: ncacn_osi_dna and ncadg_dds.

Make sure that you correctly quote backslash characters in endpoints. This error commonly occurs when the endpoint is a named pipe.

Endpoint information specified in the IDL file is used by the RPC run-time functions RpcServerUseProtseqIf and RpcServerUseAllProtseqsIf.

Examples

endpoint("ncacn_np:[\\pipe\\rainier]")

endpoint("ncacn_ip_tcp:[1044]", "ncacn_np:[\\pipe\\shasta]")

See Also

Interface Definition (IDL) File, RpcServerUseAllProtseqsIf, RpcServerUseProtseqIf


entry

The [entry] attribute specifies an exported function or constant in a module by identifying the entry point in the DLL.

[
    uuid(uuid-number),
    entry(entry-id)
    [, optional-attribute-list]
]
module modulename
{
    elementlist
};

Parameters

uuid-number
Specifies a universally unique identification number for the module.
entry-id
Specifies the module entry point function name or integer identification number.
optional-attribute-list
Specifies zero or more attributes for the MIDL compiler to apply to the module.
modulename
Specifies the name other software components use to denote the module.
elementlist
Specifies one or more module element definition statements.

Remarks

If the entryid variable of the [entry] attribute is a string, this is a named entry point. If entryid is a number, the entry point is defined by an ordinal. This attribute provides a way to obtain the address of a function in a module.

Examples

[
    dllname("MyAppsFirst.dll")
]
module MyModule
{
    [entry(20), bindable, requestedit,
     propputref, defaultbind ] HRESULT Func1(
         [in]IUnknown * Param1,
         [out] MyType * Param2);
    [entry("TwentyOne"), hidden, vararg] SAFEARRAY (int) Func2(
        [in, out] SAFEARRAY (variant) *varP) ;
    [entry(22)] Float Func3(
        [in] lpstr pName, [in] double dLevel,
        [out] short * sByte) ;
    } ;

See Also

[dllname], module, ODL File Syntax, ODL File Example, Generating a Type Library With MIDL


enum

The keyword enum to identifies an enumerated type.

enum [tag ]
{
    identifier [=integer-value ]
    [ , ... ]
}

Parameters

tag
Specifies an optional tag for the enumerated type.
identifier
Specifies the particular enumeration.
integer-value
Specifies a constant integer value.

Remarks

Enum types can appear as type specifiers in typedef declarations, general declarations, and function declarators (either as the function-return-type or as a parameter-type specifier). For the context in which type specifiers appear, see Interface Definition (IDL) File.

In the MIDL compiler's default mode, you can assign integer values to enumerators. (This feature is not available when you compile with the /osf switch.) As with C-language enumerators, enumerator names must be unique, but the enumerator values need not be.

When assignment operators are not provided, identifiers are mapped to consecutive integers from left to right, starting with zero. When assignment operators are provided, assigned values start from the most recently assigned value.

The maximum number of identifiers is 65,535.

Objects of type enum are int types, and their size is system-dependent. By default, objects of enum types are treated as 16-bit objects of type unsigned short when transmitted over a network. Values outside the range 0 - 32,767 cause the run-time exception RPC_X_ENUM_VALUE_OUT_OF_RANGE. To transmit objects as 32-bit entities, apply the [v1_enum] attribute to the enum typedef.

Examples

typedef enum {Monday=2, Tuesday, Wednesday, Thursday, Friday} workdays;

typedef enum {Clemens=21, Palmer=22, Ryan=34} pitchers;

See Also

Interface Definition (IDL) File, int, short, typedef, unsigned, [v1_enum]


error_status_t

The error_status_t keyword designates a type for an object that contains communication-status or fault-status information.

[ [ , ACF-function-attributes ] ] error_status_t function-name(
        [ [ ACF-parameter-attributes ] ] parameter-name
        , ...);

[ [ ACF-function-attributes ] ] function-name(
    [ [ ACF-parameter-attributes ] ] error_status_t parameter-name
    , ...);

Parameters

ACF-function-attributes
Specifies zero or more ACF function attributes, such as [comm_status], [fault_status], or [nocode]. Function attributes are enclosed in square brackets. Zero or more attributes can be applied to a function. Separate multiple function attributes with commas.
function-name
Specifies the name of the function as defined in the IDL file.
ACF-parameter-attributes
Specifies attributes that apply to a parameter. Note that zero, one, or more attributes can be applied to the parameter. Separate multiple parameter attributes with commas. Parameter attributes are enclosed in square brackets. IDL parameter attributes, such as directional attributes, are not allowed in the ACF.
parameter-name
Specifies the parameter for the function as defined in the IDL file. Each parameter for the function must be specified in the same sequence, using the same name as defined in the IDL file.

Remarks

The error_status_t type is used as a part of the exception handling architecture in IDL. This type maps to an unsigned long. Applications that catch error situations have an [out] parameter or a return type of a procedure specified as error_status_t, and qualify the error_status_t with the [comm_status] or [fault_status] attributes in the ACF. If the parameter or return type was not qualified with the [comm_status] or [fault_status] attributes, then the parameter operates as though it were an unsigned long.

Beginning with version 2.0, the MIDL compiler generates stubs that contain the proper error handling architecture. However, earlier versions of the MIDL compiler handled a parameter or return type of error_status_t as though the [comm_status] and [fault_status] attributes were applied, even if they were not. With MIDL 2.0 or later, you must explicitly apply the [comm_status] and [fault_status] attributes to the parameter or procedure in the ACF.

The error_status_t type is one of the predefined types of the interface definition language. Predefined types can appear as type specifiers in typedef declarations, in general declarations, and in function declarators (either as the function-return-type or as parameter-type specifiers).

See Also

comm_status, [fault_status], Interface Definition (IDL) File, long, [out], typedef, unsigned


explicit_handle

The [explicit_handle] ACF attribute specifies that each procedure has, as its first parameter, a primitive handle, such as a handle_t type.

[
    explicit_handle
]
interface interface-name
{
    ...
}

Parameters

interface-name
Specifies the name of the interface.

Remarks

When you use the [explicit_handle] attribute, each procedure has a primitive handle as its first parameter even if the IDL file does not contain this handle in its parameter list. The prototypes emitted to the header file and stub routines contain the additional parameter, and that parameter is used as the handle for directing the remote call.

The [explicit_handle] attribute affects both remote procedures and serialization procedures. For type serialization, the support routines are generated with the initial parameter as an explicit (serialization) handle. If the [explicit_handle] attribute is not used, the application can still specify that an operation have an explicit handle (binding or serialization) directing the call. To do this, a prototype with an argument containing a handle type is supplied to the IDL file. Note that in default mode, an argument that does not appear first can also be used as a handle directing the call.

Therefore, while the [explicit_handle] attribute is a way of giving the IDL prototype a primitive [explicit_handle] attribute, it does not necessarily require a change to the IDL file. In /osf mode only the first argument can be used as an explicit handle type.

The [explicit_handle] attribute can be used as either an interface attribute or an operation attribute. As an interface attribute, it affects all the operations in the interface and all the types that require serialization support. If, however, it is used as an operation attribute, it affects only that particular operation.

Example

/* ACF File */
[
    explicit_handle
]
interface iface
{
    // Interface definition statements.
};

See Also

Application Configuration File (ACF), auto_handle, implicit_handle, /osf


fault_status

The [fault_status] attribute specifies that an error code of type error_status_t indicates a failure of the remote procedure, rather than other types of problems such as communication errors.

[fault_status [ , ACF-function-attributes ] ] function-name(
    [ [ ACF-parameter-attributes ] ] parameter-name
    , ... );

[ [ ACF-function-attributes ] ] function-name(
    [fault_status [ , ACF-parameter-attributes ] ] parameter-name
    , ... );

Parameters

ACF-function-attributes
Specifies zero or more ACF function attributes such as [fault_status] and [nocode]. Function attributes are enclosed in square brackets. Note that zero or more attributes can be applied to a function. Separate multiple function attributes with commas. Also note that if [fault_status] appears as a function attribute, it cannot also appear as a parameter attribute.
function-name
Specifies the name of the function as defined in the IDL file.
ACF-parameter-attributes
Specifies attributes that apply to a parameter. Note that zero or more attributes can be applied to the parameter. Parameter attributes are enclosed in square brackets. Separate multiple parameter attributes with commas. IDL parameter attributes, such as directional attributes, are not allowed in the ACF. Note that if [fault_status] appears as a parameter attribute, it cannot also appear as a function attribute.
parameter-name
Specifies the parameter for the function as defined in the IDL file. Each parameter for the function must be specified in the same sequence, using the same name as defined in the IDL file.

Remarks

The [fault_status] attribute can be used as either a function attribute or as a parameter attribute, but it can appear only once per function. It can be applied either to the function itself or to one parameter in each function.

The [fault_status] attribute can be applied only to functions that return the type error_status_t. When the remote procedure fails in a way that causes a fault PDU to be returned, an error code is returned.

When [fault_status] is used as a parameter attribute, the parameter must be an [out] parameter of type error_status_t. If a server error occurs, the parameter is set to the error code. When the remote call is successfully completed, the procedure sets the value.

The parameter associated with the [fault_status] attribute does not have to be specified in the IDL file. When the parameter is not specified, a new out parameter of type error_status_t is generated following the last parameter defined in the DCE IDL file.

It is possible for both the [fault_status] and [comm_status] attributes to appear in a single function, either as function attributes or parameter attributes. If both attributes are function attributes, or if they apply to the same parameter and no error occurs, the function or parameter has the value error_status_ok. Otherwise, it contains the appropriate status code value. Because values returned for [fault_status] are different from the values returned for [comm_status], the returned values are readily interpreted.

See Also

Application Configuration File (ACF), comm_status, error_status_t, nocode, [out]


first_is

The [first_is] attribute specifies the index of the first array element to be transmitted.

first_is(limited-expression-list)

Parameters

limited-expression-list
Specifies one or more C-language expressions. Each expression evaluates to an integer that represents the array index of the first array element to be transmitted. The MIDL compiler supports conditional expressions, logical expressions, relational expressions, and arithmetic expressions. MIDL does not allow function invocations in expressions and does not allow increment and decrement operators. Separate multiple expressions with commas.

Remarks

If the [first_is] attribute is not present, or if the specified index is a negative number, array element zero is the first element transmitted.

The [first_is] attribute can also help determine the values of the array indexes corresponding to the [last_is] or [length_is] attribute when these attributes are not specified. The relationship between these array indexes is:

length = last - first + 1

The following relationship must also hold:

0 <= first_is <= max_is

The following relationship must hold when [max_is] <= 0:

first_is == 0

The [first_is] attribute cannot be used at the same time as the [string] attribute.

Using a constant expression with the [first_is] attribute is an inappropriate use of the attribute. It is legal, but inefficient, and will result in slower marshaling code.

Example

HRESULT Proc1(
    [in] short First,
    [first_is(First)] Arr[10]);

See Also

field_attributes, Interface Definition (IDL) File, [last_is], [length_is], [max_is], [min_is], [size_is], [string]


float

The float keyword designates a 32-bit floating-point number.

float identifier-name;

Parameters

identifier-name
Specifies a valid MIDL identifier. Valid MIDL identifiers consist of up to 31 alphanumeric and/or underscore characters and must start with an alphabetic or underscore character.

Remarks

The float type is one of the base types of the interface definition language (IDL). The float type can appear as a type specifier in typedef declarations, general declarations, and function declarators (as a function-return-type specifier and a parameter-type specifier). For the context in which type specifiers appear, see Interface Definition (IDL) File.

The float type cannot appear in const declarations.

See Also

MIDL Base Types, double, Interface Definition (IDL) File, typedef


force_allocate

The ACF attribute [force_allocate] forces a pointer parameter to be allocated using midl_user_allocate instead of optimizing away the allocation.

[ [function-attribute-list <>] ] type-specifier <> [pointer- <>declarator <>] function-name <>( [ force_allocate [ , parameter-attribute-list <> ] ] type-specifier <> [declarator <>] , ...);

Remarks

RPC attempts to minimize memory allocations on the server by supplying pointers to internal memory buffers. This approach can cause problems for applications that attempt to directly call midl_user_free on RPC-supplied pointers, because a pointer that has been optimized cannot be freed. Marking a parameter with [force_allocate] will prevent this optimization for all pointers deriving it.

Another common use for [force_allocate] is to guarantee the alignment of the memory being pointed to if an application requires an alignment greater than that of the memory pointed to. For example, applications often pass data in a generic array of bytes rather than using the actual type, but a byte is only guaranteed to be aligned at 1, which may cause problems for applications that assume a larger alignment. By marking the parameter with [force_allocate], the application can guarantee all memory pointed to will have an alignment equal to that guaranteed by midl_user_allocate.

Examples

/* IDL file */
void Func1([in, out, string] char **ppstr);
void Func2([in] long s, [in, size_is(s)] byte *pData);

/* ACF file */

/* e.g. The application wishes to call midl_user_free on *ppstr and supply a new pointer */
Func1([force_allocate] pstr);

/* e.g. pData really points to a structure that needs an alignment greater than 1 */
Func2([force_allocate] pData);

See Also

Avoiding Information Hiding, Designing 64-bit-Compatible Interfaces, midl_user_allocate, midl_user_free, allocate


handle

The [handle] attribute specifies a user-defined or "customized" handle type.

typedef [handle] typename;
handle_t __RPC_USER typename_bind (typename);
void __RPC_USER typename_unbind (typename, handle_t);

Parameters

typename
Specifies the name of the user-defined binding-handle type.

Remarks

User-defined handles permit developers to design handles that are meaningful to the application. A user-defined handle can only be defined in a type declaration, not in a function declarator.

A parameter of a type defined by the [handle] attribute is used to determine the binding for the call and is transmitted to the called procedure.

The user must provide binding and unbinding routines to convert between primitive and user-defined handle types. Given a user-defined handle of type typename, the user must supply the routines typename_bind and typename_unbind. For example, if the user-defined handle type is named MYHANDLE, the routines are named MYHANDLE_bind and MYHANDLE_unbind.

If successful, the typename_bind routine should return a valid primitive binding handle. If unsuccessful, the routine should return a NULL. If the routine returns NULL, the typename_unbind routine will not be called. If the binding routine returns an invalid binding handle different from NULL, the stub behavior is undefined.

When the remote procedure has a user-defined handle as a parameter or as an implicit handle, the client stubs call the binding routine before calling the remote procedure. The client stubs call the unbinding routine after the remote call.

In DCE IDL, a parameter with the [handle] attribute must appear as the first parameter in the remote procedure argument list. Subsequent parameters, including other [handle] attributes, are treated as ordinary parameters. Microsoft supports an extension to DCE IDL that allows the user-defined [handle] parameter to appear in positions other than the first parameter.

Examples

typedef [handle] struct
{
    char machine[8];
    char nmpipe[256];
} h_service;

handle_t __RPC_USER h_service_bind(h_service);
void __RPC_USER h_service_unbind(h_service, handle_t);

See Also

Binding and Handles, Interface Definition (IDL) File, [implicit_handle], typedef


handle_t

The handle_t keyword declares an object to be of the primitive handle type handle_t. A primitive binding handle is a data object that can be used by the application to represent the binding.

typedef RPC_BINDING_HANDLE handle_t;

Remarks

The handle_t type is one of the predefined types of the interface definition language (IDL). It can appear as a type specifier in typedef declarations, general declarations, and function declarators (as a function-return-type specifier and a parameter-type specifier). For the context in which type specifiers appear, see Interface Definition (IDL) File.

In Microsoft RPC, parameters of type handle_t can occur only as [in] parameters. Primitive handles cannot have the [unique] or [ptr] attribute.

Parameters of type handle_t (primitive handle parameters) are not transmitted on the network.

Requirements

Windows NT/2000: Requires Windows NT 3.1 or later.
Windows 95/98: Requires Windows 95 or later.
Header: Declared in Rpcdce.h.

See Also

MIDL Base Types, Binding and Handles, Interface Definition (IDL) File, [in], typedef, [ptr], [unique]


heap

The DCE ACF keyword heap is not implemented in Microsoft RPC.

See Also

Application Configuration File (ACF)


helpcontext

The [helpcontext] attribute specifies a context identifier that lets the user view information about this element in the Help file.

[
    uuid(uuid-number),
    helpcontext(helpcontext-value)
    [, attribute-list]
]
element element-name
{
    definitions
}

Parameters

uuid-number
Specifies a universally unique identification number for the library, [importlib], interface, dispinterface, module, typedef, methods, [property], or coclass.
helpcontext-value
A unique integer that identifies the help text associated with the current MIDL element.
attribute-list
Specifies a list of one or more attributes that apply to the MIDL element as a whole.
element
One of the following directives: library, [importlib], interface, dispinterface, module, typedef, method, property, or coclass.
element-name
The name that other software components can use to delineate the current element.
definitions
Specifies statements that make up the element definition.

Remarks

The helpcontext attribute can be applied to the following elements: library, [importlib], interface, dispinterface, module, typedef, method, property, or coclass.

The helpcontext-value is a 32-bit context identifier within the Help file that can be retrieved with the GetDocumentation functions in the ITypeLib and ITypeInfo interfaces.

Examples

[
    uuid(1e196b20-1f3c-1069-996b-00dd010fe676),
    helpcontext(7035943),
    helpstring("Hello Class"),
    appobject
]
coclass Hello
{
    [default, helpcontext(3914972)] interface IHello : IUnknown;
    interface IDispatch;
}

See Also

coclass, dispinterface, Generating a Type Library With MIDL, [importlib], interface, library, module, ODL File Syntax, ODL File Example, typedef


helpfile

The [helpfile] attribute sets the name of the Help file for a type library. All types in a library share the same Help file.

[
    uuid(uuid-number),
    helpfile("filename")
    [, optional-attribute-list]
]
library
{
    library statements
};

Parameters

uuid-number
Specifies a universally unique identification number for the library.
filename
Specifies the name of the file containing the help text.
optional-attribute-list
Specifies zero or more attributes that the MIDL compiler will apply to the library.
library statements
Specifies one or more MIDL statements that define the library interface.

Remarks

Use the GetDocumentation functions in the ITypeLib and ITypeInfo interfaces to retrieve the file name.

Example

[
    uuid(1e196b20-1f3c-1069-996b-00dd010fe676),
    helpfile("filename.hlp"),
    lcid(0x0409),
    version(2.0)
]
library Hello
{
    /* Library definition statements here. */
};

See Also

library, ODL File Syntax, ODL File Example, Generating a Type Library With MIDL


helpstring

The [helpstring] attribute specifies a character string that is used to describe the element to which it applies. You can apply the [helpstring] attribute to library, importlib, interface, dispinterface, module, or coclass statements, typedefs, properties, and methods.

[
    helpstring(help-text-string)
    [, optional-attribute-list]
]
element element-name
{
    definition
}

[idl-statement, helpstring(help-text-string)]

Parameters

help-text-string
A zero-terminated string of characters containing help text.
optional-attribute-list
Zero or more MIDL attribute statements.
element
One of the following directives: library, [importlib], interface, dispinterface, module, typedef, method, property, or coclass.
element-name
The name that other software components can use to delineate the current element
definition
Specifies statements that make up the element definition.
idl-statement
A MIDL interface definition statement such as propget or propput.

Remarks

Use the GetDocumentation functions in the ITypeLib and ITypeInfo interfaces to retrieve the help string.

Example

[
    uuid(1e196b20-1f3c-1069-996b-00dd010fe676),
    helpstring("Lines 1.0 Type Library"),
    version(1.0)
]
library Lines
{
     [
         uuid(1e123456-1f3c-1069-996b-00dd010fe676),
         helpstring("Line object."),
         oleautomation,
         dual
     ]
     interface ILine : IDispatch
     {
         [propget, helpstring("Returns and sets RGB color.")]
         HRESULT Color([out, retval] long* ReturnVal);
         [propput, helpstring("Returns and sets RGB color.")]
         HRESULT Color([in] long rgb);
     }
};

See Also

library, [importlib], interface, dispinterface, module, coclass, typedef, ODL File Syntax, ODL File Example, Generating a Type Library With MIDL


helpstringcontext

The [helpstringcontext] attribute specifies a 32-bit Help context identifier in the Help file. You can apply the [helpstringcontext] attribute to library, interface, dispinterface, module, coclass, typedef statements, properties, parameters and methods.

[  helpstringcontext(contextid)[, optional-attribute-list]] idl-statement

Parameters

contextid
A unique integer that identifies the help text associated with the current MIDL statement.
optional-attribute-list
Zero or more MIDL attributes.
idl-statement
The MIDL statement to which the [helpstringcontext] attribute will be applied.

Remarks

Use the GetDocumentation2 functions in the ITypeLib2 and ITypeInfo2 interfaces to retrieve the help string.

Example

[
    uuid(. . .),
    helpstringcontext(103),
    version(1.0)
]
library Lines
{
    [
        uuid(. . .),
        helpstringcontext(102),
        oleautomation,
        dual
    ]
    interface ILine : IDispatch
    {
        [propget, helpstringcontext(100)] HRESULT Color([out, retval] long* ReturnVal);
        [propput, helpstringcontext(101)] HRESULT Color([in] long rgb);
    }
};


helpstringdll

The [helpstringdll] attribute sets the name of the DLL to use to perform a document string lookup.

[
    helpstringdll(help-text-string)
    [, optional-attribute-list]
]
library library-name
{
    library-definition-statements
};

Parameters

help-text-string
A zero-terminated string of characters specifying the fully qualified file name of a DLL.
optional-attribute-list
Other attributes that apply to the library statement as a whole.
library-name
The identifier that software components will use to denote this library.
library-definition-statements
One or more MIDL statement which define the interface of the library.

Remarks

Use the [helpstringdll] attribute on a library statement to specify, as a character string, the fully qualified file name of a dynamic link library. This allows a user to view a description of the DLL with the object viewer.

Use the GetDocumentation2 functions in the ITypeLib2 and ITypeInfo2 interfaces to retrieve the help string.

See Also

library, ODL File Syntax, ODL File Example, Generating a Type Library With MIDL


hidden

The [hidden] attribute indicates that the item exists but should not be displayed in a user-oriented browser.

[
    other-attributes,
    hidden
]
element element-name
{
    definitions
}

[other-attributes, hidden] function-type function-name(optional-parameter-list);

Parameters

other-attributes
Zero or more optional MIDL attributes.
element
One of the following directives: coclass, dispinterface, interface, or library.
element-name
The name that other software components can use to delineate the current element.
definitions
Specifies statements that make up the element definition.
function-type
Return type of the function.
function-name
Name used for invoking the function.
optional-parameter-list
Zero or more function parameters.

Remarks

The [hidden] attribute allows you to remove members from your interface (by shielding them from further use) while maintaining compatibility with existing code. You can use the [hidden] attribute on properties, methods, and the coclass, dispinterface, interface, and library statements.

When specified for a library, the [hidden] attribute prevents the entire library from being displayed. This usage is intended for use with controls. Hosts need to create a new type library that wraps the control with extended properties.

Flags

VARFLAG_FHIDDEN, FUNCFLAG_FHIDDEN, TYPEFLAG_FHIDDEN

Examples

[hidden, vararg] SAFEARRAY (int) SecretFunc(
    [in, out] SAFEARRAY (variant) *varP) ;

[
    uuid(1e196b20-1f3c-1069-996b-00dd010fe676),
    hidden,
    version (3.0)
]
library HiddenLib
{
    /* Library definition statements here. */
};

See Also

TYPEFLAGS, dispinterface, coclass, Generating a Type Library With MIDL, interface, library, ODL File Syntax, ODL File Example


hyper

The keyword hyper indicates a 64-bit integer that can be declared as either signed or unsigned.

[ signed | unsigned ] hyper [ int ] declarator-list;

Parameters

declarator-list
Specifies one or more standard C declarators, such as identifiers, pointer declarators, and array declarators. (Function declarators and bit-field declarations are not allowed in structures that are transmitted in remote procedure calls. These declarators are allowed in structures that are not transmitted.) Separate multiple declarators with commas.

Remarks

The hyper type is one of the base types of the interface definition language (IDL). The hyper type can appear as a type specifier in const declarations, typedef declarations, general declarations, and function declarators (as a function-return-type specifier and as a parameter-type specifier). For the context in which type specifiers appear, see Interface Definition (IDL) File.

Note For 16-bit platforms, the MIDL compiler replaces unsigned hyper integers with MIDL_uhyper. This allows interfaces with unsigned hyper integers to be defined on platforms that do not directly support 64-bit integers. MIDL_uhyper is defined in the RPC header files.

See Also

MIDL Base Types, const, Interface Definition (IDL) File, typedef


id

The [id] attribute specifies a DISPID for a member function (either a property or a method, in an interface or dispinterface).

[id(id-num) [,optional-attribute-list]] return-type function-name(optional-parameter-list)

Parameters

id-num
DISPID for the function.
optional-attribute-list
Specifies a list of zero or more MIDL interface attributes.
return-type
Specifies the return type of the function.
function-name
Specifies the name of the function in the IDL file.
optional-parameter-list
Zero or more function parameters.

Remarks

Use the [id] attribute when you want to assign a standard DISPID (like DISPID_VALUE, DISPID_NEWENUM etc.) to a method or property, or when you implement your own IDispatch::Invoke instead of delegating to DispInvoke/ITypeInfo::Invoke.

If you do not use the [id] attribute on an interface, the MIDL compiler will assign a DISPID for you. However, when you specify a dispinterface by using properties and methods, you must specify a DISPID for every property and method.

The id-num is a 32-bit positive integral value. Negative IDs are reserved for use by Automation.

Example

interface IKnown : IUnknown
{
    properties:
        [id(90), propget,
         helpstring("A meaningful comment."] long Func1(void);

    /* Other interface statements */
}

See Also

interface, dispinterface, ODL File Syntax, ODL File Example, Generating a Type Library With MIDL


idempotent

The [idempotent] attribute specifies that an operation does not modify state information and returns the same results each time it is performed. Performing the routine more than once has the same effect as performing it once.

[
    interface-attribute-list
]
interface interface-name
{
    [idempotent [, attribute-list]] returntype function-name(params)
}

Parameters

interface-attribute-list
Specifies a list of zero or more IDL attributes that apply to the interface as a whole. When two or more interface attributes are present, they must be separated by commas.
interface-name
Specifies the name of the interface.
attribute-list
Specifies additional attributes to be applied to the function. Separate multiple attributes with commas.
returntype
Specifies the return type of the function.
function-name
Specifies the name of the function to which the [idempotent] attribute will be applied.
params
Function parameter list.

Remarks

RPC supports two types of remote call semantics: calls to operations with the [idempotent] attribute and calls to operations (idempotent operations) without the [idempotent] attribute (non-idempotent opertations). An idempotent operation can be carried out more than once with no ill effect. Conversely, a non-idempotent operation cannot be executed more than once because it will either return different results each time or because it modifies some state.

To ensure that a procedure is automatically re-executed if the call does not complete, use the [idempotent] attribute. If the [idempotent], [broadcast], or [maybe] attributes are not present, the procedure will use non-idempotent semantics by default. In this case, the operation is executed only once.

See Also

[broadcast], Interface Definition (IDL) File, [maybe]


ignore

The [ignore] attribute designates that a pointer contained in a structure or union and the object indicated by the pointer is not transmitted. The [ignore] attribute is restricted to pointer members of structures or unions.

[ignore] pointer-member-type pointer-name;

Parameters

pointer-member-type
Specifies the type of the pointer member of the structure or union.
pointer-name
Specifies the name of the pointer member that is to be ignored during marshaling.

Remarks

The value of a structure member with the [ignore] attribute is undefined at the destination. An [in] parameter is not defined at the remote computer. An [out] parameter is not defined at the local computer.

The [ignore] attribute allows you to prevent transmission of data. This is useful in situations such as a double-linked list. The following example includes a double-linked list that introduces data aliasing:

/* IDL file */
typedef struct _DBL_LINK_NODE_TYPE
{
    long value;
    struct _DBL_LINK_NODE_TYPE * next;
    struct _DBL_LINK_NODE_TYPE * previous;
} DBL_LINK_NODE_TYPE;

HRESULT remote_op([in] DBL_LINK_NODE_TYPE * list_head);

/* application */
DBL_LINK_NODE_TYPE * p, * q

p = (DBL_LINK_NODE_TYPE *) midl_user_allocate(
        sizeof(DBL_LINK_NODE_TYPE));
q = (DBL_LINK_NODE_TYPE *) midl_user_allocate(
        sizeof(DBL_LINK_NODE_TYPE));

p->next = q;
q->previous = p;
p->previous = q->next = NULL;
..
remote_op(p);

Aliasing occurs in the preceding example because the same memory area is available from two different pointers in the function p and p->next->previous.

Note that [ignore] cannot be used as a type attribute.

Example

typedef struct _DBL_LINK_NODE_TYPE
{
    long value;
    struct _DBL_LINK_NODE_TYPE * next;
    [ignore] struct _DBL_LINK_NODE_TYPE * previous;
} DBL_LINK_NODE_TYPE;

See Also

Array and Sized-Pointer Attributes, arrays, Arrays and Pointers, [in], [out], [ptr], [ref], [unique]


iid_is

The [iid_is] pointer attribute specifies the IID of the COM interface pointed to by an interface pointer.

[ iid_is(limited-expression) ]

Parameters

limited-expression
Specifies a C-language expression. The MIDL compiler supports conditional expressions, logical expressions, relational expressions, and arithmetic expressions. MIDL does not allow function invocations in expressions and does not allow increment and decrement operators.

Remarks

You can use [iid_is] in attribute lists for function parameters and for structure or union members. The stubs use the IID to determine how to marshal the interface pointer. This is useful for an interface pointer that is typed as a base class parameter.

Files that use the [iid_is] attribute must be compiled with the MIDL compiler in default mode, that is not using the /osf switch.

Example

HRESULT    CreateInstance(
    [in] REFIID riid,
    [out, iid_is(riid)] IUnknown ** ppvObject);

See Also

[object], [uuid]


immediatebind

The [immediatebind] attribute indicates that the database will be notified immediately of all changes to a property of a data-bound object.

[
    interface-attribute-list
]
interface | dispinterface interface-name
{
    [bindable, immediatebind[, optional-attribute-list]] returntype function-name(params)
}

Parameters

interface-attribute-list
Specifies a list of one or more attributes that apply to the interface as a whole.
interface-name
Specifies the name of the interface or dispinterface.
optional-attribute-list
Zero or more function attributes.
returntype
Specifies the return type of the function.
function-name
Specifies the name of the function in the IDL file.
params
Zero or more function parameters.

Remarks

The [immediatebind] attribute allows controls to differentiate between properties that need to notify the database of every change, and those that do not. For example, every change to a checkbox control should be sent to the underlying database immediately, even if the control has not lost the focus. However, for a listbox control, a change occurs whenever a different selection is highlighted. Notifying the database of a change before the control loses focus would be inefficient and unnecessary. The [immediatebind] attribute allows you to specify, by setting the ImmediateBind bit, individual properties on a form whose changes should be reported immediately.

Properties that have the [immediatebind] attribute must also have the [bindable] attribute.

Flags

FUNCFLAG_FIMMEDIATEBIND, VARFLAG_FIMMEDIATEBIND

Example

[
    uuid(12345678-1234-1234-1234-123456789ABC)
]
interface MyObject : IUnknown
{
    properties:
    methods:
        [id(1), propget, bindable, immediatebind] long Size(void);

        [id(1), propput, bindable,
         immediatebind] HRESULT Size([in]long lSize);
}

See Also

[bindable], TYPEFLAGS, interface, dispinterface, ODL File Syntax, ODL File Example, Generating a Type Library With MIDL


implicit_handle

The [implicit_handle] attribute specifies the handle used for functions that do not include an explicit handle as a procedure parameter.

implicit_handle(handle-type handle-name)

Parameters

handle-type
Specifies the handle data type, such as the base type handle_t or a user-defined handle type.
handle-name
Specifies the name of the handle.

Remarks

The handle specified by the [implicit_handle] attribute is used in different ways depending on the nature of the procedure. If the procedure is remote, the handle will be used as the binding handle for the remote call. The implicit handle may also be used to establish an initial binding for a function that uses a context handle. If the procedure is a serializing procedure, the handle is used as a serializing handle controlling the operation. In the case of type serialization, the handle is used as the serialization handle for all the serialized types.

The [implicit_handle] attribute specifies a global variable that contains a handle used by any function needing implicit handles.

The implicit binding handle type must be either handle_t (or a type based on handle_t) or a user-defined handle type specified with the handle attribute. The implicit serializing handle must be a type based on handle_t.

If the implicit handle type is not defined in the IDL file or in any files included and imported by the IDL file for the MIDL computer, you must supply the file containing the handle-type definition when you compile the stubs. Use the ACF include statement to include the file containing the handle-type definition.

The [implicit_handle] attribute can occur once, at most. The [implicit_handle] attribute can occur only if the [auto_handle] and [explicit_handle] attributes do not occur.

Example

/* ACF file */
[
    implicit_handle(handle_t hMyHandle)
]
interface iface
{
    // Attribute configuration statements
}

See Also

Application Configuration File (ACF), [auto_handle], [explicit_handle], handle_t, include


import

The import directive specifies another IDL, ODL, or header file containing definitions you wish to reference from your main IDL file.

import "filename" [[ , ... ]] ;

Parameters

filename
Specifies the name of the header, IDL, or ODL file to import.

Remarks

With the import directive, all IDL statements in the imported file, such as typedefs, constant declarations, and interface definitions become available to the importing .IDL file.

The imported file is processed separately (meaning that CPP preprocessor is invoked independently) from the importing IDL file. In this way, pre-processor directives, such as #define, do not carry over from an imported header or IDL file to the importing IDL file.

Like the C-language preprocessor macro #include, the import directive tells the compiler to include data types that were defined in the imported IDL files. Unlike the #include directive, the import directive ignores procedure prototypes, since no stubs are generated for anything in the imported file.

For specific information on using import to include header files in an IDL file, see Importing System Header Files.

The C-language header (.H) file generated for the interface does not directly contain the imported types but instead generates a #include directive for the header file corresponding to the imported interface. For example, when you import BASE.IDL into your DERIVED.IDL, the generated header file DERIVED.H will contain the directive #include BASE.H.

The following rules apply:

  • The import keyword is optional and can appear zero or more times in the IDL file.
  • Each import keyword can be associated with more than one file name.
  • Separate multiple file names with commas.
  • You must enclose the file name within quotation marks and end the import statement with a semicolon (;).
  • You can import an interface that has no attributes into another IDL file. However, the interface must contain only datatypes; it cannot contain any procedures. If even one procedure is contained in the imported interface, you must specify a local or UUID attribute.
  • The import function is idempotent — that is, importing an interface more than once has no additional effect.

Note The behavior of the import directive is independent of the MIDL compiler mode switches /ms_ext (the default), /osf, and /app_config. However, the compiler mode (/osf vs. /ms_ext) can affect pointer attribute decoration on imported types. For details see Pointer-Attribute Type Inheritance.

Examples

import "myoldodl.odl";
import "unknwn.idl";
import "part1.idl", "part2.idl", "part3.idl";

See Also

/app_config, Interface Definition (IDL) File, importlib, include, Importing System Header Files, Importing Files and Type Libraries, /ms_ext, /osf


importlib

The [importlib] directive makes types that have already been compiled into another type library available to the type library being created.

[
    library-attributes
]
library (library-name)
{
    importlib(file-to-import);
    ...
}

Parameters

library-attributes
Zero or more attributes that will be applied to the library.
library-name
The identifier that software components will use to denote this library.
file-to-import
The name and location of the imported file at MIDL compile-time.

Remarks

All [importlib] directives must precede the other type descriptions in the library. Note that the imported library, as well as the generated library, must be distributed with the application so that it is available at run time.

In most cases you should use the MIDL [import] directive to reference definitions from another .IDL file in your .IDL file. This method provides your type library with all the information from the original file, whereas [importlib] only brings in the contents of the type library.

Note The [importlib] directive makes any type defined in the imported library accessible from within the library being compiled. To avoid ambiguity when there are duplicate references, we recommend that you qualify each such reference with the appropriate library name, as follows:

library_name.type

In the absence of such qualification, MIDL resolves duplicate reference ambiguity as follows:

  • Effective with version 3.1, MIDL uses the first reference it finds. This is the same way that MKTYPLIB handled duplicate references.
  • Version 3.0 of MIDL, the first version of MIDL that could generate type libraries, uses the last reference it found.

Example

library BrowseHelper
{
    importlib("stdole32.tlb");
    importlib("mydisp.tlb");
    //Remainder of library definition
};

See Also

library, [import], Importing System Header Files, Importing Files and Type Libraries, ODL File Syntax, ODL File Example, Generating a Type Library With MIDL


in

The [in] attribute indicates that a parameter is to be passed from the calling procedure to the called procedure.

[ [function-attribute-list] ] type-specifier [pointer-declarator] function-name(
    [ in [ , parameter-attribute-list ] ] type-specifier [declarator]
    , ...);

Parameters

function-attribute-list
Specifies zero or more attributes that apply to the function. Valid function attributes are [callback], [local], the pointer attribute [ref], [unique], or [ptr], and the usage attributes [string], [ignore], and [context_handle].
type-specifier
Specifies a base_type, struct, union, or enum type or type identifier. An optional storage specification can precede type-specifier.
pointer-declarator
Specifies zero or more pointer declarators. A pointer declarator is the same as the pointer declarator used in C; it is construxcted from the * designator, modifiers such as far, and the qualifier const.
function-name
Specifies the name of the remote procedure.
parameter-attribute-list
Specifies zero or more attributes appropriate for the specified parameter type. Parameter attributes with the [in] attribute can also take the directional attribute [out]; the field attributes [first_is], [last_is], [length_is], [max_is], [size_is] and [switch_type]; the pointer attribute [ref], [unique], or [ptr]; and the usage attributes [context_handle] and [string]. The usage attribute [ignore] cannot be used as a parameter attribute. Separate multiple attributes with commas.
declarator
Specifies standard C declarators, such as identifiers, pointer declarators, and array declarators. For more information, see Array and Sized-Pointer Attributes, arrays, and Arrays and Pointers. The parameter declarator in the function declarator, such as the parameter name, is optional.

Remarks

The [in] attribute has a converse attribute, [out], which indicates that a parameter is to be returned from the called procedure to the calling procedure. The [in] and [out] attributes are known as directional parameter attributes because they specify the direction in which parameters are passed. A parameter can be defined as [in], [out], or [in, out].

The [in] attribute identifies parameters that are marshaled by the client stub for transmission to the server.

The [in] attribute is applied to a parameter by default when no directional parameter attribute is specified.

Example

HRESULT MyFunction([in] short count);

See Also

Interface Definition (IDL) File, midl_user_allocate, out


include

The ACF include statement specifies one or more header files to be included in the generated stub code.

include filenames;

Parameters

filenames
Specifies the name of one or more C-language header files. Use the full file name, including the .H extension and enclose each file name in quotation marks. Separate multiple C-language header file names with commas.

Remarks

As a result of the include statement, the generated stub code will contain a C-preprocessor #include statement. You supply the C-language header file when compiling the stubs. Include statements rely on the C-compiler mechanism of searching the directory structure for included files.

Note Use the import directive rather than the include directive for system files that contain data types you want to make available to the IDL file. The import directive ignores function prototypes and allows you to use MIDL compiler switches that optimize the generation of support routines.

Examples

include "local.h";
include "gendefs.h", "protos.h", "mystuff.h";

See Also

Application Configuration File (ACF), import, Importing Files and Type Libraries, Importing System Header Files


in_line

The DCE IDL keyword in_line is not supported in Microsoft RPC.


int

The keyword int specifies a 32-bit signed integer on 32-bit platforms. On 16-bit platforms, the keyword int is an optional keyword that can accompany the keywords small, short, and long.

[ signed | unsigned ] integer-modifier [ int ] declarator-list;

Parameters

integer-modifier
Specifies the keyword small, short, long, hyper, __int3264, or __int64,which selects the size of the integer data. On 16-bit platforms, the size qualifier must be present.
declarator-list
Specifies one or more standard C declarators, such as identifiers, pointer declarators, and array declarators. (Function declarators and bit-field declarations are not allowed in structures that are transmitted in remote procedure calls. These declarators are allowed in structures that are not transmitted.) Separate multiple declarators with commas.

Remarks

Integer types are among the base types of the interface definition language (IDL). They can appear as type specifiers in typedef declarations, general declarations, and function declarators (as a function-return-type specifier and as a parameter-type specifier). For the context in which type specifiers appear, see Interface Definition (IDL) File.

If no integer sign specification is provided, the integer type defaults to signed.

DCE IDL compilers do not allow the keyword signed to specify the sign of integer types. Therefore, this feature is not available when you use the MIDL compiler /osf switch.

Microsoft does not recommend the use of __int3264 for remoting if it can be avoided. Please see the topic on __int3264 for more information regarding it's use and limitations.

Examples

signed short int i = 0;
int j = i;
typedef struct
{
    small int         i1;
    short             i2;
    unsigned long int i3;
} INTSIZETYPE;

HRESULT MyFunc([in] long int lCount);

See Also

MIDL Base Types, enum, hyper, Interface Definition (IDL) File, long, /osf, short, signed, small, struct, typedef, union


__int3264

The keyword __int3264 specifies an integral type that has the following properties:

  • It is 32-bit on 32-bit platforms
  • It is 64-bit on 64-bit platforms
  • It is 32-bit on the wire for backward compatibility. It gets truncated on the sending side and extended appropriately (signed or unsigned) on the receiving side.
[ signed | unsigned ] __int3264 [ int ] declarator-list;

Parameters

declarator-list
Specifies one or more standard C declarators, such as identifiers, pointer declarators, and array declarators. (Function declarators and bit-field declarations are not allowed in structures that are transmitted in remote procedure calls. These declarators are allowed in structures that are not transmitted.) Separate multiple declarators with commas.

Remarks

This type has been introduced specifically to facilitate the porting of 32-bit interfaces to 64-bit. It is generally useful only in cases where existing interfaces send pointers as integers or use similar workaround techniques. Microsoft does not recommend using this type (or other public types derived from it such as INT_PTR, DWORD_PTR) where it can be avoided. In particular, these types cannot be used in OLE Automation interfaces and type libraries. Use of this type, or types derived from it, in new interfaces is not recommended. See the Microsoft Interface Definition Language (MIDL): 64-Bit Porting Guide for more information on these issues as well as comments and advice on other 64-bit issues.

The __int3264 keyword can be preceded by either the keyword signed or the keyword unsigned. The int keyword is optional and can be omitted. To the MIDL compiler the __int3264 integer is signed by default and is synonymous with signed __int3264 int.

The __int3264 integer type is one of the base types of the IDL language. The __int3264 integer type can appear as a type specifier in const declarations, typedef declarations, general declarations, and function declarators (as a function-return-type specifier and a parameter-type specifier). For the context in which type specifiers appear, see IDL.

See Also

MIDL Base Types, hyper, int, short, signed, small, typedef, unsigned


__int64

The keyword __int64 specifies a valid integer supported by the MIDL compiler.

__int64 identifier-name;

Parameters

identifier-name
Specifies a valid MIDL identifier. Valid MIDL identifiers consist of up to 31 alphanumeric and/or underscore characters and must start with an alphabetic or underscore character.

Remarks

For a discussion of how to use __int64, see hyper.

See Also

hyper, Interface Definition (IDL) File, int


interface

The interface keyword specifies the name of the interface. The interface name must be provided in both the IDL file and the ACF.

[
    interface-attribute-list
]
interface interface-name [ : base-interface ]
{
}

typedef interface interface-name declarator-list

Parameters

interface-attribute-list
Specifies attributes that apply to the interface as a whole. Valid interface attributes for an IDL file include [endpoint], [local], [object], [pointer_default], [uuid], and [version]. Valid interface attributes for an ACF include [encode], [decode], either [auto_handle] or [implicit_handle], and either [code] or [nocode].
interface-name
Specifies the name of the interface. The interface name must be a unique name and must start with an alphabetic or underscore character.
base-interface
Specifies the name of an interface from which this derived interface inherits member functions, status codes, and interface attributes. The derived interface does not inherit type definitions. To do this, use the import keyword to import the IDL file of the base interface.
declarator-list
Specifies standard C declarators, such as identifiers, pointer declarators, and array declarators. For more information, see Array and Sized-Pointer Attributes, arrays., and Arrays and Pointers. The declarator-list consists of one or more declarators, separated by commas.

Remarks

The interface names in the IDL file and ACF must be the same, except when you use the MIDL compiler switch /acf.

The interface name forms the first part of the name of interface-handle data structures that are parameters to the RPC run-time functions. For more information, see RPC_IF_HANDLE.

If the interface header includes the [object] attribute to indicate a COM interface, it must also include the [uuid] attribute and must specify the base COM interface from which it is derived. For more information about COM interfaces, see [object].

You can also use the interface keyword with the typedef keyword to define an interface data type.

Examples

/* use of interface keyword in IDL file for an RPC interface */
[
    uuid (00000000-0000-0000-0000-000000000000),
    version (1.0)
]
interface remote_if_2
{
    // Interface definition statements.
}

/* use of interface keyword in ACF for an RPC interface */
[
    implicit_handle( handle_t xa_bhandle )
]
interface remote_if_2
{
    // Attribute configuration statements.
}

/* use of interface keyword in IDL file for a COM interface */
[
    object, uuid (00000000-0000-0000-0000-000000000000)
]
interface IDerivedInterface : IBaseInterface
{
    import "base.idl"
    Save();
}

/* use of interface keyword to define an interface pointer type */
typedef interface IStorage *LPSTORAGE;

See Also

Application Configuration File (ACF), [endpoint], Interface Definition (IDL) File, [local], [object], [pointer_default], RPC_IF_HANDLE, typedef, [uuid], [version]


last_is

The field attribute [last_is] specifies the index of the last array element to be transmitted. When the specified index is zero or negative, no array elements are transmitted.

[last_is( limited-expression-list )]

Parameters

limited-expression-list
Specifies one or more C-language expressions. Each expression evaluates to an integer that represents the array index of the last array element to be transmitted. The MIDL compiler supports conditional expressions, logical expressions, relational expressions, and arithmetic expressions. MIDL does not allow function invocations in expressions and does not allow increment and decrement operators. Separate multiple expressions with commas.

Example

proc1(
    [in] short Last,
    [in, last_is(Last)] short asNumbers[MAXSIZE]);

Remarks

The [last_is] attribute determines the value of the array index corresponding to the [length_is] attribute when [length_is] is not specified. The relationship between these array indexes is as follows:

length = last - first + 1

If the value of the array index specified by [first_is] is larger than the value specified by [last_is], zero elements are transmitted.

The [last_is] attribute cannot be used as a field attribute at the same time as the [length_is] attribute or the [string] attribute.

Using a constant expression with the [last_is] attribute is an inappropriate use of the attribute. It is legal, but inefficient, and will result in slower marshaling code.

When the value specified by [max_is] is equal to or greater than zero, the following relationship must be true:

0 <= last_is <= max_is

See Also

field_attributes, [first_is], Interface Definition (IDL) File, [length_is], [max_is], [size_is]


lcid

The [lcid] attribute specifies a locale identifier and enables locale-specific MIDL compiler support.

[
    uuid(uuid-number),
    lcid(localeID)
    [, optional-attribute-list]
]
library library-name
{
    library-definition-statements
}

function-name([parameter-attribute-list, lcid] long  parameter-name,. . .);

Parameters

uuid-number
Specifies a universally unique identification number for the library.
localeID
Specifies the 32-bit locale identifier used in Win32 National Language Support. Typically the locale identifier is given in hexadecimal.
optional-attribute-list
Zero or more attributes to apply to the library.
library-name
The name by which software components refer to the library.
library-definition-statements
One or more MIDL statements which define the contents of the library.
function-name
Specifies the name of the function in the IDL file.
parameter-attribute-list
Zero or more MIDL attributes that will be applied to the function parameter.
parameter-name
Specifies the name of the parameter in the IDL file.

Remarks

The [lcid] syntax has two different forms; the effect of the attribute depends on which syntax you use — either the library statement syntax or the parameter syntax.

When applied to the library statement, along with a localeID argument, as shown in the first example, the [lcid] attribute identifies the locale for a type library or for a function argument and lets you use international characters inside the library block.

Effective with version 3.01.75 of the MIDL compiler, the locale identifier supplied by this attribute not only decorates the resulting type library, but actually changes the behavior of the compiler. Within a library statement, from the point where the [lcid] attribute is used, MIDL will accept input localized according to the specified locale. In particular, full support for Asian languages such as Japanese, Chinese and Korean (full DBCS support) is available. Features supported by the localization are: comments, strings, helpstrings and identifiers. For a complete list of locale identifiers, see the National Language Support Reference in the Windows Base Services online documentation.

Use the /lcid compiler switch to have this localization support available to the entire input file, including file name and directory path, rather than just inside the library block.

When applied to a parameter, the [lcid] attribute lets you pass a locale identifier to a function, as shown in the second example. The following restrictions apply to [lcid] parameters:

  • A function can have at most one [lcid] parameter.
  • The data type of the parameter must be long.
  • The direction of the parameter must be [in] only.
  • The [lcid] parameter must follow any other parameters, except a [retval] parameter.
  • You cannot apply the [lcid] attribute to a dispinterface or coclass parameter.

Examples

[
    uuid(12345678-1234-1234-1234-123456789ABC),
    lcid(0x09),
    version(1.0)
]
library MyLibrary
{
    /* Library definition statements */
};

interface IMyFace : IDispatch
{
    [propget] HRESULT MyFunc([in, lcid] long LocaleID,
                          [out, retval] BSTR * ReturnVal);
    // Other interface definition statements
}

See Also

coclass, dispinterface, Generating a Type Library With MIDL, /lcid, library, ODL File Syntax, ODL File Example, [retval]


length_is

The [length_is] attribute specifies the number of array elements to be transmitted. You must specify a non-negative value.

[length_is( limited-expression-list )]

Parameters

limited-expression-list
Specifies one or more C-language expressions. Each expression evaluates to an integer that represents the number of array elements to be transmitted. The MIDL compiler supports conditional expressions, logical expressions, relational expressions, and arithmetic expressions. MIDL does not allow function invocations in expressions and does not allow increment and decrement operators. Separate multiple expressions with commas.

Remarks

The [length_is] attribute determines the value of the array indexes corresponding to the [last_is] attribute when [last_is] is not specified. The relationship between these array indexes is as follows:

length = last - first + 1

The [length_is] attribute cannot be used at the same time as the [last_is] attribute or the [string attribute].

To define a counted string with a [length_is] or [last_is] attribute, use a character array or pointer without the [string] attribute.

Using a constant expression with the [length_is] attribute is an inappropriate use of the attribute. It is legal, but inefficient, and will result in slower marshaling code.

You can use the [size_is] and [length_is] attributes together. When you do, the [size_is] attribute controls the amount of memory allocated for the data. The [length_is] attribute specifies how many elements are transmitted. The amount of memory specified by the [size_is] and [length_is] attributes need not be the same. For instance, your client may pass an [in,out] parameter to a server and specify a large memory allocation with [size_is], even though it specifies a small number of data elements to be passed with [length_is]. This enables the server to fill the array with more data than it received, which it can then send back to the client.

In general, it isn't useful to specify both [size_is] and [length_is] on [in] or [out] parameters. In both cases, [size_is] controls memory allocation. Your application could use [size_is] to allocate more array elements than it transmits (as specified by [length_is]). However, this would be inefficient. It would also be inefficient to specify identical values for [size_is] and [length_is]. Because it would create extra overhead during parameter marshaling. When the values of [size_is] and [length_is] are always the same, omit the [length_is] attribute.

Examples

/* counted string holding at most "size" characters */
typedef struct
{
    unsigned short size;
    unsigned short length;
    [size_is(size), length_is(length)] char string[*];
 } COUNTED_STRING_TYPE;

/* counted string holding at most 80 characters */
typedef struct
{
    unsigned short length;
    [length_is(length)] char string[80];
} STATIC_COUNTED_STRING_TYPE;

HRESULT Proc1(
    [in] short iLength;
    [in, length_is(iLength)] short asNumbers[10]);

See Also

field_attributes, [first_is], Interface Definition (IDL) File, [last_is], [max_is], [min_is], [size_is], [string]


library

The library statement contains all the information that the MIDL compiler uses to generate a type library.

[
    uuid(uuid-number),
    [, optional-attribute-list]
]
library library-name
{
    library-definition-statements
}

Parameters

uuid-number
Specifies a universally unique identification number for the library.
optional-attribute-list
Specifies additional attributes that apply to the entire library statement. Allowable attributes include [control], [helpcontext], [helpfile], [helpstring], [hidden], [lcid], [restricted], and [version].
library-name
The name by which software components refer to the library.
library-definition-statements
One or more MIDL statements which define the contents of the library.

Remarks

Statements inside the library block can use elements that are declared inside or outside of the library block. Library statements can use those elements as base types, inheriting from those elements, or by simply referencing them on a line, as follows:

interface MyFace
{
    // Interface definition statements
};

[
    // library attributes
]
library
{
    interface MyFace;

    // Other library definition statements.
};

The MIDL compiler will create a type library that includes definitions for every element inside the library block, plus definitions for any elements defined outside and referenced from within the library block.

For information on generating both a type library and proxy stubs and headers from a single IDL file see Generating a Proxy DLL and a Type Library From a Single IDL File.

Example

[
    uuid(12345678-1234-1234-1234-123456789ABC),
    helpstring("Hello 2.0 Type Library"),
    lcid(0x0409),
    version(2.0)
]
library Hello
{
    /* Library definition statements */
};

See Also

Contents of a Type Library, [control], Generating a Type Library With MIDL, [helpcontext], [helpfile], [helpstring], [hidden], [lcid], library, ODL File Syntax, [restricted], [version]


licensed

The [licensed] attribute indicates that the coclass to which it applies is licensed, and must be instantiated using IClassFactory2.

[
    licensed
    [ , attribute-list ]
]
coclass classname
{
    coclass-definition
};

Parameters

attribute-list
Specifies zero or more attributes that apply to the coclass statement. Allowable coclass attributes are [helpstring], [helpcontext], [licensed], [version], [control], and [hidden].
classname
Specifies the name by which the component object is known in the type library.
coclass-definition
Specifies statements that make up the coclass definition.

Remarks

Licensing is a feature of COM that provides control over object creation. Licensed objects can be created only by clients that are authorized to use them. Licensing is implemented in COM through the IClassFactory2 interface and by support for a license key that can be passed at run time.

Flags

TYPEFLAG_FLICENSED

Example

[
    uuid(12345678-1234-1234-1234-123456789ABC),
    licensed,
    helpstring("A meaningfulcomment"
]
coclass MyClass
{
    // coclass definition statements
};

See Also

coclass, Contents of a Type Library, [control], Generating a Type Library With MIDL, [helpstring], [helpcontext], [hidden], [licensed], ODL File Syntax, TYPEFLAGS, [version]


local

The [local] attribute specifies to the MIDL compiler that an interface or function is not remote.

[
    local
    [, interface-attribute-list]
]
interface interface-name
{
}

[
    object,
    uuid(string-uuid),
    local [, interface-attribute-list]
]
interface interface-name
{
}

[ local [, function-attribute-list] ] function-declarator ;

Parameters

interface-attribute-list
Specifies other attributes that apply to the interface as a whole. The attributes [endpoint], [version], and [pointer_default] are optional. When you compile with the /app_config switch, either [implicit_handle] or [auto_handle] can also be present. Separate multiple attributes with commas.
interface-name
Specifies the name by which software components can delineate the interface.
string-uuid
Specifies a UUID string generated by the uuidgen utility. If you are not using the MIDL compiler switch /osf, you can enclose the UUID string in quotes.
function-attribute-list
Specifies zero or more attributes that apply to the function. Valid function attributes are [callback]; the pointer attribute [ref], [unique], or [ptr]; and the usage attributes [string], [ignore], and [context_handle]. Separate multiple attributes with commas.
function-declarator
Specifies the type specifier, function name, and parameter list for the function.

Remarks

The [local] attribute can be applied to individual functions or to the interface as a whole.

When used in the interface header, the [local] attribute allows you to use the MIDL compiler as a header generator. The compiler does not generate stubs for any functions and does not ensure that the header can be transmitted.

For an RPC interface, the [local] attribute cannot be used at the same time as the [uuid] attribute. Either uuid] or [local] must be present in the interface header, and the one you choose must occur exactly once.

For a COM interface (identified by the [object] interface attribute), the interface attribute list can include the [local] attribute even though the [uuid] attribute is present.

When used in an individual function, the [local] attribute designates a local procedure for which no stubs are generated. Using [local] as a function attribute is a Microsoft extension to DCE IDL. Therefore this attribute is not available when you compile using the MIDL /osf switch.

Note that an interface without attributes can be imported into a base IDL file. However, the interface must contain only datatypes with no procedures. If even one procedure is contained in the interface, a local or UUID attribute must be specified.

Examples

/* IDL file #1 */
[
    local
]
interface local_procs
{
    void MyLocalProc(void);
}

/* IDL file #2 */
[
    object,
    uuid(12345678-1234-1234-123456789ABC),
    local
]
interface local_object_procs : IUnknown
{
    void MyLocalObjectProc(void);
}

/* IDL file #3 */
[
    uuid(87654321-1234-1234-123456789ABC)
]
interface mixed_procs
{
    [local] void MyLocalProc(void);
    HRESULT MyRemoteProc([in] short sParam);
}

See Also

/app_config, [auto_handle], [callback], [context_handle], [endpoint], Interface Definition (IDL) File, [ignore], [implicit_handle], /osf, [object], [pointer_default], [ptr], [ref], [string], [unique], [uuid], [version]


long

The long keyword designates a 32-bit integer.

[ signed | unsigned ] long [ int ] declarator-list;

Parameters

declarator-list
Specifies one or more standard C declarators, such as identifiers, pointer declarators, and array declarators. (Function declarators and bit-field declarations are not allowed in structures that are transmitted in remote procedure calls. These declarators are allowed in structures that are not transmitted.) Separate multiple declarators with commas.

Remarks

The long keyword can be preceded by either the keyword signed or the keyword unsigned. The int keyword is optional and can be omitted. To the MIDL compiler, a long integer is signed by default and is synonymous with signed long int. On 32-bit platforms, long is synonymous with int.

The long integer type is one of the base types of the IDL language. The long integer type can appear as a type specifier in const declarations, typedef declarations, general declarations, and function declarators (as a function return–type specifier and as a parameter-type specifier). For the context in which type specifiers appear, see Interface Definition (IDL) File.

See Also

const, MIDL Base Types, hyper, int, short, signed, small, typedef, unsigned


max_is

The [max_is] attribute designates the maximum value for a valid array index.

[max_is(limited-expression-list )]

Parameters

limited-expression-list
Specifies one or more C-language expressions. Each expression evaluates to an integer that represents the highest valid array index. The MIDL compiler supports conditional expressions, logical expressions, relational expressions, and arithmetic expressions. MIDL does not allow function invocations in expressions and does not allow increment and decrement operators. Separate multiple expressions with commas.

Remarks

The [max_is] attribute does not necessarily correspond to the number of elements in the array. For an array of size n in C, where the first array element is element number zero, the maximum value for a valid array index is n–1.

The [max_is] attribute cannot be used as a field attribute at the same time as the [size_is] attribute.

While it is legal to use the [max_is] attribute with a constant expression, doing so is inefficient and unnecessary. For example, use a fixed size array:

/* transmits values of a[0]... a[MAX_SIZE-1] */
HRESULT Proc3([in] short Arr[MAX_SIZE]);

instead of:

/* legal but marshaling code is much slower */
HRESULT Proc3([in max_is(MAX_SIZE-1)] short Arr[] );

Examples

/* if m = 10, there are 11 transmitted elements (a[0]...a[10])*/
HRESULT Proc1(
    [in] short m,
    [in, max_is(m)] short a[]);

/* if m = 10, the valid range for b is b[0...10][20] */
HRESULT Proc2(
    [in] short m,
    [in, max_is(m)] short b[][20];

See Also

field_attributes, Interface Definition (IDL) File, [min_is], [size_is]


maybe

The keyword [maybe] indicates that the remote procedure call does not need to execute every time it is called and the client does not expect a response. Note that the [maybe] protocol ensures neither delivery nor completion of the call.

[
    interface-attribute-list
]
interface interface-name
{
    [maybe [, attribute-list]] returntype function-name(params)
}

Parameters

interface-attribute-list
Specifies a list of zero or more IDL attributes that apply to the interface as a whole. When two or more interface attributes are present, they must be separated by commas.
interface-name
Specifies the name of the interface.
attribute-list
Specifies additional attributes to be applied to the function. Separate multiple attributes with commas.
returntype
Specifies the return type of the function.
function-name
Specifies the name of the function to which the [maybe] attribute will be applied.
params
Function parameter list.

Remarks

A call with the [maybe] attribute cannot contain output parameters and is implicitly an [idempotent] call.

See Also

[broadcast], [idempotent], Interface Definition (IDL) File


message

The [message] attribute indicates that the remote procedure call is to be treated as a message from the client to the server.

[message, optional-attribute-list] void function-name(
    [in, optional-parameter-attributes] param-name,. . .);

Parameters

optional-attribute-list
Other attributes that apply to the function. Only the [local], [nocode], [code], and [optimize] attributes may be used with the [message] attribute.
function-name
The name of the function as defined in the IDL file.
optional-parameter-attributes
Zero or more MIDL attributes that will be applied to the parameter.
param-name
The name of the parameter as defined in the IDL file.

Remarks

As messages from the client, remote procedure calls with the [message] attribute are delivered to the server asynchronously over the ncadg_mq message-queuing transport. You can indicate synchronous-mode messaging by specifying the ncadg_mq transport protocol without using the [message] attribute.

By specifying asynchronous-mode messaging, the [message] attribute allows the client to make the remote procedure call and return immediately, even when the server application is not responding. If the target server is not available, the call will be stored until the server becomes available.

In addition, asynchronous-mode messaging lets you control message-queue properties of the receive queue for the server. See RpcBindingSetOption for more information on selecting quality of service, call priority, and call lifetime for the server process.

The following restrictions also apply to the [message] attribute:

  • Microsoft Message Queuing must be implemented in the client and server systems and the systems must be visible to each other as determined by the scope of the message queue installation.
  • The binding must use well-known endpoints and the ncadg_mq transport protocol.
  • The function cannot contain output parameters or a return type other than void. Note that the latter restriction makes the [message] attribute unsuitable for COM (object) interface methods, at this time. The next release of MIDL will permit [message] functions to return error_status_t or HRESULT.
  • Any interface that contains at least one [message] call must be registered by calling RpcServerRegisterIf or RpcServerRegisterIfEx before calling RpcServerUseProtseqEpEx(ncadg_mq). Otherwise, calls that were waiting on the queue for the server will be read before the interface is registered, and the calls will fail.

Example

[message] void DisplayString(
    [in, string] char * p1);

[message] void VarDataArray(
    [in, size_is(iSize)] ARRAY_TYPE lpMyArray,
    [in] int iSize,
    [in] unsigned long ulChksum);

See Also

[code], [local], ncadg_mq, [nocode], [optimize], RPC Message Queuing, RpcBindingSetOption, RpcBindingInqOption, void


midl_pragma warning

Use the midl_pragma warning option to temporarily override MIDL's warning message behavior at compile time.

midl_pragma warning ( warning_option : message_list )

Parameters

warning_option
The warning option can be one of the following: disable, enable, default.
message_list
A list of message numbers separated by spaces.

Remarks

The pragma can be used like a C-compiler pragma. That is, it disables, enables, or returns to the default behavior for a given MIDL warning.

Examples

#if (__midl >= 501)
midl_pragma warning( disable: 2007 )   // file already imported midl_pragma warning( disable: 2209 )   // ignored redundant attr
#endif

See Also

pragma


midl_user_allocate

The midl_user_allocate function is a function that client and server applications provide to allocate memory.

void __RPC_FAR * __RPC_API midl_user_allocate (size_t cBytes);

Parameters

cBytes
Specifies the count of bytes to allocate.

Remarks

Both client applications and server applications must implement the midl_user_allocate function, unless you are compiling in OSF-compatibility (/osf) mode. Applications and generated stubs call midl_user_allocate when dealing with objects referenced by pointers:

  • The server application should call midl_user_allocate to allocate memory for the application—for example, when creating a new node.
  • The server stub calls midl_user_allocate when unmarshaling pointed-at data into the server address space.
  • The client stub calls midl_user_allocate when unmarshaling data from the server that is referenced by an out pointer. Note that for [in], [out], and [unique] pointers, the client stub calls midl_user_allocate only if the [unique] pointer value was NULL on input and changes to a non-NULL value during the call. If the [unique] pointer was non-NULL on input, the client stub writes the associated data into existing memory.

If midl_user_allocate fails to allocate memory, it must return a NULL pointer.

It is recommended that midl_user_allocate return a pointer that is 8 bytes aligned.

Example

void __RPC_FAR * __RPC_API midl_user_allocate(size_t cBytes)
{
    return(malloc(cBytes));
}

Requirements

Windows NT/2000: Requires Windows NT 3.1 or later.
Windows 95/98: Unsupported.
Header: Declared in Rpcndr.h.

See Also

[allocate], arrays, Arrays and Pointers, Array and Sized-Pointer Attributes, [in], midl_user_free, /osf, [out], [ptr], [ref], [unique]


midl_user_free

The midl_user_free function is provided by client and server applications to deallocate dynamically allocated memory.

void __RPC_API midl_user_free(void __RPC_FAR * p);

Parameters

p
A pointer to the memory block to be freed.

Remarks

Both client application and server application must implement the midl_user_free function, unless you are compiling in OSF-compatibility (/osf) mode. The midl_user_free function must be able to free all storage allocated by midl_user_allocate.

Applications and stubs call midl_user_free when dealing with objects referenced by pointers:

  • The server application should call midl_user_free to free memory allocated by the application—for example, when deleting a specified node.
  • The server stub calls midl_user_free to release memory on the server after marshaling all [out] arguments, [in, out] arguments, and the return value.

Example

void __RPC_API midl_user_free(void __RPC_FAR * p)
{
    free(p);
}

Requirements

Windows NT/2000: Requires Windows NT 3.1 or later.
Windows 95/98: Unsupported.
Header: Declared in Rpcndr.h.

See Also

arrays, Arrays and Pointers, Array and Sized-Pointer Attributes, [in], midl_user_allocate, /osf, [out], unique


min_is

The DCE IDL attribute min_is is not implemented in Microsoft RPC. The value of the minimum valid array index is zero.

See Also

arrays, Interface Definition (IDL) File, [max_is]


module

The module statement defines a group of functions, typically a set of DLL entry points.

[
    attributes
]
module modulename
{
    elementlist
};

Parameters

attributes
The [uuid], [version], [helpstring], [helpcontext], [hidden], and [dllname] attributes are accepted before a module statement. See Attribute Descriptions, in the OLE Automation book, for more information on the attributes accepted before a module definition. The [dllname] attribute is required. If the [uuid] attribute is omitted, the module is not uniquely specified in the system.
modulename
The name of the module.
elementlist
List of constant definitions and function prototypes for each function in the DLL. Any number of function definitions can appear in the function list. A function in the function list has the following form:

[attributes] returntype [calling convention] funcname(params);
[attributes] const constname = constval;

Only the [helpstring] and [helpcontext] attributes are accepted for a const.

The following attributes are accepted on a function in a module: [helpstring], [helpcontext], [string], [entry], [propget], [propput], [propputref], and [vararg]. If [vararg] is specified, the last parameter must be a safe array of VARIANT type.

The optional calling convention can be one of __pascal/_pascal/pascal, __cdecl/_cdecl/cdecl, or __stdcall/_stdcall/stdcall. The calling convention can include up to two leading underscores.

The parameter list is a comma-delimited list of:

[attributes] type paramname

The type can be any previously declared type or built-in type, a pointer to any type, or a pointer to a built-in type. Attributes on parameters are:

[in], [out], [optional]

If [optional] is used, the types of those parameters must be VARIANT or VARIANT *.

Remarks

The header file (.h) output for modules is a series of function prototypes. The module keyword and surrounding brackets are stripped from the header (.h) file output, but a comment (// module modulename) is inserted before the prototypes. The keyword extern is inserted before the declarations.

Examples

[
    uuid(12345678-1234-1234-1234-123456789ABC),
    helpstring("This is not GDI.EXE"),
    helpcontext(190),
    dllname("MATH.DLL")
]
module somemodule
{
    [helpstring(
        "Color for the frame")] unsigned long const COLOR_FRAME =
            0xH80000006;
    [helpstring("Not a rectangle but a square"),
     entry(1)] pascal double square([in] double x);
};

See Also

const, Contents of a Type Library, [dllname], [entry], Generating a Type Library With MIDL, [helpcontext], [helpstring], [hidden], ODL File Syntax, [propget], [propput], [propputref], [string], TYPEFLAGS, [uuid], [vararg], [version]


ms_union

The keyword [ms_union] is used to control the NDR alignment of nonencapsulated unions.

[
    ms_union,
     ...
]
interface interface-name
{
    ...
}

[ms_union] procedure-type procedure-name(param-list);

Parameters

interface-name
Specifies the name of the interface.
procedure-type
Specifies the return type of the procedure to which the [ms_union] attribute is being applied.
procedure-name
Specifies the name of the procedure.
param-list
Specifies the procedure's parameter list, which may be empty.

Remarks

Never use this switch or attribute with new interfaces. This is a backward compatibility feature only.The MIDL compiler in this version of Microsoft RPC mirrors the behavior of the OSF DCE IDL compiler for nonencapsulated unions. However, because earlier versions of the MIDL compiler did not do so, the /ms_union switch provides compatibility with interfaces built on previous versions of the MIDL compiler.

The ms_union feature can be used as an IDL interface attribute, an IDL type attribute, or as a command-line switch (/ms_union).

Example

[ms_union] long procedure (...);

See Also

Interface Definition (IDL) File, /ms_union


ncacn_at_dsp

The ncacn_at_dsp keyword identifies Appletalk DSP as the protocol family for the endpoint.

endpoint("ncacn_at_dsp:[port-name]")

Parameters

port-name
Specifies a character string up to 22 bytes long.

Remarks

The syntax of the Appletalk DSP port string, like all port strings, is defined by the transport implementation and is independent of the IDL specification. The MIDL compiler performs limited syntax checking but does not guarantee that the endpoint specification is correct. Some classes of errors may be reported at run time rather than at compile time.

Example

[
    uuid(12345678-4000-2006-0000-20000000001a),
    version(1.1),
    endpoint("ncacn_at_dsp:[my_services_endpoint]")
]
interface iface
{
    // Interface definition statements.
}

See Also

endpoint, Interface Definition (IDL) File, string binding


ncacn_dnet_nsp

The ncacn_dnet_nsp keyword identifies DECnet as the protocol family for the endpoint.

endpoint("ncacn_dnet_nsp:server-name[port-name]")

Parameters

server-name
Specifies the name or internet address for the server, or host, computer. The name is a character string.
port-name
Specifies a DECnet object name or object number. The object name can consist of up to 16 characters. Object numbers can be prefixed by the pound sign (#).

Remarks

The syntax of the DECnet transport port string, like all port strings, is defined independently of the IDL specification. The compiler performs some syntax checking but does not guarantee that the endpoint specification is correct. Some errors may be reported at run time rather than at compile time.

Examples

[
    uuid(12345678-4000-2006-0000-20000000001a),
    version(1.1),
    endpoint("ncacn_dnet_nsp:node[RPC0034501]")
interface iface
{
    // Interface definition statements.
}

[
    uuid(12345678-1234-1234-1234-123456789ABC),
    version(1.1),
    endpoint("ncacn_dnet_nsp:node[#41]")
]
interface iface
{
    // Interface definition statements.
}

See Also

endpoint, string binding


ncacn_http

The ncacn_http keyword identifies the Microsoft Internet Information Server (IIS) as the protocol family for the endpoint.

ncacn_http:rpc_server[endpoint, HttpProxy=proxy_server:server_port,
RpcProxy=iis_rpc_proxy:proxy_port]

Parameters

rpc_server
The Internet address or name of the machine that the RPC server process is running on.
endpoint
The well-known (static) TCP/IP port that the RPC server process is listening on.
proxy_server
The name of the outgoing HTTP proxy server, if there is one. If you specify a proxy server but do not specify a port number (server_port), port 80 is assumed.
server_port
The number of the port that the proxy server uses for communication.
iis_rpc_proxy
The IIS machine used as proxy to the rpc_server. If no IIS machine is specified, iis_rpc_proxy is assumed to be the same machine as the RPC server. If you do not specify a port number (proxy_port), port 80 is assumed.
proxy_port
The number of the port that the rpc_server uses for communication.

Remarks

Identifying the Microsoft Internet Information Server (IIS) as the protocol family allows client and server applications to communicate across the internet by using the Microsoft Internet Information Server (IIS) as a proxy. Because calls are tunneled through an established HTTP port, they can cross firewalls.

Any RPC client and server applications can support the ncacn_http protocol as long as they are networked to an Internet Information Server. The IIS contacts the RPC server and establishes a TCP/IP socket, which it maintains for the client. The IIS negotiates a TCP/IP connection with the RPC server, and once the negotiation is complete, acts as an RPC proxy, forwarding data between the client-side TCP/IP socket and the server-side TCP/IP socket. When the IIS RPC proxy detects a session close on either the client or the server side, it closes the remaining socket.

The client application implicitly uses static binding to the IIS, but the server can use dynamic endpoints, with the server's RPCSS (endpoint mapper) resolving the RPC server port. If the IIS is on a different machine than the RPC server, the IIS receives the remote call, contacts RPCSS on the RPC server machine to get the server process endpoint, and then forwards the call to the appropriate RPC server.

If Internet Explorer is installed , and no outgoing HTTP proxy server is specified, the transport will check the registry to see if there is a configuration for an HTTP proxy. If a proxy exists, the transport will use it.

Examples

//RPC client accesses an RPC server application, which is listening on //endpoint 2225 of an IIS Web Server named major7.somewhere.com
[
    uuid(12345678-1234-1234-1234-123456789ABC),
    version(1.0),
    endpoint("ncacn_http:major7.somewhere.com[2225]")
]
interface iface
{
    // Interface definition statements.
}

//string binding format.
//IIS Web server (websvr1)is on a different machine than the RPC
//server, and endpoints are dynamic
"obj_uuid@ncacn_http:major7.somewhere.com
    [,RpcProxy=websvr1.somewhere.com]"

//tells the transport to use proxysvr, port 80, as the outgoing http
//server:
"obj_uuid@ncacn_http:major7.somewhere.com[,HttpProxy=proxysvr:80,
    RpcProxy=websvr1.somewhere.com:80]"

See Also

endpoint, Interface Definition (IDL) File, string binding


ncacn_ip_tcp

The ncacn_ip_tcp keyword identifies TCP/IP as the protocol family for the endpoint.

endpoint("ncacn_ip_tcp:server-name[port-name]")

Parameters

server-name
Specifies the name or Internet address for the server, or host, computer. The name is a character string. The Internet address is a common Internet address notation.
port-name
Specifies an optional 16-bit number. Values of less than 1024 are usually reserved. If no value is specified, the endpoint-mapping service selects a valid port-name value.

Remarks

The syntax of the TCP/IP transport port string, like all port strings, is defined independently of the IDL specification. The compiler performs some syntax checking but does not guarantee that the endpoint specification is correct. Some errors may be reported at run time rather than at compilate time.

Example

[
    uuid(12345678-4000-2006-0000-20000000001a),
    version(1.1),
    endpoint("ncacn_ip_tcp:rainier[1404]")
]
interface iface
{
    // Interface definition statements.
}

endpoint("ncacn_ip_tcp:128.10.2.30[1404]")

See Also

endpoint, Interface Definition (IDL) File, ncacn_nb_tcp, ncacn_np, ncacn_spx, ncalrpc, string binding


ncacn_nb_ipx

The ncacn_nb_ipx keyword identifies NetBIOS over IPX as the protocol family for the endpoint.

endpoint("ncacn_nb_ipx:[port-name]")

Parameters

port-name
Specifies an optional 8-bit value ranging from 1 to 254. Values of less than 0x20 are reserved. If the port-name value is not specified, the endpoint-mapping service selects the port value.

Remarks

The syntax of the NetBIOS port string, like all port strings, is defined by the transport implementation and is independent of the IDL specification. The MIDL compiler performs limited syntax checking but does not guarantee that the endpoint specification is correct. Some classes of errors may be reported at run time rather than at compile time.

Example

[
    uuid(12345678-4000-2006-0000-20000000001a),
    version(1.1),
    endpoint("ncacn_nb_ipx:[100]")
]
interface iface
{
    // Interface definition statements.
}

See Also

endpoint, Interface Definition (IDL) File, ncacn_ip_tcp, ncacn_nb_tcp, ncacn_nb_nb, ncacn_at_dsp, ncacn_spx, ncacn_np, ncalrpc, ncadg_ip_udp, ncadg_ipx, string binding


ncacn_nb_nb

The ncacn_nb_nb keyword identifies NetBEUI over NetBIOS as the protocol family for the endpoint.

endpoint("ncacn_nb_nb:[port-name]")

Parameters

port-name
Specifies an optional 8-bit value ranging from 1 to 255. Values of less than 0x20 are reserved. If the port-name value is not specified, the endpoint-mapping service selects the port value.

Remarks

The syntax of the NetBIOS port string, like all port strings, is defined by the transport implementation and is independent of the IDL specification. The MIDL compiler performs limited syntax checking but does not guarantee that the endpoint specification is correct. Some classes of errors may be reported at run time rather than at compile time.

Example

[
    uuid(12345678-4000-2006-0000-20000000001a),
    version(1.1),
    endpoint("ncacn_nb_nb:[100]")
]
interface iface
{
    // Interface definition statements.
}

See Also

endpoint, Interface Definition (IDL) File, ncacn_ip_tcp, ncacn_nb_tcp, ncacn_np, ncacn_spx, ncalrpc, string binding


ncacn_nb_tcp

The ncacn_nb_tcp keyword is used to identify TCP over NetBIOS as the protocol family for the endpoint.

endpoint("ncacn_nb_tcp:[port-name]")

Parameters

port-name
Specifies an optional 8-bit value ranging from 1 to 254. Values of less than 0x20 are reserved. If the port-name value is not specified, the endpoint-mapping service selects the port value.

Remarks

The syntax of the NetBIOS port string, like all port strings, is defined by the transport implementation and is independent of the IDL specification. The MIDL compiler performs limited syntax checking but does not guarantee that the endpoint specification is correct. Some classes of errors may be reported at run time rather than at compile time.

Example

[
    uuid(12345678-4000-2006-0000-20000000001a),
    version(1.1),
    endpoint("ncacn_nb_tcp:[100]")
]
interface iface
{
    // Interface definition statements.
}

See Also

endpoint, Interface Definition (IDL) File, ncacn_ip_tcp, ncacn_nb_nb, ncacn_np, ncacn_spx, ncalrpc, string binding


ncacn_np

The ncacn_np keyword identifies named pipes as the protocol family for the endpoint. On Microsoft®Windows 95/98, ncacn_np is supported only for client applications.

endpoint("ncacn_np:server-name[\\pipe\\pipe-name]")

Parameters

server-name
Optional. Specifies the name of the server. Backslash characters are optional.
pipe-name
Specifies a valid pipe name. A valid pipe name is a string containing identifiers separated by backslash characters. The first identifier must be pipe. Each identifier must be separated by two backslash characters.

Remarks

A server creates an instance of a named pipe that is then available to any client. When a client attempts to connect, the existing instance is associated with that client. Before another client can connect, the server must create another instance of the named pipe. If a client tries to bind to the server before the new instance is created, the binding call, RpcBindingFromStringBinding, may fail with the error message RPC_S_SERVER_TOO_BUSY. Therefore, you need to make sure that your client application handles the case where the server is too busy to accept a connection. The client should automatically retry, prompt the user for a course of action, or fail gracefully.

The syntax of the named-pipe port string, like all port strings, is defined by the transport implementation and is independent of the IDL specification. The MIDL compiler performs limited syntax checking but does not guarantee that the endpoint specification is correct. Some classes of errors may be reported at run time rather than at compile time.

Examples

[
    uuid(12345678-4000-2006-0000-20000000001a),
    version(1.1),
    endpoint("ncacn_np:[\\pipe\\stove\\hat]")
]
interface iface1
{
    // Interface definition statements.
}

[
    uuid(87654321-4000-2006-0000-20000000001b),
    version(1.1),
    endpoint("ncacn_np:\\\\myotherserver[\\pipe\\corncob]")
]
interface iface2
{
    // Interface definition statements.
}

See Also

endpoint, Interface Definition (IDL) File, ncacn_at_dsp, ncacn_dnet_nsp, ncacn_ip_tcp, ncacn_nb_ipx, ncacn_spx, ncacn_nb_nb, ncacn_nb_tcp, ncacn_vns_spp, ncalrpc, ncadg_ipx, ncadg_ip_udp, string binding


ncacn_spx

The ncacn_spx keyword identifies SPX as the protocol family for the endpoint.

endpoint("ncacn_spx:link-address[port-name]")

Parameters

link-address
Specifies the host server. This may be either a character string (the server name), or a 20-digit hexadecimal number that consists of the host server's network address (8 digits) concatenated with the node address (12 digits). See Remarks for instructions on how to obtain the network address and node address. A NULL string specifies the local computer.
port-name
Specifies an optional 16-bit number that represents the socket address. Values can range from 1 to 65,535. When no value is specified, the endpoint-mapping service selects a valid port-name value.

Remarks

When you use the ncacn_spx transport, the server name is exactly the same as the 32-bit Windows NT/Windows 2000 name. However, since the names are distributed using Novell protocols, they must conform to the Novell naming conventions. If a server name is not a valid Novell name, servers will not be able to create endpoints with the ncacn_spx transport. The following is a partial list of characters prohibited in Novell server names:

" * + . / : ; < = > ? [ ] \ |

The ncacn_spx transport is not supported by the version of NWLink supplied with MS Client 3.0.

16-bit Windows client applications that use the ncacn_spx transport require that the file Nwipxspx.dll be installed in order to run under the Windows NT/Windows 2000 Win32 on Win16 (WOW) subsystem. Contact Novell to obtain this file.

Note To obtain the network and node addresses, use Novell's comcheck utility, or the Novell-defined API IPXGetInternetAddress. On Windows NT/Windows 2000, you can also obtain these addresses with the ipxroute config command.

The syntax of the SPX transport port string, like all port strings, is defined independently of the IDL specification. The compiler performs some syntax checking but does not guarantee that the endpoint specification is correct. Some errors may be reported at run time rather than at compile time.

Example

[
    uuid(12345678-4000-2006-0000-20000000001a),
    version(1.1),
    endpoint("ncacn_spx:[1000]")
]
interface iface
{
    // Interface definition statements.
}

See Also

endpoint, Interface Definition (IDL) File, ncacn_at_dsp, ncacn_dnet_nsp, ncacn_ip_tcp, ncacn_nb_ipx, ncacn_nb_nb, ncacn_nb_tcp, ncacn_np, ncacn_vns_spp, ncalrpc, ncadg_ipx, ncadg_ip_udp, string binding


ncacn_vns_spp

The ncacn_vns_spp keyword identifies Banyan Vines SPP as the protocol family for the endpoint.

endpoint("ncacn_vns_spp:server-name[port-address]")

Parameters

server-name
Specifies the StreetTalk name of the server. The name is of the form item@group@organization. The item can be up to 31 characters long and the group and organization can be up to 15 characters.
port-name
Specifies a Banyan Vines SPP port. The valid range for static endpoints is 250– 511.

Remarks

In order to use the ncacn_vns_spp transport protocol in distributed applications running on Windows NT/Windows 2000, Banyan's Enterprise Client for Windows NT must be installed. After installation, open Control Panel, choose Configuration and Add, then select Service | Banyan | RPC services for Banyan. Support for 16-bit clients (MS-DOS and Windows 3.x) requires appropriate Vines software.

For more information on Enterprise Client for Windows NT and 16-bit Vines software, contact http://WWW.BANYAN.COM or call:

In USA 1-800-2-BANYAN
In Canada (905)-855-2971
In Europe 31-3465-75080
In Asia Pacific (852) 2821-9700

The syntax of the Banyan Vines SPP transport port string, like all port strings, is defined independently of the IDL specification. The compiler performs some syntax checking but does not guarantee that the endpoint specification is correct. Some errors may be reported at run time rather than at compile time.

Example

[
    uuid(12345678-1234-1234-1234-123456789ABC),
    version(1.1),
    endpoint("ncacn_vns_spp:printer@sdkgrp@company[260]")
]
interface iface
{
    // Interface definition statements.
}

See Also

endpoint, Interface Definition (IDL) File, ncacn_at_dsp, ncacn_dnet_nsp, ncacn_ip_tcp, ncacn_nb_ipx, ncacn_spx, ncacn_nb_nb, ncacn_nb_tcp, ncacn_np, ncalrpc, ncadg_ipx, ncadg_ip_udp, string binding


ncadg_ip_udp

The ncadg_ip_udp keyword identifies the datagram version of TCP/IP as the protocol family for the endpoint.

endpoint("ncadg_ip_udp:server-name[port-name]")

Parameters

server-name
Specifies the name or internet address for the server, or host, computer. The name is a character string and may be a fully-qualified domain name. The internet address is a common internet address notation.
port-name
Specifies an optional 16-bit number. Values of less than 1024 are usually reserved. If no value is specified, the endpoint-mapping service selects a valid port-name value.

Remarks

The following restrictions apply to the datagram protocols, ncadg_ipx and ncadg_ip_udp:

  • They do not support callbacks. Any functions using the [callback] attribute will fail.
  • They do not support use of the pipe type constructor.

The syntax of the TCP/IP transport port string, like all port strings, is defined independently of the IDL specification. The compiler performs some syntax checking but does not guarantee that the endpoint specification is correct. Some errors may be reported at run time rather than at compile time.

Example

[
    uuid(12345678-4000-2006-0000-20000000001a),
    version(1.1),
    endpoint("ncadg_ip_udp:rainier[1404]")
]
interface iface1
{
    // Interface definition statements.
}

[
    uuid(87654321-4000-2006-0000-20000000001a),
    version(1.1),
    endpoint("ncadg_ip_udp:128.10.2.30[1404]")
]
interface iface2
{
    // Interface definition statements.
}

See Also

[endpoint], Interface Definition (IDL) File, ncacn_at_dsp, ncacn_dnet_nsp, ncacn_ip_tcp, ncacn_nb_ipx, ncacn_spx, ncacn_nb_nb, ncacn_nb_tcp, ncacn_np, ncacn_vns_spp, ncalrpc, ncadg_ipx, string binding


ncadg_ipx

The ncadg_ipx keyword identifies IPX as the protocol family for the endpoint.

endpoint("ncadg_ipx:link-address[port-name]")

Parameters

link-address
Specifies the host server. This may be either a character string (the server name), or a 20-digit hexadecimal number that consists of the host server's network address (8 digits) concatenated with the node address (12 digits). See Remarks for instructions on how to obtain the network address and node address. A NULL string specifies the local computer.
port-name
Specifies an optional 16-bit number that represents the socket address. Values can range from 1 to 65535. When no value is specified, the endpoint-mapping service selects a valid port-name value.

Remarks

The following restrictions apply to the datagram protocols, ncadg_ipx and ncadg_ip_udp:

  • They do not support callbacks. Any functions using the [callback] attribute will fail.
  • They do not support use of the pipe type constructor.

When using the ncadg_ipx transport, the server name is exactly the same as the 32-bit Windows server name. However, since the names are distributed using Novell protocols, they must conform to the Novell naming conventions. If a server name is not a valid Novell name, servers will not be able to create endpoints with the ncadg_ipx transport. The following is a partial list of characters prohibited in Novell server names:

" * + . / : ; < = > ? [ ] \ |

The ncadg_ipx transport is supported by the version of NWLink supplied with MS Client 3.0.

16-bit Windows client applications that use the ncadg_ipx transport require that the file Nwipxspx.dll be installed in order to run under the Windows NT/Windows 2000 Win32 on Win16 (WOW) subsystem. Contact Novell to obtain this file.

To obtain the network and node addresses, use Novell's comcheck utility, or the Novell-defined API IPXGetInternetAddress. On Windows NT/Windows 2000, you can also obtain these addresses with the ipxroute config command.

The syntax of the TCP/IP transport port string, like all port strings, is defined independently of the IDL specification. The compiler performs some syntax checking but does not guarantee that the endpoint specification is correct. Some errors may be reported at run time rather than at compile time.

Example

[
    uuid(12345678-4000-2006-0000-20000000001a),
    version(1.1),
    endpoint("ncadg_ipx:[1000]")
]
interface iface
{
    // Interface definition statements.
}

See Also

[endpoint], Interface Definition (IDL) File, ncacn_at_dsp, ncacn_dnet_nsp, ncacn_ip_tcp, ncacn_nb_ipx, ncacn_spx, ncacn_nb_nb, ncacn_nb_tcp, ncacn_np, ncacn_vns_spp, ncalrpc, ncadg_ip_udp, string binding


ncadg_mq

The ncadg_mq keyword identifies Microsoft Message Queuing Services (MSMQ) as the transport protocol for the endpoint.

endpoint("ncadg_mq:server-name")

Parameters

server-name
Specifies the name of the server, or host, computer. The name is a character string and may be a fully-qualified domain name.

Remarks

In order to use the ncadg_mq transport protocol, the MSMQ components must be fully installed and the client and server systems must be reachable through the MQ protocols.

The ncadg_mq protocol does not support dynamic endpoints or broadcast calls. As with other datagram protocols, ncadg_mq does not support callbacks; any functions using the callback attribute will fail.

Example

[
    uuid(12345678-4000-2006-0000-20000000001a),
    version(1.1),
    endpoint("ncadg_mq:rainier")
]
interface iface
{
    // Interface definition statements.
}

Note The syntax of the message-queue protocol is defined independently of the IDL specification. The MIDL compiler performs some syntax checking but does not guarantee that the endpoint specification is correct. Some errors may be reported at run time rather than during compilation.

See Also

[broadcast], [callback], [endpoint], Interface Definition (IDL) File, message, RPC Message Queuing, string binding


ncalrpc

The ncalrpc keyword identifies local interprocess communication as the protocol family for the endpoint. This keyword is one of the valid protocol family names that must be used with the [endpoint] attribute.

endpoint("ncalrpc:[port-name]")

Parameters

port-name
A character string that specifies the communication port (an application, a service, or an instance of a service) that a client uses to make interprocess calls to a server. The string can contain up to 250 characters and should not contain any backslash (\) characters. The computer name must not be used with the ncalrpc keyword.

Remarks

The syntax of the local interprocess-communication port string, like all port strings, is defined by the transport implementation and is independent of the IDL specification. The MIDL compiler performs limited syntax checking but does not guarantee that the endpoint specification is correct. Some classes of errors may be reported at run time rather than at compile time.

Example

[
    uuid(12345678-4000-2006-0000-20000000001a),
    version(1.1),
    endpoint("ncalrpc:[myapplicationname]")
]
interface iface
{
    // Interface definition statements.
}

See Also

[endpoint], Interface Definition (IDL) File, ncacn_at_dsp, ncacn_dnet_nsp, ncacn_ip_tcp, ncacn_nb_ipx, ncacn_spx, ncacn_nb_nb, ncacn_nb_tcp, ncacn_np, ncacn_vns_spp, ncadg_ip_udp, ncadg_ipx, string binding


nocode

The [nocode] attribute is used in ACF headers or with individual functions to prevent the generation of client stub code.

[
    nocode
    [ , ACF-interface-attributes ]
]
interface interface-name
{
    [ include filename-list ; ]
    [ typedef [type-attribute-list] typename; ]
    [ [ nocode [ , ACF-function-attributes ] ] function-name (
        [ ACF-parameter-attributes ] parameter-name ;
        ...);
    ]
    ...
}

Parameters

ACF-interface-attributes
Specifies a list of one or more attributes that apply to the interface as a whole. Valid attributes include either [auto_handle] or [implicit_handle] and either [code] or [nocode]. When two or more interface attributes are present, they must be separated by commas.
interface-name
Specifies the name of the interface. In DCE-compatibility mode, the interface name must match the name of the interface specified in the IDL file. When you use the MIDL compiler switch /acf, the interface name in the ACF and the interface name in the IDL file can be different.
filename-list
Specifies a list of one or more C-language header file names, separated by commas. The full file name, including the extension, must be supplied.
type-attribute-list
Specifies a list of one or more attributes, separated by commas, that apply to the specified type. Valid type attributes include [allocate].
typename
Specifies a type defined in the IDL file. Type attributes in the ACF can only be applied to types previously defined in the IDL file.
ACF-function-attributes
Specifies attributes that apply to the function as a whole, such as [comm_status]. Function attributes are enclosed in square brackets. Separate multiple function attributes with commas.
function-name
Specifies the name of the function as defined in the IDL file.
ACF-parameter-attributes
Specifies ACF attributes that apply to a parameter. Note that zero or more attributes can be applied to the parameter. Separate multiple parameter attributes with commas. ACF parameter attributes are enclosed in square brackets.
parameter-name
Specifies a parameter of the function as defined in the IDL file. Each parameter for the function must be specified in the same sequence and using the same name as defined in the IDL file.

Remarks

The [nocode] attribute can appear in the ACF header, or it can be applied to an individual function.

When the [nocode] attribute appears in the ACF header, client stub code is not generated for any remote function unless it has the [code] function attribute. You can override the [nocode] attribute in the header for an individual function by specifying the [code] attribute as a function attribute.

When the [nocode] attribute appears in the function's attribute list, no client stub code is generated for the function.

Client stub code is not generated when:

  • The ACF header includes the [nocode] attribute.
  • The [nocode] attribute is applied to the function.
  • The [local] attribute applies to the function in the interface file.

Either [code] or [nocode] can appear in a function's attribute list, and the one you choose can appear exactly once.

The [nocode] attribute is ignored when server stubs are generated. You cannot apply it when generating server stubs in DCE-compatibility mode.

See Also

Application Configuration File (ACF), /acf, [allocate], [auto_handle], [code], [comm_status], [implicit_handle]


nonbrowsable

Use the [nonbrowsable] attribute to tag an interface or dispinterface member that should not be displayed in a properties browser.

[property-attribute-list, nonbrowsable]return-type property-name(prop-param-list)

Parameters

property-attribute-list
Other attributes that apply to the property.
return-type
The type of the data returned by the method.
property-name
The name of the property or method.
prop-param-list
Zero or more parameters to be passed to the method.

Remarks

Certain properties should not be displayed in a properties browser. This may be because retrieving the value would take a very long time. The example prevents the user from attempting to retrieve the Count property, which returns the number of rows in the dynaset.This number may represent the results of a very large query.

Other properties may have unexpected effects on the browser. For example, consider a control with the property "IsSelected" to tell whether the control is selected. If "IsSelected" is set to false, a selection-based properties browser will browse a different object.

Note that a property tagged as [nonbrowsable] will still appear in an object browser, which does not show property values.

Typeflag Representation

The presence of FUNCFLAG_FNONBROWSABLE or VARFLAG_FNONBROWSABLE.

Example

[
    dual,
    uuid(12345678-1234-1234-1234-123456789ABC),
    restricted
]
interface IDynaset:IDispatch
{
    [propget, nonbrowsable]HRESULT Count([out, retval] long *Value);
}

See Also

ODL File Syntax, ODL File Example, Generating a Type Library With MIDL


noncreatable

The [noncreatable] attribute defines an object that cannot be instantiated by itself.

[
    coclass-attribute-list,
    noncreatable
]
coclass coclass-name
{
    coclass-interface-list
}

Parameters

coclass-attribute-list
Other attributes that apply to the class.
coclass-name
The name of the class.
coclass-interface-list
A list of interfaces for the class.

Remarks

Use the [noncreatable] attribute on a coclass statement to indicate to users that they cannot create a new object of this class at the top level—that is, by calling CreateInstance or CoCreateInstance. Instantiation of an object of this class requires a method call to another object. For example, in Microsoft® Excel®, the "Cell" object is noncreatable and must be obtained from a Microsoft Excel Worksheet object.

Methods that return instances of noncreatable classes should return the exact type of the object, rather than VARIANT or Idispatch* types.

Typeflag Representation:

The absence of TYPEFLAG_FCANCREATE.

Example

[
    uuid(12345678-1234-1234-1234-123456789ABC),
    helpstring("This is MyCOClass"),
    noncreatable
]
coclass MyCoClass
{
    [default] interface IMyClass;
    [default, source] dispinterface IMyClassEvents;
}

See Also

coclass, ODL File Syntax, ODL File Example, Generating a Type Library With MIDL


nonextensible

The [nonextensible] attribute specifies that the IDispatch implementation includes only the properties and methods listed in the interface description and cannot be extended with additional members at run time. (By default, Automation assumes that interfaces may add members at run time; that is, it assumes they are extensible.)

[
    uuid(uuid-number),
    nonextensible
    [, optional-attribute-list]
]
interface | dispinterface interface-name
{
    interface-definition
}

Parameters

uuid-number
Specifies a universally unique identification number for the interface.
optional-attribute-list
Specifies a list of zero or more MIDL interface attributes.
interface-name
Specifies the name of the interface or dispinterface.
interface-definition
Specifies IDL statements that form the definition of the interface or dispinterface.

Remarks

You can apply the [nonextensible] attribute to either an interface or a dispinterface. However, an interface must also have the [dual] and [oleautomation] attributes.

Flags

TYPEFLAG_FNONEXTENSIBLE

Examples

library Hello
{
    [
        uuid(12345678-1234-1234-1234-123456789ABC),
        helpstring("A helpful description."),
        oleautomation,
        dual,
        nonextensible
    ]
    interface IHello : IDispatch
    {
        // Interface definition statements.
    }
}

See Also

Contents of a Type Library, dispinterface, [dual], Generating a Type Library With MIDL, interface, ODL File Syntax, [oleautomation], TYPEFLAGS


notify

The [notify] attribute instructs the MIDL compiler to generate a call to a [notify] procedure on the server side of the application.

[notify] procedure-name();

Parameters

procedure-name
The name of the remote procedure with which the notify procedure will be associated.

Remarks

The [notify] procedure called as a result of the [notify] attribute is associated with a particular remote procedure on the server. It is similar in concept to a callback function. The stub calls the [notify] procedure after all the output arguments of the remote procedure with which it is associated have been marshaled and any memory associated with the parameters is freed.

The [notify] attribute is useful to develop applications acquiring resources in remote procedures. These resources are then freed in the [notify] procedure after the output parameters of the remote procedure are fully marshaled.

The [notify] procedure name is the name of the remote procedure suffixed by _notify. The _notify procedure does not require any parameters and does not return a result. A prototype of this procedure is also generated in the header file. For example, if the IDL file contains the following:

MyProcedure([in] short S);

Specify the following in the ACF for MIDL to generate the _notify call:

[notify] MyProcedure();

The MIDL compiler will generate server stub code which contains the following call to the _notify procedure:

MyProcedure_notify();

The header file will contain a prototype:

void MyProcedure_notify(void);

Example

[notify] MyProcedure();

See Also

Application Configuration File (ACF)


object

The [object] interface attribute identifies a COM interface. (An interface attribute list that does not include the [object] attribute indicates a DCE RPC interface.)

[
    object,
    uuid(string-uuid)
    [ , interface-attribute-list]
]
interface interface-name : base-interface
{
    …
}

Parameters

string-uuid
A UUID string generated by the uuidgen utility. You can enclose the UUID string in quotes.
interface-attribute-list
Other attributes that apply to the interface as a whole.
interface-name
The name of the interface.
base-interface
The COM interface from which this interface derives. The base interface must be IUnknown, IDispatch, or another COM interface that derives, either directly or indirectly, from IUnknown or IDispatch.

Remarks

An interface attribute list for a COM interface must include the [uuid] attribute, but it cannot include the [version] attribute.

By default, compiling a COM interface with the MIDL compiler generates the files needed to build a proxy DLL. This DLL contains the code to support the use of the custom COM interface by both client applications and object servers. However, if the interface attribute list for a COM interface specifies the [local] attribute, the MIDL compiler generates only the interface header file.

The MIDL compiler automatically generates an interface data type for a COM interface. As an alternative, you can use typedef with the interface keyword to explicitly define an interface data type. The interface specification can then use the interface data type in function parameters and return values, struct and union members, and other type declarations. The following example illustrates the use of an automatically generated IStream data type:

[
    object,
    uuid (ABCDEFOO-1234-1234-5678-ABCDEF123456)
]
interface IStream : IUnknown
{
    typedef IStream * LPSTREAM;
    // Other interface definition statements.
}

In a COM interface, all the interface member functions are assumed to be virtual functions. A virtual function has an implicit this pointer as the first parameter. The virtual function table contains an entry for each interface member function.

Non-[local] object interface member functions must have a return value of HRESULT or SCODE. (Note that earlier versions of MIDL allowed member functions to return void. However, beginning with MIDL version 3.0, returning void generates a compiler error.) Having a return value of HRESULT or SCODE means that if an exception is generated during a remote call, the generated proxies catch the exception and return the exception code in the return value. If your application can afford to ignore errors that occur during a remote procedure call, you can specify HRESULT as the return type without checking the return value after the call.

If you are recompiling an old application, changing the return types can introduce backward compatibility problems when the server sends the newly introduced result to the client. As an alternative to changing the return type, you can label the function that returns void with the [call_as] attribute, thus making it a local function. Then define a related remote function with the same parameters but with the return type of HRESULT. The local function can raise an exception based on that HRESULT value, if necessary.

The [object] attribute is not available when you compile using the MIDL compiler /osf switch.

Examples

[
    uuid(12345678-1234-1234-1234-123456789ABC),
    object
]
interface IMyInterface : IUnknown
{
    // Interface definition statements.
}

[
    uuid(87654321-1234-1234-1234-123456789ABC),
    object,
    local
]
interface ILocalInterface : ISomeOldCOMInterface
{
    // Interface definition statements.
}

See Also

[call_as], Interface Definition (IDL) File, [iid_is], interface, [local], /osf, typedef, [uuid], [version]


odl

Remarks

MKTYPLIB required the [odl] attribute on ODL interfaces. The MIDL compiler does not require the [odl] attribute; it is recognized only for compatibility with older ODL files.


oleautomation

The [oleautomation] attribute indicates that an interface is compatible with Automation.

[
    oleautomation,
    uuid(string-uuid)
    [ , interface-attribute-list]
]
interface interface-name : base-interface
{
    …
}

Parameters

string-uuid
Specifies a UUID string generated by the uuidgen utility.
interface-attribute-list
Specifies other attributes that apply to the interface as a whole.
interface-name
Specifies the name of the interface.
base-interface
Specifies the name of an Automation interface from which this derived interface inherits member functions, status codes, and interface attributes. All Automation interfaces are derived from IUnknown or IDispatch.

Example

library Hello
{
    importlib("stdole32.tlb");
    [
        uuid(12345678-1234-1234-1234-123456789ABC),
        helpstring("Application object for the Hello application."),
        oleautomation,
        dual
    ]
    interface IHello : IDispatch
    {
        // Interface definition statements.
    }

    // Other library definition statements.
}

Remarks

The parameters and return types specified for the members of an [oleautomation] interface must be Automation-compatible, as listed in the following table.

Type | Description
Boolean | The MIDL base type Boolean is incompatible with the [oleautomation] attribute. Use VARIANT_BOOL instead.
unsigned char | 8-bit unsigned data item.
Double | 64-bit IEEE floating-point number.
Float | 32-bit IEEE floating-point number.
Int | Integer whose size is system dependent. On 32-bit platforms, MIDL treats int as a 32-bit signed integer.
Long | 32-bit signed integer.
Short | 16-bit signed integer.
BSTR | Length-prefixed string, as described in the Automation topic BSTR.
CY | (Formerly CURRENCY) 8-byte fixed-point number.
DATE | 64-bit floating-point fractional number of days since December 30, 1899.
SCODE | Built-in error type that corresponds to HRESULT.
Enum | Signed integer, whose size is system-dependent. In remote operations, enum objects are treated as 16-bit unsigned entities. Applying the [v1_enum] attribute to an enum type definition allows enum objects to be transmitted as 32-bit entities.
IDispatch * | Pointer to IDispatch interface (VT_DISPATCH).
IUnknown * | Pointer to interface that is not derived from IDispatch (VT_UNKNOWN). (Any COM interface can be represented by its IUnknown interface.)

A parameter is compatible with Automation if its type is an Automation-compatible type, a pointer to an Automation-compatible type, or a SAFEARRAY of an Automation-compatible type.

A return type is compatible with Automation if its type is an HRESULT, SCODE or void. However, MIDL requires that interface methods return either HRESULT or SCODE. Returning void generates a compiler error.

A member is compatible with Automation if its return type and all its parameters are Automation compatible.

An interface is compatible with Automation if it is derived from IDispatch or IUnknown, it has the [oleautomation] attribute, and all of its VTBL entries are Automation compatible. For 32-bit platforms, the calling convention for all methods in the interface must be STDCALL. For 16-bit systems, all methods must have the CDECL calling convention.

Every dispinterface is implicitly Automation-compatible. Therefore you should not use the [oleautomation] attribute on dispinterfaces.

The [oleautomation] attribute is not available when you compile using the MIDL compiler /osf switch.

Flags

TYPEFLAG_FOLEAUTOMATION

See Also

Differences Between MIDL and MKTYPLIB, Interface Definition (IDL) File, Generating a Type Library With MIDL, ODL File Example, ODL File Syntax, /osf, uuid


optimize

The keyword [optimize] is used to fine tune the level of gradation for marshaling data.

optimize ("optimization-options")

Parameters

optimization-options
Specifies the method of marshaling data. Use either "s" for mixed-mode marshaling or "i" for interpreted marshaling.

Remarks

This version of RPC provides two methods for marshaling data: mixed-mode ("s") and interpreted ("i"). These methods correspond to the /Os and /Oi command-line switches. The interpreted method marshals data completely offline. While this can reduce the size of the stub considerably, performance can be affected.

If performance is a concern, the mixed-mode method can be the best approach. Mixed-mode allows the MIDL compiler to make the determination between which data will be marshaled inline and which will be marshaled by a call to an offline dynamic-link library. If many procedures use the same data types, a single procedure can be called repeatedly to marshal the data. In this way, data that is most suited to inline marshaling is processed inline while other data can be more efficiently marshaled offline.

Note that the [optimize] attribute can be used as an interface attribute or as an operation attribute. If it is used as an interface attribute, it sets the default for the entire interface, overriding command-line switches. If, however, it is used as an operation attribute, it affects only that operation, overriding command-line switches and the interface default.

Examples

optimize ("s") HRESULT FasterProcedure(...);
optimize ("i") HRESULT SmallerProcedure(...);

See Also

Application Configuration File (ACF), /Oi, /Os


optional

The [optional] attribute specifies an optional parameter for a member function.

return-type function-name([optional [, other-attributes]] parameter-type parameter-name)

Parameters

return-type
Specifies the return type of the function.
function-name
Specifies the name of the function as defined in the IDL file.
other-attributes
Zero or more optional MIDL attributes.
parameter-type
The data type of the optional parameter.
parameter-name
Specifies the name of the optional parameter.

Remarks

The [optional] attribute is valid only if the parameter is of type VARIANT or VARIANT *.

The MIDL compiler accepts the following parameter ordering (from left-to-right):

  1. Required parameters (parameters that do not have the [defaultvalue] or [optional] attributes),
  2. Optional parameters with or without the [defaultvalue] attribute,
  3. Parameters with the [optional] attribute and without the [defaultvalue] attribute,
  4. [lcid] parameter, if any,
  5. [retval] parameter

You cannot apply the [optional] attribute to a parameter that also has the [lcid] or [retval] attributes.

Example

HRESULT MyFunc([in, optional] VARIANT Param1,
               [out, optional] VARIANT Param2)

See Also

[defaultvalue], Differences Between MIDL and MKTYPLIB, Generating a Type Library With MIDL, [lcid], ODL File Example, ODL File Syntax, [retval]


out

The [out] attribute identifies pointer parameters that are returned from the called procedure to the calling procedure (from the server to the client).

[ [function-attribute-list] ] type-specifier [pointer-declarator] function-name(
    [ out [ , parameter-attribute-list ] ] type-specifier [declarator]
    , ...
);

Parameters

function-attribute-list
Specifies zero or more attributes that apply to the function. Valid function attributes are [callback], [local]; the pointer attribute [ref], [unique], or [ptr]; and the usage attributes [string], [ignore], and [context_handle].
type-specifier
Specifies a base_type, struct, union, or enum type or type identifier. An optional storage specification can precede type-specifier.
pointer-declarator
Specifies zero or more pointer declarators. A pointer declarator is the same as the pointer declarator used in C; it is constructed from the * designator, modifiers such as far, and the qualifier const.
function-name
Specifies the name of the remote procedure.
parameter-attribute-list
Specifies zero or more attributes appropriate for a specified parameter type. Parameter attributes with the [out] attribute can also take the directional attribute [out]; the field attributes [first_is], [last_is], [length_is], [max_is], [size_is], and [switch_type]; the pointer attribute [ref], [unique], or [ptr]; and the usage attributes [context_handle] and [string]. The usage attribute [ignore] cannot be used as a parameter attribute. Separate multiple attributes with commas.
declarator
Specifies the standard declarators, such as identifiers, pointer declarators, and array declarators. For more information, see Array and Sized-Pointer Attributes, arrays, and Arrays and Pointers. The parameter declarator in the function declarator, such as the parameter name, is optional.

Remarks

The [out] attribute indicates that a parameter that acts as a pointer and its associated data in memory are to be passed back from the called procedure to the calling procedure.

The [out] attribute must be a pointer. DCE IDL compilers require the presence of an explicit * as a pointer declarator in the parameter declaration. Microsoft IDL offers an extension that drops this requirement and allows an array or a previously defined pointer type.

A related attribute, [in], indicates that the parameter is passed from the calling procedure to the called procedure. The [in] and [out] attributes specify the direction in which the parameters are passed. A parameter can be defined as [in]-only, [out]-only, or [in, out].

An [out]-only parameter is assumed to be undefined when the remote procedure is called and memory for the object is allocated by the server. Since top-level pointer/parameters must always point to valid storage, and therefore cannot be NULL, [out] cannot be applied to top-level [unique] or [ptr] pointers. Parameters that are [ref] pointers must be either [in] or [in, out] parameters.

Example

HRESULT MyFunction([out] short * pcount);

See Also

arrays, MIDL Base Types, [callback], const, [context_handle], enum, [first_is], [ignore], [in], last_is ], [length_is], [local], [max_is], [ptr], [ref], [size_is], [string], struct, [switch_type], union, [unique]


out_of_line

The DCE IDL keyword out_of_line is not supported in Microsoft RPC.

See Also

Interface Definition (IDL) File


partial_ignore

The ACF attribute [partial_ignore] defines a specialized version of [unique] pointers that provides optional-out semantics.

[ [function-attribute-list <>] ] type-specifier <> [pointer- <>declarator <>] function-name <>( [ partial_ignore [ , parameter-attribute-list <> ] ] type-specifier <> [declarator <>] , ...);

Remarks

When creating a function, it is common to allow users to specify a non-NULL pointer to optional return data, often referred to as an optional-out pointer. The memory pointed to by the user is not typically required to be initialized. This technique represents a problem when the function is used over RPC.

If the optional-out pointer is valid, but points to uninitialized data, RPC attempts to marshal that data and send it to the server, which can cause the marshaling to fail and abort the call. Even if the marshaling succeeds, a potentially large amount of useless data is sent to the server.

These problems are solved by marking the pointer as [in, out, unique, partial_ignore]. All four attributes must be present. When a [partial_ignore] pointer is marshaled on the client side, the only data sent to the server is an indicator showing whether the pointer is NULL. If the pointer is non-NULL, the server-side routine receives a valid pointer to a block of memory that has been initialized with zeros. If the pointer is NULL, the server-side routine receives a NULL pointer.

In this situation, the maximum size of the pointer must be well defined either at compile time or based on input parameters, because the server needs to allocate space for the memory location being pointed to. For example, a simple [string] pointer does not have a well defined size because the string is implicitly terminated by a NULL character. In this case, specifying the maximum size of the string by adding a [size_is] attribute would achieve the well defined size requirement.

Example

/* The MoveLeft function will move one position to the left and optionally return the previous position */
void MoveLeft([in, out, unique, partial_ignore] long *pPrevPosition);

See Also

unique


pipe

The pipe type constructor makes it possible to transmit an open-ended stream of typed data across a remote procedure call.

typedef pipe element-type pipe-declarator;

Parameters

element-type
Defines the size of a single element in the transfer buffer. The element-type can be a base type, predefined_type, struct, 32b enum, or type identifier. Several restrictions apply to element_types, as described in Remarks, below.
pipe-declarator
Specifies one or more identifiers or pointers to identifiers. Separate multiple declarators with commas.

Remarks

You can use the pipe type constructor to transmit data in both directions. An [in] pipe parameter allows the server to pull the data stream from the client during a remote procedure call. An [out] pipe parameter allows the server to push the data stream back to the client. You supply the client-side routines to push and pull the data stream and to allocate a global buffer for the data. The client and server stub routines marshal and unmarshal data and pass a reference to the buffer back to the application.

The following restrictions apply to pipes:

  • A pipe element cannot be or contain a pointer, a conformant or varying array, a handle, or a context handle. Also, in the Microsoft implementation of pipes, a pipe element cannot be or contain a union, a 16b enum, or an __int3264.
  • You cannot apply the [transmit_as], [represent_as], [wire_marshal], or [user_marshal] attributes to a pipe type or to the element-type.
  • A pipe type cannot be a member of a structure or union, the target of a pointer, or the base type of an array.
  • A data type declared to be a pipe type can only be used as a parameter of a remote call.
  • You can pass a pipe parameter in either direction by value or by reference ([ref] pointer). However you cannot apply the [ptr] attribute to a pipe that is passed by reference. You cannot specify a pipe parameter with a [unique] or a full pointer, regardless of direction.
  • You cannot use pipes in [object] interfaces.
  • You cannot apply the [idempotent] attribute to a routine that has a pipe parameter.
  • You cannot use the serialization attributes, [encode] and [decode] with pipes.
  • You cannot use automatic handles, either by default, or with the [auto_handle] attribute, with pipes.

Note The MIDL compiler supports pipes in /Oif mode only.

For more information on implementing routines with pipe parameters, see Pipes in the RPC Programmer's Guide and Reference.

Examples

typedef pipe unsigned char UCHAR_PIPE1, UCHAR_PIPE2;

//SIMPLE_STRUCT defined elsewhere
typedef pipe SIMPLE_STRUCT SIMPLE_STRUCT_PIPE;

See Also

[auto_handle], MIDL Base Types, [decode], [encode], enum, [idempotent], [in], [object], [out], [ptr], [ref], [represent_as], struct, [transmit_as], [unique], [user_marshal], [wire_marshal]


pointer_default

The [pointer_default] attribute specifies the default pointer attribute for all pointers except top-level pointers that appear in parameter lists.

pointer_default ( ptr | ref | unique )

Example

[
    uuid(6B29FC40-CA47-1067-B31D-00DD010662DA),
    version(3.3),
    pointer_default(unique)
]
interface dictionary
{
    // Interface definition statements.
}

See Also

interface, Array and Sized-Pointer Attributes, arrays, Arrays and Pointers, [ptr], [ref], [unique], Default Pointer Types


pragma

The #pragma midl_echo directive instructs MIDL to emit the specified string, without the quotation characters, into the generated header file.

#pragma midl_echo("string")
#pragma token-sequence
#pragma pack (n)
#pragma pack ( [push] [, id] [, n} )
#pragma pack ( [pop] [, id] [, n} )

Parameters

string
Specifies a string that is inserted into the generated header file. The quotation marks are removed during the insertion process.
token-sequence
Specifies a sequence of tokens that are inserted into the generated header file as part of a #pragma directive without processing by the MIDL compiler.
n
Specifies the current pack size. Valid values are 1, 2, 4, 8, and 16.
id
Specifies the user identifier.

Remarks

C-language preprocessing directives that appear in the IDL file are processed by the C compiler's preprocessor. The #define directives in the IDL file are available during MIDL compilation, although not to the C compiler.

For example, when the preprocessor encounters the directive "#define WINDOWS 4", the preprocessor replaces all occurrences of "WINDOWS" in the IDL file with "4". The symbol "WINDOWS" is not available at C-compile time.

To allow the C-preprocessor macro definitions to pass through the MIDL compiler to the C compiler, use the #pragma midl_echo or cpp_quote directive. These directives instruct the MIDL compiler to generate a header file that contains the parameter string with the quotation marks removed. The #pragma midl_echo and cpp_quote directives are equivalent.

The #pragma pack directive is used by the MIDL compiler to control the packing of structures. It overrides the /Zp command-line switch. The pack (n) option sets the current pack size to a specific value: 1, 2, 4, 8, or 16. The pack (push) and pack (pop) options have the following characteristics:

  • The compiler maintains a packing stack. The elements of the packing stack include a pack size and an optional id. The stack is limited only by available memory with the current pack size at the top of the stack.
  • Pack (push) results in the current pack size pushed onto the packing stack. The stack is limited by available memory.
  • Pack (push, n) is the same as pack (push) followed by pack (n).
  • Pack (push, id) also pushes id onto the packing stack along with the pack size.
  • Pack (push, id, n) is the same as pack (push, id) followed by pack (n).
  • Pack (pop) results in popping the packing stack. Unbalanced pops cause warnings and set the current pack size to the command-line value.
  • If pack (pop, id, n) is specified, then n is ignored.

The MIDL compiler places the strings specified in the cpp_quote and pragma directives in the header file in the sequence in which they are specified in the IDL file and relative to other interface components in the IDL file. The strings should usually appear in the interface-body section of the IDL file after all import operations.

The MIDL compiler does not attempt to process #pragma directives that do not start with the prefix "midl_." Other #pragma directives in the IDL file are passed into the generated header file without changes.

Examples

/* IDL file */
#pragma midl_echo("#define UNICODE")
cpp_quote("#define __DELAYED_PREPROCESSING__ 1")
#pragma hdrstop
#pragma check_pointer(on)

/* generated header file */
#define UNICODE
#define __DELAYED_PREPROCESSING__ 1
#pragma hdrstop
#pragma check_pointer(on)

See Also

cpp_quote, Interface Definition (IDL) File, import, /Zp


propget

The [propget] attribute specifies a property accessor function. The property must have the same name as the function.

[propget [,optional-property-attributes]] return-type function-name( parameters);

Parameters

optional-property-attributes
Zero or more property attributes.
return-type
The type of the data returned by the remote procedure.
function-name
The name of the remote procedure.
parameters
Zero or more parameters to the remote procedure.

Remarks

A function that has the propget attribute should also have, as its last parameter, a pointer type with the [out] and [retval] attributes. If the last parameter does not have the [out, retval] attributes, the return value of the function is treated as an [out, retval] parameter. For example, a function with the prototype

[propget] short MyFunction([in] long aLongValue);

is treated as

[propget] HRESULT MyFunction([in] long aLongValue, [out,retval] short *outValue);

At most, one of [propget], [propput], and [propputref] can be specified for a function.

If the [lcid] attribute is used in the parameter list of a function that contains a parameter with the [propput] attribute, the [lcid] parameter must be second to the last.

Flags

INVOKE_PROPERTYGET

Example

interface InMyFace : IDispatch
{
    [propget,
     helpstring("A meaningful comment.")] HRESULT Method1(
         [out, retval] int* ReturnVal);

    [propput,
     helpstring("Another meaningful comment.")] HRESULT Method1(
         [in] int Value);

    [propget,
     helpstring("A meaningful comment."), id(1)] HRESULT Method2(
         [out, retval] InYourFace** ReturnVal);

    [propputref,
     helpstring("Another meaningful comment."),
     id(1)] HRESULT Method2([in] InYourFace* Point);
}

See Also

Differences Between MIDL and MKTYPLIB, Generating a Type Library With MIDL, ODL File Example, ODL File Syntax, [out], [retval], [propput], [propputref], TYPEFLAGS


propput

The [propput] attribute specifies a property-setting function. The property must have the same name as the function.

[propput [,optional-property-attributes]] return-type function-name( parameters);

Parameters

optional-property-attributes
Zero or more property attributes.
return-type
The type of the data returned by the remote procedure.
function-name
The name of the remote procedure.
parameters
Zero or more parameters to the remote procedure.

Remarks

A function that has the [propput] attribute must also have, as its last parameter, a parameter that has the [in] attribute.

At most, one of [propget], [propput] and [propputref] can be specified for a function.

If the [lcid] attribute is used in the parameter list of a function that contains a parameter with the [propget] attribute, the [lcid] parameter must be second to the last.

Flags

INVOKE_PROPERTYPUT

Example

interface InMyFace : IDispatch
{
    [propget,
     helpstring("A meaningful comment.")] HRESULT Method1(
         [out, retval] int* ReturnVal);

    [propput,
     helpstring("Another meaningful comment.")] HRESULT Method1(
         [in] int Value);
}

See Also

Differences Between MIDL and MKTYPLIB, Generating a Type Library With MIDL, ODL File Example, ODL File Syntax, [propget], [propputref], TYPEFLAGS


propputref

The [propputref] attribute specifies a property-setting function that uses a reference instead of a value.

[propputref [,optional-property-attributes]] return-type function-name( parameters);

Parameters

optional-property-attributes
Zero or more property attributes.
return-type
The type of the data returned by the remote procedure.
function-name
The name of the remote procedure.
parameters
Zero or more parameters to the remote procedure.

Remarks

A function that has the [propputref] attribute must also have, as its last parameter, a pointer that has the [in] attribute.

The property must have the same name as the function. At most, one of [propget], [propput] and [propputref] attributes can be specified for a function.

Flags

INVOKE_PROPERTYPUTREF

Example

interface InMyFace : IDispatch
{
    [propget,
     helpstring("A meaningful comment."),
     id(1)] HRESULT Method2([out, retval] InYourFace** ReturnVal);
    [propputref,
     helpstring("Another meaningful comment."),
     id(1)] HRESULT Method2([in] InYourFace* Point);
}

See Also

Differences Between MIDL and MKTYPLIB, Generating a Type Library With MIDL, [in], ODL File Example, ODL File Syntax, [propget], [propput], TYPEFLAGS


ptr

The [ptr] attribute designates a pointer as a full pointer.

pointer_default(ptr)

typedef [ ptr [ , type-attribute-list ] ] type-specifier declarator-list;

typedef [ struct | union ]
{
    [ ptr [ , field-attribute-list ] ] type-specifier declarator-list;
    ...
}

[ ptr [ , function-attribute-list ] ] type-specifier ptr-decl function-name(
    [ [ parameter-attribute-list ] ] type-specifier [standard-declarator]
    , ...);

[[ [ function-attribute-list ] ]] type-specifier [[ptr-decl]] function-name(
    [ ptr [[ , parameter-attribute-list ]] ] type-specifier [[standard-declarator]]
    , ...);

Parameters

type-attribute-list
Specifies one or more attributes that apply to the type. Valid type attributes include [handle], [switch_type], [transmit_as]; the pointer attribute [ref], [unique, or [ptr]; and the usage attributes [context_handle], [string], and [ignore]. Separate multiple attributes with commas.
type-specifier
Specifies a base type, struct, union, or enum type or type identifier. An optional storage specification can precede type-specifier.
standard-declarator
Specifies a standard C declarator, such as an identifier, a pointer declarator, or an array declarator. For more information, see Array and Sized-Pointer Attributes, arrays, and Arrays and Pointers.
declarator-list
Specifies standard C declarators, such as identifiers, pointer declarators, and array declarators. For more information, see Array and Sized-Pointer Attributes, arrays., and Arrays and Pointers. The declarator-list consists of one or more declarators separated by commas. The parameter-name identifier in the function declarator is optional.
field-attribute-list
Specifies zero or more field attributes that apply to the structure or union member or function parameter. Valid field attributes include [first_is], [last_is], [length_is], [max_is], [size_is]; the usage attributes [string], [ignore], and [context_handle]; the pointer attribute [ref], [unique], or [ptr]; and the union attribute [switch_type]. Separate multiple field attributes with commas.
function-attribute-list
Specifies zero or more attributes that apply to the function. Valid function attributes are [callback], [local]; the pointer attribute [ref], [unique], or [ptr]; and the usage attributes [string], [ignore, and [context_handle.
ptr-decl
Specifies at least one pointer declarator to which the [ptr] attribute applies. A pointer declarator is the same as the pointer declarator used in C; it is constructed from the * designator, modifiers such as far, and the qualifier const.
function-name
Specifies the name of the remote procedure.
parameter-attribute-list
Consists of zero or more attributes appropriate for the specified parameter type. Parameter attributes can take the directional attributes in and out; the field attributes first_is, last_is, length_is, max_is, size_is, and switch_type; the pointer attribute ref, unique, or [ptr]; and the usage attributes context_handle and string. The usage attribute ignore cannot be used as a parameter attribute. Separate multiple attributes with commas.

Remarks

The full pointer designated by the [ptr] attribute approaches the full functionality of the C-language pointer. The full pointer can have the value NULL and can change during the call from NULL to non-NULL. Storage pointed to by full pointers can be reached by other names in the application supporting aliasing and cycles. This functionality requires more overhead during a remote procedure call to identify the data referred to by the pointer, determine whether the value is NULL, and to discover if two pointers point to the same data.

Use full pointers for:

  • Remote return values.
  • Double pointers, when the size of an output parameter is not known.
  • Null pointers.

Full (and unique) pointers cannot be used to describe the size of an array or union because these pointers can have the value NULL. This restriction by MIDL prevents an error that can result when a NULL value is used as the size.

Reference and unique pointers are assumed to cause no aliasing of data. A directed graph obtained by starting from a unique or reference pointer and following only unique or reference pointers contains neither reconvergence nor cycles.

To avoid aliasing, all pointer values should be obtained from an input pointer of the same class of pointer. If more than one pointer points to the same memory location, all such pointers must be full pointers.

In some cases, full and unique pointers can be mixed. A full pointer can be assigned the value of a unique pointer, as long as the assignment does not violate the restrictions on changing the value of a unique pointer. However, when you assign a unique pointer the value of a full pointer, you may cause aliasing.

Mixing full and unique pointers can cause aliasing, as demonstrated in the following example:

typedef struct
{
    [ptr] short * pdata;          // full pointer
} GRAPH_NODE_TYPE;

typedef struct
{
    [unique] graph_node * left;   // unique pointer
    [unique] graph_node * right;  // unique pointer
} TREE_NODE_TYPE;

// application code:
short a = 5;
TREE_NODE_TYPE * t;
GRAPH_NODE_TYPE g, h;

g.pdata = h.pdata = &a;
t->left = &g;
t->right = &h;
// t->left->pdata == t->right->pdata == &a

Although "t->left" and "t->right" point to unique memory locations, "t->left->pdata" and "t->right->pdata" are aliased. For this reason, aliasing-support algorithms must follow all pointers (including unique and reference pointers) that may eventually reach a full pointer.

Examples

pointer_default(ptr)

typedef [ptr, string] unsigned char * MY_STRING_TYPE;

[ptr] char * MyFunction([in, out, unique] long * plNumber);

See Also

arrays, Arrays and Pointers, Array and Sized-Pointer Attributes, MIDL Base Types, [callback], const, [context_handle], enum, [first_is], [handle], Interface Definition (IDL) File, [ignore], [last_is], [length_is], [local], [max_is], [pointer_default], [ptr], [ref], [size_is], [string], struct, [switch_type], [transmit_as], [union], [unique]


public

The [public] attribute includes an alias declared with the typedef keyword in the type library.

typedef [public] data-type identifier;

Parameters

data-type
The data type that the identifier will be an alias for.
identifier
Another name by which data-type will be known in the software.

Remarks

By default, an alias that is declared with typedef and has no other attributes is treated as a #define and is not included in the type library. Using the [public] attribute ensures that the alias becomes part of the type library.

Note The MIDL compiler requires that you explicitly apply the [public] attribute to each typedef that you want public. This is in contrast to MKTYPLIB, which treats as public, every typedef inside of a public interface block.

Example

typedef [public] long MEMBERID;

See Also

Differences Between MIDL and MKTYPLIB, Generating a Type Library With MIDL, ODL File Example, interface, ODL File Syntax, typedef


range

The [range] attribute lets you specify a range of allowable values for arguments or fields whose values are set at run time. When used with a pipe type, the attribute specifies the allowable range for the count of elements in the pipe chunks.

[range(low-val,high-val)] type-specifier declarator

Parameters

low-val
The lowest allowable value that the parameter or field can hold.
high-val
The highest allowable value that the parameter or field can hold.
type-specifier
An integral type other than hyper or _int64, a type identifier to an integral type, an enum type, or a pipe type name.
declarator
A standard C declarator, such as an identifier.

Remarks

Use the [range] attribute to modify the meaning of sensitive parameters or fields, such as those used for size or length, with conformant or varying arrays; or whenever you want to check a parameter or field value against a range of valid values. The attribute is applicable to top-level parameters as well as lower-level parameters and fields.

Note that you must use the /robust compiler option when you compile your IDL file in order to generate the stub code that will perform these checks. Without the /robust switch, the MIDL compiler ignores this attribute.

Examples

HRESULT Method1(
    [in, range(0,100)] ULONG m,
    [in, range(0,100)] ULONG n,
    [size_is(m,n)] ULONG **pplong);

void InPipe(
    [in, range(0, MAX_CHUNK) LONG_PIPE pipe_date);

See Also

Interface Definition (IDL) File, arrays, [first_is], [last_is], [length_is], [max_is], /robust, [size_is], [switch_is]


readonly

The [readonly] attribute prohibits assignment to a variable.

[readonly [, optional-attributes]] data-type identifier

Parameters

optional-attributes
Zero or more MIDL attributes.
data-type
The type of the data contained by identifier.
identifier
A name by which the software can refer to the data storage location.

Remarks

The [readonly] attribute prohibits assignment to a variable.

Flags

VARFLAG_FREADONLY

Example

HRESULT Method3([in, readonly] int iMmutable);

See Also

TYPEFLAGS, ODL File Syntax, ODL File Example, Generating a Type Library With MIDL, Differences Between MIDL and MKTYPLIB


ref

The [ref] attribute identifies a reference pointer. It is used simply to represent a level of indirection.

pointer_default(ref)

typedef [ ref [[ , type-attribute-list ]] ] type-specifier declarator-list;

typedef [ struct | union ]
{
    [ ref [[ , field-attribute-list ]] ] type-specifier declarator-list;
    ...}

[[ [ function-attribute-list ] ]] type-specifier [[ptr-decl]] function-name(
    [ ref [[ , parameter-attribute-list ]] ] type-specifier [[standard-declarator]]
    , ...);

Parameters

type-attribute-list
Specifies one or more attributes that apply to the type. Valid type attributes include [handle], [switch_type], [transmit_as]; the pointer attributes [ref], [unique], or [ptr]; and the usage attributes [context_handle], [string], and [ignore]. Separate multiple attributes with commas.
type-specifier
Specifies a base type, struct, union, or enum type or type identifier. An optional storage specification can precede type-specifier.
standard-declarator
Specifies a standard C declarator, such as an identifier, a pointer declarator, or an array declarator. For more information, see Array and Sized-Pointer Attributes, arrays., and Arrays and Pointers.
declarator-list
Specifies standard C declarators, such as identifiers, pointer declarators, and array declarators. For more information, see Array and Sized-Pointer Attributes, arrays., and Arrays and Pointers. The declarator-list consists of one or more declarators separated by commas. The parameter-name identifier in the function declarator is optional.
field-attribute-list
Specifies zero or more field attributes that apply to the structure, union member, or function parameter. Valid field attributes include [first_is], [last_is], [length_is], [max_is], [size_is]; the usage attributes [string], [ignore], and [context_handle]; the pointer attribute [ref], [unique], or [ptr]; and the union attribute [switch_type]. Separate multiple field attributes with commas.
function-attribute-list
Specifies zero or more attributes that apply to the function. Valid function attributes are [callback], [local]; the pointer attribute [ref], [unique], or [ptr]; and the usage attributes [string], [ignore], and [context_handle].
ptr-decl
Specifies at least one pointer declarator to which the [ref] attribute applies. A pointer declarator is the same as the pointer declarator used in C; it is constructed from the * designator, modifiers such as far, and the qualifier const.
function-name
Specifies the name of the remote procedure.
parameter-attribute-list
Consists of zero or more attributes appropriate for the specified parameter type. Parameter attributes can take the directional attributes [in] and [out]; the field attributes [first_is], [last_is], [length_is], [max_is, [size_is], and [switch_type]; the pointer attribute [ref], [unique], or [ptr]; and the usage attributes [context_handle] and [string]. The usage attribute [ignore] cannot be used as a parameter attribute. Separate multiple attributes with commas.

Remarks

A pointer attribute can be applied as a type attribute, as a field attribute that applies to a structure member, union member, or parameter; or as a function attribute that applies to the function return type. The pointer attribute can also appear with the [pointer_default] keyword.

A reference pointer has the following characteristics:

  • Always points to valid storage; never has the value NULL. A reference pointer can always be dereferenced.
  • Never changes during a call. A reference pointer always points to the same storage on the client before and after the call.
  • Does not allocate new memory on the client. Data returned from the server is written into existing storage specified by the value of the reference pointer before the call.
  • Does not cause aliasing. Storage pointed to by a reference pointer cannot be reached from any other name in the function.

A reference pointer cannot be used as the type of a pointer returned by a function.

If no attribute is specified for a top-level pointer parameter, it is treated as a reference pointer.

Example

[unique] char * GetFirstName(
    [in, ref] char * pszFullName);

See Also

arrays, Arrays and Pointers, Array and Sized-Pointer Attributes, MIDL Base Types, [callback], const, [context_handle], enum, [first_is], [handle], [ignore], [last_is], [length_is], [local], [max_is], [size_is], [ptr], [ref], [string], struct, [switch_type, transmit_as, union, [unique]


represent_as

The [represent_as] attribute associates a named local type in the target language repr-type with a transfer type named-type that is transferred between client and server.

typedef [represent_as(repr-type) [[ , type-attribute-list ]] ] named-type;
void __RPC_USER named-type_from_local (
    repr-type __RPC_FAR * ,
    named-type __RPC_FAR * __RPC_FAR * );
void __RPC_USER named-type_to_local (
    named-type __RPC_FAR * ,
    repr-type __RPC_FAR * );
void __RPC_USER named-type_free_inst (
    named-type __RPC_FAR * );
void __RPC_USER named-type_free_local (
    repr-type__RPC_FAR * );

Parameters

named-type
Specifies the named transfer data type that is transferred between client and server.
type-attribute-list
Specifies one or more attributes that apply to the type. Separate multiple attributes with commas.
repr-type
Specifies the represented local type in the target language that is presented to the client and server applications.

Remarks

When using [represent_as], you must supply routines that convert between the local and the transfer types and that free memory used to hold the converted data. The [represent_as] attribute instructs the stubs to call the user-supplied conversion routines.

The transferred type named-type must resolve to a MIDL base type, predefined type, or to a type identifier. For more information, see MIDL Base Types.

You must supply the following routines:

Routine name | Description
named_type_from_local | Converts data from the local type to the network type. The routine allocates memory for the network data type, including memory for any data referenced by pointers in the network data type.
named_type_to_local | Converts data from the network type to the local type. The routine is responsible for allocating memory for data referenced by pointers in the local type. RPC allocates memory for the local type itself.
named_type_free_local | Frees memory allocated for data referenced by pointers in the local type. RPC frees memory for the type itself
named_type_free_inst | Frees memory allocated for the data referenced by pointers in the network type and for the network type itself.

The client stub calls named-type_from_local to allocate space for the transmitted type and to translate the data from the local type to the network type. The server stub allocates space for the original data type and calls named-type_to_local to translate the data from the network type to the local type.

Upon return from the application code, the client and server stubs call named-type_free_inst to deallocate the storage for network type. The client stub calls named-type_free_local to deallocate storage returned by the routine.

The following types cannot have a [represent_as] attribute:

  • Conformant, varying, or conformant-varying arrays
  • Structures in which the last member is a conformant array (a conformant structure)
  • Pointers or types that contain a pointer
  • Pipes or types that contain pipes
  • Types that are used as the base type for a pipe
  • Predefined types handle_t, void
  • Types that have the [handle] attribute

Examples

//these data types defined in .IDL or elsewhere
typedef struct  _lbox
{
    long         data;
    struct _lbox *next;
} lbox;
typedef [ref] lbox *PBOX_LOC;
typedef long LONG4[4];

//in .ACF file :
interface iface
{
    typedef  [ represent_as(PBOX_LOC) ]  LONG4;
}

See Also

Application Configuration File (ACF), arrays, MIDL Base Types, handle_t, typedef, void


requestedit

The [requestedit] attribute indicates that the property supports the OnRequestEdit notification.

[requestedit [,optional-attributes]] return-type function-name(params)

Parameters

optional-attributes
Zero or more MIDL attributes.
return-type
Specifies the return type of the function.
function-name
Specifies the name of the function in the IDL file.
params
Zero or more function parameters.

Remarks

Supporting OnRequestEdit notification means that, before a change is made, the object will send the client a request for permission to change a property. An object can support data binding but not have this attribute.

Flags

FUNCFLAG_FREQUESTEDIT, VARFLAG_FREQUESTEDIT

Example

properties:
    [propget, helpstring("A useful comment"), bindable, defaultbind,
     displaybind, requestedit] long Func1(void);

See Also

TYPEFLAGS, ODL File Syntax, ODL File Example, Generating a Type Library With MIDL, Differences Between MIDL and MKTYPLIB


restricted

The [restricted] attribute specifies that a library, or member of a module, interface, or dispinterface cannot be called arbitrarily.

[
    restricted
    [, other-attributes]
]
statement-type statement-name
{
    definitions
};

Parameters

other-attributes
Zero or more MIDL attributes.
statement-type
One of the following: library, module, interface, dispinterface.
statement-name
The identifier by which the software refers to this statement.
definitions
MIDL language elements that define the contents of this statement.

Remarks

This attribute enables you to control access to elements of interfaces, libraries, modules, and dispinterfaces. For example, it can prevent a data item from being used by a macro programmer. You can apply this attribute to a member of a coclass, independent of whether the member is a dispinterface or interface, and independent of whether the member is a sink (incoming) or source (outgoing). A member of a coclass cannot have both the [restricted] and [default] attributes.

Flags

IMPLTYPEFLAG_FRESTRICTED, FUNCFLAG_FRESTRICTED

Examples

[
    uuid(12345678-1234-1234-1234-123456789ABC),
    version (1.0),
    restricted
]
library MyLibrary
{
    // Library definition statements.
};

[propget, restricted] HRESULT MyProc(void);

See Also

TYPEFLAGS, library, interface, dispinterface, module, ODL File Syntax, ODL File Example, Generating a Type Library With MIDL, Differences Between MIDL and MKTYPLIB


retval

The [retval] attribute designates the parameter that receives the return value of the member.

return-type function-name(
    [out, retval [, optional-attributes]] data-type * param-name,
    ...);

Parameters

return-type
The data type of the return value of the remote procedure.
function-name
The name used to invoke the remote procedure.
optional-attributes
Zero or more MIDL attributes.
data-type
The type of the data passed through the parameter.
param-name
The identifier name of the parameter.

Remarks

You can use the [retval] attribute on parameters of interface members that describe methods or get properties. (The attribute is required on the last parameter of a method that has the [propget] attribute.) The parameter must have the [out] attribute and must be a pointer type.

You cannot apply the [optional] attribute to a [retval] parameter.

The MIDL compiler accepts the following parameter ordering (from left-to-right):

  1. Required parameters (parameters that do not have the [defaultvalue] or [optional] attributes).
  2. Optional parameters with or without the [defaultvalue] attribute.
  3. Parameters with the [optional] attribute and without the [defaultvalue] attribute.
  4. [lcid] parameter, if any.
  5. [retval] parameter.

Parameters with the [retval] attribute are not displayed in user-oriented browsers.

Flags

IDLFLAG_FRETVAL

Examples

HRESULT MyMethod([out, retval] InMyFace** ReturnVal);
HRESULT MyOtherMethod([out, retval] VARIANT_BOOL* ReturnVal);

See Also

[defaultvalue], Differences Between MIDL and MKTYPLIB, Generating a Type Library With MIDL, [lcid], ODL File Example, ODL File Syntax, [optional], [out], [propget], TYPEFLAGS


shape

The DCE IDL keyword shape is not supported in Microsoft RPC.

See Also

Interface Definition (IDL) File


short

The short keyword designates a 16-bit integer.

[[ signed | unsigned ]] short [[ int ]] declarator-list;

Parameters

declarator-list
Specifies one or more standard C declarators, such as identifiers, pointer declarators, and array declarators. (Function declarators and bit-field declarations are not allowed in structures that are transmitted in remote procedure calls. These declarators are allowed in structures that are not transmitted.) Separate multiple declarators with commas.

Remarks

The short keyword can be preceded by either the keyword signed or the keyword unsigned. The int keyword is optional and can be omitted. To the MIDL compiler, a short integer is signed by default and is synonymous with signed short int.

The short integer type is one of the base types of the IDL language. The short integer type can appear as a type specifier in const declarations, typedef declarations, general declarations, and function declarators (as a function-return-type specifier and a parameter-type specifier). For the context in which type specifiers appear, see Interface Definition (IDL) File.

See Also

MIDL Base Types, Interface Definition (IDL) File, int, long, signed, small, unsigned


signed

The signed keyword indicates that the most significant bit of an integer variable represents a sign bit rather than a data bit.

[[ signed ]] type-qualifier [[ int ]]identifier-name;

Parameters

type-qualifier
Can be any of char, wchar_t, long, short, and small.
identifier-name
Specifies a valid MIDL identifier. Valid MIDL identifiers consist of up to 31 alphanumeric and/or underscore characters and must start with an alphabetic or underscore character.

Remarks

This keyword is optional and can be used with any of the character and integer types char, wchar_t, long, short, and small. You can optionally include the keyword int after the type qualifiers long, short, and small.

When you use the MIDL compiler switch char, character and integer types that appear in the IDL file without explicit sign keywords can appear with the signed or unsigned keywords in the generated header file. To avoid confusion, specify the sign of the integer and character types.

See Also

MIDL Base Types, /char, Interface Definition (IDL) File, int, long, short, signed, small, unsigned, wchar_t


size_is

Use the [size_is] attribute to specify the size of memory allocated for sized pointers, sized pointers to sized pointers, and single- or multidimensional arrays.

[ size_is(limited-expression-list) ]

Parameters

limited-expression-list
Specifies one or more C-language expressions. Each expression evaluates to a non-negative integer that represents the amount of memory allocated to a sized pointer or an array. In the case of an array, specifies a single expression that represents the allocation size, in elements, of the first dimension of that array. The MIDL compiler supports conditional expressions, logical expressions, relational expressions, and arithmetic expressions. MIDL does not allow function invocations in expressions and does not allow increment and decrement operators. Use commas as placeholders for implicit parameters, or to separate multiple expressions.

Remarks

If you are using the [size_is] attribute to allocate memory for a multidimensional array and you are using array [ ] notation, keep in mind that only the first dimension of a multidimensional array can be dynamically determined at run time. The other dimensions must be statically specified. For more information on using the [size_is] attribute with multiple levels of pointers to enable a server to return a dynamically-sized array of data to a client, as shown in the example Proc7, see Multiple Levels of Pointers.

You can use either [size_is] or [max_is] (but not both in the same attribute list) to specify the size of an array whose upper bounds are determined at run time. Note, however, that the [size_is] attribute cannot be used on array dimensions that are fixed. The [max_is] attribute specifies the maximum valid array index. As a result, specifying [size_is(n)] is equivalent to specifying [max_is(n-1)].

An [in] or [in, out ] conformant-array parameter with the [string] attribute need not have the [size_is] or [max_is] attribute. In this case, the size of the allocation is determined from the NULL terminator of the input string. All other conformant arrays with the [string] attribute must have a [size_is] or [max_is] attribute.

While it is legal to use the [size_is] attribute with a constant, doing so is inefficient and unnecessary. For example, use a fixed size array:

HRESULT Proc3([in] short Arr[MAX_SIZE]);

instead of:

// legal but marshaling code is much slower
HRESULT Proc3([in size_is(MAX_SIZE)] short Arr[] );

You can use the [size_is] and [length_is] attributes together. When you do, the [size_is] attribute controls the amount of memory allocated for the data. The [length_is] attribute specifies how many elements are transmitted. The amount of memory specified by the [size_is] and [length_is] attributes need not be the same. For instance, your client may pass an [in,out] parameter to a server and specify a large memory allocation with [size_is], even though it specifies a small number of data elements to be passed with [length_is]. This enables the server to fill the array with more data than it received, which it can then send back to the client.

In general, it isn't useful to specify both [size_is] and [length_is] on [in] or [out] parameters. In both cases, [size_is] controls memory allocation. Your application could use [size_is] to allocate more array elements than it transmits (as specified by [length_is]). However, this would be inefficient. It would also be inefficient to specify identical values for [size_is] and [length_is]. It would create extra overhead during parameter marshaling. If the values of [size_is] and [length_is] are always the same, omit the [length_is] attribute.

Examples

HRESULT Proc1(
    [in] short m;
    [in, size_is(m)] short a[]);  // If m = 10, a[10]
HRESULT Proc2(
    [in] short m;
    [in, size_is(m)] short b[][20]);  // If m = 10, b[10][20]
HRESULT Proc3(
    [in] short m;
    [size_is(m)] short * pshort); /* Specifies a pointer
                                  to an m-sized block of shorts */
HRESULT Proc4(
    [in] short m;
    [size_is( , m)] short ** ppshort); /* Specifies a pointer
                                       to a pointer to an m-sized
                                       block of shorts */
HRESULT Proc5(
    [in] short m;
    [size_is(m ,)] short ** ppshort); /* Specifies an
                                      m-sized block of pointers
                                      to shorts */
HRESULT Proc6(
    [in] short m;
    [in] short n;
    [size_is(m,n)] short ** ppshort); /* Specifies a pointer to an
                                      m-sized block of pointers, each
                                      of which points to an n-sized
                                      block of shorts.*/
 HRESULT Proc7(
     [out] long  * pSize,
     [out, size_is( , *pSize)] my_type ** ppMyType); /* Specifies a pointer
                                              to a sized pointer,
                                              which points to a block
                                              of my_types, whose size is
                                              unknown when the stub
                                              calls the server. */

See Also

arrays, field_attributes, [first_is], Interface Definition (IDL) File, [in], [last_is], [length_is], [max_is], [min_is], [out], [string]


small

The small keyword designates an 8-bit integer number.

short identifier-name;

Parameters

identifier-name
Specifies a valid MIDL identifier. Valid MIDL identifiers consist of up to 31 alphanumeric and/or underscore characters and must start with an alphabetic or underscore character.

Remarks

The small keyword can be preceded by either the keyword signed or the keyword unsigned. The int keyword is optional and can be omitted. To the MIDL compiler, a small integer is signed by default and is synonymous with signed small int.

The small integer type is one of the base types of the IDL language. The small integer type can appear as a type specifier in const declarations, typedef declarations, general declarations, and function declarators (as a function return–type specifier and as a parameter-type specifier). For the context in which type specifiers appear, see Interface Definition (IDL) File.

The sign of the small type can be modified by the MIDL compiler switch /char. To avoid confusion, specify the sign of the integer type with the keywords signed and unsigned.

See Also

/char, const, Interface Definition (IDL) File, int, long, short, signed, unsigned, typedef


source

The [source] attribute indicates that a member of a coclass, property, or method is a source of events. For a member of a coclass, this attribute means that the member is called rather than implemented.

[
    coclass-attributes
]
coclass coclass-name
{
    [source [, optional-attributes] ] statement-type statement-name;
    [, ...]
}

[source] object-type function-name(optional-parameter-list);

Parameters

coclass-attributes
Zero or more attributes that will be applied to the coclass.
coclass-name
The name identifier of the coclass.
optional-attributes
Zero or more MIDL attributes.
statement-type
Can be interface or dispinterface.
statement-name
The name of the interface or dispinterface.
object-type
The type of the object that the method returns. This object is a source of events.
function-name
The name of a method in an interface or dispinterface.
optional-parameter-list
Zero or more method parameters.

Remarks

On a property or method, the [source] attribute indicates that the member returns an object or VARIANT that is a source of events. The object implements IConnectionPointContainer.

Flags

IMPLTYPEFLAG_FSOURCE, VARFLAG_SOURCE, FUNCFLAG_SOURCE

Examples

[default, source] dispinterface DIMyFaceAdviseSink;
[source]interface IMyFaceAdviseSink;

See Also

coclass, Differences Between MIDL and MKTYPLIB, dispinterface, Generating a Type Library With MIDL, interface, ODL File Example, ODL File Syntax, TYPEFLAGS


strict_context_handle

Use the [strict_context_handle] in an ACF file to set restrictions on context handles.

[
    strict_context_handle
    [, interface-attribute-list]
]
interface interface-name
{
    interface-definition-statements
}

Parameters

interface-attribute-list
Other ACF attributes that apply to the interface as a whole. Valid attributes include auto_handle, implicit_handle, explicit_handle, and optimize, code, or nocode. Separate multiple attributes with commas.
interface-name
The name of the interface.
interface-definition-statements
One or more MIDL statements that define the elements of the interface.

Remarks

Normally, when a call to an interface method generates a context handle, that handle becomes freely available to any other interface. When you use the [strict_context_handle] attribute you guarantee that the methods in that interface will only accept context handles that were created by a method from the same interface.

Examples

[
    auto_handle,
    strict_context_handle,
    optimize
]
interface MySafeFastInterface
{
    // Interface definition statements.
}

See Also

Application Configuration File (ACF), Application Configuration File (ACF), [code], Context Handles, [context_handle_serialize], [context_handle_noserialize], [explicit_handle], [implicit_handle], [nocode], [optimize]


string

The [string] attribute indicates that the one-dimensional char, wchar_t, byte (or equivalent) array or the pointer to such an array must be treated as a string. The string can also be an array (or a pointer to an array) of constructs whose fields are all of the type byte.

typedef [ string [[ , type-attribute-list ]] ] type-specifier declarator-list;

typedef [ struct | union ]
{
    [ string [[ , field-attribute-list ]] ] type-specifier declarator-list;
    ...
};

[ string [[ , function-attribute-list ]] ] type-specifier ptr-decl function-name(
    [[ [ parameter-attribute-list ] ]] type-specifier [[standard-declarator]]
    , ...);

[[ [ function-attribute-list ] ]] type-specifier [[ptr-decl]] function-name(
    [ string [[ , parameter-attribute-list ]] ] type-specifier [[standard-declarator]]
    , ...);

Parameters

type-attribute-list
Specifies one or more attributes that apply to a type. Valid type attributes include [handle], [switch_type], [transmit_as]; the pointer attribute [ref], [unique], or [ptr]; and the usage attributes [context_handle], [string], and [ignore]. Separate multiple attributes with commas.
type-specifier
Specifies a base type, struct, union, or enum type or type identifier. An optional storage specification can precede type-specifier.
standard-declarator
Specifies a standard C declarator, such as an identifier, a pointer declarator, or an array declarator. For more information, see Array and Sized-Pointer Attributes, arrays., and Arrays and Pointers.
declarator-list
Specifies standard C declarators, such as identifiers, pointer declarators, and array declarators. For more information, see Array and Sized-Pointer Attributes, arrays., and Arrays and Pointers. The declarator-list consists of one or more declarators separated by commas. The parameter-name identifier in the function declarator is optional.
field-attribute-list
Specifies zero or more field attributes that apply to the structure, union member, or function parameter. Valid field attributes include [first_is], [last_is], [length_is], [max_is], [size_is]; the usage attributes [string], [ignore], and [context_handle], the pointer attribute [ref], [unique], or [ptr], and the union attribute [switch_type]. Separate multiple field attributes with commas.
function-attribute-list
Specifies zero or more attributes that apply to the function. Valid function attributes are [callback], [local]; the pointer attribute [ref], [unique], or [ptr]; and the usage attributes [string], [ignore], and [context_handle].
ptr-decl
Specifies an optional pointer declarator to which the [string] attribute applies. A pointer declarator is the same as the pointer declarator used in C; it is constructed from the * designator, modifiers such as far, and the qualifier const.
function-name
Specifies the name of the remote procedure.
parameter-attribute-list
Consists of zero or more attributes appropriate for the specified parameter type. Parameter attributes can take the directional attributes [in and [out; the field attributes [first_is, [last_is, [length_is, [max_is, [size_is, and [switch_type]; the pointer attribute [ref], [unique], or [ptr]; and the usage attributes [context_handle] and [string]. The usage attribute [ignore] cannot be used as a parameter attribute. Separate multiple attributes with commas.

Remarks

If the [string] attribute is used with an array whose bounds are determined at run time, you must also specify a [size_is] or [max_is] attribute.

The [string] attribute cannot be used with attributes that specify the range of transmitted elements, such as [first_is], [last_is], and [length_is].

When used on multidimensional arrays, the [string] attribute applies to the rightmost array.

To define a counted string, do not use the [string] attribute. Use a character array or character-based pointer such as the following:

typedef struct
{
    unsigned short size;
    unsigned short length;
    [size_is(size), length_is(length)] char string[*];
} counted_string;

The [string] attribute specifies that the stub should use a language-supplied method to determine the length of strings.

When declaring strings in C, you must allocate space for an extra character that marks the end of the string.

Examples

/* a string type that can hold up to 80 characters */
typedef [string] char line[81];

HRESULT Proc1([in, string] char * pszName);

See Also

arrays, MIDL Base Types, [callback], char, const, [context_handle], enum, [first_is], [handle], Interface Definition (IDL) File, [ignore], [last_is], [length_is], [local], [max_is], [pointer_default], [ptr], [ref], [size_is], [string], [struct], [switch_type], [transmit_as], union, [unique], wchar_t


struct

The struct keyword is used in a structure type specifier.

struct [[ struct-tag ]]
{
    [[ [ field-attribute-list ] ]] type-specifier declarator-list;
    ...
};

Parameters

struct-tag
Specifies an optional tag for the structure.
field-attribute-list
Specifies zero or more field attributes that apply to the structure member. Valid field attributes include [first_is], [last_is], [length_is], [max_is], [size_is]; the usage attributes [string], [ignore], and [context_handle]; the pointer attribute [ref], [unique], or [ptr]; and the union attribute [switch_type]. Separate multiple field attributes with commas.
type-specifier
Specifies a base type, struct, union, or enum type or type identifier. An optional storage specification can precede type-specifier.
declarator-list
Specifies one or more standard C declarators, such as identifiers, pointer declarators, and array declarators. (Function declarators and bit-field declarations are not allowed in structures that are transmitted in remote procedure calls. These declarators are allowed in structures that are not transmitted.) Separate multiple declarators with commas.

Remarks

The IDL structure type specifier, struct, differs from the standard C type specifier in the following ways:

  • Each structure member can be associated with optional field attributes that describe characteristics of that structure member for the purposes of a remote procedure call.
  • Bit fields and function declarators are not allowed in structures that are used in remote procedure calls. These standard C declarator constructs can be used only if the structure is not transmitted on the network.

The shape of structures must be the same across platforms to ensure interconnectivity.

Example

typedef struct _PITCHER_RECORD_TYPE
{
    short flag;
    [switch_is(flag)] union PITCHER_STATISTICS_TYPE p;
} PITCHER_RECORD_TYPE;

See Also

arrays, Arrays and Pointers, Array and Sized-Pointer Attributes, MIDL Base Types, /c_ext, context_handle ], enum, [first_is], Interface Definition (IDL) File, [ignore], [last_is], [length_is], [max_is], /osf, [ptr], [ref], [size_is], [string], struct, [switch_type], [union], [unique]


switch

The switch keyword selects the discriminant for an encapsulated_union.

switch (switch-type switch-name)

Parameters

switch-type
Specifies an int, char, enum type, or an identifier that resolves to one of these types.
switch-name
Specifies the name of the variable of type switch-type that acts as the union discriminant.

Examples

typedef union _S1_TYPE switch (long l1) U1_TYPE
{
    case 1024:
        float f1;
    case 2048:
        double d2;
} S1_TYPE;

/* in generated header file */
typedef struct _S1_TYPE
{
    long l1;
    union
    {
        float f1;
        double d2;
    } U1_TYPE;
} S1_TYPE;

See Also

Interface Definition (IDL) File, Nonencapsulated Unions, [switch_is], [switch_type], [union]


switch_is

The [switch_is] attribute specifies the expression or identifier acting as the union discriminant that selects the union member.

typedef struct [[ struct-tag ]]
{
    [ switch_is(limited-expr) [[ , field-attr-list ]] ] union-type-specifier declarator;
    ...
}

[[ [function-attribute-list] ]] type-specifier [[pointer-declarator]] function-name(
    [ switch_is(limited-expr) [[ , param-attr-list ]] ] union-type [[declarator]]
    , ...);

Parameters

struct-tag
Specifies an optional tag for a structure.
limited-expr
Specifies a C-language expression supported by MIDL. Almost all C-language expressions are supported. The MIDL compiler supports conditional expressions, logical expressions, relational expressions, and arithmetic expressions. MIDL does not allow function invocations in expressions and does not allow pre- and post-increment and pre- and post-decrement operators.
field-attr-list
Specifies zero or more field attributes that apply to a union member. Valid field attributes include [first_is], [last_is], [length_is], [max_is], [size_is]; the usage attributes [string], [ignore], and [context_handle]; the pointer attribute [ref], [unique], or [ptr]; and for members that are themselves unions, the union attribute [switch_type]. Separate multiple field attributes with commas.
union-type-specifier
Specifies the union type identifier. An optional storage specification can precede type-specifier.
declarator and declarator-list
Specifies a standard C declarator, such as an identifier, pointer declarator, and array declarator. (Function declarators and bit-field declarations are not allowed in unions that are transmitted in remote procedure calls. These declarators are allowed in unions that are not transmitted.) Separate multiple declarators with commas.
function-attribute-list
Specifies zero or more attributes that apply to the function. Valid function attributes are [callback], [local]; the pointer attribute [ref], [unique], or [ptr]; and the usage attributes [string], [ignore], and [context_handle].
type-specifier
Specifies a base type, struct, union, enum type, or type identifier. An optional storage specification can precede type-specifier.
pointer-declarator
Specifies zero or more pointer declarators. A pointer declarator is the same as the pointer declarator used in C; it is constructed from the * designator, modifiers such as far, and the qualifier const.
function-name
Specifies the name of the remote procedure.
param-attr-list
Specifies zero or more attributes appropriate for the specified parameter type. Parameter attributes can take the directional attributes [in] and [out], the field attributes [first_is], [last_is], [length_is], [max_is], [size_is], and [switch_type]; the pointer attribute [ref], [unique], or [ptr]; and the usage attributes [context_handle] and [string]. The usage attribute [ignore] cannot be used as a parameter attribute. Separate multiple attributes with commas.
union-type
Identifies the union type specifier.

Remarks

The discriminant associated with the [switch_is] attribute must be defined at the same logical level as the union:

  • When the union is a parameter, the union discriminant must be another parameter.
  • When the union is a field of a structure, the discriminant must be another field of the same structure.

The sequence in a structure or a function parameter list is not significant. The union can either precede or follow the discriminant.

The [switch_is] attribute can appear as a field attribute or as a parameter attribute.

Examples

typedef [switch_type(short)] union _WILLIE_UNION_TYPE
{
    [case(24)]
        float fMays;
    [case(25)]
        double dMcCovey;
    [default]
        ;
} WILLIE_UNION_TYPE;

typedef struct _WINNER_TYPE
{
    [switch_is(sUniformNumber)] WILLIE_UNION_TYPE w;
    short sUniformNumber;
} WINNER_TYPE;

See Also

MIDL Base Types, [callback], const, [context_handle], Encapsulated Unions, enum, [first_is], [ignore], [last_is], [length_is], [local], [max_is], Nonencapsulated Unions, [ptr], [ref], [size_is], [string], struct, [switch_type], [union], [unique]


switch_type

The [switch_type] attribute identifies the type of the variable used as the union discriminant. The switch type can be an integer, character, Boolean, or enumeration type.

switch_type(switch-type-specifier)

Parameters

switch-type-specifier
Specifies an int, char, Boolean, or enum type, or an identifier of such a type.

Remarks

While the [switch_type] attribute identifes the variable type, the [switch_is] attribute specifies the name of the parameter that is the union discriminant. The [switch_type] attribute applies to parameters or members of structures or unions.

The union and its discriminant must be specified at the same logical level. When the union is a parameter, the union discriminant must be another parameter. When the union is a field of a structure, the discriminant must be another field of the structure at the same level as the union field.

Examples

typedef [switch_type(short)] union _WILLIE_UNION_TYPE
{
    [case(24)]
        float fMays;
    [case(25)]
        double dMcCovey;
    [default]
        ;
} WILLIE_UNION_TYPE;

typedef struct _WINNER_TYPE
{
    [switch_is(sUniformNumber)] WILLIE_UNION_TYPE w;
    short sUniformNumber;
} WINNER_TYPE;

See Also

Boolean, char, Encapsulated Unions, enum, Interface Definition (IDL) File, int, Nonencapsulated Unions, [switch_is], union


transmit_as

The [transmit_as] attribute instructs the compiler to associate type-id, which is a presented type that client and server applications manipulate, with a transmitted type xmit-type.

typedef [transmit_as(xmit-type) [[ , type-attribute-list ]] ] type-specifier declarator-list;

void __RPC_USER type-id_to_xmit (
    type-id __RPC_FAR *,
    xmit-type __RPC_FAR * __RPC_FAR *);
void __RPC_USER type-id_from_xmit (
    xmit-type __RPC_FAR *,
    type-id __RPC_FAR *);
void __RPC_USER type-id_free_inst (
    type-id __RPC_FAR *);
void __RPC_USER type-id_free_xmit (
    xmit-type__RPC_FAR *);

Parameters

xmit-type
Specifies the data type that is transmitted between client and server.
type-attribute-list
Specifies one or more attributes that apply to the type. Valid type attributes include [handle], [switch_type]; the pointer attribute [ref], [unique], or [ptr]; and the usage attributes [string] and [ignore]. Separate multiple attributes with commas.
type-specifier
Specifies a base type, struct, union, enum type, or type identifier. An optional storage specification can precede type-specifier.
declarator-list
Specifies standard C declarators, such as identifiers, pointer declarators, and array declarators. For more information, see Array and Sized-Pointer Attributes, arrays, and Arrays and Pointers. The declarator-list consists of one or more declarators separated by commas. The parameter declarator in the function declarator, such as the parameter name, is optional.
type-id
Specifies the name of the data type that is presented to the client and server applications.

Remarks

To use the [transmit_as] attribute, the user must supply routines that convert data between the presented and the transmitted types; these routines must also free memory used to hold the converted data. The [transmit_as] attribute instructs the stubs to call the user-supplied conversion routines.

The transmitted type xmit-type must resolve to a MIDL base type, predefined type, or a type identifier. For more information, see MIDL Base Types.

The user must supply the following routines.

Routine name | Description
type-id_to_xmit | Converts data from the presented type to the transmitted type. This routine allocates memory for the transmitted type and for any data referenced by pointers in the transmitted type.
type-id_from_xmit | Converts data from the transmitted type to the presented type. This routine is responsible for allocating memory for data referenced by pointers in the presented type. RPC allocates memory for the type itself.
type-id_free_inst | Frees memory allocated for data referenced by pointers in the presented type. RPC frees memory for the type itself.
type-id_free_xmit | Frees storage used by the caller for the transmitted type and for data referenced by pointers in the transmitted type.

The client stub calls type-id_to_xmit to allocate space for the transmitted type and to translate the data into objects of type xmit-type. The server stub allocates space for the original data type and calls type-id_from_xmit to translate the data from its transmitted type to the presented type.

Upon return from the application code, the server stub calls type-id_free_inst to deallocate the storage for type-id on the server side. The client stub calls type-id_free_xmit to deallocate the xmit-type storage on the client side.

The following types cannot have a [transmit_as] attribute:

  • Context handles (types with the [context_handle] type attribute and types that are used as parameters with the [context_handle] attribute)
  • Types that are pipes or derived from pipes
  • Data types that are used as the base type of a pipe definition
  • Parameters that are pointers or resolve to pointers
  • Parameters that are conformant, varying, or open arrays
  • Structures that contain conformant arrays
  • The predefined type handle_t, void

Types that are transmitted must conform to the following restrictions:

  • They must not be pointers or contain pointers.
  • They must not be pipes or contain pipes.

Examples

typedef struct _TREE_NODE_TYPE
{
    unsigned short data;
    struct _TREE_NODE_TYPE * left;
    struct _TREE_NODE_TYPE * right;
} TREE_NODE_TYPE;

typedef [transmit_as(TREE_XMIT_TYPE)] TREE_NODE_TYPE * TREE_TYPE;

void __RPC_USER TREE_TYPE_to_xmit(
    TREE_TYPE __RPC_FAR * ,
    TREE_XMIT_TYPE __RPC_FAR * __RPC_FAR *);

void __RPC_USER TREE_TYPE_from_xmit (
    TREE_XMIT_TYPE __RPC_FAR *,
    TREE_TYPE __RPC_FAR *);

void __RPC_USER TREE_TYPE_free_inst(
    TREE_TYPE __RPC_FAR *);

void __RPC_USER TREE_TYPE_free_xmit(
    TREE_XMIT_TYPE __RPC_FAR *);

See Also

arrays, MIDL Base Types, [context_handle], enum, [handle], handle_t, Interface Definition (IDL) File, [ignore], [ptr], [ref], [string], struct, [switch_type], typedef, union, [unique], void


typedef

The IDL typedef keyword allows typedef declarations that are very similar to C-language typedef declarations.

/* IDL file typedef syntax */
typedef [[ [ idl-type-attribute-list ] ]] type-specifier declarator-list;

/* ACF typedef syntax */
typedef [ acf-type-attribute-list ] typename;

Parameters

idl-type-attribute-list
Specifies one or more attributes that apply to the type. Valid type attributes in an IDL file include [handle], [switch_type], [transmit_as]; the pointer attribute [ref], [unique], or [ptr]; and the usage attributes [context_handle], [string], and [ignore]. Separate multiple attributes with commas.
type-specifier
Specifies a base type, struct, union, enum type, or type identifier. An optional storage specification can precede type-specifier. The const keyword can precede type-specifier.
declarator-list
Specifies standard MIDL declarators, such as identifiers, pointer declarators, and array declarators. For more information, see Array and Sized-Pointer Attributes, arrays., and Arrays and Pointers. The declarator-list consists of one or more declarators, separated by commas.
acf-type-attribute-list
Specifies one or more attributes that apply to the type. Valid type attributes in an ACF include [allocate], [encode], and [decode].
typename
Specifies a type defined in the IDL file.

Remarks

The IDL typedef declaration is augmented to allow you to associate type attributes with the defined types. Valid type attributes include [handle], [switch_type], [transmit_as]; the pointer attribute [ref], [unique], or [ptr]; and the usage attributes [context_handle], [string], and [ignore].

The typedef keyword in an ACF applies attributes to types that are defined in the corresponding IDL file. For example, the [allocate] type attribute allows you to customize memory allocation and deallocation by both the application and the stubs.

The ACF typedef statement appears as part of the ACF body. Note that the ACF typedef syntax is different from the IDL typedef syntax and the C-language typedef syntax. No new types can be introduced in the ACF.

See Also

Application Configuration File (ACF), [allocate], arrays, const, [context_handle], [decode], [encode], enum, [handle], Interface Definition (IDL) File, [ignore], [ptr], [ref], [string], struct, [switch_type], [transmit_as], union, [unique]


union

The union keyword appears in functions that relate to discriminated unions.

/* Encapsulated union*/
typedef [[ [type-attribute-list] ]] union [[ struct-name ]] switch (switch-type switch-name) [[ union-name ]]
{
    C-style-case-list
           [[ [ field-attribute-list <> ] ]] type-specifier <> declarator-list <>;

        ...
}

/* Non-encapsulated union*/
typedef [switch_type(switch-type) [[ , type-attr-list ]] ] union [[ tag ]]
{
    [ case ( limited-expr-list) ]
        [[ [ field-attribute-list ] ]] type-specifier declarator-list;
    [[ [ default ]
        [[ [ field-attribute-list ] ]] type-specifier declarator-list;
    ]]
}

Parameters

type-attribute-list
Specifies zero or more attributes that apply to the union type. Valid type attributes include [handle], [transmit_as]; the pointer attribute [unique], or [ptr]; and the usage attributes [context_handle] and [ignore]. Encapsulated unions can also have the [ref] pointer type attribute. Separate multiple attributes with commas.
struct-name
Specifies an optional tag that names the structure generated by the MIDL compiler.
switch-type
Specifies an int, char, enum type, or an identifier that resolves to one of these types.
switch-name
Specifies the name of the variable of type switch-type that acts as the union discriminant.
union-name
Specifies an optional identifier that names the union in the structure, generated by the MIDL compiler, that contains the union and the discriminant.
C-style-case-list
List of case const-expr :
limited-expression-list
Specifies one or more C-language expressions. The MIDL compiler supports conditional expressions, logical expressions, relational expressions, and arithmetic expressions. MIDL does not allow function invocations in expressions and does not allow increment and decrement operators. Individual expressions in the list should be separated by a comma.
field-attribute-list
Specifies zero or more field attributes that apply to the union member. Valid field attributes include [first_is], [last_is], [length_is], [max_is], [size_is]; the usage attributes [string], [ignore], and [context_handle]; the pointer attribute [unique] or [ptr]; and, for members that are nonencapsulated unions, the union attribute [switch_type]. Nonencapsulated unions can also use the [ref] pointer field attribute. Separate multiple field attributes with commas.
type-specifier
Specifies a base type, struct, union, enum type, or type identifier. An optional storage specification can precede type-specifier.
declarator-list
One or more standard C declarators, such as identifiers, pointer declarators, and array declarators. (Function declarators and bit-field declarations are not allowed in unions that are transmitted in remote procedure calls. Except when you use the MIDL compiler switch /osf, these declarators are allowed in unions that are not transmitted.) Separate multiple declarators with commas.
tag
Specifies an optional tag.

Remarks

MIDL supports two types of discriminated unions: encapsulated unions and nonencapsulated unions. The encapsulated union is compatible with previous implementations of RPC (NCA version 1). The nonencapsulated union eliminates some of the restrictions of the encapsulated union and provides a more visible discriminant than the encapsulated union.

The encapsulated union is identified by the switch keyword and the absence of other union-related keywords.

The nonencapsulated union, also known as a union, is identified by the presence of the [switch_is] and [switch_type] keywords, which identify the discriminant and its type.

When you use [in, out ] unions, be aware that changing the value of the union switch during the call can make the remote call behave differently from a local call. On return, the stubs copy the [in, out] parameter into memory that is already present on the client. When the remote procedure modifies the value of the union switch and consequently changes the data object's size, the stubs can overwrite valid memory with the [out] value. When the union switch changes the data object from a base type to a pointer type, the stubs can overwrite valid memory when they copy the pointer referent into the memory location indicated by the [in] value of a base type.

The shape of unions must be identical across platforms to ensure interconnectivity.

See Also

Encapsulated Unions, Interface Definition (IDL) File, [in], Nonencapsulated Unions, [out], [switch_is], [switch_type]


uidefault

The [uidefault] attribute indicates that the type information member is the default member for display in the user interface.

[method-attribute-list, uidefault]return-type method-name(method-parameter-list)

Parameters

method-attribute-list
Other attributes that apply to the method.
return-type
The type of the data that the method will return when it finishes execution.
method-name
The name of the method.
method-parameter-list
Zero or more parameters for the method.

Remarks

Applying the [uidefault] attribute to a member of an interface or a dispinterface tells Visual Basic, at design-time, to automatically display this event or property to the user. This means that when the user double-clicks an object, VB jumps to the event in the default source interface that has the [uidefault] attribute. When the user selects an object, VB's Properties browser displays the property in the default source interface that has this attribute. If no event or property has the [uidefault] attribute, VB displays the first event or property listed in the default interface.

Typeflag Representation

The presence of FUNCFLAG_FUIDEFAULT or VARFLAG_FUIDEFAULT

Example

[
    dual,
    uuid(12345678-1234-1234-1234-123456789ABC),
    restricted
]
interface IForm: IDispatch
{
    [propget]HRESULT Backcolor([out, retval] long *Value);
    [propput]HRESULT Backcolor([in] long Value);
    [propget, uidefault]HRESULT Name([out, retval] BSTR *Value);
    [propput, uidefault]HRESULT Name([in] BSTR Value);
}
[
    odl,
    dual,
    uuid(87654321-1234-1234-1234-123456789ABC),
    restricted
]
interface IFormEvents: IDispatch
{
    [uidefault]HRESULT Click();
    HRESULT Resize();
}

[
    uuid(12345678-1234-1234-1234-987654321ABC)
]
coclass Form
{
    [default] interface IForm;
    [default, source] interface IFormEvents;
}

See Also

Generating a Type Library With MIDL, ODL File Example, ODL File Syntax


unique

The [unique] attribute specifies a unique pointer.

pointer_default(unique)

typedef [ unique [[ , type-attribute-list ]] ] type-specifier declarator-list;

typedef struct-or-union-declarator
{
    [ unique [[ , field-attribute-list ]] ] type-specifier declarator-list;
    ...}

[ unique [[ , function-attribute-list ]] ] type-specifier ptr-decl function-name(
    [[ [ parameter-attribute-list ] ]] type-specifier [[declarator]]
    , ...);

[[ [ function-attribute-list ] ]] type-specifier [[ptr-decl]] function-name(
    [ unique [[ , parameter-attribute-list ]] ] type-specifier [[declarator]]
    , ...);

Parameters

type-attribute-list
Specifies one or more attributes that apply to the type. Valid type attributes include [handle], [switch_type], [transmit_as]; the pointer attribute [ref], [unique], or [ptr]; and the usage attributes [context_handle], [string], and [ignore]. Separate multiple attributes with commas.
type-specifier
Specifies a base type, struct, union, enum type, or type identifier. An optional storage specification can precede type-specifier.
declarator and declarator-list
Specifies standard C declarators, such as identifiers, pointer declarators, and array declarators. For more information, see Array and Sized-Pointer Attributes, arrays., and Arrays and Pointers. The declarator-list consists of one or more declarators separated by commas. The parameter-name identifier in the function declarator is optional.
struct-or-union-declarator
Specifies a MIDL struct or union declarator.
field-attribute-list
Specifies zero or more field attributes that apply to the structure member, union member, or function parameter. Valid field attributes include [first_is], [last_is], [length_is], [max_is], [size_is]; the usage attributes [string], [ignore], and [context_handle]; the pointer attribute [ref], [unique], or [ptr]; and the union attribute [switch_type]. Separate multiple field attributes with commas.
function-attribute-list
Specifies zero or more attributes that apply to the function. Valid function attributes are [callback], [local]; the pointer attribute [ref], [unique], or [ptr]; and the usage attributes [string], [ignore], and [context_handle].
ptr-decl
Specifies at least one pointer declarator to which the [unique] attribute applies. A pointer declarator is the same as the pointer declarator used in C; it is constructed from the * designator, modifiers such as far, and the qualifier const.
function-name
Specifies the name of the remote procedure.
parameter-attribute-list
Consists of zero or more attributes appropriate for the specified parameter type. Parameter attributes can take the directional attributes [in] and [out]; the field attributes [first_is], [last_is], [length_is], [max_is], [size_is], and [switch_type]; the pointer attribute [ref], unique, or ptr; and the usage attributes [context_handle] and [string]. The usage attribute [ignore] cannot be used as a parameter attribute. Separate multiple attributes with commas.

Remarks

Pointer attributes can be applied as a type attribute; as a field attribute that applies to a structure member, union member, or parameter; or as a function attribute that applies to the function return type. The pointer attribute can also appear with the [pointer_default] keyword.

A unique pointer has the following characteristics:

  • Can have the value NULL.
  • Can change during a call from NULL to non-NULL, from non-NULL to NULL, or from one non-NULL value to another.
  • Can allocate new memory on the client. When the unique pointer changes from NULL to non-NULL, data returned from the server is written into new storage.
  • Can use existing memory on the client without allocating new memory. When a unique pointer changes during a call from one non-NULL value to another, the pointer is assumed to point to a data object of the same type. Data returned from the server is written into existing storage specified by the value of the unique pointer before the call.
  • Can orphan memory on the client. Memory referenced by a non-NULL unique pointer may never be freed if the unique pointer changes to NULL during a call and the client does not have another means of dereferencing the storage.
  • Does not cause aliasing. Like storage pointed to by a reference pointer, storage pointed to by a unique pointer cannot be reached from any other name in the function.

The stubs call the user-supplied memory-management functions midl_user_allocate and midl_user_free to allocate and deallocate memory required for unique pointers and their referents.

The following restrictions apply to unique pointers:

  • The [unique] attribute cannot be applied to binding-handle parameters (handle_t) and context-handle parameters.
  • The [unique] attribute cannot be applied to [out]-only top-level pointer parameters (parameters that have only the [out] directional attribute).
  • By default, top-level pointers in parameter lists are [ref] pointers. This is true even if the interface specifies pointer_default(unique). Top-level parameters in parameter lists must be specified with the [unique] attribute to be a unique pointer.
  • Unique pointers cannot be used to describe the size of an array or union arm because unique pointers can have the value NULL. This restriction prevents the error that results if a NULL value is used as the array size or the union-arm size.

Examples

pointer_default(unique)

typedef [unique, string] unsigned char * MY_STRING_TYPE;

[unique] char * MyFunction([in, out, unique] long * plNumber);

See Also

arrays, Arrays and Pointers, Array and Sized-Pointer Attributes, MIDL Base Types, [callback], const, [context_handle], enum, [first_is], [handle], handle_t, [ignore, [last_is], [length_is], [local], [max_is], midl_user_allocate, midl_user_free, [out], [pointer_default, [ptr], [ref], [size_is], [string], struct, [switch_type], [transmit_as], union, [unique]


unsigned

The unsigned keyword indicates that the most significant bit of an integer variable represents a data bit rather than a signed bit.

[[ unsigned ]] type-qualifier [[ int ]]identifier-name;

Parameters

type-qualifier
Can be any of char, wchar_t, long, int, short, and small.
identifier-name
Specifies a valid MIDL identifier. Valid MIDL identifiers consist of up to 31 alphanumeric and/or underscore characters and must start with an alphabetic or underscore character.

Remarks

This keyword is optional and can be used with any of the character and integer types char, wchar_t, long, short, and small. You can optionally include the keyword int after the type qualifiers long, short, and small.

When you use the MIDL compiler switch /char, character and integer types that appear in the IDL file without explicit sign keywords can appear with the signed or unsigned keyword in the generated header file. To avoid confusion, specify the sign of the integer and character types.

See Also

MIDL Base Types, char, /char, Interface Definition (IDL) File, int, long, short, signed, small, wchar_t


user_marshal

The [user_marshal] attribute associates a named local type in the target language (userm-type) with a transfer type (wire-type) that is transferred between client and server.

typedef [user_marshal(userm_type)] wire-type;
unsigned long __RPC_USER  < userm_type >_UserSize(
    unsigned long __RPC_FAR *pFlags,
    unsigned long StartingSize,
    < userm_type >  __RPC_FAR * pUser_typeObject );
unsigned char __RPC_FAR * __RPC_USER  < userm_type >_UserMarshal(
    unsigned long __RPC_FAR *pFlags,
    unsigned char __RPC_FAR * Buffer,
    < userm_type >  __RPC_FAR * pUser_typeObject);
unsigned char __RPC_FAR * __RPC_USER  < userm_type >_UserUnmarshal(
    unsigned long  __RPC_FAR *  pFlags,
    unsigned char __RPC_FAR *  Buffer,
    < userm_type >  __RPC_FAR * pUser_typeObject);
void __RPC_USER  < userm_type >_UserFree(
    unsigned long  __RPC_FAR * pFlags,
    < userm_type >  __RPC_FAR * pUser_typeObject);

Parameters

userm-type
Specifies the identifier of the user data type to be marshaled. The userm-type need not be transmittable and need not be a type known to the MIDL compiler.
wire-type
Specifies the named transfer data type that is actually transferred between client and server. the wire-type must be a MIDL base type, predefined type, or a type identifier of a type that can be transmitted across the network.
pFlags
Specifies a pointer to a flag field (unsigned long). The high-order word specifies NDR data representation flags as defined by DCE for floating point, big- or little-endian, and character representation. The low-order word specifies a marshaling context flag. The exact layout of the flags is described in The type_UserSize Function.
StartingSize
Specifies the current buffer size (offset) before sizing the object.
pUser_typeObject
Specifies a pointer to an object of userm_type.
Buffer
Specifies the current buffer pointer.

Remarks

Each named local type, userm-type, has a one-to-one correspondence with a wire-type that defines the wire representation of the type. You must supply routines to size the data for marshaling, to marshal and unmarshal the data, and to free memory. For more information on these routines, see The user_marshal Attribute. Note that if there are embedded types in your data that are also defined with [user_marshal] or [wire_marshal], you need to manage the servicing of those embedded types also.

The wire-type cannot be an interface pointer or a full pointer. The wire-type must have a well-defined memory size. See Marshaling Rules for user_marshal and wire_marshal for details on how to marshal a given wire-type.

The userm-type should not be an interface pointer as these can be marshaled directly. If the user type is a full pointer, you must manage the aliasing yourself.

Examples

// Marshal a long as a structure containing two shorts.
typedef unsigned long FOUR_BYTE_DATA;
typedef struct _TWO_X_TWO_BYTE_DATA
{
    unsigned short low;
    unsigned short high;
} TWO_X_TWO_BYTE_DATA;
//in ACFL file:
typedef [user_marshal(FOUR_BYTE_DATA)] TWO_X_TWO_BYTE_DATA;

//Marshaling functions:

// Calculate size that converted data will
// require in the buffer
unsigned long __RPC_USER FOUR_BYTE_DATA_UserSize(
    ULONG __RPC_FAR * pulFlags,
    char __RPC_FAR * pBufferStart,
    FOUR_BYTE_DATA __RPC_FAR * pul);

// Copy FOUR_BYTE_DATA into buffer as TWO_X_TWO_BYTE_DATA
unsigned long __RPC_USER FOUR_BYTE_DATA_UserMarshal(
    ULONG __RPC_FAR *pulFlags,
    char __RPC_FAR * pBufferStart,
    FOUR_BYTE_DATA __RPC_FAR * pul);

// Recreate FOUR_BYTE_DATA from TWO_X_TWO_BYTE_DATA
// in buffer
unsigned long __RPC_USER FOUR_BYTE_DATA_UserUnmarshal(
    ULONG __RPC_FAR * pulFlags,
    char __RPC_FAR * pBufferStart,
    FOUR_BYTE_DATA __RPC_FAR * pul);

// Nothing to do here as the engine frees the
// top node and FOUR_BYTE_DATA is a flat data type.
void __RPC_USER FOUR_BYTE_DATA_UserFree(
    ULONG __RPC_FAR * pulFlags,
    FOUR_BYTE_DATA __RPC_FAR * pul);

See Also

MIDL Base Types, long, [represent_as], unsigned, The user_marshal Attribute, [wire_marshal], NdrGetUserMarshalInfo


usesgetlasterror

The [usesgetlasterror] attribute signals the caller that it can call GetLastError to retrieve the error code.

[
    module-attributes
]
module module-name
{
    [entry(entry-id), usesgetlasterror [, other-attributes]] return-type function-name(param-list);
};

Parameters

module-attributes
Zero or more MIDL attributes that will be applied to the module.
module-name
The identifier name of the module.
entry-id
Specifies the module entry point–function name or integer-identification number.
other-attributes
Zero or more MIDL attributes that will be applied to the remote procedure.
return-type
The type of the data that the remote procedure will return upon completion.
function-name
The name of the remote procedure as defined in the IDL file.
param-list
Zero or more parameters to the remote procedure.

Remarks

The [usesgetlasterror] attribute can be set on a module entry point, if that entry point uses the Win32 function SetLastError to return error codes. The attribute tells the caller that, if there is an error when calling that function, the caller can then call GetLastError to retrieve the error code.

Example

[
    dllname("MyOwn.dll")
]
module MyModule
{
    [entry("One"), usesgetlasterror, bindable, requestedit,
     propputref, defaultbind] HRESULT Func1(
         [in]IUnknown * iParam1,
         [out] long * Param2) ;
    [entry("TwentyOne"), usesgetlasterror,
     hidden, vararg] SAFEARRAY (int) Func2(
         [in, out] SAFEARRAY (variant) *varP) ;

    // Other module definition statements.
};

See Also

Differences Between MIDL and MKTYPLIB, Generating a Type Library With MIDL, ODL File Example, ODL File Syntax


uuid

The [uuid] interface attribute designates a universally unique identifier (UUID) that is assigned to the interface and that distinguishes it from other interfaces.

uuid (string-uuid)
uuid ("string-uuid")

Parameters

string-uuid
Specifies a string consisting of 8 hexadecimal digits followed by a hyphen, then three groups of 4 hexadecimal digits each followed by a hyphen, then 12 hexadecimal digits. You can enclose the UUID string in quotes, except when you use the MIDL compiler switch /osf.

Remarks

The run-time library uses the interface UUID that the [uuid] attribute designates to help establish communication between the client and server applications. The [uuid] attribute can appear in the interface attribute list for either an RPC interface or a COM interface.

For an RPC interface, the interface attribute list must include either the [uuid] attribute or the [local] attribute, and the one you choose must occur exactly once. If the list includes the [uuid] attribute, it can also include the [version] attribute.

For a COM interface (identified by the [object] interface attribute), the interface attribute list must include the [uuid] attribute, but it cannot include the [version] attribute. The list for a COM interface can include the [local] attribute even though the [uuid] attribute is present.

Microsoft RPC supports an extension to DCE IDL that allows the UUID to be enclosed in double quotation marks ("" ""). The quoted form is needed for C-compiler preprocessors that interpret UUID numbers as floating-point numbers.

All UUID values should be computer-generated to guarantee uniqueness. Use the uuidgen utility to generate unique UUID values.

The UUID and version numbers of the interface are used to determine whether the client can bind to the server. For the client to bind to the server, the UUID specified in the client and server interfaces must be the same.

Note that an interface without attributes can be imported into a base IDL file. However, the interface must contain only datatypes with no procedures. If even one procedure is contained in the interface, a local or UUID attribute must be specified.

Examples

uuid(6B29FC40-CA47-1067-B31D-00DD010662DA)

uuid("6B29FC40-CA47-1067-B31D-00DD010662DA")

See Also

Interface Definition (IDL) File, interface, [local], [object], /osf, [version]


v1_enum

The [v1_enum] attribute directs that the specified enumerated type be transmitted as a 32-bit entity, rather than the 16-bit default.

[v1_enum] enum
{
    ...
};

Parameters

Remarks

Using the [v1_enum] attribute to transmit an enumerated type as a 32-bit entity increases the efficiency of marshaling and unmarshaling data when such an enumeration is embedded in structures or unions.

For improved performance, we recommend applying the [v1_enum] attribute to enumerators in 32-bit applications. Keep in mind, however, that on 16-bit platforms the C compiler treats an enumerated type as a 16-bit int. Therefore 16-bit client applications need to convert enum types to long for remote transmission in order to avoid overwriting data or sending incorrect values.

Example

typedef [v1_enum] enum
{
    value1,
    value2, ...
};

See Also

enum, Interface Definition (IDL) File, long


vararg

The [vararg] attribute specifies that the function takes a variable number of parameters. To accomplish this, the last parameter must be a safe array of VARIANT type that contains all the remaining parameters.

[vararg [, optional-attributes]] return-type function-name(
    [optional-param-attributes] param-list,
    SAFEARRAY(VARIANT) last-param-name);

Parameters

optional-attributes
Specifies zero or more attributes to be applied to the function. Separate multiple attributes with commas.
return-type
The type of the data returned by the remote procedure upon completion.
function-name
The name of the remote procedure.
optional-param-attributes
Specifies zero or more attributes to be applied to the function parameter immediately following the attribute listing.
param-list
Specifies all the parameters, save the final, varying, parameter.
last-param-name
The name of the varying parameter.

Remarks

You cannot apply the [optional] or [defaultvalue] attributes to any parameters in a function that has the [vararg] attribute.

Example

[vararg] VARIANT_BOOL Button([in]SAFEARRAY(VARIANT) psa);

See Also

[defaultvalue], Differences Between MIDL and MKTYPLIB, Generating a Type Library With MIDL, ODL File Example, ODL File Syntax, [optional]


version

The [version] interface attribute identifies a particular version among multiple versions of an RPC interface. With the version attribute, you ensure that only compatible versions of client and server software are allowed to bind.

version ( major-value[[. minor-value]] )

Parameters

major-value
Specifies a short unsigned integer between zero and 65,535, inclusive, that represents the major version number.
minor-value
Specifies a short unsigned integer between zero and 65,535, inclusive, that represents the minor version number. The minor version value is optional. If present, the minor version value is separated from the major version number by a period character (.). If not specified, the minor version value is zero.

Remarks

The MIDL compiler does not support multiple versions of a COM interface. As a result, an interface attribute list that includes the [object] attribute cannot include the [version] attribute. To create a new version of an existing COM interface, use interface inheritance. A derived COM interface has a different UUID but inherits the interface member functions, status codes, and interface attributes of the base interface.

In combination with the [uuid] value, the [version] value uniquely identifies the interface. The run-time library passes the [version] and [uuid] values to the server when the client calls a remote function. A client can bind to a server for a given interface if:

  • The [uuid] value is the same.
  • The major version number is the same.
  • The client's minor version number is less than or equal to the server's minor version number.

It is to your benefit and your users' benefit to retain upward compatibility among versions that is, to modify the interface so that only the minor version number changes. You can retain upward compatibility when you add new data types that are not used by existing functions and when you add new functions without changing the interface specification for existing functions.

Change the major version number if any one of the following conditions apply:

  • If you change a data type that is used by an existing function.
  • If you change the interface specification for an existing function (such as adding or removing a parameter).
  • If you add callbacks that are called by existing functions.

Change the minor version number if all of the following conditions apply:

  • If you add type definitions or constants that are not used by any existing functions or callbacks.
  • If you do not change any existing functions and you add new functions to the interface.
  • If you add callbacks that are not called by any existing functions and the new callbacks follow any existing functions.

If your modifications qualify as an upward-compatible change to the interface, use the following procedure.

To modify the interface (IDL) file

  1. Add new constant and type definitions to the interface file.
  2. Add callback functions to the end of the interface file.
  3. Add new functions to the end of the interface file.

The [version] attribute can occur at most once in the interface header.

When the version attribute is not present, the interface has a default version of 0.0.

The period character between the major and minor numbers is a delimiter and does not represent a decimal point. The minor number is treated as an integer. Leading zeroes are not significant. Trailing zeroes are significant.

For example, the version setting 1.11 represents a major value of one and a minor value of eleven. Version 1.11 does not represent a value between 1.1 and 1.2.

See Also

Interface Definition (IDL) File, interface, [object], [uuid]


void

The base type void indicates a procedure with no arguments or a procedure that does not return a result value.

void function-name(parameter-list);

return-type function-name(void);

typedef [context_handle] void * context-handle-type;

return-type function-name(
    [context_handle] void * * context-handle-type
    , ...);

Parameters

function-name
Specifies the name of the remote procedure.
parameter-list
Specifies the list of parameters passed to the function along with the associated parameter types and parameter attributes.
return-type
Specifies the name of the type returned by the function.
context-handle-type
Specifies the name of the type that takes the [context_handle] attribute.

Remarks

The pointer type void *, which in C describes a generic pointer that can be cast to represent any pointer type, is limited in MIDL to its use with the [context_handle] keyword.

Examples

void VoidFunc1(void);
HRESULT VoidFunc2([in, out] short s1);
typedef [context_handle] void * MY_CX_HNDL_TYPE;
HRESULT InitHandle([out] MY_CX_HNDL_TYPE * ppCxHndl);

See Also

MIDL Base Types, [context_handle], Interface Definition (IDL) File


wchar_t

The wchar_t keyword designates a wide-character type.

wchar_t identifier-name;

Parameters

identifier-name
Specifies a valid MIDL identifier. Valid MIDL identifiers consist of up to 31 alphanumeric and/or underscore characters and must start with an alphabetic or underscore character.

Remarks

The wchar_t type is defined by MIDL as an unsigned short (16-bit) data object.

The MIDL compiler allows redefinition of wchar_t, but only if it is consistent with the preceding definition.

The wide-character type is one of the predefined types of MIDL. The wide-character type can appear as a type specifier in const declarations, typedef declarations, general declarations, and function declarators (as a function return–type specifier and as a parameter-type specifier). For the context in which type specifiers appear, see Interface Definition (IDL) File.

The [string] attribute can be applied to a pointer or array of type wchar_t.

Use the L character before a character or a string constant to designate the wide character–type constant.

See Also

MIDL Base Types, char, const, Interface Definition (IDL) File, short, typedef, unsigned


wire_marshal

The [wire_marshal] attribute specifies a data type that will be used for transmission (the wire-type) instead of an application-specific data type (the userm-type).

typedef [wire_marshal(wire_type)] type-specifier userm-type;
unsigned long __RPC_USER  < userm-type >_UserSize(
    unsigned long __RPC_FAR *pFlags,
    unsigned long StartingSize,
    < userm-type >  __RPC_FAR * pUser_typeObject );
unsigned char __RPC_FAR * __RPC_USER  < userm-type >_UserMarshal(
    unsigned long  __RPC_FAR * pFlags,
    unsigned char __RPC_FAR * Buffer,
    < userm-type >  __RPC_FAR * pUser_typeObject);
unsigned char __RPC_FAR * __RPC_USER  < userm-type >_UserUnmarshal(
    unsigned long  __RPC_FAR *  pFlags,
    unsigned char __RPC_FAR *  Buffer,
    < userm-type >  __RPC_FAR * pUser_typeObject);
void __RPC_USER  < userm-type >_UserFree(
    unsigned long  __RPC_FAR * pFlags,
    < userm-type >  __RPC_FAR * pUser_typeObject);

Parameters

wire-type
Specifies the named transfer data type that is actually transferred between client and server. The wire-type must be a MIDL base type, predefined type, or a type identifier of a type that can be transmitted across the network.
type-specifier
The type for which userm-type will become an alias.
userm-type
Specifies the identifier of the user data type to be marshaled. It can be any type, as given by the type-specifier, as long as it has a well-defined size. The userm-type need not be transmittable but must be a type known to the MIDL compiler.
pFlags
Specifies a pointer to a flag field (unsigned long). The high-order word specifies NDR data representation flags as defined by DCE for floating point, big- or little-endian, and character representation. The low-order word specifies a marshaling context flag. The exact layout of the flags is described in The type_UserSize Function.
StartingSize
Specifies the current buffer size (offset) before sizing the object.
pUser_typeObject
Specifies a pointer to an object of userm_type.
Buffer
Specifies the current buffer pointer.

Remarks

Each application-specific data type, userm-type, has a one-to-one correspondence with a wire-type that defines the wire representation of the type. You must supply routines to size the data for marshaling, to marshal and unmarshal the data, and to free memory. Note that if there are embedded types in your data that are also defined with [wire_marshal] or [user_marshal], you need to manage the servicing of those embedded types also. For more information on these routines, see The wire_marshal Attribute.

The wire-type cannot be an interface pointer or a full pointer. The wire-type must have a well-defined memory size. See Marshaling Rules for user_marshal and wire_marshal for details on how to marshal a given wire-type.

The userm-type should not be an interface pointer because these can be marshaled directly. If the user type is a full pointer, you must manage the aliasing yourself.

You cannot use the [wire_marshal] attribute with the [allocate] attribute, either directly or indirectly, because the NDR engine does not control memory allocation for the transmitted type.

Examples

typedef unsigned long _FOUR_BYTE_DATA;

typedef struct _TWO_X_TWO_BYTE_DATA
{
        unsigned short low;
        unsigned short high;
} TWO_X_TWO_BYTE_DATA;

typedef [wire_marshal(TWO_X_TWO_BYTE_DATA)]
    _FOUR_BYTE_DATA FOUR_BYTE_DATA;

//Marshaling functions:

// Calculate size that converted data will
// require in the buffer
unsigned long __RPC_USER FOUR_BYTE_DATA_UserSize(
    ULONG __RPC_FAR * pulFlags,
    char __RPC_FAR * pBufferStart,
    FOUR_BYTE_DATA __RPC_FAR * pul);

// Copy FOUR_BYTE_DATA into buffer as
// TWO_X_TWO_BYTE_DATA
unsigned long __RPC_USER FOUR_BYTE_DATA_UserMarshal(
    ULONG __RPC_FAR *pulFlags,
    char __RPC_FAR * pBufferStart,
    FOUR_BYTE_DATA __RPC_FAR * pul);

// Recreate FOUR_BYTE_DATA from TWO_X_TWO_BYTE_DATA in buffer
unsigned long __RPC_USER FOUR_BYTE_DATA_UserUnmarshal(
    ULONG __RPC_FAR * pulFlags,
    char __RPC_FAR * pBufferStart,
    FOUR_BYTE_DATA __RPC_FAR * pul);

// Nothing to do here as the engine frees the top
// node and FOUR_BYTE_DATA is a flat data type.
void __RPC_USER FOUR_BYTE_DATA_UserFree(
    ULONG __RPC_FAR * pulFlags,
    FOUR_BYTE_DATA __RPC_FAR * pul
    );

See Also

[allocate], MIDL Base Types, long, [transmit_as], unsigned, [user_marshal], The wire_marshal Attribute, NdrGetUserMarshalInfo


MIDL Compiler Errors and Warnings

When using the MIDL compiler, errors and warnings can be caused by improper use of the command-line switches or by the content of the IDL and ACF files. If the error is due to improperly entering the command-line switches, an error or warning message may specify the name of one or more MIDL compiler mode switches. For example, you can include certain ACF attributes in an IDL file when you use the /app_config switch, but that IDL file will generate an error if you compile without using the /app_config switch.

Errors in the IDL and ACF files fall into two categories: errors caught by the preprocessor and errors recognized by the compiler. This section lists the MIDL preprocessor and compiler error messages. It also describes their formats and causes.

  • Error and Warning Message Formats
  • Preprocessor Errors
  • Compiler Errors


Error and Warning Message Formats

Command-line errors appear in the following format:

Command line error : MIDLnnnn: <error text>
[<additional error information>]

The additional error-information field provides context-specific information depending on the error message. For example, when an unresolved type-declaration error occurs, the additional error-information field displays the name of the type that could not be resolved.

Compile-time warnings appear in the following format:

<FileName>(line#) : warning MIDLnnnn:
<warning text>
[optional context information]:

Compile-time errors appear in the following format:

<FileName>(line#) : error MIDLnnnn:
<error text>
[optional context information] :

Optional context information refers to the context in which the error occurred. It is generated when the MIDL compiler discovers an error during semantic analysis of type and procedure signatures. The MIDL compiler reports this information to help you find the error in the IDL file quickly.

System error messages appear in the following format:

<FileName>(line#) : MIDL error 0xnnnn:
"Unexpected internal compiler problem. Try to find a workaround."

This message is generated by an error that was unexpected. The hexadecimal error number is a Microsoft® Windows NT®/Windows® 2000 or Windows 9x system error identifier. You may find additional information in Winerror.h or Ntstatus.h. For more information on working around the conditions that caused this error, see the error text for compiler error MIDL9008.


Preprocessor Errors

The following error messages are generated during preprocessing:

MIDL1000: missing source file name
No input file has been specified in the MIDL compiler–command line.
MIDL1001: cannot open input file
The specified input file could not be opened.
MIDL1002: error while reading input file
The system returned an error while reading the input file.
MIDL1003: error returned by the C preprocessor
The preprocessor returned an error. The error message is directed to the output stream.
MIDL1004: cannot execute C preprocessor
The operating system reported an error when it tried to launch the preprocessor. With MS-DOS, this error can occur when the argument list exceeds 128 bytes. You can reduce the size of the argument list by using a response file.
MIDL1005: cannot find C preprocessor
The MIDL compiler cannot locate the preprocessor in the path specified by either the command line or the PATH environment variable.
MIDL1006: invalid C preprocessor executable
The specified preprocessor is not executable or it has an invalid executable-file format.
MIDL1007: switch specified more than once on command line
A switch that should only occur once on the command-line was specified multiple times. The redefined switch is displayed after the error message.
MIDL1008: unknown switch
An unknown switch has been specified on the command line.
MIDL1009: unknown argument ignored
The MIDL compiler does not recognize the command-line argument as a switch, a switch argument, or a file name. The compiler discards the unknown argument and attempts to continue processing.

If everything appears correct but ythis error persists, check to see if the arguments to the command-line switch are passed to the MIDL compiler in a response file. If they are and if the arguments are a file name that uses the multibyte character set (MBCS), ensure that the file name contains no spaces. If it does, delete the spaces, invoke the MIDL compiler and its arguments from a batch file, or enclose the file name in quotes.

MIDL1010: switch not implemented
The MIDL compiler recognizes the switch as defined, but the switch is not yet implemented in Microsoft RPC.
MIDL1011: argument(s) missing for switch
The switch expected an argument, and the argument is not present. Check the appropriate topic for the specified switch in the MIDL Command-Line Reference documentation.
MIDL1012: argument illegal for switch /
The argument supplied to the specified switch is illegal. Check the appropriate topic for the specified switch in the MIDL Command-Line Reference documentation.
MIDL1013: illegal syntax for switch
Several command-line switches require a space between the switch and the argument, while other switches require no space between the switch and the argument. The specified command line violates the defined syntax for that switch. Check the appropriate topic for the specified switch in the MIDL Command-Line Reference documentation.
MIDL1014: /no_cpp overrides /cpp_cmd and /cpp_opt
The cpp_opt command has been supplied along with the /no_cpp switch. The /no_cpp switch takes precedence over the other switches.
MIDL1015: /W0 or /no_warn overrides warning-level switch
The W0 or no_warn option has been specified along with the warning-level switch W1, W2, or W3. The /no_warn switch takes precedence over all other warning-level switches.
MIDL1016: cannot create intermediate file
The system returned an error when the compiler tried to create an intermediate file. The disk might be full, the path might not exist, or you may not have write permission for the disk or directory.
MIDL1018: out-of-system file handles
The MIDL compiler ran out of file handles while opening a file. This error can occur if too many import files are open and the compiler tries to open an IDL file or an intermediate file.
MIDL1020: cannot open response file
The specified response file could not be opened. The file probably does not exist.
MIDL1021: illegal character(s) found in response file
A nonprintable character has been detected in the response file. The response file should contain valid MIDL command-line switches and arguments.
MIDL1022: mismatch in argument pair for switch
The arguments for this switch cannot be used together. Check the appropriate topic for the specified switch in the MIDL Command-Line Reference documentation.
MIDL1023: nested invocation of response files is illegal
A response file cannot contain the @ command that directs the MIDL compiler to process another response file. Although there is no limit on the number of response files on the command line, response files cannot be nested.


Compiler Errors

The following error messages are generated during MIDL compilation:

MIDL2000: must specify /c_ext for abstract declarators
Abstract declarators represent a Microsoft extension to RPC and are not defined in DCE RPC. Therefore, if your file includes abstract declarators, you cannot compile with the /osf switch, which enforces strict DCE compatibility. MIDL versions 3.0 and later use the /c_ext switch as the default; the /osf switch turns off the /c_ext switch. For information on abstract declarators, see The ACF Body.
MIDL2001: instantiation of data is illegal; you must use "extern" or "static"
Declaration and initialization in the IDL file are not compatible with DCE RPC. This feature is a Microsoft extension that is not available when you compile in DCE-compatibility (/osf) mode.
MIDL2002: compiler stack overflow
The compiler ran out of stack space while processing the IDL file. This problem can occur when the compiler is processing a complex declaration or expression. To solve the problem, simplify the complex declaration or expression.
MIDL2003: redefinition
This error message can appear under the following circumstances: a type has been redefined; a procedure prototype has been redefined; a member of a structure or union of the same name already exists; a parameter of the same name already exists in the prototype.
MIDL2004: [auto_handle] binding will be used
No handle type has been defined as the default handle type. The compiler assumes that an auto handle will be used as the binding handle for the specified procedure.
MIDL2005: out of memory
The compiler ran out of memory during compilation. Reduce the size or complexity of the IDL file or allocate more memory to the process.
MIDL2006: recursive definition
A structure or union has been recursively defined. This error can occur when a pointer specification in a nested structure definition is missed.
MIDL2007: import ignored; file already imported
Importing an IDL file is an idempotent operation. Including it more than once has no effect. All but the first import operation are ignored.
MIDL2008: sparse enums require /c_ext or /ms_ext
Assigning values to enumeration constants is not compatible with DCE RPC. If you want to use the Microsoft extensions to MIDL that permit assigning values to enumeration constants,you cannot compile with the /osf switch, which enforces strict DCE compatibility. MIDL versions 3.0 and later use the /c_ext and /ms_ext switches as the default; the /osf switch turns off these extension switches.
MIDL2009: undefined symbol
An undefined symbol has been used in an expression. This error can occur when you use an undefined enumerated value.
MIDL2010: type used in ACF file not defined in IDL file
An undefined type is being used.
MIDL2011: unresolved type declaration
The type reported in the additional error-information field has not been defined elsewhere in the IDL file.
MIDL2012: use of wide-character constants requires /ms_ext or /c_ext
Wide-character constants are a Microsoft extension to DCE IDL. To use the data type wchar_t, you cannot compile with the /osf switch, which overrides the MIDL compiler default switches–/ms_ext and /c_ext.
MIDL2013: use of wide character strings requires /ms_ext or /c_ext
Wide-character string constants are a Microsoft extension to DCE IDL. To use the data type wchar_t, you cannot compile with the /osf switch, which overrides the MIDL compiler default switches–/ms_ext and /c_ext.
MIDL2014: inconsistent redefinition of type wchar_t
The type wchar_t has been redefined as a type that is not equivalent to unsigned short.
MIDL2015: importlib not found
The compiler could not find the type library specified by the [importlib] directive. Check to make sure the path and name of the library are correct.
MIDL2016: two library blocks
Two library blocks (even with different names) in the same source file are illegal. Combine all the elements into a single library block.
MIDL2017: the dispinterface statement requires a definition for IDispatch
This error generally occurs when the files Stdole2.tlb or Oaidl.idl are not imported.
MIDL2018: error accessing type library
The compiler could not find the specified type library. Check to make sure that you have specified the path correctly.
MIDL2019: error accessing type info
The imported type library is corrupt, invalid, or only partially constructed.
MIDL2020: error generating type library
The type library could not be generated. One possible cause of this error is specifying a path to the IDL file that is longer than 126 characters. Oleaut32.dll does not support path names longer than 126 characters.
MIDL2021: duplicate id
Applications use the id statement in IDL files to specify a DISPID for member functions. The member functions can be either properties or methods of interfaces or dispinterfaces. This error indicates the IDL file specifies the same identifier number for two methods or properties.
MIDL2022: illegal or missing value for entry attribute
The argument for the entry attribute may be either a string that specifies a named entry point, or an ordinal number that defines the entry point. This argument is either missing or it contains an invalid value.
MIDL2023: error recovery assumes
The MIDL compiler found illegal characters in the IDL file.
MIDL2024: error recovery discards
The MIDL compiler found illegal characters in the IDL file. It will ignore the illegal characters.
MIDL2025: syntax error
The compiler detected a syntax error at the specified line.
MIDL2026: cannot recover from earlier syntax errors; aborting compilation
The MIDL compiler automatically tries to recover from syntax errors by adding or removing syntactic elements. This message indicates that despite these attempts to recover, the compiler detected too many errors. Correct the specified error(s) and recompile.
MIDL2027: unknown pragma option
The specified C pragma is not supported in MIDL. Remove the pragma from the IDL file.
MIDL2028: feature not implemented
The MIDL feature, although part of the language definition, is not implemented in Microsoft RPC and is not supported by the MIDL compiler. For example, the following language features are not implemented: bitset, pipe, and the international character type. The unimplemented language feature appears in the additional error-information field of the error message.
MIDL2029: type not implemented
The specified data type, although a legal MIDL keyword, is not implemented in Microsoft RPC.
MIDL2030: non-pointer used in a dereference operation
A data type that is not a pointer has been associated with pointer operations. You cannot access the object through the specified non-pointer.
MIDL2031: expression has a divide by zero
The constant expression contains division by zero.
MIDL2032: expression uses incompatible types
The left and right sides of the operator in an expression are of incompatible types.
MIDL2033: nonarray expression uses index operator
The expression uses the array-indexing operation on a data item that is not of the array type.
MIDL2034: left-hand side of expression does not evaluate to struct/union/enum
The direct or indirect reference operator "." or "->" has been applied to a data object that is not a structure, union, or an enumeration. You cannot obtain a direct or indirect reference using the specified object.
MIDL2035: constant expression expected
A constant expression was expected in the syntax. For example, array bounds require a constant expression. The compiler issues this error message when the array bound is defined with a variable or undefined symbol.
MIDL2036: expression cannot be evaluated at compile time
The compiler cannot evaluate an expression at compile time.
MIDL2037: expression not implemented
A feature that was supported in previous releases of the MIDL compiler is not supported in the version of the compiler supplied with Microsoft RPC. Remove the specified expression.
MIDL2038: no [pointer_default] attribute specified, assuming [unique] for all unattributed pointers
The MIDL compiler offers three different default cases for pointers that do not have pointer attributes. Function parameters that are top-level pointers default to [ref ] pointers. Pointers embedded in structures and pointers to other pointers (not top-level pointers) default to the type specified by the [pointer_default] attribute. When no [pointer_default] attribute is supplied, these nontop-level pointers default to unique pointers. This error message indicates the last case: no [pointer_default] attribute is supplied, and there is at least one non-top-level pointer that will be treated as a unique pointer. For more information, see Default Pointer Types.
MIDL2039: interface is not automation marshaling conformant, requires Windows NT 4.0 SP4 or greater
The interface does not meet the requirements for an OLE Automation interface. Check to make sure the interface is derived from IUnknown or IDispatch.
MIDL2040: [out] only parameter cannot be a pointer to an open structure
An [out]-only parameter has been used as a pointer to a structure, known as an open structure, whose transmitted range and size are determined at run time. The server stub does not know how much space to allocate for an open structure. Use a pointer to a pointer to the open structure and ensure that the server application allocates sufficient space for it.
MIDL2041: [out] only parameter cannot be an unsized string
An array with the string attribute has been declared as an [out]-only parameter without any size specification. The server stub needs size information to allocate memory for the string. You can remove the string attribute and add the [size_is] attribute, or you can change the parameter to an [in, out] parameter.
MIDL2042: [out] parameter is not a pointer
All [out] parameters must be pointers, in keeping with the call-by-value convention of the C programming language. The [out] directional parameter indicates that the server transmits a value to the client. With the call-by-value convention, the server can transmit data to the client only if the function argument is a pointer.
MIDL2043: open structure cannot be a parameter
An open structure contains a conformant array as the last element. A structure or union is truncated when the last element of that structure or union is a conformant array.
MIDL2044: [out] context handle/generic handle must be specified as a pointer to that handle type
A context-handle or user-defined handle parameter with the [out] directional attribute must be a pointer to a pointer.
MIDL2045: context handle must not derive from a type that has the [transmit_as] attribute
Context handles must be transmitted as context-handle types. They cannot be transmitted as other types and cannot derive from [transmit_is], [represent_as], [wire_marshal], or [user_marshal].
MIDL2046: cannot specify a variable number of arguments to a remote procedure
Remote procedure calls that specify a variable number of arguments at compile time are not compatible with the DCE RPC definition. You cannot use a variable number of arguments in Microsoft RPC.
MIDL2047: named parameter cannot be "void"
A parameter with the base type void is specified with a name.
MIDL2048: parameter derives from "coclass" or "module"
The coclass specifies a top-level object that contains interfaces and dispinterfaces. It cannot be passed as a parameter.
MIDL2049: only the first parameter can be a binding handle; you must specify the /ms_ext switch
DCE RPC allows only the first parameter to be a binding handle. Compiling with the /osf switch turns off the default /ms_ext switch that supports multiple handle parameters and handle parameters in other than the left-most position.
MIDL2050: cannot use [comm_status] on both a parameter and a return type
Both the procedure and one of its parameters have the [comm_status] attribute. The [comm_status] attribute specifies that only one data object at a time can be of type error_status_t.
MIDL2051: [local] attribute on a procedure requires /ms_ext
The [local] attribute is a Microsoft extension to DCE IDL. To use this attribute on a function, you cannot compile with the /osf switch. The /osf switch overrides the MIDL compiler default switches–/ms_ext and /c_ext.
MIDL2052: property attributes may only be used with procedures
Improper usage of a [propget], [propput], or [propputref] attribute. Check to be sure that you have spelled the property's function name correctly and that the property and function have the same name.
MIDL2053: a procedure may not have more than one property attribute
At most, only one of the [propget], [propput], or [propputref] attributes can be specified for a function.
MIDL2054: the procedure has an illegal combination of operation attributes
Certain attributes cannot be used in connection with other attributes. Check the MIDL Language Reference for the exact requirements and syntax of the attributes used in this procedure.
MIDL2055: field deriving from a conformant array must be the last member of the structure
The structure contains a conformant array that is not the last element in the structure. The conformant array must appear as the last structure element.
MIDL2056: duplicate [case] label
A duplicate case label has been specified. The duplicate label is displayed.
MIDL2057: no [default] case specified for discriminated union
A discriminated union has been specified without a default case.
MIDL2058: attribute expression cannot be resolved
The expression associated with the attribute cannot be resolved. This error usually occurs when a variable that appears in the expression is not defined. For example, the error can occur when the variable s is not defined and is used by the attribute [size_is].
MIDL2059: attribute expression must be of integral type, no support for 64-bit expressions
The specified attribute variable or expression must be an integral type. This error occurs when the attribute-expression type does not resolve to an integer.
MIDL2060: [byte_count] requires /ms_ext
The [byte_count] attribute is a Microsoft extension to DCE IDL. To use this attribute you cannot compile with the /osf switch, which overrides the MIDL compiler–default switches–/ms_ext and /c_ext.
MIDL2061: [byte_count] can be applied only to out parameters of pointer type
The [byte_count] attribute can only be applied to [out] parameters, and all [out] parameters must be pointer types.
MIDL2062: [byte_count] cannot be specified on a pointer to a conformant array or structure
The [byte_count] attribute cannot be applied to a conformant array or structure.
MIDL2063: parameter specifying the byte count is not [in] only or byte count parameter is not [out] only
The value associated with the [byte_count] must be transmitted from the client to the server; it must be an [in] parameter. The [byte_count] parameter does not need to be an [in, out] parameter.
MIDL2064: parameter specifying the byte count is not an integral type
The value associated with the byte count must be the integer type int, small, short, or long.
MIDL2065: [byte_count] cannot be specified on a parameter with size attributes
The [byte_count] attribute cannot be used with other size attributes such as [size_is] or [length_is].
MIDL2066: [case] expression is not constant
The expression specified for the case label is not a constant.
MIDL2067: [case] expression is not of integral type
The expression specified for the case label is not an integer type.
MIDL2068: specifying [context_handle] on a type other than void * requires /ms_ext
For DCE-RPC compatibility, the context handle must be a pointer of type void *. If you want the context handles to be associated with types other than void *, do not use the MIDL compiler switch /osf, which overrides the MIDL compiler default switch /ms_ext.
MIDL2069: cannot specify more than one parameter with each of comm_status/fault_status
A procedure can have only one parameter with the [comm_status] attribute. It can have at most one parameter with the [fault_status] attribute.
MIDL2070: comm_status/fault_status parameter must be an [out] only pointer parameter
The error-code types [comm_status] and [fault_status] are transmitted from server to client and therefore must be specified as an [out] parameter. Due to the constraints in the C-programming language, all [out] parameters must be pointers.
MIDL2071: endpoint syntax error
The endpoint syntax is incorrect.
MIDL2072: inapplicable attribute
The specified attribute cannot be applied in this construct. For example, the string attribute applies to char arrays or char pointers and cannot be applied to a structure that consists of two short integers:
typedef [string] struct moo
{
    short x;
    short y;
};
MIDL2073: [allocate] requires /ms_ext
The allocate attribute represents a Microsoft extension that is not defined as part of DCE RPC. To use this attribute, you cannot compile with the /osf switch, which overrides the MIDL compiler default switch /ms_ext
MIDL2074: invalid [allocate] mode
An invalid mode for the [allocate] attribute construct has been specified. The four valid modes are single_node, all_nodes, on_null, and always.
MIDL2075: length attributes cannot be applied with string attribute
When the string attribute is used, the generated stub files call the strlen function to determine the string length. Don't use the length attribute and the string attribute for the same variable.
MIDL2076: [last_is] and [length_is] cannot be specified at the same time
Both [last_is] and [length_is] have been specified for the same array. These attributes are related as follows: length = last – first + 1. Because each value can be derived from the other, don't specify both.
MIDL2077: [max_is] and [size_is] cannot be specified at the same time
Both [max_is] and [size_is] have been specified for the same array. These attributes are related as follows: max = size + 1. Because each value can be derived from the other, don't specify both.
MIDL2078: no [switch_is] attribute specified at use of union
No discriminant has been specified for the union. The [switch_is] attribute indicates the discriminant used to select among the union fields.
MIDL2079: no [uuid] specified
No UUID has been specified for the interface.
MIDL2080: [uuid] ignored on [local] interface
Using the [local] attribute on an object interface causes the MIDL compiler to ignore the [uuid] attribute. You cannot use both attributes on an RPC interface.
MIDL2081: type mismatch between length and size attribute expressions
The length and size attribute expressions must be of the same types. For example, this warning is issued when the attribute variable for the [size_is] expression is of type unsigned long and the attribute variable for the [length_is] expression is of type long.
MIDL2082: [string] attribute must be specified "byte," "char," or "wchar_t" array or pointer
A string attribute cannot be applied to a pointer or array whose base type is not a byte, char, or struct in which the members are all of the byte or char type.
MIDL2083: mismatch between the type of the [switch_is] expression and the switch type of the union
If the union [switch_type] is not specified, the switch type is the same type as the [switch_is] field.
MIDL2084: [transmit_as] must not be applied to a type that derives from a context handle
Context handles cannot be transmitted as other types.
MIDL2085: [transmit_as] must specify a transmissible type
The specified [transmit_as] type derives from a type that cannot be transmitted by Microsoft RPC, such as void, void *, or int. Use a defined RPC base type; in the case of int, add size specifiers like small, short, or long to qualify the int.
MIDL2086: transmitted type for [transmit_as] and [represent_as] must not be a pointer or derive from a pointer
The transmitted type cannot be a pointer or derive from a pointer.
MIDL2087: presented type for [transmit_as] and [represent_as] must not derive from a conformant/varying array, its pointer equivalent, or a conformant/varying structure
The type to which [transmit_as] has been applied cannot derive from a conformant array or structure (an array or structure whose size is determined at run time).
MIDL2088: [uuid] format is incorrect
The UUID format does not conform to specification. The UUID must be a string that consists of five sequences of hexadecimal digits of length 8, 4, 4, 4, and 12 digits. "12345678-1234-ABCD-EF01-28A49C28F17D" is a valid UUID. Use the function UuidCreate or a utility to generate a valid UUID.
MIDL2089: uuid is not a hexidecimal number
The UUID specified for the interface contains characters that are invalid in a hexadecimal number representation. The characters 0 through 9 and A through F are valid in a hexadecimal representation.
MIDL2090: optional parameters must come after required parameters
For a description of the ordering of parameter lists, see [optional] in the MIDL Language Reference.
MIDL2091: [dllname] required when [entry] is used
If you are specifying an entry point into a DLL you must also specify the name of that DLL by using the [dllname] attribute.
MIDL2092: [bindable] is invalid without [propget], [propput], or [propputref]
The [bindable] attribute is valid only on a property, therefore you must also specify one of the property-accessing or property-setting functions.
MIDL2093: procedures with [propput] or [propputref] must have at least one parameter
A [propput] or [propputref] procedure must have at least an [in] parameter with the property to set; a [propget] procedure must have at least an [out, retval] parameter to receive the property or reference.
MIDL2094: [id] attribute is required
This member function, because of the dispinterface syntax used, requires a DISPID, which you specify by using the [id] attribute. When you specify a dispinterface by using properties and methods you must specify a DISPID for every property and method.
MIDL2095: interface name specified in the ACF does not match that specified in the IDL file
In the current compiler mode, the name that follows the interface keyword in the ACF must be the same as the name that follows the interface keyword in the IDL file. The interface names in the IDL and ACF files can be different when you compile with the MIDL compiler switch /acf.
MIDL2096: duplicated attribute
Duplicate or conflicting attributes have been specified. This error often occurs when two attributes are mutually exclusive. For example, the attributes [code] and [nocode] cannot be used at the same time.
MIDL2097: parameter with [comm_status] or [fault_status] attribute must be a pointer to type error_status_t
When [fault_status] or [comm_status] is used as a parameter attribute, the parameter must be an [out] parameter of type error_status_t. If a server error occurs, the parameter is set to the error code. When the remote call is successfully completed, the procedure sets the value.
MIDL2098: a [local] procedure cannot be specified in ACF file
A local procedure has been specified in the ACF. The local procedure can only be specified in the IDL file.
MIDL2099: specified type is not defined as a handle
The type specified in the [implicit_handle] attribute is not defined as a handle type. Change the type definition or the type name specified by the attribute.
MIDL2100: procedure undefined
An attribute has been applied to a procedure in the ACF, and that procedure is not defined in the IDL file.
MIDL2101: this parameter does not exist in the IDL file
A parameter specified in the ACF does not exist in the definition in the IDL file. All parameters, functions, and type definitions that appear in the ACF must correspond to parameters, functions, and types previously defined in the IDL file.
MIDL2102: this array-bounds construct is not supported
MIDL currently supports expressing the upper and lower bounds of an array inthe form Array[Lower .. Upper] only when the constant that specifies the lower bound of the array resolves to the value zero.
MIDL2103: array bound specification is illegal
The user specification of array bounds for the fixed-size array is illegal. For example:
typedef short Array[-1]
MIDL2104: pointer to a conformant array or an array that contains a conformant array is not supported
Illegal conformant array usage. For rules governing conformant arrays, see Arrays and RPC.
MIDL2105: pointee/array does not derive any size
A conformant array has been specified without any size specification. You can specify the size with the [max_is] or [size_is] attribute.
MIDL2106: only fixed arrays and SAFEARRAYs are legal in a type library
You have used an array type inside a library statement that cannot be used in a type library.
MIDL2107: SAFEARRAYs are only legal inside a library block
The MIDL compiler does not recognize a SAFEARRAY as a valid data type except when generating a type library.
MIDL2108: badly formed character constant
The end-of-line character is not allowed in character constants.
MIDL2109: end of file found in comment
The end-of-file character has been encountered in a comment.
MIDL2110: end of file found in string
The end-of-file character has been encountered in a string.
MIDL2111: identifier length exceeds 31 characters
Identifiers are limited to 31 alphanumeric characters. Identifier names longer than 31 characters are truncated.
MIDL2112: end of line found in string
The end-of-line character has been encountered in the string. Verify that you have included the double-quote character that terminates the string.
MIDL2113: string constant exceeds limit of 255 characters
The string exceeded the maximum allowable length of 255 characters.
MIDL2114: identifier exceeds limit of 255 characters and has been truncated
The identifier exceeded the maximum allowable length of 255 characters. Excess characters in the identifier are truncated.
MIDL2115: constant too big
The constant is too large to be represented internally.
MIDL2116: numerical parsing error
The compiler could not parse the numerical identifier.
MIDL2117: error in opening file
The operating system reported an error while trying to open an output file. This error can be caused by a name that is too long for the file system or by a duplicate filename.
MIDL2118: error binding to function
MIDL2119: error initializing OLE
MIDL2120: error loading library
MIDL2121: [out] only parameter must not derive from a top-level [unique] or [ptr] pointer/array
A unique pointer cannot be an [out]-only parameter. By definition, a unique pointer can change from NULL to non-NULL. No information about the [out]-only parameter is passed from client to server.
MIDL2122: attribute is not applicable to this non-rpcable union
Only the [switch_is] and [switch_type] attributes apply to a union that is transmitted as part of a remote procedure call.
MIDL2123: expression used for a size attribute must not derive from an [out]-only parameter
The value of an [out]-only parameter is not transmitted to the server and cannot be used to determine the length or size of the [in] parameter.
MIDL2124: expression used for a length attribute for an [in] parameter cannot derive from an [out]-only parameter
The value of an [out]-only parameter is not transmitted to the server and cannot be used to determine the length or size of the [in] parameter.
MIDL2125: use of "int" needs /c_ext
MIDL is a strongly typed language. All parameters transmitted over the network must be derived from one of the MIDL base types. The type int is not defined as part of MIDL. Transmitted data must include a size specifier: small, short, or long. Data that is not transmitted over the network can be included in an interface; use the /c_ext switch.
MIDL2126: struct/union field must not be "void"
Fields in a structure or union must be declared to be of a specific base type supported by MIDL or a type that is derived from the base types. Void types are not allowed in remote operations.
MIDL2127: array element must not be void
An array element cannot be void.
MIDL2128: use of type qualifiers and/or modifiers needs /c_ext
Type modifiers such as _cdecl and _far can be compiled only if you specify the /c_ext switch.
MIDL2129: struct/union field must not derive from a function
The fields of a structure or union must be MIDL base types or types that are derived from these base types. Functions are not legal in structure or union fields.
MIDL2130: array element must not be a function
An array element cannot be a function.
MIDL2131: parameter must not be a function
The parameter to a remote procedure must be a variable of a specified type. A function cannot be a parameter to the remote procedure.
MIDL2132: struct/union with bit fields needs /c_ext
You must specify the MIDL compiler switch /c_ext to allow bit fields in structures that are not transmitted in a remote procedure call.
MIDL2133: bit field specification on a type other that "int" is a non-ANSI-compatible extension
The ANSI C programming language specification does not allow bit fields to be applied to noninteger types.
MIDL2134: bit field specification can be applied only to simple, integral types
The ANSI C programming language specification does not allow bit fields to be applied to noninteger types.
MIDL2135: struct/union field must not derive from handle_t or a context-handle
Context handles cannot be transmitted as part of another structure. They must be transmitted as context handles.
MIDL2136: array element must not derive from handle_t or a context handle
Context handles cannot be transmitted as part of an array.
MIDL2137: this specification of union needs /c_ext
A union that appears in the interface definition must be associated with the discriminant or declared as local. Data that is not transmitted over the network can be implicitly declared as local when you use the /c_ext switch, which is the MIDL default. You cannot compile this IDL with the /osf switch.
MIDL2138: parameter deriving from an "int" must have size specifier "small," "short," or "long" with the "int"
The type int is only a valid MIDL type on 32-bit platforms, on 16-bit systems int must be accompanied by a size specification. Use one of the size specifiers small, short, or long.
MIDL2139: type of the parameter cannot derive from void or void*
MIDL is a strongly typed language. All parameters transmitted over the network must be derived from one of the MIDL base types. MIDL does not support void as a base type. You must change the declaration to a valid MIDL type.
MIDL2140: parameter deriving from a struct/union containing bit fields is not supported
Bit fields are not defined as a valid data type by DCE RPC.
MIDL2141: use of a parameter deriving from a type containing type-modifiers/type-qualifiers needs /c_ext
The use of keywords such as far, near, const, and volatile in the IDL file is a Microsoft extension to DCE RPC. These keywords are not available when you compile with the /osf switch, which turns off the default /c_ext extension switch.
MIDL2142: parameter must not derive from a pointer to a function
The RPC run-time libraries transmit a pointer and its associated data between client and server. Pointers to functions cannot be transmitted as parameters because the function cannot be transmitted over the network.
MIDL2143: parameter must not derive from a nonrpc–capable union
The union must be associated with a discriminant. Use the [switch_is] and [switch_type] attributes.
MIDL2144: return type derives from an "int." You must use size specifiers with the "int"
On 16-bit systems, the type int is not a valid MIDL type unless it is accompanied by a size specification. Use one of the size specifiers small, short, or long.
MIDL2145: return type must not derive from a void pointer
MIDL is a strongly typed language. All parameters transmitted over the network must be derived from one of the MIDL base types. Void types are not defined as part of MIDL. You must change the declaration to a valid MIDL type.
MIDL2146: return type must not derive from a structure/union containing bit-fields
Bit fields are not defined as a valid data type by DCE RPC.
MIDL2147: return type must not derive from a nonrpc–capable union
The union must be associated with a discriminant. Use the [switch_is] and [switch_type] attributes.
MIDL2148: return type must not derive from a pointer to a function
The RPC run-time libraries transmit a pointer and its associated data between client and server. Pointers to functions cannot be transmitted as parameters because RPC does not define a method to transmit the associated function over the network.
MIDL2149: compound initializers are not supported
DCE RPC supports simple initialization only. The structure or array cannot be initialized in the IDL file.
MIDL2150: ACF attributes in the IDL file need the /app_config switch
A Microsoft extension allows you to specify ACF attributes in the IDL file. Use the /app_config switch to activate this extension.
MIDL2151: single-line comment needs /ms_ext or /c_ext
Single-line comments that use two slash characters (//) represent a Microsoft extension to DCE RPC. You cannot use single-line comments if you are compiling with the /osf switch.
MIDL2152: [version] format is incorrect
The interface version number in the interface header must be specified in the format major.minor, where each number can range from 0 to 65535.
MIDL2153: "signed" needs /ms_ext or /c_ext
The use of the signed keyword is a Microsoft extension to DCE RPC. You cannot use the /osf switch if you want to use this feature.
MIDL2154: mismatch in assignment type
The type of the variable does not match the type of the value that is assigned to the variable.
MIDL2155: declaration must be of the form: const <type><declarator> = <initializing expression>
The declaration is not compatible with DCE RPC syntax. Use the /ms_ext or /c_ext MIDL compiler mode switch.
MIDL2156: declaration must have "const"
Declarations in the IDL file must be constant expressions that use the keyword const, for example:
const short x = 2;
MIDL2157: struct/union/enum must not be defined in a parameter-type specification
The structure, union, or enumerated type must be explicitly stated outside of the function prototype.
MIDL2158: [allocate] attribute must be applied only on non-void pointer types
The [allocate] attribute is designed for complex pointer-based data structures. When the [allocate] attribute is specified, the stub file traverses the data structure to compute the total size of all objects accessible from the pointer and all other pointers in the data structure. Change the type to a nonvoid pointer type or remove the [allocate] attribute and use another method to determine its allocation size, such as the sizeof operator.
MIDL2159: array or equivalent pointer construct cannot derive from a nonencapsulated union
Each union must be associated with a discriminant. Arrays of unions are not permitted because they do not provide the associated discriminant. Arrays of structures in which the structure packages the union and its discriminant are permitted because the stubs can use the discriminant to determine the size of each union.
MIDL2160: field must not derive from an error_status_t type
The error_status_t type can only be used as a parameter or a return type. It cannot be embedded in the field of a structure or union.
MIDL2161: union has at least one arm without a case label
The union declaration does not match the required MIDL syntax for the union. Each union arm requires a case label or default label that selects that union arm.
MIDL2162: parameter or return value must not derive from a type that has [ignore] applied to it
The [ignore] attribute is a field attribute that can be applied only to fields, such as fields of structures and arrays. The [ignore] attribute indicates that the stub should not dereference the pointer during transmission and is not allowed when it conflicts with other attributes that must be dereferenced, such as [out] parameters and function return values.
MIDL2163: pointer already has a pointer attribute applied to it
Only one of the pointer attributes, [ref], [unique], or [ptr], can be applied to a single pointer.
MIDL2164: field/parameter must not derive from a structure that is recursive through a ref pointer
By definition, a reference pointer cannot be set to NULL. A recursive data structure defined with a reference pointer has no NULL elements and by convention is nonterminating. Use a [unique] pointer attribute to allow the data structure to specify a NULL element, or redefine the data structure as a nonrecursive data structure.
MIDL2165: use of field deriving from a void pointer needs /c_ext
The type void * and other types and type qualifiers that are not supported by DCE IDL are allowed in the IDL file only when you use the MIDL default compiler settings. Using the /osf switch overrides this default. If you must compile in osf-compatibility mode, you will need to redefine the pointer type
MIDL2166: use of this attribute needs /ms_ext
This language feature is a Microsoft extension to DCE IDL. You cannot use this feature if you are compiling in osf-compatibility mode ( /osf ).
MIDL2167: this attribute only allowed with new format type libraries
To use this attribute, you need the version of Oleaut32.dll provided with Microsoft® Windows NT® 4.0, Window 2000, or later.
MIDL2168: use of wchar_t needs /ms_ext or /c_ext
The wide-character type represents an extension to DCE IDL. The MIDL compiler does not accept the wide-character type when you specify the /osf switch.
MIDL2169: unnamed fields need /ms_ext or /c_ext
DCE IDL does not support the use of unnamed structures or unions embedded in other structures or unions. In DCE IDL, all such embedded fields must be named. The MIDL compiler does not allow their use when you specify the /osf switch.
MIDL2170: unnamed fields can derive only from struct/union types
The Microsoft extension to the DCE IDL that supports unnamed fields applies only to structures and unions. You must assign a name to the field or redefine the field to comply with this restriction.
MIDL2171: field of a union cannot derive from a conformant/varying array or its pointer equivalent
The conformant array cannot appear alone in the union but must be accompanied by the value that specifies the size of the array. Instead of using the array as the union arm, use a structure that consists of the conformant array and the identifier that specifies its size.
MIDL2172: no [pointer_default] attribute specified, assuming [ptr] for all unattributed pointers in interface
The DCE IDL implementation specifies that all pointers in each IDL file must be associated with pointer attributes. When an explicit pointer attribute is not assigned to the parameter or pointer type and no [pointer_default] attribute is specified in the IDL file, the full pointer attribute ptr is associated with the pointer. You can change the pointer attributes by using explicit pointer attributes, by specifying a [pointer_default] attribute, or by specifying the /ms_ext switch to change the default for unattributed pointers to [unique].
MIDL2173: initializing expression must resolve to a constant expression
If an expression is used as an initializer, the expression must be a constant expression. This is true in all MIDL compiler modes. The expression must be resolvable at compile time. Specify a literal constant or an expression that resolves to a constant, rather than a variable.
MIDL2174: attribute expression must be of type integer, char, Boolean or enum
The specified type does not resolve to a valid switch type. Use an integer, character, byte, Boolean, or enum type, or a type that is derived from one of these types.
MIDL2175: illegal constant
The specified constant is out of the valid range for the specified type.
MIDL2176: attribute not implemented; ignored
The attribute specified is not implemented in this release of Microsoft RPC. The MIDL compiler continues processing the IDL file as if the attribute were not present.
MIDL2177: return type must not derive from a [ref] pointer
Function return values that are defined to be pointer types must be specified as [unique] or full pointers. You cannot use reference pointers.
MIDL2178: attribute expression must be a variable name or a pointer dereference expression in this mode. You must specify the /ms_ext switch
The DCE IDL compiler requires the size associated with the [size_is] attribute to be specified by a variable or pointer variable. If you want to take advantage of the Microsoft extension that allows the [size_is] attribute to be defined by a constant expression, you cannot use the /osf compiler switch.
MIDL2179: parameter must not derive from a recursive nonencapsulated union
A union must include a discriminant, so a union cannot have another union as an element. A union can be embedded in another union only when it is part of a structure that includes the discriminant.
MIDL2180: binding-handle parameter cannot be [out] only
The handle parameter identified by the MIDL compiler as the binding handle for this operation must be an [in] parameter. [out]-only parameters are undefined on the client stub, and the binding handle must be defined on the client.
MIDL2181: pointer to a handle cannot be [unique] or [ptr]
You cannot use the unique and full pointer attributes for a pointer to a handle. These attributes allow the value NULL, and the binding handle cannot be NULL. Use the [ref] attribute to derive the binding-handle parameter from reference pointers.
MIDL2182: parameter that is not a binding handle must not derive from handle_t
The primitive handle type handle_t is not a valid data type that is transmitted over the network. Change the parameter type to a type other than handle_t, or remove the parameter.
MIDL2183: unexpected end of file found
The MIDL compiler found the end of the file before it was able to successfully resolve all syntactical elements of the file. Verify that the terminating right-brace character (}) is present at the end of the file, or check the syntax.
MIDL2184: type deriving from handle_t must not have [transmit_as] applied to it
The primitive handle type handle_t is not transmitted over the network.
MIDL2185: [context_handle] must not be applied to a type that has [handle] applied to it
The [context_handle] and [handle] attributes cannot be applied to the same type.
MIDL2186: [handle] must not be specified on a type deriving from void or void *
A type specified with the [handle] attribute can be transmitted over the network, but the type void * is not a transmissible type. The handle type must resolve to a type that derives from the transmissible base types.
MIDL2187: parameter must have either [in], [out] or [in,out] in this mode. You must specify /ms_ext or /c_ext
The DCE IDL compiler requires all parameters to have explicit directional parameters. To use the Microsoft extensions to DCE IDL, you cannot use the /osf switch, which overrides /ms_ext and /c_ext.
MIDL2188: transmitted type may not derive from "void" for [transmit_as], [represent_as], [wire_marshal], [user_marshal].
The [transmit_as] attribute applies only to pointer types. Use the type void * in place of void.
MIDL2189: "void" must be specified on the first and only parameter specification
The keyword void incorrectly appears with other function parameters. To specify a function without parameters, the keyword void must be the only element of the parameter list, as in the following example:
void Moo(void)
MIDL2190: [switch_is] must be specified only on a type deriving from a nonencapsulated union
The [switch_is] keyword is incorrectly applied. It can only be used with nonencapsulated union types.
MIDL2191: stringable structures are not implemented in this version
DCE IDL allows the attribute [string] to apply to a structure whose elements consist only of characters, bytes, or types that resolve to characters or bytes. This functionality is not supported in Microsoft RPC. The [string] attribute cannot be applied to the structure as a whole. However, it can be applied to each individual array.
MIDL2192: switch type can only be integral, char, Boolean or enum
The specified type does not resolve to a valid switch type. Use an integer, character, byte, Boolean, enum type, or a type that is derived from one of these types.
MIDL2193: [handle] must not be specified on a type deriving from handle_t
A handle type must be defined using one and only one of the handle types or attributes. Use the primitive type handle_t or the attribute [handle], but not both. The user-defined handle type must be transmissible, but the handle_t type is not transmitted on the network.
MIDL2194: parameter deriving from handle_t must not be an [out] parameter
A handle of the primitive type handle_t is meaningful only to the side of the application in which it is defined. The type handle_t is not transmitted on the network.
MIDL2195: attribute expression derives from [unique] or [ptr] pointer dereference
Although the [unique] and full pointer attributes allow pointers to have NULL values, the expression that defines the size or length attribute must never have a NULL value. When pointers are used, MIDL constrains expressions to [ref] pointers.
MIDL2196: "cpp_quote" requires /ms_ext
The cpp_quote attribute is a Microsoft extension to DCE IDL. Do not use the MIDL compiler switch /osf, which overrides /ms_ext.
MIDL2197: quoted uuid requires /ms_ext
The ability to specify a UUID value within quotation marks is a Microsoft extension to DCE IDL. Do not use the MIDL compiler switch /osf, which overrides /ms_ext.
MIDL2198: return type cannot derive from a nonencapsulated union
The nonencapsulated union cannot be used as a function return type. To return the union type, specify the union type as an [out] or [in, out] parameter.
MIDL2199: return type cannot derive from a conformant structure
The size of the return type must be a constant. You cannot specify as a return type a structure that contains a conformant array even when the structure also includes its size specifier. To return the conformant structure, specify the structure as an [out] or [in, out] parameter.
MIDL2200: [transmit_as] must not be applied to a type deriving from a generic handle
In this release, the [handle] and [transmit_as] attributes cannot be combined on the same type.
MIDL2201: [handle] must not be applied to a type that has [transmit_as] applied to it
In this release, the [handle] and [transmit_as] attributes cannot be combined on the same type.
MIDL2202: type specified for the const declaration is invalid
Const declarations are limited to integer, character, wide-character, string, and Boolean types.
MIDL2203: operand to the sizeof operator is not supported
The MIDL compiler supports the sizeof operation for simple types only. The specified operand does not evaluate to an integer type.
MIDL2204: this name already used as a const identifier name
The identifier has previously been used to identify a constant in a const declaration. Change the name of one of the identifiers so that the identifiers are unique.
MIDL2205: inconsistent redefinition of type error_status_t
The type error_status_t must resolve to the type unsigned long. Other type definitions cannot be used.
MIDL2206: [case] value out of range of switch type
The value associated with the switch statement case is out of range for the specified switch type. For example, this error occurs when a long integer value is used in the case statement for a short integer type.
MIDL2207: parameter deriving from wchar_t needs /ms_ext
The wide-character type wchar_t is a Microsoft extension to DCE IDL. Do not use the MIDL compiler switch /osf, which overrides /ms_ext
MIDL2208: this interface has only callbacks
Callbacks are valid only in the context of a remote procedure call. The interface must include at least one function prototype for a remote procedure call that does not include the [callback] attribute.
MIDL2209: redundantly specified attribute; ignored
The specified attribute has been applied more than once. Multiple instances of the same attribute are ignored.
MIDL2210: context handle type used for an implicit handle
A type that was defined using the [context_handle] attribute has been specified as the handle type in an [implicit_handle ] attribute. The attributes cannot be combined in this way.
MIDL2211: conflicting options specified for [allocate]
The options specified for the ACF attribute [allocate] represent conflicting directives. For example, specify either the option all_nodes or the option single_node, but not both.
MIDL2212: error while writing to file
An error occurred while writing to the file. This condition can be caused by errors relating to disk space, file handles, file-access restrictions, and hardware failures.
MIDL2213: no switch type found at definition of union, using the [switch_is] type
The union definition does not include an explicit [switch_type] attribute. The type of the variable specified by the [switch_is] attribute is used as the switch type.
MIDL2214: semantic check incomplete due to previous errors
The MIDL compiler makes two passes over the input file(s) to resolve any forward declarations. Due to errors encountered during the first pass, checking for the second pass has not been performed. Unreported errors relating to forward declarations may still be present in the file.
MIDL2215: handle parameter or return type is not supported on a [callback] procedure
A [callback] procedure occurs in the context of a call from a client to the server and uses the same binding handle as the original call. Explicit binding-handle parameters or return types are not permitted in callback functions.
MIDL2216: [ptr] does not support aliasing in this version
An alias occurs when data is accessible through more than one pointer or variable name. Remove the alias. For more information, see Unique Pointers.
MIDL2217: parameter already defined as a context handle
The parameter was previously defined as a context handle.
MIDL2218: [context_handle] must not derive from handle_t
The three handle characteristics: the type handle_t, the attribute [handle], and the attribute [context_handle], are mutually exclusive. Only one characteristic can be applied to a type or parameter at a time.
MIDL2219: array size exceeds 65536 bytes
On some Microsoft platforms, the maximum transmissible data size is 64K. Redesign your application so that all transmitted data fits within the maximum transmissible size.
MIDL2220: structure size exceeds 65536 bytes
On some Microsoft platforms, the maximum transmissible data size is 64K. Redesign your application so that all transmitted data fits within the maximum transmissible size.
MIDL2221: field of a nonencapsulated union cannot be another nonencapsulated union
Unions that are transmitted as part of a remote procedure call require an associated data item, the discriminant, that selects the union arm. Unions nested in other unions do not offer a discriminant; as a result, they cannot be transmitted in this form. Create a structure that consists of the union and its discriminant.
MIDL2222: pointer attribute(s) applied on an embedded array; ignored
A pointer attribute can be applied to an array only when the array is a top-level parameter. Other pointer attributes applied to arrays embedded in other data structures are ignored.
MIDL2223: [allocate] is illegal on either the transmitted or presented type for [transmit_as], [represent_as], [wire_marshal], or [user_marshal].
The [transmit_as] and [allocate] attributes cannot both be applied to the same type. The [transmit_as] attribute distinguishes between presented and transmitted types, while the [allocate] attribute assumes that the presented type is the same as the transmitted type.
MIDL2224: [switch_type] must be specified in this import mode
...
MIDL2225: [implicit_handle] type undefined; assuming generic handle
The handle type specified in the ACF is not defined in the IDL file. The MIDL compiler assumes that the handle type resolves to the primitive handle type handle_t. Add the [handle] attribute to the type definition if you want the handle to behave like a user-defined or generic handle.
MIDL2226: array element must not derive from error_status_t
In this release of Microsoft RPC, the type error_status_t can appear only as a parameter or return type. It cannot appear in arrays.
MIDL2227: [allocate] illegal on a type deriving from a primitive/generic/context handle
By design, the ACF attribute [allocate] cannot be applied to handle types.
MIDL2228: transmitted or presented type must not derive from error_status_t
In this release of Microsoft RPC, the type error_status_t cannot be used with the [transmit_as] attribute.
MIDL2229: discriminant of a union must not derive from a field with [ignore] applied to it
A union used in a remote procedure call must be associated with another data item, called the discriminant, that selects the union arm. The discriminant must be transmitted. The [ignore] attribute cannot be applied to the union discriminant.
MIDL2230: [nocode] ignored for server side since "/server none" not specified
Some DCE IDL compilers generate an error when the [nocode] attribute is applied to a procedure in an interface for which server stub files are being generated. Because the server must support all operations, [nocode] must not be applied to a procedure in this mode, or you must use the MIDL compiler switch /server none to explicitly specify that no server routines are to be generated.
MIDL2231: no remote procedures specified in non-[local] interface; no client/server stubs will be generated
The provided interface does not have any remote procedures, so only header files will be generated.
MIDL2232: too many default cases specified for encapsulated union
An encapsulated union can have only one default: arm.
MIDL2233: too many default interfaces specified for coclass
A coclass can have at most two [default] members, one to represent the outgoing (source) interface or dispinterface, and one to represent the incoming (sink) interface or dispinterface.
MIDL2234: items with [defaultvtable] must also have [source]
The defaultvtable interface creates a second source interface for an object, one that lets sinks receive events through the V-table.
MIDL2235: union specification with no fields is illegal
Unions must have at least one field.
MIDL2236: value out of range
The provided case value is out of the range of the switch type.
MIDL2237: [context_handle] must be applied on a pointer type
Context handles must always be pointer types. DCE specifies that all context handles must be typed as void *.
MIDL2238: return type must not derive from handle_t
Handle_t cannot be returned.
MIDL2239: [handle] must not be applied to a type deriving from a context handle
A type cannot be both a context handle and a generic handle.
MIDL2240: field deriving from an "int" must have size specifier "small", "short", or "long" with the "int"
The type int is not transmissible on 16-bit systems, since the size of int may be different across machines.
MIDL2241: field must not derive from a void or void *
Void and void * cannot be used as parameter types for remote procedures.
MIDL2242: field must not derive from a structure containing bit-fields
Structures containing bit fields cannot be used as parameters or return types for remote procedures.
MIDL2243: field must not derive from a non-rpcable union
A union must be specified as a nonencapsulated union or encapsulated union in order to be transmitted. Ordinary C unions lack the discriminant needed to transmit the union across the network.
MIDL2244: field must not derive from a pointer to a function
Pointers to functions cannot be transmitted to remote procedures. Pointers to functions point to function code, and no function code can be transmitted across the network using RPC.
MIDL2245: cannot use [fault_status] on both a parameter and a return type
The attribute [fault_status] can be used only once per procedure. The [comm_status] attribute can be used independently.
MIDL2246: return type too complicated for /Oi modes, using /Os
Large return types that are passed by value can be handled only by /Os optimization stubs. The stubs for this routine will be generated using /Os optimization.
MIDL2247: generic handle type too large for /Oi modes, using /Os
Large generic handle types that are passed by value can be handled only by /Os optimization stubs. The stubs for this routine will be generated using /Os optimization.
MIDL2248: [allocate(all_nodes)] on an [in,out] parameter may orphan the original memory
Use of [allocate(all_nodes)] on an [in, out] parameter must reallocate contiguous memory for the [out] direction, thus orphaning the [in] parameter. This usage is not recommended.
MIDL2249: cannot have a [ref] pointer as a union arm
Reference pointers must always point to valid memory, but an [in,out] union with a reference pointer may return a reference pointer when the [in] direction used another type.
MIDL2250: return of context handles not supported for /Oi modes, using /Os
MIDL does not support context handles in the fully interpreted optimization modes. Switching to mixed-mode optimization.
MIDL2251: use of the extra [comm_status] or [fault_status] parameter not supported for /Oi modes, using /Os
The [comm_status] and [fault_status] attributes can be handled only by /Os optimization stubs. The stubs for this routine will be generated using /Os optimization.
MIDL2252: use of an unknown type for [represent_as] or [user_marshal] not supported for /Oi modes, using /Os
Use of the [represent_as] attribute with a local type that is not defined in the IDL file or an imported IDL file can be handled only by /Os optimization stubs. The stubs for this routine will be generated using /Os optimization.
MIDL2253: array types with [transmit_as] or [represent_as] not supported on return type for /Oi modes , using /Os
Returning an array with [transmit_as] or [represent_as] applied can only be handled by /Os optimization stubs. The stubs for this routine will be generated using /Os optimization.
MIDL2254: array types with [transmit_as] or [represent_as] not supported pass-by-value for /Oi modes, using /Os
This action is not supported for fully-interpreted optimization. Switching to mixed-mode optimization.
MIDL2255: [callback] requires /ms_ext
The [callback] attribute is a Microsoft extension and requires that the /ms_ext switch be enabled. Do not compile with /osf, which overrides /ms_ext.
MIDL2256: circular interface dependency
This interface uses itself (directly or indirectly) as a base interface.
MIDL2257: only IUnknown may be used as the root interface
Currently, all interfaces must have IUnknown as the root interface.
MIDL2258: [IID_IS] may only be applied to pointers to interfaces
The [iid_is] attribute can only be applied to interface pointers, although they can be specified as pointers to IUnknown *.
MIDL2259: interfaces may only be used in pointer-to-interface constructs
Interface names cannot be used except as base interfaces or interface pointers.
MIDL2260: interface pointers must have a UUID/IID
The base type of the [iid_is] expression must be a UUID/GUID/IID type.
MIDL2261: definitions and declarations outside of interface body requires /ms_ext
Putting declarations and definitions outside of any interface body is a Microsoft extension and requires the use of the /ms_ext switch.
MIDL2262: multiple interfaces in one file requires /ms_ext
Using multiple interfaces in a single idl file is a Microsoft extension and is not available when you compile in /osf mode.
MIDL2263: only one of [implicit_handle], [auto_handle], or [explicit_handle] allowed
Each interface can have only one of these three attributes.
MIDL2264: [implicit_handle] references a type which is not a handle
Implicit handles must be of one of the handle types.
MIDL2265: [object] procs may only be used with "/env win32"
Interfaces with the [object] attribute cannot be used with 16-bit environments.
MIDL2266: [callback] with -env dos/win16 not supported for /Oi, using /Os
Callbacks in 16-bit environments can be handled only by /Os optimization stubs. The stubs for this routine will be generated using /Os optimization.
MIDL2267: float/double not supported as top-level parameter for /Oi mode, using /Os
The float and double types can only be handled as parameters by the /Os optimization stubs. The stubs for this routine will be generated using /Os optimization. The float and double types within structures, arrays, or unions can still be handled with /Oi.
MIDL2268: pointers to context handles may not be used as return values
Context handles must be used as direct return values, not indirect return values.
MIDL2269: procedures in an object interface must return an HRESULT
All procedures in an object interface that do not have the-[local] attribute must return an HRESULT/SCODE.
MIDL2270: duplicate UUID. Same as
UUIDs must be unique.
MIDL2271: [object] interfaces must derive from another [object] interface such as IUnknown
Interface inheritance is allowed only when you are using object interfaces.
MIDL2272: (async) interface must derive from another (async) interface
Object interfaces, both synchronous and asynchronous, must derive from IUnknown or some other base OLE interface.
MIDL2273: [IID_IS] expression must be a pointer to IID structure
The base type of the [iid_is] expression must be a UUID/GUID/IID type.
MIDL2274: [call_as] type must be a [local] procedure
The target of a [call_as] type, if defined, must have [local] applied.
MIDL2275: undefined [call_as] must not be used in an object interface
You must define the target of a [call_as] type. Make sure you have supplied call_as routines for both the calling and called applications.
MIDL2276: [auto_handle] may not be used with [encode] or [decode]
The [encode] and [decode] attributes can be used only with explicit handles or implicit handles.
MIDL2277: normal procedures are not allowed in an interface with [encode] or [decode]
Interfaces containing [encode] or [decode] procedures cannot also have remote procedures.
MIDL2278: top-level conformance or variance not allowed with [encode] or [decode]
Types that have top-level conformance or variance cannot use type serialization, since there is no way to provide sizing/lengthening. Structures containing them are, however, allowed to use type serialization.
MIDL2279: [out] parameters may not have "const"
Since an [out] parameter is altered, it must not be declared as a constant.
MIDL2280: return values may not have "const"
Since a function value is set when the function returns, this value must not be declared as a constant.
MIDL2281: invalid use of "retval" attribute
Check to make sure you have not used the [optional] attribute and that the [retval] parameter is the last parameter in the list.
MIDL2282: multiple calling conventions illegal
Only one calling convention can be applied to a single procedure.
MIDL2283: attribute illegal on [object] procedure
The above attribute only applies to procedures in interfaces that do not have the [object] attribute.
MIDL2284: [out] interface pointers must use double indirection
Since the altered value is the pointer to the interface, there must be another level of indirection above the pointer to allow it to be returned.
MIDL2285: procedure used twice as the caller in [call_as]
A given [local] procedure can be used only once as the target of a [call_as ], in order to avoid name clashes.
MIDL2286: [call_as] target must have [local] in an object interface
The target of a [call_as ] must be a defined [local] procedure in the current interface.
MIDL2287: [code] and [nocode] may not be used together
These two attributes are contradictory and cannot be used together.
MIDL2288: procedures with [maybe] or [message] attributes may not have [out] params, or return values must be of type HRESULT or error_status_t
Since [maybe] procedures never return, there is no way to get return values.
MIDL2289: pointer to function must be used
Although function-type definitions are allowed in /c_ext mode, they can only be used as pointers to functions. They can never be transmitted as a parameter or a return value of a remote procedure.
MIDL2290: functions may not be passed in an RPC operation
Functions and function pointers cannot be passed as parameters or return values of remote procedures.
MIDL2291: hyper/double not supported as return value for /Oi modes, using /Os
Hyper and double return values can be handled only by /Os optimization stubs. The stubs for this routine will be generated using /Os optimization.
MIDL2292: #pragma pack(pop) without matching #pragma pack(push)
#pragma pack(push) and #pragma pack(pop) must appear in matching pairs. At least one too many #pragma pack(push)s were specified.
MIDL2293: stringable structure fields must be byte/char/wchar_t
The type [string] can only be applied to a structure whose fields are all of type byte, or a type definition equivalent to byte.
MIDL2294: [notify] not supported for /Oi modes, using /Os
The [notify] attribute can be processed only by /Os optimization stubs.
MIDL2295: handle parameter or return type is not supported on a procedure in an [object] interface
Handles cannot be used with [object] interfaces.
MIDL2296: ANSI C only allows the leftmost array bound to be unspecified
In a conformant array, ANSI C allows only the leftmost (most significant) array bound to be unspecified. If multiple dimensions are conformant, MIDL will attempt to put a "1" in the other conformant dimensions. If the other dimensions are defined in a different type definition, this cannot be possible. Try putting all the array dimensions on the array declaration to avoid this. In any case, beware of the array-indexing calculations done by the compiler; you may need to do your own calculations using the actual sizes.
MIDL2297: by-value union parameters not supported for /Oi modes, using /Os
This action is not supported for fully-interpreted optimization. Switching to mixed-mode optimization.
MIDL2298: [version] attribute is ignored on an [object] interface
The [object] attribute identifies a COM interface. An interface attribute list for a COM interface cannot include the [version] attribute
MIDL2299: [size_is] or [max_is] attribute is invalid on a fixed array
Arrays of fixed size can't use the size_is or max_is attributes.
MIDL2300: [encode] or [decode] are invalid in an [object] interface
The [object] attribute identifies a COM interface. The [encode] and [decode] attributes enable serialization. That is, you can provide and control buffers for data marshal and unmarshal, however, you cannot perform serialization on COM interfaces.
MIDL2301: [encode] or [decode] on a type requires /ms_ext
Serialization is not part of the DCE-IDL specification. It is a Microsoft extension that requires the use of the /ms_ext command-line switch.
MIDL2302: int not supported on /env win16 or /env dos
The 16-bit Microsoft platforms do not support the use of the int type in an IDL file. Qualify the int type with small, short, or long.
MIDL2303: [bstring] may only be applied to a pointer to "char" or "whchar_t"
This error is obsolete. It is provided only for backward compatibility.
MIDL2304: attribute invalid on a procedure in an [object] interface
The specified attribute is not allowed on procedure in a COM interface.
MIDL2305: attribute invalid on an [object] interface
The specified attribute is not allowed in a COM interface.
MIDL2306: too many parameters or stack too big for /Oi modes, using /Os
This warning is obsolete. It is provided only for backward compatibility. It indicates that the call to the remote procedure causes the stack to grow larger than 64 K.
MIDL2307: no attributes on ACF file typedef, so no effect
IDL file should contain all of the typedef statements that do not have attributes. They should not occur in ACF files. If they do, the MIDL compiler interprets them as redundant and ignores them.
MIDL2308: calling conventions other than __stdcall or __cdecl not supported for /Oi modes, using /Os
Calling conventions such as __pascal or __fastcall change the format of the stack. The /Oi modes only support the __stdcall and __cdecl calling conventions. If you must use other calling conventions, use the /Os mode.
MIDL2309: Too many delegation methods in the interface, require Windows 2000 or greater
One interface can inherit from another. When it does, the methods of the base interface are considered delegated. No derived interface can contain more than 256 delegated methods.
MIDL2310: auto handles not supported with /env mac or /env powermac
When compiling your IDL file for a PowerMac, you cannot use automatic binding handles. You must specify explicit or implicit handles.
MIDL2311: statements outside library block are illegal in mktyplib compatibility mode
You may need to specify the /mktyplib203 command-line switch when you compile your IDL file.
MIDL2312: illegal syntax unless using mktyplib compatibility mode
You may need to specify the /mktyplib203 command-line switch when you compile your IDL file.
MIDL2313: illegal definition, must use typedef in mktyplib compatibility mode
You may need to specify the /mktyplib203 command-line switch when you compile your IDL file.
MIDL2314: explicit pointer attribute [ptr] [ref] ignored for interface pointers
Pointers to interfaces cannot have IDL attributes.
MIDL2315: /Oi modes not implemented for PowerMac, switching to /Os
MIDL2316: illegal expression type used in attribute
The default value for the pointer should be a constant.
MIDL2317: illegal type used in pipe
Pipes are limited to basic IDL data types. For example, you cannot specify a pipe of arrays.
MIDL2318: procedure uses pipes, using /Oicf
The mode you selected does not support pipes. The MIDL compiler detected the use of one or more pipes in your interface. Therefor, it is compiling your IDL file in /Oicf mode.
MIDL2319: procedure has an attribute that requires use of /Oif, switching modes
You must compile [async] procedures in /Oif mode.
MIDL2320: conflicting optimization requirements, cannot optimize
This error often indicates that you specified both /Os and /Oi (or a variant of /Oi) MIDL compiler modes. It can also mean that the features you specified in your IDL and ACL files require the use of both modes. You must select one mode or the other to optimize.
MIDL2321: pipes cannot be array elements, or members of structures or unions
Pipe data types can only be top-level parameters.
MIDL2322: invalid pipe usage
You cannot use pipes with the [transmit_as], [represent_as], or [user_marshal] attributes. In addition, pipes cannot be used as return types.
MIDL2323: feature requires the advanced interpreted optimization option; use -Oicf
This error indicates that MIDL compiler command-line switches such as /robust require the use of /Oicf mode.
MIDL2324: feature requires the advanced interpreted optimization option; use -Oicf
This warning indicates that MIDL compiler command-line switches such as /robust require the use of /Oicf mode.
MIDL2329: the optimization option is being phased out, use -Oic
The -Oi1 optimization mode was specified on the MIDL command line. This mode is no longer supported and -Oicf should be used instead.
MIDL2330: the optimization option is being phased out, use -Oicf
The Oi2 optimization mode was specified on the MIDL command line. This mode is no longer supported and -Oicf should be used instead.
MIDL2331: the optimization option is being phased out, use -ic
The i1 optimization mode was specified in an [optimize] ACF attribute. This mode is no longer supported and icf should be used intead.

Example ACF file:

[optimize("i1")] foo();    //MIDL 2331
MIDL2332: the optimization option is being phased out, use -icf
The i2 optimization mode was specified in an [optimize] ACF attribute. This mode is no longer supported and icf should be used instead.

Example ACF file:

[optimize("i2")] foo();    //MIDL 2332
MIDL2333: the -old and -new switches are obsolete, use -oldtlb and -newtlb
This message is obsolete and is no longer omitted by MIDL.
MIDL2334: illegal argument value
The allowed variants of the /O command-line switch include /Os, /Oi, /Oic, /Oicf, and /Oif.
MIDL2335: illegal expression type in constant
The expression does not evaluate to a constant.
MIDL2336: illegal expression type in enum
An enumerated value in an enum definition does not evaluate to an integral type.
MIDL2337: unsatisfied forward declaration
The MIDL compiler could not resolve the definition of a forward declaration.
MIDL2338: switches are contradictory
You cannot use both the /osf and /ms_ext command-line switches when you compile an IDL file. You must choose one or the other.
MIDL2339: MIDL cannot generate HOOKOLE information for the non-rpc-able union
This error is obsolete. It is provided strictly for backward compatibility.
MIDL2340: no case expression found for union
Each field of a union must have a case statement with a constant expression.
MIDL2341: [user_marshal] and [wire_marshal] not supported with -Oi and -Oic flags, use -Os or -Oicf
The [user_marshal] and [wire_marshal] attributes require the specific optimization features available only in /Oicf (codeless proxy with fast format strings)or /Os (mixed mode marshaling).
MIDL2342: pipes can't be used with data serialization, i.e. [encode] and/or [decode]
You cannot pass pipes as parameters to procedures that have the [encode] or [decode] attributes.
MIDL2343: all pipe interface pointers must use single indirection
You cannot use a pointer to a pointer to a pipe interface in this manner.
MIDL2344: [iid_is()] cannot be used with a pipe interface pointer
This message is obsolete. This message is no longer used by the compiler.
MIDL2345: invalid or inapplicable -lcid switch:
The local identifier (LCID) that you specified is not valid.
MIDL2346: the specified lcid is different from previous specification
The values specified in /lcid and [lcid] are different. The MIDL compiler will use the last one defined.
MIDL2347: importlib is not allowed outside of a library block
All [importlib] statements should occur in a [library] block.
MIDL2348: invalid floating point value
This error should not be emitted by MIDL. If you see this error please report a bug to Microsoft providing all files needed to reproduce the error, including your IDL files, ACF files, headers, etc.
MIDL2349: invalid member
Procedures cannot be members of a library.
MIDL2350: possible invalid member
To be a valid member of a library, the library element must be a module, a dispinterface, a coclass, an if statement, a structure, a union, an enumeration, or a forward declaration.
MIDL2351: mismatch in pipe and interface types
This message is obsolete.
MIDL2352: string, varying array, conformant array and full pointer parameters are incompatible with pipe parameters
Remote procedures that pass pipes as parameters cannot have parameters that are strings, varying arrays, conformant arrays, or full pointers.
MIDL2353: parameter must be in
Asynchronous handles must be [in] parameters.
MIDL2354: parameter type of an [async] object must be a double pointer to an interface
The parameter must be of type IAsyncManager **.
MIDL2355: incorrect async handle type
The handle type should be IAsyncManager or a type derived from IAsyncManager.
MIDL2356: the "internal" switch enables unsupported features, use with caution
Avoid using this switch.
MIDL2357: async procedures cannot use auto handle
Procedures with the [async] attribute require explicit handles.
MIDL2358: error_status_t should have both [comm_status] and [fault_status]
A procedure was specified with the IDL attributes [maybe] or [message] but the return type only has the ACF attributes [comm_status] or [fault_status]. Both ACF attributes are required.

Example ACF file:

[comm_status] foo();    //MIDL 2358
[fault_status] bar();    //MIDL 2358
[comm_status, fault_status] baz();    //OK
MIDL2359: this construct is only allowed within a library block
A module can occur only within a library block.
MIDL2360: invalid type redefinition
A new type was recursively defined on a nonexisting type.

Example:

typedef foo foo[10];    //MIDL 2360
MIDL2361: procedures with a [vararg] attribute must have a SAFEARRAY(VARIANT) parameter; param order is [vararg], [lcid], [retval]
Most of the parameters for procedures with the [vararg] attribute must occur before the SAFEARRAY(VARIANT) parameter. The SAFEARRAY(VARIANT) parameter must be present. If the parameter list contains a parameter with the [lcid] attribute, it must follow the SAFEARRAY(VARIANT) parameter. If the parameter list contains a parameter with the [retval] attribute, it must occur after the parameter with the [lcid] attribute.
MIDL2362: too many methods in the interface, requires Windows NT 4.0 SP3 or greater
The maximum number of methods in an interface for versions of Windows NT prior to version 3.51 is 32. Windows NT 4.0 supports up to 110 methods in an interface. Windows NT 4.0 SP 3 supports up to 512 methods in a single interface.
MIDL2363: too many methods in the interface, requires Windows 2000 or greater
The MIDL compiler does not allow more than 1024 methods in an interface when you are compiling in /Oicf mode.
MIDL2364: switch is being phased out
The following switches are obsolete: /hookole, /env win16, and /env DOS.
MIDL2365: cannot derive from IAdviseSink, IAdviseSink2, or IAdviseSinkEx
These interfaces cannot be extended.
MIDL2366: cannot assign a default value
Assigning a default value to a parameter is allowed in Visual Basic, but not in C++. If you are using C++, the default value is ignored.
MIDL2367: type library generation for DOS/Win16/MAC is not supported
MIDL does not support 16-bit type libraries.
MIDL2368: error generating type library, ignored
A nonfatal error occurred while generating the type library.
MIDL2369: exceeded stack size for /Oi, using /Os
The -Oi optimization mode is limited to 128 bytes of stack space for parameters. The compiler has automatically switched to the Os optimization mode to work around this limitation.

To avoid this warning, use the -Oicf or -Os optimization modes. The optimization mode may be changed on the command line by specifying -Oicf or -Os instead of -Oi or by adding an [optimize9"icf")] or optimize[("s")] attribute to the function in the ACF file.

This warning typically happens when passing large structures as parameters by value. The required stack size can be lowered by passing a pointer to the structure instead.

Example:

typedef struct
{
char a[127];
}
large;
//This function has a stack size of 132 (x86) or 136 (alpha) on 32-bit systems
void foo(large s, int a);    //MIDL 2360
// workaround: pass by reference
void bar (large *s, int a);
MIDL2370: use of /robust requires /Oicf, switching modes
You must compile in /Oicf mode when you specify the /robust switch on the command line.
MIDL2371: incorrect range specified
The highest value specified in a [range] attribute is less than the lowest value.

Example:

void foo([range(3,2)] int a);    //MIDL 2371
MIDL2372: invalid combination of [in] only and [out] parameters for [async_uuid] interface
Only simple combinations of attributes with [in] or [out] parameters are allowed for this type of interface.
MIDL2373: DOS, Win16 and MAC platforms are not supported with /robust
MIDL supports the /robust switch on Microsoft® Windows® 2000 or later.
MIDL2374: support for NT 3.51 style stubless proxies for object interfaces will be phased out; use /Oif.
This mode is obsolete. Use /Oif or /Oicf.
MIDL2375: [encode] or [decode] with /robust requires /Oicf
Serialization cannot be performed when the /robust switch is specified.
MIDL2377: conflicting attributes specified
Both [context_handle_serialize] and [context_handle_noserialize] were specified.
MIDL2378: [serialize], [noserialize] can be applied to context_handles
The ACF attributes [context_handle_serialize] or [context_handle_noserialize] can only be applied to types that are context handles.

Example IDL file:

typedef /*[context_handle] */ void *PV;    //Note: PV is *not* a context handle.

Example ACF file:

typedef [context_handle_serialize] PV;    //MIDL 2378
MIDL2379: The compiler reached a limit for a format string representation. See documentation for advice.
The MIDL compiler has a 64 KB limit for format strings. This error generally occurs when IDL files include other IDL files. The composite IDL file generated by all of the include statements exceeds the limits of the type representation tables of the marshaling engine interpreter. Try using the import directive rather than the include directive in your IDL files. For more information, see Importing System Header Files, include, and import.
MIDL2380: wire format may be incorrect, you may need to use -ms_conf_struct, see documentation for advice:
The MIDL compiler could not generate a transmissible format for the data. One common way to get this error is to define an ms_conf_struct inside a complex structure.
MIDL2381: a stack size or an offset bigger than 64 K limit. See documentation for advice.
The call results in a stack that is larger than 64 KB. Try passing the data in smaller blocks.
MIDL2382: an interpreter mode forced for 64-bit platform :
64-bit platforms require the /Oicf compilation mode.
MIDL2383: The array element size is bigger than 64 KB limit.
All array elements must be less than 64 KB in size.
MIDL2384: there can be only one [Icid] parameter in a mehtod, and it should be last or second to last if last parameter has [retval]
A parameter with the [lcid] attribute must occur last. The only exception is when there is also a parameter with the [retval] attribute. When both occur, the second to the last parameter in the parameter list must have the [lcid] attribute. The last parameter must have the [retval] attribute.
MIDL2385: incorrect syntax for midl_pragma
The MIDL compiler detected an unknown syntax error in a midl_pragma statement.
MIDL2386: __int3264 is not supported in /osf mode
If you need to use __int3264, compile in /ms-ext mode.
MIDL2387: unresolved symbol in type library
The compiler could not resolve a formal declaration or referenced type in the type library.
MIDL2388: async pipes cannot be passed by value
Asynchronous pipes should be passed by reference or by address.
MIDL2389: parameter offset exceed 64-KB limit for interpreted procedures
This error typically means that a procedure has too many parameters.
MIDL2390: invalid array element
Pipes cannot be used as array elements.
MIDL2391: dispinterface members must be methods, properties or interfaces
A dispinterface cannot contain type definitions, structures, enumerations, or unions.
MIDL2392: [local] procedure without [call_as]
Object procedures that have the [local] attribute also require the [call_as] attribute.
MIDL2393: multi dimentional vector, switching to /Oicf
The /Os optimization mode does not support multidimensional nonfixed size arrays. The compiler has automatically switched the optimization mode to /Oicf for this function.

This warning can be suppressed globally by changing the compiler mode by specifying /Oicf on the MIDL command line or by using midl_pragma warning (disable: 2393) in the IDL file. The optimization mode can be changed for an individual function by adding the [optimize("icf")] attribute to the function in the ACF file.

The following example demonstrates this warning:

void foo(long s1, [size_is(s1)] long a[][30];    //MIDL2393
void bar(long s1, long s2, [size_is(s1,s2) long **a);//MIDL2393
MIDL2395: type or construct not supported in a library block because Oleaut32.dll support for 64-KB polymorphic types is missing
OLE automation does not support polymorphic types (such as _int3264, INT_PTR, etc). These types have incompatible data representations between 32-bit and 64-bit platforms. The remote call will fail at run time on 64-bit platforms.

Note Note that as of Windows 2000 release, 64-bit TLB files are supported by OLE Automation by converting 32-bit TLB information at run time. Therefore only 32-bit TLB generation is supported by MIDL.

If MIDL is being used just to generate a header file, the /notlb switch will supress generation of the TLB file.

MIDL2396: old interpreter code being generated for 64b
This error is obsolete. If you see this error, please report a bug to Microsoft giving your IDL files, ACF files, and full MIDL-command line.
MIDL2397: the compiler switch is not supported anymore
The specified switch or switches are no longer supported.
MIDL2398: cannot execute MIDL engine
As of the Windows 2000 release (MIDL version 5.03.279), the MIDL compiler is implemented using two executable files: Midl.exe (the driver), and Midlc.exe (the compiler engine). This error indicates the Midl.exe is unable to launch Midlc.exe. Make sure that Midlc.exe is in the same directory as Midl.exe, and that they are the same version.

The error may have been caused by copying Midl.exe but not Midlx.exe from the latest distribution. Run midl and/or midlc at the command line without any parameters to see the version number of the executable.

MIDL2399: bad commands from driver
As of the Windows 2000 release (MIDL version 5.03.279), the MIDL compiler is implemented using two executable files: Midl.exe (the driver), and Midlc.exe (the compiler engine). This error indicates that the temporary file used to pass commands from Midl.exe to Midlc.ece is missing or corrupt. Make sure that Midlc.exe is in the same directory as Midl.exe, and that they are the same version.

The error may have been caused by attempting to run Midlc.exe directly or by copying Midl.exe but not Midlc.exe from the latest distribution. Run midl and/or midlc at the command line without any parameters to see the version number of the executable.

MIDL2400: for ole automation, optional parameters should be VARIANT or VARIANT *
OLE Automation requires that all [optional] parameters be of type VARIANT or VARIANT *.

In OLE automation, using non-VARIANT parameters may cause the call to fail at run time or to pass undefined data for the [optional] parameters.

MIDL2401: [defaultvalue] is applied to a non-VARIANT and [optional]. Please remove [optional]
The [defaultvalue] attribute implies [optional]. The [optional] attribute is not necessary.
MIDL2402: [optional] attribute is inapplicable outside of a library block
The functionality implied by the [optional] attribute is not applicable to proxies generated for an interface outside of a library block.
MIDL2403: The data type of the [Icid] parameter must be long
OLE Automation requires that parameters with the [Icid] attribute must be of type long.
MIDL2404: procedures with [propput], [propget] or [propref] can't have more than one required parameter after [optional] one
There cannot be more than one parameter without [optional] after the last parameter with [optional] when using [propput], [propget], or [propputref].
MIDL2405: [comm_status] or [fault_status] with pickling requires -Oicf
The old -Oi optimization mode does not support procedures or parameters with [comm_status] or [fault_status] with pickling (that is, using [encode] and/or [decode]).

This warning can be suppressed globally by specifying -Oicf on the MIDL command line or for an individual function by adding the [optimize("icf:)] attribute to the function in the ACF file.

In general, the -Oicf optimization mode is recommended over -Oi mode.

MIDL2406: midl driver and compiler version mismatch
As of the Windows 2000 release (MIDL version 5.03.279) the MIDL compiler is implemented using two executable files: Midl.exe (the driver), and Midlc.exe (the compiler engine). This error indicates that the version of Midl.exe does not match the version of Midlc.exe.

The error may have been caused by copying Midl.exe but not Midlc.exe from the latest distribution. Run midl and/or midlc at the command line without any parameters to see the version number of the executable.

MIDL2407: no intermediate file specified: use Midl.exe
As of the Windows 2000 release (MIDL version 5.03.279), the MIDL compiler is implemented using two executable files: Midl.exe (the driver), and Midlc.exe (the compiler engine). This error indicates that Midlc.exe was run directly instead of using Midl.exe.
MIDL2408: processing problem with a parameter in a procedure
This error may be seen when importing data from a TLB and when a procedure has an invalid parameter.

If you see this error, report a bug to Microsoft. Specify your IDL files, ACF files, TLB file, and full MIDL-command line.

MIDL2409: processing problem with a field in a structure
This error may be seen when importing data from a TLB and when a structure has an invalid structure or union field.

If you see this error, report a bug to Microsoft. Specify your IDL files, ACF files, TLB file, and full MIDL-command line.

MIDL2410: internal compiler inconsistency detected: the format string offset is invalid. See the documentation for more information.
The MIDL compiler detected an invalid value in its internal data structures. This may be caused by structures that are recursive or by compiler breaching its own limits of representation for internal data. To identify and/or work around the problem, try to simplify the IDL file. You can do this by simplifying complex parameters and recursive data structures or making the IDL file smaller by splitting it. This message may be accompanied by a diagnostic printout with additional information about the problem.

If you see this error, report a bug to Microsoft. Specify youf IDL files, ACF files, full MIDL command line, and diagnostic output, if any.

MIDL2411: internal compiler inconsistency detected: the type offset is invalid. See the documentation for more information.
The MIDL compiler detected an invalid value in its internal data structures. This may be caused by structures that are recursive or by the compiler breaching its own limits of representation for internal data. To identify and/or work around the problem try to simplify the IDL file. You can do this by simplifying complex parameters and recursive data structures or by making the IDL file smaller by splitting it. This message may be accompanied by a diagnostic printout with additional information about the problem.

If yoiu see this error, report a bug to Microsoft. Specify your IDL files, ACF files, full MIDL command line, and diagnostic output, if any.

MIDL2412: SAFEARRAY(foo) syntax is not supported outside of the library block, use LPSAFEARRAY for proxy
Explicitly-typed SAFEARRAYs are not allowed outside of a library block. Use LPSAFEARRAY instead.

The following example demonstrates this error:

void foo(SAFEARRAY(long) *a); //MIDL2412 when outside a library block
void foo(LPSAFEAEEAY a);         //OK
MIDL2413: bit fields are not supported
C-style bit fields are not supported by MIDL. This applies to proxy generation as well as TLB generation.
MIDL2414: floating point or complex return types with [decode] are not supported in -Oicf, using -OI
Procedures with floating point or structure/union return types are not supported in the -Oicf style pickling. A work around for 32-bit is to use the -Oi optimization mode when serializing data (using [encode] and/or [decode]). However, as the old -Oi style interpreter and pickling support are slated to be phased out after the Windows 2000 release, using pointers is strongly suggested as the work around for this problem. Also note that typically, changing an interface method to use an [out, ref] pointer instead of the return value causing the problem is fully backward-compatible on wire and can be easily hidden from the app layer.

This warning can be suppressed globally by specifying -Oi on the MIDL command line or for an individual function by adding the [optimize("i")] attribute to the function in the ACF file.

The following example demonstrates the issue:

foo.idl:

double GetDouble();

foo.acf:

[decode] GetDouble();

One option to work around this limitation would be to pass an [out] parameter to hold the result instead of using a return value:

foo.idl:

void GetDouble([out] double *result); //top level pointer is a [ref] pointer

foo.acf:

[decode] GetDouble();

As mentioned earlier, the solution described above is good not only for the new interfaces but also as a work-around for the old ones. The wire representation for the new "out" argument is the same as for the return value (notice void as the new return value).

MIDL2415: the return type is not supported for 64-bit when using [decode]
Procedures with floating point or structure/union return types are not supported in 64-bit mode when performing data serialization (using [encode] and/or [decode]). This is related to the old style -Oi interpreter and data serializer not being supported on 64-bit platform. Please see the description of MIDL2414 for more information.

The following example demonstrates this error:

foo.idl:

double GetDouble();

foo.acf:

[decode] GetDouble();

The following is advised as a work-around for both new and old interfaces. Use an [out] parameter to hold the result instead of using a return value:

foo.idl:

void GetDouble([out] double *result); //top level pointer is a [ref] pointer.

foo.acf:

[decode] GetDouble();

Note that this solution is fully backward-compatible on wire, as the wire representation of a [ref, out] pointer or a double is the same as that of a double.

MIDL2416: transmitted type may not contain a full pointer for either [wire_marshal] or [user_marshal]
Types with [wire_marshal] or [user_marshal] attributes may not contain full ([ptr]) pointers. Use [unique] or [ref] instead.

The following example demonstrates this error:

typdef struct
{
    [ptr] long *a;    //Should use [ref] or [unique] instead
}
st1;
typedef [wire_marshal(st1)] struct
{
    long a;
}
st2:
void foo(st2 *s);    //MIDL2416
MIDL2417: transmitted type must either be a pointer or have a constant size for [wire_marshal] and [user_marshal]
Top-level types with [wire_marshal] or [user_marshal] attributes must have a well-defined size at compile time. They cannot be or contain conformant or varying-sized arrays.

The following example demonstrates this error:

typedef struct        //Type contains variable-sized array
{
    long s;
    [size_is(s)] char a[];
}
st1;
typedef [wire_marshal(st1)] struct
{
    long a;
}
st2;
void foo(st2 *s);        //MIDL2417
MIDL2418: procedures with [propget] must have at least one parameter or a return value
Procedures with the [propget] attribute must have some means of returning the property value. They must have at least one [out] parameter or a return value.
MIDL9008: internal compiler problem <system error code> - the compiler cannot continue for an unknown reason. See documentation for a workaround.
The compiler could not continue and the cause of the error is unknown. The hexadecimal error number is a Windows NT/Windows 2000 or Windows 95/98 system-error identifier. The compile may have failed because of an external problem, such as an out-of-memory condition. In that case, you can find more information in Winerror.h or Ntstatus.h .

There are two situations that usually generate this error:

  • The MIDL compiler failed to recover after detecting an error in the IDL file. If MIDL returned any error messages about your IDL file, try fixing them and recompiling. If there are no error messages, the compiler may have failed before it could report an error. Look for a syntax error on the line for which the internal compiler error is reported.
  • The MIDL compiler could not generate correct code under a specified optimization option. Try changing compiler modes, compiling in mixed-mode optimization (/Os), or removing all optimizations. Or, recompile using the /NO_FORMAT_OPT flag to suppress MIDL's default optimization of procedure and type descriptors.

Occasionally this error occurs even when the IDL file is correct and no optimization options are being used. If this is the case, try rewriting the section of code in the vicinity of where the error was reported by removing any recent modifications, simplifying or rearranging data types, changing prototypes, or else begin to comment out portions of the IDL file to locate the problem code.

If none of these options works, or if you think the problem may be related to a bug in Midl.exe, please notify Microsoft, giving all the relevant details.


Topic Not Found

No matching topic was found. Some possible reasons and remedies are as follows:

  • The file (.chm) that contains the destination topic is not in the expected location.

    Remedy: Rerun the MSDN Library Setup.

  • The file (.chm) that contains the current topic or destination topic is out-of-date and the link is no longer valid.

    Remedy: Install the latest version of the MSDN Library.

  • The MSDN Library CD is not in the CD-ROM drive.

    Remedy: Insert the MSDN Library CD into the CD-ROM drive.