Funzione EnumServicesStatusA (winsvc.h)

Articolo
11/20/2024

Enumera i servizi nel database di Gestione controllo dei servizi specificato. Vengono forniti il nome e lo stato di ogni servizio.

Questa funzione è stata sostituita dalla funzione EnumServicesStatusEx. Restituisce le stesse informazioni EnumServicesStatus restituisce, oltre all'identificatore del processo e alle informazioni aggiuntive per il servizio. Inoltre, EnumServicesStatusEx consente di enumerare i servizi appartenenti a un gruppo specificato.

Sintassi

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
);

Parametri

[in] hSCManager

Handle per il database di Gestione controllo dei servizi. Questo handle viene restituito dalla funzione OpenSCManager e deve avere il diritto di accesso SC_MANAGER_ENUMERATE_SERVICE. Per altre informazioni, vedere Service Security and Access Rights.

[in] dwServiceType

Tipo di servizi da enumerare. Questo parametro può essere uno o più dei valori seguenti.

Valore	Significato
SERVICE_DRIVER 0x0000000B	Servizi di tipo SERVICE_KERNEL_DRIVER e SERVICE_FILE_SYSTEM_DRIVER.
SERVICE_FILE_SYSTEM_DRIVER 0x00000002	Servizi driver del file system.
SERVICE_KERNEL_DRIVER 0x00000001	Servizi driver.
SERVICE_WIN32 0x00000030	Servizi di tipo SERVICE_WIN32_OWN_PROCESS e SERVICE_WIN32_SHARE_PROCESS.
SERVICE_WIN32_OWN_PROCESS 0x00000010	Servizi eseguiti nei propri processi.
SERVICE_WIN32_SHARE_PROCESS 0x00000020	Servizi che condividono un processo con uno o più servizi. Per altre informazioni, vedere Service Programs.

[in] dwServiceState

Stato dei servizi da enumerare. Questo parametro può essere uno dei valori seguenti.

Valore	Significato
SERVICE_ACTIVE 0x00000001	Enumera i servizi inclusi negli stati seguenti: SERVICE_START_PENDING, SERVICE_STOP_PENDING, SERVICE_RUNNING, SERVICE_CONTINUE_PENDING, SERVICE_PAUSE_PENDING e SERVICE_PAUSED.
SERVICE_INACTIVE 0x00000002	Enumera i servizi che si trovano nello stato SERVICE_STOPPED.
SERVICE_STATE_ALL 0x00000003	Combina gli stati seguenti: SERVICE_ACTIVE e SERVICE_INACTIVE.

[out, optional] lpServices

Puntatore a un buffer che contiene una matrice di strutture ENUM_SERVICE_STATUS che ricevono le informazioni sullo stato del nome e del servizio per ogni servizio nel database. Il buffer deve essere sufficientemente grande da contenere le strutture, oltre alle stringhe a cui puntano i membri.

La dimensione massima di questa matrice è di 256.000 byte. Per determinare le dimensioni necessarie, specificare NULL per questo parametro e 0 per il parametro cbBufSize . La funzione avrà esito negativo e GetLastError restituirà ERROR_INSUFFICIENT_BUFFER. Il parametro pcbBytesNeeded riceverà le dimensioni necessarie.

Windows Server 2003 e Windows XP: La dimensione massima di questa matrice è di 64.000 byte. Questo limite è stato aumentato a partire da Windows Server 2003 con SP1 e Windows XP con SP2.

[in] cbBufSize

Dimensioni del buffer a cui punta il parametro lpServices in byte.

[out] pcbBytesNeeded

Puntatore a una variabile che riceve il numero di byte necessari per restituire le voci del servizio rimanenti, se il buffer è troppo piccolo.

[out] lpServicesReturned

Puntatore a una variabile che riceve il numero di voci del servizio restituite.

[in, out, optional] lpResumeHandle

Puntatore a una variabile che, in input, specifica il punto iniziale dell'enumerazione. È necessario impostare questo valore su zero alla prima chiamata di questa funzione. Nell'output questo valore è zero se la funzione ha esito positivo. Tuttavia, se la funzione restituisce zero e la funzione GetLastError restituisce ERROR_MORE_DATA, questo valore viene utilizzato per indicare la voce di servizio successiva da leggere quando viene chiamata la funzione per recuperare i dati aggiuntivi.

Valore restituito

Se la funzione ha esito positivo, il valore restituito è diverso da zero.

Se la funzione ha esito negativo, il valore restituito è zero. Per ottenere informazioni estese sull'errore, chiamare GetLastError.

I codici di errore seguenti possono essere impostati dal gestore di controllo del servizio. Altri codici di errore possono essere impostati dalle funzioni del Registro di sistema chiamate dal gestore di controllo del servizio.

Codice restituito	Descrizione
ERROR_ACCESS_DENIED	L'handle non dispone del diritto di accesso SC_MANAGER_ENUMERATE_SERVICE.
ERROR_INVALID_HANDLE	L'handle specificato non è valido.
ERROR_INVALID_PARAMETER	Parametro specificato non valido.
ERROR_MORE_DATA	Sono presenti più voci del servizio che si adattano al buffer lpServices. Il numero effettivo di voci del servizio scritte in lpServices viene restituito nel parametro lpServicesReturned. Il numero di byte necessari per ottenere le voci rimanenti viene restituito nel parametro pcbBytesNeeded. I servizi rimanenti possono essere enumerati da chiamate aggiuntive a EnumServicesStatus con il parametro lpResumeHandle che indica il servizio successivo da leggere.

Osservazioni

Nota

L'intestazione winsvc.h definisce EnumServicesStatus come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante del preprocessore UNICODE. La combinazione dell'utilizzo dell'alias indipendente dalla codifica con il codice non indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere convenzioni di per i prototipi di funzioni.

Fabbisogno

Requisito	Valore
client minimo supportato	Windows XP [solo app desktop]
server minimo supportato	Windows Server 2003 [solo app desktop]
piattaforma di destinazione	Finestre
intestazione	winsvc.h (include Windows.h)
libreria	Advapi32.lib
dll	Advapi32.dll