Funzione RegisterServiceCtrlHandlerA (winsvc.h)

Articolo
03/08/2023

Registra una funzione per gestire le richieste di controllo del servizio.

Questa funzione è stata sostituita dalla funzione RegisterServiceCtrlHandlerEx . Un servizio può usare una funzione, ma la nuova funzione supporta i dati di contesto definiti dall'utente e la nuova funzione gestore supporta codici di controllo estesi aggiuntivi.

Sintassi

SERVICE_STATUS_HANDLE RegisterServiceCtrlHandlerA(
  [in] LPCSTR             lpServiceName,
  [in] LPHANDLER_FUNCTION lpHandlerProc
);

Parametri

[in] lpServiceName

Nome del servizio eseguito dal thread chiamante. Si tratta del nome del servizio specificato dal programma di controllo del servizio nella funzione CreateService durante la creazione del servizio.

Se il tipo di servizio è SERVICE_WIN32_OWN_PROCESS, la funzione non verifica che il nome specificato sia valido, perché nel processo è presente un solo servizio registrato.

[in] lpHandlerProc

Puntatore alla funzione del gestore da registrare. Per altre informazioni, vedere Gestore.

Valore restituito

Se la funzione ha esito positivo, il valore restituito è un handle di stato del servizio.

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

I codici di errore seguenti possono essere impostati dal gestore di controllo del servizio.

Codice restituito	Descrizione
ERROR_NOT_ENOUGH_MEMORY	Memoria insufficiente per convertire un parametro stringa ANSI in Unicode. Questo errore non si verifica per i parametri stringa Unicode.
ERROR_SERVICE_NOT_IN_EXE	La voce di servizio è stata specificata in modo errato quando il processo ha chiamato la funzione StartServiceCtrlDispatcher .

Commenti

La funzione ServiceMain di un nuovo servizio deve chiamare immediatamente la funzione RegisterServiceCtrlHandler per registrare una funzione del gestore di controllo con il dispatcher del controllo. Ciò consente al dispatcher del controllo di richiamare la funzione specificata quando riceve le richieste di controllo per questo servizio. Per un elenco dei possibili codici di controllo, vedere Gestore. I thread del processo chiamante possono usare l'handle di stato del servizio restituito da questa funzione per identificare il servizio nelle chiamate successive alla funzione SetServiceStatus .

La funzione RegisterServiceCtrlHandler deve essere chiamata prima della prima chiamata SetServiceStatus perché RegisterServiceCtrlHandler restituisce un handle di stato del servizio per il chiamante da usare in modo che nessun altro servizio possa impostare inavvertitamente lo stato del servizio. Inoltre, il gestore del controllo deve essere inserito per ricevere le richieste di controllo entro il momento in cui il servizio specifica i controlli accetta tramite la funzione SetServiceStatus .

Quando la funzione del gestore del controllo viene richiamata con una richiesta di controllo, il servizio deve chiamare SetServiceStatus per segnalare lo stato del controllo del servizio solo se lo stato del servizio è cambiato, ad esempio quando il servizio elabora i controlli di arresto o arresto. Se lo stato del servizio non è stato modificato, il servizio non deve segnalare lo stato al gestore del controllo del servizio.

L'handle di stato del servizio non deve essere chiuso.

Esempio

Per un esempio, vedere Scrittura di una funzione ServiceMain.

Nota

L'intestazione winsvc.h definisce RegisterServiceCtrlHandler come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante preprocessore UNICODE. La combinazione dell'utilizzo dell'alias di codifica neutrale con il codice che non è neutrale dalla codifica può causare errori di corrispondenza che causano errori di compilazione o runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzione.

Requisiti

Requisito	Valore
Client minimo supportato	Windows XP [solo app desktop]
Server minimo supportato	Windows Server 2003 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	winsvc.h (include Windows.h)
Libreria	Advapi32.lib
DLL	Advapi32.dll