Funzione NotifyServiceStatusChangeA (winsvc.h)
Consente a un'applicazione di ricevere una notifica quando il servizio specificato viene creato o eliminato o quando cambia lo stato.
Sintassi
DWORD NotifyServiceStatusChangeA(
[in] SC_HANDLE hService,
[in] DWORD dwNotifyMask,
[in] PSERVICE_NOTIFYA pNotifyBuffer
);
Parametri
[in] hService
Handle per il servizio o lo strumento di gestione del controllo del servizio. Gli handle ai servizi vengono restituiti dalla funzione OpenService o CreateService e devono avere il diritto di accesso SERVICE_QUERY_STATUS. Gli handle per la gestione controllo del servizio vengono restituiti dalla funzione OpenSCManager e devono avere il diritto di accesso SC_MANAGER_ENUMERATE_SERVICE. Per altre informazioni, vedere Sicurezza del servizio e diritti di accesso.
Può essere presente una sola richiesta di notifica in sospeso per servizio.
[in] dwNotifyMask
Tipo di modifiche dello stato da segnalare. Questo parametro può essere uno o più dei valori seguenti.
| Valore | Significato |
|---|---|
|
Report al momento della creazione del servizio.
Il parametro hService deve essere un handle per SCM. |
|
Segnalare quando il servizio sta per continuare.
Il parametro hService deve essere un handle per il servizio. |
|
Segnalare quando un'applicazione ha specificato il servizio in una chiamata alla funzione DeleteService . L'applicazione deve chiudere tutti gli handle al servizio in modo che possa essere eliminato.
Il parametro hService deve essere un handle per il servizio. |
|
Segnalare quando il servizio è stato eliminato. Un'applicazione non può ricevere questa notifica se ha un handle aperto per il servizio.
Il parametro hService deve essere un handle per SCM. |
|
Segnalare quando il servizio è in pausa.
Il parametro hService deve essere un handle per il servizio. |
|
Segnalare quando il servizio è stato sospeso.
Il parametro hService deve essere un handle per il servizio. |
|
Segnalare quando il servizio è in esecuzione.
Il parametro hService deve essere un handle per il servizio. |
|
Segnalare all'avvio del servizio.
Il parametro hService deve essere un handle per il servizio. |
|
Segnalare quando il servizio viene arrestato.
Il parametro hService deve essere un handle per il servizio. |
|
Segnalare quando il servizio è stato arrestato.
Il parametro hService deve essere un handle per il servizio. |
[in] pNotifyBuffer
Puntatore a una struttura SERVICE_NOTIFY che contiene informazioni di notifica, ad esempio un puntatore alla funzione di callback. Questa struttura deve rimanere valida finché la funzione di callback non viene richiamata o il thread chiamante annulla la richiesta di notifica.
Non effettuare più chiamate a NotifyServiceStatusChange con lo stesso parametro del buffer finché la funzione di callback dalla prima chiamata non è stata completata con il buffer o la prima richiesta di notifica è stata annullata. In caso contrario, non esiste alcuna garanzia quale versione del buffer riceverà la funzione di callback.
Windows Vista: L'indirizzo della funzione di callback deve essere compreso nell'intervallo di indirizzi di un modulo caricato. Di conseguenza, la funzione di callback non può essere codice generato in fase di esecuzione (ad esempio codice gestito generato dal compilatore JIT) o codice nativo decompresso in fase di esecuzione. Questa restrizione è stata rimossa in Windows Server 2008 e Windows Vista con SP1.
Valore restituito
Se la funzione ha esito positivo, il valore restituito viene ERROR_SUCCESS. Se il servizio è stato contrassegnato per l'eliminazione, il valore restituito è ERROR_SERVICE_MARKED_FOR_DELETE e l'handle per il servizio deve essere chiuso. Se la notifica del servizio è troppo indietro rispetto allo stato del sistema, la funzione restituisce ERROR_SERVICE_NOTIFY_CLIENT_LAGGING. In questo caso, il client deve chiudere l'handle a SCM, aprire un nuovo handle e chiamare di nuovo questa funzione.
Se la funzione ha esito negativo, il valore restituito è uno dei codici di errore di sistema.
Commenti
La funzione NotifyServiceStatusChange può essere usata per ricevere notifiche sulle applicazioni di servizio. Non può essere usato per ricevere notifiche sui servizi driver.
Quando lo stato del servizio cambia, il sistema richiama la funzione di callback specificata come chiamata di procedura asincrona (APC) accodata al thread chiamante. Per ricevere la notifica, il thread chiamante deve immettere un'attesa di avviso, ad esempio chiamando la funzione SleepEx . Per altre informazioni, vedere Chiamate di routine asincrone.
Se il servizio si trova già in uno degli stati richiesti quando viene chiamato NotifyServiceStatusChange , la funzione di callback viene accodata immediatamente. Se lo stato del servizio non è stato modificato alla successiva chiamata della funzione con lo stesso servizio e lo stesso stato, la funzione di callback non viene accodata immediatamente; La funzione di callback viene accodata la volta successiva che il servizio entra nello stato richiesto.
La funzione NotifyServiceStatusChange chiama la funzione OpenThread nel thread chiamante con il diritto di accesso THREAD_SET_CONTEXT. Se il thread chiamante non ha questo diritto di accesso, NotifyServiceStatusChange ha esito negativo. Se il thread chiamante rappresenta un altro utente, potrebbe non disporre di autorizzazioni sufficienti per impostare il contesto.
È più efficiente chiamare NotifyServiceStatusChange da un thread che esegue un'attesa rispetto alla creazione di un thread aggiuntivo.
Dopo aver richiamato la funzione di callback, il chiamante deve chiamare NotifyServiceStatusChange per ricevere notifiche aggiuntive. Si noti che alcune funzioni nell'API Windows, tra cui NotifyServiceStatusChange e altre funzioni SCM, usano chiamate di procedura remota (RPC); queste funzioni possono eseguire un'operazione di attesa di avviso, in modo che non siano sicure da chiamare dall'interno della funzione di callback. Al contrario, la funzione di callback deve salvare i parametri di notifica ed eseguire qualsiasi lavoro aggiuntivo all'esterno del callback.
Per annullare le notifiche in sospeso, chiudere l'handle del servizio usando la funzione CloseServiceHandle . Dopo l'esito positivo di CloseServiceHandle , non verranno accodate altre API di notifica. Se il thread chiamante viene chiuso senza chiudere l'handle del servizio o attendere la generazione dell'APC, può verificarsi una perdita di memoria.
Nota
L'intestazione winsvc.h definisce NotifyServiceStatusChange 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 Vista [solo app desktop] |
| Server minimo supportato | Windows Server 2008 [solo app desktop] |
| Piattaforma di destinazione | Windows |
| Intestazione | winsvc.h (include Windows.h) |
| Libreria | Advapi32.lib |
| DLL | Advapi32.dll |