3.2.5.4.10 SchRpcGetInstanceInfo (Opnum 9)

  • Article

The SchRpcGetInstanceInfo method MUST get information about an instance of a running task.

 HRESULT SchRpcGetInstanceInfo(
   [in] GUID guid,
   [out, string] wchar_t** pPath,
   [out] DWORD* pState,
   [out, string] wchar_t** pCurrentAction,
   [out, string] wchar_t** pInfo,
   [out] DWORD* pcGroupInstances,
   [out, size_is(, *pcGroupInstances)] 
     GUID** pGroupInstances,
   [out] DWORD* pEnginePID
 );

guid: MUST contain the GUID of the running task instance.

pPath: MUST be the location where a string containing the task's path is to be returned in the format specified in section 2.3.11. If NULL, specifies that the path is not requested.

pState: Location where the state of the instance (section 2.3.13) is to be returned. If NULL, specifies that the state is not requested.

pCurrentAction: MUST be the location where the name (id) of the action the task is currently executing is to be returned. If NULL, specifies that the current action is not requested.

pInfo: Unused. If non-NULL, the server MUST set the string to NULL.

pcGroupInstances: Unused.

pGroupInstances: Unused. If non-NULL, the server MUST set the GUID to NULL.

pEnginePID: MUST be the location where the Process ID of the process executing the task is to be returned. If NULL, specifies that the Process ID is not requested.

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 SchRpcGetInstanceInfo, the server MUST:

  • Return SCHED_E_TASK_NOT_RUNNING if there is no entry in the running task list with an instance ID matching the guid parameter.

  • Return E_ACCESSDENIED if the caller does not have read access to the task.

  • Return the path of the task instance in the pPath parameter.

  • Return the state of the task instance in the pState parameter.

  • If the state is TASK_STATE_RUNNING, return the action of the task instance in the pCurrentAction parameter. Otherwise, return NULL in the pCurrentAction parameter.

  • Return NULL in the location pointed to by the pInfo parameter, if pInfo is non-NULL.

  • Return 0x00000000 in the location pointed to by the pcGroupInstances parameter, if pcGroupInstances is non-NULL.

  • Return NULL in the location pointed to by the pGroupInstances parameter, if pGroupInstances is non-NULL.

  • Return the PID of the task instance in the location pointed to by the pEnginePID parameter, if pEnginePID is non-NULL.

  • Return S_OK.