AddPortUI 函式 (winsplp.h)

發行項
03/01/2024

埠監視器 UI DLL 的 AddPortUI 函式會新增印表機埠，然後從使用者取得埠組態資訊，並將其傳送至埠監視器伺服器 DLL。

語法

BOOL AddPortUI(
  [in, optional]  PCWSTR pszServer,
  [in]            HWND   hWnd,
                  PCWSTR pszMonitorNameIn,
  [out, optional] PWSTR  *ppszPortNameOut
);

參數

[in, optional] pszServer

呼叫端提供的字串指標代表伺服器名稱，如果印表機為本機，則為 NULL 。

[in] hWnd

視窗的呼叫端提供句柄，該視窗應該用來做為對話框的父代。如果 為 NULL，則不應該顯示任何對話框。

pszMonitorNameIn

呼叫端提供的字串指標，代表監視器的名稱。可以是 NULL。

[out, optional] ppszPortNameOut

呼叫端提供的位置指標，以接收埠名稱字串。可以是 NULL，在此情況下不會傳回名稱。

傳回值

如果作業成功，函式應該會傳回 TRUE。否則應該呼叫 SetLastError 以指定錯誤碼，而且函式應該傳回 FALSE。如果使用者取消作業或不受支援，函式應該呼叫 SetLastError (ERROR_CANCELLED) ，然後傳回 FALSE。

備註

需要埠監視器 UI DLL 才能定義 AddPortUI 函式，並在 MONITORUI 結構中包含函式的位址。

多任務緩衝處理程式會從 AddPort 函式內呼叫 AddPortUI 。 AddPortUI 收到的前三個自變數是 AddPort 收到的自變數。 (AddPort 函式會在 Microsoft Windows SDK documentation.)

函式應該執行下列作業：

呼叫 OpenPrinter，以下列格式指定印表機名稱：

\\ServerName\，XcvMonitorMonitorName

其中 ServerName 和 MonitorName 是伺服器和監視名稱接收為 AddPortUI 函式自變數。

呼叫 OpenPrinter 需要PRINTER_DEFAULTS結構，如 Windows SDK 檔中所述。結構的 DesiredAccess 成員必須設定為 SERVER_ACCESS_ADMINISTER。其 pDatatype 和 pDevMode 成員可以是 NULL。

此呼叫會導致呼叫列印監視器伺服器 DLL 的 XcvOpenPort 函式。
藉由顯示對話框，從使用者取得埠名稱。
呼叫 XcvData，指定下列輸入自變數：
- 從 OpenPrinter 收到的句柄
- 從使用者收到的埠名稱
- 自定義數據名稱字串，例如 “PortExists”
此呼叫會導致呼叫伺服器 DLL 的 XcvDataPort 函式。 XcvDataPort 函式應該會傳回值，指出是否已使用指定的埠名稱。如果有，UI DLL 應該向使用者要求另一個名稱，然後再次呼叫 XcvData 。
收到有效的新埠名稱之後，請再次呼叫 XcvData ，這次指定下列輸入自變數
- 從 OpenPrinter 收到的句柄
- 從使用者收到的已驗證埠名稱
- “AddPort” 的數據名稱字串
此呼叫會再次呼叫伺服器 DLL 的 XcvDataPort 函式。
藉由顯示對話框，從使用者取得埠組態參數。
呼叫 XcvData 一或多次，指定自訂的數據名稱字串，以將每個組態參數傳送至伺服器 DLL。每個 XcvData 呼叫都會呼叫伺服器的 XcvDataPort 函式。
呼叫 ClosePrinter，指定從 OpenPrinter 收到的句柄。這會導致呼叫伺服器 DLL 的 XcvClosePort 函式。