AddPrinter 函式

  • 發行項

AddPrinter 函式會將印表機新增至指定伺服器支援的印表機清單。

語法

HANDLE AddPrinter(
  _In_ LPTSTR *pName,
  _In_ DWORD  Level,
  _In_ LPBYTE pPrinter
);

參數

pName [in]

Null 終止字串的指標，指定應該安裝印表機的伺服器名稱。 如果此字串為 Null，則會在本機安裝印表機。

層級 [in]

pPrinter指向的結構版本。 此值必須是 2。

pPrinter [in]

包含印表機相關資訊 之PRINTER_INFO_2 結構的指標。 在呼叫AddPrinter之前，您必須為此結構的pPrinterName、pPortName、pDriverName和pPrintProcessor成員指定非Null值。

傳回值

如果函式成功，傳回值就是 (不是安全線程的控制碼，) 到新的印表機物件。 當您完成控制碼時，請將它傳遞給 ClosePrinter 函 式以關閉它。

如果函式失敗，傳回值為 Null。

備註

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

注意

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

呼叫端必須具有 SeLoadDriverPrivilege。

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

以下是在呼叫AddPrinter函式之前可設定PRINTER_INFO_2結構的成員：

  • 屬性
  • pPrintProcessor
  • DefaultPriority
  • 優先順序
  • pComment
  • pSecurityDescriptor
  • pDatatype
  • pSepFile
  • pDevMode
  • pShareName
  • pLocation
  • StartTime
  • pParameters
  • UntilTime

PRINTER_INFO_2結構的Status、cJobs和AveragePPM成員會保留供GetPrinter 函式使用。 呼叫 AddPrinter之前，不得設定它們。

如果 pSecurityDescriptor 為 Null，系統會將預設的安全性描述項指派給印表機。 預設安全性描述項具有下列許可權。

值 Description
系統管理員與進階使用者 列印佇列的完整控制。 這表示這些群組的成員可以列印、管理佇列 (可以刪除佇列、變更佇列的任何設定，包括安全性描述項) ，以及管理所有使用者的列印工作， (刪除、暫停、繼續、重新開機作業) 。請注意，在 Windows XP Professional 之前，Power Users 不存在。
建立者/擁有者 可以管理自己的作業。 這表示提交工作的使用者可以管理 (刪除、暫停、繼續、重新開機) 自己的作業。
所有人 執行和標準讀取控制項。 這表示每個人群組的成員都可以列印和讀取列印佇列的屬性。

應用程式使用 AddPrinter 函式建立印表機物件之後，必須使用 PrinterProperties 函式來指定與印表機物件相關聯之印表機驅動程式的正確設定。

如果印表機物件具有相同名稱， 則 AddPrinter 函 式會傳回錯誤，除非該物件標示為擱置刪除。 在此情況下，不會刪除現有的印表機，而且 AddPrinter 建立參數會用來變更現有的印表機設定 (，就像應用程式已使用 SetPrinter 函式) 一樣。

使用 EnumPrintProcessors 函式來列舉伺服器上安裝的列印處理器集合。 使用 EnumPrintProcessorDatatypes 函式來列舉列印處理器支援的資料類型集合。 使用 EnumPorts 函式來列舉可用的埠集合。 使用 EnumPrinterDrivers 函式來列舉已安裝的印表機驅動程式。

AddPrinter函式的呼叫端必須具有要建立印表機之伺服器的SERVER_ACCESS_ADMINISTER存取權。 函式傳回的控制碼會有PRINTER_ALL_ACCESS許可權，而且可用來在印表機上執行系統管理作業。

如果 DrvPrinterEvent 函式傳遞PRINTER_EVENT_FLAG_NO_UI旗標，驅動程式就不應該在 DrvPrinterEvent期間使用 UI 呼叫。 若要執行 UI 相關作業，安裝程式應該使用印表機 .inf 檔案中的VendorSetup專案，或針對隨插即用裝置，安裝程式可以使用裝置特定的共同安裝程式。 如需 VendorSetup的詳細資訊，請參閱 Microsoft Windows 驅動程式開發工具組 (DDK) 。

網際網路連線防火牆 (ICF) 預設會封鎖印表機埠，但當您執行 AddPrinter時，會啟用檔案和列印共用的例外狀況。

規格需求

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

另請參閱

列印

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

ClosePrinter

DeletePrinter

EnumPorts

EnumPrinterDrivers

EnumPrintProcessors

EnumPrintProcessorDatatypes

GetPrinter

PRINTER_INFO_2

PrinterProperties

SetPrinter