rpc_ns_profile_elt_inq_begin(3rpc) — Subroutines

NAME

rpc_ns_profile_elt_inq_begin — Creates an inquiry context for viewing the elements in a profile; used by client, server, or management applications

Synopsis

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 that is 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_idSpecifies 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 parametr in rpc_ns_profile_elt_inq_next(). To use the syntax that is 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 following routines:

•rpc_ns_profile_elt_inq_next()

•rpc_ns_profile_elt_inq_done()

statusReturns 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).

Museum