Funzione NotifyServiceStatusChangeW (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 NotifyServiceStatusChangeW(
  [in] SC_HANDLE        hService,
  [in] DWORD            dwNotifyMask,
  [in] PSERVICE_NOTIFYW pNotifyBuffer
);

Parametri

[in] hService

Handle per il servizio o il gestore di 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 della gestione controllo del servizio vengono restituiti dalla funzione OpenSCManager e devono avere il diritto di accesso SC_MANAGER_ENUMERATE_SERVICE. Per altre informazioni, vedere Service Security and Access Rights.

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.

[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 fino a quando non viene richiamata la funzione di callback 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 è 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 .

Osservazioni

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 asincrona (APC) accodata al thread chiamante. Il thread chiamante deve immettere un'attesa avvisabile (ad esempio chiamando la funzione SleepEx ) per ricevere la notifica. Per altre informazioni, vedere chiamate di procedure asincrone.

Se il servizio è 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 sul thread chiamante con il diritto di accesso THREAD_SET_CONTEXT. Se il thread chiamante non dispone di questo diritto di accesso, NotifyServiceStatusChange non riesce. 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 che non creare 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 avvisabile, pertanto non sono 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 che CloseServiceHandle ha esito positivo, non verranno accodati altri APC di notifica. Se il thread chiamante viene chiuso senza chiudere l'handle del servizio o attendere fino a quando non viene generato il servizio APC, può verificarsi una perdita di memoria.

Fabbisogno

Vedere anche

SERVICE_NOTIFY

SubscribeServiceChangeNotifications

Funzioni del servizio