Funzione RegisterServiceCtrlHandlerA (winsvc.h)
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 |
|---|---|
|
Memoria insufficiente per convertire un parametro stringa ANSI in Unicode. Questo errore non si verifica per i parametri stringa Unicode. |
|
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 |