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

Matrizes

Atributos de campo

first_is

Arquivo IDL (definição de interface)

Em

last_is

length_is

max_is

min_is

out

cadeia de caracteres