MONITOR-Struktur (winsplp.h)

  • Artikel

Achtung

Die MONITOR-Struktur ist veraltet und wird nur aus Kompatibilitätsgründen unterstützt. Neue Druckmonitore sollten MONITOR2 implementieren, damit sie mit Druckserverclustern verwendet werden können.

Die MONITOR-Struktur enthält Zeiger auf die von Druckmonitoren definierten Funktionen.

Syntax

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;

Member

pfnEnumPorts

Die EnumPorts-Funktion einer Portmonitorserver-DLL listet die Vom Portmonitor unterstützten Ports auf.

pfnOpenPort

Zeiger auf die OpenPort-Funktion des Druckmonitors.

pfnOpenPortEx

Die Funktion eines Sprachmonitors OpenPortEx öffnet einen Druckeranschluss.

pfnStartDocPort

Die Funktion eines Druckmonitors StartDocPort führt die Aufgaben aus, die zum Starten eines Druckauftrags am angegebenen Port erforderlich sind.

pfnWritePort

Zeiger auf die WritePort-Funktion des Druckmonitors.

pfnReadPort

Zeiger auf die ReadPort-Funktion des Druckmonitors.

pfnEndDocPort

Die EndDocPort-Funktion eines Druckmonitors führt die Aufgaben aus, die zum Beenden eines Druckauftrags am angegebenen Port erforderlich sind.

pfnClosePort

Zeiger auf die ClosePort-Funktion des Druckmonitors.

pfnAddPort

Achtung

Die AddPort-Funktion ist veraltet und sollte nicht verwendet werden.

AddPort erstellt einen Port und fügt ihn der Liste der Ports hinzu, die derzeit vom angegebenen Monitor in der Spooler-Umgebung unterstützt werden.

pfnAddPortEx

(Veraltet. Muss NULL sein.) Zeiger auf die AddPortEx-Funktion des Druckmonitors. (Nur Portmonitore.)

pfnConfigurePort

Achtung

Die ConfigurePort-Funktion ist veraltet und sollte nicht verwendet werden. Verwenden Sie stattdessen ConfigurePortUI .

ConfigurePort ist eine Portverwaltungsfunktion, die den angegebenen Port konfiguriert.

pfnDeletePort

Achtung

Die DeletePort-Funktion ist veraltet und sollte nicht verwendet werden.

DeletePort löscht einen Port aus der Umgebung des Monitors.

pfnGetPrinterDataFromPort

Die GetPrinterDataFromPort-Funktion eines Portmonitors ruft status Informationen von einem bidirektionalen Drucker ab und gibt sie an den Aufrufer zurück.

pfnSetPortTimeOuts

Die Funktion einer Portmonitorserver-DLL SetPortTimeOuts legt Porttimeoutwerte für einen offenen Port fest.

pfnXcvOpenPort

Zeiger auf die XcvOpenPort-Funktion des Druckmonitors. (Nur Portmonitore.)

pfnXcvDataPort

Zeiger auf die XcvDataPort-Funktion des Druckmonitors. (Nur Portmonitore.)

pfnXcvClosePort

Zeiger auf die XcvClosePort-Funktion des Druckmonitors. (Nur Portmonitore.)

Hinweise

In den folgenden Abschnitten werden die einzelnen Rückrufmember ausführlicher beschrieben.

AddPort

typedef BOOL (WINAPI *pfnAddPort)(
  _In_ HANDLE hMonitor,
  _In_ LPWSTR pName,
  _In_ HWND   hWnd,
  _In_ LPWSTR pMonitorName
);

Parameter (AddPort)

Überwachen [in] (AddPort)

Vom Aufrufer bereitgestellter Monitor instance Handle. Dies ist das Handle, das von der InitializePrintMonitor2-Funktion des Monitors zurückgegeben wird. (Dieser Parameter ist nicht vorhanden, wenn der Druckmonitor InitializePrintMonitor2 anstelle von InitializePrintMonitor2 unterstützt.)

pName [in] (AddPort)

Zeiger auf eine NULL-Zeichenfolge, die den Namen des Servers angibt, mit dem der Port verbunden ist. Wenn pName NULL ist, ist der Port lokal.

hWnd [in] (AddPort)

Handle mit dem übergeordneten Fenster des Dialogfelds, in dem der Portname eingegeben wird.

