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

指定指標類型或類型識別碼。 選擇性的儲存體規格可以在 type-specifier之前。

declarator 和 declarator-list

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

function-attr-list

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

ptr-decl

指定零個或多個指標宣告子。 指標宣告子與 C 中使用的指標宣告子相同;它會從 * 指示項建構, 例如遠方修飾詞和限定詞 常數

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 coNtext handle 可以是輸入上的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

回檔

用戶端內容重設

const

內容控制碼

處理

系結和控制碼

忽略

implicit_handle

in

當地

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

/ms_ext

out

ptr

ref

represent_as

RpcSsDestroyClientCoNtext

伺服器內容執行常式

字串

transmit_as

typedef

獨特

void