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.

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

Remarks

Note  The Windows NT 5.0 Active Directory Service supports this function. Support is not available from the Microsoft Locator in earlier versions of NT.

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:

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.

QuickInfo

  Windows NT: Yes
  Windows CE: Unsupported.
  Header: Declared in rpcnsi.h.
  Import Library: Link with rpcns4.lib.

See Also

RpcIfInqId, RpcNsProfileEltInqDone, RpcNsProfileEltInqNext