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

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

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

Output

statusReturns 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_okSuccess. 

ept_s_not_registeredNo entries found. 

rpc_s_invalid_bindingInvalid binding handle. 

rpc_s_invalid_if_handleInvalid interface handle. 

rpc_s_wrong_kind_of_binding
Wrong kind of binding for operation.

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 RPC daemon (RPCD), on the host that the binding argument specifies, to look up an endpoint for a compatible server instance.  The RPC daemon finds the endpoint by looking in the local endpoint map for the interface UUID from the if_handle argument and for the object UUID in the binding argument. 

Routine rpc_ep_resolve_binding 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 argument 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 argument 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 argument binding and the rpc_s_ok status code.  The routine makes no request of the RPC 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 routine 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 RPC 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 NCS 2.0 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 routine rpc_ep_resolve_binding 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 routine rpc_ep_resolve_binding. 

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 RPC daemon searches for a compatible server instance.  The search is based only on 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 RPC daemon on the remote host cannot distinguish among server instances registered in the local endpoint map. 

When the RPC 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: An application that wants to manage all the server instances on a host does not call the rpc_ep_resolve_binding routine.  Instead, the application obtains fully bound binding handles for each server instance by calling routines rpc_mgmt_ep_elt_inq_begin, rpc_mgmt_ep_elt_inq_next, and rpc_mgmt_ep_elt_inq_done. 

RETURN VALUES

None. 

RELATED INFORMATION

Functions: rpc_ep_register(3), rpc_ep_register_no_replace(3), rpc_mgmt_ep_elt_inq_begin(3), rpc_mgmt_ep_elt_inq_done(3), rpc_mgmt_ep_elt_inq_next(3), rpc_binding_from_string_binding(3), rpc_binding_reset(3)