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.
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);
See also