Funzione StartServiceCtrlDispatcherW (winsvc.h)

Articolo
11/20/2024

Connette il thread principale di un processo del servizio al gestore di controllo del servizio, che fa sì che il thread sia il thread dispatcher del controllo del servizio per il processo chiamante.

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

Il codice di errore seguente può essere impostato dal gestore di 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 dispatch specificata contiene voci che non sono nel formato corretto.
ERROR_SERVICE_ALREADY_RUNNING	Il processo ha già chiamato StartServiceCtrlDispatcher. Ogni processo può chiamare StartServiceCtrlDispatcher una sola volta.

Osservazioni

Quando il gestore di 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 ha esito positivo, connette il thread chiamante al gestore di controllo del servizio e non restituisce finché tutti i servizi in esecuzione nel processo non hanno immesso lo stato di SERVICE_STOPPED. Il gestore di controllo del servizio usa questa connessione per inviare richieste di avvio del controllo e 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 di 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 del 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 è necessario eseguire alcune operazioni comuni di inizializzazione a livello di processo 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 Interactive Services.

Esempi

Per un esempio, vedere Writing a Service Program's Main Function.

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