A pointer attribute can be applied to a parameter only if the parameter contains an explicit pointer declaration (*).
By default, a single pointer (*) operator in a parameter list of an operation declaration is treated as a reference pointer. To override this, specify a pointer attribute for the parameter. When there is more than one pointer operator, or multiple levels of indirection in the parameter list, the rightmost pointer is the top-level pointer; all pointers to the left of the rightmost pointer are of a lower level. The top-level pointer is treated as a reference pointer by default; the lower-level pointers have the semantics specified by the pointer_default attribute in the interface.
The following example illustrates the use of top- and lower-level pointers:
void op1 ([in] long **p_p_l)
In this example, p_p_l is a pointer to a pointer to a long integer. The first or leftmost pointer (*) signifies that the pointer to the long integer is a lower-level pointer, and the second or rightmost pointer (*) signifies that the pointer to the pointer is a top-level pointer.
Any pointer attribute you specify for the parameter applies to the top-level pointer only. Note that unless you specify a pointer attribute, the top-level explicit pointer declaration in a parameter defaults to a reference pointer even if the pointer_default(ptr) interface attribute is specified.
Using a reference pointer improves performance but is more restrictive. For example, the pointer declared in the following operation, for the parameter int_value, is a reference pointer. An application call to this operation can never specify NULL as the value of int_value.
void op ([in] long *int_value);
To pass a NULL value, use a full pointer. The following two methods make int_value into a full pointer:
· Applying the ptr attribute to the declaration of the parameter, int_value
void op ([in, ptr] long *int_value);
· Using the pointer_default (ptr) attribute in an interface header
[uuid(135e7f00-1682-11ca-bf61-08002b111685,
pointer_default(ptr),
version(1.0)] interface full_pointer
{
typedef long *long_ptr;
void op ([in] long_ptr int_value);
}
A NULL pointer can also be passed via a unique pointer.