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