rpc_mgmt_is_server_listening(3rpc)
Tells whether a server is listening for remote procedure calls
Used by client, server, or management applications.
Synopsis
#include <dce/rpc.h>
boolean32 rpc_mgmt_is_server_listening(
rpc_binding_handle_t binding,
unsigned32 *status);
Parameters
Input
binding
Specifies a server binding handle. To determine if a remote application is listening for remote procedure calls, specify a server binding handle for that application.
To determine if your own (local) application is listening for remote procedure calls, specify NULL.
If the binding handle you supply refers to partially bound binding information and the binding information contains a nil object UUID, this routine returns the rpc_s_binding_incomplete status code. In this case, the DCE host daemon does not know which server instance to select from the local endpoint map because the RPC management interface is automatically registered (by the RPC runtime) for all RPC servers.
To avoid this situation, you can obtain a fully bound server binding handle by calling the rpc_ep_resolve_binding( ) routine.
Output
status
Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. status can also return
the value of parameter status from the application-defined authorization function (rpc_mgmt_authorization_fn_t). The prototype for such a function is defined in the
authorization_fn parameter in the reference page for rpc_mgmt_set_authorization_fn(3rpc).
Description
The rpc_mgmt_is_server_listening( ) routine determines whether the server specified in the binding parameter is listening for remote procedure
calls.
This routine returns a value of TRUE if the server is blocked in the rpc_server_listen( ) routine.
By default, the RPC runtime allows all clients to remotely call this routine. To restrict remote calls of this routine, a server application supplies an authorization function using the rpc_mgmt_set_authorization_fn( ) routine.
Return Values
Your program must examine the return value of the status parameter and the return value of the routine to understand the meaning of the routine value.
The following table summarizes the values that this routine can return.
| Values Returned by rpc_mgmt_is_server_listening( ) | ||
| Value Returned | Status Code | Explanation |
| TRUE | rpc_s_ok | The specified server is listening for remote procedure calls. |
| FALSE | One of the status codes listed for the status parameter | The specified server is not listening for remote procedure calls, or the server cannot be reached. |
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_binding_incomplete
Binding incomplete (no object ID and no endpoint).
rpc_s_comm_failure
Communications failure.
rpc_s_invalid_binding
Invalid binding handle.
rpc_s_mgmt_op_disallowed
Management operation disallowed.
rpc_s_wrong_kind_of_binding
Wrong kind of binding for operation.
Related Information
Functions: rpc_ep_resolve_binding(3rpc)
rpc_mgmt_set_authorization_fn(3rpc)