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 中使用的指针声明符相同;它是从 * 指示符、修饰符（如 far）和限定符 常值构造的。

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， out] 参数。 [ in]-only 上下文句柄可用作绑定句柄，因此它必须具有非 NULL 值。 仅 [in] 上下文句柄不反映服务器上的状态更改。

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

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

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

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

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

  • 上下文句柄不能是数组元素、结构成员或联合成员。 它们只能是参数。
  • 上下文句柄不能具有 [transmit_as] 或 [represent_as] 属性。
  • 指向 [out] 上下文句柄的指针的参数必须是 [ref] 指针。
  • [in] 上下文句柄可用作绑定句柄，不能为 NULL。
  • [in， out 上下文句柄在输入时可以为 NULL，但前提是该过程具有另一个显式句柄参数。 如果没有其他显式非 NULL 上下文句柄参数，则 [in， out] 上下文句柄不能为 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

服务器上下文运行例程

string

transmit_as

typedef

独特

无效