Struttura KSIDENTIFIER (ks.h)

La struttura KSIDENTIFIER specifica un GUID che identifica in modo univoco un set correlato di GUID e un valore di indice da fare riferimento a un membro specifico all'interno di tale set.

KSDEGRADE, KSEVENT, KSMETHOD, KSPIN_INTERFACE, KSPIN_MEDIUM e KSPROPERTY typedef sono alias per la struttura KSIDENTIFIER. Di conseguenza, le loro definizioni sono identiche. Per specifiche sull'utilizzo, vedere gli argomenti typedef individuali.

Sintassi

typedef struct {
  union {
    struct {
      GUID  Set;
      ULONG Id;
      ULONG Flags;
    } _IDENTIFIER;
    struct {
      GUID  Set;
      ULONG Id;
      ULONG Flags;
    };
    LONGLONG Alignment;
  };
} KSIDENTIFIER, *PKSIDENTIFIER;

Members

_IDENTIFIER

Vedere la sezione Note riportata di seguito.

_IDENTIFIER.Set

Vedere la sezione Note riportata di seguito.

_IDENTIFIER.Id

Vedere la sezione Note riportata di seguito.

_IDENTIFIER.Flags

Vedere la sezione Note riportata di seguito.

Set

Vedere la sezione Note riportata di seguito.

Id

Vedere la sezione Note riportata di seguito.

Flags

Vedere la sezione Note riportata di seguito.

Alignment

Vedere la sezione Note riportata di seguito.

Commenti

Descrizioni dei membri KSIDENTIFIER

Set

Specifica un GUID che identifica una proprietà di streaming del kernel, un evento, un metodo, un set di bus di comunicazione. La struttura KSPIN_INTERFACE descrive un'interfaccia specifica all'interno di un set di interfacce. La struttura KSDEGRADE contiene specifiche strategie di riduzione. Per altre informazioni, vedere la sezione Osservazioni di seguito.

Id

Specifica il membro della proprietà, dell'evento, del set di metodi. Per KSPIN_MEDIUM, identifica una connessione univoca sul bus. Per KSPIN_INTERFACE, specifica il numero ID di questa particolare interfaccia all'interno del set di interfacce. Per KSDEGRADE, specifica l'identificatore specifico del set per un elemento all'interno del set.

Flags

Specifica il tipo di richiesta. Se si scrive un minidriver di classe di flusso, vedere anche KSPROPERTY_ITEM per informazioni sul flag specifiche della classe. I flag devono essere uno dei valori elencati nella tabella seguente. Alcuni flag possono essere combinati usando un'operazione OR bit per bit.

Per specifiche sull'utilizzo, vedere gli argomenti KSDEGRADE, KSEVENT,KSMETHOD, KSPIN_INTERFACE, KSPIN_MEDIUM e KSPROPERTY typedef.

Specifica il tipo di richiesta KSPROPERTY .

