rpc_ns_profile_elt_inq

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.

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)