Funzione NotifyServiceStatusChangeW (winsvc.h)

Articolo
08/27/2023

Consente a un'applicazione di ricevere una notifica quando il servizio specificato viene creato o eliminato o quando lo stato cambia.

Sintassi

DWORD NotifyServiceStatusChangeW(
  [in] SC_HANDLE        hService,
  [in] DWORD            dwNotifyMask,
  [in] PSERVICE_NOTIFYW pNotifyBuffer
);

Parametri

[in] hService

Handle al servizio o al 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 al gestore del 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
SERVICE_NOTIFY_CREATED 0x00000080	Segnalare quando è stato creato il servizio. Il parametro hService deve essere un handle per SCM.
SERVICE_NOTIFY_CONTINUE_PENDING 0x00000010	Segnalare quando il servizio sta per continuare. Il parametro hService deve essere un handle per il servizio.
SERVICE_NOTIFY_DELETE_PENDING 0x00000200	Segnalare quando un'applicazione ha specificato il servizio in una chiamata alla funzione DeleteService . L'applicazione deve chiudere eventuali handle al servizio in modo che possa essere eliminata. Il parametro hService deve essere un handle per il servizio.
SERVICE_NOTIFY_DELETED 0x00000100	Segnalare quando il servizio è stato eliminato. Un'applicazione non può ricevere questa notifica se ha un handle aperto al servizio. Il parametro hService deve essere un handle per SCM.
SERVICE_NOTIFY_PAUSE_PENDING 0x00000020	Segnalare quando il servizio è in pausa. Il parametro hService deve essere un handle per il servizio.
SERVICE_NOTIFY_PAUSED 0x00000040	Segnalare quando il servizio è sospeso. Il parametro hService deve essere un handle per il servizio.
SERVICE_NOTIFY_RUNNING 0x00000008	Segnalare quando il servizio è in esecuzione. Il parametro hService deve essere un handle per il servizio.
SERVICE_NOTIFY_START_PENDING 0x00000002	Segnalare all'avvio del servizio. Il parametro hService deve essere un handle per il servizio.
SERVICE_NOTIFY_STOP_PENDING 0x00000004	Segnalare quando il servizio viene arrestato. Il parametro hService deve essere un handle per il servizio.
SERVICE_NOTIFY_STOPPED 0x00000001	Segnalare quando il servizio è stato arrestato. Il parametro hService deve essere un handle per il servizio.

[in] pNotifyBuffer

Puntatore a una struttura di SERVICE_NOTIFY contenente informazioni di notifica, ad esempio un puntatore alla funzione di callback. Questa struttura deve rimanere valida fino a quando la funzione di callback 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 della 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. Pertanto, la funzione di callback non può essere codice generato in fase di esecuzione, ad esempio il codice gestito generato dal compilatore JIT, o il 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 al servizio deve essere chiuso. Se la notifica del servizio è in ritardo 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 nuovamente 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 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 procedura 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 è cambiato alla successiva chiamata alla funzione con lo stesso servizio e lo stato, la funzione di callback non viene accodata immediatamente; la funzione di callback viene accodata alla successiva entrata del servizio nello stato richiesto.

La funzione NotifyServiceStatusChange chiama la funzione OpenThread nel thread chiamante con il THREAD_SET_CONTEXT diritto di accesso. Se il thread chiamante non ha questo diritto di accesso, NotifyServiceStatusChange ha esito negativo. Se il thread chiamante rappresenta un altro utente, potrebbe non avere 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 avvisabile, quindi non sono sicure da chiamare dall'interno della funzione di callback. La funzione di callback deve invece 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 aver completato CloseServiceHandle , non verranno accodate altre API 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.

Importante Se il thread chiamante si trova in una DLL e la DLL viene scaricata prima che il thread riceva la notifica o chiami CloseServiceHandle, la notifica causerà risultati imprevedibili e potrebbe causare l'arresto del processo di risposta.

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 preprocessore UNICODE. La combinazione dell'utilizzo dell'alias di codifica neutrale con il codice che non è neutrale dalla codifica può causare errori di corrispondenza che causano errori di compilazione o runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzione.

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

Vedi anche

SERVICE_NOTIFY

SubscribeServiceChangeNotifications

Funzioni del servizio