XcvDataPort 函式 (winsplp.h)

發行項
02/27/2024

埠監視器伺服器 DLL 的 XcvDataPort 函式會接收來自埠監視器 UI DLL 的資訊，並將資訊傳回至該埠監視器的 UI DLL。

語法

DWORD XcvDataPort(
  _In_  HANDLE  hXcv,
  _In_  LPCWSTR pszDataName,
  _In_  PBYTE   pInputData,
        DWORD   cbInputData,
  _Out_ PBYTE   pOutputData,
        DWORD   cbOutputData,
  _Out_ PDWORD  pcbOutputNeeded
);

參數

[in] hXcv

呼叫端提供的印表機句柄，透過呼叫 OpenPrinter (取得，Microsoft Windows SDK 檔) 中所述。這個句柄是由 XcvOpenPort 函式建立和傳回。

[in] pszDataName

呼叫端提供的字串指標，代表所要求數據的名稱。如需詳細資訊，請參閱接下來的＜備註＞一節。

[in] pInputData

呼叫端提供的緩衝區指標，其中包含輸入數據。

cbInputData

呼叫端提供的大小，以位元組為單位，由 pInputData 指向的緩衝區。

[out] pOutputData

呼叫端提供的緩衝區指標，以接收輸出數據。

cbOutputData

呼叫端提供的大小，以位元組為單位，由 pOutputData 指向的緩衝區。

[out] pcbOutputNeeded

呼叫端提供的位置指標，以位元組為單位接收 pOutputData 所指向緩衝區所需的最小大小。

傳回值

如果作業成功，此函式應該會傳回ERROR_SUCCESS。否則，它應該會傳回ERROR_前置詞 Win32 錯誤碼。列印監視器 UI DLL 會在為 XcvData 指定的 pdwStatus 位置收到此值。

備註

需要埠監視器伺服器 DLL 才能定義 XcvDataPort 函式，以便接收資訊，並將資訊傳回埠監視器 UI DLL。函式的地址必須包含在 MONITOR2 結構中。

XcvDataPort 函式是由多任務緩衝處理器的 XcvData 函式所呼叫。 XcvDataPort 和 XcvData 的函式參數幾乎完全相同。 (XcvData 有額外的參數 pdwStatus，不存在 於 XcvDataPort.)

pszDataName 指向的字串會指定要執行的作業。函式必須辨識下列資料名稱字串：

數據名稱字串	作業
L“AddPort”	已傳送新增埠所需的所有資訊。函式應該執行新增指定埠所需的作業，包括在登錄的埠機碼下寫入埠名稱。 pInputData 參數會指向 NULL 終止的埠名稱字串。如果函式傳回ERROR_SUCCESS，多任務緩衝處理程式會將埠標示為已新增。此字串是由列印監視器 UI DLL 從其 AddPortUI 函式內指定。
L“DeletePort”	刪除埠所需的所有資訊都已傳送。函式應該執行刪除指定埠所需的作業，包括從登錄的 Ports 機碼移除埠名稱。 pInputData 參數會指向 NULL 終止的埠名稱字串。如果函式傳回ERROR_SUCCESS，多任務緩衝處理程式會將埠標示為已刪除。此字串是由列印監視器 UI DLL 從其 DeletePortUI 函式內指定。
L“MonitorUI”	函式應該使用 pOutputData 傳回相關聯埠監視器 UI DLL 的名稱。當應用程式呼叫 Microsoft Windows SDK addPort 函式時，列印後台處理程式會指定此字串。

函式通常會寫入，以辨識 UI DLL 在其 AddPortUI、ConfigurePortUI 和 DeletePortUI 函式內傳送的其他自定義字元串。這些字串可能代表從伺服器 DLL 要求目前組態值的命令，或提供新值的命令。例如， 您的 XcvDataPort 函式可能會辨識字串「GetTransmissionRetryTimeout」，您的 UI DLL 可以傳送至您的伺服器 DLL，以要求目前儲存的傳輸重試逾時值。或者，您可以定義一組必須在傳送「AddPort」或「DeletePort」之前傳送的字串，其中字串用來提供識別要新增或刪除之埠的資訊。

針對指定的 pszDataName 字串和輸入緩衝區， XcvDataPort 可能會先以 零的 cbOutputData 值呼叫。函式應該會傳回 ERROR_INSUFFICIENT_BUFFER的ERROR_INSUFFICIENT_BUFFER，以在ERROR_INSUFFICIENT_BUFFER中傳回所需的緩衝區大小。呼叫端可以使用 在 sqlOutputNeeded 中收到的值來配置適當大小的輸出緩衝區，然後再次呼叫 XcvDataPort ，這次指定 cbOutputData 中配置的緩衝區大小。

XcvDataPort 函式必須驗證所有輸入自變數。具體而言，函式必須：

驗證 pszDataName 參數指向的字串內容。如果此字串代表系統管理作業， (通常會新增、刪除或設定埠 ) ，XcvDataPort 函式應該會比較 XcvOpenPort 函式先前收到的授與存取遮罩與SERVER_ACCESS_ADMINISTER。如果比較失敗， XcvDataPort 必須傳回ERROR_ACCESS_DENIED。
驗證 pInputData 參數指向的緩衝區內容。當多任務緩衝處理程式呼叫 XcvOpenPort 函式時，它不會對此緩衝區的內容執行驗證。此監視器無法假設此數據的有效性，這可能來自惡意應用程式。

如果您要撰寫會與 TCPMON 通訊的埠監視器，請參閱 TCPMON Xcv 介面。