rpc_binding_reset(3rpc)

Used by client or management applications.

Synopsis

#include <dce/rpc.h>

void rpc_binding_reset(

rpc_binding_handle_t binding,

unsigned32 *status);

Parameters

Input

binding
Specifies the server binding handle to reset.

Output

status
Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not.

Description
The rpc_binding_reset( ) routine disassociates a server instance from the server binding handle specified in the binding parameter. 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(3rpc) reference page contains an explanation of partially and fully bound binding handles.

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

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 binding.

When the client makes the next remote procedure call using the reset server binding handle in 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 DCE Host Daemon (dced) 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 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 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
No value is returned.

Errors

The following describes a partial list of errors that might be returned. Refer to the OSF DCE Problem Determination Guide for complete descriptions of all error messages.

rpc_s_ok
Success.

rpc_s_invalid_binding
Invalid binding handle.

rpc_s_wrong_kind_of_binding
Wrong kind of binding for operation.

Related Information
Functions: rpc_ep_register(3rpc)

rpc_ep_register_no_replace(3rpc)