Funzione StartServiceA (winsvc.h)

Articolo
11/20/2024

Avvia un servizio.

Sintassi

BOOL StartServiceA(
  [in]           SC_HANDLE hService,
  [in]           DWORD     dwNumServiceArgs,
  [in, optional] LPCSTR    *lpServiceArgVectors
);

Parametri

[in] hService

Handle per il servizio. Questo handle viene restituito dalla funzione OpenService o CreateService e deve avere il diritto di accesso SERVICE_START. Per altre informazioni, vedere Service Security and Access Rights.

[in] dwNumServiceArgs

Numero di stringhe nella matrice lpServiceArgVectors. Se lpServiceArgVectors è NULL, questo parametro può essere zero.

[in, optional] lpServiceArgVectors

Stringhe con terminazione Null da passare alla funzione servicemain per il servizio come argomenti. Se non sono presenti argomenti, questo parametro può essere NULL. In caso contrario, il primo argomento (lpServiceArgVectors[0]) è il nome del servizio, seguito da eventuali argomenti aggiuntivi (lpServiceArgVectors[1] fino a lpServiceArgVectors[dwNumServiceArgs-1]).

I servizi driver non ricevono questi argomenti.

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.

I codici di errore seguenti possono essere impostati dal gestore di controllo del servizio. Altri possono essere impostati dalle funzioni del Registro di sistema chiamate dal gestore del controllo del servizio.

Codice restituito	Descrizione
ERROR_ACCESS_DENIED	L'handle non dispone del diritto di accesso SERVICE_START.
ERROR_INVALID_HANDLE	L'handle non è valido.
ERROR_PATH_NOT_FOUND	Impossibile trovare il file binario del servizio.
ERROR_SERVICE_ALREADY_RUNNING	Un'istanza del servizio è già in esecuzione.
ERROR_SERVICE_DATABASE_LOCKED	Il database è bloccato.
ERROR_SERVICE_DEPENDENCY_DELETED	Il servizio dipende da un servizio che non esiste o è stato contrassegnato per l'eliminazione.
ERROR_SERVICE_DEPENDENCY_FAIL	Il servizio dipende da un altro servizio che non è stato avviato.
ERROR_SERVICE_DISABLED	Il servizio è stato disabilitato.
ERROR_SERVICE_LOGON_FAILED	Il servizio non è stato avviato a causa di un errore di accesso. Questo errore si verifica se il servizio è configurato per l'esecuzione con un account che non dispone del diritto "Accesso come servizio".
ERROR_SERVICE_MARKED_FOR_DELETE	Il servizio è stato contrassegnato per l'eliminazione.
ERROR_SERVICE_NO_THREAD	Impossibile creare un thread per il servizio.
ERROR_SERVICE_REQUEST_TIMEOUT	Il processo per il servizio è stato avviato, ma non ha chiamato StartServiceCtrlDispatchero il thread che ha chiamato StartServiceCtrlDispatcher potrebbe essere bloccato in una funzione del gestore di controllo.

Osservazioni

Quando viene avviato un servizio driver, la funzione StartService non viene restituita fino al termine dell'inizializzazione del driver di dispositivo.

Quando un servizio viene avviato, Service Control Manager (SCM) genera il processo del servizio, se necessario. Se il servizio specificato condivide un processo con altri servizi, è possibile che il processo richiesto esista già. La funzione StartService non attende il primo aggiornamento dello stato dal nuovo servizio, perché può richiedere del tempo. Restituisce invece quando Gestione controllo servizi riceve una notifica dal dispatcher del controllo del servizio che indica che il thread serviceMain per questo servizio è stato creato correttamente.

Gestione controllo servizi imposta i valori di stato predefiniti seguenti prima di restituire da StartService:

Lo stato corrente del servizio è impostato su SERVICE_START_PENDING.
I controlli accettati sono impostati su nessuno (zero).
Il valore checkpoint è impostato su zero.
Il tempo WaitHint è impostato su 2 secondi.

Il processo chiamante può determinare se il nuovo servizio ha terminato l'inizializzazione chiamando periodicamente la funzione QueryServiceStatus per eseguire query sullo stato del servizio.

Un servizio non può chiamare StartService durante l'inizializzazione. Il motivo è che Gestione controllo servizi blocca il database di controllo del servizio durante l'inizializzazione, pertanto una chiamata a StartService verrà bloccata. Dopo che il servizio segnala a Gestione controllo servizi che è stato avviato correttamente, può chiamare StartService.

Come per ControlService, StartService bloccherà per 30 secondi se un servizio è occupato a gestire un codice di controllo. Se il servizio occupato non è ancora stato restituito dalla funzione del gestore quando scade il timeout, StartService ha esito negativo con ERROR_SERVICE_REQUEST_TIMEOUT. Questo perché Gestione controllo servizi elabora una sola notifica di controllo del servizio alla volta.

Esempi

Per un esempio, vedere Avvio di un servizio.

Nota

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