OpenPrinter2 函式

擷取指定印表機、列印伺服器或列印子系統中其他類型的控點，同時設定某些印表機選項。

語法

BOOL OpenPrinter2(
  _In_  LPCTSTR            pPrinterName,
  _Out_ LPHANDLE           phPrinter,
  _In_  LPPRINTER_DEFAULTS pDefault,
  _In_  PPRINTER_OPTIONS   pOptions
);

參數

pPrinterName [in]

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

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

Windows Vista： 如果 為 Null，表示本機列印伺服器。

phPrinter [out]

接收開啟之印表機或列印伺服器物件的控制碼之變數的指標。

pDefault [in]

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

pOptions [in]

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

傳回值

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

如果此函式失敗，則傳回值為零。 如需擴充的錯誤資訊，請呼叫 GetLastError。

備註

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

注意

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

未實作此函式的 ANSI 版本，並傳回ERROR_NOT_SUPPORTED。

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

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

使用PRINTER_DEFAULTS結構的DesiredAccess成員來指定必要的存取權限。 存取權限可以是下列其中一項。

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

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

當pPrinterName是本機印表機時，OpenPrinter2會忽略PRINTER_OPTIONS結構使用pOptions指向的所有dwFlags值，但PRINTER_OPTION_CLIENT_CHANGE除外。 如果傳遞後者， 則 OpenPrinter2 會傳回ERROR_ACCESS_DENIED。 因此，在開啟本機印表機時， OpenPrinter2 不會提供 比 OpenPrinter的優點。

Windows Vista：除非在pOptions所參考PRINTER_OPTIONS結構的dwFlags欄位中設定PRINTER_OPTION_NO_CACHE旗標，否則OpenPrinter2所傳回的印表機資料會從本機快取擷取。

範例

在此範例中，PRINTER_ACCESS_MANAGE_LIMITED傳遞至PRINTER_DEFAULTS結構時，OpenPrinter2會失敗，而且使用者沒有適當的許可權。

// Specify the limited management permission.
PRINTER_DEFAULTS defaults = {};
defaults.DesiredAccess = PRINTER_ACCESS_MANAGE_LIMITED;

// Open a printer to which the user has no administrative rights.
HANDLE printer = nullptr;
assert(!OpenPrinter2(L QueueWithNoAdminRights , // Queue name
                     &printer,                  // Printer handle
                     &defaults,                 // Printer defaults
                     nullptr));                 // Printer options

assert(GetLastError() == ERROR_ACCESS_DENIED);

if (printer)
{
    ClosePrinter(printer);
}

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

規格需求

需求	值
最低支援的用戶端	Windows Vista [僅限傳統型應用程式]
最低支援的伺服器	Windows Server 2008 [僅限傳統型應用程式]
標頭	Winspool.h (包含 Windows.h)
程式庫	Winspool.lib
DLL	Spoolss.dll
Unicode 與 ANSI 名稱	OpenPrinter2W (Unicode) 和 OpenPrinter2A (ANSI)

另請參閱

列印

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

ClosePrinter

PRINTER_DEFAULTS

PRINTER_OPTIONS

SetJob

SetPrinter

StartDocPrinter

OpenPrinter