共用方式為

用於管道原則修改的 WinUSB 函式

  • 發行項

若要讓應用程式取得和設定端點管道的默認原則參數，Winusb.dll公開 WinUsb_GetPipePolicy 函式以擷取管道的默認原則。 WinUsb_SetPipePolicy函式可讓應用程式將原則參數設定為新的值。

WinUSB 可讓您將原則套用至端點管道，以修改其默認行為。 藉由使用這些原則，您可以設定 WinUSB 以最符合您的裝置與其功能。 下表提供 WinUSB 支援的管道原則清單。

注意

數據表中所述的原則僅適用於指定的端點。 在其他端點上設定原則不會影響 WinUSB 對讀取或寫入要求的行為。

原則編號 原則名稱 描述 端點（方向） 預設值
0x01 SHORT_PACKET_TERMINATE 針對寫入要求傳送長度為零的封包，其中緩衝區是端點所支援封包大小上限的倍數。 大量 （OUT）

插斷（OUT）		 FALSE
0x02 AUTO_CLEAR_STALL 自動清除停滯的管道，而不停止數據流。 大量 （IN）

插斷 （IN）		 FALSE
0x03 PIPE_TRANSFER_TIMEOUT 在取消要求之前，等候超時時間間隔，以毫秒為單位。 大量 （IN）

大量 （OUT）

插斷 （IN）

插斷（OUT）		 5 秒 （5000 毫秒） 用於控制;0 供其他人使用
0x04 IGNORE_SHORT_PACKETS 收到簡短封包或讀取特定位元組數目時，完成讀取要求。 如果檔案大小未知，要求會在短封包終止。 大量 （IN）

插斷 （IN）		 FALSE
0x05 ALLOW_PARTIAL_READS 允許從傳回比呼叫端要求更多數據的裝置讀取要求。 大量 （IN）

插斷 （IN）		 TRUE
0x06 AUTO_FLUSH 從讀取要求儲存多餘的數據，並將其新增至下一個讀取要求，或捨棄多餘的數據。 大量 （IN）

插斷 （IN）		 FALSE
0x07 RAW_IO 略過佇列和錯誤處理，以提高多個讀取要求的效能。 大量 （IN）

插斷 （IN）		 FALSE
0x08 MAXIMUM_TRANSFER_SIZE 取得 WinUSB 支援的 USB 傳輸大小上限。 這是可藉由呼叫 WinUsb_GetPipePolicy 來擷取的唯讀原則。 大量 （IN）

大量 （OUT）

插斷 （IN）

插斷（OUT）
0x09 RESET_PIPE_ON_RESUME 在接受新要求之前，從暫停繼續之後，重設端點的管道。 大量 （IN）

大量 （OUT）

插斷 （IN）

插斷（OUT）		 FALSE

下表識別如何使用每個管道原則的最佳做法，並描述啟用原則時所產生的行為。

原則 開啟 if... 行為
SHORT_PACKET_TERMINATE（0x01） 裝置需要以零長度封包終止 OUT 傳輸。 大部分的裝置都不需要此需求。 如果啟用 （原則參數值為 TRUE 或非零值），則每個寫入要求都是端點所支援封包大小上限的倍數，後面接著零長度的封包。

將數據傳送至主機控制器之後，WinUSB 會傳送長度為零的封包的寫入要求，然後完成WinUsb_WritePipe所建立的要求。
AUTO_CLEAR_STALL 您不希望失敗的傳輸讓端點處於停滯狀態。 只有在停用RAW_IO時，對端點有多個擱置的讀取要求時，此原則才有用。
  • 如果啟用 （原則參數值為 TRUE 或非零值），則會自動清除停滯條件。 此原則參數不會影響控制管道。

    當讀取要求失敗，主控制器傳回STATUS_CANCELLED或STATUS_DEVICE_NOT_CONNECTED以外的狀態時，WinUSB 會在完成失敗的要求之前重設管道。 重設管道會清除停止狀況，而不會中斷數據流。 只要新的傳輸持續從裝置抵達，數據就會繼續流入端點。 新的傳輸可以包含發生停滯時佇列中的傳輸。

    啟用此原則不會影響效能。

  • 如果停用 （原則參數值為 FALSE 或零），則所有在停止傳輸后抵達端點的傳輸都會失敗，直到呼叫者藉由呼叫 WinUsb_ResetPipe 手動重設端點的管道為止。
