size_is 屬性

  • 發行項

使用 [size_is] 屬性可指定記憶體大小、在元素中，針對大小指標配置、大小指標的大小指標，以及單一或多維度陣列。

[ size_is(limited-expression-list) ]

參數

limited-expression-list

指定一或多個 C 語言運算式。 每個運算式都會評估為非負整數，代表配置給大小指標或陣列的記憶體數量。 在陣列的案例中，指定單一運算式，代表該陣列第一個維度的配置大小。 MIDL 編譯器支援條件運算式、邏輯運算式、關聯運算式和算術運算式。 MIDL 不允許運算式中的函式呼叫，而且不允許遞增和遞減運算子。 使用逗號做為隱含參數的預留位置，或分隔多個運算式。

備註

如果您使用 [size_is] 屬性來配置多維度陣列的記憶體，而且您使用的是陣列 [ ] 標記法，請記住，只有多維度陣列的第一個維度可以在執行時間動態決定。 其他維度必須以靜態方式指定。 如需搭配多個指標層級使用 [size_is] 屬性的詳細資訊，可讓伺服器將動態大小的資料陣列傳回給用戶端，如 Proc7 範例所示，請參閱 多個指標層級。

您可以使用 [size_is] 或 max_is (，但不能同時在相同的屬性清單中) 指定在執行時間決定其上限的陣列大小。 不過請注意，[size_is] 屬性不能用於固定的陣列維度上。 [max_is] 屬性會指定最大有效陣列索引。 因此，指定 [size_is (n) ] 相當於指定 [max_is (n-1) ]。

具有 [ string] 屬性的 [ in] 或 [in， out] 一致性陣列參數不需要 [size_is] 或 [max_is] 屬性。 在此情況下，配置的大小取決於輸入字串的 Null 結束字元。 具有 [string] 屬性的所有其他一致性陣列都必須具有 [size_is] 或 [max_is] 屬性。

雖然將 [size_is] 屬性與常數搭配使用是合法的，但這麼做沒有效率且不必要。 例如，使用固定大小陣列：

HRESULT Proc3([in] short Arr[MAX_SIZE]);

而非：

// legal but marshaling code is much slower
HRESULT Proc3([in size_is(MAX_SIZE)] short Arr[] );

您可以將 [size_is] 和 [length_is] 屬性一起使用。 當您這樣做時，[size_is] 屬性會控制配置給資料的記憶體數量。 [length_is] 屬性會指定傳輸的專案數目。 [size_is] 和 [length_is] 屬性指定的記憶體數量不一樣。 例如，您的用戶端可能會將 [in，out] 參數傳遞至伺服器，並使用 [size_is] 指定大型記憶體配置，即使它指定要以 [length_is傳遞的少量資料元素也一樣。 這可讓伺服器以比收到的更多資料填滿陣列，然後傳送回用戶端。

一般而言，在 [in] 或 [out] 參數上同時指定 [size_is] 和 [length_is] 並不實用。 在這兩種情況下，[size_is] 會控制記憶體配置。 您的應用程式可以使用 [size_is] 來配置比 [length_is]) 所指定 (更多的陣列元素。 不過，這會沒有效率。 針對 [size_is] 和 [length_is] 指定相同的值也會沒有效率。 它會在參數封送處理期間建立額外的額外負荷。 如果 [size_is] 和 [length_is] 的值一律相同，請省略 [length_is] 屬性。

範例

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. */

另請參閱

陣 列

欄位屬性

first_is

介面定義 (IDL) 檔案

in

last_is

length_is

max_is

min_is

out

字串