Funzione RegisterServiceCtrlHandlerA (winsvc.h)

2024-11-20

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

Questa funzione è stata sostituita dalla funzione RegisterServiceCtrlHandlerEx. Un servizio può usare entrambe le funzioni, ma la nuova funzione supporta i dati di contesto definiti dall'utente e la nuova funzione del 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é è presente un solo servizio registrato nel processo.

[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 ottenere informazioni estese 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 di stringa Unicode.
ERROR_SERVICE_NOT_IN_EXE	La voce del servizio è stata specificata in modo non corretto quando il processo ha chiamato la funzione startServiceCtrlDispatcher .

Osservazioni

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 di 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 che il chiamante deve usare in modo che nessun altro servizio possa impostare inavvertitamente questo stato del servizio. Inoltre, il gestore di controlli deve essere posizionato per ricevere le richieste di controllo entro il momento in cui il servizio specifica i controlli accettati tramite la funzione SetServiceStatus.

Quando la funzione del gestore di controllo viene richiamata con una richiesta di controllo, il servizio deve chiamare SetServiceStatus per segnalare lo stato al gestore di controllo del servizio solo se lo stato del servizio è stato modificato, 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 di controllo del servizio.

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

Esempi

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