rpc_binding_server_from_client(3rpc)
Converts a client binding handle to a server binding handle
Used by server applications.
Synopsis
#include <dce/rpc.h>
void rpc_binding_server_from_client(
rpc_binding_handle_t client_binding,
rpc_binding_handle_t *server_binding,
unsigned32 *status);
Parameters
Input
client_binding
Specifies the client binding handle to convert to a server binding handle.
Output
server_binding
Returns a server binding handle.
status
Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not.
Description
When a remote procedure call arrives at a server, the RPC runtime creates a client binding handle to refer to information about the calling client (client binding
information). The RPC runtime passes the client binding handle to the called remote procedure as the first input argument (which uses the handle_t type).
The rpc_binding_server_from_client( ) routine converts client binding information into server binding information corresponding to the client's system. When calling this routine, the called remote procedure specifies the client binding handle, and the routine returns a partially bound server binding handle (that is, the newly constructed server binding information contains a network address for the client's system, but lacks an endpoint). The server binding information also lacks authentication information, but the called procedure can add it by calling rpc_binding_set_auth_info( ). The object UUID from the client binding information remains.
The rpc_binding_server_from_client( ) routine is relevant when a called remote procedure (the first remote procedure) needs to make its own remote procedure call (a nested procedure call) to a second remote procedure offered by a server on the system of the client that called the first remote procedure (that is, the original client). The partially bound server binding handle returned by the rpc_binding_server_from_client( ) routine ensures that a nested call requests the second remote procedure on the original client's system.
In a multithreaded RPC application, the second remote procedure can belong to a server that shares the original client's address space (that is, the server and client can operate jointly as a server/client instance). If the original client belongs to a server/client instance and the application requires the nested call to execute in that instance, the application must guarantee that the nested remote procedure call uses one of the instances' endpoints.
An application can provide this guarantee by meeting any of the following conditions:
· The interface possesses its own well-known endpoints, and the server elects to use these interface-specific endpoints (by calling rpc_server_use_protseq_if( ) or rpc_server_use_all_protseqs_if( )).
· The server uses server-specific endpoints, and the interface is offered by only one server/client instance per system.
To use server-specific endpoints, a server either requests dynamic endpoints (by calling rpc_server_use_protseq( ) or rpc_server_use_all_protseqs( )) or specifies its own well-known endpoints (by calling rpc_server_use_protseq_ep( )). The server must also register its server-specific endpoints in the local endpoint map (by calling rpc_ep_register( )).
· The original client sets an object UUID into the server binding information of the first call (by calling rpc_binding_set_object( )); the object UUID identifies the server/client instance.
The client can obtain the object UUID from the list of object UUIDs used to register the endpoints of the server/client instance. The client must select an object UUID that belongs exclusively to its instance.
Server binding information containing an object UUID impacts the selection of a manager for a remote procedure call; see the OSF DCE Application Development Guide - Core Components for a description of manager selection. The object UUID can either identify a particular resource offered by the companion server or, used as an instance UUID, the object UUID can identify the original client's server/client instance.
The object UUID is passed in the first remote procedure call as part of the client binding information and is retained in the server binding information. This server binding information is newly constructed by the rpc_binding_server_from_client(~) routine. When the second remote procedure call arrives at the original client's system, the DCE Host daemon uses the object UUID to look for associated endpoints in the local endpoint map. To ensure that the object UUID is associated with the endpoints of the original server/client instance, the server must complete the following steps:
1. Obtain the UUID (for example, by calling uuid_create( )).
2. Specify the UUID as part of registering endpoints for the interface of the second remote procedure (by calling rpc_ep_register( ) or rpc_ep_register_no_replace( )).
If the second remote procedure call will be routed to a manager of a non-nil type, then the server must also do the following:
- Specify the type for the manager that implements that interface (by calling rpc_server_register_if( )).
- Set the object UUID to the same type as the manager (by calling rpc_object_set_type( )).
· The first remote procedure call contains a distinct call argument used by the original client to pass server information that identifies its server/client instance.
The first remote procedure call uses this information to route the second remote procedure call to the original server/client instance. For example, server information can be as follows:
- A fully bound string binding that identifies the client's server/client instance.
- If the first remote procedure receives this string binding, calling the rpc_binding_server_from_client routine is unnecessary. Instead, the first remote procedure requests a server binding handle for the string binding (by calling rpc_binding_from_string_binding( )).
- An object UUID that is associated in the endpoint map with one or more endpoints of the original server/client instance.
- The client can obtain the object UUID from the list of object UUIDs used to register the endpoints of the server/client instance. The client must select an object UUID that belongs exclusively to its instance, and pass that UUID as a call argument.
- After calling the rpc_binding_server_from_client( ) routine, add the object UUID from the call argument to the newly constructed server binding information (by calling rpc_binding_set_object( )).
Return Values
No value is returned.
Errors
The following describes a partial list of errors that might be returned. Refer to the OSF DCE Problem Determination Guide for complete descriptions of all error messages.
rpc_s_ok
Success.
rpc_s_cant_getpeername
Cannot get peer name.
rpc_s_connection_closed
Connection closed.
rpc_s_invalid_binding
Invalid binding handle.
rpc_s_wrong_kind_of_binding
Wrong kind of binding.
Related Information
Functions: rpc_binding_free(3rpc)
rpc_ep_register_no_replace(3rpc)
Books: OSF DCE Application Development Guide - Core Components