Funzione RegisterServiceCtrlHandlerExA (winsvc.h)

Articolo
08/27/2023

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

Sintassi

SERVICE_STATUS_HANDLE RegisterServiceCtrlHandlerExA(
  [in]           LPCSTR                lpServiceName,
  [in]           LPHANDLER_FUNCTION_EX lpHandlerProc,
  [in, optional] LPVOID                lpContext
);

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.

[in] lpHandlerProc

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

[in, optional] lpContext

Tutti i dati definiti dall'utente. Questo parametro, passato alla funzione del gestore, consente di identificare il servizio quando più servizi condividono un processo.

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 di stringa Unicode.
ERROR_SERVICE_NOT_IN_EXE	La voce del 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 RegisterServiceCtrlHandlerEx per registrare una funzione del gestore di controllo con il dispatcher del controllo. In questo modo il dispatcher di controllo può richiamare la funzione specificata quando riceve le richieste di controllo per questo servizio. Per un elenco dei codici di controllo possibili, vedere HandlerEx. 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 RegisterServiceCtrlHandlerEx deve essere chiamata prima della prima chiamata SetServiceStatus perché RegisterServiceCtrlHandlerEx 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 impostato per ricevere le richieste di controllo dal 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 sta elaborando 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.

Nota

L'intestazione winsvc.h definisce RegisterServiceCtrlHandlerEx 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 che non è indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzioni.

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