SetPrinter

描述

SetPrinter功能设置指定打印机的数据，或通过暂停打印，恢复打印或清除所有打印作业来设置指定打印机的状态。

C++ 语法

BOOL SetPrinter(

__in HANDLE hPrinter,

__in DWORD Level,

__in LPBYTE pPrinter,

__in DWORD Command

);

PowerBASIC 语法

FUNCTION SetPrinterA ( _

BYVAL hPrinter AS DWORD, _

BYVAL Level AS DWORD, _

BYREF pPrinter AS ANY, _

BYVAL Command AS DWORD _

) AS LONG

Unicode版本:

FUNCTION SetPrinterW ( _

BYVAL hPrinter AS DWORD, _

BYVAL Level AS DWORD, _

BYREF pPrinter AS ANY, _

BYVAL Command AS DWORD _

) AS LONG

参数

hPrinter

[in]处理打印机。使用OpenPrinter，OpenPrinter2或AddPrinter功能来检索打印机句柄。

Level

[in]指定函数存储到pPrinter指向的缓冲区中的数据类型。如果命令参数不等于零，则水平参数必须为零。

Windows 95/98 / Me：该值可以是0,2或5。

Windows NT / 2000 / XP / Vista / Windows 7：该值可以是0,2,3,4,5,6,7,8或9。

pPrinter

[in]指向包含要为打印机设置的数据的缓冲区的指针，或包含由命令参数指定的命令的信息。缓冲区中的数据类型由水平的值决定。

水平	结构体
0	如果命令参数是PRINTER_CONTROL_SET_STATUS，则pPrinter必须包含一个DWORD值，该值指定要设置的新打印机状态。有关可能状态值的列表，请参阅PRINTER_INFO_2结构的状态成员。请注意，PRINTER_STATUS_PAUSED和PRINTER_STATUS_PENDING_DELETION不是要设置的有效状态值。如果水平为0，但是Command参数不是PRINTER_CONTROL_SET_STATUS，则pPrinter必须为NULL。
2	包含有关打印机详细信息的PRINTER_INFO_2结构。
3	Windows NT / 2000 / XP / Vista / Windows 7：包含打印机安全信息的PRINTER_INFO_3结构。
4	Windows NT / 2000 / XP / Vista / Windows 7：包含最少打印机信息的PRINTER_INFO_4结构，包括打印机的名称，服务器的名称以及打印机是远程的还是本地的。
5	包含打印机信息（如打印机属性和超时设置）的PRINTER_INFO_5结构。
6	Windows 2000 / XP / Vista / Windows 7：指定打印机状态值的PRINTER_INFO_6结构。
7	Windows 2000 / XP / Vista / Windows 7：A PRINTER_INFO_7结构。此结构的dwAction成员指示SetPrinter是否应在目录服务中发布，取消发布，重新发布或更新打印机的数据。
8	Windows 2000 / XP / Vista / Windows 7：指定全局默认打印机设置的PRINTER_INFO_8结构。
9	Windows 2000 / XP / Vista / Windows 7：指定每用户默认打印机设置的PRINTER_INFO_9结构。

Command

[in]指定由SetPrinter函数执行的操作。

如果水平参数非零，则命令必须为零。在这种情况下，打印机保持其当前状态，并且功能重新配置由水平和pPrinter参数指定的打印机数据。

如果水平参数为零，则命令可以是以下值之一来设置打印机的状态。

值	含义
PRINTER_CONTROL_PAUSE	暂停打印机。
PRINTER_CONTROL_PURGE	删除打印机中的所有打印作业。
PRINTER_CONTROL_RESUME	恢复暂停的打印机。
PRINTER_CONTROL_SET_STATUS	设置打印机状态。pPrinter参数是指向新的打印机状态的DWORD的指针。

返回值

如果函数成功，则返回值为非零值。

如果函数失败，返回值为零。

