3.2.5.4.2 SchRpcRegisterTask (Opnum 1)

  • Article

The SchRpcRegisterTask method MUST register a task with the server.

 HRESULT SchRpcRegisterTask(
   [in, string, unique] const wchar_t* path,
   [in, string] const wchar_t* xml,
   [in] DWORD flags,
   [in, string, unique] const wchar_t* sddl,
   [in] DWORD logonType,
   [in] DWORD cCreds,
   [in, size_is(cCreds), unique] const TASK_USER_CRED* pCreds,
   [out, string] wchar_t** pActualPath,
   [out] PTASK_XML_ERROR_INFO* pErrorInfo
 );

path: MUST contain the full path associated (or to be associated) with a task as specified in section 2.3.11. A NULL path indicates that the server SHOULD either take the path from the task definition or generate a path itself.

xml: MUST contain the task definition in XML format as specified in section 2.5.

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

I
R

D A

D I

U P

C R

V O

Value

Description

VO

TASK_VALIDATE_ONLY

If set to 1, the server MUST only validate the task definition and not actually register the task.

CR

TASK_CREATE

If set to 1, the server MUST register the task if the task does not already exist.

UP

TASK_UPDATE

If set to 1, the server MUST update the task if the task already exists.

DI

TASK_DISABLE

If set to 1, the server MUST disable the task.

DA

TASK_DONT_ADD_PRINCIPAL_ACE

If set to 1, the server MUST NOT add an 'Allow' access control entry (ACE) for the task principal to the task's security descriptor.

IR

TASK_IGNORE_REGISTRATION_TRIGGERS

If set to 1, the server MUST NOT start the task after registering it, even if it has registration triggers.

Undefined bits. MUST be set to zero when sent and MUST be ignored on receipt.<66>

sddl: MUST be a security descriptor in SDDL format as specified in [MS-DTYP]. A NULL value MUST specify that the task inherits its security descriptor from its folder, when creating a new task, or that the task's security descriptor does not change when updating an existing task.

logonType: MUST contain a TASK_LOGON_TYPE value (section 2.3.9). The server MUST reject invalid values. The specified logonType SHOULD correspond to the type of principal used in the xml task definition, or supplied in pCreds.

cCreds: MUST contain the number of credentials passed in pCreds parameter. Client MUST set to 0 or 1, and the server MUST return an error if not 0 or 1.

pCreds: MUST be an array of credentials for the task with cCreds entries. pCreds MUST be NULL if cCreds is 0. See section 2.3.8 for details of the TASK_USER_CRED structure.

pActualPath: If this parameter is non-NULL, the server MUST return the task's actual path.

pErrorInfo: If this parameter is non-NULL and the XML task definition is invalid, the server MUST return additional error information.

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

