啟用 3D 印表機的自訂 USB 介面

發行項
10/16/2024

本主題所述的架構可支援 v3 和 v4 列印生態系統中的自定義 USB 介面 3D 印表機。標準埠監視器 3dmon.dll會將 3D 列印作業命令轉送至使用本地服務認證執行的 Windows 3DPrintService 。服務會載入並與夥伴 DLL 通訊，以執行 3D 列印作業所需的自定義命令。裝置的 USB 驅動程式套件會安裝合作夥伴 DLL 以及 3dmon.dll 和 3dprintservice.exe 可轉散發套件。夥伴 DLL 必須實作並匯出一組函式，才能與 3DPrintService 通訊。 3dmon.dll中實作與列印後台處理程式服務互動所需的其餘功能。

注意

此架構需要夥伴 DLL 才能多實例安全線程。

架構決策

3DPrintService Windows 服務可用來在列印工作流程期間載入和叫用合作夥伴提供的 DLL 中的特定定義 API。這些 API 將允許與印表機通訊。

KMDF USB 篩選器驅動程式套件會在 Windows Update 上發布，以便透過 PnP 安裝支援的 3D 印表機。 KMDF 驅動程式會安裝合作夥伴軟體，並建立 3D 印表機裝置節點。 3D 印表機裝置節點是使用 Windows Update 中合作夥伴發佈的 v4 印表驅動程式來安裝。

封裝決策

二進位檔和二進位相依性

此架構會使用硬體製造商在 Windows Update 上發佈的驅動程式。此驅動程式包含下列Microsoft提供的可轉散發二進位檔及其相依性：

3dmon.dll
3dprintservice.exe
ms3dprintusb.sys

核心模式 USB 篩選器驅動程式

KMDF 驅動程式是由合作夥伴所發佈，由下圖所示的元件所組成。這會比對具有硬體標識碼的裝置（通常是 VID 和 PID）。驅動程式會在安裝時建立 3D 印表機裝置節點，以觸發列印佇列和交叉分析篩選器驅動程式的安裝。合作夥伴會為所建立的 3D 印表機裝置節點提供 v4 印表機驅動程式。

kmdf usb 篩選器驅動程式。

MS3DPrintUSB.sys

核心模式設備驅動器，會在 Enum\3DPrint 下建立 3D 印表機開發節點。 PnP 子系統會根據Winusb.sys所建立的裝置節點，透過直接比對 VID 和 PID 來叫用它。驅動程式 .inf 檔案會設定用來設定 3DPrintService 的自定義 DLL（如果尚未安裝在系統上）。

3dmon.dll

3DMon.dll是Microsoft發行的埠監視器可轉散發二進位檔，由多任務緩衝處理器叫用以與 3D 印表機通訊。

3dprintservice.exe

3DPrintService.exe是在驅動程式安裝期間，以 Windows 服務形式安裝Microsoft發行的二進位檔。 3DMon 會與這項服務通訊，以在 3D 印表機上執行列印、bidi 等作業。

Partnerimpl.dll

Partnerimp.dll是合作夥伴已發行Microsoft介面的實作。 DLL 會使用其通訊協定與合作夥伴的裝置通訊。 3DPrintService.exe運行時間載入此 DLL，以驅動 3D 印表機裝置的作業。

此圖顯示 3D 印表機裝置作業的裝置通訊流程。

印表機使用順序

多任務緩衝處理程式會與傳送命令至 3DPrintService Windows 服務的3dmon.dll通訊
3DPrintService.exe會使用 NetworkService 的帳戶認證執行
多任務緩衝處理器透過 3dmon.dll，在每次使用 3D 印表機時傳送命令至 3DPrintService
3DPrintService 會在合作夥伴提供的實作 DLL 上處理命令，並在運行時間叫用 API
3DPrintService 會將合作夥伴提供的 DLL 的回應交還給後台處理程式

介面和互動

夥伴 DLL 必須匯出下列 API 函式：

HRESULT Install（in] LPCWSTR args）

此 API 是選擇性的，可供製造商用來安裝其裝置的自定義軟體或註冊。例如，安裝隨附於裝置驅動程式套件的模型。此 API 會使用 SYSTEM 認證叫用，以啟用安裝。

DWORD PrintApiSupported（）

第三方製造商會使用此 API 來指出支援的 3D 列印服務 API 版本。下列 API 與 3DPrintService 第 1 版相容。

HRESULT InitializePrint（LPCWSTR pPrinterName， LPCWSTR pPortName， DWORD dwJobId， LPVOID* ppPartnerData）