Valore del flag KSPROPERTY	Descrizione
KSPROPERTY_TYPE_GET	Recupera il valore dell'elemento della proprietà specificata.
KSPROPERTY_TYPE_SET	Imposta il valore dell'elemento della proprietà specificata.
KSPROPERTY_TYPE_SETSUPPORT	Esegue query se il driver supporta questo set di proprietà.
KSPROPERTY_TYPE_BASICSUPPORT	Esegue una query sui tipi di richiesta gestiti dal driver per questo elemento della proprietà. Restituisce KSPROPERTY_TYPE_GET o KSPROPERTY_TYPE_SET o entrambi. Tutti i set di proprietà devono supportare questo flag.
KSPROPERTY_TYPE_DEFAULTVALUES	Esegue una query sui valori predefiniti per l'elemento di proprietà specificato. Restituisce una struttura di tipo KSPROPERTY_VALUES.
KSPROPERTY_TYPE_RELATIONS	Esegue query su tutte le proprietà con dipendenze sull'impostazione corrente di questa proprietà. Specifica che l'elenco delle relazioni delle proprietà deve essere restituito o la quantità di spazio buffer richiesto da tale elenco se il buffer restituito è la dimensione di un ULONG. Ogni elemento si trova su FILE_QUAD_ALIGNMENT, preceduto da una struttura KSMULTIPLE_ITEM. Questa operazione non è valida quando si esegue una query sul supporto della proprietà impostata in generale. Tutti i set di proprietà devono supportare questo flag.
KSPROPERTY_TYPE_SERIALIZESET	Serializzare il set di proprietà usando le strutture di KSPROPERTY_SERIALHDR standard e di KSPROPERTY_SERIAL.
KSPROPERTY_TYPE_UNSERIALIZESET	Annullare il set di proprietà usando le strutture standard KSPROPERTY_SERIALHDR e KSPROPERTY_SERIAL .
KSPROPERTY_TYPE_SERIALIZESIZE	Restituisce un oggetto ULONG che specifica le dimensioni dei dati delle proprietà quando viene serializzato come parte di una richiesta di KSPROPERTY_TYPE_SERIALIZESET. Una dimensione pari a zero indica che non è necessario serializzare una proprietà.
KSPROPERTY_TYPE_SERIALIZERAW	Specifica che le proprietà di questo set devono essere serializzate dal gestore del supporto del set di proprietà, se presente. In caso contrario, la chiamata ha esito negativo. Il formato di serializzazione è privato. Questa operazione deve essere inversa di KSPROPERTY_TYPE_UNSERIALIZERAW.
KSPROPERTY_TYPE_TOPOLOGY	La proprietà passata è di tipo KSP_NODE, dove NodeId indica l'ID numerico del nodo della topologia. Non impostare questo flag da solo; invece, OR con altri flag in questa tabella.
KSPROPERTY_TYPE_UNSERIALIZERAW	Specifica che il buffer fornito contiene un gruppo di proprietà che appartengono a questo set che deve essere annullato dal gestore del supporto del set di proprietà, se presente. In caso contrario, la chiamata ha esito negativo. Il formato di serializzazione è privato. Questa operazione deve essere inversa di KSPROPERTY_TYPE_SERIALIZERAW.

Specifica il tipo di richiesta KSEVENT . Questo flag deve essere uno dei valori elencati nella tabella seguente.

Valore del flag KSEVENT	Descrizione
KSEVENT_TYPE_ENABLE	Abilita la notifica degli eventi per questo tipo di evento. Il driver continua la notifica degli eventi fino a quando il client lo disabilita in modo esplicito.
KSEVENT_TYPE_ONESHOT	Abilita la notifica degli eventi solo per l'occorrenza successiva di questo evento. Il client non deve (e non deve) disabilitare l'evento dopo che si è verificato.
KSEVENT_TYPE_SETSUPPORT	Query per l'elenco di set di eventi o per il supporto di un determinato set di eventi.
KSEVENT_TYPE_BASICSUPPORT	Query per il supporto di un determinato tipo di evento.
KSEVENT_TYPE_ENABLEBUFFERED	Invece di inviare una notifica al client, le notifiche degli eventi della coda del driver. Il client invia quindi una seconda richiesta di IOCTL_KS_ENABLE_EVENT con il KSEVENT_TYPE_QUERYBUFFER per ricevere le notifiche degli eventi in coda.
KSEVENT_TYPE_TOPOLOGY	Indica che l'evento passato è di tipo KSE_NODE, dove NodeId indica l'ID numerico del nodo della topologia. Non impostare questo flag da solo; invece, OR con altri flag da questo elenco.
KSEVENT_TYPE_QUERYBUFFER	Recupera la notifica dell'evento buffer successiva.

Specifica il tipo di richiesta KSMETHOD . Vedere anche i flag di KSMETHOD_TYPE_Xxx per KSMETHOD_ITEM. Una richiesta può contenere una combinazione dei valori elencati nella tabella seguente.

Valore del flag KSMETHOD	Descrizione
KSMETHOD_TYPE_BASICSUPPORT	Indica di eseguire una query sul minidriver per determinare se supporta il metodo specificato del set di metodi.
KSMETHOD_TYPE_SEND	Indica che il minidriver deve eseguire il metodo specificato. L'effetto del metodo sui parametri specificati deve essere noto al client, ovvero se i parametri vengono letti, scritti in, entrambi o nessuno dei due. Il minidriver usa la struttura KSMETHOD_ITEM per specificare l'effetto del metodo sui parametri.
KSMETHOD_TYPE_SETSUPPORT	Indica di eseguire una query sul minidriver per determinare se supporta il set di metodi specificato.
KSMETHOD_TYPE_TOPOLOGY	Indica che il metodo specificato è di tipo KSM_NODE, dove il membro NodeId è l'identificatore del nodo della topologia. Non impostare questo flag autonomamente; in alternativa, OPPURE con altri flag da questo elenco.

