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.