RsopCreateSession method

Article
05/31/2018

The RsopCreateSession method generates planning mode data.

This method is implemented in the provider.

Syntax

static void RsopCreateSession(
  [in]  uint32 flags,
  [in]  string computerName,
  [in]  string computerSOM,
  [in]  string computerSecurityGroups[],
  [in]  string computerGPOFilters[],
  [in]  string userName,
  [in]  string userSOM,
  [in]  string userSecurityGroups[],
  [in]  string userGPOFilters[],
  [in]  string site,
  [out] string nameSpace,
  [out] uint32 hResult,
  [out] uint32 ExtendedInfo
);

Parameters

flags [in]: By default, the method filters the list of GPOs based on ACLs and other parameters. You can also specify the following values.
FLAG_NO_GPO_FILTER: GPOs are not filtered; implies the FLAG_NO_CSE_INVOKE value.
FLAG_NO_CSE_INVOKE: In planning mode, simulate the processing of policy, but do not call client-side extensions to process RSoP data.
FLAG_ASSUME_SLOW_LINK: In planning mode, RSoP processing assumes a slow link.
FLAG_LOOPBACK_MERGE: In planning mode, RSoP processing assumes merge loopback.
FLAG_LOOPBACK_REPLACE: In planning mode, RSoP processing assumes replace loopback.
FLAG_ASSUME_USER_WQLFILTER_TRUE: In planning mode, RSoP processing assumes all computer filters to be TRUE.
FLAG_ASSUME_COMP_WQLFILTER_TRUE: In planning mode, RSoP processing assumes all user filters to be TRUE.

computerName [in]

The name of the target computer account. If both this parameter and the computerSOM parameter are NULL, the method generates policy data for a user.

computerSOM [in]

The proposed fully qualified distinguished name of the new scope of management (domain or OU) of the target computer. If this parameter is NULL, the method uses the OU of the computer account.

computerSecurityGroups [in]

The proposed list of security groups to which the target computer belongs. If this parameter is NULL, the method retrieves the current list of security groups for the target computer from the DC. For more information about security groups, see Filtering the Scope of a GPO and How Security Groups are Used in Access Control.

computerGPOFilters [in]

The list of computer WMI Query Language (WQL) filter IDs whose query evaluates to TRUE.

userName [in]

The name of the target user account. If both this parameter and the userSOM parameter are NULL, the method generates policy data for a target computer.

userSOM [in]

The proposed fully qualified distinguished name of the new scope of management (domain or OU) of the target user. If this parameter is NULL, the method uses the OU of the user account.

userSecurityGroups [in]

The proposed list of security groups to which the target user belongs. If this parameter is NULL, the method retrieves the current list of security groups for the user from the DC.

userGPOFilters [in]

The list of user WQL filter IDs whose query evaluates to TRUE.

site [in]

The site name of the target computer.

nameSpace [out]

The namespace under which the RSoP data for this planning mode session is created. The computer data will be stored under "nameSpace\Computer" and the user data will be stored under "nameSpace\User". An example of a namespace would be "\\.\Root\Rsop\NS71EF4AA3_FB96_465F_AC1C_DFCF9A3E9010".

You can run the RSoP MMC snap-in to display the data in the RSoP namespace, specifying the generated namespace and the computer on which the planning mode provider was invoked. For more information, see the following Remarks section.

hResult [out]

An HRESULT that indicates the success or failure of the method. If the method succeeds, the return value is S_OK. Otherwise, the method returns one of the COM error codes defined in the Platform SDK header file WinError.h.

ExtendedInfo [out]

Currently, this parameter can have one of the following values.

RSOP_USER_ACCESS_DENIED

User RSoP data is not available to the user.

RSOP_COMPUTER_ACCESS_DENIED

Computer RSoP data is not available to the user.

Return value

This method has no return value. For more information, see the description of the hResult parameter.

Remarks

RSoP planning mode requires Windows Server.

Note that a call to RsopCreateSession can potentially take a few minutes to generate the RSoP data for both a computer and a user. It is recommended that you provide users with an indication of the method's progress, and that you allow users to cancel the method. WMI provides an asynchronous way of calling a method with the IWbemServices::ExecMethodAsync method. To use this method, an RSoP UI must supply an implementation of the IWbemObjectSink interface to IWbemServices::ExecMethodAsync. The RSoP UI can then cancel the execution of RsopCreateSession by calling the IWbemServices::CancelAsyncCall method.

While the RsopCreateSession method executes it sends updates of the outbound parameters to the IWbemObjectSink::Indicate method. When RsopCreateSession completes, it calls IWbemObjectSink::SetStatus to set the final status.

To view RSoP planning mode data, an administrator could pass the namespace returned by this method as a command-line parameter to the RSoP MMC snap-in. For example, if you run the snap-in on the computer "TestDC.example.microsoft.com", you could invoke the snap-in in the following manner:

Rsop.msc /RsopNamespace:"\\.\Root\Rsop\NS71EF4AA3_FB96_465F_AC1C_DFCF9A3E9010" /RsopTargetComp:"TestDC.example.microsoft.com"

To remotely target the RSoP snap-in to the same namespace, you could invoke the snap-in in the following manner:

Rsop.msc /RsopNamespace:"\\TestDC.example.microsoft.com\Root\Rsop\NS71EF4AA3_FB96_465F_AC1C_DFCF9A3E9010" /RsopTargetComp:"TestDC.example.microsoft.com"

For more information about running rsop.msc from the command-line, see the Windows Server Help.

Requirements


Minimum supported client	None supported
Minimum supported server	Windows Server 2008
Namespace	Root\RSOP\Computer
MOF	Rsop.mof
DLL	GPSvc.dll