rpc_ns_profile_elt_inq_begin(3) — 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

#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_syntaxAn integer value that specifies the syntax of argument profile_name. To use the syntax specified in the RPC_DEFAULT_ENTRY_SYNTAX environment variable, provide the integer value rpc_c_ns_syntax_default.

profile_nameSpecifies the name of the profile to view. This can be either the global or cell-relative name.

inquiry_typeAn integer value that specifies the type of inquiry to perform on the profile. The following list describes the valid inquiry types:

ValueDescription

rpc_c_profile_default_eltSearches the profile for the default profile element, if any. The if_id, vers_option, and member_name arguments are ignored.

rpc_c_profile_all_eltsReturns every element from the profile. The if_id, vers_option, and member_name arguments 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 argument is ignored.

rpc_c_profile_match_by_mbr
Searches the profile for those elements that contain the member name specified by the member_name argument. The if_id and vers_option arguments 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 arguments.

if_idSpecifies the interface identifier of the profile elements to be returned by the rpc_ns_profile_elt_inq_next routine. This argument is used only when specifying a value of rpc_c_profile_match_by_if or rpc_c_profile_match_by_both for the inquiry_type argument. Otherwise, this argument is ignored and you can specify the value NULL.

vers_optionSpecifies how the rpc_ns_profile_elt_inq_next routine uses the if_id argument. This argument is used only when specifying a value of rpc_c_profile_match_by_if or rpc_c_profile_match_by_both for the inquiry_type argument. Otherwise, this argument is ignored and you can specify the value 0 (zero). The following are the valid values for this argument:

ValueDescription

rpc_c_vers_allReturns 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 argument 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_exactReturns 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 argument if_id.

rpc_c_vers_uptoReturns 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 argument if_id contains V2.0 and the profile contains elements with the versions V1.3, V2.0, and V2.1, the rpc_ns_profile_elt_inq_next routine returns the elements with V1.3 and V2.0.)

member_name_syntax
An integer value that specifies the syntax of argument member_name in this routine and the syntax of argument member_name in the rpc_ns_profile_elt_inq_next routine. To use the syntax specified in the RPC_DEFAULT_ENTRY_SYNTAX environment variable, provide the integer value rpc_c_ns_syntax_default.

member_nameSpecifies the member name that the rpc_ns_profile_elt_inq_next routine looks for in profile elements. This can be either the global or cell-relative name. This argument is used only when specifying a value of rpc_c_profile_match_by_mbr or rpc_c_profile_match_by_both for the inquiry_type argument. Otherwise, this argument is ignored and you specify the value NULL.

Output

inquiry_contextReturns a name service handle for use with the rpc_ns_profile_elt_inq_next and rpc_ns_profile_elt_inq_done routines.

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

rpc_s_incomplete_nameIncomplete name.

rpc_s_invalid_inquiry_typeInvalid inquiry type.

rpc_s_invalid_name_syntaxInvalid name syntax.

rpc_s_invalid_vers_optionInvalid version option.

rpc_s_unsupported_name_syntax
Unsupported name syntax.

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 arguments, an application specifies which of the following profile elements will be returned from calls to the rpc_ns_profile_elt_inq_next routine:

•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 the rpc_ns_profile_elt_inq_next routine, 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

None.

NOTE:

For this release, the RPC naming service (rpc_ns) routines are not implemented, nor is an independent naming service provided.

RETURN VALUES