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_1PORT_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_1DOC_INFO_2 结构的指针。

(StartDocPort) 返回值

如果操作成功,函数应返回 TRUE。 否则应返回 FALSE。

备注

后台处理程序在收到将端口添加到其环境的应用程序请求时调用 AddPort 。 后台处理程序将调用转发到命名服务器上的命名端口监视器。

AddPort 允许以交互方式添加端口。 监视器应提示用户在与 hWnd 关联的窗口上的对话框中输入端口名称。 AddPort 应通过调用 Win32 EnumPorts 函数来验证输入的端口名称,以确保不会将重复的端口名称添加到后台处理程序环境。 监视器还应验证端口是否为它所支持的端口。

后台处理程序不支持远程 AddPort 调用。 因此, AddPort 实现可以忽略 pNamepMonitorName 参数。

后台处理程序调用 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 函数的用途是枚举打印监视器当前支持的端口。 这些端口是以前指定给监视器的 AddPortUIAddPortEx 函数的端口。

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结构的 pMonitorNamepDescription 成员所指向的字符串的本地化。 这些字符串应在资源文件中定义,并通过调用 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 以将控制代码传递给内核模式端口驱动程序。 lpInBuffercbInBufferlpOutBuffercbOutBufferlcbReturned 参数值也应传递到 DeviceIOControl

需要语言监视器来定义函数 OpenPortEx 并将其地址包含在 MONITOR2 结构中。 当 OpenPortEx 打印队列连接到端口时,打印后台处理程序将调用 该函数。

函数 OpenPortEx 的主要用途是返回一个端口句柄,调用方可以将该句柄用作后续调用语言监视器的 StartDocPortWritePortReadPortEndDocPortGetPrinterDataFromPort 函数的输入参数。 由于语言监视器通常通过在其关联的端口监视器中调用等效函数来实现这些函数,因此语言监视器通常通过调用端口监视器的 OpenPort 函数来获取端口句柄。 有关详细信息,请参阅 语言和端口监视器交互

函数 OpenPortExpMonitor 参数是指向端口监视器 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)

另请参阅

MONITOR2

MONITORUI