DocumentProperties 函式

  • 發行項

DocumentProperties函式會擷取或修改印表機初始化資訊，或顯示指定印表機的印表機組態屬性工作表。

語法

LONG DocumentProperties(
  _In_  HWND     hWnd,
  _In_  HANDLE   hPrinter,
  _In_  LPTSTR   pDeviceName,
  _Out_ PDEVMODE pDevModeOutput,
  _In_  PDEVMODE pDevModeInput,
  _In_  DWORD    fMode
);

參數

hWnd [in]

印表機組態屬性工作表之父視窗的控制碼。

hPrinter [in]

印表機物件的控制碼。 使用 OpenPrinter 或 AddPrinter 函式來擷取印表機控制碼。

pDeviceName [in]

Null 終止字串的指標，指定顯示印表機組態屬性工作表之裝置的名稱。

pDevModeOutput [out]

DEVMODE結構的指標，可接收使用者指定的印表機組態資料。

pDevModeInput [in]

作業系統用來初始化屬性工作表控制項之 DEVMODE 結構的指標。

只有在fMode參數中設定DM_IN_BUFFER旗標時，才會使用此參數。 如果未設定 DM_IN_BUFFER ，作業系統會使用印表機的預設 DEVMODE。

fMode [in]

函式執行的作業。 如果此參數為零， DocumentProperties 函式會傳回印表機驅動程式 DEVMODE 資料結構所需的位元組數目。 否則，請使用下列一或多個常數來建構此參數的值;不過請注意，若要變更列印設定，應用程式必須至少指定一個輸入值和一個輸出值。

值 意義
DM_IN_BUFFER
 輸入值。 在提示、複製或更新之前，函式會將印表機驅動程式目前的列印設定與pDevModeInput參數所指定的DEVMODE結構中的設定合併。 函式只會針對 DEVMODE 結構的 dmFields 成員所指定的成員更新結構。 此值也會定義為 DM_MODIFY。 在合併期間發生衝突時，pDevModeInput所指定的DEVMODE結構中的設定會覆寫印表機驅動程式目前的列印設定。
DM_IN_PROMPT
 輸入值。 函式會呈現印表機驅動程式的 [列印設定] 屬性工作表，然後將印表機 DEVMODE 資料結構中的設定變更為使用者指定的值。 這個值也會定義為 DM_PROMPT。
DM_OUT_BUFFER
 輸出值。 函式會將印表機驅動程式目前的列印設定，包括私人資料寫入pDevModeOutput參數所指定的DEVMODE資料結構。 呼叫端必須配置足以包含資訊的緩衝區。 如果位 DM_OUT_BUFFER 集是清楚的， pDevModeOutput 參數可以是 Null。 此值也會定義為 DM_COPY。

傳回值

如果 fMode 參數為零，則傳回值是包含印表機驅動程式初始化資料所需的緩衝區大小。 請注意，如果印表機驅動程式將私人資料附加至 結構，此緩衝區可以大於 DEVMODE 結構。

如果函式顯示內容表，傳回值為 IDOK 或 IDCANCEL，視使用者選取的按鈕而定。

如果函式未顯示內容表且成功，則傳回值為 IDOK。

如果函式失敗，傳回值會小於零。

備註

注意

這是封鎖或同步函式，可能不會立即傳回。 此函式傳回的速度取決於執行時間因素，例如網路狀態、列印伺服器設定，以及撰寫應用程式時難以預測的印表機驅動程式實作因素。 從管理與使用者介面互動的執行緒呼叫此函式，可能會使應用程式看起來沒有回應。

pDeviceName參數指向的字串可以藉由呼叫GetPrinter 函式來取得。

印表機驅動程式實際使用的 DEVMODE 結構包含與裝置無關的元件 (，如上述所定義) ，後面接著每個驅動程式和驅動程式版本的大小和內容有所不同的驅動程式特定元件。 由於此驅動程式相依性，應用程式在為其配置緩衝區之前，先查詢驅動程式的正確 DEVMODE 結構大小非常重要。

若要變更應用程式本機的列印設定，應用程式應遵循下列步驟：

  1. 呼叫DocumentProperties並在fMode參數中指定零，以取得完整DEVMODE結構所需的位元組數目。
  2. 為完整的 DEVMODE 結構配置記憶體。
  3. 呼叫 DocumentProperties以取得目前的印表機設定。 將指標傳遞至步驟 2 中配置之 DEVMODE 結構的指標做為 pDevModeOutput 參數，並指定 DM_OUT_BUFFER 值。
  4. 修改傳回之 DEVMODE結構的適當成員，並藉由在DEVMODE的dmFields成員中設定對應的位來指出哪些成員已變更。
  5. 呼叫DocumentProperties並將修改過的DEVMODE結構傳回為pDevModeInput和pDevModeOutput參數，並同時指定使用 OR 運算子) 結合的DM_IN_BUFFER和DM_OUT_BUFFER (值。第三次呼叫DocumentProperties所傳回的DEVMODE結構，可以做為CreateDC函式呼叫中的引數。

若要使用目前的印表機設定建立印表機裝置內容的控制碼，您只需要呼叫 DocumentProperties 兩次，如上所述。 第一次呼叫會取得完整 DEVMODE 的大小，而第二個呼叫會使用目前的印表機設定來初始化 DEVMODE 。 將初始化的 DEVMODE 傳遞至 CreateDC ，以取得印表機裝置內容的控制碼。

規格需求

需求 值
最低支援的用戶端
 Windows 2000 Professional [僅限傳統型應用程式]
最低支援的伺服器
 Windows 2000 Server [僅限桌面應用程式]
標頭
Winspool.h (包含 Windows.h)
程式庫
Winspool.lib
DLL
Winspool.drv
Unicode 與 ANSI 名稱
 DocumentPropertiesW (Unicode) 和 DocumentPropertiesA (ANSI)

另請參閱

列印

列印多工緩衝處理器 API 函式

AdvancedDocumentProperties

CreateDC

DEVMODE

GetPrinter

OpenPrinter