pipe attribute

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.

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