Funzione StartServiceCtrlDispatcherW (winsvc.h)

Articolo
03/04/2024

Connette il thread principale di un processo di servizio al gestore del controllo del servizio, che causa il thread come thread del dispatcher del controllo del servizio per il processo di chiamata.

Sintassi

BOOL StartServiceCtrlDispatcherW(
  [in] const SERVICE_TABLE_ENTRYW *lpServiceStartTable
);

Parametri

[in] lpServiceStartTable

Puntatore a una matrice di strutture SERVICE_TABLE_ENTRY contenenti una voce per ogni servizio che può essere eseguito nel processo chiamante. I membri dell'ultima voce della tabella devono avere valori NULL per designare la fine della tabella.

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 informazioni dettagliate sull'errore, chiamare GetLastError.

Il codice di errore seguente può essere impostato dal gestore del 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_FAILED_SERVICE_CONTROLLER_CONNECT	Questo errore viene restituito se il programma viene eseguito come applicazione console anziché come servizio. Se il programma verrà eseguito come applicazione console a scopo di debug, strutturarlo in modo che il codice specifico del servizio non venga chiamato quando viene restituito questo errore.
ERROR_INVALID_DATA	La tabella di invio specificata contiene voci che non sono nel formato appropriato.
ERROR_SERVICE_ALREADY_RUNNING	Il processo ha già chiamato StartServiceCtrlDispatcher. Ogni processo può chiamare StartServiceCtrlDispatcher una sola volta.

Commenti

Quando il gestore del controllo del servizio avvia un processo di servizio, attende che il processo chiami la funzione StartServiceCtrlDispatcher . Il thread principale di un processo di servizio deve effettuare questa chiamata il prima possibile dopo l'avvio (entro 30 secondi). Se StartServiceCtrlDispatcher riesce, connette il thread chiamante alla gestione controllo del servizio e non restituisce fino a quando tutti i servizi in esecuzione nel processo hanno immesso lo stato di SERVICE_STOPPED. Gestione controllo del servizio usa questa connessione per inviare richieste di controllo e avvio del servizio al thread principale del processo del servizio. Il thread principale funge da dispatcher richiamando la funzione HandlerEx appropriata per gestire le richieste di controllo o creando un nuovo thread per eseguire la funzione ServiceMain appropriata quando viene avviato un nuovo servizio.

Il parametro lpServiceTable contiene una voce per ogni servizio che può essere eseguito nel processo chiamante. Ogni voce specifica la funzione ServiceMain per tale servizio. Per i servizi SERVICE_WIN32_SHARE_PROCESS, ogni voce deve contenere il nome di un servizio. Questo nome è il nome del servizio specificato dalla funzione CreateService quando è stato installato il servizio. Per SERVICE_WIN32_OWN_PROCESS servizi, il nome del servizio nella voce della tabella viene ignorato.

Se un servizio viene eseguito nel proprio processo, il thread principale del processo di servizio deve chiamare immediatamente StartServiceCtrlDispatcher. Tutte le attività di inizializzazione vengono eseguite nella funzione ServiceMain del servizio all'avvio del servizio.

Se più servizi condividono un processo e un'inizializzazione a livello di processo comune deve essere eseguita prima che venga chiamata qualsiasi funzione ServiceMain , il thread principale può eseguire il lavoro prima di chiamare StartServiceCtrlDispatcher, purché richieda meno di 30 secondi. In caso contrario, è necessario creare un altro thread per eseguire l'inizializzazione a livello di processo, mentre il thread principale chiama StartServiceCtrlDispatcher e diventa il dispatcher del controllo del servizio. Qualsiasi inizializzazione specifica del servizio deve comunque essere eseguita nelle singole funzioni principali del servizio.

I servizi non devono tentare di visualizzare direttamente un'interfaccia utente. Per altre informazioni, vedere Servizi interattivi.

Esempio

Per un esempio, vedere Scrittura della funzione principale di un programma di servizio.

Nota

L'intestazione winsvc.h definisce StartServiceCtrlDispatcher 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