3.2.5.4.13 SchRpcRun (Opnum 12)

  • Article

The SchRpcRun method MUST run a task specified by a path.

 HRESULT SchRpcRun(
   [in, string] const wchar_t* path,
   [in] DWORD cArgs,
   [in, string, size_is(cArgs), unique] 
     const wchar_t** pArgs,
   [in] DWORD flags,
   [in] DWORD sessionId,
   [in, unique, string] const wchar_t* user,
   [out] GUID* pGuid
 );

path: MUST be the full path to a task using the format specified in section 2.3.11.

cArgs: MUST be the number of strings supplied in pArgs.

pArgs: MUST be an array of strings of size cArgs. This parameter MUST supply string values for parameter substitution, as specified in section 2.5.9.

flags: The flags field MUST contain individual bit flags that MUST have one or more of the following values.


0


1


2


3


4


5


6


7


8


9

1
0


1


2


3


4


5


6


7


8


9

2
0


1


2


3


4


5


6


7


8


9

3
0


1

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

U S

S
I

I
C

A S

Flags

Value

Description

AS

TASK_RUN_AS_SELF

If set to 1, the server MUST run the task in the context of the caller.

IC

TASK_RUN_IGNORE_CONSTRAINTS

If set to 1, the server MUST ignore the conditions in the task definition.

SI

TASK_RUN_USE_SESSION_ID

If set to 1, the server MUST run the task in the login session specified by the sessionId parameter.

US

TASK_RUN_USER_SID

If set to 1, the userId parameter MUST contain a SID string.

Undefined bits MUST be set to 0 when sent and the server MUST return an error if undefined bits are set to 1.

sessionId: MUST specify a terminal server session in which to run the task. The server MUST ignore this parameter unless the TASK_RUN_USE_SESSION_ID bit in the flags parameter is set. For more information on terminal server sessions, see [MSDN-WSI].

user: If non-NULL, MUST specify the user context under which to run the task. If the TASK_RUN_USER_SID bit in the flags parameter is set, userID MUST contain a SID string. Otherwise, userID MUST contain an account name. If the TASK_RUN_AS_SELF bit in the flag parameter is set, the server MUST ignore the userId parameter.

pGuid: MUST contain a GUID for the task instance created as result of this call.

Return Values: For more information on return codes, see section 2.3.14, or Win32 Error Codes in [MS-ERREF] section 2.1.

Upon receipt of the SchRpcRun call, the server MUST:

  • Return E_INVALIDARG if any bits other than TASK_RUN_AS_SELF, TASK_RUN_IGNORE_CONSTRAINTS, TASK_RUN_USE_SESSION_ID, or TASK_RUN_USER_SID are set in the flags parameter.

  • Return E_ACCESSDENIED if the caller does not have read or execute access to the path in the XML task store.

  • Return 0x8007007B, the HRESULT form of the Win32 error ERROR_INVALID_NAME, if the specified path is not in the format specified in section 2.3.11.

  • Return the value 0x80070003, the HRESULT form of the Win32 error ERROR_PATH_NOT_FOUND, if the specified path does not exist on the server in the XML task store.

  • Return the HRESULT form of the Win32 error ERROR_FILE_NOT_FOUND if the specified file does not exist on the server in the XML task store.

  • Return SCHED_E_START_ON_DEMAND if the task's definition does not specify AllowStartOnDemand (section 2.5.4.1).

  • Return SCHED_E_TASK_DISABLED if the value of the enabled/disabled Boolean associated with the task in the task store is disabled.

  • Return S_OK but not start the task if the task's conditions (DisallowStartIfOnBatteries, RunOnNetworkAvailable, RunOnlyIfIdle; see section 2.5.4) do not allow the task to be started, unless the TASK_RUN_IGNORE_CONSTRAINTS bit is set in the flags parameter.

  • Return E_INVALIDARG if the caller does not have administrative privileges on the server and the caller is not the task's registered user unless the TASK_RUN_AS_SELF bit is set in the flags parameter.

  • Return E_INVALIDARG if the TASK_RUN_USE_SESSION_ID bit is set in the flags parameter and the caller does not have administrative privileges on the server and the user specified in the userId parameter is not the user running in the logon session identified by the sessionId parameter.

  • Return E_INVALIDARG if both the TASK_RUN_USE_SESSION_ID and TASK_RUN_AS_SELF bits are set in the flags parameter and the caller does not have administrative privileges on the server and the caller is not the user running in the logon session identified by the sessionId parameter.

  • Return RPC_E_INVALID_PARAMETER if pArgs is not of the size specified by cArgs.

  • Select the user to be used to run the task:

    • If a user is specified in the userId parameter, use that.

    • Otherwise, if the TASK_RUN_AS_SELF bit is set in the flags parameter, use the caller's identity.

    • Otherwise, if the TASK_RUN_USE_SESSION_ID bit is set in the flags parameter, use the user in the logon session identified by the sessionId parameter.

    • Otherwise, use the user in the task's XML definition.

  • Parameterize the task definition by modifying specific fields in the task XML definition using the cArgs and pArgs parameters, as specified in section 2.5.9.

  • Start the task using the selected user (section 3.2.5.1.2).

  • Return S_FALSE upon failure.

  • Return S_OK upon success.

    S_OK is also returned when the Task Scheduler service attempted to run the task, but the task did not run due to one of the constraints in the task definition and the TASK_RUN_IGNORE_CONSTRAINTS bit was not set to ignore those conditions. Constraints in the task definition include DisallowStartIfOnBatteries, RunOnNetworkAvailable, and RunOnlyIfIdle.

    S_OK is also returned if another instance of the task is already running, and a new instance was not started due to the IgnoreNew condition being set in the multiple instance policy specified in section 2.5.4.3.

If any errors are raised during the processing, they are returned. For more information about return codes, see section 2.3.14 and Win32 Error Codes in [MS-ERREF] section 2.1.