Per KSDEGRADE, specifica la percentuale corrente di riduzione della riduzione, espressa in parti per migliaia (dove un valore pari a 1000 non rappresenta alcuna riduzione) oppure specifica la quantità di tempo in unità native, come specificato dall'interfaccia.

Alignment

Non usato. Membro di un'unione senza nome utilizzata per forzare l'allineamento corretto sulla struttura senza nome.

Note

Per informazioni specifiche sull'utilizzo, vedere gli argomenti KSDEGRADE, KSEVENT, KSMETHOD, KSPIN_INTERFACE, KSPIN_MEDIUM e KSPROPERTY typedef.

L'uso di un ID all'interno del set consente di eseguire un singolo confronto di grandi dimensioni per un identificatore di set, quindi confronti rapidi più piccoli,ad esempio usando un'istruzione switch per gli identificatori all'interno di un set. Ad esempio, un set di proprietà viene indicato da un identificatore GUID univoco e le proprietà all'interno di tale set vengono definite dall'ID breve.

Il metodo, l'evento, l'interfaccia e i set medi possono essere considerati come "classi" di set.

Le dimensioni del buffer di output passato determinano quali dati vengono restituiti da una richiesta di KSPROPERTY_TYPE_BASICSUPPORT. Se il buffer di output è la dimensione di una ULONG, vengono restituiti solo i flag di accesso. Se il buffer di output è la dimensione della struttura KSPROPERTY_DESCRIPTION , la struttura viene riempita con i flag di accesso, la dimensione inclusiva dell'intera informazione sui valori, le informazioni sul tipo di valore della proprietà e il numero di elenchi di membri che corrispondono alla struttura.

Per una richiesta di KSPROPERTY_TYPE_RELATIONS, i dati restituiti dipendono anche dalle dimensioni del buffer di output. Se le dimensioni del buffer di output sono pari a zero, le dimensioni necessarie per restituire le proprietà correlate vengono restituite in BytesReturned con stato di avviso di STATUS_BUFFER_OVERFLOW. Se il buffer è la dimensione di una struttura KSMULTIPLE_ITEM , vengono restituite sia le dimensioni dei byte che il conteggio delle relazioni. In caso contrario, il buffer dovrebbe essere sufficientemente lungo da restituire la struttura KSMULTIPLE_ITEM e tutti gli identificatori di proprietà correlati, che vengono restituiti come elenco di strutture KSIDENTIFIER .

KSPROPERTY_TYPE_SERIALIZESET e KSPROPERTY_TYPE_UNSERIALIZESET richieste consentono l'interazione con più proprietà con una singola chiamata dal client. Se il gestore di streaming del kernel viene usato per elaborare le richieste di proprietà, queste vengono suddivise in più chiamate dalla funzione KsPropertyHandler . Quando si usa questo gestore, la definizione del set di proprietà controlla quali proprietà devono essere serializzate.

Per le richieste di serializzazione, il membro SerializedSize della struttura KSPROPERTY_ITEM pertinente viene controllato per un valore diverso da zero che indica le dimensioni, in byte, della proprietà . Se il valore del membro SerializedSize è 1, è sconosciuto e deve essere sottoposto a query (tutte le proprietà sconosciute iniziano con una struttura KSMULTIPLE_ITEM su cui è possibile eseguire query separatamente). Per eseguire una query sulle dimensioni totali di una serializzazione, il client passa un buffer di lunghezza zero nella chiamata a DeviceIoControl. BytesReturned restituisce quindi le dimensioni, in byte, che il buffer deve essere per serializzare il set e uno stato di avviso di STATUS_BUFFER_OVERFLOW. Un buffer allocato che le dimensioni possono quindi essere riempite con i dati serializzati.

Il formato del buffer di serializzazione è un KSPROPERTY_SERIALHDR, seguito da proprietà serializzate. Ogni proprietà che segue contiene un'intestazione (KSPROPERTY_SERIAL), seguita dai dati della proprietà, con l'inizio di ogni proprietà in FILE_LONG_ALIGNMENT. Si noti che la struttura dell'intestazione seriale è definita in FILE_LONG_ALIGNMENT.

