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) |