PIPE_TRANSFER_TIMEOUT 您預期會在特定時間內完成傳送至端點。
  • 如果設定為零（預設值），傳輸將不會逾時，因為主機控制器不會取消傳輸。 在此情況下，傳輸會無限期等候，直到手動取消或傳輸正常完成為止。
  • 如果設定為非零值（逾時間隔），主控制器會在收到傳輸要求時啟動定時器。 當定時器超過設定的超時時間間隔時，就會取消要求。

    由於定時器管理，效能會稍微降低。

    在 WinUSB 佇列中等候時，要求不會逾時。

    在 Windows Vista 中，針對所有傳輸（除了啟用RAW_IO的傳輸除外），WinUSB 會將要求排入佇列，直到目的地端點上所有先前的傳輸都完成為止。 主機控制器不會在超時時間間隔的計算中包含佇列時間。

    啟用RAW_IO后，WinUSB 不會將要求排入佇列。 相反地，它會將要求直接傳遞至USB堆疊，不論USB堆疊是否正忙於處理先前的傳輸。 如果 USB 堆疊忙碌中，可能會延遲處理新的要求。 這可能會導致逾時。
IGNORE_SHORT_PACKETS RAW_IO已停用，而且您不希望短封包完成讀取要求。
  • 如果啟用 （原則參數值為 TRUE 或非零值），主控制器在收到簡短封包之後，將不會立即完成讀取作業。 相反地，它只會在下列情況下完成作業：
    • 發生錯誤。
    • 要求已取消。
    • 已接收所有要求的位元組。
  • 如果停用 （原則參數值為 FALSE 或零），主控制器會在讀取要求的位元組數目或收到簡短封包之後完成讀取作業。
ALLOW_PARTIAL_READS 如果您的要求緩衝區大小是端點封包大小上限的倍數，裝置可以傳送比要求更多的數據。

如果您的應用程式想要讀取幾個位元組，以判斷要讀取的總位元組數，請使用 。
  • 如果停用 （原則參數值為 FALSE 或零），且裝置傳回的數據超過要求，WinUSB 會以錯誤完成要求。
  • 如果啟用 （原則參數值為 TRUE 或非零值），且裝置傳回的數據超過所要求的數據，WinUSB AUTO_FLUSH 可以從讀取要求新增多餘的數據到下一個讀取要求開頭，或捨棄多餘的數據。

    如果啟用，WinUSB 會立即順利完成零個字節的讀取要求，而且不會將要求傳送到堆棧。
AUTO_FLUSH 已啟用ALLOW_PARTIAL_READS原則。

裝置可以傳送比要求更多的數據，而且您的應用程式不需要任何其他數據。 如果您的要求緩衝區大小是端點封包大小上限的倍數，就可能發生這種情況。		 AUTO_FLUSH會在啟用 ALLOW_PARTIAL_READS 時定義 WinUSB 的行為。 如果停用ALLOW_PARTIAL_READS，WinUSB 會忽略AUTO_FLUSH值。

WinUSB 可以捨棄剩餘的數據，或使用呼叫端的下一個讀取要求傳送它。

  • 如果啟用 （原則參數值為 TRUE 或非零值），WinUSB 會捨棄額外的位元組，而不會有任何錯誤碼。
  • 如果停用 （policy 參數值為 FALSE 或零），WinUSB 會儲存額外的位元組、將它們新增至呼叫端下一個讀取要求的開頭，然後將數據傳送至下一個讀取作業中的呼叫端。
RAW_IO 效能是優先順序，應用程式會將同時讀取要求提交至相同的端點。

RAW_IO會對呼叫者在 WinUsb_ReadPipe 中傳遞的緩衝區施加特定限制：

  • 緩衝區長度必須是端點封包大小上限的倍數。
  • 長度必須小於或等於WinUsb_GetPipePolicy所擷取MAXIMUM_TRANSFER_SIZE的值。
 如果已啟用，則會傳輸略過佇列和錯誤處理，以提升多個讀取要求的效能。 WinUSB 會處理讀取要求，如下所示：

  • 不是端點封包大小上限倍數的要求失敗。
  • 大於 WinUSB 所支援傳輸大小上限的要求失敗。
  • 所有格式正確的要求都會立即傳送到USB核心堆疊，以排程在主機控制器中。


啟用此設定可大幅改善多個讀取要求的效能，方法是減少一個傳輸的最後一個封包與下一個傳輸的第一個封包之間的延遲。
RESET_PIPE_ON_RESUME 裝置不會在暫停時保留其數據切換狀態。 從暫停繼續時，WinUSB 會先重設端點，再讓呼叫端將新的要求傳送至端點。