pMonitorName [in] (AddPort)

Zeiger auf eine null-beendete Zeichenfolge, die den dem Port zugeordneten Monitor angibt.

Rückgabewert (AddPort)

Der Rückgabewert ist TRUE, wenn die Funktion erfolgreich ist, andernfalls FALSE.

ConfigurePort

typedef BOOL (WINAPI *pfnConfigurePort)(
  _In_ HANDLE hMonitor,
  _In_ LPWSTR pName,
  _In_ HWND   hWnd,
  _In_ LPWSTR pPortName
);

Parameter (ConfigurePort)

hMonitor [in] (ConfigurePort)

Vom Aufrufer bereitgestellter Monitor instance Handle. Dies ist das Handle, das von der InitializePrintMonitor2-Funktion des Monitors zurückgegeben wird. (Dieser Parameter ist nicht vorhanden, wenn der Druckmonitor InitializePrintMonitor anstelle von InitializePrintMonitor2 unterstützt.)

pName [in] (ConfigurePort)

Zeiger auf eine NULL-Zeichenfolge, die den Namen des Servers angibt, auf dem sich der angegebene Port befindet. Wenn diese Zeichenfolge NULL ist, ist der Port lokal.

hWnd [in] (ConfigurePort)

Handle mit dem übergeordneten Fenster des Dialogfelds, in dem die Konfigurationsinformationen eingegeben werden.

pPortName [in] (ConfigurePort)

Zeiger auf eine NULL-Zeichenfolge, die den Namen des zu konfigurierenden Ports angibt.

Rückgabewert (ConfigurePort)

Der Rückgabewert ist TRUE, wenn die Funktion erfolgreich ist.

DeletePort

pfnDeletePort DeletePort;

BOOL WINAPI DeletePort(
  _In_ HANDLE hMonitor,
  _In_ LPWSTR pName,
  _In_ HWND   hWnd,
  _In_ LPWSTR pPortName
)

Parameter (DeletePort)

hMonitor [in] (DeletePort)

Vom Aufrufer bereitgestellter Monitor instance Handle. Dies ist das Handle, das von der InitializePrintMonitor2-Funktion des Monitors zurückgegeben wird. (Dieser Parameter ist nicht vorhanden, wenn der Druckmonitor InitializePrintMonitor anstelle von InitializePrintMonitor2 unterstützt.)

pName [in] (DeletePort)

Zeiger auf eine NULL-Zeichenfolge, die den Namen des Servers angibt, auf dem der zu löschende Port vorhanden ist. Wenn dieser Parameter NULL ist, ist der Port lokal.

hWnd [in] (DeletePort)

Handle mit dem übergeordneten Fenster des Dialogfelds zum Löschen von Ports.

pPortName [in] (DeletePort)

Zeiger auf eine NULL-beendete Zeichenfolge, die den zu löschenden Port benennt.

Rückgabewert (DeletePort)

Der Rückgabewert ist TRUE, wenn die Funktion erfolgreich ist.

EndDocPort

typedef BOOL ( WINAPI *pfnEndDocPort)(
  _In_ HANDLE hPort
);

Parameter (EndDocPort)

hPort [in] (EndDocPort)

Vom Aufrufer bereitgestelltes Porthandle.

Rückgabewert (EndDocPort)

Wenn der Vorgang erfolgreich ist, sollte die Funktion TRUE zurückgeben. Andernfalls sollte false zurückgegeben werden.

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
);

Parameter (EnumPorts)

hMonitor [in] (EnumPorts)

Vom Aufrufer bereitgestellter Monitor instance Handle. Dies ist das Handle, das von der InitializePrintMonitor2-Funktion des Monitors zurückgegeben wird. (Dieser Parameter ist nicht vorhanden, wenn der Druckmonitor InitializePrintMonitor anstelle von InitializePrintMonitor2 unterstützt.)

pName [in, optional] (EnumPorts)

Vom Aufrufer bereitgestellter Zeiger auf eine Zeichenfolge, die den Namen des Servers enthält, dessen Ports aufgelistet werden sollen. Ein NULL-Zeiger stellt das System dar, auf dem die Portmonitorserver-DLL ausgeführt wird.

Level [in] (EnumPorts)

Vom Aufrufer bereitgestellter Wert, der den Typ der Strukturen angibt, die im Puffer zurückgegeben werden sollen, auf den von pPorts verwiesen wird.

