Embedded Out-Only Reference Pointers

When you use [out]-only reference pointers in Microsoft RPC, the generated server stubs allocate only the first level of pointers accessible from the reference pointer. Pointers at deeper levels are not allocated by the stubs, but must be allocated by the server application layer. For example, suppose an interface specifies an [out]-only array of reference pointers:

/* IDL file (fragment) */
typedef [ref] short * PREF;

Proc1([out] PREF array[10]);

In this example, the server stub allocates memory for 10 pointers and sets the value of each pointer to null. The server application must allocate the memory for the 10 short integers referenced by the pointers and then set the 10 pointers to point to the integers.

When the [out]-only data structure includes nested reference pointers, the server stubs allocate only the first pointer accessible from the reference pointer. For example:

/* IDL file (fragment) */
typedef struct 
{
    [ref] small * psValue;
} STRUCT1_TYPE;

typedef struct 
{
    [ref] STRUCT1_TYPE * ps1;
} STRUCT_TOP_TYPE;

Proc2([out, ref] STRUCT_TOP_TYPE * psTop);

In the preceding example, the server stubs allocate the pointer psTop and the structure STRUCT_TOP_TYPE. The reference pointer ps1 in STRUCT_TOP_TYPE is set to null. The server stub does not allocate every level of the data structure, nor does it allocate the STRUCT1_TYPE or its embedded pointer, psValue.