string Attribute (Windows)

Switch View

string Attribute

string Attribute

The [string] attribute indicates that the one-dimensional char, wchar_t, byte (or equivalent) array or the pointer to such an array must be treated as a string. The string can also be an array (or a pointer to an array) of constructs whose fields are all of the type byte.

typedef [ string [[ , type-attribute-list ]] ] type-specifier declarator-list; 

typedef [ struct | union ] 
{
    [ string [[ , field-attribute-list ]] ] type-specifier declarator-list;
    ...
};

[ string [[ , function-attribute-list ]] ] type-specifier ptr-decl function-name(
  [[ [ parameter-attribute-list ] ]] type-specifier [[standard-declarator]]
  , ...);

[[ [ function-attribute-list ] ]] type-specifier [[ptr-decl]] function-name(
    [ string [[ , parameter-attribute-list ]] ] type-specifier [[standard-declarator]]
  , ...);

Parameters

type-attribute-list: Specifies one or more attributes that apply to a type. Valid type attributes include [handle], [switch_type], [transmit_as]; the pointer attribute [ref], [unique], or [ptr]; and the usage attributes [context_handle], [string], and [ignore]. Separate multiple attributes with commas.
type-specifier: Specifies a base type, struct type, or type identifier. An optional storage specification can precede type-specifier.
standard-declarator: Specifies a standard C declarator, such as an identifier, a pointer declarator, or an array declarator. For more information, see Array and Sized-Pointer Attributes, arrays., and Arrays and Pointers.
declarator-list: Specifies standard C declarators, such as identifiers, pointer declarators, and array declarators. For more information, see Array and Sized-Pointer Attributes, arrays., and Arrays and Pointers. The declarator-list consists of one or more declarators separated by commas. The parameter-name identifier in the function declarator is optional.
field-attribute-list: Specifies zero or more field attributes that apply to the structure, union member, or function parameter. The two valid field attributes are [max_is] and [size_is]; the usage attributes [string], [ignore], and [context_handle], the pointer attribute [ref], [unique], or [ptr], and the union attribute [switch_type]. Separate multiple field attributes with commas.
function-attribute-list: Specifies zero or more attributes that apply to the function. Valid function attributes are [callback], [local]; the pointer attribute [ref], [unique], or [ptr]; and the usage attributes [string], [ignore], and [context_handle].
ptr-decl: Specifies an optional pointer declarator to which the [string] attribute applies. A pointer declarator is the same as the pointer declarator used in C; it is constructed from the * designator, modifiers such as far, and the qualifier const.
function-name: Specifies the name of the remote procedure.
parameter-attribute-list: Consists of zero or more attributes appropriate for the specified parameter type. Parameter attributes can take the directional attributes [in] and [out]; the field attributes [max_is] and [size_is]; the pointer attribute [ref], [unique], or [ptr]; and the usage attributes [context_handle] and [string]. The usage attribute [ignore] cannot be used as a parameter attribute. Separate multiple attributes with commas.

Return Value

This attribute does not return a value.

Remarks

If the [string] attribute is used with an array whose bounds are determined at run time, you must also specify a [size_is] or [max_is] attribute, as in the following example:

/* a string that can hold up to MAX_STRING_LENGTH characters */
typedef [string, max_is(MAX_STRING_LENGTH)] char line[];

The [string] attribute cannot be used with attributes that specify the range of transmitted elements, such as [first_is], [last_is], and [length_is].

When used on multidimensional arrays, the [string] attribute applies to the rightmost array.

To define a counted string, do not use the [string] attribute. Use a character array or character-based pointer such as the following:

typedef struct 
{ 
    unsigned short size; 
    unsigned short length; 
    [size_is(size), length_is(length)] char string[*]; 
} counted_string;

The [string] attribute specifies that the stub should use a language-supplied method to determine the length of strings.

When declaring strings in C, you must allocate space for an extra character that marks the end of the string.

Examples

/* a string type that can hold up to 80 characters */ 
typedef [string] char line[81]; 
 
HRESULT Proc1([in, string] char * pszName);

Parameters

Return Value

Remarks

Examples

See Also