Mögliche Werte sind 1 (PORT_INFO_1) oder 2 (PORT_INFO_2).

pPorts [out] (EnumPorts)

Vom Aufrufer bereitgestellter Zeiger auf einen Puffer zum Empfangen von Portinformationen. Zurückgegebene Informationen müssen aus einem Array von PORT_INFO_1 - oder PORT_INFO_2-Strukturen bestehen, gefolgt von den Zeichenfolgen, auf die von Strukturmembern verwiesen wird.

cbBuf [in] (EnumPorts)

Vom Aufrufer bereitgestellte Größe des Puffers, auf den pPorts verweist, in Bytes.

pcbNeeded [out] (EnumPorts)

Vom Aufrufer bereitgestellter Zeiger auf einen Speicherort, an dem die Puffergröße in Bytes empfangen wird, die alle zurückgegebenen Informationen enthalten muss.

pcReturned [out] (EnumPorts)

Vom Aufrufer bereitgestellter Zeiger auf einen Ort, an dem die nummerumerierten Ports empfangen werden sollen.

Rückgabewert (EnumPorts)

Wenn der Vorgang erfolgreich ist, sollte die Funktion TRUE zurückgeben. Andernfalls sollte FALSE zurückgegeben werden.

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
)

Parameters (GetPrinterDataFromPort)

hPort [in] (GetPrinterDataFromPort)

Vom Aufrufer bereitgestelltes Porthandle.

ControlID [in] (GetPrinterDataFromPort)

Vom Aufrufer bereitgestellter Geräte-E/A-Steuerungscode. Der Wert 0 (null) gibt an, dass ein Wertname von pValueName angegeben wird.

pValueName [in] (GetPrinterDataFromPort)

Vom Aufrufer bereitgestellter Zeiger auf eine Zeichenfolge, die die angeforderten Informationen identifiziert. Nur gültig, wenn ControlID 0 ist.

lpInBuffer [in] (GetPrinterDataFromPort)

Vom Aufrufer bereitgestellter Zeiger auf einen Puffer, der Eingabedaten enthält. Wird nur verwendet, wenn ControlID ungleich null ist.

cbInBuffer [in] (GetPrinterDataFromPort)

Vom Aufrufer bereitgestellte Größe des Puffers, auf den lpInBuffer verweist, in Bytes.

lpOutBuffer [out] (GetPrinterDataFromPort)

Vom Aufrufer bereitgestellter Zeiger auf einen Puffer zum Empfangen der angeforderten Daten.

cbOutBuffer [in] (GetPrinterDataFromPort)

Vom Aufrufer bereitgestellte Größe des Puffers, auf den lpOutBuffer verweist, in Bytes.

lpcbReturned [out] (GetPrinterDataFromPort)

Vom Aufrufer bereitgestellter Zeiger auf einen Speicherort, an dem die Anzahl der Bytes empfangen werden soll, die in den Puffer geschrieben werden, auf den lpOutBuffer verweist.

Rückgabewert (GetPrinterDataFromPort)

Wenn der Vorgang erfolgreich ist, sollte die Funktion TRUE zurückgeben. Andernfalls sollte FALSE zurückgegeben werden.

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
)

Parameter (OpenPortEx)

hMonitor [in] (OpenPortEx)

Vom Aufrufer bereitgestellter Sprachmonitor instance Handle. Dies ist das Handle, das von der InitializePrintMonitor2-Funktion des Monitors zurückgegeben wird. (Dieser Parameter ist nicht vorhanden, wenn der Druckmonitor InitializePrintMonitor anstelle von InitializePrintMonitor2 unterstützt.) In einer Clusterumgebung können mehrere Instanzen von Sprachmonitoren vorhanden sein.

hMonitorPort [in] (OpenPortEx)

Vom Aufrufer bereitgestellter Portmonitor instance Handle. Dies ist das Handle, das von der InitializePrintMonitor2-Funktion des Monitors zurückgegeben wird. (Dieser Parameter ist nicht vorhanden, wenn der Druckmonitor InitializePrintMonitor anstelle von InitializePrintMonitor2 unterstützt.) Ein Sprachmonitor muss dieses Handle verwenden, wenn er Funktionen in der MONITOR2 Struktur des Portmonitors aufruft.

pPortName [in] (OpenPortEx)

