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之前,您必須為此結構的pPrinterNamepPortNamepDriverNamepPrintProcessor成員指定非Null值。

傳回值

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

如果函式失敗,則傳回值為 Null

備註

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

注意

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

呼叫端必須具有 SeLoadDriverPrivilege

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

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

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

PRINTER_INFO_2結構的StatuscJobsAveragePPM成員會保留供GetPrinter函式使用。 呼叫 AddPrinter之前,不得設定它們。

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

描述
系統管理員與進階使用者 列印佇列的完整控制。 這表示這些群組的成員可以列印、管理佇列 (可以刪除佇列、變更佇列的任何設定,包括安全性描述元) ,以及管理所有使用者的列印工作, (刪除、暫停、繼續、重新開機作業) 。請注意,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