Buffer Annotations

This section summarizes the annotations that can be combined to describe a buffer. The following table lists these annotations.

Annotations for Buffers

Level	Usage	Size	Output	Optional	Parameters
omitted _deref _deref_opt	omitted _in _out _inout	omitted _ecount _bcount _xcount(expr)	omitted _full _part	omitted _opt	omitted (size) (size, length)

 

The following list items describes the columns in the table.

• Level
  Describes the buffer pointer's level of dereference from the parameter or return value p. Level can be one of the following:

  Omitted

  p is the buffer pointer.

  _deref

  *p is the buffer pointer. p must not be NULL.

  _deref_opt

  *p is the buffer pointer. p can be NULL, in which case the rest of the annotation is ignored.

• Usage
  Describes how the function uses the buffer. Usage can be one of the following:

  • omitted
    The buffer is not accessed. If used on the return value or with _deref, the function provides the buffer and is uninitialized at exit. Otherwise, the caller must provide the buffer. This should be used only for alloc and free functions.

  • _in
    The function reads only from the buffer. The calling function must provide the buffer and initialize it.

  • _out
    The function writes only to the buffer. If used on the return value or with _deref, the function provides the buffer and initializes it. Otherwise, the caller must provide the buffer and the function initializes it.

  • _inout
    The function may freely read from and write to the buffer. The caller must provide the buffer and initialize it. If used with _deref, the buffer may be reallocated by the function.

• Size
  Describes the total size of the buffer. This can be less than the space that is actually allocated for the buffer, in which case it describes the accessible amount. Size can be one of the following:

  • omitted
    No buffer size is given. If the type specifies the buffer size--such as with LPSTR and LPWSTR--that amount is used. Otherwise, the buffer is one element long. This must be used with _in, _out, or _inout.

  • _ecount
    The buffer size is an explicit element count.

  • _bcount
    The buffer size is an explicit byte count.

  • _xcount(expr)
    The buffer size cannot be expressed as a simple byte or element count. For example, the count might be in a global variable, in a structure member, or implied by an enumeration. PFD treats expr as a comment and does not use it to check buffer size. The expr can be anything that is meaningful to the reader, such as an actual expression or a quoted string.

• Output
  Describes how much of the buffer is initialized by the function. For _inout buffers, this partial annotation also describes how much is initialized at entry. Omit this category for _in buffers--they must be fully initialized by the caller.

  Output can be one of the following:

  • omitted
    The type specifies how much is initialized. For example, a function that is initializing an LPWSTR must use a terminating null character.

  • _full
    The function initializes the entire buffer.

  • _part
    The function initializes part of the buffer and explicitly indicates how much.

• Optional

  • omitted
    The pointer to the buffer must not be NULL.

  • _opt
    The pointer to the buffer might be NULL. It is checked by PFD before being dereferenced.

• Parameters
  Provides explicit counts for the size and length of the buffer. The size and length can be either constant expressions or an expression that involves a parameter--usually other than the one being annotated. Length should refer to the resulting value of an __out parameter. The parameters can be one of the following:

  • omitted
    There is no explicit count. Use when neither _ecount nor _bcount is used.

  • (size)
    This is the buffer's total size. Use with _ecount or _bcount but not with _part.

  • (size,length)
    This is the buffer's total size and initialized length. Use with _ecount_part and _bcount_part.

 

 

Send comments about this topic to Microsoft

Build date: 5/3/2011