KSPROPERTY_TYPE_SERIALIZERAW e KSPROPERTY_TYPE_UNSERIALIZERAW sono supportati se esiste un gestore di elementi di proprietà. La funzione KsPropertyHandler richiama il gestore fornito dal minidriver. È anche possibile eseguire query sulle dimensioni del buffer necessarie per la serializzazione passando un buffer di lunghezza zero a una richiesta non elaborata di serializzazione. Poiché i gestori sono associati agli elementi della proprietà anziché al set di proprietà, è necessario specificare un elemento specifico all'interno del set di proprietà nel parametro Property . Questo gestore può gestire più proprietà all'interno del set.

Microsoft fornisce diversi GUID dei set di proprietà definiti dal sistema. I minidriver specificano uno di questi GUID nel membro Set . I set di proprietà di streaming del kernel iniziano in genere con un prefisso KSPROPSETID o PROPSETID . I set di proprietà di streaming del kernel sono definiti in ks.h, ksmedia.h, bdamedia.h ed eventualmente altri file di intestazione.

Per altre informazioni sulle proprietà di streaming del kernel, vedere Proprietà, eventi e metodi KS.

Microsoft fornisce diversi GUID del set di eventi definiti dal sistema. I minidriver specificano uno di questi GUID nel membro Set . I set di eventi di streaming del kernel iniziano in genere con un prefisso KSEVENTSETID . I set di eventi di streaming del kernel sono definiti in ks.h, ksmedia.h, bdamedia.h ed eventualmente altri file di intestazione.

Per altre informazioni sugli eventi di streaming del kernel, vedere Proprietà, eventi e metodi KS.

Microsoft fornisce diversi GUID del set di metodi definiti dal sistema. I minidriver specificano uno di questi GUID nel membro Set . I set di metodi di streaming del kernel iniziano in genere con un prefisso KSMETHODSETID . I set di metodi di streaming del kernel sono definiti in ks.h, ksmedia.h, bdamedia.h ed eventualmente altri file di intestazione.

Per altre informazioni sui metodi di streaming del kernel, vedere Proprietà, eventi e metodi KS.

Un client può usare la richiesta di IOCTL_KS_METHOD insieme alla struttura KSMETHOD per eseguire metodi su un oggetto di streaming del kernel gestito dal minidriver. Per altre informazioni, vedere Metodi KS.

La struttura KSPIN_MEDIUM identifica un supporto, con un GUID medio univoco e un identificatore di istanza, che viene generato in modo specifico del bus. Esiste un valore di identificatore riservato KSMEDIUM_TYPE_ANYINSTANCE che viene usato quando le istanze del bus non sono problematiche. Ad esempio, il KSMEDIUMSETID_Standard fa riferimento al bus di sistema, di cui deve essere presente solo uno. Pertanto, questo identificatore di istanza viene sempre usato come comodità.

Un pin può supportare più supporti e interfacce su tali supporti. Il modo in cui viene descritto un pin implica che l'elenco di interfacce è supportato in tutti i supporti enumerati per un pin. In caso contrario, è possibile usare un altro pin per descrivere ogni subset di interfacce per i supporti specifici.

Il supporto viene memorizzato nella cache anche dal flusso del kernel per velocizzare la ricerca di una possibile connessione.

Un esempio di utilizzo di questa struttura è disponibile in un esempio di tuner, in cui KSPIN_MEDIUM rappresenta connessioni univoche tra tuner, barre incrociate e altri componenti del tuner.

Il membro Flags può contenere valori diversi in base al tipo di riduzione del segnale usano il client. Vedere Gestione della qualità. per maggiori dettagli sulle diverse strategie per risolvere i problemi di gestione della qualità riducendo la qualità del segnale.

Poiché Flag contiene un valore ULONG, potrebbero essere necessarie più richieste skip per risolvere il problema di gestione della qualità.

Requisiti

Requisito	Valore
Intestazione	ks.h (include Ks.h)

Vedi anche

KSDEGRADE

KSEVENT

KSMETHOD

KSPIN_INTERFACE

KSPIN_MEDIUM

KSPROPERTY