NAME
rpc_mgmt_ep_elt_inq_begin - Creates an inquiry context for viewing
the elements in an 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_binding
Specifies 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 parameter 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 parameter is ignored.
inquiry_type
Specifies an integer value that indicates the type of inquiry
to perform on the local endpoint map. The following list shows
the valid inquiry types:
Valid Inquiries on Local Endpoint Maps
_____________________________________________________________________
Value Description
_____________________________________________________________________
rpc_c_ep_all_elts Returns every element from the local
endpoint map. The if_id, vers_option,
and object_uuid parameters are ignored.
rpc_c_ep_match_by_if Searches the local endpoint map for
those elements that contain the inter-
face identifier specified by the if_id
and vers_option values. The object_uuid
parameter 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 param-
eter. The if_id and vers_option parame-
ters are ignored.
rpc_c_ep_match_by_both Searches the local endpoint map for
those elements that contain the inter-
face identifier and object UUID speci-
fied by the if_id, vers_option, and
object_uuid parameters.
Specifies the interface identifier of the local endpoint map
elements to be returned by the rpc_mgmt_ep_elt_inq_next() routine.
Use this parameter only when specifying a value of
rpc_c_ep_match_by_if or rpc_c_ep_match_by_both for the
inquiry_type parameter. Otherwise, this parameter is ignored
and the value NULL can be specified.
Specifies how the rpc_mgmt_ep_elt_inq_next() routine uses the
if_id parameter. Use this parameter only when specifying a
value of rpc_c_ep_match_by_if or rpc_c_ep_match_by_both for the
inquiry_type parameter. Otherwise, this parameter is ignored
and a 0 (zero) value can be specified.
The following list presents the valid values for this parameter:
Valid values of vers_option
_____________________________________________________________________
Value Description
_____________________________________________________________________
rpc_c_vers_all Returns 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_exact Returns 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_upto Returns local endpoint map elements that
offer a version of the specified inter-
face 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 ele-
ments 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.)
Specifies the object UUID that rpc_mgmt_ep_elt_inq_next() looks
for in local endpoint map elements.
This parameter 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 parameter. Otherwise, this parameter is ignored
and you can supply NULL to specify a nil UUID.
Output
inquiry_context
Returns an inquiry context for use with the
rpc_mgmt_ep_elt_inq_next() and rpc_mgmt_ep_elt_inq_done()
routines.
status
Returns 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_ok Success.
rpc_s_invalid_inquiry_context
Invalid inquiry context.
rpc_s_invalid_inquiry_type
Invalid inquiry type.
rpc_s_invalid_vers_option
Invalid 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 parameters, 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
No value is returned.
RELATED INFORMATION
Functions: rpc_ep_register
rpc_ep_register_no_replace
rpc_ep_unregister
rpc_mgmt_ep_elt_inq_done
rpc_mgmt_ep_elt_inq_next
rpc_mgmt_ep_unregister