NAME

   rpc_ep_resolve_binding - Resolves a partially bound server binding
                            handle into a fully bound server binding
                            handle

   Used by client and management applications.

 SYNOPSIS

   #include <dce/rpc.h>

   void rpc_ep_resolve_binding( rpc_binding_handle_t binding,
                                rpc_if_handle_t if_handle,
                                unsigned32 *status );

 PARAMETERS

   Input/Output

   binding
       Specifies a partially bound server binding handle to resolve
       into a fully bound server binding handle.

   if_handle
       Contains a stub-generated data structure that specifies the
       interface of interest.

   Output

   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.

       ept_s_not_registered
                     No entries found.

       rpc_s_invalid_binding
                     Invalid binding handle.

       rpc_s_wrong_kind_of_binding
                     Wrong kind of binding for operation.

       rpc_s_rpcd_comm_failure
                     Communications failure while trying to reach the
                     endpoint map.

 DESCRIPTION

   An application calls the rpc_ep_resolve_binding() routine to resolve
   a partially bound server binding handle into a fully bound server
   binding handle.

   Resolving binding handles requires an interface UUID and an object
   UUID.  The object UUID can be a nil UUID.  The RPC runtime requests
   the DCE Host Daemon's Endpoint Mapper Service, on the host that the
   binding parameter specifies, to look up an endpoint for a compatible
   server instance.  The Endpoint Mapper Service finds the endpoint by
   looking in the local endpoint map for the interface UUID from the
   if_handle parameter and for the object UUID in the binding parameter.

   The rpc_ep_resolve_binding() routine depends on whether the specified
   binding handle is partially bound or fully bound.  When the
   application specifies a partially bound handle, the routine produces
   the following results:

     +  If no compatible server instances are registered in the local
        endpoint map, the routine returns the ept_s_not_registered
        status code.

     +  If one compatible server instance is registered in the local
        endpoint map, the routine returns a fully bound binding handle
        in binding and the rpc_s_ok status code.

     +  If more than one compatible server instance is registered in the
        local endpoint map, the routine randomly selects one.  It then
        returns the corresponding fully bound binding handle in binding
        and the rpc_s_ok status code.

   When the application specifies a fully bound binding  handle, the
   routine returns the specified binding handle in binding and the
   rpc_s_ok status code.  The routine makes no request of the DCE Host
   daemon.

   In neither the partially bound case nor the fully bound case does the
   routine contact a compatible server instance.

   Using This Routine

   For each server instance, the RPC runtime automatically provides
   routines (the rpc_mgmt_* routines) that form an RPC management
   interface.  If a server instance registers any application-provided
   interfaces, the RPC runtime automatically registers the RPC-provided
   management interface with the local endpoint map for that server
   instance.

   An application can call rpc_ep_resolve_binding() at any time with
   either a partially  bound  or a fully bound handle.  However,
   applications typically call this routine to avoid calling a routine
   in the management interface with a partially bound handle.

   An application can have a partially bound binding handle at the
   following times:

     +  After importing a binding handle.

     +  After resetting a binding handle.

     +  After converting a string binding without an endpoint to a
        binding handle.

   If an application calls an application-provided remote procedure using
   a partially bound handle, the RPC runtime automatically asks the DCE
   Host daemon to resolve the binding handle into a fully bound handle.
   This fully bound binding handle corresponds to the RPC interface of
   the called remote procedure and the requested object, if any.  The
   application can then use this fully bound handle to make remote
   management calls, so calling the rpc_ep_resolve_binding() routine is
   unnecessary.

   When a high proportion of all servers in an environment offers the
   same interface, the interface is known as a pervasive one.  The RPC
   management interface is a pervasive interface in all environments
   that use DCE RPC.

   Using this routine to unambiguously locate compatible server
   instances applies to application-pervasive interfaces as well as
   to the RPC management interface.

   Partially Bound Handles with a Non-nil Object UUID

   If the application has a partially bound handle with a non-nil
   object UUID, the application can decide not to call the
   rpc_ep_resolve_binding() routine before calling a procedure in the
   management interface.  In this case the remote management call is
   sent to a server instance, registered on the remote host, that
   offers that object UUID.

   After completing the remote management call, the application has a
   fully bound handle to that server instance.  The server instance that
   the handle specifies probably offers the non-management interfaces of
   interest to the calling application.  However, if you want to be
   certain of obtaining a fully bound handle to a server instance that
   offers the interfaces needed for later remote procedure calls, call
   the rpc_ep_resolve_binding() routine.

   Partially Bound Handles with a Nil Object UUID

   When an application makes a remote procedure or management call using
   a partially bound handle with a nil object UUID, the DCE Host daemon
   searches for a compatible server instance.  The search is based on
   the nil object UUID and the UUID of the interface to which the call
   belongs.

   All server instances that register any RPC interface automatically
   offer the RPC management interface.  When an application makes a
   remote management call using a partially bound handle with a nil
   object UUID, the DCE Host daemon on the remote host cannot
   distinguish among server instances registered in the local endpoint
   map.

   When the DCE Host daemon cannot distinguish among these instances it
   selects any server instance.  After completing the remote management
   call, the calling application has a fully bound handle.  However, the
   server instance that the handle represents probably does not offer
   the non-management interfaces that interest the application.

   The remote RPC management routines avoid this ambiguity.  They do
   this by returning the status rpc_s_binding_incomplete if the
   provided binding handle is a partially bound one with a nil object
   UUID.

   An application wanting to contact servers that have exported and
   registered interfaces with a nil object UUID calls routine
   rpc_ep_resolve_binding().  The application obtains a fully bound
   binding handle for calling remote management procedures in a server
   instance that also offers the remote procedures in the application-
   specific interface.

   Note that an application that wants to manage all the server instances
   on a host does not call rpc_ep_resolve_binding().  Instead, the
   application obtains fully bound binding handles for each  server
   instance by calling rpc_mgmt_ep_elt_inq_begin(),
   rpc_mgmt_ep_elt_inq_next(), and rpc_mgmt_ep_elt_inq_done().

 RETURN VALUES

   No value is returned.

 RELATED INFORMATION

   Functions: rpc_ep_register
              rpc_ep_register_no_replace
              rpc_mgmt_ep_elt_inq_begin
              rpc_mgmt_ep_elt_inq_done
              rpc_mgmt_ep_elt_inq_next
              rpc_binding_from_string_binding
              rpc_binding_reset