MONITOR 结构 (winsplp.h)
注意
MONITOR 结构已过时,仅出于兼容性原因而受支持。 新的打印监视器应实现 MONITOR2 ,以便它们可以与打印服务器群集一起使用。
MONITOR 结构包含指向由打印监视器定义的函数的指针。
语法
typedef struct _MONITOR {
BOOL( )(LPWSTR pName,DWORD Level,LPBYTE pPorts,DWORD cbBuf,LPDWORD pcbNeeded,LPDWORD pcReturned) *pfnEnumPorts;
BOOL( )(LPWSTR pName,PHANDLE pHandle) *pfnOpenPort;
BOOL()(LPWSTR pPortName,LPWSTR pPrinterName,PHANDLE pHandle,_MONITOR *pMonitor) * pfnOpenPortEx;
BOOL( )(HANDLE hPort,LPWSTR pPrinterName,DWORD JobId,DWORD Level,LPBYTE pDocInfo) *pfnStartDocPort;
BOOL( )(HANDLE hPort,LPBYTE pBuffer,DWORD cbBuf,LPDWORD pcbWritten) *pfnWritePort;
BOOL( )(HANDLE hPort,LPBYTE pBuffer,DWORD cbBuffer,LPDWORD pcbRead) *pfnReadPort;
BOOL( )(HANDLE hPort) *pfnEndDocPort;
BOOL( )(HANDLE hPort) *pfnClosePort;
BOOL( )(LPWSTR pName,HWND hWnd,LPWSTR pMonitorName) *pfnAddPort;
BOOL( )(LPWSTR pName,DWORD Level,LPBYTE lpBuffer,LPWSTR lpMonitorName) *pfnAddPortEx;
BOOL( )(LPWSTR pName,HWND hWnd,LPWSTR pPortName) *pfnConfigurePort;
BOOL( )(LPWSTR pName,HWND hWnd,LPWSTR pPortName) *pfnDeletePort;
BOOL( )(HANDLE hPort,DWORD ControlID,LPWSTR pValueName,LPWSTR lpInBuffer,DWORD cbInBuffer,LPWSTR lpOutBuffer,DWORD cbOutBuffer,LPDWORD lpcbReturned) *pfnGetPrinterDataFromPort;
BOOL( )(HANDLE hPort,LPCOMMTIMEOUTS lpCTO,DWORD reserved) *pfnSetPortTimeOuts;
BOOL( )(LPCWSTR pszObject,ACCESS_MASK GrantedAccess,PHANDLE phXcv) *pfnXcvOpenPort;
DWORD( )(HANDLE hXcv,LPCWSTR pszDataName,PBYTE pInputData,DWORD cbInputData,PBYTE pOutputData,DWORD cbOutputData,PDWORD pcbOutputNeeded) *pfnXcvDataPort;
BOOL( )(HANDLE hXcv) *pfnXcvClosePort;
} MONITOR, *LPMONITOR;
成员
pfnEnumPorts
端口监视器服务器 DLL 的 EnumPorts 函数枚举端口监视器支持的端口。
pfnOpenPort
指向打印监视器的 OpenPort 函数的指针。
pfnOpenPortEx
语言监视器的 OpenPortEx
函数打开打印机端口。
pfnStartDocPort
打印监视器的 StartDocPort
函数执行在指定端口上启动打印作业所需的任务。
pfnWritePort
指向打印监视器的 WritePort 函数的指针。
pfnReadPort
指向打印监视器的 ReadPort 函数的指针。
pfnEndDocPort
打印监视器的 EndDocPort 函数执行在指定端口上结束打印作业所需的任务。
pfnClosePort
指向打印监视器的 ClosePort 函数的指针。
pfnAddPort
注意
AddPort 函数已过时,不应使用。
AddPort 创建一个端口,并将其添加到后台处理程序环境中指定监视器当前支持的端口列表。
pfnAddPortEx
(已过时。必须为 NULL.) 指向打印监视器的 AddPortEx 函数的指针。 仅 (端口监视器。)
pfnConfigurePort
注意
ConfigurePort 函数已过时,不应使用。 请改用 ConfigurePortUI 。
ConfigurePort 是配置指定端口的端口管理功能。
pfnDeletePort
注意
DeletePort 函数已过时,不应使用。
DeletePort 从监视器的环境中删除端口。
pfnGetPrinterDataFromPort
端口监视器的 GetPrinterDataFromPort 函数从双向打印机获取状态信息,并将其返回给调用方。
pfnSetPortTimeOuts
端口监视器服务器 DLL 的 SetPortTimeOuts
函数为打开的端口设置端口超时值。
pfnXcvOpenPort
指向打印监视器的 XcvOpenPort 函数的指针。 仅 (端口监视器。)
pfnXcvDataPort
指向打印监视器的 XcvDataPort 函数的指针。 仅 (端口监视器。)
pfnXcvClosePort
指向打印监视器的 XcvClosePort 函数的指针。 仅 (端口监视器。)
注解
以下部分更详细地介绍了每个回调成员。
AddPort
typedef BOOL (WINAPI *pfnAddPort)(
_In_ HANDLE hMonitor,
_In_ LPWSTR pName,
_In_ HWND hWnd,
_In_ LPWSTR pMonitorName
);
AddPort) (参数
监视 [in] (AddPort)
调用方提供的监视器实例句柄。 这是监视器的 InitializePrintMonitor2 函数返回的句柄。 (如果打印监视器支持 InitializePrintMonitor2 而不是 InitializePrintMonitor2.)
pName [in] (AddPort)
指向以 null 结尾的字符串的指针,该字符串指定端口连接到的服务器的名称。 如果 pName 为 NULL,则端口为本地端口。
hWnd [in] (AddPort)
要在其中输入端口名称的对话框的父窗口的句柄。
pMonitorName [in] (AddPort)
指向以 null 结尾的字符串的指针,该字符串指定与端口关联的监视器。
返回值 (AddPort)
如果函数成功,则返回值为 TRUE,否则返回值为 FALSE。
ConfigurePort
typedef BOOL (WINAPI *pfnConfigurePort)(
_In_ HANDLE hMonitor,
_In_ LPWSTR pName,
_In_ HWND hWnd,
_In_ LPWSTR pPortName
);
ConfigurePort) (参数
hMonitor [in] (ConfigurePort)
调用方提供的监视器实例句柄。 这是监视器的 InitializePrintMonitor2 函数返回的句柄。 (如果打印监视器支持 InitializePrintMonitor 而不是 InitializePrintMonitor2.)
pName [in] (ConfigurePort)
指向以 null 结尾的字符串的指针,该字符串指定给定端口所在的服务器的名称。 如果此字符串为 NULL,则端口为本地端口。
hWnd [in] (ConfigurePort)
要在其中输入配置信息的对话框的父窗口的句柄。
pPortName [in] (ConfigurePort)
指向以 null 结尾的字符串的指针,该字符串指定要配置的端口的名称。
ConfigurePort) (返回值
如果函数成功,则返回值为 TRUE。
DeletePort
pfnDeletePort DeletePort;
BOOL WINAPI DeletePort(
_In_ HANDLE hMonitor,
_In_ LPWSTR pName,
_In_ HWND hWnd,
_In_ LPWSTR pPortName
)
DeletePort) (参数
hMonitor [in] (DeletePort)
调用方提供的监视器实例句柄。 这是监视器的 InitializePrintMonitor2 函数返回的句柄。 (如果打印监视器支持 InitializePrintMonitor 而不是 InitializePrintMonitor2.)
pName [in] (DeletePort)
指向以 null 结尾的字符串的指针,该字符串指定要删除的端口所在的服务器的名称。 如果此参数为 NULL,则端口为本地端口。
hWnd [in] (DeletePort)
端口删除对话框的父窗口的句柄。
pPortName [in] (DeletePort)
指向以 null 结尾的字符串的指针,该字符串命名要删除的端口。
DeletePort) (返回值
如果函数成功,则返回值为 TRUE。
EndDocPort
typedef BOOL ( WINAPI *pfnEndDocPort)(
_In_ HANDLE hPort
);
EndDocPort) (参数
hPort [in] (EndDocPort)
调用方提供的端口句柄。
返回值 (EndDocPort)
如果操作成功,函数应返回 TRUE。 否则应返回 FALSE。
EnumPorts
typedef BOOL (WINAPI *pfnEnumPorts)(
_In_ HANDLE hMonitor,
_In_opt_ LPWSTR pName,
_In_ DWORD Level,
_Out_ LPBYTE pPorts,
_In_ DWORD cbBuf,
_Out_ LPDWORD pcbNeeded,
_Out_ LPDWORD pcReturned
);
EnumPorts) (参数
hMonitor [in] (EnumPorts)
调用方提供的监视器实例句柄。 这是监视器的 InitializePrintMonitor2 函数返回的句柄。 (如果打印监视器支持 InitializePrintMonitor 而不是 InitializePrintMonitor2.)
pName [in, optional] (EnumPorts)
调用方提供的指针,指向包含要枚举其端口的服务器的名称的字符串。 NULL 指针表示正在执行端口监视服务器 DLL 的系统。
级别 [in] (EnumPorts)
调用方提供的值,指示要在 pPorts 指向的缓冲区中返回的结构类型。
可能的值为 1 (PORT_INFO_1) 或 2 (PORT_INFO_2) 。
pPorts [out] (EnumPorts)
调用方提供的指向缓冲区的指针,用于接收端口信息。 返回的信息必须由 PORT_INFO_1 或 PORT_INFO_2 结构的数组组成,后跟结构成员指向的字符串。
cbBuf [in] (EnumPorts)
pPorts 指向的缓冲区的调用方提供的大小(以字节为单位)。
(EnumPorts)
调用方提供的指针指向要接收缓冲区大小(以字节为单位)的位置的指针,该大小需要包含所有返回的信息。
pcReturned [out] (EnumPorts)
调用方提供的指针指向用于接收枚举端口数的位置。
EnumPorts) (返回值
如果操作成功,函数应返回 TRUE。 否则应返回 FALSE。
GetPrinterDataFromPort
pfnGetPrinterDataFromPort GetPrinterDataFromPort;
BOOL WINAPI GetPrinterDataFromPort(
_In_ HANDLE hPort,
_In_ DWORD ControlID,
_In_ LPWSTR pValueName,
_In_ LPWSTR lpInBuffer,
_In_ DWORD cbInBuffer,
_Out_ LPWSTR lpOutBuffer,
_In_ DWORD cbOutBuffer,
_Out_ LPDWORD lpcbReturned
)
GetPrinterDataFromPort) (参数
hPort [in] (GetPrinterDataFromPort)
调用方提供的端口句柄。
ControlID [in] (GetPrinterDataFromPort)
调用方提供的设备 I/O 控制代码。 如果值为零,则表示值名称由 pValueName 提供。
pValueName [in] (GetPrinterDataFromPort)
调用方提供的指向标识所请求信息的字符串的指针。 仅当 ControlID 为零时有效。
lpInBuffer [in] (GetPrinterDataFromPort)
调用方提供的指向包含输入数据的缓冲区的指针。 仅当 ControlID 为非零时使用。
cbInBuffer [in] (GetPrinterDataFromPort)
lpInBuffer 指向的缓冲区的调用方提供的大小(以字节为单位)。
lpOutBuffer [out] (GetPrinterDataFromPort)
调用方提供的指向缓冲区的指针,用于接收请求的数据。
cbOutBuffer [in] (GetPrinterDataFromPort)
lpOutBuffer 指向的缓冲区的调用方提供的大小(以字节为单位)。
l (GetPrinterDataFromPort)
调用方提供的指向位置的指针,用于接收写入 lpOutBuffer 指向的缓冲区的字节数。
返回值 (GetPrinterDataFromPort)
如果操作成功,函数应返回 TRUE。 否则应返回 FALSE。
OpenPortEx
pfnOpenPortEx OpenPortEx;
BOOL WINAPI OpenPortEx(
_In_ HANDLE hMonitor,
_In_ HANDLE hMonitorPort,
_In_ LPWSTR pPortName,
_In_ LPWSTR pPrinterName,
_Out_ PHANDLE pHandle,
_In_ struct _MONITOR2 *pMonitor
)
OpenPortEx) (参数
hMonitor [in] (OpenPortEx)
调用方提供的语言监视器实例句柄。 这是监视器的 InitializePrintMonitor2 函数返回的句柄。 (如果打印监视器支持 InitializePrintMonitor 而不是 InitializePrintMonitor2.) 则此参数不存在。
hMonitorPort [in] (OpenPortEx)
调用方提供的端口监视器实例句柄。 这是监视器的 InitializePrintMonitor2 函数返回的句柄。 (如果打印监视器支持 InitializePrintMonitor 而不是 InitializePrintMonitor2.) 语言监视器在调用端口监视器 MONITOR2 结构中的函数时必须使用此句柄,则此参数不存在。
pPortName [in] (OpenPortEx)
调用方提供的指针,指向包含要打开的端口名称的字符串。
pPrinterName [in] (OpenPortEx)
调用方提供的指针指向包含连接到端口的打印机名称的字符串。
pHandle [out] (OpenPortEx)
调用方提供的指向要接收端口句柄的位置的指针。
pMonitor [in] (OpenPortEx)
调用方提供的指针指向端口监视器的 InitializePrintMonitor2 函数返回的 MONITOR2 结构。
(OpenPortEx) 返回值
如果操作成功,函数应返回 TRUE。 否则应返回 FALSE。
SetPortTimeOuts
BOOL (WINAPI *pfnSetPortTimeOuts)
(
_In_ HANDLE hPort,
_In_ LPCOMMTIMEOUTS lpCTO,
_In_ DWORD reserved // must be set to 0
);
SetPortTimeOuts) (参数
hPort [in] (SetPortTimeOuts)
调用方提供的用于设置超时值的开放端口的句柄。
lpCTO [in] (SetPortTimeOuts)
调用方提供的指向 COMMTIMEOUTS 结构的指针。
reserved [in] (SetPortTimeOuts)
保留供将来使用。 必须设置为零。
SetPortTimeOuts) (返回值
如果操作成功,函数应返回 TRUE。 否则应返回 FALSE。
StartDocPort
typedef BOOL (WINAPI *pfnStartDocPort)(
_In_ HANDLE hPort,
_In_ LPWSTR pPrinterName,
_In_ DWORD JobId,
_In_ DWORD Level,
_In_ LPBYTE pDocInfo
);
StartDocPort) (参数
hPort [in] (StartDocPort)
调用方提供的端口句柄。
pPrinterName [in] (StartDocPort)
调用方提供的指针,指向包含打印机名称的字符串。
JobId [in] (StartDocPort)
调用方提供的后台处理程序分配的作业标识符。
级别 [in] (StartDocPort)
调用方提供的值,指示 pDocInfo 指向的结构的类型。
可能的值为 1 (DOC_INFO_1) 或 2 (DOC_INFO_2) 。
pDocInfo [in] (StartDocPort)
调用方提供的指向 DOC_INFO_1 或 DOC_INFO_2 结构的指针。
(StartDocPort) 返回值
如果操作成功,函数应返回 TRUE。 否则应返回 FALSE。
备注
后台处理程序在收到将端口添加到其环境的应用程序请求时调用 AddPort 。 后台处理程序将调用转发到命名服务器上的命名端口监视器。
AddPort 允许以交互方式添加端口。 监视器应提示用户在与 hWnd 关联的窗口上的对话框中输入端口名称。 AddPort 应通过调用 Win32 EnumPorts 函数来验证输入的端口名称,以确保不会将重复的端口名称添加到后台处理程序环境。 监视器还应验证端口是否为它所支持的端口。
后台处理程序不支持远程 AddPort 调用。 因此, AddPort 实现可以忽略 pName 和 pMonitorName 参数。
后台处理程序调用 ConfigurePort ,以便端口监视器可以执行端口配置。 ConfigurePort 可以提供一个对话框,用于从用户获取部分或全部必需的端口配置信息。
后台处理程序不支持远程 ConfigurePort 调用;因此,监视器可以忽略 pName 参数。
后台处理程序调用 DeletePort ,以便端口监视器可以从监视器的环境中删除端口。 监视器应从其状态中删除指定的端口。 只要端口打开,后台处理程序就不会在监视器上调用 DeletePort 。
应用程序可以删除本地和远程端口。 打印机 UI 在后台处理程序调用 DeletePort 之前显示一个确认消息框,因此监视器应忽略 hWnd 参数,而不显示另一个对话框。
语言监视器 和端口监视器服务器 DLL 是定义 EndDocPort 函数并在 MONITOR2 结构中包含该函数的地址所必需的。
作为函数的 hPort 参数接收的句柄是监视器的 OpenPort 或 OpenPortEx 函数提供的端口句柄。
语言监视器的 EndDocPort 函数通常调用关联的端口监视器的 EndDocPort 函数。 当打印设备完成作业时,它还应通过调用 SetJob 并指定 JOB_CONTROL_LAST_PAGE_EJECTED 命令来通知后台处理程序。 在打印机发送作业真正完成的通知之前,双向打印机的语言监视器不应调用 SetJob 。
端口监视服务器 DLL 的 EndDocPort 函数通常调用 CloseHandle 函数,以关闭以前通过从 StartDocPort 中调用 CreateFile 获取的句柄。 它还应在打印设备完成作业后通知后台处理程序,方法是调用 SetJob,指定JOB_CONTROL_SENT_TO_PRINTER命令。 (如果后台处理程序通过语言监视器与端口通信,则在语言监视器发送JOB_CONTROL_LAST_PAGE_EJECTED.)
EndDocPort 函数应释放由 StartDocPort 函数分配的所有资源。
如果用户已删除或重新启动打印作业,则可能需要修改 EndDocPort 函数的行为。 函数可以调用 GetJob,并检查状态为JOB_STATUS_DELETING或JOB_STATUS_RESTART,以查看是否发生了其中任一事件。
需要端口监视服务器 DLL 来定义 EnumPorts 函数,并在 MONITOR2 结构中包含该函数的地址。 语言监视器不导出此函数。
EnumPorts 函数的用途是枚举打印监视器当前支持的端口。 这些端口是以前指定给监视器的 AddPortUI 或 AddPortEx 函数的端口。
EnumPorts 函数应使用PORT_INFO_1或PORT_INFO_2结构数组填充 pPort 指向的缓冲区。 然后,从最后一个数组元素后面的内存位置开始,该函数必须加载数组的结构成员指向的所有字符串。 有关如何执行此操作的示例,请参阅 localmon.dll( 一个示例端口监视器)。 该函数还必须返回 (提供的结构数,即通过将数字放置在 pcReturned 指向的位置) 支持的端口数。
调用方指定 cbBuf 中提供的缓冲区的大小。 如果缓冲区太小,该函数应将所需的缓冲区大小放置在 由ERROR_INSUFFICIENT_BUFFER所指向的位置,调用 SetLastError 并指定ERROR_INSUFFICIENT_BUFFER,并返回 FALSE。
如果 Level 包含无效的级别号,则函数应调用 SetLastError 并指定ERROR_INVALID_LEVEL,并返回 FALSE。 某些端口监视器仅支持级别值 1。
端口监视器必须支持PORT_INFO_2结构的 pMonitorName 和 pDescription 成员所指向的字符串的本地化。 这些字符串应在资源文件中定义,并通过调用 LoadString 获取。
PORT_INFO_2 结构的 fPortType 成员不用于基于 NT 的操作系统。
语言监视器 和端口监视器服务器 DLL 可以选择定义 GetPrinterDataFromPort 函数,并将函数的地址包含在 MONITOR2 结构中。
函数适用于双向打印机,可通过以下两种方式使用:
作为请求语言监视器轮询打印机端口的一种方法,获取注册表中存储的特定于打印机的信息的当前值。
作为请求端口监视器向端口驱动程序发送 I/O 控制代码的一种方法。
如果语言监视器的 GetPrinterDataFromPort 函数收到 pValueName 中的字符串指针,则应在提供的输出缓冲区中返回一个值。 通常,字符串表示注册表值名称,当应用程序调用 GetPrinterData 函数时,后台处理程序调用 GetPrinterDataFromPort 。
语言监视器的职责是通过调用端口监视器的 WritePort 函数,并通过调用 ReadPort 读取响应来获取所需的值,将命令发送到打印机硬件。 例如, 示例语言监视器 pjlmon.dll 可以返回端口的“已安装内存”和“可用内存”注册表值名称的值。
后台处理程序调用 GetPrinterDataFromPort 以获取注册表值后,它会使用新值更新注册表。
通常,端口监视器不支持调用在 pValueName 中包含字符串指针的 GetPrinterDataFromPort。
如果语言监视器的 GetPrinterDataFromPort 函数在 ControlID 中收到非零 I/O 控件代码,则它应仅调用关联端口监视器的 GetPrinterDataFromPort 函数并返回结果。 内核模式驱动程序参考列出了并行端口和串行端口的 I/O 控制代码。
当端口监视器的 GetPrinterDataFromPort 函数在 ControlID 中收到非零 I/O 控制代码时,它应调用 DeviceIOControl 以将控制代码传递给内核模式端口驱动程序。 lpInBuffer、cbInBuffer、lpOutBuffer、cbOutBuffer 和 lcbReturned 参数值也应传递到 DeviceIOControl。
需要语言监视器来定义函数 OpenPortEx
并将其地址包含在 MONITOR2 结构中。 当 OpenPortEx
打印队列连接到端口时,打印后台处理程序将调用 该函数。
函数 OpenPortEx
的主要用途是返回一个端口句柄,调用方可以将该句柄用作后续调用语言监视器的 StartDocPort、 WritePort、 ReadPort、 EndDocPort 和 GetPrinterDataFromPort 函数的输入参数。 由于语言监视器通常通过在其关联的端口监视器中调用等效函数来实现这些函数,因此语言监视器通常通过调用端口监视器的 OpenPort 函数来获取端口句柄。 有关详细信息,请参阅 语言和端口监视器交互。
函数 OpenPortEx
的 pMonitor 参数是指向端口监视器 MONITOR2 结构的指针。 此结构包含指向端口监视器的可调用函数的指针。 函数OpenPortEx
应检查 结构,以验证所有必需的函数指针是否为非 NULL。 如果该结构有效,则函数应将其复制到本地存储中。 否则 OpenPortEx
,应调用 SetLastError,指定ERROR_INVALID_PRINT_MONITOR,并返回 FALSE。
接受端口句柄作为输入的打印监视器函数也不接受监视器句柄。 因此, OpenPortEx
函数必须将收到的监视器句柄存储在端口句柄可以引用的位置。 这允许接受端口句柄的函数引用监视器句柄。
端口监视器服务器 DLL 的 SetPortTimeOuts
函数允许语言监视器为打开的端口指定端口超时值。 函数是可选的,仅当端口监视器控制允许修改端口超时值的端口时,才必须提供该函数。 如果定义了函数,则其地址必须包含在 MONITOR2 结构中。
函数由示例 语言监视器 pjlmon.dll 调用,可以编写调用它的自定义语言监视器。 打印后台处理程序不调用 SetPortTimeOuts
。
端口监视器应从其 OpenPort 函数中初始化端口的超时值。
需要语言监视器 和端口监视器服务器 DLL 来定义 StartDocPort
函数,并在 MONITOR2 结构中包含函数的地址。
作为函数的 hPort 参数接收的句柄是监视器的 OpenPort 或 OpenPortEx 函数提供的端口句柄。
语言监视器的 StartDocPort
函数通常调用关联的端口监视器的 StartDocPort
函数。
端口监视器服务器 DLL 的 StartDocPort
函数通常调用 CreateFile 函数,以创建与内核模式端口驱动程序的连接。
如有必要,端口监视器应阻止其他进程使用指定的端口,直到调用 EndDocPort 。 例如,COM 端口的端口监视器必须确保,当后台处理程序向端口发送打印机数据时,另一个应用程序不会假定该端口已连接到特定的通信设备,然后尝试与该设备通信。 此警告说明不适用于本地打印提供程序,该提供程序保证它永远不会 StartDocPort
在没有对 EndDocPort 进行干预调用的情况下连续调用两次,但它适用于不做出此保证的打印提供程序。
要求
要求 | 值 |
---|---|
Header | winsplp.h (包括 Winsplp.h) |