NAME
rpc_binding_server_from_client - 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. The possible status codes and their meanings
are as follows:
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.
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 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:
1. Specify the type for the manager that implements that
interface (by calling rpc_server_register_if()).
2. 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.
RELATED INFORMATION
Functions: rpc_binding_free
rpc_binding_set_object
rpc_ep_register
rpc_ep_register_no_replace
Books: DCE OSF Application Development Guide.