Upon receipt of the SchRpcRegisterTask call, the server MUST:

  • Return E_INVALIDARG (0x80070057) if any of the parameters contain invalid values.

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

  • Parse the task definition contained in the xml parameter (section 2.4.2.11).

    • If any errors are found and the pErrorInfo parameter is non-NULL, MUST return extended error information in a TASK_XML_ERROR_INFO structure (section 2.4) in the pErrorInfo parameter.

    • Finally, the server MUST return one of the following error codes (section 2.3.14):

      • SCHED_E_UNEXPECTEDNODE

      • SCHED_E_NAMESPACE

      • SCHED_E_INVALIDVALUE

      • SCHED_E_MISSINGNODE

      • SCHED_E_TOO_MANY_NODES

      • SCHED_E_MALFORMEDXML

  • If the TASK_VALIDATE_ONLY flag is set in the flags parameter, return S_OK.

  • Take one of the following actions, depending upon the supplied task xml:

    • Registration (section 2.5.2):

      • Version: The server MUST return an error if the task definition uses a feature that is not compatible with the version (see section 3.2.5.4.2).

      • URI: If not specified, the server saves the task in the task store's root folder.

      • Security Descriptor: If present apply security description to the task, otherwise secure the task as follows: Task creator/owner has full control on the task configuration and Administrators have read and delete permissions.

    • Triggers (section 2.5.3):

      • For each trigger, independently of its type (section 2.5.3.1), apply:

        • StartBoundary: If present, the server MUST NOT start the task before this time/date value.

        • EndBoundary: If present, the server MUST NOT start the task after this time/date value.

        • Enabled: If the field is not present or the value is TRUE, the trigger is enabled and the server MUST start the task when this trigger occurs. If FALSE, the trigger is disabled and the server MUST ignore the trigger when determining whether to run the task.

        • ExecutionTimeLimit: If specified, the server MUST limit the task's execution time—when triggered by this particular trigger—to the specified duration. If not present, the server MUST limit the task's execution time to 72 hours for this particular trigger.

        • Interval: If specified, the server MUST start the task at the time specified by the trigger, and then restart the task at the intervals specified by this field, calculated from the trigger start time.

        • Duration: If not present, the server MUST use the value of 1 day for Duration.

        • StopAtDurationEnd: If the field has the value TRUE, the server MUST stop all running task instances at the end of the Duration.

      • BootTrigger (section 2.5.3.2): If present, the BootTrigger specifies that the server MUST start the task at operating system startup, after the ATSvc server initializes.

        • BootTrigger's Delay: If specified, the server MUST delay starting the task after boot (ATSvc start-up) by the delay value. If not present, the server MUST NOT delay starting the task.

      • RegistrationTrigger (section 2.5.3.3): If present, the RegistrationTrigger specifies that the server MUST start the task immediately when it is registered on the system.

        • RegistrationTrigger's Delay: If present, server MUST delay starting the task after task registration by the delay value. If not present, the server MUST NOT delay starting the task.

      • IdleTrigger (section 2.5.3.4): If specified, the server MUST start the task when the machine becomes idle, as specified in section 3.2.4.2.

      • TimeTrigger (section 2.5.3.5): If present, the TimeTrigger specifies that the server MUST start the task at the specified StartBoundary time.

        • TimeTrigger's RandomDelay: The server MUST choose a delay value randomly and delay starting the task after the time trigger fires by the random delay value. The random delay value MUST be chosen from the interval from zero to RandomDelay, inclusive. If not present, the server MUST NOT delay starting the task.

      • EventTrigger (section 2.5.3.6): If present, the EventTrigger specifies that the server MUST start the task upon occurrence of an event matching an event subscription query, as specified in [MS-EVEN6] section 2.2.14, or on the occurrence of a number of events of the same type (same EventId) in a given period of time. The server MUST accept queries for multiple event types, up to and including an entire event channel ([MS-EVEN6] section 3.1.1.4).

        • EventTrigger's NumberOfIOccurences: If EventTrigger is present but if the NumberOfOccurences field is not present, the server MUST fire the trigger after the first occurrence.

        • EventTrigger's Delay: If specified, the server MUST delay starting the task after event occurrence by the delay value. If not present, the server MUST NOT delay starting the task.

        • NumberOfOccurrences: If specified, the server MUST fire the trigger after NumberOfOccurrences occurrences of the MatchingElement query (subject to the PeriodOfOccurrence field; see the following field). If this field is not present, the server MUST fire the trigger after the first occurrence.

        • PeriodOfOccurences: If specified, the server MUST NOT count occurrences of the MatchingElement query that occurred prior to the last PeriodOfOccurrence time period.

        • MatchingElement: If present, the server MUST count occurrences of events that match the Subscription query and contain this field name. For more information, see [MS-EVEN6] section 3.1.4.31.

        • ValueQueries: If present, when an event matches the subscription and fires the trigger, the server MUST retrieve the element values from the event for task action parameterization as specified in section 2.5.9. If not present, the server MUST NOT perform parameterization for this task trigger.

      • LogonTrigger (section 2.5.3.7): If present, the LogonTrigger specifies that the server MUST start the task at user logon.

        • LogonTrigger's UserId filed: If LogonTrigger is present and UserId is not present then server MUST start the task for any user at logon.

        • LogonTrigger's Delay: If present, the server MUST delay starting the task after Logon by the delay value. If not present, the server MUST NOT delay starting the task.

      • SessionStateChangeTrigger (section 2.5.3.8): If present, this trigger specifies that the server MUST start the task when one of the following system changes occurs: ConsoleConnect, ConsoleDisconnect, RemoteConnect, RemoteDisconnect, SessionLock, SessionUnlock.<67>

        • SessionStateChangeTrigger's UserId: If UserId is not present then server MUST start the task for any user at session change event.

        • SessionStateChangeTrigger's Delay: The server MUST delay starting the task after the SessionStateChangeTrigger by the delay value. If not present, the server MUST NOT delay starting the task.<68>

      • CalendarTrigger (section 2.5.3.9): If present, the CalendarTrigger specifies that the server MUST start the task on the specified days.

        • ScheduleByDay: If specified, server MUST run the task every day or every X number of days as specified by the DaysInterval subfield.

          • CalendarTrigger's ScheduleByDay DaysInterval: If CalendarTrigger ScheduleByDay is specified but DaysInterval is not present, the server MUST run the task every day.

        • ScheduleByWeek: If present, this field specifies that the server MUST run the task every week or every X  number of weeks as specified by the WeeksInterval subfield, or on specific days of the week as specified by the DaysOfWeek subfield.

          • CalendarTrigger's ScheduleByWeek WeeksInterval: If CalendarTrigger ScheduleByWeek is specified but WeeksInterval is not present, the server MUST run the task every week.

          • CalendarTrigger's ScheduleByWeek DaysOfWeek: If CalendarTrigger ScheduleByWeek is specified but the DaysOfWeek field is not present or none of the seven subfields are present, the server MUST return SCHED_E_MISSINGNODE (0x80041319).

        • ScheduleByMonth: If present, this field specifies that the server MUST run the task on the days specified by the DaysOfMonth subfield, on specific months as specified by the Months subfield.

          • CalendarTrigger's ScheduleByMonth DaysOfMonth: If CalendarTrigger ScheduleByMonth is specified but the DaysOfMonth field is not present, or no Day subfields are present, the server MUST return SCHED_E_MISSINGNODE (0x80041319).

          • CalendarTrigger's ScheduleByMonth Months: If CalendarTrigger ScheduleByMonth is specified but the Months field is not present, the server MUST run the task every month.  If CalendarTrigger ScheduleByMonth is specified and the Months field is present but none of the twelve subfields are present, the server MUST return SCHED_E_MISSINGNODE (0x80041319).

        • ScheduleByMonthDayOfWeek: If present, this field specifies that the server MUST run the task on the weeks specified by the Weeks subfield, on specific days of the week as specified by the DaysOfWeek subfield, on specific months as specified by the Months subfield.

          • CalendarTrigger's ScheduleByMonthDayOfWeek Weeks: If CalendarTrigger ScheduleByMonthDayOfWeek is specified but the Weeks field is not present or no Week subfields are present, the server MUST return SCHED_E_MISSINGNODE (0x80041319).

          • CalendarTrigger's ScheduleByMonthDayOfWeek DaysOfWeek: If the CalendarTrigger ScheduleByMonthDayOfWeek is specified but the DaysOfWeek field is not present or none of the seven subfields are present, the server MUST return SCHED_E_MISSINGNODE (0x80041319).

          • CalendarTrigger's ScheduleByMonthDayOfWeek Months: If the CalendarTrigger ScheduleByMonthDayOfWeek is specified but the Months field is not present, the server MUST run the task every month.  If CalendarTrigger ScheduleByMonthDayOfWeek is specified and the Months field is present but none of the twelve subfields are present, the server MUST return SCHED_E_MISSINGNODE (0x80041319).

    • Settings (section 2.5.4): The server MUST check machine conditions (running on batteries, network available, idle) according to the settings (DisallowStartIfOnBatteries, RunOnNetworkAvailable, RunOnlyIfIdle) once the trigger occurs to determine if the task is to be started. The task will run only if the conditions at the time the trigger fires match the settings defined.

      • MultipleInstancesPolicy conditions:

        • Parallel: Specifies that the server MUST start multiple instances of the task in parallel for each occurring trigger.

        • Queue: If present, specifies that execution instances related to this trigger MUST start serially, on the completion of the previous instance.

        • IgnoreNew: If present, specifies that the server MUST ignore all additional triggers occurring during the execution of an instance.

        • StopExisting: If present, specifies that the server MUST stop the running instance and start a new instance on any additional trigger occurrence. If not present, the server MUST use the value IgnoreNew for MultipleInstancesPolicy.

      • DisallowStartIfOnBatteries: The server MUST NOT start the task if the computer is running on batteries, unless this field is present and set to FALSE.

      • StopIfGoingOnBatteries: The server MUST stop the task if the computer switches to battery or Uninterrupted Power Supply (UPS) power, unless this field is present and set to FALSE.

      • AllowHardTerminate: The server MUST forcibly stop the task if it exceeds its absolute execution time limit, unless this field is present and set to FALSE.

      • StartWhenAvailable: If present and set to TRUE, this field specifies that the server MUST start the task when the computer becomes available if a scheduled run time was missed.

      • RunOnNetworkAvailable: If present and set to TRUE, this field specifies that the server MUST start the task only if a network connection is available.

      • NetworkSettings: If present, the server MUST ignore the NetworkSettings field unless the RunOnNetworkAvailable field (section 2.5.4.8) is present and set to TRUE.<69>

        • NetworkSetting's Name or Id: The server MUST start the task only if a network connection to the specified network is available.

      • WakeToRun: If present and set to TRUE, this field specifies that the server MUST wake from power-suspended mode (standby or hibernate) to run the task.

      • Enabled: If present and set to FALSE, this field specifies that the server MUST NOT run the task.Hidden: If present and set to TRUE, this field specifies that the server SHOULD NOT show the task in an administrative console or graphic user interface.

      • DeleteExpiredTaskAfter: The server MUST delete the task (after this delay) when it has no future scheduled run times.

      • IdleSettings: If present, this field specifies that the server MUST run the task only when the machine has been idle for the value of the Duration subfield. The server MUST ignore the IdleSettings field, unless the RunOnlyIfIdle field, which MUST be specified as in section 2.5.4.18, is present and has the value TRUE.

        • IdleSettings Duration: The server MUST delay starting the task until the specified Duration has elapsed from the time that the machine became idle.

      • MaintenanceSettings: If present, this field specifies that the server MUST run the task during the regular maintenance periods with the periodicity defined by the Period field. The server MUST reject tasks with the MaintenanceSettings field unless the UseUnifiedSchedulingEngine field (as specified in section 2.5.4.19) is present and has the value TRUE.

        • MaintenanceSettings Period: The server MUST run the task during the regular machine maintenance periods only if the task previously run finished running before the beginning of the preceding Period time ago.

        • MaintenanceSettings Deadline: If present, and the Period time was missed, the server MUST run the task during machine idle.

        • MaintenanceSettings Exclusive: If present and set to TRUE, the server MUST run the task independently of other tasks that specify MaintenanceSettings.

      • ExecutionTimeLimit: The server MUST attempt to gracefully stop the task after its execution runtime exceeds this maximum time allowed. The server MUST forcibly stop the task in accordance with the AllowHardTerminate setting if its execution runtime exceeds this maximum time allowed.

      • Priority: If not present, the server MUST use the value 7 for Priority.

      • RunOnlyIfIdle: If present and set to TRUE, this field specifies that the server MUST start the task only if the machine is idle according to the IdleSettings field defined in section 2.5.4.14.

    • Principal (section 2.5.6): specifies the security context of the user on whose behalf the task will run. One of UserId or GroupId is mandatory.

      • UserId: The server MUST use the account name as the principal for running the task.

      • GroupId: the server MUST run the task for each and every user in the security group who is logged on at the time.

      • LogonType of S4U: the server MUST run the task non-interactively. The server MUST NOT save a password. At task runtime, the server MUST retrieve a restricted token from Active Directory based on the account name.

      • LogonType of Password: the server MUST run the task non-interactively. The server MUST use the password specified in the TASK_USER_CRED (section 2.3.8) structure for running the task.

      • LogonType of InteractiveToken: the server MUST run the task interactively in the currently logged-on user credentials. The server MUST NOT save a password and SHOULD NOT require a password.

      • LogonType of InteractiveTokenOrPassword: the server MUST run the task interactively if the user is logged on and non-interactively if the user is logged off.

      • LogonType: if not present, the server MUST use the value InteractiveToken for LogonType.

      • RunLevel's LeastPrivilege: the server MUST run the task with least privileges allowed for the user.

      • RunLevel's HighestAvailable: the server MUST run the task with highest privileges allowed for the user.

      • RunLevel: if not present, the server MUST use the value LeastPrivilege.

    • Actions (section 2.5.7): The server MUST support up to 32 actions. The server MUST execute multiple actions sequentially, in the order specified in the Actions field.

      • Exec Action's Arguments: If specified, the server MUST pass the arguments to the Command executable. If not present, the server MUST NOT pass arguments to the Command executable.

      • Exec Action's WorkingDirectory: The server MUST start the executable with its working directory set to the specified folder. If not present, the server MUST start the executable in the task store folder.

      • ComHandler Action's ClassId: If specified, the server MUST map the GUID value to the custom handler's COM class.

      • ComHandler Action's Data: If specified, the server SHOULD NOT parse the XML fragment. The server MUST pass the XML fragment to the custom handler.

      • Email Action: If present, this field MUST contain the specification of an email action and the server MUST send email through a Simple Mail Transfer Protocol (SMTP) server. See [RFC788].

        • Email Action's Subject: If present, the server MUST send the email with the specified Subject.

        • Email Action's To: If present, the server MUST send the email to the specified addresses.

        • Email Action's CC: If present, the server MUST send the email to all addresses specified.

        • Email Action's BCC: If present, the server MUST send the email to all specified addresses and MUST do so using a blind copy action.

        • Email Action's ReplyTo: If present, the server MUST send the email with the specified ReplyTo address.

        • Email Action's From: If Email Action is specified, then this field MUST be present and the server MUST send the email with the specified From address.

        • Email Action's Body: If present, the server MUST send the email with the specified email body text.

      • ShowMessage Action: If present, specifies that the server MUST display a message box on each session where this user is logged on the local machine.

        • ShowMessage Action's Title: If specified, the server MUST use the string for the caption of the message box.

        • ShowMessage Action's Body: If specified, the server MUST use the string for the contents of the message box.

  • Determine the logon type to be used depending upon logonType supplied:

    • If TASK_LOGON_NONE is specified, the server MUST determine the logon type from XML, or by using the TASK_LOGON_INTERACTIVE_TOKEN if not specified in XML.

    • If TASK_LOGON_PASSWORD is specified, the server MUST run the task with the user's logon and password supplied. The server MUST run the task non-interactively.

    • If TASK_LOGON_S4U is specified, the server MUST run the task with user's Service for User (S4U), as specified in [MS-SFU]. The server MUST run the task non-interactively.

    • If TASK_LOGON_INTERACTIVE_TOKEN is specified, the server MUST run the task in the user's interactive logon session. The server MUST run the task interactively.

    • If TASK_LOGON_GROUP is specified, then the server MUST run the task in the user's interactive logon session for any member of the security group. The server MUST run the task interactively.

    • If TASK_LOGON_SERVICE_ACCOUNT is specified, then the server MUST run the task as local system, local service or network service. The server MUST run the task noninteractively.

    • If TASK_LOGON_INTERACTIVE_TOKEN_OR_PASSWORD is specified, then the server MUST run in the user's interactive logon session. If the user is not logged on then the server MUST run the task using the user's logon and password noninteractively.

  • Determine the principal to be used:

    • A user ID specified in the pCreds parameter MUST be used if present.

    • A user ID specified in the UserID element of the xmlTaskDefinition (section 2.5.6) MUST be used if present.

    • A group ID is specified in the GroupID element of the xmlTaskDefinition (section 2.5.6) MUST be used if present.

    • If both UserID and GroupID are present then server MUST return SCHED_E_UNEXPECTEDNODE, with the "node" field of the ErrorInfo structure specifying the "GroupId" as unexpected node.

    • If none of the above is present, the user ID of the caller MUST be used.

  • Update the principal node of the XML task definition (section 2.5.6) to reflect the principal just determined and the logonType parameter.

  • The server MUST return an error if any of the undefined bits in the FLAGS field of the pCreds parameter are not set to 0.

    • pCreds parameter Flags field's D credFlagDefault bit: If set to 1, the server MUST use these credentials only if no other credentials are provided. If set to 0, the server MUST use these credentials instead of the credentials specified in the task configuration.

  • Return ERROR_LOGON_FAILURE if the call was made using an unknown user name or bad password.

  • Return E_ACCESSDENIED if the caller does not have administrative privileges on the server and the task has one of the following triggers:

    • Boot trigger (section 2.5.3.2).

    • Logon trigger for "everyone" or any user other than the caller (section 2.5.3.7).

    • Session state change trigger for "everyone" or any user other than the caller (section 2.5.3.8).

  • Return E_ACCESSDENIED if the task priority is 1 and the caller does not have administrative privileges on the server.

  • Perform security validation as specified in section 3.2.5.1.1.

  • Return E_ACCESSDENIED if a password is required (section 3.2.5.1.1) but the password provided in the pCreds parameter is not valid for the principal chosen.

  • Determine the correct path.

    • MUST use the path parameter if non-NULL.

    • Otherwise, if present, MUST use the URI element of the RegistrationInfo node of the task definition (section 2.5.1).

    • Otherwise, MUST generate a UUID and MUST use the string representation of it surrounded by '{' and '}' characters, as specified in [C706] section A.3.

  • If the path determined does not exist in the XML task store and the TASK_UPDATE flag is specified instead of the TASK_CREATE flag in the flags parameter, and the flags parameter is not 0: the server MUST return the value 0x80070002, the HRESULT form of the Win32 error ERROR_FILE_NOT_FOUND.

  • If the following three conditions are all true:

    • The path determined does not exist in the XML task store.

    • One of the following flags has been specified instead of TASK_CREATE in the flags parameter: TASK_DISABLE, TASK_DONT_ADD_PRINCIPAL_ACE, or TASK_IGNORE_REGISTRATION_TRIGGERS.

    • The flags parameter is not 0.

      The server MUST return the value 0x80070057 (the HRESULT form of the Win32 error E_INVALIDARG).

  • If the path determined does exist in the XML task store and the TASK_CREATE flag is specified instead of the TASK_UPDATE flag in the flags parameter: the server MUST return the value 0x800700B7, the HRESULT form of the Win32 error ERROR_ALREADY_EXISTS.

  • If the path determined does exist in the XML task store, and TASK_DISABLE, TASK_DONT_ADD_PRINCIPAL_ACE, or TASK_IGNORE_REGISTRATION_TRIGGERS has been specified instead of the TASK_UPDATE flag in the flags parameter: the server MUST return the value 0x80070057 (the HRESULT form of the Win32 error E_INVALIDARG).

  • Create subfolders in the task store for the path determined using the security descriptor specified in the sddl parameter (section 3.2.5.4.4).

  • Save the task in the XML task store at the path determined. The server MUST use the security descriptor specified in the sddl parameter, and unless the TASK_DONT_ADD_PRINCIPAL_ACE bit is specified in the flags parameter also give the principal File Read ("FR") access to the task (as specified in [MS-DTYP] section 2.5.1.1).

  • If the XML task definition has the Version attribute (section 2.5) with a value of "1.1" or "1.0", the server MUST also save the task in the .JOB task store or the AT task store, respectively.

  • If a password is required, the server MUST update its credential store with the principal chosen and the password provided in the pCreds parameter.

  • The server MUST update its EventLog subscriptions (section 3.2.4.1) to match the event triggers (section 2.5.3.6) currently in the XML task store, as specified in [MS-EVEN6] section 2.2.13.

  • If this task is to run earlier than the current value of the global timer, reset the global timer.

  • If the task has a registration trigger (section 2.5.3.3) and the TASK_IGNORE_REGISTRATION_TRIGGERS bit in the flags parameter is not set, start the task (section 3.2.5.1.2).

  • If the pActualPath parameter is non-NULL, return the path determined in the pActualPath parameter.

  • Return S_OK.

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