這個 API 會在列印事件開始初始化印表機之前叫用。印表機可以在ppPartnerData 參數中儲存作業特定狀態。此呼叫類似於 StartDocPort 調用。

jobId - 用來追蹤作業的作業標識符
portName - 3D 印表機的 portname
printerName - 此列印作業要傳送至的印表機名稱
ppPartnerData - 指標指標，可用來儲存任何作業特定數據

HRESULT PrintFile（in] DWORD jobId， [in] LPWSTR portName， [in] LPWSTR printerName， [in] LPWSTR pathToRenderedFile，[in]LPVOID* ppPartnerData）

第三方製造商會使用此 API 在其印表機上列印檔。

jobId - 用來追蹤作業的作業標識符
portName - 3D 印表機的 portname
printerName - 要傳送列印作業的印表機名稱
pathToRenderedFile - 執行轉譯之後多任務緩衝處理檔案位置的 UNC 路徑。第三方製造商會處理此位置的檔案，並在其裝置上列印檔
ppPartnerData - 在 InitializePrint API 呼叫期間發出以儲存夥伴特定數據設定的指標指標。
printerName 可以使用埠名稱從登錄取得。第三方製造商可能無法使用埠名稱與其裝置通訊。印表機名稱在 Windows 電腦上是唯一的，其軟體將能夠識別要列印作業的印表機。您可以在下列登入機碼找到電腦上使用的所有印表機：

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Print\Printers

HRESULT Query（_In_ LPCWSTR 命令、_In_ LPCWSTR commandData、_Out_ LPWSTR resultBuffer、_Out_ resultBufferSize、、_In_ LPVOID* ppPartnerData）

command - 以查詢的形式傳送的字串命令
commandData - 命令自變數（選擇性）
resultBuffer - 叫用查詢自變數的結果>
resultBufferSize - 結果緩衝區字串的大小
ppPartnerData - 目前夥伴 DLL 實例指標的指標

3Dprint 服務會叫用夥伴 DLL，以取得為命令配置的緩衝區大小。

配置記憶體以保存回應字串之後，將會再次叫用 DLL 以取得實際結果。

DLL 可以使用先前 IntializePrint（） 呼叫中的實例數據來與裝置通訊，而不需要每次呼叫 Query（） 函式時開啟新的通道。

此 API 可用來與印表機通訊，以取得裝置設定、列印進度的相關信息，或通知合作夥伴 DLL 裝置拔除事件。

製造商必須支援下列命令：

Command	輸出	註解
\\Printer.3DPrint：JobStatus	作業開始 = {“Status”： “ok”}，完成時要使用的狀態 {“Status”： “Completed”}	多任務緩衝處理器會在列印佇列 UI 中顯示任何傳回的值。這可讓裝置在列印佇列 UI 上的列印期間顯示相關信息。裝置可以在這裡傳回任意字串（例如「忙碌」或「33%完成」），這會在列印佇列作業狀態中逐字顯示。
\\Printer.3DPrint：JobCancel	{“Status”： “Completed”}	當使用者取消列印時，多任務緩衝處理程式會叫用此命令。當取消成功且句柄和線程已關閉時，夥伴 DLL 會傳回此值。
\\Printer.Capabilities：Data	符合 PrintDeviceCapabilites （PDC）架構的 XML 字串。	PDC 查詢是由想要取得印表機詳細資訊的應用程式叫用。數據可用來描述裝置的功能，如果驅動程式依賴Microsoft交叉分析篩選器，則可以包含交叉分析篩選器設定。如需範例 PDC，請參閱下文。
\\Printer.3DPrint：Disconnect	{“Status”： “OK”}	每當印表機裝置有 PnP 中斷連線時，就會觸發此查詢。合作夥伴可以採取任何必要的動作，例如關閉任何開啟的句柄，以允許適當的重新連線。
\\Printer.3DPrint：Connect	{“Status”：“OK”}	每當印表機裝置有 PnP 連線時，就會觸發此查詢。合作夥伴可以採取任何必要的動作。

列印裝置功能 XML

下列列印裝置功能 XML 可作為範例：