Windows 2000 / XP / Vista / Vista / Windows 7：如果水平为7且发布操作失败，SetPrinter返回ERROR_IO_PENDING，并尝试在后台完成该操作。如果水平为7且更新操作失败，SetPrinter将返回ERROR_FILE_NOT_FOUND。

备注

您不能使用SetPrinter更改默认打印机。

要修改当前的打印机设置，请调用GetPrinter功能将当前设置检索到PRINTER_INFO_2结构中，根据需要修改该结构的成员，然后调用SetPrinter.

SetPrinter功能忽略pServerName，AveragePPM，状态和cJobscJobs结构的成员。

暂停打印机将暂停对该打印机的所有打印作业的计划，但可能正在打印的打印作业除外。打印作业可以提交到一个已暂停的打印机，但是没有任何作业将被安排在该打印机上打印，直到打印恢复为止。如果打印机被清除，则除了当前打印作业之外，该打印机的所有打印作业将被删除。

如果您使用SetPrinter修改打印机的默认DEVMODE结构（全局设置打印机默认值），则必须先调用DocumentProperties功能验证DEVMODE结构。

Windows NT / 2000 / XP / Vista / Windows 7：对于包含指向安全描述符的指针的PRINTER_INFO_2和PRINTER_INFO_3结构，该函数只能设置调用方有权修改的安全描述符的那些组件。要设置特定的安全描述符组件，您必须在调用OpenPrinter或OpenPrinter2函数以检索打印机的句柄时指定必要的访问权限。下表显示了修改各种安全描述符组件所需的访问权限。

访问权限	安全描述符组件
WRITE_OWNER	所有者小组
WRITE_DAC	自由访问控制列表（DACL）
ACCESS_SYSTEM_SECURITY	系统访问控制列表（SACL）

如果安全描述符包含调用者不具有修改访问权限的组件，则SetPrinter将失败。您不想修改的安全描述符的那些组件应该为NULL或不适用。如果您不想修改安全描述符，并使用PRINTER_INFO_2结构调用SetPrinter，则将该结构的pSecurityDescriptor成员设置为NULL。

Windows XP SP2 / Vista / Windows 7：默认情况下，Internet连接防火墙（ICF）阻止打印机端口，但可以启用文件和打印共享的例外。如果机器管理员调用SetPrinter，则启用异常。如果由非管理员调用，并且异常尚未启用，则调用失败。

Windows 2000 / XP / Vista / Windows 7：您可以使用级别7与PRINTER_INFO_7结构来发布，取消发布或更新打印机的目录服务数据。打印机的目录服务数据包括通过调用打印机的SetPrinterDataEx功能在SPLDS_ *键下存储的所有数据。在致电SetPrinter之前，将PRINTER_INFO_7的pszObjectGUID成员设置为NULL，并将dwAction成员设置为以下值之一。

值	描述
DSPRINT_PUBLISH	发布目录服务数据。
DSPRINT_REPUBLISH	打印机的目录服务数据未发布，然后再次发布，刷新已发布打印机中的所有属性。重新发布还会更改已发布打印机的GUID。如果您怀疑打印机的已发布数据已损坏，请使用此值。
DSPRINT_UNPUBLISH	取消发布目录服务数据。
DSPRINT_UPDATE	更新目录服务数据。这与DSPRINT_PUBLISH相同，但如果打印机尚未发布，则SetPrinter将失败，并显示ERROR_FILE_NOT_FOUND。使用DSPRINT_UPDATE更新发布的属性，但不强制发布。打印机驱动程序应始终使用DSPRINT_UPDATE而不是DSPRINT_PUBLISH。

对于SetPrinter，DSPRINT_PENDING不是有效的dwAction值。

Windows 95/98 / Me：SetPrinter不更新PRINTER_INFO_2结构中的pShareName成员。

您不能从Windows 95/98 / Me计算机调用SetPrinter，以使用打印机的UNC名称设置Windows NT / 2000 / XP / Vista / Windows 7打印机的数据。

引用文件 #INCLUDE Once

WinSpool.inc