OpenPrinter 函式

OpenPrinter 函式會擷取指定印表機或列印伺服器或列印子系統中其他類型的控點的控制碼。

語法

BOOL OpenPrinter(
  _In_  LPTSTR             pPrinterName,
  _Out_ LPHANDLE           phPrinter,
  _In_  LPPRINTER_DEFAULTS pDefault
);

參數

pPrinterName [in]

指定印表機或列印伺服器名稱、印表機物件、XcvMonitor 或 XcvPort 之 Null 終止字串的指標。

針對印表機物件，請使用：PrinterName、Job xxxx。 若為 XcvMonitor，請使用：ServerName、XcvMonitor MonitorName。 若為 XcvPort，請使用：ServerName、XcvPort PortName。

如果 為 Null，表示本機印表機伺服器。

phPrinter [out]

接收控制碼 (不是安全線程的變數指標，) 開啟的印表機或列印伺服器物件。

phPrinter參數可以傳回 Xcv 控制碼，以便與 XcvData 函式搭配使用。 如需 XcvData 的詳細資訊，請參閱 DDK。

pDefault [in]

PRINTER_DEFAULTS結構的指標。 此值可以是 Null。

傳回值

如果函式成功，則傳回值是非零值。

如果此函式失敗，則傳回值為零。

備註

請勿在 DllMain中呼叫這個方法。

注意

針對遠端印表機呼叫 OpenPrinter 以取得遠端印表機的控制碼，會透過列印多工緩衝處理器服務的本機快取來存取印表機。 此快取無法即時精確。 若要取得精確的資料，請將 OpenPrinter 呼叫取代為 OpenPrinter2 ，並將 pOptions.dwFlags 設定為 PRINTER_OPTION_NO_CACHE。 請注意，只有 OpenPrinter2W 可正常運作。 函式會傳回使用其他列印 API 呼叫的印表機控制碼，並略過本機快取。 此方法會在等候遠端印表機的網路通訊時封鎖，因此可能不會立即傳回。 此函式傳回的速度取決於執行時間因素，例如網路狀態、列印伺服器設定，以及撰寫應用程式時難以預測的印表機驅動程式實作因素。 從管理使用者介面互動的執行緒呼叫此函式，可能會使應用程式沒有回應。

注意

針對遠端印表機呼叫 OpenPrinter 取得的控制碼，將會透過列印多工緩衝處理器服務中的本機快取來存取印表機。 此快取的設計並不精確。 如果您需要取得精確的資料，請將OpenPrinter 呼叫取代為 OpenPrinter2，並將pOptions.dwFlags設定為PRINTER_OPTION_NO_CACHE。 請注意，只有 OpenPrinter2W 可正常運作。 如此一來，函式會傳回印表機控制碼，讓其他列印 API 呼叫略過本機快取。 請注意，此方法會在等候往返網路通訊至遠端印表機時封鎖，因此可能不會立即傳回。 此函式傳回的速度取決於執行時間因素，例如網路狀態、列印伺服器組態，以及印表機驅動程式實作 - 撰寫應用程式時難以預測的因素。 因此，從管理與使用者介面互動的執行緒呼叫此函式，可能會使應用程式看起來沒有回應。

phPrinter指向的控制碼不是安全線程。 如果呼叫端需要在多個執行緒上同時使用它，則必須使用 同步處理函式提供印表機控制碼的自訂同步處理存取權。 若要避免撰寫自訂程式碼，應用程式可以視需要在每一個執行緒上開啟印表機控制碼。

pDefault參數可讓您指定用於列印StartDocPrinter 函式所提交檔的資料類型和裝置模式值。 不過，您可以在檔啟動之後使用 SetJob 函式覆寫這些值。

當StartDocPrinter呼叫之pDocInfo參數中傳遞DOC_INFO_1之pDatatype成員的值為 「RAW」 時，不會使用pDefault參數PRINTER_DEFAULTS中定義的DEVMODE設定。 當高階檔 (例如 Adobe PDF 或 Microsoft Word檔案) 或其他印表機資料 (這類 PCL、PS 或 HPGL) 直接傳送至pDatatype設定為 「RAW」 的印表機時，檔必須完整描述硬體所瞭解語言的DEVMODE樣式列印工作設定。

您可以呼叫 OpenPrinter 函 式來開啟列印伺服器的控制碼，或判斷用戶端對列印伺服器具有的存取權限。 若要這樣做，請在pPrinterName參數中指定列印伺服器的名稱、將PRINTER_DEFAULTS結構的pDatatype和pDevMode成員設定為Null，並將DesiredAccess成員設定為指定伺服器存取遮罩值，例如 SERVER_ALL_ACCESS。 當您完成控制碼時，請將它傳遞給 ClosePrinter 函 式以關閉它。

使用PRINTER_DEFAULTS結構的DesiredAccess成員來指定印表機所需的存取權限。 存取權限可以是下列其中一項。 (如果 pDefault 為 Null，則存取權限會PRINTER_ACCESS_USE.)

Desired Access 值	意義
PRINTER_ACCESS_ADMINISTER	若要執行系統管理工作，例如 SetPrinter所提供的工作。
PRINTER_ACCESS_USE	若要執行基本列印工作。
PRINTER_ALL_ACCESS	若要執行 SYNCHRONIZE (以外的所有系統管理工作和基本列印工作，請參閱 標準存取權限。
PRINTER_ACCESS_MANAGE_LIMITED	若要執行系統管理工作，例如 SetPrinter 和 SetPrinterData所提供的工作。 此值可從 Windows 8.1 開始取得。
泛型安全性值，例如 WRITE_DAC	允許特定控制存取權限。 請參閱 標準存取權限。

如果使用者沒有許可權開啟具有所需存取權的指定印表機或列印伺服器， OpenPrinter 呼叫將會失敗，傳回值為零，而 GetLastError 會傳回值ERROR_ACCESS_DENIED。

範例

如需使用此函式的範例程式，請參閱 How To： Print Using the GDI Print API。

規格需求

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

另請參閱

列印

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

WritePrinter

ClosePrinter

PRINTER_DEFAULTS

SetJob

SetPrinter

StartDocPrinter