byte_count

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

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 pointer-parameter-name.

pointer-parameter-name

Specifies the name of the out-only pointer parameter defined in the IDL file.

Examples

/* IDL file */

void proc1([in] unsigned long length, [out] struct foo * pFoo); 

/* ACF file */

proc1([byte_count(length)] pFoo); 

Remarks

Note  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.

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

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 provides a pointer to a buffer, the service provider can pass the buffer pointer on to the remote function and 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 many calls to individually free each pointer and structure. The memory area can be allocated or freed 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. Pointers are unmarshalled on a 4-byte aligned boundary. 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.

See Also