callback attribute
The [callback] attribute declares a static callback function that exists on the client side of the distributed application. Callback functions provide a way for the server to execute code on the client.
[callback [ , function-attr-list] ] type-specifier [ptr-declarator] function-name(
[ [attribute-list] ] type-specifier [declarator]
, ...);
Parameters
-
function-attr-list
-
Specifies zero or more attributes that apply to the function. Valid function attributes are [local]; the pointer attribute [ref], [unique], or [ptr]; and the usage attributes [string], [ignore], and [context_handle]. Separate multiple attributes with commas.
-
type-specifier
-
Specifies a base_type, struct, union, enum type, or type identifier. An optional storage specification can precede type-specifier.
-
ptr-declarator
-
Specifies zero or more pointer declarators. A pointer declarator is the same as the pointer declarator used in C; it is constructed from the * designator, modifiers such as far, and the qualifier const.
-
function-name
-
Specifies the name of the remote procedure.
-
attribute-list
-
Specifies zero or more directional attributes, field attributes, usage attributes, and pointer attributes appropriate for the specified parameter type. Separate multiple attributes with commas.
-
declarator
-
Specifies a standard C declarator such as identifiers, pointer declarators, and array declarators. For more information, see Array and Sized-Pointer Attributes, arrays, and Arrays and Pointers. The parameter-name identifier is optional.
Remarks
The [callback] function is useful when the server must obtain information from the client. If server applications were supported on Windows 3.x, the server could make a call to a remote procedure on the Windows 3.x server to obtain the needed information. The callback function accomplishes the same purpose and lets the server query the client for information in the context of the original call.
Callbacks are special cases of remote calls that execute as part of a single thread. A callback is issued in the context of a remote call. Any remote procedure defined as part of the same interface as the static callback function can call the callback function.
It is important to note that the use of [callback] is not recommended in multi-thread programming. As a single-thread programming function, it is not equipped to support the security demands a multi-thread environment provides.
The RpcCancelThread function cannot be used to cancel a call that may dispatch a static callback. If a particular remote procedure call will never result in a callback, then it can be canceled. Otherwise, a call can be canceled only if it can be guaranteed that a callback for it has not been issued.
Only the connection-oriented and local-protocol sequences support the callback attribute. The size of the [out] data for callbacks over the local-protocol sequence is limited to 150 bytes. If an RPC interface uses a connectionless (datagram) protocol sequence, calls to procedures with the callback attribute will fail.
Handles cannot be used as parameters in callback functions. Because callbacks always execute in the context of a call, the binding handle used by the client to make the call to the server is also used as the binding handle from the server to the client.
Callbacks can nest to any depth.
Examples
[callback] HRESULT DisplayString([in, string] char * p1);
See also