NAME

rpc_mgmt_ep_elt_inq_begin - Creates an inquiry context for viewing the elements in a local or remote endpoint map

Used by management applications. 

SYNOPSIS

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

rpc_binding_handle_t ep_binding ,
unsigned32 inquiry_type ,
rpc_if_id_t ∗if_id ,
unsigned32 vers_option ,
uuid_t ∗object_uuid ,
rpc_ep_inq_handle_t ∗inquiry_context ,
unsigned32 ∗status );

PARAMETERS

Input

ep_bindingSpecifies the host whose local endpoint map elements you receive. To receive elements from the same host as the calling application, specify NULL.  To receive local endpoint map elements from another host, specify a server binding handle for that host. You can specify the same binding handle you are using to make other remote procedure calls. The object UUID associated with this argument must be a nil UUID.  If you specify a non-nil UUID, the routine fails with the status code ept_s_cant_perform_op.  Other than the host information and object UUID, all information in this argument is ignored. 

inquiry_typeSpecifies an integer value that indicates the type of inquiry to perform on the local endpoint map. The following table lists the valid inquiry types:

ValueDescription

rpc_c_ep_all_eltsReturns every element from the local endpoint map.  The if_id, vers_option, and object_uuid arguments are ignored. 

rpc_c_ep_match_by_if
Searches the local endpoint map for those elements that contain the interface identifier specified by the if_id and vers_option values.  The object_uuid argument is ignored. 

rpc_c_ep_match_by_obj
Searches the local endpoint map for those elements that contain the object UUID specified by the object_uuid argument.  The if_id and vers_option arguments are ignored. 

rpc_c_ep_match_by_both
Searches the local endpoint map for those elements that contain the interface identifier and object UUID specified by the if_id, vers_option, and object_uuid arguments. 

if_idSpecifies the interface identifier of the local endpoint map elements to be returned by the rpc_mgmt_ep_elt_inq_next routine.  Use this argument only when specifying a value of rpc_c_ep_match_by_if or rpc_c_ep_match_by_both for the inquiry_type argument. Otherwise, this argument is ignored and the value NULL can be specified. 

vers_optionSpecifies how the rpc_mgmt_ep_elt_inq_next routine uses the if_id argument.  Use this argument only when specifying a value of rpc_c_ep_match_by_if or rpc_c_ep_match_by_both for the inquiry_type argument. Otherwise, this argument is ignored and a 0 (zero) value can be specified.  The following list presents the valid values for this argument.

ValueDescription

rpc_c_vers_allReturns local endpoint map elements that offer the specified interface UUID, regardless of the version numbers.  For this value, specify 0 (zero) for both the major and minor versions in if_id. 

rpc_c_vers_compatible
Returns local endpoint map elements that offer the same major version of the specified interface UUID and a minor version greater than or equal to the minor version of the specified interface UUID.

rpc_c_vers_exactReturns local endpoint map elements that offer the specified version of the specified interface UUID. 

rpc_c_vers_major_only
Returns local endpoint map elements that offer the same major version of the specified interface UUID (ignores the minor version). For this value, specify 0 (zero) for the minor version in if_id. 

rpc_c_vers_uptoReturns local endpoint map elements that offer a version of the specified interface UUID less than or equal to the specified major and minor version. (For example, suppose if_id contains V2.0 and the local endpoint map contained elements with the following versions: V1.3, V2.0, and V2.1.  The rpc_mgmt_ep_elt_inq_next routine returns the elements with V1.3 and V2.0.) 

object_uuidSpecifies the object UUID that routine rpc_mgmt_ep_elt_inq_next looks for in local endpoint map elements.  This argument is used only when you specify a value of rpc_c_ep_match_by_obj or rpc_c_ep_match_by_both for the inquiry_type argument. Otherwise, this argument is ignored and you can supply NULL to specify a nil UUID. 

Output

inquiry_contextReturns an inquiry context for use with the rpc_mgmt_ep_elt_inq_next and rpc_mgmt_ep_elt_inq_done routines. 

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_inquiry_context
Invalid inquiry context.

rpc_s_invalid_inquiry_typeInvalid inquiry type. 

rpc_s_invalid_vers_optionInvalid version option. 

rpc_s_wrong_kind_of_binding
Wrong kind of binding for operation.

DESCRIPTION

The rpc_mgmt_ep_elt_inq_begin routine creates an inquiry context for viewing server address information stored in the local endpoint map. 

Using the inquiry_type and vers_option arguments, an application specifies which of the following local endpoint map elements are returned from calls to the rpc_mgmt_ep_elt_inq_next routine:

       •All elements

       •Those elements with the specified interface identifier

       •Those elements with the specified object UUID

       •Those elements with both the specified interface identifier and object UUID

Before calling the rpc_mgmt_ep_elt_inq_next routine, the application must first call this routine to create an inquiry context. 

After viewing the local endpoint map elements, the application calls the rpc_mgmt_ep_elt_inq_done routine to delete the inquiry context. 

RETURN VALUES

None. 

RELATED INFORMATION

Functions: rpc_ep_register(3), rpc_ep_register_no_replace(3), rpc_ep_unregister(3), rpc_mgmt_ep_elt_inq_done(3), rpc_mgmt_ep_elt_inq_next(3), rpc_mgmt_ep_unregister(3)