NetScheduleJobAdd function (lmat.h)
[NetScheduleJobAdd is no longer available for use as of Windows 8. Instead, use the Task Scheduler 2.0 Interfaces.
]
The NetScheduleJobAdd function submits a job to run at a specified future time and date. This function requires that the schedule service be started on the computer to which the job is submitted.
Syntax
NET_API_STATUS NET_API_FUNCTION NetScheduleJobAdd(
[in, optional] LPCWSTR Servername,
[in] LPBYTE Buffer,
[out] LPDWORD JobId
);
Parameters
[in, optional] Servername
A pointer to a constant string that specifies the DNS or NetBIOS name of the remote server on which the function is to execute. If this parameter is NULL, the local computer is used.
[in] Buffer
A pointer to an AT_INFO structure describing the job to submit. For more information about scheduling jobs using different job properties, see the following Remarks section and Network Management Function Buffers.
[out] JobId
A pointer that receives a job identifier for the newly submitted job. This entry is valid only if the function returns successfully.
Return value
If the function succeeds, the return value is NERR_Success.
If the function fails, the return value is a system error code. For a list of error codes, see System Error Codes.
Remarks
Normally only members of the local Administrators group on the computer where the schedule job is being added can successfully execute this function. If the server name passed in the string pointed to by the Servername parameter is a remote server, then only members of the local Administrators group on the remote server can successfully execute this function.
If the following registry value has the least significant bit set (for example, 0x00000001), then users belonging to the Server Operators group can also successfully execute this function.
HKLM\System\CurrentControlSet\Control\Lsa\SubmitControl
The following are examples of how to schedule jobs using different properties supported by the NetScheduleJobAdd function.
To schedule a job that executes once:
- Set the DaysOfMonth member of the AT_INFO structure to zero.
- Set the DaysOfWeek member of the AT_INFO structure to zero.
- Set the JobTime member of the AT_INFO structure to the time the job should execute.
To schedule and delete a job that executes multiple times:
- Set the appropriate bits in the DaysOfMonth member of the AT_INFO structure or
- Set the appropriate bits in the DaysOfWeek member of the AT_INFO structure.
- Set the JobTime member of the AT_INFO structure to the time the job should execute.
To schedule a job that executes periodically:
- Set the appropriate bits in the DaysOfMonth member of the AT_INFO structure or
- Set the appropriate bits in the DaysOfWeek member of the AT_INFO structure.
- Set the JobTime member of the AT_INFO structure to the time the job should execute.
- Set the job submission flag JOB_RUN_PERIODICALLY in the Flags member of the AT_INFO structure.
See the AT_INFO structure for a description of the DaysOfWeek, DaysOfMonth, and job property bitmasks.
On Windows 2000, the earlier AT service and the Task Scheduler were combined. The Task Scheduler service was only accurate to the minute. Therefore, the NetScheduleJobAdd function only uses hours and minutes specified in the JobTime member of the AT_INFO structure when a job is scheduled to run.
Starting with Windows Vista, the precision for the Task Scheduler was increased to the second. Therefore, the NetScheduleJobAdd function uses only the hours, minutes, and seconds specified in the JobTime member of the AT_INFO structure when a job is scheduled to run.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows 2000 Professional [desktop apps only] |
| Minimum supported server | Windows 2000 Server [desktop apps only] |
| Target Platform | Windows |
| Header | lmat.h (include Lmat.h) |
| Library | Netapi32.lib |
| DLL | Netapi32.dll |