Vom Aufrufer bereitgestellter Zeiger auf eine Zeichenfolge, die den Namen des zu öffnenden Ports enthält.

pPrinterName [in] (OpenPortEx)

Vom Aufrufer bereitgestellter Zeiger auf eine Zeichenfolge, die den Namen des Druckers enthält, der mit dem Port verbunden ist.

pHandle [out] (OpenPortEx)

Vom Aufrufer bereitgestellter Zeiger auf einen Ort, an dem ein Porthandle empfangen werden soll.

pMonitor [in] (OpenPortEx)

Vom Aufrufer bereitgestellter Zeiger auf die MONITOR2 Struktur, die von der InitializePrintMonitor2-Funktion eines Portmonitors zurückgegeben wird.

Rückgabewert (OpenPortEx)

Wenn der Vorgang erfolgreich ist, sollte die Funktion TRUE zurückgeben. Andernfalls sollte FALSE zurückgegeben werden.

SetPortTimeOuts

BOOL (WINAPI *pfnSetPortTimeOuts)
    (
    _In_ HANDLE  hPort,
    _In_ LPCOMMTIMEOUTS lpCTO,
    _In_ DWORD   reserved    // must be set to 0
    );

Parameter (SetPortTimeOuts)

hPort [in] (SetPortTimeOuts)

Vom Aufrufer bereitgestelltes Handle für den geöffneten Port, an dem die Timeoutwerte festgelegt werden sollen.

lpCTO [in] (SetPortTimeOuts)

Vom Aufrufer bereitgestellter Zeiger auf eine COMMTIMEOUTS-Struktur .

reserved [in] (SetPortTimeOuts)

Für die zukünftige Verwendung reserviert. Muss auf 0 (null) festgelegt werden.

Rückgabewert (SetPortTimeOuts)

Wenn der Vorgang erfolgreich ist, sollte die Funktion TRUE zurückgeben. Andernfalls sollte FALSE zurückgegeben werden.

StartDocPort

typedef BOOL (WINAPI *pfnStartDocPort)(
  _In_ HANDLE hPort,
  _In_ LPWSTR pPrinterName,
  _In_ DWORD  JobId,
  _In_ DWORD  Level,
  _In_ LPBYTE pDocInfo
);

Parameter (StartDocPort)

hPort [in] (StartDocPort)

Vom Aufrufer bereitgestelltes Porthandle.

pPrinterName [in] (StartDocPort)

Vom Aufrufer bereitgestellter Zeiger auf eine Zeichenfolge, die den Druckernamen enthält.

JobId [in] (StartDocPort)

Vom Aufrufer bereitgestellte, vom Spooler zugewiesene Auftragsbezeichner.

Ebene [in] (StartDocPort)

Vom Aufrufer bereitgestellter Wert, der den Typ der Struktur angibt, auf die pDocInfo verweist.

Mögliche Werte sind 1 (DOC_INFO_1) oder 2 (DOC_INFO_2).

pDocInfo [in] (StartDocPort)

Vom Aufrufer bereitgestellter Zeiger auf eine DOC_INFO_1- oder DOC_INFO_2 struktur.

Rückgabewert (StartDocPort)

Wenn der Vorgang erfolgreich ist, sollte die Funktion TRUE zurückgeben. Andernfalls sollte FALSE zurückgegeben werden.

Hinweise

Der Spooler ruft AddPort auf, wenn er eine Anwendungsanforderung empfängt, um seiner Umgebung einen Port hinzuzufügen. Der Spooler leitet den Aufruf an den benannten Portmonitor auf dem benannten Server weiter.

AddPort ermöglicht das interaktive Hinzufügen eines Ports. Ein Monitor sollte einen Benutzer auffordern, den Portnamen in einem Dialogfeld in dem Fenster einzugeben, das hWnd zugeordnet ist. AddPort sollte den eingegebenen Portnamen überprüfen, indem die Win32 EnumPorts-Funktion aufgerufen wird, um sicherzustellen, dass der Spoolerumgebung keine doppelten Portnamen hinzugefügt werden. Ein Monitor sollte auch überprüfen, ob der Port unterstützt wird.

Der Spooler unterstützt keine AddPort-Remoteaufrufe . Daher können AddPort-Implementierungen die Parameter pName und pMonitorName ignorieren.

