3.2.5.4.16 SchRpcScheduledRuntimes (Opnum 15)

  • Article

The SchRpcScheduledRuntimes method MUST return scheduled run times.

 HRESULT SchRpcScheduledRuntimes(
   [in, string] const wchar_t* path,
   [in, unique] PSYSTEMTIME start,
   [in, unique] PSYSTEMTIME end,
   [in] DWORD flags,
   [in] DWORD cRequested,
   [out] DWORD* pcRuntimes,
   [out, size_is(, *pcRuntimes)] PSYSTEMTIME* pRuntimes
 );

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

start: If non-NULL, MUST specify the start of a time interval. If NULL, the server MUST calculate scheduled runtimes from the start of time, where the start of time is the smallest time value that the specific operating system implements.

end: If non-NULL, MUST specify the end of a time interval. If NULL, the server MUST calculate scheduled runtimes to the end of time, where the end of time is the largest time value that the specific operating system implements.

flags: Unused. The client MUST specify 0, and the server MUST return an error if nonzero.

cRequested: MUST contain the number of scheduled runtimes requested.

pcRuntimes: MUST contain the number of runtimes actually returned. The server MUST NOT return more than cRequested runtimes.

pRuntimes: MUST be a pointer to an array of scheduled runtimes. The server MUST return the first pcRuntimes runtimes in the specified time interval.

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 SchRpcScheduledRuntimes call that requires the server to return the state of the scheduled instances of a task, the server MUST:

  • Return E_INVALIDARG if any of the following are true:

    • The path parameter is NULL.

    • The flags parameter is nonzero.

    • The pcRuntimes parameter is NULL.

    • The pRuntimes parameter is NULL.

    Note When passing NULL as a value for parameters, behavior can change based upon the RPC Runtime Check, as specified in RPC Runtime Check Notes (section 3.3).

  • Return the value 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 task does not exist on the server in the XML task store.

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

  • Retrieve the task definition from the XML task store and compute all the scheduled runtimes between start and end parameters, up to the number cRequested. If the start parameter is NULL, the computation MUST start at the beginning of time. If the end parameter is NULL, the computation MUST continue to the end of time.

  • The server MUST NOT compute more than cRequested scheduled runtimes and MUST compute as many scheduled runtimes as are available, up to a total of cRequested scheduled runtimes.<80>

  • The server MUST return the computed runtimes in the pRuntimes parameter.

  • The server MUST return the number of computed runtimes in the pcRuntimes parameter.

  • Depending upon the situation, the server MUST return:

    • S_OK if there were scheduled runs in the given time window and all were returned.

    • S_FALSE if there were scheduled runs in the given time window but some were not returned.

    • SCHED_S_TASK_NO_MORE_RUNS if no runs are scheduled in given time window.

    • SCHED_S_TASK_NOT_SCHEDULED if the task has no time-based triggers.