QueryServiceStatusEx-Funktion (winsvc.h)

Artikel
03/04/2024

Ruft die aktuelle status des angegebenen Diensts basierend auf der angegebenen Informationsebene ab.

Syntax

BOOL QueryServiceStatusEx(
  [in]            SC_HANDLE      hService,
  [in]            SC_STATUS_TYPE InfoLevel,
  [out, optional] LPBYTE         lpBuffer,
  [in]            DWORD          cbBufSize,
  [out]           LPDWORD        pcbBytesNeeded
);

Parameter

[in] hService

Ein Handle für den Dienst. Dieses Handle wird von der CreateService - oder OpenService-Funktion zurückgegeben und muss über das SERVICE_QUERY_STATUS-Zugriffsrecht verfügen. Weitere Informationen finden Sie unter Dienstsicherheit und Zugriffsrechte.

[in] InfoLevel

Die zurückzugebenden Dienstattribute. Verwenden Sie SC_STATUS_PROCESS_INFO, um die Dienstinformationen status abzurufen. Der lpBuffer-Parameter ist ein Zeiger auf eine SERVICE_STATUS_PROCESS-Struktur .

Derzeit sind keine weiteren Informationsebenen definiert.

[out, optional] lpBuffer

Ein Zeiger auf den Puffer, der die status Informationen empfängt. Das Format dieser Daten hängt vom Wert des InfoLevel-Parameters ab.

Die maximale Größe dieses Arrays beträgt 8.000 Bytes. Um die erforderliche Größe zu bestimmen, geben Sie NULL für diesen Parameter und 0 für den cbBufSize-Parameter an. Die Funktion schlägt fehl, und GetLastError gibt ERROR_INSUFFICIENT_BUFFER zurück. Der parameter pcbBytesNeeded empfängt die erforderliche Größe.

[in] cbBufSize

Die Größe des Puffers, auf den der lpBuffer-Parameter in Bytes verweist.

[out] pcbBytesNeeded

Ein Zeiger auf eine Variable, die die Anzahl von Bytes empfängt, die zum Speichern aller status Informationen benötigt werden, wenn die Funktion mit ERROR_INSUFFICIENT_BUFFER fehlschlägt.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert ungleich Null.

Wenn die Funktion fehlerhaft ist, ist der Rückgabewert null. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf. Die folgenden Fehler können zurückgegeben werden.

Rückgabecode	Beschreibung
ERROR_INVALID_HANDLE	Das Handle ist ungültig.
ERROR_ACCESS_DENIED	Das Handle verfügt nicht über das zugriffsrecht SERVICE_QUERY_STATUS.
ERROR_INSUFFICIENT_BUFFER	Der Puffer ist zu klein für die SERVICE_STATUS_PROCESS-Struktur . Es wurde nichts in die Struktur geschrieben.
ERROR_INVALID_PARAMETER	Das cbSize-Element von SERVICE_STATUS_PROCESS ist ungültig.
ERROR_INVALID_LEVEL	Der InfoLevel-Parameter enthält einen nicht unterstützten Wert.
ERROR_SHUTDOWN_IN_PROGRESS	Das System wird heruntergefahren. Diese Funktion kann nicht aufgerufen werden.

Hinweise

Die QueryServiceStatusEx-Funktion gibt die neuesten Dienst-status Informationen zurück, die an den Dienststeuerungs-Manager gemeldet wurden. Wenn der Dienst gerade seine status geändert hat, hat er den Dienststeuerungs-Manager möglicherweise noch nicht aktualisiert.

Der in der SERVICE_STATUS_PROCESS-Struktur zurückgegebene Prozessbezeichner ist gültig, sofern der Status des Diensts einer der SERVICE_RUNNING, SERVICE_PAUSE_PENDING, SERVICE_PAUSED oder SERVICE_CONTINUE_PENDING ist. Wenn sich der Dienst jedoch in einem SERVICE_START_PENDING oder SERVICE_STOP_PENDING Zustand befindet, ist der Prozessbezeichner möglicherweise ungültig, und wenn sich der Dienst im SERVICE_STOPPED Zustand befindet, ist er nie gültig.

Beispiele

Ein Beispiel finden Sie unter Starten eines Diensts oder Beenden eines Diensts.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows XP [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2003 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	winsvc.h (einschließen von Windows.h)
Bibliothek	Advapi32.lib
DLL	Advapi32.dll

Weitere Informationen

SERVICE_STATUS_PROCESS

Dienstfunktionen

Dienststart

Freigeben über