The binding_callout attribute permits you to specify the name of a routine that the client stub is to call automatically to modify a server binding handle before it initiates a remote procedure call. This attribute is intended for use by client applications that employ the automatic binding method through the auto_handle ACF interface attribute. In automatic binding, it is the client stub, rather than the client application code, that obtains the binding handle to the server. The binding_callout attribute allows a client application using automatic binding to modify the binding handle obtained by the client stub. Without this attribute, it is impossible for the client application to modify the binding handle before the client stub attempts to initiate a remote procedure call to the selected server.
Clients typically use this attribute to augment automatic binding handles with security context, for example, so that authenticated RPC is used between client and server.
The binding_callout attribute has the following syntax. (See the example at the end of this topic.)
[binding_callout(routine_name)] interface interface_name
The routine_name specifies the name of a binding callout routine hat 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 outine_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 OSF DCE Application Development Reference for a description of the rpc_ss_bind_authn_client( ) routine.
The binding callout routine you provide must have a specific routine signature. See the description of rpc_ss_bind_authn_client( ) in the OSF DCE Application Development Reference 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 bindcall
{
}
Generated Header File (bindcall.h
void my_bh_callout(
rpc_binding_handle_t *p_binding,
rpc_if_handle_t interface_handle,
error_status_t *p_st
);