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_syntax
An integer value that specifies the syntax of the
profile_name parameter. To use the syntax specified
in the RPC_DEFAULT_ENTRY_SYNTAX logical name, 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 pro-
file. The if_id, vers_option, and
member_name parameters are ignored.
rpc_c_profile_match_by_if Searches the profile for those ele-
ments 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 ele-
ments that contain the member name
specified by the member_name param-
eter. The if_id and vers_option
parameters are ignored.
rpc_c_profile_match_by_both Searches the profile for those ele-
ments that contain the interface
identifier and member name speci-
fied 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 ver-
sions 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 speci-
fied interface UUID.
rpc_c_vers_exact Returns profile elements that offer
the specified version of the speci-
fied 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 inter-
face UUID less than or equal to the
specified major and minor version.
(For example, if if_id contains
V2.0 and the profile contains ele-
ments 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 logical name, 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.
The possible status codes and their meanings are as follows:
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.
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.
RELATED INFORMATION
Functions: rpc_if_inq_id
rpc_ns_mgmt_handle_set_exp_age
rpc_ns_profile_elt_inq_done
rpc_ns_profile_elt_inq_next