Funzione StartServiceCtrlDispatcherA (winsvc.h)

Articolo
03/04/2024

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

Sintassi

BOOL StartServiceCtrlDispatcherA(
  [in] const SERVICE_TABLE_ENTRYA *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 nella 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 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.

Commenti

Quando gestione controllo del servizio avvia un processo del servizio, attende che il processo chiami la funzione StartServiceCtrlDispatcher . Il thread principale di un processo del servizio deve effettuare questa chiamata il prima possibile dopo l'avvio (entro 30 secondi). Se StartServiceCtrlDispatcher ha esito positivo, connette il thread chiamante alla gestione controllo del servizio e non restituisce finché tutti i servizi in esecuzione nel processo non hanno immesso lo stato di SERVICE_STOPPED. La 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 all'avvio di 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 SERVICE_WIN32_SHARE_PROCESS servizi, 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 un'inizializzazione a livello di processo comune deve essere eseguita prima che venga chiamata una 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.

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