rpc_mgmt_ep_elt_inq_next(3rpc)
Returns one element from an endpoint map
Used by management applications.
Synopsis
#include <dce/rpc.h>
void rpc_mgmt_ep_elt_inq_next(
rpc_ep_inq_handle_t inquiry_context,
rpc_if_id_t *if_id,
rpc_binding_handle_t *binding,
uuid_t *object_uuid,
unsigned_char_t **annotation,
unsigned32 *status);
Parameters
Input
inquiry_context
Specifies an inquiry context. This inquiry context is returned from the rpc_mgmt_ep_elt_inq_begin( ) routine.
Output
if_id
Returns the interface identifier of the local endpoint map element.
binding
Returns the binding handle from the local endpoint map element.
Specify NULL to prevent the routine from returning this parameter. In this case the application does not call the rpc_binding_free( ) routine.
object_uuid
Returns the object UUID from the local endpoint map element.
Specify NULL to prevent the routine from returning this parameter.
annotation
Returns the annotation string for the local endpoint map element. If there is no annotation string in the local endpoint map element, the string \0 is
returned.
Specify NULL to prevent the routine from returning this argument. In this case the application does not call the rpc_string_free( ) routine.
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_mgmt_ep_elt_inq_next( ) routine returns one element from the local endpoint map. Regardless of the selector value specified for the
inquiry_type parameter in rpc_mgmt_ep_elt_inq_begin( ), this routine returns all the components of a selected local endpoint map element. The rpc_ep_register( ) routine's
reference page summarizes the contents of an element in the local endpoint map.
An application can view all the selected local endpoint map elements by repeatedly calling the rpc_mgmt_ep_elt_inq_next( ) routine. When all the elements have been viewed, this routine returns an rpc_s_no_more_elements status. The returned elements are unordered.
If a remote endpoint map contains elements that include a protocol sequence that your system does not support, this routine does not return the elements. (A protocol sequence is part of the binding information component of an endpoint map element.) To receive all possible elements from a remote endpoint map, your application must run on a system that supports the protocol sequences included in the elements.
For example, if your system does not support protocol sequence ncacn_ip_tcp and a remote endpoint map contains elements that include this protocol sequence, this routine does not return these elements to your application. If your application ran on a system that supported protocol sequence ncacn_ip_tcp, this routine would return the elements.
The RPC runtime allocates memory for the returned binding and the annotation string on each call to this routine. The application calls the rpc_binding_free( ) routine for each returned binding and the rpc_string_free( ) routine for each returned annotation string.
After viewing the local endpoint map's elements, the application must call the rpc_mgmt_ep_elt_inq_done( ) routine to delete the inquiry context.
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.
ept_s_cant_perform_op
Cannot perform the requested operation.
rpc_s_comm_failure
Communications failure.
ept_s_database_invalid
Endpoint map database invalid.
rpc_s_fault_context_mismatch
Fault context mismatch.
ept_s_invalid_context
Invalid inquiry type for this context.
ept_s_invalid_entry
Invalid database entry.
rpc_s_invalid_arg
Invalid argument.
rpc_s_invalid_inquiry_context
Invalid inquiry context.
rpc_s_invalid_inquiry_type
Invalid inquiry type.
rpc_s_no_more_elements
No more elements.
Related Information
Functions: rpc_binding_free(3rpc)
rpc_ep_register_no_replace(3rpc)
rpc_mgmt_ep_elt_inq_begin(3rpc)
rpc_mgmt_ep_elt_inq_done(3rpc)