callback

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

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.

parameter-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 pointers and arrays. The parameter-name identifier is optional.

Example

[callback] HRESULT DisplayString([in, string] char * p1); 
 

Remarks

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.

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.

Only the connection-oriented and local protocol sequences support the callback attribute. 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.

See Also

IDL, /osf