Der Spooler ruft ConfigurePort auf, damit ein Portmonitor die Portkonfiguration ausführen kann. ConfigurePort kann ein Dialogfeld zum Abrufen einiger oder aller erforderlichen Portkonfigurationsinformationen vom Benutzer bieten.

Der Spooler unterstützt keine ConfigurePort-Remoteaufrufe . Daher können Monitore den pName-Parameter ignorieren.

Der Spooler ruft DeletePort auf, damit ein Portmonitor einen Port aus der Umgebung des Monitors löschen kann. Der Monitor sollte den angegebenen Port aus seinem Zustand löschen. Der Spooler ruft DeletePort nicht auf einem Monitor auf, solange ein Port geöffnet ist.

Anwendungen können lokale und Remoteports löschen. Auf der Drucker-Benutzeroberfläche wird ein Bestätigungsmeldungsfeld angezeigt, bevor der Spooler DeletePort aufruft. Daher sollte ein Monitor den hWnd-Parameter ignorieren und kein weiteres Dialogfeld anzeigen.

Sprachmonitore und Portmonitorserver-DLLs sind erforderlich, um eine EndDocPort-Funktion zu definieren und die Adresse der Funktion in eine MONITOR2-Struktur aufzunehmen.

Das Handle, das als hPort-Argument der Funktion empfangen wird, ist das Porthandle, das die OpenPort - oder OpenPortEx-Funktion des Monitors bereitgestellt hat.

Die EndDocPort-Funktion eines Sprachmonitors ruft in der Regel die EndDocPort-Funktion des zugeordneten Portmonitors auf. Darüber hinaus sollte der Spooler benachrichtigt werden, wenn das Druckgerät den Auftrag abgeschlossen hat, indem SetJob aufgerufen und ein Befehl JOB_CONTROL_LAST_PAGE_EJECTED angegeben wird. Sprachmonitore für bidirektionale Drucker sollten SetJob erst aufrufen, wenn der Drucker eine Benachrichtigung gesendet hat, dass der Auftrag wirklich abgeschlossen ist.

Die EndDocPort-Funktion einer Portmonitorserver-DLL ruft in der Regel die CloseHandle-Funktion auf, um das Handle zu schließen, das zuvor durch Aufrufen von CreateFile aus StartDocPort abgerufen wurde. Außerdem sollte der Spooler benachrichtigt werden, wenn das Druckgerät den Auftrag abgeschlossen hat, indem SetJob aufgerufen und ein Befehl JOB_CONTROL_SENT_TO_PRINTER angegeben wird. (Wenn ein Spooler über einen Sprachmonitor mit dem Port kommuniziert, gilt der Auftrag erst als abgeschlossen, wenn der Sprachmonitor JOB_CONTROL_LAST_PAGE_EJECTED sendet.)

Die EndDocPort-Funktion sollte alle Ressourcen freigeben, die von der StartDocPort-Funktion zugewiesen wurden.

Sie können das Verhalten der EndDocPort-Funktion ändern, wenn der Benutzer den Druckauftrag gelöscht oder neu gestartet hat. Die Funktion kann GetJob aufrufen und nach einer status von JOB_STATUS_DELETING oder JOB_STATUS_RESTART suchen, um festzustellen, ob eines dieser Ereignisse aufgetreten ist.

Portmonitorserver-DLLs sind erforderlich, um eine EnumPorts-Funktion zu definieren und die Adresse der Funktion in eine MONITOR2-Struktur einzuschließen. Sprachmonitore exportieren diese Funktion nicht.

Der Zweck der EnumPorts-Funktion besteht darin, die Ports aufzulisten, die derzeit von einem Druckmonitor unterstützt werden. Diese Ports wurden zuvor für die AddPortUI- oder AddPortEx-Funktion des Monitors angegeben.

Die EnumPorts-Funktion sollte den Puffer, auf den pPort verweist, mit einem Array von PORT_INFO_1- oder PORT_INFO_2-Strukturen füllen. Ab einem Speicherspeicherort nach dem letzten Arrayelement muss die Funktion dann alle Zeichenfolgen laden, auf die die Strukturelemente des Arrays verweisen. Ein Beispiel dafür finden Sie in localmon.dll, einem Beispielportmonitor. Die Funktion muss auch die Anzahl der bereitgestellten Strukturen zurückgeben (d. h. die Anzahl der unterstützten Ports), indem die Zahl an der Position platziert wird, auf die von pcReturned verwiesen wird.

