size_is (attributo)
Usare l'attributo [size_is] per specificare le dimensioni della memoria, negli elementi allocati per puntatori di dimensioni, puntatori ridimensionati a puntatori di dimensioni e matrici a matrice single o multidimensionale.
[ size_is(limited-expression-list) ]
Parametri
-
limited-expression-list
-
Specifica una o più espressioni del linguaggio C. Ogni espressione restituisce un numero intero non negativo che rappresenta la quantità di memoria allocata a un puntatore di dimensioni o a una matrice. Nel caso di una matrice, specifica una singola espressione che rappresenta le dimensioni di allocazione, negli elementi, della prima dimensione della matrice. Il compilatore MIDL supporta espressioni condizionali, espressioni logiche, espressioni relazionali ed espressioni aritmetiche. MIDL non consente chiamate di funzione nelle espressioni e non consente operatori di incremento e decremento. Usare le virgole come segnaposto per i parametri impliciti o per separare più espressioni.
Commenti
Se si usa l'attributo [size_is] per allocare memoria per una matrice multidimensionale e si usa la notazione array [ ] , tenere presente che solo la prima dimensione di una matrice multidimensionale può essere determinata dinamicamente in fase di esecuzione. Le altre dimensioni devono essere specificate in modo statico. Per altre informazioni sull'uso dell'attributo [size_is] con più livelli di puntatori per consentire a un server di restituire una matrice di dati di dimensioni dinamiche a un client, come illustrato nell'esempio Proc7, vedere Più livelli di puntatori.
È possibile usare [size_is] o max_is (ma non entrambi nello stesso elenco di attributi) per specificare le dimensioni di una matrice i cui limiti superiori vengono determinati in fase di esecuzione. Si noti, tuttavia, che l'attributo [size_is] non può essere usato nelle dimensioni di matrice fisse. L'attributo [max_is] specifica l'indice di matrice massimo valido. Di conseguenza, specificare [size_is(n)] equivale a specificare [max_is(n-1)].
Un parametro [in] o [ in, out] conforme all'attributo [ string] non deve avere l'attributo [size_is] o [max_is]. In questo caso, le dimensioni dell'allocazione vengono determinate dal carattere di terminazione NULL della stringa di input. Tutte le altre matrici conformi con l'attributo [string] devono avere un attributo [size_is] o [max_is].
Anche se è legale usare l'attributo [size_is] con una costante, questa operazione è inefficiente e non necessaria. Ad esempio, usare una matrice di dimensioni fisse:
HRESULT Proc3([in] short Arr[MAX_SIZE]);
invece di:
// legal but marshaling code is much slower
HRESULT Proc3([in size_is(MAX_SIZE)] short Arr[] );
È possibile usare insieme gli attributi [size_is] e [length_is]. Quando si esegue questa operazione, l'attributo [size_is] controlla la quantità di memoria allocata per i dati. L'attributo [length_is] specifica il numero di elementi trasmessi. La quantità di memoria specificata dagli attributi [size_is] e [length_is] non deve essere la stessa. Ad esempio, il client può passare un parametro [in,out] a un server e specificare un'allocazione di memoria di grandi dimensioni con [size_is], anche se specifica un numero ridotto di elementi dati da passare con [length_is]. In questo modo il server può riempire la matrice con più dati di quelli ricevuti, che può quindi inviare di nuovo al client.
In generale, non è utile specificare sia [size_is] che [length_is] nei parametri [in] o [out]. In entrambi i casi, [size_is] controlla l'allocazione della memoria. L'applicazione può usare [size_is] per allocare più elementi di matrice rispetto a quelli trasmessi (come specificato da [length_is]). Tuttavia, ciò sarebbe inefficiente. Sarebbe anche inefficiente specificare valori identici per [size_is] e [length_is]. Si creerebbe un sovraccarico aggiuntivo durante il marshalling dei parametri. Se i valori di [size_is] e [length_is] sono sempre uguali, omettere l'attributo [length_is].
Esempi
HRESULT Proc1(
[in] short m;
[in, size_is(m)] short a[]); // If m = 10, a[10]
HRESULT Proc2(
[in] short m;
[in, size_is(m)] short b[][20]); // If m = 10, b[10][20]
HRESULT Proc3(
[in] short m;
[size_is(m)] short * pshort); /* Specifies a pointer
to an m-sized block of shorts */
HRESULT Proc4(
[in] short m;
[size_is( , m)] short ** ppshort); /* Specifies a pointer
to a pointer to an m-sized
block of shorts */
HRESULT Proc5(
[in] short m;
[size_is(m ,)] short ** ppshort); /* Specifies an
m-sized block of pointers
to shorts */
HRESULT Proc6(
[in] short m;
[in] short n;
[size_is(m,n)] short ** ppshort); /* Specifies a pointer to an
m-sized block of pointers, each
of which points to an n-sized
block of shorts. m associates with
the pointer closeest to the identifer
it decorates. n associates with rest.*/
HRESULT Proc7(
[out] long * pSize,
[out, size_is( , *pSize)] my_type ** ppMyType); /* Specifies a pointer
to a sized pointer,
which points to a block
of my_types, whose size is
unknown when the stub
calls the server. */
Vedere anche