OSF DCE Application Development Guide--Core Components

OSF DCE Application Development Guide—Core Components
The binding_callout attribute has the following syntax. (See the example at the end of
this section.)
[binding_callout(routine_name)] interface interface_name
The routine_name specifies the name of a binding callout routine that the client stub will
call to modify the server binding handle before initiating the remote procedure call to
the server. The IDL compiler will generate a function prototype for routine_name in the
generated header file.
You can specify the name of a routine that you supply, or you can specify the DCE RPC
routine rpc_ss_bind_authn_client( ) to modify the binding handle if it meets the needs
of your application. See the rpc_ss_bind_authn_client(3rpc) reference page for more
information.
The binding callout routine you provide must have a specific routine signature. See the
rpc_ss_bind_authn_client(3rpc) reference page for information about the required
routine signature.
The binding_callout attribute can occur at most once in the ACF and applies to all of
the operations in the corresponding IDL file.
A binding callout routine should return the error_status_ok status code when it
successfully modifies the binding handle or determines that no action is necessary. This
status code causes the client stub to initiate the remote procedure call.
A binding callout routine can also return error status. If it does, the client stub does not
initiate the remote procedure call. Instead, if the auto_handle attribute has been applied
in the ACF, the client stub attempts to locate another server of the interface and then
calls the binding callout routine again. If auto_handle is not in use, the client stub
invokes its normal error-handling logic. A binding callout routine for a client using
auto_handle can return the status code rpc_s_no_more_bindings to prevent the client
stub from searching for another server and instead invoking its error-handling logic
immediately.
By default, the client stub handles an error condition by raising an exception. If a
binding callout routine returns one of the rpc_s_ status codes, the client stub raises a
matching rpc_x_ exception. However, if a binding callout routine returns any other
type of status code, the client stub will most likely raise it as an ‘‘unknown status’’
exception.
If the comm_status parameter ACF attribute has been applied to an operation, the client
stub handles an error condition by returning the error status value in the comm_status
parameter. Consequently, a binding callout routine can return any error status value to
the client application code if the comm_status attribute has been applied to the
operation.
A binding callout routine can raise a user-defined exception, rather than return a status
code, to report application-specific error conditions back to the client application code
using exceptions.
Example Using the binding_callout Attribute
ACF
[auto_handle,binding_callout(my_bh_callout)] interface \
18 − 28 Tandem Computers Incorporated 124245