EnumServicesStatusA-Funktion (winsvc.h)

Artikel
08/27/2023

Listet Dienste in der angegebenen Datenbank des Dienststeuerungs-Managers auf. Der Name und die status der einzelnen Dienste werden bereitgestellt.

Diese Funktion wurde durch die Funktion EnumServicesStatusEx abgelöst. Sie gibt die gleichen Informationen zurück, die EnumServicesStatus zurückgibt, sowie den Prozessbezeichner und zusätzliche Informationen für den Dienst. Darüber hinaus können Sie mit EnumServicesStatusEx Dienste auflisten, die zu einer angegebenen Gruppe gehören.

Syntax

BOOL EnumServicesStatusA(
  [in]                SC_HANDLE              hSCManager,
  [in]                DWORD                  dwServiceType,
  [in]                DWORD                  dwServiceState,
  [out, optional]     LPENUM_SERVICE_STATUSA lpServices,
  [in]                DWORD                  cbBufSize,
  [out]               LPDWORD                pcbBytesNeeded,
  [out]               LPDWORD                lpServicesReturned,
  [in, out, optional] LPDWORD                lpResumeHandle
);

Parameter

[in] hSCManager

Ein Handle für die Datenbank des Dienststeuerungs-Managers. Dieses Handle wird von der OpenSCManager-Funktion zurückgegeben und muss über das zugriffsrecht SC_MANAGER_ENUMERATE_SERVICE verfügen. Weitere Informationen finden Sie unter Dienstsicherheit und Zugriffsrechte.

[in] dwServiceType

Der Typ der dienste, die aufgelistet werden sollen. Dieser Parameter kann einen oder mehrere der folgenden Werte aufweisen.

Wert	Bedeutung
SERVICE_DRIVER 0x0000000B	Dienste vom Typ SERVICE_KERNEL_DRIVER und SERVICE_FILE_SYSTEM_DRIVER.
SERVICE_FILE_SYSTEM_DRIVER 0x00000002	Dateisystemtreiberdienste.
SERVICE_KERNEL_DRIVER 0x00000001	Treiberdienste.
SERVICE_WIN32 0x00000030	Dienste vom Typ SERVICE_WIN32_OWN_PROCESS und SERVICE_WIN32_SHARE_PROCESS.
SERVICE_WIN32_OWN_PROCESS 0x00000010	Dienste, die in ihren eigenen Prozessen ausgeführt werden.
SERVICE_WIN32_SHARE_PROCESS 0x00000020	Dienste, die einen Prozess mit einem oder mehreren anderen Diensten gemeinsam nutzen. Weitere Informationen finden Sie unter Dienstprogramme.

[in] dwServiceState

Der Status der dienste, die aufgelistet werden sollen. Dieser Parameter kann einen der folgenden Werte annehmen.

Wert	Bedeutung
SERVICE_ACTIVE 0x00000001	Listet Dienste auf, die sich in den folgenden Zuständen befinden: SERVICE_START_PENDING, SERVICE_STOP_PENDING, SERVICE_RUNNING, SERVICE_CONTINUE_PENDING, SERVICE_PAUSE_PENDING und SERVICE_PAUSED.
SERVICE_INACTIVE 0x00000002	Listet Dienste auf, die sich im SERVICE_STOPPED Zustand befinden.
SERVICE_STATE_ALL 0x00000003	Kombiniert die folgenden Zustände: SERVICE_ACTIVE und SERVICE_INACTIVE.

[out, optional] lpServices

Ein Zeiger auf einen Puffer, der ein Array von ENUM_SERVICE_STATUS Strukturen enthält, die den Namen und den Dienst status Informationen für jeden Dienst in der Datenbank empfangen. Der Puffer muss groß genug sein, um die Strukturen sowie die Zeichenfolgen zu enthalten, auf die ihre Member verweisen.

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

Windows Server 2003 und Windows XP: Die maximale Größe dieses Arrays beträgt 64.000 Byte. Dieser Grenzwert wurde ab Windows Server 2003 mit SP1 und Windows XP mit SP2 erhöht.

[in] cbBufSize

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

[out] pcbBytesNeeded

Ein Zeiger auf eine Variable, die die Anzahl von Bytes empfängt, die erforderlich sind, um die verbleibenden Diensteinträge zurückzugeben, wenn der Puffer zu klein ist.

[out] lpServicesReturned

Ein Zeiger auf eine Variable, die die Anzahl der zurückgegebenen Diensteinträge empfängt.

[in, out, optional] lpResumeHandle

Ein Zeiger auf eine Variable, die bei der Eingabe den Startpunkt der Enumeration angibt. Sie müssen diesen Wert beim ersten Aufruf dieser Funktion auf Null festlegen. Bei der Ausgabe ist dieser Wert null, wenn die Funktion erfolgreich ist. Wenn die Funktion jedoch null zurückgibt und die GetLastError-Funktion ERROR_MORE_DATA zurückgibt, wird dieser Wert verwendet, um den nächsten Zu lesenden Diensteintrag anzugeben, wenn die Funktion aufgerufen wird, um die zusätzlichen Daten abzurufen.

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 Fehlercodes können vom Dienststeuerungs-Manager festgelegt werden. Andere Fehlercodes können von den Registrierungsfunktionen festgelegt werden, die vom Dienststeuerungs-Manager aufgerufen werden.

Rückgabecode	Beschreibung
ERROR_ACCESS_DENIED	Das Handle verfügt nicht über das Zugriffsrecht SC_MANAGER_ENUMERATE_SERVICE.
ERROR_INVALID_HANDLE	Das angegebene Handle ist ungültig.
ERROR_INVALID_PARAMETER	Ein parameter, der angegeben wurde, ist ungültig.
ERROR_MORE_DATA	Es gibt mehr Diensteinträge, als in den lpServices-Puffer passen würden. Die tatsächliche Anzahl der in lpServices geschriebenen Diensteinträge wird im lpServicesReturned-Parameter zurückgegeben. Die Anzahl der Bytes, die zum Abrufen der verbleibenden Einträge erforderlich sind, wird im parameter pcbBytesNeeded zurückgegeben. Die verbleibenden Dienste können durch zusätzliche Aufrufe von EnumServicesStatus mit dem lpResumeHandle-Parameter aufgelistet werden, der den nächsten zu lesenden Dienst angibt.

Hinweise

Hinweis

Der winsvc.h-Header definiert EnumServicesStatus als Alias, der die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante automatisch auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit Code, der nicht Codierungsneutral ist, kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.

Anforderungen


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