Funzione EvtSubscribe (winevt.h)

Crea una sottoscrizione che riceverà eventi correnti e futuri da un canale o un file di log che corrispondono ai criteri di query specificati.

Sintassi

EVT_HANDLE EvtSubscribe(
  [in] EVT_HANDLE             Session,
  [in] HANDLE                 SignalEvent,
  [in] LPCWSTR                ChannelPath,
  [in] LPCWSTR                Query,
  [in] EVT_HANDLE             Bookmark,
  [in] PVOID                  Context,
  [in] EVT_SUBSCRIBE_CALLBACK Callback,
  [in] DWORD                  Flags
);

Parametri

[in] Session

Handle di sessione remoto restituito dalla funzione EvtOpenSession . Impostare su NULL per sottoscrivere eventi nel computer locale.

[in] SignalEvent

Handle a un oggetto evento che il servizio segnalerà quando sono disponibili nuovi eventi che corrispondono ai criteri di query. Questo parametro deve essere NULL se il parametro Callback non è NULL.

[in] ChannelPath

Nome del canale Amministrazione o operativo che contiene gli eventi da sottoscrivere (non è possibile sottoscrivere canali analitici o debug). Il percorso è obbligatorio se il parametro Query contiene una query XPath; il percorso viene ignorato se il parametro Query contiene una query XML strutturata.

[in] Query

Query che specifica i tipi di eventi che si desidera che il servizio di sottoscrizione restituisca. È possibile specificare una query XPath 1.0 o una query XML strutturata. Se XPath contiene più di 20 espressioni, usare una query XML strutturata. Per ricevere tutti gli eventi, impostare questo parametro su NULL o "*".

[in] Bookmark

Handle a un segnalibro che identifica il punto iniziale per la sottoscrizione. Per ottenere un handle di segnalibro, chiamare la funzione EvtCreateBookmark . È necessario impostare questo parametro se il parametro Flags contiene il flag EvtSubscribeStartAfterBookmark; in caso contrario, NULL.

[in] Context

Valore di contesto definito dal chiamante che il servizio sottoscrizione passerà al callback specificato ogni volta che restituisce un evento.

[in] Callback

Puntatore alla funzione di callback EVT_SUBSCRIBE_CALLBACK che riceverà gli eventi della sottoscrizione. Questo parametro deve essere NULL se il parametro SignalEvent non è NULL.

[in] Flags

Uno o più flag che specificano quando avviare la sottoscrizione agli eventi. Ad esempio, se si specifica EvtSubscribeStartAtOldestRecord, il servizio recupera tutti gli eventi correnti e futuri che corrispondono ai criteri di query; tuttavia, se si specifica EvtSubscribeToFutureEvents, il servizio restituisce solo eventi futuri che corrispondono ai criteri di query. Per i valori possibili, vedere l'enumerazione EVT_SUBSCRIBE_FLAGS .

Valore restituito

Handle per la sottoscrizione se ha esito positivo; in caso contrario, NULL. Se la funzione restituisce NULL, chiamare la funzione GetLastError per ottenere il codice di errore. È necessario chiamare la funzione EvtClose con l'handle della sottoscrizione al termine.

Commenti

Per annullare la sottoscrizione, passare l'handle di sottoscrizione restituito alla funzione EvtClose .

Esistono due modelli di sottoscrizione: il modello di polling e il modello push. Nel modello push si implementa un callback della sottoscrizione e si imposta il parametro Callback sull'implementazione. Il servizio chiamerà il callback per ogni evento corrispondente ai criteri di query o se si verifica un errore.

Nel modello di polling si crea un oggetto evento che segnala il servizio. Quando viene segnalato, si chiama la funzione EvtNext usando l'handle della sottoscrizione per enumerare gli eventi. È necessario chiamare la funzione EvtClose in ogni evento enumerato. È quindi possibile reimpostare l'oggetto e attendere che il servizio segnali di nuovo. Questo processo viene ripetuto fino a quando non si annulla la sottoscrizione.

Esempio

Per un esempio che illustra come usare questa funzione, vedere Sottoscrizione agli eventi.

Requisiti

Client minimo supportato	Windows Vista [solo app desktop]
Server minimo supportato	Windows Server 2008 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	winevt.h
Libreria	Wevtapi.lib
DLL	Wevtapi.dll

Vedi anche

EVT_SUBSCRIBE_CALLBACK

EvtQuery