coNtext_handle屬性

[coNtext_handle]屬性會識別在遠端程序呼叫之間維護伺服器內容或狀態資訊的系結控制碼。

typedef [context_handle [ , type-attribute-list ] ] type-specifier declarator-list;

[context_handle [, function-attr-list ] ] type-specifier [ptr-decl] function-name(
    [ [parameter-attribute-list] ] type-specifier [declarator], ...);

[ [ function-attr-list ] ] type-specifier [ ptr-decl ] function-name(
    [context_handle [ , parameter-attribute-list ] ] type-specifier [declarator], ...);

[ void __RPC_USER context-handle-type_rundown (
  context-handle-type); ]

參數

type-attribute-list

指定套用至類型的一或多個屬性。

type-specifier

指定指標類型或類型識別碼。 選擇性儲存體規格可以位於 類型規範之前。

宣告子和宣告子清單

指定標準 C 宣告子,例如識別碼、指標宣告子和陣列宣告子。 內容控制碼的宣告子必須至少包含一個指標宣告子。 如需詳細資訊,請參閱 陣列和Sized-Pointer屬性陣列陣列和指標宣告子清單包含一或多個宣告子,並以逗號分隔。 函式宣告子中的參數名稱識別碼是選擇性的。

function-attr-list

指定套用至函式的零個或多個屬性。 有效的函式屬性為[callback][local];指標屬性[ref][unique][ptr];和使用屬性[string][ignore][coNtext_handle]。

ptr-decl

指定零個或多個指標宣告子。 指標宣告子與 C 中使用的指標宣告子相同;它會從 * 指示項、 方和限定詞 const等修飾詞建構。

function-name

指定遠端程式的名稱。

parameter-attribute-list

指定零個或多個方向屬性、欄位屬性、使用方式屬性,以及適用于指定參數類型的指標屬性。 以逗號分隔多個屬性。

coNtext-handle-type

指定識別碼,指定內容控制碼類型,如採用[coNtext_handle]屬性的typedef宣告中所定義。 取消常式是選擇性的。

Windows Server 2003 和 Windows XP: 單一介面可以容納序列化和非序列化的內容控制碼,讓介面上的一個方法 (可以獨佔存取序列化) 的內容控制碼,而其他方法則會在共用模式中存取該內容控制碼, (非序列化) 。 這些存取功能相當於讀取/寫入鎖定機制;使用序列化內容控制碼的方法是 (寫入器) 的獨佔使用者,而使用非序列化內容控制碼的方法則共用使用者 (讀取者) 。 終結或修改內容控制碼狀態的方法必須序列化。 未修改內容控制碼狀態的方法,例如只從內容控制碼讀取的方法,可以進行非序列化。 請注意,建立方法會隱含序列化。

備註

[coNtext_handle]屬性可以顯示為 IDL typedef 類型屬性、函式傳回型別屬性或參數屬性。 當您將 [coNtext_handle] 屬性套用至類型定義時,也必須提供內容取消常式。 如需詳細資訊,請參閱 伺服器內容執行常式

當您在預設 (/ms_ext) /ms_ext 模式中使用 MIDL 編譯器時,只要內容控制碼符合這裡所述的內容控制碼需求,內容控制碼就可以是使用者選取的任何指標類型。 與這類內容控制碼類型相關聯的資料不會在網路上傳輸,而且只能由伺服器應用程式操作。 DCE IDL 編譯器會將內容控制碼限制為void* 類型的指標。 因此,當您使用 MIDL 編譯器 /osf 參數時,無法使用此功能。

如同其他控制碼類型,內容控制碼與用戶端應用程式不透明,而且不會傳輸與其相關聯的任何資料。 在伺服器上,內容控制碼可作為使用中內容的控制碼,而且與內容控制碼類型相關聯的所有資料都可以存取。

若要建立內容控制碼,用戶端會將 [out][ref] 指標傳遞給內容控制碼的伺服器。 (內容控制碼本身可以有 Null 或非Null 值,只要其值與其指標屬性一致即可。例如,當內容控制碼類型套用 了 [ref] 屬性時,它不能有 Null 值。) 必須提供另一個系結控制碼來完成系結,直到建立內容控制碼為止。 如果未指定明確的控制碼,則會使用隱含系結。 當沒有 [implicit_handle] 屬性存在時,就會使用自動控制碼。

伺服器上的遠端程式會建立作用中內容控制碼。 用戶端必須在後續呼叫中使用該內容控制碼作為 [in][inout] 參數。 [in]-only 內容控制碼可以當做系結控制碼使用,因此它必須具有非Null值。 僅限 [in]的內容控制碼不會反映伺服器上的狀態變更。

在伺服器上,呼叫的程式可以視需要解譯內容控制碼。 例如,呼叫的程式可以配置堆積儲存體,並使用內容控制碼作為此儲存體的指標。

若要關閉內容控制碼,用戶端會將內容控制碼傳遞為 [in][out] 引數。 當伺服器不再代表呼叫端維護內容時,伺服器必須傳回 Null 內容控制碼。 例如,如果內容控制碼代表開啟的檔案,而呼叫會關閉檔案,則伺服器必須將內容控制碼設定為 Null ,並將它傳回用戶端。 Null值當做後續呼叫的系結控制碼無效。

內容控制碼僅適用于一部伺服器。 當函式有兩個控制碼參數且內容控制碼不是 Null時,系結控制碼必須參考相同的位址空間。

當函式具有 [in][inout] 內容控制碼時,其內容控制碼可以當做系結控制碼使用。 在此情況下,不會使用隱含系結,而且會忽略 [implicit_handle][auto_handle] 屬性。

下列限制適用于內容控制碼:

  • 內容控制碼不能是陣列元素、結構成員或等位成員。 它們只能是參數。
  • 內容控制碼不能有 [transmit_as][represent_as] 屬性。
  • 屬於 [out] 內容控制碼指標的參數必須是 [ref] 指標。
  • [in]內容控制碼可以當做系結控制碼使用,而且不能是Null
  • [inout內容控制碼可以是輸入上的Null,但只有在程式有另一個明確的控制碼參數時。 如果沒有其他明確的非Null 內容控制碼參數, 則 [inout] 內容控制碼不能是 Null
  • 內容控制碼不能與回呼搭配使用。

範例

typedef [context_handle] void * PCONTEXT_HANDLE_TYPE; 
short RemoteFunc1([out] PCONTEXT_HANDLE_TYPE * pCxHandle); 
short RemoteFunc2([in, out] PCONTEXT_HANDLE_TYPE * pCxHandle); 
void __RPC_USER PCONTEXT_HANDLE_TYPE_rundown (PCONTEXT_HANDLE_TYPE);

另請參閱

陣 列

auto_handle

回檔

用戶端內容重設

常量

內容控制碼

處理

系結和控制碼

忽略

implicit_handle

in

當地

多執行緒用戶端和內容控制碼

/ms_ext

out

Ptr

ref

represent_as

RpcSsDestroyClientCoNtext

伺服器內容執行常式

string

transmit_as

typedef

獨特

無效