Pin KS

Il minidriver fornisce una struttura KSPIN_DESCRIPTOR per ogni tipo di pin da creare un'istanza. Una struttura di descrittore pin è nota come una fabbrica di pin. Ogni pin factory può creare un'istanza di una o più istanze di pin di un tipo specifico. Una pin factory contiene diverse matrici che descrivono il tipo di pin creato da questo descrittore.

Il minidriver specifica una o più categorie KS a cui i pin creati da questo descrittore appartengono al membro Categorie di KSPIN_DESCRIPTOR. KS usa le categorie per connettere le istanze del pin quando compila un grafico di filtro. Query di proprietà KSPROPERTY_TOPOLOGY_CATEGORIES per la matrice di categorie funzionali supportate da un driver.

Un minidriver fornisce un file INF che registra uno o più nomi di dispositivo pin. All'installazione, il sistema operativo carica i nomi e le categorie corrispondenti nel Registro di sistema. I client possono quindi effettuare chiamate create-file con questi nomi di dispositivo per creare un'istanza dei pin.

I client in modalità utente chiamano la funzione CreateFile Win32 con il nome del dispositivo. Ad esempio, "\\.\filters\audio\default renderer" può essere un collegamento al dispositivo audio configurato per l'output predefinito. I client in modalità kernel chiamano ZwCreateFile dalla modalità kernel. Dopo che la routine create-file restituisce un handle di file, i client KS comunicano con istanze di pin tramite le proprietà KS.

Nelle strutture del descrittore di pin, il minidriver specifica matrici di strutture KSPIN_INTERFACEe strutture KSPIN_MEDIUM che specificano le interfacce e i supporti supportati da tale pin factory. KSPIN_DESCRIPTOR è anche in cui il minidriver specifica gli intervalli di dati validi per i pin creati da tale factory. Questa operazione viene eseguita fornendo un puntatore a una matrice di strutture KSDATARANGE . Il minidriver specifica anche le direzioni del flusso di dati e comunicazione per i nuovi pin creati da questa pin factory.

Un minidriver consente l'individuazione in fase di esecuzione delle pin factory supportando il set di proprietà KSPROPSETID_Pin .

Per creare una connessione pin, chiamare la routine KsCreatePin . In questa chiamata, il minidriver passa un puntatore a una struttura di tipo KSPIN_CONNECT che descrive la connessione richiesta. Quando viene creato un pin, il filtro visualizza il nuovo pin come oggetto file subordinato all'oggetto file per tale filtro.

Il minidriver chiama KsValidateConnectRequest con le strutture descrittori fornite nella IRP_MJ_CREATE risultante. Questa routine convalida queste strutture e restituisce un puntatore alla struttura di connessione e all'oggetto file radice.

I minidriver usano i membri di DataFlow e Communication delle strutture KSPIN_DESCRIPTOR per definire le specifiche dei pin seguenti:

• Pin di origine IRP rispetto al pin sink IRP

  Un pin di origine IRP genera problemi di IRP; un pin sink IRP li riceve. Un client in modalità utente invia richieste di I/O direttamente a un pin sink IRP tramite l'handle di file pertinente. I client usano KSPROPERTY_PIN_COMMUNICATION per verificare se i flussi di dati in o fuori un tipo di pin.

• Pin dell'origine dati rispetto al pin del sink di dati

  Un pin dell'origine dati è un pin di output su un filtro; un pin sink di dati è un pin di input. La proprietà di essere un'origine dati o un sink è indipendente dall'essere un'origine o un sink IRP. Ad esempio, il client può connettere un'origine dati, un pin sink IRP a un sink di dati, un pin di origine IRP. I client usano KSPROPERTY_PIN_DATAFLOW per verificare se i flussi di dati in o fuori un tipo di pin.

Quando termina una connessione, l'handle del pin di origine deve essere chiuso prima che l'oggetto file sottostante venga eliminato. Se il pin di origine si basa sulle risorse fornite dal pin sink, è responsabilità del pin sink notificare all'origine quando la connessione viene terminata.

Un client interagisce con un pin di streaming del kernel chiamando la routine DeviceIoControl (descritta nella documentazione di Microsoft Windows SDK) con IRP_MJ_DEVICE_CONTROL. Il chiamante identifica la richiesta dal codice di controllo I/O che inserisce in Parameters.DeviceIoControl.IoControlCode nella struttura della posizione dello stack I/O.

Per supportare le richieste, il minidriver fornisce un puntatore a una struttura KSDISPATCH_TABLE in una chiamata a KsAllocateObjectHeader.

Le richieste di scrittura contengono un puntatore a una matrice di strutture KSSTREAM_HEADER che a sua volta contengono puntatori per trasmettere i dati. Le richieste di lettura contengono un puntatore a una matrice di strutture di intestazione vuote in cui devono essere restituiti i dati di lettura.