Der Aufrufer gibt die Größe des bereitgestellten Puffers in cbBuf an. Wenn der Puffer zu klein ist, sollte die Funktion die erforderliche Puffergröße an der Position platzieren, auf die von pcbNeed verwiesen wird, SetLastError aufrufen, ERROR_INSUFFICIENT_BUFFER angeben, und FALSE zurückgeben.

Wenn Level eine ungültige Levelnummer enthält, sollte die Funktion SetLastError aufrufen und ERROR_INVALID_LEVEL angeben und FALSE zurückgeben. Einige Portmonitore unterstützen nur den Levelwert 1.

Der Portmonitor muss die Lokalisierung von Zeichenfolgen unterstützen, auf die von den pMonitorName - und pDescription-Membern der PORT_INFO_2-Struktur verwiesen wird. Diese Zeichenfolgen sollten in Ressourcendateien definiert und durch Aufrufen von LoadString abgerufen werden.

Das fPortType-Element der PORT_INFO_2-Struktur wird bei NT-basierten Betriebssystemen nicht verwendet.

Sprachmonitore und Portmonitorserver-DLLs können optional eine GetPrinterDataFromPort-Funktion definieren und die Adresse der Funktion in eine MONITOR2-Struktur einschließen.

Die Funktion ist für die Verwendung mit bidirektionalen Druckern vorgesehen und kann auf die folgenden beiden Arten verwendet werden:

  • Als Mittel zum Anfordern eines Sprachmonitors zum Abfragen des Druckerports, um den aktuellen Wert der druckerspezifischen Informationen abzurufen, die in der Registrierung gespeichert sind.

  • Als Mittel zum Anfordern eines Portmonitors zum Senden eines E/A-Steuerungscodes an den Porttreiber.

Wenn die GetPrinterDataFromPort-Funktion eines Sprachmonitors einen Zeichenfolgenzeiger in pValueName empfängt, sollte ein Wert im angegebenen Ausgabepuffer zurückgegeben werden. In der Regel stellt die Zeichenfolge einen Registrierungswertnamen dar, und der Spooler ruft GetPrinterDataFromPort auf, wenn eine Anwendung die GetPrinterData-Funktion aufruft .

Die Verantwortung des Sprachmonitors besteht darin, einen Befehl an die Druckerhardware zu senden, indem die WritePort-Funktion des Portmonitors aufgerufen und die Antwort durch Aufrufen von ReadPort gelesen wird, um den erforderlichen Wert abzurufen. Beispielsweise kann pjlmon.dll, der Beispielsprachmonitor, Werte für die Registrierungswertnamen "Installierter Arbeitsspeicher" und "Verfügbarer Arbeitsspeicher" eines Ports zurückgeben.

Nachdem der Spooler GetPrinterDataFromPort aufgerufen hat, um einen Registrierungswert abzurufen, aktualisiert er die Registrierung mit dem neuen Wert.

Portmonitore unterstützen in der Regel keine Aufrufe von GetPrinterDataFromPort , die einen Zeichenfolgenzeiger in pValueName enthalten.

Wenn die GetPrinterDataFromPort-Funktion eines Sprachmonitors einen nichtzero-E/A-Steuerelementcode in ControlID empfängt, sollte sie einfach die GetPrinterDataFromPort-Funktion des zugehörigen Portmonitors aufrufen und das Ergebnis zurückgeben. Die Referenz zu Kernelmodustreibern listet E/A-Steuercodes für parallele und serielle Ports auf.

Wenn die GetPrinterDataFromPort-Funktion eines Portmonitors einen nichtzero-E/A-Steuerelementcode in ControlID empfängt, sollte DeviceIOControl aufgerufen werden, um den Steuerungscode an den Kernelmodusporttreiber zu übergeben. Die Parameterwerte lpInBuffer, cbInBuffer, lpOutBuffer, cbOutBuffer und lpcbReturned sollten ebenfalls an DeviceIOControl übergeben werden.

Sprachmonitore sind erforderlich, um eine OpenPortEx Funktion zu definieren und deren Adresse in eine MONITOR2-Struktur aufzunehmen. Die OpenPortEx Funktion wird vom Druckspooler aufgerufen, wenn eine Druckwarteschlange mit einem Port verbunden ist.

