Platform SDK: Network Management

NetScheduleJobAdd

The NetScheduleJobAdd function submits a job to run at a specified future time and date. This function requires that the schedule service be started at the computer to which the job is submitted.

Security Requirements

Only members of the Administrators local group can successfully execute the NetScheduleJobAdd function on a remote server.

NET_API_STATUS NetScheduleJobAdd(
  LPCWSTR Servername,  
  LPBYTE Buffer,      
  LPDWORD JobId       
);

Parameters

Servername: [in] Pointer to a constant Unicode string specifying the name of the remote server on which the function is to execute. The string must begin with \\. If this parameter is NULL, the local computer is used.
Buffer: [in] 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.
JobId: [out] Pointer that receives a job identifier for the newly submitted job. This entry is valid only if the function returns successfully.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value is a Win32 API error code. For a list of error codes, see Error Codes.

Remarks

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 to zero.
Set the JobTime member to the time the job should execute.

The job executes at the time specified by the JobTime member. After the job executes, it is deleted.

To schedule and delete a job that executes multiple times

Set the appropriate bits in the DaysOfMonth member of the AT_INFO structure.
Set the appropriate bits in the DaysOfWeek member. (You do not need to set both the DaysOfMonth and the DaysOfWeek members.)
Set the JobTime member to the time the job should execute.

The job executes at the time specified by the JobTime member, once for each day set in DaysOfMonth and DaysOfWeek. After each execution, the corresponding bit is cleared. When the last bit is cleared, the job is deleted.

To schedule a job that executes periodically

Set the appropriate bits in the DaysOfMonth member of the AT_INFO structure.
Set the appropriate bits in the DaysOfWeek member. (You do not need to set both the DaysOfMonth and the DaysOfWeek members.)
Set the JobTime member to the time the job should execute.
Set the job submission flag JOB_RUN_PERIODICALLY in the Flags member.

The job will execute periodically, at the time specified by the JobTime member, on each day set in DaysOfMonth and DaysOfWeek. The job will not be deleted as a result of the repeated executions. The only way to delete the job is by an explicit call to the NetScheduleJobDel function.

See AT_INFO for a description of the DaysOfWeek, DaysOfMonth, and job property bitmasks.

Requirements