rpc_mgmt_ep_elt_inq_begin(3rpc)
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 interface 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 parameter. The if_id and vers_option parameters 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 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.
vers_option
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 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.) |
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.
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.
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_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.
Related Information
Functions: rpc_ep_register(3rpc)
rpc_ep_register_no_replace(3rpc)
rpc_mgmt_ep_elt_inq_done(3rpc)
rpc_mgmt_ep_elt_inq_next(3rpc)