Edit

Share via

RpcNsProfileEltInqBeginA function (rpcnsi.h)

  • Article

The RpcNsProfileEltInqBegin function creates an inquiry context for viewing the elements in a profile.

Note  This function is not supported on Windows Vista and later operating systems.
 

Syntax

RPC_STATUS RpcNsProfileEltInqBeginA(
  unsigned long ProfileNameSyntax,
  RPC_CSTR      ProfileName,
  unsigned long InquiryType,
  RPC_IF_ID     *IfId,
  unsigned long VersOption,
  unsigned long MemberNameSyntax,
  RPC_CSTR      MemberName,
  RPC_NS_HANDLE *InquiryContext
);

Parameters

ProfileNameSyntax

Syntax of ProfileName.

To use the syntax specified in the registry value entry HKEY_LOCAL_MACHINE\Software\Microsoft\Rpc\NameService\DefaultSyntax, provide a value of RPC_C_NS_SYNTAX_DEFAULT.

ProfileName

Pointer to the name of the profile to view.

InquiryType

Type of inquiry to perform on the profile. The following table lists valid inquiry types.

Inquiry type Meaning
RPC_C_PROFILE_DEFAULT_ELT
 Searches the profile for the default profile element, if any. The IfId, VersOption, and MemberName parameters are ignored.
RPC_C_PROFILE_ALL_ELTS
 Returns every element from the profile. The IfId, VersOption, and MemberName parameters are ignored.
RPC_C_PROFILE_MATCH_BY_IF
 Searches the profile for elements that contain the interface identification specified by IfId and VersOption. The MemberName parameter is ignored.
RPC_C_PROFILE_MATCH_BY_MBR
 Searches the profile for elements that contain MemberName. The IfId and VersOption parameters are ignored.
RPC_C_PROFILE_MATCH_BY_BOTH
 Searches the profile for elements that contain the interface identification and member identified by the IfId, VersOption, and MemberName parameters.

IfId

Pointer to the interface identification of the profile elements to be returned by the RpcNsProfileEltInqNext function.

The IfId parameter is used only when specifying a value of RPC_C_PROFILE_MATCH_BY_IF or RPC_C_PROFILE_MATCH_BY_BOTH for the InquiryType parameter. Otherwise, IfId is ignored and a null value can be specified.

VersOption

Specifies how the RpcNsProfileEltInqNext function uses the IfId parameter. This parameter is used only when specifying a value of RPC_C_PROFILE_MATCH_BY_IF or RPC_C_PROFILE_MATCH_BY_BOTH for InquiryType. Otherwise, this parameter is ignored and a 0 value can be specified.

The following table describes valid values for VersOption.

Value Meaning
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 function returns elements with V1.3 and V2.0.)

MemberNameSyntax

Syntax of MemberName, and the return parameter MemberName in the RpcNsProfileEltInqNext function.

To use the syntax specified in the registry value entry HKEY_LOCAL_MACHINE\Software\Microsoft\Rpc\NameService\DefaultSyntax, provide a value of RPC_C_NS_SYNTAX_DEFAULT.

MemberName

Pointer to the member name that the RpcNsProfileEltInqNext function looks for in profile elements. The MemberName parameter is used only when specifying a value of RPC_C_PROFILE_MATCH_BY_MBR or RPC_C_PROFILE_MATCH_BY_BOTH for InquiryType. 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 functions.

Return value

Value Meaning
RPC_S_OK
 The call succeeded.
RPC_S_INVALID_VERS_OPTION
 The version option is invalid.
RPC_S_INVALID_NAME_SYNTAX
 The name syntax is invalid.
RPC_S_UNSUPPORTED_NAME_SYNTAX
 The name syntax is not supported.
RPC_S_INCOMPLETE_NAME
 The name is incomplete.
RPC_S_ENTRY_NOT_FOUND
 The name-service entry was not found.
RPC_S_NAME_SERVICE_UNAVAILABLE
 The name service is unavailable.
 
Note  For a list of valid error codes, see RPC Return Values.
 

Remarks

The RpcNsProfileEltInqBegin function creates an inquiry context for viewing the elements in a profile.

Using the InquiryType parameter, an application specifies which of the following profile elements are to be returned from calls to RpcNsProfileEltInqNext:

  • 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 RpcNsProfileEltInqNext, the application must first call RpcNsProfileEltInqBegin to create an inquiry context.

When finished viewing the profile elements, the application calls the RpcNsProfileEltInqDone function to delete the inquiry context.

Note  Windows 2000 Active Directory supports this function. Earlier versions of Windows NT support the use of this function with Cell Directory Service (CDS) only.
 

Note

The rpcnsi.h header defines RpcNsProfileEltInqBegin as an alias which automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.

Requirements

Requirement Value
Minimum supported client Windows 2000 Professional [desktop apps only]
Minimum supported server Windows 2000 Server [desktop apps only]
Target Platform Windows
Header rpcnsi.h (include Rpc.h)
Library Rpcns4.lib
DLL Rpcns4.dll

See also

RpcIfInqId

RpcNsProfileEltInqDone

RpcNsProfileEltInqNext