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，则系统将默认安全描述符分配给打印机。 默认安全描述符具有以下权限。
| 值 | 说明 |
|---|---|
| 管理员和超级用户 | 完全控制打印队列。 这意味着这些组的成员可以打印、管理队列 (可以删除队列、更改队列的任何设置（包括安全描述符) ），以及管理所有用户的打印作业 (删除、暂停、恢复、重启作业) 。请注意，Power Users 在 Windows XP Professional 之前不存在。 |
| 创建者/所有者 | 可以管理自己的作业。 这意味着提交作业的用户可以管理 (删除、暂停、恢复、重启) 自己的作业。 |
| 所有人 | 执行和标准读取控制。 这意味着 everyone 组的成员可以打印和读取打印队列的属性。 |
使用 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) 。
默认情况下，Internet 连接防火墙 (ICF) 阻止打印机端口，但在运行 AddPrinter 时会启用文件和打印共享的例外。
要求
| 要求 | 值 |
|---|---|
| 最低受支持的客户端 |
Windows 2000 Professional [仅限桌面应用] |
| 最低受支持的服务器 |
Windows 2000 Server [仅限桌面应用] |
| 标头 |
|
| 库 |
|
| DLL |
|
| Unicode 和 ANSI 名称 |
AddPrinterW (Unicode) 和 AddPrinterA (ANSI) |