KSPIN 結構 （ks.h）

KSPIN 結構描述具現化的針腳。

語法

typedef struct _KSPIN {
  const KSPIN_DESCRIPTOR_EX *Descriptor;
  KSOBJECT_BAG              Bag;
  PVOID                     Context;
  ULONG                     Id;
  KSPIN_COMMUNICATION       Communication;
  BOOLEAN                   ConnectionIsExternal;
  KSPIN_INTERFACE           ConnectionInterface;
  KSPIN_MEDIUM              ConnectionMedium;
  KSPRIORITY                ConnectionPriority;
  PKSDATAFORMAT             ConnectionFormat;
  PKSMULTIPLE_ITEM          AttributeList;
  ULONG                     StreamHeaderSize;
  KSPIN_DATAFLOW            DataFlow;
  KSSTATE                   DeviceState;
  KSRESET                   ResetState;
  KSSTATE                   ClientState;
} KSPIN, *PKSPIN;

成員

Descriptor

這個特定針腳的針腳描述元指標。 如需詳細資訊，請參閱 KSPIN_DESCRIPTOR_EX。

Bag

這個成員會指定這個特定針腳實例的 KSOBJECT_BAG （KSOBJECT_BAG 結構相當於 PVOID 類型）。 Object Bags 是用來將易失記憶體與特定 AVStream 物件產生關聯的結構。 釘選物件包中的任何項目都會在針腳關閉時自動清除。

Context

緩衝區的指標。 用戶端可以使用 Context，將內容資訊與特定釘選實例產生關聯。 這通常用於針腳/數據流延伸模組，並配置在針腳分派數據表中提供的建立分派中。 請注意，配置給內容資訊的任何動態記憶體，都應該使用 KsAddItemToObjectBag放在釘選實例的物件包中。 Context 初始化為建立釘選時父系 KSFILTER 之 Context 成員的值。 請參閱 AVStream 物件階層。

Id

這個成員會指定針腳類型標識碼。 這是指定篩選類型所提供之針腳描述元陣列的索引。

Communication

此成員會指定KSPIN_COMMUNICATION_NONE、KSPIN_COMMUNICATION_SINK、KSPIN_COMMUNICATION_SOURCE、KSPIN_COMMUNICATION_BOTH或KSPIN_COMMUNICATION_BRIDGE。 如需每個值的意義，請參閱 KSPROPERTY_PIN_COMMUNICATION。

ConnectionIsExternal

這個成員會指定布爾值，如果 TRUE，表示連接的針腳不支援 AVStream 連線交握。 如果 FALSE，表示連接的針腳支援AVStream連線交握。 這表示此針腳與其所連接的針腳之間的連線是否為兩個AVStream針腳之間的連線。

ConnectionInterface

這個成員包含 KSPIN_INTERFACE 結構，可識別用於連接的介面。 建立針腳時，圖表產生器會提供這項資訊。

ConnectionMedium

此成員包含 KSPIN_MEDIUM 結構，可識別此針腳應使用的連線媒體。 建立針腳時，圖表產生器會提供這項資訊。

ConnectionPriority

這個成員包含 KSPRIORITY 結構，指定連線的優先順序。 建立針腳時，圖表產生器會提供這項資訊。

ConnectionFormat

KSDATAFORMAT 結構的指標，指定連接的數據格式。 建立針腳時，圖形產生器一開始會提供這項資訊，而且可能透過屬性存取或格式變更插入數據流中的訊息來變更。 篩選控件 Mutex 會同步存取此成員。 用戶端不應變更此成員。

AttributeList

KSMULTIPLE_ITEM 結構的指標，指定在針腳建立期間提供的屬性清單，以描述連接。 指定這個針腳的數據流方向（KSPIN_DATAFLOW_IN或KSPIN_DATAFLOW_OUT）。 這項資訊是釘選的靜態屬性，並出現在針腳描述元中。 這裡快取以供在 IRQL 存取PASSIVE_LEVEL。

StreamHeaderSize

這個成員會指出這個針腳每個 KSSTREAM_HEADER 結構的大小，以位元組為單位。 通常用於輸出針腳，用戶端可以將此值設定為大於 sizeof （KSSTREAM_HEADER） 且已配置的擴充數據流標頭 （每個數據流標頭將會 StreamHeaderSize 個字節長）。 如果客戶端未設定此成員，這表示數據流標頭後面沒有延伸資訊。 在這種情況下，每個資料流標頭會精確 大小 （KSSTREAM_HEADER）。 用戶端可以在針腳建立分派中設定此設定。

DataFlow

這個成員會指定針腳的數據流方向。 可能的設定是 KSPIN_DATAFLOW_IN 和KSPIN_DATAFLOW_OUT。 此資訊是針腳的靜態屬性，並出現在相關的 KSPIN_DESCRIPTOR 結構中。 這裡快取以供在 IRQL 存取PASSIVE_LEVEL。

DeviceState

此成員包含類型為 KSSTATE 的列舉，可識別針腳被告知要轉換的狀態。 不一定與管道的狀態相同，它會透過 AVStrMiniPinSetDeviceState回報。 一開始KSSTATE_STOP，當AVStream收到連線狀態屬性集IOCTL時，就會變更此成員。 存取會使用 篩選控件 mutex進行同步處理。 Minidrivers 不應該變更此成員。 請參閱下方一節中的附註。 另請參閱 ClientState 成員。

ResetState

此成員包含 KSRESET 類型的列舉，可識別針腳的目前重設狀態。 可能的設定是KSRESET_BEGIN和KSRESET_END。 此成員一開始會設定為 KSRESET_END，並透過屬性存取變更。 篩選控件 mutex會同步存取這個成員。 用戶端不應該變更此成員。

ClientState

此成員會指定目前設定針腳 KSSTATE。 在呼叫AVStrMiniPinSetDeviceState 之前立即更新。 如果此回呼例程失敗，AVStream 會將 ClientState 復原至其先前的值。 失敗狀態轉換且在處理期間檢查此成員的迷你驅動程式應該注意此事件序列。

言論

在許多方面，針腳是篩選行為的焦點。 這反映在針腳結構具有大量成員的事實中。 許多迷你驅動程式需要精簡釘選行為，並維護其他與針腳相關聯的內容。 對於具有相當傳統針腳行為的篩選，不需要額外的精簡或內容。 在許多情況下，預設針腳行為就已足夠;針腳是使用 Filter-Centric Processing來存取。

為了進行同步處理，此物件的存留期是從呼叫minidriver的 PreCreate 分派函式開始的間隔，並在迷你驅動程式的 Close 分派函式傳回時結束，假設函式不會傳回STATUS_PENDING。 如果它確實傳回STATUS_PENDING，當用戶端藉由呼叫 KsCompletePendingRequest指出關閉要求完成時，物件的存留期就會結束。

如果迷你驅動程式需要判斷它是否被告知要移至特定 KSSTATE，請將 KSPIN DeviceState 成員的值與該狀態相比較不是可靠的方法。 請改為查看 ClientState 成員，或在 SetDeviceState 回呼中建立變數，然後檢查此變數。 SetDeviceState 是 KSPIN_DISPATCH的成員。

請參閱 物件包。

要求

另請參閱

KSPIN_DESCRIPTOR

KSPIN_DESCRIPTOR_EX

KSPIN_DISPATCH

KsAddItemToObjectBag

KsCompletePendingRequest