atributo string
O atributo [string] indica que a matriz char unidimensional, wchar_t, byte (ou equivalente) ou o ponteiro para essa matriz deve ser tratado como uma cadeia de caracteres. A cadeia de caracteres também pode ser uma matriz (ou um ponteiro para uma matriz) de constructos cujos campos são todos do tipo 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]]
, ...);
Parâmetros
-
type-attribute-list
-
Especifica um ou mais atributos que se aplicam a um tipo. Os atributos de tipo válidos incluem [handle], [switch_type], [transmit_as]; o atributo de ponteiro [ref], [unique]ou [ptr]; e os atributos de uso [context_handle], [cadeia de caracteres] e [ignorar]. Separe vários atributos com vírgulas.
-
type-specifier
-
Especifica um tipo base, um tipo de struct ou um identificador de tipo. Uma especificação de armazenamento opcional pode preceder o especificador de tipo.
-
declarador padrão
-
Especifica um declarador C padrão, como um identificador, um declarador de ponteiro ou um declarador de matriz. Para obter mais informações, consulte Atributos de matriz e Sized-Pointer, matrizes e matrizes e ponteiros.
-
declarator-list
-
Especifica declaradores C padrão, como identificadores, declaradores de ponteiro e declaradores de matriz. Para obter mais informações, consulte Atributos de matriz e Sized-Pointer, matrizes e matrizes e ponteiros. A lista de declaradores consiste em um ou mais declaradores separados por vírgulas. O identificador parameter-name no declarador de função é opcional.
-
field-attribute-list
-
Especifica zero ou mais atributos de campo que se aplicam à estrutura, ao membro da união ou ao parâmetro de função. Os dois atributos de campo válidos são [max_is] e [size_is]; os atributos de uso [string], [ignore], e [context_handle], o atributo de ponteiro [ref], [unique], ou [ptr], e o atributo union [switch_type]. Separe vários atributos de campo com vírgulas.
-
function-attribute-list
-
Especifica zero ou mais atributos que se aplicam à função. Os atributos de função válidos são [retorno de chamada], [local]; o atributo de ponteiro [ref], [unique]ou [ptr]; e os atributos de uso [string], [ignore], e [context_handle].
-
ptr-decl
-
Especifica um declarador de ponteiro opcional ao qual o atributo [string] se aplica. Um declarador de ponteiro é o mesmo que o declarador de ponteiro usado em C; ele é construído a partir do designador * , modificadores como , por exemplo, e o qualificador const.
-
function-name
-
Especifica o nome do procedimento remoto.
-
parameter-attribute-list
-
Consiste em zero ou mais atributos apropriados para o tipo de parâmetro especificado. Os atributos de parâmetro podem usar os atributos direcionais [in] e [out]; os atributos de campo [max_is] e [size_is]; o atributo de ponteiro [ref], [unique]ou [ptr]; e os atributos de uso [context_handle] e [cadeia de caracteres]. O atributo de uso [ignore] não pode ser usado como um atributo de parâmetro. Separe vários atributos com vírgulas.
Comentários
Se o atributo [string] for usado com uma matriz cujos limites são determinados em tempo de execução, você também deverá especificar um atributo [size_is] ou [max_is] , como no exemplo a seguir:
/* a string that can hold up to MAX_STRING_LENGTH characters */
typedef [string, max_is(MAX_STRING_LENGTH)] char line[];
O atributo [string] não pode ser usado com atributos que especificam o intervalo de elementos transmitidos, como [first_is], [last_is] e [length_is].
Quando usado em matrizes multidimensionais, o atributo [string] aplica-se à matriz mais à direita.
Para definir uma cadeia de caracteres contada, não use o atributo [string] . Use uma matriz de caracteres ou um ponteiro baseado em caracteres, como o seguinte:
typedef struct
{
unsigned short size;
unsigned short length;
[size_is(size), length_is(length)] char string[*];
} counted_string;
O atributo [string] especifica que o stub deve usar um método fornecido pela linguagem para determinar o comprimento das cadeias de caracteres.
Ao declarar cadeias de caracteres em C, você deve alocar espaço para um caractere extra que marca o final da cadeia de caracteres.
Exemplos
/* a string type that can hold up to 80 characters */
typedef [string] char line[81];
HRESULT Proc1([in, string] char * pszName);
Confira também