RpcNsProfileEltInqNext

The RpcNsProfileEltInqNext function returns one element at a time from a profile.

#include <rpc.h>
RPC_STATUS RPC_ENTRY RpcNsProfileEltInqNext( 
  RPC_NS_HANDLE  InquiryContext,   
  RPC_IF_ID *  IfId,           
  unsigned char * *  MemberName,   
  unsigned long *  Priority,   
  unsigned char * *  Annotation  
);

Parameters

InquiryContext
Specifies a name-service handle returned from the RpcNsProfileEltInqBegin routine.
IfId
Returns a pointer to the interface identification of the profile element.
MemberName
Returns a pointer to a pointer to the profile element's member name.

The syntax of the returned name was specified by the MemberNameSyntax argument in the RpcNsProfileEltInqBegin routine.

Specify a null value to prevent RpcNsProfileEltInqNext from returning the MemberName argument. In this case, the application does not call the RpcStringFree routine.

Priority
Returns a pointer to the profile-element priority.
Annotation
Returns a pointer to a pointer to the annotation string for the profile element. If there is no annotation string in the profile element, the string "\0" is returned.

Specify a null value to prevent RpcNsProfileEltInqNext from returning the Annotation argument. In this case, the application does not need to call the RpcStringFree routine.

Return Values

Value Meaning
RPC_S_OK Success
RPC_S_INCOMPLETE_NAME Incomplete name
RPC_S_NAME_SERVICE_UNAVAILABLE Name service unavailable
RPC_S_NO_MORE_ELEMENTS No more elements

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 RpcNsProfileEltInqNext routine returns one element from the profile specified by the ProfileName argument in the RpcNsProfileEltInqBegin routine. Regardless of the value specified for the InquiryType argument in RpcNsProfileEltInqBegin, RpcNsProfileEltInqNext returns all the components (interface identification, member name, priority, annotation string) of a profile element.

An application can view all the selected profile entries by repeatedly calling the RpcNsProfileEltInqNext routine. When all the elements have been viewed, this routine returns a RPC_S_NO_MORE_ELEMENTS status code. The returned elements are unordered.

On each call to RpcNsProfileEltInqNext that returns a profile element, the RPC run-time library allocates memory for the returned member name and annotation string. The application is responsible for calling the RpcStringFree routine for each returned member name and annotation string.

After viewing the profile's elements, the application must call the RpcNsProfileEltInqDone routine to release the inquiry context.

QuickInfo

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

See Also

RpcNsProfileEltInqBegin, RpcNsProfileEltInqDone, RpcStringFree