atributo exclusivo
O atributo [exclusivo] especifica um ponteiro exclusivo.
pointer_default(unique)
typedef [ unique [[ , type-attribute-list ]] ] type-specifier declarator-list;
typedef struct-or-union-declarator
{
[ unique [[ , field-attribute-list ]] ] type-specifier declarator-list;
...}
[ unique [[ , function-attribute-list ]] ] type-specifier ptr-decl function-name(
[[ [ parameter-attribute-list ] ]] type-specifier [[declarator]]
, ...);
[[ [ function-attribute-list ] ]] type-specifier [[ptr-decl]] function-name(
[ unique [[ , parameter-attribute-list ]] ] type-specifier [[declarator]]
, ...);
Parâmetros
-
type-attribute-list
-
Especifica um ou mais atributos que se aplicam ao 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], [cadeiade caracteres] e [ignorar]. Separe vários atributos com vírgulas.
-
type-specifier
-
Especifica um tipo base, struct, união, tipo de enumeração ou identificador de tipo. Uma especificação de armazenamento opcional pode preceder o especificador de tipo.
-
declarator e 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.
-
struct-or-union-declarator
-
field-attribute-list
-
Especifica zero ou mais atributos de campo que se aplicam ao membro da estrutura, membro da união ou parâmetro de função. Os atributos de campo válidos incluem [first_is], [last_is], [length_is], [max_is], [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 pelo menos um declarador de ponteiro ao qual o atributo [exclusivo] 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 [first_is], [last_is], [length_is], [max_is], [size_is], e [switch_type]; 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
Os atributos de ponteiro podem ser aplicados como um atributo de tipo; como um atributo de campo que se aplica a um membro da estrutura, membro da união ou parâmetro; ou como um atributo de função que se aplica ao tipo de retorno de função. O atributo de ponteiro também pode aparecer com a palavra-chave [pointer_default].
Um ponteiro exclusivo tem as seguintes características:
- Pode ter o valor NULL.
- Pode ser alterado durante uma chamada de NULL para não NULL, de não NULL para NULL ou de um valor não NULL para outro.
- Pode alocar nova memória no cliente. Quando o ponteiro exclusivo é alterado de NULL para não NULL, os dados retornados do servidor são gravados em um novo armazenamento.
- Pode usar a memória existente no cliente sem alocar memória nova. Quando um ponteiro exclusivo é alterado durante uma chamada de um valor não NULL para outro, supõe-se que o ponteiro aponte para um objeto de dados do mesmo tipo. Os dados retornados do servidor são gravados no armazenamento existente especificado pelo valor do ponteiro exclusivo antes da chamada.
- Pode memória órfã no cliente. A memória referenciada por um ponteiro exclusivo não NULL pode nunca ser liberada se o ponteiro exclusivo for alterado para NULL durante uma chamada e o cliente não tiver outro meio de desreferenciar o armazenamento.
- Não causa alias. Como o armazenamento apontado por um ponteiro de referência, o armazenamento apontado por um ponteiro exclusivo não pode ser acessado de nenhum outro nome na função.
Os stubs chamam as funções de gerenciamento de memória fornecidas pelo usuário midl_user_allocate e midl_user_free para alocar e desalocar a memória necessária para ponteiros exclusivos e seus referenciantes.
As seguintes restrições se aplicam a ponteiros exclusivos:
- O atributo [exclusivo] não pode ser aplicado a parâmetros de identificador de associação ( handle_t) e parâmetros de identificador de contexto.
- O atributo [exclusivo] não pode ser aplicado a parâmetros de ponteiro de nível superior [out]-only (parâmetros que têm apenas o atributo direcional [out] ).
- Por padrão, ponteiros de nível superior em listas de parâmetros são ponteiros [ref]. Isso é verdadeiro mesmo que a interface especifique pointer_default(exclusivo). Parâmetros de nível superior em listas de parâmetros devem ser especificados com o atributo [exclusivo] para ser um ponteiro exclusivo.
- Ponteiros exclusivos não podem ser usados para descrever o tamanho de uma matriz ou braço de união porque ponteiros exclusivos podem ter o valor NULL. Essa restrição impede o erro que resulta se um valor NULL for usado como o tamanho da matriz ou o tamanho do braço de união.
Exemplos
pointer_default(unique)
typedef [unique, string] unsigned char * MY_STRING_TYPE;
[unique] char * MyFunction([in, out, unique] long * plNumber);
Confira também