NAME

rpc_binding_reset - Resets a server binding handle so the host remains specified, but the server instance on that host is unspecified

Used by client or management applications. 

SYNOPSIS

#include <dce/rpc.h>
void rpc_binding_reset(

rpc_binding_handle_t binding ,
unsigned32 ∗status );

PARAMETERS

Input

bindingSpecifies the server binding handle to reset. 

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. 

rpc_s_invalid_bindingInvalid binding handle. 

rpc_s_wrong_kind_of_binding
Wrong kind of binding for operation.

DESCRIPTION

The rpc_binding_reset routine disassociates a server instance from the server binding handle specified in the binding argument.  This routine removes the endpoint portion of the server address in the binding handle as well as any other server instance information in the binding handle.  The host portion of the server address remains unchanged.  The result is a partially bound server binding handle.  This binding handle can rebind to another server instance on the previous host when it is later used to make a remote procedure call.  The rpc_intro(3) reference page contains an explanation of partially and fully bound binding handles. 

This routine does not affect any authentication information for the binding argument. 

Suppose that a client can be serviced by any compatible server instance on the host specified in the binding handle.  Then, the client can call the rpc_binding_reset routine before making a remote procedure call using the binding handle specified in argument binding. 

When the client makes the next remote procedure call using the reset server binding handle in argument binding, the client’s RPC runtime uses a well-known endpoint from the client’s interface specification, if any.  Otherwise, the client’s RPC runtime automatically communicates with the RPC daemon (RPCD) on the specified remote host, to obtain the endpoint of a compatible server from the local endpoint map.  If a compatible server is located, the RPC runtime updates argument binding with a new endpoint. 

However, if a compatible server is not located, the client’s remote procedure call fails.  If the failed call uses a connection protocol (ncacn), it receives the rpc_s_endpoint_not_found status code.  If the failed call uses a datagram protocol (ncadg), it receives the rpc_s_comm_failure status code. 

If a server application wants to be available to clients making a remote procedure call on a reset binding handle, it registers all binding handles by calling routine rpc_ep_register or rpc_ep_register_no_replace.  If, however, the IDL-generated file contains endpoint address information, then the application does not have to call either of these two routines. 

RETURN VALUES

None. 

RELATED INFORMATION

Functions: rpc_ep_register(3), rpc_ep_register_no_replace(3)