Metodo ICaptureGraphBuilder2::ControlStream (strmif.h)

Articolo
07/28/2023

[La funzionalità associata a questa pagina, DirectShow, è una funzionalità legacy. È stata sostituita da MediaPlayer, IMFMediaEngine e Audio/Video Capture in Media Foundation. Queste funzionalità sono state ottimizzate per Windows 10 e Windows 11. Microsoft consiglia vivamente che il nuovo codice usi MediaPlayer, IMFMediaEngine e Audio/Video Capture in Media Foundation invece di DirectShow, quando possibile. Microsoft suggerisce che il codice esistente che usa le API legacy venga riscritto per usare le nuove API, se possibile.

Il ControlStream metodo imposta gli orari di inizio e arresto per uno o più flussi di dati acquisiti.

Sintassi

HRESULT ControlStream(
  [in] const GUID     *pCategory,
  [in] const GUID     *pType,
  [in] IBaseFilter    *pFilter,
  [in] REFERENCE_TIME *pstart,
  [in] REFERENCE_TIME *pstop,
  [in] WORD           wStartCookie,
  [in] WORD           wStopCookie
);

Parametri

[in] pCategory

Puntatore a un GUID che specifica una delle categorie di pin elencate in Pin Property Set. Il valore di questo parametro non può essere NULL.

[in] pType

Puntatore a un GUID di tipo principale che specifica il tipo di supporto o NULL. Se questo parametro è NULL, impostare anche il parametro pFilter su NULL . In caso contrario, è possibile controllare il pin errato e ottenere risultati imprevedibili.

[in] pFilter

Puntatore a un'interfaccia IBaseFilter che specifica il filtro da controllare. Per controllare tutti i filtri di acquisizione nel grafico, impostare questo parametro su NULL.

[in] pstart

Puntatore a una variabile contenente l'ora di inizio. Se il valore è MAXLONGLONG (0x7FFFFFFFFFFFFFFF), il metodo annulla la richiesta di avvio precedente. Se il valore è NULL, il pin viene avviato immediatamente quando viene eseguito il grafico.

[in] pstop

Puntatore a una variabile che contiene l'ora di arresto. Se il valore è MAXLONGLONG, il metodo annulla qualsiasi richiesta di arresto precedente. Se il valore è NULL, il pin viene arrestato immediatamente.

[in] wStartCookie

Valore inviato come secondo parametro della notifica degli eventi EC_STREAM_CONTROL_STARTED . Per ulteriori informazioni, vedere la sezione Osservazioni.

[in] wStopCookie

Valore inviato come secondo parametro della notifica degli eventi EC_STREAM_CONTROL_STOPPED . Per ulteriori informazioni, vedere la sezione Osservazioni.

Valore restituito

Restituisce un valore HRESULT . Di seguito sono indicati alcuni valori possibili.

Codice restituito	Descrizione
S_FALSE	Almeno un renderer downstream non invierà una notifica di arresto.
S_OK	Operazione completata.
E_FAIL	Impossibile trovare un pin corrispondente oppure il pin non supportava il controllo del flusso.
E_POINTER	Argomento puntatore NULL.

Commenti

Questo metodo individua i pin di output nei filtri di acquisizione, usando i criteri di ricerca specificati nella chiamata al metodo. Chiama quindi i metodi IAMStreamControl su tali pin. Questo metodo consente a un'applicazione di controllare i flussi senza che l'applicazione debba enumerare i filtri e i puntini nel grafico.

Usare questo metodo per l'acquisizione accurata dei fotogrammi o per il controllo individuale dell'acquisizione e dell'anteprima. Ad esempio, è possibile arrestare l'acquisizione su disco ma lasciare in esecuzione l'anteprima video.

I primi tre parametri specificano i pin da controllare. Un grafico di acquisizione può avere più di un filtro di acquisizione. Ad esempio, potrebbe avere filtri per i dati di video, audio e sottotitoli. Inoltre, un filtro di acquisizione può avere più di un pin di output. Alcuni filtri di acquisizione hanno pin separati per l'anteprima e l'acquisizione o pin separati per dati solo video e dati interleaved audio-video. Per controllare l'anteprima video, ad esempio, specificare PIN_CATEGORY_PREVIEW per pCategory e MEDIATYPE_Video per pType.

Nota

Se la categoria pin è PIN_CATEGORY_PREVIEW, non è possibile impostare orari di inizio e arresto specifici, perché gli esempi recapitati da un pin di anteprima non hanno timestamp (vedere Timestamp). Usare invece i valori NULL e MAXLONGLONG per avviare e arrestare il pin nei momenti desiderati.

Inoltre, questo metodo non è supportato per l'anteprima se il dispositivo usa un pin di porta video, perché in questo caso il dispositivo distribuisce gli esempi di anteprima direttamente sull'hardware.

Per controllare un pin, questo metodo chiama i metodi IAMStreamControl::StartAt e IAMStreamControl::StopAt . Ogni pin invia una notifica di evento EC_STREAM_CONTROL_STARTED all'avvio. Il secondo parametro della notifica degli eventi è il valore specificato in wStartCookie. Quando il pin si arresta, invia una notifica di evento EC_STREAM_CONTROL_STOPPED . Il secondo parametro della notifica degli eventi è il valore specificato in wStopCookie.

Quando questo metodo individua un pin corrispondente, cerca un altro filtro downstream che supporta IAMStreamControl (in genere un multiplexer). Se ne trova uno, imposta anche l'ora di inizio e di arresto per tale filtro. Vengono generate due coppie di notifiche di arresto: una per il filtro di acquisizione e una per il filtro downstream. Solo la notifica di arresto dal filtro downstream usa il parametro wStopCookie . In attesa di questo evento si garantisce che il filtro downstream riceva l'ultimo esempio.

Se nessun filtro downstream supporta IAMStreamControl, il metodo restituisce S_FALSE. In tal caso, è possibile ricevere la notifica di arresto prima del rendering dell'ultimo esempio.

MAXLONGLONG è il valore REFERENCE_TIME più grande possibile. Nella libreria di classi di base DirectShow viene definita anche come costante MAX_TIME.

Requisiti

Requisito	Valore
Client minimo supportato	Windows 2000 Professional [solo app desktop]
Server minimo supportato	Windows 2000 Server [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	strmif.h (include Dshow.h)
Libreria	Strmiids.lib

Vedi anche

Codici di errore e di esito positivo

Interfaccia ICaptureGraphBuilder2

Condividi tramite