Der OpenPortEx Hauptzweck der Funktion besteht darin, ein Porthandle zurückzugeben, das der Aufrufer als Eingabeargument für nachfolgende Aufrufe der Funktionen StartDocPort, WritePort, ReadPort, EndDocPort und GetPrinterDataFromPort des Sprachmonitors verwenden kann. Da ein Sprachmonitor diese Funktionen in der Regel durch Aufruf der entsprechenden Funktionen im zugehörigen Portmonitor implementiert, ruft ein Sprachmonitor in der Regel ein Porthandle ab, indem die OpenPort-Funktion des Portmonitors aufgerufen wird. Weitere Informationen finden Sie unter Sprach- und Portmonitorinteraktion.

Der OpenPortExpMonitor-Parameter der Funktion ist ein Zeiger auf die MONITOR2 Struktur des Portmonitors. Diese Struktur enthält Zeiger auf die aufrufbaren Funktionen des Portmonitors. Die OpenPortEx Funktion sollte die Struktur überprüfen, um sicherzustellen, dass alle erforderlichen Funktionszeiger nicht NULL sind. Wenn die Struktur gültig ist, sollte sie von der Funktion in den lokalen Speicher kopiert werden. Andernfalls OpenPortEx sollte SetLastError aufgerufen werden, ERROR_INVALID_PRINT_MONITOR angeben und FALSE zurückgeben.

Drucküberwachungsfunktionen, die ein Porthandle als Eingabe akzeptieren, akzeptieren nicht auch ein Monitorhandle. Daher muss die Funktion das OpenPortEx empfangene Monitorhandle an einer Position speichern, auf die vom Porthandle verwiesen werden kann. Dadurch können die Funktionen, die ein Porthandle akzeptieren, auf das Monitorhandle verweisen.

Die Funktion einer SetPortTimeOuts Portmonitorserver-DLL ermöglicht es einem Sprachmonitor, Porttimeoutwerte für einen offenen Port anzugeben. Die Funktion ist optional und muss nur bereitgestellt werden, wenn der Portmonitor einen Port steuert, der die Änderung von Porttimeoutwerten zulässt. Wenn die Funktion definiert ist, muss ihre Adresse in einer MONITOR2-Struktur enthalten sein.

Die Funktion wird von pjlmon.dll aufgerufen, dem Beispielsprachmonitor, und Sie können einen benutzerdefinierten Sprachmonitor schreiben, der sie aufruft. Der Druckspooler ruft nicht auf SetPortTimeOuts.

Der Portmonitor sollte die Timeoutwerte des Ports in seiner OpenPort-Funktion initialisieren.

Sprachmonitore und Portmonitorserver-DLLs sind erforderlich, um eine StartDocPort Funktion zu definieren und die Adresse der Funktion in eine MONITOR2-Struktur aufzunehmen.

Das Handle, das als hPort-Argument der Funktion empfangen wird, ist das Porthandle, das die OpenPort - oder OpenPortEx-Funktion des Monitors bereitgestellt hat.

Die Funktion eines Sprachmonitors StartDocPort ruft in der Regel die Funktion des zugeordneten Portmonitors StartDocPort auf.

Die Funktion einer StartDocPort Portmonitorserver-DLL ruft in der Regel die CreateFile-Funktion auf, um eine Verbindung mit dem Kernelmodus-Porttreiber herzustellen.

Bei Bedarf sollte der Portmonitor verhindern, dass andere Prozesse den angegebenen Port verwenden, bis EndDocPort aufgerufen wird. Beispielsweise muss ein Portmonitor für einen COM-Port sicherstellen, dass während ein Spooler Druckerdaten an den Port sendet, eine andere Anwendung nicht davon ausgeht, dass der Port mit einem bestimmten Kommunikationsgerät verbunden ist, und dann versucht, mit diesem Gerät zu kommunizieren. Dieser warnende Hinweis gilt nicht für den lokalen Druckanbieter, der garantiert, dass er nie zweimal hintereinander aufruft StartDocPort , ohne einen dazwischenliegenden Anruf bei EndDocPort, aber er gilt für Druckanbieter, die diese Garantie nicht übernehmen.

Anforderungen

Anforderung Wert
Header winsplp.h (einschließlich Winsplp.h)

Weitere Informationen

MONITOR2

MONITORUI