Macro Definitions

The RPC tools achieve model, calling, and naming-convention independence by associating data types and function-return types in the generated stub files and header files with definitions that are specific to each platform. These macro definitions ensure that any data types and functions that require the designation of _ _far are specified as far objects.

The following figure shows the macro definitions that the MIDL compiler applies to function calls between RPC components:

These are the macro definitions:

Definition Description
_ _RPC_API Applied to calls made by the stub to the user application. Both functions are in the same executable program.
_ _RPC_FAR Applied to the standard macro definition for pointers. This macro definition should appear as part of the signature of all user-supplied functions.
_ _RPC_STUB Applied to calls made from the run-time library to the stub. These calls can be considered private.
_ _RPC_USER Applied to calls made by the run-time library to the user application. These cross the boundary between a DLL and an application.
_ _RPC_ENTRY Applied to calls made by the application or stub to the run-time library. This macro definition is applied to all RPC run-time functions.

To link correctly with the Microsoft RPC run-time libraries, stubs, and support routines, some user-supplied functions must also include these macros in the function definition. Use the macro _ _RPC_API when you define the functions associated with memory management, user-defined binding handles, and the transmit_as attribute, and use the macro _ _RPC_USER when you define the context-rundown routine associated with the context handle. Specify the functions as:

_ _RPC_USER midl_user_allocate(...)
_ _RPC_USER midl_user_free(...)
_ _RPC_USER handletype_bind(...)
_ _RPC_USER handletype_unbind(...)
_ _RPC_USER type_to_local
_ _RPC_USER type_from_local
_ _RPC_USER type_to_xmit(...)
_ _RPC_USER type_from_xmit(...)
_ _RPC_USER type_free_local
_ _RPC_USER type_free_inst(...)
_ _RPC_USER type_free_xmit(...)
_ _RPC_USER context_rundown(...)

Note  All pointer parameters in these functions must be specified using the macro _ _RPC_FAR.

These are the two approaches that can be used to select an application's memory model:

  1. To use a single memory model for all files, compile all source files using the same memory-model compiler switches. For example, to develop a small-model application, compile both the application and the stub source code using the C-compiler switch /AS, as in the following:
    cl -c /AS myfunc.c
    cl -c /AS clstub_c.c
     
  2. To use different memory models for the application source files and the support source files (stubs files), use the RPC macros when you define function prototypes in the IDL file. Compile the distributed-application source files using one compiler memory-model setting and compile the support files using another compiler memory-model setting. Use the same memory model for all of the files generated by the compiler.