<?xml version="1.0"?>
<PrintDeviceCapabilities
    xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
    xmlns:xsd="https://www.w3.org/2001/XMLSchema"
    xmlns:xml="https://www.w3.org/XML/1998/namespace"
    xmlns:psk="https://schemas.microsoft.com/windows/2003/08/printing/printschemakeywords"
    xmlns:psk3d="https://schemas.microsoft.com/3dmanufacturing/2013/01/pskeywords3d"
    xmlns:psk3dx="https://schemas.microsoft.com/3dmanufacturing/2014/11/pskeywords3dextended"
    xmlns:pskv="https://schemas.microsoft.com/3dmanufacturing/2014/11/pskeywordsvendor"
    xmlns:psf="https://schemas.microsoft.com/windows/2003/08/printing/printschemaframework"
    xmlns:psf2="https://schemas.microsoft.com/windows/2013/12/printing/printschemaframework2"
    xmlns="https://schemas.microsoft.com/windows/2013/12/printing/printschemaframework2"
    version="2">
    <CapabilitiesChangeID xsi:type="xsd:string">{9F58AF07-DCB6-4865-8CA3-A52EA5DCB05F}</CapabilitiesChangeID>

  <psk3d:Job3DOutputArea psf2:psftype="Property">
    <psk3d:Job3DOutputAreaWidth>150001</psk3d:Job3DOutputAreaWidth>
    <psk3d:Job3DOutputAreaDepth>150001</psk3d:Job3DOutputAreaDepth>
    <psk3d:Job3DOutputAreaHeight>150001</psk3d:Job3DOutputAreaHeight>
  </psk3d:Job3DOutputArea>

  <psk3d:Job3DMaterials psf2:psftype="Property">

      <psk3dx:MaterialPLA>
         <psk:DisplayName>PLA</psk:DisplayName>
         <psk3d:Job3DMaterialType>psk3d:PLA</psk3d:Job3DMaterialType>
         <psk3d:MaterialColor>#FFFFFFFF</psk3d:MaterialColor>

         <psk3dx:platformtemperature>0</psk3dx:platformtemperature>
         <psk3dx:filamentdiameter>1750</psk3dx:filamentdiameter>
         <psk3dx:filamentcalibrationoverride>1.0</psk3dx:filamentcalibrationoverride>
         <psk3dx:extrudertemperature>207</psk3dx:extrudertemperature>

         <psk3dx:SpeedFactor>1.0</psk3dx:SpeedFactor>

         <psk3dx:SetupCommands>
            <!-- Executed during pre-commands: nozzle pre-heating, priming, etc -->
            <psk3dx:command>M104 S207 T1</psk3dx:command>
            <psk3dx:command>M140 S50</psk3dx:command>
         </psk3dx:SetupCommands>

         <psk3dx:SelectCommands>
            <!-- Executed during printing: T0/T1 selection, nozzle wiping sequence,turn fan on/off/gradual, retract the material, temperature, etc-->
            <psk3dx:command>; PLA on</psk3dx:command>
            <psk3dx:command>M108 T1</psk3dx:command>
         </psk3dx:SelectCommands>

         <psk3dx:DeselectCommands>
            <!-- Executed during printing: retract the material, park the nozzle, reduce temperature, etc -->
            <psk3dx:command>; PLA off</psk3dx:command>
         </psk3dx:DeselectCommands>


      </psk3dx:MaterialPLA>
  </psk3d:Job3DMaterials>

  <psk3dx:customStatus>Slicing</psk3dx:customStatus>
  <psk3dx:userprompt>Confirm the 3D printer is calibrated and ready for the next print</psk3dx:userprompt>

   <!— Additional Slicer settings follow (optional) -->

</PrintDeviceCapabilities>

對於沒有面板顯示器和按鈕的 3D 印表機，可讓使用者在列印開始時與裝置互動，我們主張傳回 PDC xml 與適當的使用者提示訊息集，如 psdk3dx：userPrompt 所示。這是為了避免在現有列印之上開始新的列印。自訂狀態消息 <psk3dx：customStatus> 可用來在切割期間顯示任何訊息。

HRESULT 清理（LPCWSTR pPrinterName， LPCWSTR pPortName， DWORD dwJobId， LPVOID* ppPartnerData）

dwJobId - 用來追蹤多任務緩衝處理程式中作業的作業標識碼
pPortName - 3D 印表機的 portname
pPrinterName - 此列印作業要傳送至的印表機名稱
ppPartnerData - 指標，在 InitializePrint API 調用期間保留作業特定數據設定的指標

清除會在列印作業成功完成時叫用，或在列印作業上完成取消查詢時叫用。它提供合作夥伴 DLL 清除為此列印初始化的資源的機會。

HRESULT UnInstall（[in]LPCWSTR args）

卸載 3D 印表機裝置時會呼叫此 API，並提供一個機制讓製造商卸載可能已安裝的軟體。

共用方式為