Binding Handle
A binding handle is a pointer-size opaque variable containing information the RPC runtime uses to manage binding information. The RPC runtime uses binding information to establish a client/server relationship that allows the execution of remote procedure calls.
Based on the context where it is created, a binding handle is considered a server binding handle or a client binding handle.
A server binding handle is a reference to the binding information necessary for a client to establish a relationship with a specific server. Many RPC API runtime routines return a server binding handle that you can use to make a remote procedure call.
A server binding handle refers to several components of binding information. One is the network address of a server's host system. Each server instance has one or more transport addresses (endpoints). A well-known endpoint is a stable address on the host, while a dynamic endpoint is an address that the RPC runtime requests for the server. Some transport protocols provide fewer well-known endpoints than dynamic endpoints.
If binding information contains an endpoint, the corresponding binding handle is a fully bound binding handle. If the information lacks an endpoint, the binding handle is a partially bound binding handle.
The RPC runtime creates and provides a client binding handle to a called remote procedure as the handle_t parameter. The client binding handle contains information about the calling client. A client binding handle cannot be used to make a remote procedure call. A server uses the client binding handle. The rpc_binding_server_from_client( ) routine converts a client binding handle to a server binding handle. You can use the resulting server binding handle to make a remote procedure call.
For an explanation of making a remote procedure call with a partially bound binding handle, see the OSF DCE Application Development Guide - Core Components.
Binding information can contain an object UUID. The default object UUID associated with a binding handle is a nil UUID. Clients can obtain a non-nil UUID in various ways, such as from a string representation of binding information (a string binding), or by importing it.
The following table contains the RPC runtime routines that operate on binding handles. The table also specifies the type of binding handle, client or server, allowed.
| Client and Server Binding Handles |
| Routine | Input Argument | Output Argument |
| rpc_binding_copy( ) | Server | Server |
| rpc_binding_free( ) | Server | None |
| rpc_binding_from_string_binding( ) | None | Server |
| rpc_binding_inq_auth_client( ) | Client | None |
| rpc_binding_inq_auth_info( ) | Server | None |
| rpc_binding_inq_object( ) | Server or client | None |
| rpc_binding_reset( ) | Server | None |
| rpc_binding_server_from_client( ) | Client | Server |
| rpc_binding_set_auth_info( ) | Server | None |
| rpc_binding_set_object( ) | Server | None |
| rpc_binding_to_string_binding( ) | Server or client | None |
| rpc_binding_vector_free( ) | Server | None |
| rpc_ns_binding_export( ) | Server | None |
| rpc_ns_binding_import_next | None | Server |
| rpc_ns_binding_inq_entry_name( ) | Server | None |
| rpc_ns_binding_lookup_next( ) | None | Server |
| rpc_ns_binding_select( ) | Server | Server |
| rpc_server_inq_bindings( ) | None | Server |
If the input argument type is only a client or only a server, the routines return the status code rpc_s_wrong_kind_of_binding when an application provides the incorrect binding handle type.
An application can share a single binding handle across multiple threads of execution. The RPC runtime, instead of the application, manages binding handle concurrency control across concurrent remote procedure calls that use a single binding handle. However, the client application has responsibility for binding handle concurrency control for operations that read or modify a binding handle. The related routines are as follows:
· rpc_binding_set_auth_info( )
For example, suppose an application shares a binding handle across two threads of execution and it resets the binding handle endpoint in one of the threads (by calling rpc_binding_reset( )). The binding handle in the other thread is then also reset. Similarly, freeing the binding handle in one thread (by calling rpc_binding_free( )) frees the binding handle in the other thread.
If you do not want this effect, your application can create a copy of a binding handle by calling rpc_binding_copy( ). An operation on one binding handle then has no effect on the second binding handle.
Clients and servers can access and set object UUIDs using the rpc_binding_inq_object( ) and rpc_binding_set_object( ) routines.
Routines requiring a binding handle as an argument show a data type of rpc_binding_handle_t. Binding handle arguments are passed by value.