Struttura KSPROPERTY

Articolo
06/15/2023

La struttura KSPROPERTY specifica una singola proprietà di streaming del kernel all'interno di un set di proprietà.

Le strutture KSEVENT, KSMETHOD e KSPROPERTY sono alias per la struttura KSIDENTIFIER . Di conseguenza, le loro definizioni sono identiche.

Sintassi

struct KSPROPERTY {
  GUID Set;
  ULONG Id;
  ULONG Flags;
};

Members

Set

Specifica un GUID che identifica un set di proprietà di streaming del kernel. Per altre informazioni sui GUID del set di proprietà, vedere la sezione Osservazioni di seguito.

Id

Specifica il membro del set di proprietà.

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.

Valore	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 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à durante la serializzazione 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.

Commenti

Le dimensioni del buffer di output passato determinano i dati restituiti da una richiesta di KSPROPERTY_TYPE_BASICSUPPORT. Se il buffer di output è la dimensione di un 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, le dimensioni incluse dell'intero valore dei valori, le informazioni sul tipo di valore della proprietà e il numero di elenchi di membri corrispondenti alla struttura.

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

KSPROPERTY_TYPE_SERIALIZESETe 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, il set di proprietà controlla quali proprietà devono essere serializzate.

Per le richieste di serializzazione, il membro SerializedSize della struttura di 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 eseguito una query (tutte le proprietà sconosciute iniziano con una struttura KSMULTIPLE_ITEM che può essere eseguita una query separatamente). Per eseguire una query sulle dimensioni totali di una serializzazione, il client passa un buffer di lunghezza zero nella chiamata a DeviceIoControl. ByteReturned restituisce quindi le dimensioni, in byte, che il buffer deve essere serializzare il set e uno stato di avviso di STATUS_BUFFER_OVERFLOW. Un buffer allocato che può quindi essere riempito con i dati serializzati.

Il formato del buffer di serializzazione è un KSPROPERTY_SERIALHDR, seguito dalle proprietà serializzate. Ogni proprietà che segue contiene un'intestazione (KSPROPERTY_SERIAL), seguita dai dati delle 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. Le dimensioni del buffer necessarie per la serializzazione possono anche essere sottoposte a query passando un buffer a lunghezza zero a una richiesta non elaborata di serializzazione. Poiché i gestori sono collegati agli elementi delle 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 offre diversi GUID del 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 e eventualmente altri file di intestazione.

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