unique (attributo)
L'attributo [unique] specifica un puntatore univoco.
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]]
, ...);
Parametri
-
type-attribute-list
-
Specifica uno o più attributi che si applicano al tipo. Gli attributi di tipo validi includono [handle], [switch_type], [transmit_as]; l'attributo puntatore [ref], [unique]o [ptr]; e gli attributi di utilizzo [context_handle], [string]e [ignore]. Separare più attributi con virgole.
-
type-specifier
-
Specifica un tipo di base, uno struct, un'unione, un tipo di enumerazione o un identificatore di tipo. Una specifica di archiviazione facoltativa può precedere l'identificatore di tipo.
-
declarator e declarator-list
-
Specifica i dichiaratori C standard, ad esempio identificatori, dichiaratori di puntatore e dichiaratori di matrice. Per altre informazioni, vedere Attributi,matrici e Sized-Pointer, matrici e puntatori. L'elenco dichiaratore è costituito da uno o più dichiaratori separati da virgole. L'identificatore del nome parametro nel dichiaratore di funzione è facoltativo.
-
struct-or-union-declarator
-
field-attribute-list
-
Specifica zero o più attributi di campo che si applicano al membro della struttura, al membro dell'unione o al parametro della funzione. Gli attributi di campo validi includono [first_is], [last_is], [length_is], [max_is], [size_is]; gli attributi di utilizzo [string], [ignore], e [context_handle]; l'attributo puntatore [ref], [unique]o [ptr]; e l'attributo union [switch_type]. Separare più attributi di campo con virgole.
-
function-attribute-list
-
Specifica zero o più attributi che si applicano alla funzione. Gli attributi di funzione validi sono [callback], [local]; l'attributo puntatore [ref], [unique]o [ptr]; e gli attributi di utilizzo [string], [ignore], e [context_handle].
-
ptr-decl
-
Specifica almeno un dichiaratore di puntatore a cui si applica l'attributo [unique]. Un dichiaratore di puntatore è lo stesso del dichiaratore del puntatore usato in C; viene costruito da * designator, modificatori come per lontano e qualificatore const.
-
function-name
-
Specifica il nome della routine remota.
-
parameter-attribute-list
-
È costituito da zero o più attributi appropriati per il tipo di parametro specificato. Gli attributi dei parametri possono accettare gli attributi direzionali [in] e [out]; gli attributi del campo [first_is], [last_is], [length_is], [max_is], [size_is], e [switch_type]; l'attributo puntatore [ref], unique o ptr; e gli attributi di utilizzo [context_handle] e [string]. L'attributo di utilizzo [ignore] non può essere usato come attributo di parametro. Separare più attributi con virgole.
Commenti
Gli attributi del puntatore possono essere applicati come attributo di tipo; come attributo di campo che si applica a un membro della struttura, a un membro dell'unione o a un parametro; o come attributo di funzione che si applica al tipo restituito della funzione. L'attributo puntatore può essere visualizzato anche con la parola chiave [pointer_default].
Un puntatore univoco presenta le caratteristiche seguenti:
- Può avere il valore NULL.
- Può cambiare durante una chiamata da NULL a non NULL, da non NULL a NULL o da un valore non NULL a un altro.
- Può allocare nuova memoria nel client. Quando il puntatore univoco passa da NULL a non NULL, i dati restituiti dal server vengono scritti in una nuova risorsa di archiviazione.
- Può usare la memoria esistente nel client senza allocare nuova memoria. Quando un puntatore univoco cambia durante una chiamata da un valore non NULL a un altro, si presuppone che il puntatore punti a un oggetto dati dello stesso tipo. I dati restituiti dal server vengono scritti nella risorsa di archiviazione esistente specificata dal valore del puntatore univoco prima della chiamata.
- Può orfanare la memoria nel client. La memoria a cui fa riferimento un puntatore univoco non NULL potrebbe non essere mai liberata se il puntatore univoco cambia in NULL durante una chiamata e il client non dispone di un altro mezzo per dereferenziare l'archiviazione.
- Non causa l'aliasing. Analogamente all'archiviazione a cui punta un puntatore di riferimento, l'archiviazione a cui punta un puntatore univoco non può essere raggiunta da qualsiasi altro nome nella funzione.
Gli stub chiamano le funzioni di gestione della memoria fornite dall'utente midl_user_allocate e midl_user_free per allocare e deallocare la memoria necessaria per puntatori univoci e i relativi riferimenti.
Le restrizioni seguenti si applicano ai puntatori univoci:
- L'attributo [unique] non può essere applicato ai parametri di handle di associazione ( handle_t) e ai parametri di handle di contesto.
- L'attributo [unique] non può essere applicato ai parametri del puntatore di primo livello [out]-only (parametri che hanno solo l'attributo direzionale [out] ).
- Per impostazione predefinita, i puntatori di primo livello negli elenchi di parametri sono puntatori [ref]. Ciò vale anche se l'interfaccia specifica pointer_default(unique). I parametri di primo livello negli elenchi di parametri devono essere specificati con l'attributo [unique] per essere un puntatore univoco.
- Non è possibile usare puntatori univoci per descrivere le dimensioni di una matrice o di un braccio di unione perché i puntatori univoci possono avere il valore NULL. Questa restrizione impedisce l'errore che restituisce se un valore NULL viene usato come dimensione della matrice o dimensione del braccio di unione.
Esempi
pointer_default(unique)
typedef [unique, string] unsigned char * MY_STRING_TYPE;
[unique] char * MyFunction([in, out, unique] long * plNumber);
Vedere anche