Atributo size_is
Use o atributo [size_is] para especificar o tamanho da memória, em elementos, alocado para ponteiros dimensionados, ponteiros dimensionados para ponteiros dimensionados e matrizes multidimensionais ou simples.
[ size_is(limited-expression-list) ]
Parâmetros
-
limited-expression-list
-
Especifica uma ou mais expressões de linguagem C. Cada expressão é avaliada como um inteiro não negativo que representa a quantidade de memória alocada para um ponteiro de tamanho ou uma matriz. No caso de uma matriz, especifica uma única expressão que representa o tamanho da alocação, em elementos, da primeira dimensão dessa matriz. O compilador MIDL dá suporte a expressões condicionais, expressões lógicas, expressões relacionais e expressões aritméticas. MIDL não permite invocações de função em expressões e não permite operadores de incremento e decremento. Use vírgulas como espaços reservados para parâmetros implícitos ou para separar várias expressões.
Comentários
Se você estiver usando o atributo [size_is] para alocar memória para uma matriz multidimensional e estiver usando a notação array [ ], tenha em mente que apenas a primeira dimensão de uma matriz multidimensional pode ser determinada dinamicamente em tempo de execução. As outras dimensões devem ser especificadas estaticamente. Para obter mais informações sobre como usar o atributo [size_is] com vários níveis de ponteiros para permitir que um servidor retorne uma matriz de dados de tamanho dinâmico para um cliente, conforme mostrado no exemplo Proc7, consulte Vários níveis de ponteiros.
Você pode usar [size_is] ou max_is (mas não ambos na mesma lista de atributos) para especificar o tamanho de uma matriz cujos limites superiores são determinados em tempo de execução. Observe, no entanto, que o atributo [size_is] não pode ser usado em dimensões de matriz fixas. O atributo [max_is] especifica o índice máximo de matriz válido. Como resultado, especificar [size_is(n)] é equivalente a especificar [max_is(n-1)].
Um parâmetro [ in] ou [in, out] da matriz em conformidade com o atributo [ string] não precisa ter o atributo [size_is] ou [max_is]. Nesse caso, o tamanho da alocação é determinado do terminador NULL da cadeia de caracteres de entrada. Todas as outras matrizes em conformidade com o atributo [string] devem ter um atributo [size_is] ou [max_is].
Embora seja legal usar o atributo [size_is] com uma constante, fazer isso é ineficiente e desnecessário. Por exemplo, use uma matriz de tamanho fixo:
HRESULT Proc3([in] short Arr[MAX_SIZE]);
em vez de:
// legal but marshaling code is much slower
HRESULT Proc3([in size_is(MAX_SIZE)] short Arr[] );
Você pode usar os atributos [size_is] e [length_is] juntos. Quando você faz isso, o atributo [size_is] controla a quantidade de memória alocada para os dados. O atributo [length_is] especifica quantos elementos são transmitidos. A quantidade de memória especificada pelos atributos [size_is] e [length_is] não precisa ser a mesma. Por exemplo, seu cliente pode passar um parâmetro [in,out] para um servidor e especificar uma alocação de memória grande com [size_is], mesmo que ele especifique um pequeno número de elementos de dados a serem passados com [length_is]. Isso permite que o servidor preencha a matriz com mais dados do que recebeu, que ele pode enviar de volta para o cliente.
Em geral, não é útil especificar os parâmetros [size_is] e [length_is] em [in] ou [out]. Em ambos os casos, [size_is] controla a alocação de memória. Seu aplicativo pode usar [size_is] para alocar mais elementos de matriz do que transmite (conforme especificado por [length_is]). No entanto, isso seria ineficiente. Também seria ineficiente especificar valores idênticos para [size_is] e [length_is]. Isso criaria uma sobrecarga extra durante o marshaling de parâmetros. Se os valores de [size_is] e [length_is] forem sempre os mesmos, omita o atributo [length_is].
Exemplos
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. */
Confira também