Was this page helpful?
Your feedback about this content is important. Let us know what you think.
Additional feedback?
1500 characters remaining
Export (0) Print
Expand All
COM
id
in
int
odl
out
ptr
ref
Expand Minimize

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

arrays
MIDL Base Types
callback
char
const
context_handle
enum
first_is
handle
Interface Definition (IDL) File
ignore
last_is
length_is
local
max_is
pointer_default
ptr
ref
size_is
struct
switch_type
transmit_as
union
unique
wchar_t

 

 

Community Additions

ADD
Show:
© 2015 Microsoft