NetScheduleJobAdd-Funktion (lmat.h)

Artikel
08/24/2023

[NetScheduleJobAdd ist ab Windows 8 nicht mehr verfügbar. Verwenden Sie stattdessen die Taskplaner 2.0-Schnittstellen.

]

Die NetScheduleJobAdd-Funktion übermittelt einen Auftrag, der zu einer bestimmten späteren Uhrzeit und einem bestimmten Datum ausgeführt werden soll. Diese Funktion erfordert, dass der Zeitplandienst auf dem Computer gestartet wird, an den der Auftrag übermittelt wird.

Syntax

NET_API_STATUS NET_API_FUNCTION NetScheduleJobAdd(
  [in, optional] LPCWSTR Servername,
  [in]           LPBYTE  Buffer,
  [out]          LPDWORD JobId
);

Parameter

[in, optional] Servername

Ein Zeiger auf eine konstante Zeichenfolge, die den DNS- oder NetBIOS-Namen des Remoteservers angibt, auf dem die Funktion ausgeführt werden soll. Wenn dieser Parameter NULL ist, wird der lokale Computer verwendet.

[in] Buffer

Ein Zeiger auf eine AT_INFO Struktur, die den zu übermittelnden Auftrag beschreibt. Weitere Informationen zum Planen von Aufträgen mit unterschiedlichen Auftragseigenschaften finden Sie im folgenden Abschnitt hinweise und Netzwerkverwaltungsfunktionspuffer.

[out] JobId

Ein Zeiger, der einen Auftragsbezeichner für den neu übermittelten Auftrag empfängt. Dieser Eintrag ist nur gültig, wenn die Funktion erfolgreich zurückgegeben wird.

Rückgabewert

Wenn die Funktion erfolgreich ist, wird der Rückgabewert NERR_Success.

Wenn die Funktion fehlschlägt, ist der Rückgabewert ein Systemfehlercode. Eine Liste der Fehlercodes finden Sie unter Systemfehlercodes.

Hinweise

Normalerweise können nur Mitglieder der lokalen Administratorgruppe auf dem Computer, auf dem der Zeitplanauftrag hinzugefügt wird, diese Funktion erfolgreich ausführen. Wenn der Servername, der in der Zeichenfolge übergeben wird, auf die der Servername-Parameter verweist, ein Remoteserver ist, können nur Mitglieder der lokalen Gruppe Administratoren auf dem Remoteserver diese Funktion erfolgreich ausführen.

Wenn der folgende Registrierungswert über das am wenigsten signifikante Bit festgelegt ist (z. B. 0x00000001), können Benutzer, die zur Gruppe Serveroperatoren gehören, diese Funktion ebenfalls erfolgreich ausführen.

HKLM\System\CurrentControlSet\Control\Lsa\SubmitControl

Im Folgenden finden Sie Beispiele für das Planen von Aufträgen mit verschiedenen Eigenschaften, die von der NetScheduleJobAdd-Funktion unterstützt werden.

So planen Sie einen Auftrag, der einmal ausgeführt wird:

Legen Sie das DaysOfMonth-Element der AT_INFO-Struktur auf 0 (null) fest.
Legen Sie das DaysOfWeek-Element der AT_INFO-Struktur auf Null fest.
Legen Sie den JobTime-Member der AT_INFO-Struktur auf den Zeitpunkt fest, zu dem der Auftrag ausgeführt werden soll.

Der Auftrag wird zu dem Zeitpunkt ausgeführt, der vom JobTime-Member der AT_INFO Struktur angegeben wird, auf die der Buffer-Parameter verweist. Nachdem der Auftrag ausgeführt wurde, wird er gelöscht.

So planen und löschen Sie einen Auftrag, der mehrmals ausgeführt wird:

Legen Sie die entsprechenden Bits im DaysOfMonth-Element der AT_INFO-Struktur oder fest.
Legen Sie die entsprechenden Bits im DaysOfWeek-Element der AT_INFO-Struktur fest.
Legen Sie den JobTime-Member der AT_INFO-Struktur auf den Zeitpunkt fest, zu dem der Auftrag ausgeführt werden soll.

Hinweis Sie müssen nicht sowohl die DaysOfMonth - als auch die DaysOfWeek-Member der AT_INFO-Struktur festlegen.

Der Auftrag wird zu dem Zeitpunkt ausgeführt, der vom JobTime-Member der AT_INFO Struktur angegeben wird, auf die der Buffer-Parameter verweist, einmal für jeden Tag, der in den DaysOfMonth - oder DaysOfWeek-Membern der AT_INFO-Struktur festgelegt ist. Nachdem jeder Auftrag ausgeführt wurde, wird das entsprechende Bit gelöscht. Wenn das letzte Bit gelöscht wird, wird der Auftrag gelöscht.

So planen Sie einen Auftrag, der regelmäßig ausgeführt wird:

Legen Sie die entsprechenden Bits im DaysOfMonth-Element der AT_INFO-Struktur oder fest.
Legen Sie die entsprechenden Bits im DaysOfWeek-Element der AT_INFO-Struktur fest.
Legen Sie den JobTime-Member der AT_INFO-Struktur auf den Zeitpunkt fest, zu dem der Auftrag ausgeführt werden soll.
Legen Sie das JOB_RUN_PERIODICALLY des Auftragsübermittlungsflags im Flags-Element der AT_INFO-Struktur fest.

Hinweis Sie müssen nicht sowohl die DaysOfMonth - als auch die DaysOfWeek-Member der AT_INFO-Struktur festlegen.

Der Auftrag wird regelmäßig zu dem Zeitpunkt ausgeführt, der vom JobTime-Member der AT_INFO Struktur angegeben wird, auf die der Buffer-Parameter verweist, und zwar an jedem Tag, der im DaysOfMonth - oder DaysOfWeek-Element der AT_INFO-Struktur festgelegt ist. Der Auftrag wird aufgrund der wiederholten Ausführungen nicht gelöscht. Die einzige Möglichkeit zum Löschen des Auftrags ist ein expliziter Aufruf der NetScheduleJobDel-Funktion .

Eine Beschreibung der Bitmasken daysOfWeek, DaysOfMonth und der Auftragseigenschaft finden Sie in der AT_INFO-Struktur.

Unter Windows 2000 wurden der frühere AT-Dienst und der Aufgabenplaner kombiniert. Der Taskplaner-Dienst war nur minutengenau. Daher verwendet die NetScheduleJobAdd-Funktion nur Stunden und Minuten, die im JobTime-Member der AT_INFO-Struktur angegeben sind, wenn die Ausführung eines Auftrags geplant ist.

Ab Windows Vista wurde die Genauigkeit für den Aufgabenplaner auf die Sekunde erhöht. Daher verwendet die NetScheduleJobAdd-Funktion nur die Stunden, Minuten und Sekunden, die im JobTime-Member der AT_INFO-Struktur angegeben sind, wenn die Ausführung eines Auftrags geplant ist.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 2000 Professional [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows 2000 Server [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	lmat.h (include Lmat.h)
Bibliothek	Netapi32.lib
DLL	Netapi32.dll