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

指定指针类型或类型标识符。 可选存储规范可以在 类型说明符之前。

declarator 和 declarator-list

指定标准 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) 模式下使用 MIDL 编译器时,只要上下文句柄符合此处所述的上下文句柄的要求,上下文句柄就可以是用户选择的任何指针类型。 与此类上下文句柄类型关联的数据不会在网络上传输,并且只能由服务器应用程序操作。 DCE IDL 编译器将上下文句柄限制为 类型 void* 的指针。 因此,使用 MIDL 编译器 /osf 开关时,此功能不可用。

与其他句柄类型一样,上下文句柄对客户端应用程序不透明,并且不会传输与之关联的任何数据。 在服务器上,上下文句柄充当活动上下文的句柄,并且可访问与上下文句柄类型关联的所有数据。

若要创建上下文句柄,客户端会将 [out][ref] 指针传递给服务器,指向上下文句柄。 (上下文句柄本身可以具有 NULL 或非 NULL 值,只要其值与其指针属性一致。例如,当上下文句柄类型应用 了 [ref] 属性时,它不能有 NULL 值。) 必须提供另一个绑定句柄才能完成绑定,直到创建上下文句柄。 如果未指定显式句柄,则使用隐式绑定。 如果没有 [implicit_handle] 属性,则使用自动句柄。

服务器上的远程过程创建活动上下文句柄。 客户端必须在后续调用中使用该上下文句柄作为 [in][in] 参数。 [ in]-only 上下文句柄可用作绑定句柄,因此它必须具有非 NULL 值。 仅限 [in] 的上下文句柄不反映服务器上的状态更改。

在服务器上,调用的过程可以根据需要解释上下文句柄。 例如,调用的过程可以分配堆存储,并使用上下文句柄作为指向此存储的指针。

若要关闭上下文句柄,客户端将上下文句柄作为 [in][out] 参数传递。 当服务器不再代表调用方维护上下文时,服务器必须返回 NULL 上下文句柄。 例如,如果上下文句柄表示打开的文件,并且调用关闭文件,则服务器必须将上下文句柄设置为 NULL 并将其返回到客户端。 NULL 值作为后续调用的绑定句柄无效。

上下文句柄仅对一台服务器有效。 当函数具有两个句柄参数并且上下文句柄不 为 NULL 时,绑定句柄必须引用相同的地址空间。

当函数具有 [in][in, out] 上下文句柄时,其上下文句柄可用作绑定句柄。 在这种情况下,不使用隐式绑定,并且忽略 [implicit_handle][auto_handle] 属性。

以下限制适用于上下文句柄:

  • 上下文句柄不能是数组元素、结构成员或联合成员。 它们只能是参数。
  • 上下文句柄不能具有 [transmit_as][represent_as] 属性。
  • 指向 [out] 上下文句柄的指针的参数必须是 [ref] 指针。
  • 上下文句柄可用作绑定句柄,不能为 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

回调 (callback)

客户端上下文重置

const

上下文句柄

处理

绑定和句柄

忽略

implicit_handle

in

当地

多线程客户端和上下文句柄

/ms_ext

out

ptr

裁判

represent_as

RpcSsDestroyClientContext

服务器上下文运行例程

字符串

transmit_as

typedef

独特

void