RpcNsProfileEltInqBegin
The RpcNsProfileEltInqBegin
function creates an inquiry context for viewing the elements in a profile.
#include <rpc.h>
RPC_STATUS RPC_ENTRY RpcNsProfileEltInqBegin(
|
unsigned long ProfileNameSyntax, |
|
|
unsigned char * ProfileName, |
|
|
unsigned long InquiryType, |
|
|
RPC_IF_ID * IfId, |
|
|
unsigned long VersOption, |
|
|
unsigned long MemberNameSyntax, |
|
|
unsigned char * MemberName, |
|
|
RPC_NS_HANDLE * InquiryContext |
|
|
); |
|
Parameters
ProfileNameSyntax
Specifies an
integer value that indicates the syntax of the next argument, ProfileName.
To use the
syntax specified in the registry value
HKEY_LOCAL_MACHINE\Software\Microsoft\Rpc\NameService\
DefaultSyntax, provide a value of RPC_C_NS_SYNTAX_DEFAULT.
ProfileName
Points to the
name of the profile to view.
InquiryType
Specifies an
integer value indicating the type of inquiry to perform on the profile. The
following table lists valid inquiry types:
|
Inquiry
type |
Description |
|
RPC_C_PROFILE_DEFAULT_ELT |
Searches
the profile for the default profile element, if any. The IfId, VersOption,
and MemberName arguments are ignored. |
|
RPC_C_PROFILE_ALL_ELTS |
Returns
every element from the profile. The IfId, VersOption, and MemberName
arguments are ignored. |
|
RPC_C_PROFILE_MATCH_BY_IF |
Searches
the profile for the elements that contain the interface identification
specified by the IfId and VersOption values. The MemberName
argument is ignored. |
|
RPC_C_PROFILE_MATCH_BY_MBR |
Searches
the profile for the elements that contain the member name specified by the MemberName
argument. The IfId and VersOption arguments are ignored. |
|
RPC_C_PROFILE_MATCH_BY_BOTH |
Searches
the profile for the elements that contain the interface identification and
member identified by the IfId, VersOption, and MemberName
arguments. |
IfId
Points to the
interface identification of the profile elements to be returned by the RpcNsProfileEltInqNext
routine.
The IfId
argument is used only when specifying a value of RPC_C_PROFILE_MATCH_BY_IF or
RPC_C_PROFILE_MATCH_BY_BOTH for the InquiryType argument. Otherwise, IfId
is ignored and a null value can be specified.
VersOption
Specifies how
the RpcNsProfileEltInqNext routine uses the IfId argument.
The VersOption
argument is used only when specifying a value of RPC_C_PROFILE_MATCH_BY_IF or
RPC_C_PROFILE_MATCH_BY_BOTH for the InquiryType argument. Otherwise,
this argument is ignored and a 0 value can be specified.
The following
table describes valid values for the VersOption argument.
|
Values |
Description |
|
RPC_C_VERS_ALL |
Returns
profile elements that offer the specified interface UUID, regardless of the
version numbers. For this value, specify 0 for both the major and minor
versions in IfId. |
|
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 for the minor
version in IfId. |
|
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 the IfId
contained V2.0 and the profile contained elements with V1.3, V2.0, and V2.1,
the RpcNsProfileEltInqNext routine returns the elements with V1.3 and
V2.0.) |
MemberNameSyntax
Specifies an
integer value that indicates the syntax of the next argument, MemberName,
and of the return argument MemberName in the RpcNsProfileEltInqNext
routine.
To use the
syntax specified in the registry value HKEY_LOCAL_MACHINE\Software\Microsoft\Rpc\NameService\
DefaultSyntax, provide a value of RPC_C_NS_SYNTAX_DEFAULT.
MemberName
Points to the
member name that the RpcNsProfileEltInqNext routine looks for in profile
elements.
The MemberName
argument is used only when specifying a value of RPC_C_PROFILE_MATCH_BY_MBR or
RPC_C_PROFILE_MATCH_BY_BOTH for the InquiryType argument. Otherwise, MemberName
is ignored and a null value can be specified.
InquiryContext
Returns a
pointer to a name-service handle for use with the RpcNsProfileEltInqNext
and RpcNsProfileEltInqDone routines.
Remarks
Note This DCE
function is not supported by the Microsoft Locator.
The RpcNsProfileEltInqBegin
routine creates an inquiry context for viewing the elements in a profile.
Using the InquiryType
argument, an application specifies which of the following profile elements are
to be returned from calls to the RpcNsProfileEltInqNext routine:
The default element
All elements
Elements with the specified
interface identification
Elements with the specified
member name
Elements with both the
specified interface identification and member name
Before
calling the RpcNsProfileEltInqNext routine, the application must first
call RpcNsProfileEltInqBegin to create an inquiry context.
When finished
viewing the profile elements, the application calls the RpcNsProfileEltInqDone
routine to delete the inquiry context.
Return Values
|
Value |
Meaning |
|
RPC_S_OK |
Success |
|
RPC_S_INVALID_VERS_OPTION |
Invalid
version option |
|
RPC_S_INVALID_NAME_SYNTAX |
Invalid
name syntax |
|
RPC_S_UNSUPPORTED_NAME_SYNTAX |
Unsupported
name syntax |
|
RPC_S_INCOMPLETE_NAME |
Incomplete
name |
|
RPC_S_ENTRY_NOT_FOUND |
Name-service
entry not found |
|
RPC_S_NAME_SERVICE_UNAVAILABLE |
Name
service unavailable |
See Also