Funzione CreateServiceW (winsvc.h)
Crea un oggetto servizio e lo aggiunge al database di gestione controllo del servizio specificato.
Sintassi
SC_HANDLE CreateServiceW(
[in] SC_HANDLE hSCManager,
[in] LPCWSTR lpServiceName,
[in, optional] LPCWSTR lpDisplayName,
[in] DWORD dwDesiredAccess,
[in] DWORD dwServiceType,
[in] DWORD dwStartType,
[in] DWORD dwErrorControl,
[in, optional] LPCWSTR lpBinaryPathName,
[in, optional] LPCWSTR lpLoadOrderGroup,
[out, optional] LPDWORD lpdwTagId,
[in, optional] LPCWSTR lpDependencies,
[in, optional] LPCWSTR lpServiceStartName,
[in, optional] LPCWSTR lpPassword
);
Parametri
[in] hSCManager
Handle per il database di Gestione controllo dei servizi. Questo handle viene restituito dalla funzione OpenSCManager e deve avere il diritto di accesso SC_MANAGER_CREATE_SERVICE . Per altre informazioni, vedere Sicurezza del servizio e diritti di accesso.
[in] lpServiceName
Nome del servizio da installare. La lunghezza massima della stringa è di 256 caratteri. Il database di Gestione controllo dei servizi mantiene la distinzione tra maiuscole e minuscole, ma i confronti dei nomi del servizio non fanno sempre distinzione tra maiuscole e minuscole. La barra (/) e la barra rovesciata (\) non sono caratteri di nome del servizio validi.
[in, optional] lpDisplayName
Nome visualizzato da utilizzare dai programmi dell'interfaccia utente per identificare il servizio. La lunghezza massima della stringa è di 256 caratteri. Il nome viene mantenuto senza maiuscole/minuscole nella gestione controllo del servizio. I confronti dei nomi visualizzati sono sempre senza distinzione tra maiuscole e minuscole.
[in] dwDesiredAccess
Accesso al servizio. Prima di concedere l'accesso richiesto, il sistema controlla il token di accesso del processo chiamante. Per un elenco di valori, vedere Sicurezza dei servizi e diritti di accesso.
[in] dwServiceType
Tipo di servizio. Questo parametro può avere uno dei valori seguenti.
| Valore | Significato |
|---|---|
|
Riservato. |
|
Servizio driver del file system. |
|
Servizio driver. |
|
Riservato. |
|
Servizio eseguito nel proprio processo. |
|
Servizio che condivide un processo con uno o più servizi. Per altre informazioni, vedere Programmi di servizio. |
Se si specifica SERVICE_WIN32_OWN_PROCESS o SERVICE_WIN32_SHARE_PROCESS e il servizio è in esecuzione nel contesto dell'account LocalSystem, è anche possibile specificare il valore seguente.
| Valore | Significato |
|---|---|
|
Il servizio può interagire con il desktop.
Per altre informazioni, vedere Interactive Services. |
[in] dwStartType
Opzioni di avvio del servizio. Questo parametro può avere uno dei valori seguenti.
| Valore | Significato |
|---|---|
|
Un servizio avviato automaticamente dal gestore di controllo del servizio durante l'avvio del sistema. Per altre informazioni, vedere Avvio automatico dei servizi. |
|
Driver di dispositivo avviato dal caricatore di sistema. Questo valore è valido solo per i servizi del driver. |
|
Servizio avviato da Gestione controllo del servizio quando un processo chiama la funzione StartService . Per altre informazioni, vedere Avvio di servizi su richiesta. |
|
Servizio che non può essere avviato. I tentativi di avvio del servizio generano il codice di errore ERROR_SERVICE_DISABLED. |
|
Driver di dispositivo avviato dalla funzione IoInitSystem . Questo valore è valido solo per i servizi del driver. |
[in] dwErrorControl
Gravità dell'errore e azione eseguita, se il servizio non viene avviato. Questo parametro può avere uno dei valori seguenti.
[in, optional] lpBinaryPathName
Percorso completo del file binario del servizio. Se il percorso contiene uno spazio, deve essere racchiuso tra virgolette in modo che venga interpretato correttamente. Ad esempio, "d:\my share\myservice.exe" deve essere specificato come ""d:\my share\myservice.exe"".
Il percorso può includere anche argomenti per un servizio di avvio automatico. Ad esempio, "d:\myshare\myservice.exe arg1 arg2". Questi argomenti vengono passati al punto di ingresso del servizio (in genere la funzione principale ).
Se si specifica un percorso in un altro computer, la condivisione deve essere accessibile dall'account computer del computer locale perché si tratta del contesto di sicurezza utilizzato nella chiamata remota. Tuttavia, questo requisito consente a eventuali potenziali vulnerabilità nel computer remoto di influire sul computer locale. Pertanto, è consigliabile usare un file locale.
[in, optional] lpLoadOrderGroup
Nomi del gruppo di ordinamento del carico di cui questo servizio è membro. Specificare NULL o una stringa vuota se il servizio non appartiene a un gruppo.
Il programma di avvio usa i gruppi di ordinamento del carico per caricare gruppi di servizi in un ordine specificato rispetto agli altri gruppi. L'elenco dei gruppi di ordinamento del carico è contenuto nel valore del Registro di sistema seguente: HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\ServiceGroupOrder
[out, optional] lpdwTagId
Puntatore a una variabile che riceve un valore di tag univoco nel gruppo specificato nel parametro lpLoadOrderGroup . Specificare NULL se non si modifica il tag esistente.
È possibile usare un tag per l'avvio del servizio di ordinamento all'interno di un gruppo di ordinamento di carico specificando un vettore di ordine di tag nel valore del Registro di sistema seguente:HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\GroupOrderList
I tag vengono valutati solo per i servizi driver con SERVICE_BOOT_START o SERVICE_SYSTEM_START tipi di avvio.
[in, optional] lpDependencies
Puntatore a una matrice con terminazione Null doppia di nomi separati da Null di servizi o gruppi di ordinamento di carico che il sistema deve avviare prima di questo servizio. Specificare NULL o una stringa vuota se il servizio non ha dipendenze. La dipendenza da un gruppo significa che questo servizio può essere eseguito se almeno un membro del gruppo è in esecuzione dopo un tentativo di avviare tutti i membri del gruppo.
È necessario anteporre i nomi dei gruppi con SC_GROUP_IDENTIFIER in modo che possano essere distinti da un nome di servizio, perché i servizi e i gruppi di servizi condividono lo stesso spazio dei nomi.
[in, optional] lpServiceStartName
Nome dell'account in cui deve essere eseguito il servizio. Se il tipo di servizio è SERVICE_WIN32_OWN_PROCESS, usare un nome account nel formato NomeUtente\NomeDominio. Il processo del servizio verrà connesso come utente. Se l'account appartiene al dominio predefinito, è possibile specificare .\UserName.
Se questo parametro è NULL, CreateService usa l'account LocalSystem. Se il tipo di servizio specifica SERVICE_INTERACTIVE_PROCESS, il servizio deve essere eseguito nell'account LocalSystem.
Se questo parametro è NT AUTHORITY\LocalService, CreateService usa l'account LocalService. Se il parametro è NT AUTHORITY\ NetworkService, CreateService usa l'account NetworkService.
Un processo condiviso può essere eseguito come qualsiasi utente.
Se il tipo di servizio è SERVICE_KERNEL_DRIVER o SERVICE_FILE_SYSTEM_DRIVER, il nome è il nome dell'oggetto driver usato dal sistema per caricare il driver di dispositivo. Specificare NULL se il driver deve usare un nome di oggetto predefinito creato dal sistema di I/O.
Un servizio può essere configurato per l'uso di un account gestito o di un account virtuale. Se il servizio è configurato per l'uso di un account del servizio gestito, il nome è il nome dell'account del servizio gestito. Se il servizio è configurato per l'uso di un account virtuale, specificare il nome NT SERVICE\ServiceName. Per altre informazioni sugli account del servizio gestito e sugli account virtuali, vedere la Guida dettagliata agli account del servizio.
Windows Server 2008, Windows Vista, Windows Server 2003 e Windows XP: Gli account del servizio gestito e gli account virtuali non sono supportati fino a Windows 7 e Windows Server 2008 R2.
[in, optional] lpPassword
Password del nome dell'account specificato dal parametro lpServiceStartName . Specificare una stringa vuota se l'account non ha password o se il servizio viene eseguito nell'account LocalService, NetworkService o LocalSystem. Per altre informazioni, vedere Elenco di record del servizio.
Se il nome dell'account specificato dal parametro lpServiceStartName è il nome di un account del servizio gestito o di un nome account virtuale, il parametro lpPassword deve essere NULL.
Le password vengono ignorate per i servizi driver.
Valore restituito
Se la funzione ha esito positivo, il valore restituito è un handle per il servizio.
Se la funzione ha esito negativo, il valore restituito è NULL. Per informazioni dettagliate sull'errore, chiamare GetLastError.
I codici di errore seguenti possono essere impostati 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 |
|---|---|
|
L'handle per il database SCM non dispone del diritto di accesso SC_MANAGER_CREATE_SERVICE . |
|
È stata specificata una dipendenza del servizio circolare. |
|
Il nome visualizzato esiste già nel database di Gestione controllo dei servizi come nome del servizio o come altro nome visualizzato. |
|
L'handle per il database di Gestione controllo del servizio specificato non è valido. |
|
Il nome del servizio specificato non è valido. |
|
Parametro specificato non valido. |
|
Il nome dell'account utente specificato nel parametro lpServiceStartName non esiste. |
|
Il servizio specificato esiste già in questo database. |
|
Il servizio specificato esiste già in questo database ed è stato contrassegnato per l'eliminazione. |
Commenti
La funzione CreateService crea un oggetto servizio e la installa nel database di Gestione controllo servizi creando una chiave con lo stesso nome del servizio nella chiave del Registro di sistema seguente:HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services
Le informazioni specificate da CreateService, ChangeServiceConfig e ChangeServiceConfig2 vengono salvate come valori in questa chiave. Di seguito sono riportati esempi di valori archiviati per un servizio.
| Valore | Descrizione |
|---|---|
| DependOnGroup | Gruppi di ordinamento del carico da cui dipende questo servizio, come specificato da lpDependencies. |
| DependOnService | Servizi da cui dipende questo servizio, come specificato da lpDependencies. |
| Descrizione | Descrizione specificata da ChangeServiceConfig2. |
| DisplayName | Nome visualizzato specificato da lpDisplayName. |
| ErrorControl | Controllo degli errori specificato da dwErrorControl. |
| FailureActions | Azioni di errore specificate da ChangeServiceConfig2. |
| Gruppo | Gruppo di ordinamento del carico specificato da lpLoadOrderGroup. Si noti che l'impostazione di questo valore può eseguire l'override dell'impostazione del valore DependOnService . |
| Imagepath | Nome del file binario, come specificato da lpBinaryPathName. |
| ObjectName | Nome account specificato da lpServiceStartName. |
| Inizia | Quando avviare il servizio, come specificato da dwStartType. |
| Tag | Identificatore di tag specificato da lpdwTagId. |
| Tipo | Tipo di servizio specificato da dwServiceType. |
I programmi di installazione e il servizio stesso possono creare sottochiavi aggiuntivi per informazioni specifiche del servizio.
L'handle restituito è valido solo per il processo denominato CreateService. Può essere chiuso chiamando la funzione CloseServiceHandle .
Se si creano servizi che condividono un processo, evitare di chiamare funzioni con effetti a livello di processo, ad esempio ExitProcess. Inoltre, non scaricare la DLL del servizio.
Esempio
Per un esempio, vedere Installazione di un servizio.
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 |
Vedi anche
QueryServiceDynamicInformation
Guida dettagliata agli account del servizio gestiti