| ## rpc_ns_profile_elt_inq_begin(3rpc) Creates an inquiry context for viewing the elements in a profile Used by client, server, or management applications. Synopsis #include <dce/rpc.h> void rpc_ns_profile_elt_inq_begin( unsigned32 profile_name_syntax, unsigned_char_t *profile_name, unsigned32 inquiry_type, rpc_if_id_t *if_id, unsigned32 vers_option, unsigned32 member_name_syntax, unsigned_char_t *member_name, rpc_ns_handle_t *inquiry_context, unsigned32 *status); Parameters Input profile_name_syntax An integer value that specifies the syntax of the profile_name parameter. To use the syntax specified in the RPC_DEFAULT_ENTRY_SYNTAX environment variable, provide rpc_c_ns_syntax_default. profile_name Specifies the name of the profile to view. This can be either the global or cell-relative name. inquiry_type An integer value that specifies the type of inquiry to perform on the profile. The following table describes the valid inquiry types:
Valid Values of inquiry_ type
Value | Description
rpc_c_profile_default_elt | Searches the profile for the default profile element, if any. The if_id, vers_option, and member_name parameters are ignored.
rpc_c_profile_all_elts | Returns every element from the profile. The if_id, vers_option, and member_name parameters are ignored.
rpc_c_profile_match_by_if | Searches the profile for those elements that contain the interface identifier specified by the if_id and vers_option values. The member_name parameter is ignored.
rpc_c_profile_match_by_mbr | Searches the profile for those elements that contain the member name specified by the member_name parameter. The if_id and vers_option parameters are ignored.
rpc_c_profile_match_by_both | Searches the profile for those elements that contain the interface identifier and member name specified by the if_id , vers_option , and member_name parameters.
if_id Specifies the interface identifier of the profile elements to be returned by rpc_ns_profile_elt_inq_next( ). This parameter is used only when specifying a value of either rpc_c_profile_match_by_if or rpc_c_profile_match_by_both for the inquiry_type parameter. Otherwise, this parameter is ignored and you can specify the value NULL. vers_option Specifies how rpc_ns_profile_elt_inq_next( ) uses the if_id parameter. This parameter is used only when specifying a value of either rpc_c_profile_match_by_if or rpc_c_profile_match_by_both for the inquiry_type parameter. Otherwise, this parameter is ignored and you can specify the value 0 (zero). The following table describes the valid values for this parameter:
Valid Values of vers_option
Value | Description
rpc_c_vers_all | Returns profile 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 profile 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 profile elements that offer the specified version of the specified interface UUID.
rpc_c_vers_major_only | Returns profile 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 profile elements that offer a version of the specified interface UUID less than or equal to the specified major and minor version. (For example, if if_id contains V2.0 and the profile contains elements with the versions V1.3, V2.0, and V2.1, rpc_ns_profile_elt_inq_next( ) returns the elements with V1.3 and V2.0.)
member_name_syntax An integer value that specifies the syntax of the member_name parameter in this routine and the syntax of the member_name parameter in rpc_ns_profile_elt_inq_next( ). To use the syntax specified in the RPC_DEFAULT_ENTRY_SYNTAX environment variable, provide rpc_c_ns_syntax_default. member_name Specifies the member name that rpc_ns_profile_elt_inq_next( ) looks for in profile elements. This can be either the global or cell-relative name. This parameter is used only when specifying a value of either rpc_c_profile_match_by_mbr or rpc_c_profile_match_by_both for the inquiry_type parameter. Otherwise, this parameter is ignored and you specify the value NULL. Output inquiry_context Returns a name service handle for use with the rpc_ns_profile_elt_inq_next( ) and rpc_ns_profile_elt_inq_done( ) routines. status Returns the status code from this routine, indicating indicates whether the routine completed successfully or, if not, why not. Description The rpc_ns_profile_elt_inq_begin( ) routine creates an inquiry context for viewing the elements in a profile. Using the inquiry_type and vers_option parameters, an application specifies which of the following profile elements will be returned from calls to rpc_ns_profile_elt_inq_next( ): · The default element. · All elements. · Those elements with the specified interface identifier. · Those elements with the specified member name. · Those elements with both the specified interface identifier and member name. Before calling rpc_ns_profile_elt_inq_next( ), the application must first call this routine to create an inquiry context. When finished viewing the profile elements, the application calls the rpc_ns_profile_elt_inq_done( ) routine to delete the inquiry context. Permissions Required No permissions are required. 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_incomplete_name Incomplete name. rpc_s_invalid_inquiry_type Invalid inquiry type. rpc_s_invalid_name_syntax Invalid name syntax. rpc_s_invalid_vers_option Invalid version option. rpc_s_unsupported_name_syntax Unsupported name syntax. Related Information Functions: rpc_if_inq_id(3rpc) rpc_ns_mgmt_handle_set_exp_age(3rpc) rpc_ns_profile_elt_inq_done(3rpc) rpc_ns_profile_elt_inq_next(3rpc) ##