This attribute causes the client stub and RPC runtime to manage the binding to the server by using a directory service. Any operation in the interface that has no parameter containing binding information is bound automatically to a server so the client does not have to specify a binding to a server.
When an operation is automatically bound, the client does not have to specify the server on which an operation executes. If you make a call on an operation without explicit binding information in an interface for which you have specified auto_handle, and no client/server binding currently exists, the client stub selects an available server and establishes a binding. This binding is used for this call and subsequent calls to all operations in the interface that do not include explicit binding information, while the server is still available.
When a client use the automatic binding method, DCE must use the name service to obtain binding information. However, the client host must have a starting entry from which to begin the namespace search. If the RPC_DEFAULT_ENTRY environment variable is defined on the client host, DCE uses the entry in that variable to obtain binding information. If RPC_DEFAULT_ENTRY is not defined, DCE looks for binding information from the host's name service profile.
Server termination, network failure, or other problems can cause a break in binding. If this occurs during the execution of an automatically bound operation, the client stub issues the call to another server, provided one is available and the operation is idempotent, or it determines that the call did not start to run on the server. Similarly, if a communications or server failure occurs between calls, the client stub binds to another server for the next call, if a server is available.
If the client stub is unable to find a server to run the operation, it reports this by returning the status code rpc_s_no_more_bindings in the comm_status parameter, or by raising the exception rpc_x_no_more_bindings if the operation does not use the comm_status attribute for error reporting. Note that if a binding breaks, the search for another server begins at the directory service entry following the one where the binding broke. This means that even if a server earlier in the list becomes available, it is not treated as a candidate for binding. After the RPC runtime tries each server in the list, it reinitializes the list of server candidates and tries again. If the second attempt is unsuccessful, the RPC runtime reports the status code rpc_s_no_more_bindings. The next call on an operation in the interface starts from the top of the list when looking for a server to bind to.
The auto_handle attribute can occur at most once in the ACF.
If an interface uses the auto_handle attribute, the presence of a binding handle or context handle parameter in an operation overrides auto_handle for that operation.
The auto_handle attribute declaration has the following syntax. (See the example at the end of this topic.)
[auto_handle] interface interface_name
You cannot use auto_handle if you use implicit_handle or if you use explicit_handle in the interface header. You also cannot use auto_handle if you use the encode or decode ACF attributes.
Example Using the auto_handle Attribute
ACF
[auto_handle] interface math_1
{
}
IDL File
[uuid(b3c86900-2d27-11c9-ab09-08002b0ecef1)]
{
/* This operation has no handle parameter,
* therefore, uses automatic binding.
*/
long add([in] long a,
[in] long b);
/*
* This operation has an explicit handle parameter, h,
* that overrides the [auto_handle] ACF attribute.
* Explicit handles also override [implicit_handle].
*/
long subtract ([in] handle_t h,
[in] long a,
[in] long b);
}