EnumServicesStatusExA-Funktion (winsvc.h)

  • Artikel

Listet Dienste in der angegebenen Dienststeuerungs-Manager-Datenbank auf. Der Name und die status der einzelnen Dienste werden zusammen mit zusätzlichen Daten basierend auf der angegebenen Informationsebene bereitgestellt.

Syntax

BOOL EnumServicesStatusExA(
  [in]                SC_HANDLE    hSCManager,
  [in]                SC_ENUM_TYPE InfoLevel,
  [in]                DWORD        dwServiceType,
  [in]                DWORD        dwServiceState,
  [out, optional]     LPBYTE       lpServices,
  [in]                DWORD        cbBufSize,
  [out]               LPDWORD      pcbBytesNeeded,
  [out]               LPDWORD      lpServicesReturned,
  [in, out, optional] LPDWORD      lpResumeHandle,
  [in, optional]      LPCSTR       pszGroupName
);

Parameter

[in] hSCManager

Ein Handle für die Dienststeuerungs-Manager-Datenbank. 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] InfoLevel

Die zurückzugebenden Dienstattribute. Verwenden Sie SC_ENUM_PROCESS_INFO, um den Namen und den Dienst status Informationen für jeden Dienst in der Datenbank abzurufen. Der lpServices-Parameter ist ein Zeiger auf einen Puffer, der ein Array von ENUM_SERVICE_STATUS_PROCESS Strukturen empfängt. Der Puffer muss groß genug sein, um sowohl die Strukturen als auch die Zeichenfolgen zu speichern, auf die ihre Member verweisen.

Derzeit sind keine weiteren Informationsebenen definiert.

[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 aufzuzählenden Dienste. 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 SERVICE_ACTIVE - und SERVICE_INACTIVE-Zustände .

[out, optional] lpServices

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 256.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_MORE_DATA 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 Bytes. 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 der Bytes empfängt, die zum Zurückgeben der verbleibenden Diensteinträge erforderlich sind, 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 der EnumServicesStatusEx-Funktion auf Null festlegen. Bei der Ausgabe ist dieser Wert 0, wenn die Funktion erfolgreich ist. Wenn die Funktion jedoch null zurückgibt und die GetLastError-FunktionERROR_MORE_DATA zurückgibt, gibt dieser Wert den nächsten Diensteintrag an, der gelesen werden soll, wenn die EnumServicesStatusEx-Funktion aufgerufen wird, um die zusätzlichen Daten abzurufen.

[in, optional] pszGroupName

Der Name der Ladereihenfolgegruppe. Wenn es sich bei diesem Parameter um eine Zeichenfolge handelt, werden nur die Dienste aufgelistet, die zu der Gruppe gehören, die den durch die Zeichenfolge angegebenen Namen aufweist. Wenn es sich bei diesem Parameter um eine leere Zeichenfolge handelt, werden nur Dienste aufgelistet, die keiner Gruppe angehören. Wenn dieser Parameter NULL ist, wird die Gruppenmitgliedschaft ignoriert, und alle Dienste werden aufgelistet.

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_ACCESS_DENIED
 Das Handle verfügt nicht über das zugriffsrecht SC_MANAGER_ENUMERATE_SERVICE .
ERROR_MORE_DATA
 Der Puffer ist zu klein. Nicht alle Daten in der aktiven Datenbank können zurückgegeben werden. Der parameter pcbBytesNeeded enthält die Anzahl der Bytes, die zum Empfangen der verbleibenden Einträge erforderlich sind.
ERROR_INVALID_PARAMETER
 Es wurde ein ungültiger Parameterwert verwendet.
ERROR_INVALID_HANDLE
 Das Handle 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

Wenn der Aufrufer nicht über das SERVICE_QUERY_STATUS Zugriffsrecht auf einen Dienst verfügt, wird der Dienst unbeaufsichtigt aus der Liste der an den Client zurückgegebenen Dienste ausgelassen.

Hinweis

Der winsvc.h-Header definiert EnumServicesStatusEx als Alias, der automatisch die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit nicht codierungsneutralem Code 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 (einschließen von Windows.h)
Bibliothek Advapi32.lib
DLL Advapi32.dll

Weitere Informationen

ENUM_SERVICE_STATUS_PROCESS

Dienstfunktionen

Dienstinstallation, -entfernung und -enumeration