JavaScript-API-Referenz
Wichtig
Die Modern Print-Plattform ist die von Windows bevorzugte Methode zur Kommunikation mit Druckern. Wir empfehlen die Verwendung des Microsoft IPP-Treibers für die Posteingangsklasse zusammen mit Print Support Apps (PSA), um das Druckverhalten in Windows 10 und 11 für die Entwicklung von Druckergeräten anzupassen.
Weitere Informationen finden Sie unter Modern Print-Plattform und der Anleitung zum Design der Print-Support-App.
Hersteller können die hier vorgestellte JavaScript-API in Kombination mit einer Bidi-XML-Datei verwenden, um Unterstützung für Bidi über eine USB-Verbindung zu einem Gerät bereitzustellen.
Weitere Informationen über die USB Bidi-Kommunikation mit einem Druckgerät finden Sie unter USB Bidi Extender.
Bidi über USB
getSchemas-Methode
Diese Methode behandelt Bidi-GET-Abfragen wie z. B. \Printer.Consumables.YellowInk:Level. Der JavaScript-Code ist in der Lage, Abfragen an den Drucker über den USB-Bus zu stellen und die Antworten zu lesen, sobald sie zurückkommen.
Syntax
function getSchemas(scriptContext, printerStream, schemaRequests, printerBidiSchemaResponses);
Parameter (getSchemas-Methode)
scriptContext [in] Ein IPrinterScriptContext-Objekt, das den Zugriff auf relevante Property Bags ermöglicht. printerStream
[in] Ein IPrinterScriptableSequentialStream-Objekt, das Lese- und Schreibzugriff auf den USB-Bus bietet. schemaRequests
[in] Array-Objekt, das alle angefragten Zeichenfolgen der Bidi-Abfrage enthält. printerBidiSchemaResponses
[out] Objekt, das das Skript verwendet, um alle Antworten auf Abfragen zu speichern.
Rückgabewerte (Methode getSchemas)
| Rückgabewert | BESCHREIBUNG |
|---|---|
| 0 | Das Skript wurde erfolgreich abgeschlossen. |
| 1 | Das angeschlossene Gerät war nicht bereit, einige angefragte Informationen zu liefern. Zeigt an, dass das Drucksystem die Funktion unter Verwendung der während der Verarbeitung hinzugefügten Requery-Keys erneut aufrufen sollte. |
setSchema-Methode
Diese Methode verarbeitet Bidi-SET-Vorgänge. Das Skript kann den eingehenden Bidi-Schema-Wert ermitteln, um entweder Daten im Gerät festzulegen oder eine Aktion auf dem Gerät durchzuführen, wie z. B. das Reinigen von Tintenköpfen.
Wenn das Gerät nicht bereit ist, die angegebenen Daten zu verarbeiten, kann die Methode den Wert 1 zurückgeben, um anzuzeigen, dass der Aufruf nach einer Wartezeit erneut versucht werden soll.
Parameter (setSchema-Methode)
scriptContext [in] Ein IPrinterScriptContext-Objekt, das den Zugriff auf relevante Property Bags ermöglicht. printerStream
[in] Ein IPrinterScriptableSequentialStream-Objekt, das Lese- und Schreibzugriff auf den USB-Bus bietet. printerBidiSchemaElement
[in] Ein IPrinterBidiSchemaElement-Objekt, das alle Daten enthält, die mit dem festzulegenden Bidi-Schema-Wert verbunden sind.
Rückgabewerte (Methode setSchema)
| Rückgabewert | BESCHREIBUNG |
|---|---|
| 0 | Das Skript wurde erfolgreich abgeschlossen. |
| 1 | Das angeschlossene Gerät war nicht bereit, einige angefragte Informationen zu liefern. Zeigt an, dass das Drucksystem die Funktion unter Verwendung des übergebenen printerBidiSchemaElements erneut aufrufen soll. |
getStatus-Methode
Diese Methode wird verwendet, um unaufgefordert den Status eines Druckers abzurufen, während das Gerät druckt. Diese Funktion wird nur während des Druckens aufgerufen. Das Gerät sollte über den Lesekanal Daten bereitstellen, die dieses Skript in Bidi-Schema-Werte interpretieren kann. Da der Schreibkanal zum Gerät durch Druckdaten blockiert ist, wird hier nur der unaufgeforderte Status unterstützt.
Diese Methode wird während des Druckens wiederholt aufgerufen. Es wird erwartet, dass das Gerät nur dann Daten zurückgibt, wenn sie verfügbar sind und das Skript sie verstehen kann. Wenn das Gerät keinen unaufgeforderten Status unterstützt oder es keine Notwendigkeit gibt, diese Funktion erneut aufzurufen, sollte das Skript einen Wert von 2 zurückgeben, der dem getStatus-Ausführungsthread in USBMon mitteilt, dass er erfolgreich beendet wurde.
Parameter (getStatus-Methode)
scriptContext [in] Ein IPrinterScriptContext-Objekt, das den Zugriff auf relevante Property-Bags ermöglicht. printerStream
[in] Ein IPrinterScriptableSequentialStream-Objekt, das Lesezugriff auf den USB-Bus bietet. printerBidiSchemaResponses
[out] Objekt, das das Skript verwendet, um alle Antworten auf Abfragen zu speichern.
Rückgabewerte (Methode getStatus)
| Rückgabewert | BESCHREIBUNG |
|---|---|
| 0 | Das Skript wurde erfolgreich abgeschlossen. |
| 2 | Das angeschlossene Gerät unterstützt nicht mehr den unaufgeforderten Status und diese Funktion sollte nicht mehr aufgerufen werden. |
startPrintJob-Methode
USBMon ruft diese Methode während StartDocPort auf. Der Aufruf von startPrintJob bietet dem Treiber die Möglichkeit, den Druck-Stream zu ändern oder ein Host-basiertes Anfrage/Antwort-Protokoll zu implementieren, das verwendet wird, während das Gerät einen Auftrag druckt. Das Auftragskontextobjekt wird an die Funktion übergeben, um dem JavaScript-Code des Herstellers die Möglichkeit zu bieten, Jobeigenschaften zu verwalten und Zugriff auf die persistenten Datenströme zu erhalten. Die Druckdaten werden als JavaScript-Array übergeben, damit der JavaScript-Code sie verarbeiten kann. startPrintJob ermöglicht außerdem den Zugriff auf das Gerät des Druckers auf die folgenden Arten:
Über den Druck-Stream
Über ein Objekt, das Bidi-Schema-Antworten für USBMon zur Verarbeitung zurückgeben kann
Syntax (Methode startPrintJob)
function startPrintJob(jobScriptContext, printerStream, printerBidiSchemaResponses);
Parameter (startPrintJob-Methode)
jobScriptContext [in] Ein IPrinterScriptUsbJobContext-Objekt, das dem JavaScript-Code des Herstellers Zugriff auf die Job-Eigenschaft bag und die persistenten Datenströme gibt. printerStream
[in] Ein IPrinterScriptableSequentialStream-Objekt, das der JavaScript-Code des Herstellers zum Lesen und Schreiben von Daten auf dem Gerät verwenden kann. printerBidiSchemaResponses
[out] Ein IPrinterBidiSchemaResponses-Objekt, das der JavaScript-Code des Herstellers verwenden kann, um alle Änderungen/Aktualisierungen von Bidi Schema-Werten zurückzugeben.
Rückgabewerte (Methode startPrintJob)
| Rückgabewert | BESCHREIBUNG |
|---|---|
| 0 | Erfolg. |
| 1 | Failure – Bereinigen Sie das Job Context-Objekt und geben Sie einen Fehlercode an den Druck-Spooler zurück. |
writePrintData-Methode
USBMon ruft diese Methode während writePort auf. Der Aufruf von writePrintData bietet dem Treiber die Möglichkeit, den Druck-Stream zu ändern oder ein Host-basiertes Anfrage/Antwort-Protokoll zu implementieren, das verwendet wird, während das Gerät einen Auftrag druckt. Das Auftragskontextobjekt wird an die Methode übergeben, um dem JavaScript-Code des Herstellers die Möglichkeit zu bieten, Jobeigenschaften zu verwalten und Zugriff auf die persistenten Datenströme zu erhalten. Die Druckdaten werden als JavaScript-Array übergeben, damit der JavaScript-Code sie verarbeiten kann. writePrintData ermöglicht außerdem den Zugriff auf das Gerät des Druckers auf folgende Weise:
Über den Druck-Stream
Über ein Objekt, das Bidi-Schema-Antworten für USBMon zur Verarbeitung zurückgeben kann
function writePrintData(jobScriptContext, writePrintDataProgress, printData, printerStream, printerBidiSchemaResponses);
Parameter (writePrintData-Methode)
jobScriptContext [in] Ein IPrinterScriptUsbJobContext-Objekt, das dem JavaScript-Code des Herstellers Zugriff auf die Jobeigenschaften und die persistenten Datenströme gibt. writePrintDataProgress
[in] Ein IPrinterScriptableSequentialStream-Objekt, das der JavaScript-Code des Herstellers zum Lesen und Schreiben von Daten auf dem Gerät verwenden kann. printData
[in] Ein IDispatch-Objekt, ein JavaScript-Array mit den aktuellen Druckdaten. Der Parameter printData bietet dem JavaScript-Code die Möglichkeit, die Daten zu manipulieren, bevor er sie entweder in einem der Datenströme in jobScriptContext zwischenspeichert oder sie über printerStream an den Drucker sendet. printerStream
[in] Ein IPrinterScriptableSequentialStream-Objekt, das der JavaScript-Code des Herstellers zum Lesen und Schreiben von Daten auf dem Gerät verwenden kann. printerBidiSchemaResponses
[out] Ein IPrinterBidiSchemaResponses-Objekt, das der JavaScript-Code des Herstellers verwenden kann, um alle Änderungen oder Aktualisierungen von Bidi-Schema-Werten zurückzugeben.
Rückgabewerte (Methode writePrintData)
| Rückgabewert | BESCHREIBUNG |
|---|---|
| 0 | Erfolg. Die Anzahl der verarbeiteten Bytes aus dem Druck-Daten-Stream (printData) wird über writePrintDataProgress zurückgegeben. |
| 1 | Failure – Rückgabe eines Fehlercodes an den Druck-Spooler. |
| 2 | Retry – Verarbeitet alle Bidi-Schema-Updates (einschließlich Bidi-Ereignisse) in printerBidiSchemaResponses und ruft dann die JavaScript-Funktion erneut auf, um dem Code des Herstellers die Möglichkeit zu geben, die Daten weiter zu verarbeiten. Die Anzahl der verarbeiteten Bytes aus dem Druck-Daten-Stream (printData) wird über writePrintDataProgress zurückgegeben. |
| 3 | DeviceBusy – Der Kommunikationskanal des Geräts nimmt zur Zeit keine Daten entgegen. Dies ist kein Hinweis auf einen Fehler. USBMon sollte den Spooler darüber informieren, dass das Gerät beschäftigt ist, und die Funktion zu einem späteren Zeitpunkt erneut aufrufen. Die Anzahl der verarbeiteten Bytes aus dem Druck-Daten-Stream (printData) wird über writePrintDataProgress zurückgegeben. |
| 4 | AbortTheJob – Das Gerät kann den Auftrag nicht weiter verarbeiten, oder der Benutzer hat den Auftrag über das Bedienfeld des Druckgeräts abgebrochen. Wenn USBMon die Nachricht zum Abbruch eines Druckauftrags erhält, gibt es die Information an den Druck-Spooler weiter, um den Auftrag abzubrechen, bevor es zurückkehrt. |
endPrintJob-Methode
USBMon ruft diese Methode während endDocPort auf. Der Aufruf von endPrintJob bietet dem Treiber die Möglichkeit, den Druck-Stream zu ändern oder ein Host-basiertes Anfrage/Antwort-Protokoll zu implementieren, das verwendet wird, während das Gerät einen Auftrag druckt. Das Jobkontext-Objekt wird an die Methode übergeben, um dem JavaScript Code des Herstellers die Möglichkeit zu bieten:
Abschließen der Verarbeitung aller Druckdaten, die bestehen geblieben sind
über den Druck-Stream auf das Gerät zuzugreifen
Zugriff auf ein Objekt, das Bidi-Schema-Antworten für die Verarbeitung durch USBMon übergeben kann
function endPrintJob(jobScriptContext, printerStream, printerBidiSchemaResponses);
Parameter (endPrintJob-Methode)
jobScriptContext [in] Ein IPrinterScriptUsbJobContext-Objekt, das dem JavaScript-Code des Herstellers Zugriff auf die Jobeigenschaft bag und die persistenten Datenströme gibt. printerStream
[in] Ein IPrinterScriptableSequentialStream-Objekt, das der JavaScript-Code des Herstellers zum Lesen und Schreiben von Daten auf dem Gerät verwenden kann. printerBidiSchemaResponses
[out] Ein IPrinterBidiSchemaResponses-Objekt, das der JavaScript-Code des Herstellers verwenden kann, um alle Änderungen oder Aktualisierungen von Bidi-Schema-Werten zurückzugeben.
Rückgabewerte (Methode endPrintJob)
| Rückgabewert | BESCHREIBUNG |
|---|---|
| 0 | Success – Bereinigt das Job Context-Objekt und gibt den Erfolg an den Druck-Spooler zurück. |
| 1 | Failure – Bereinigen Sie das Job Context-Objekt und geben Sie einen Fehlercode an den Druck-Spooler zurück. |
| 2 | Retry – Verarbeitung aller Bidi-Schema-Aktualisierungen (einschließlich Bidi-Ereignisse) in printerBidiSchemaResponses und erneuter Aufruf der JavaScript-Funktion, um dem JavaScript-Code des Herstellers die Möglichkeit zu geben, die Daten weiter zu verarbeiten. |
Bidi über sekundäres USB
Wenn das Gerät eine sekundäre USB-Schnittstelle unterstützt, kann das Gerät zusätzlich zur Methode requestStatus die in den vorangegangenen Abschnitten beschriebenen Methoden getSchemas und setSchema verwenden.
requestStatus-Methode
Diese Methode wird anstelle von getStatus aufgerufen, wenn die Direktive BidiUSBStatusInterface in der Manifestdatei des v4-Treibers angegeben wurde. requestStatus wird verwendet, um den Status von einem Gerät abzurufen, während das Gerät druckt.
Das folgende Diagramm gibt einen Überblick über die Architektur der USB-Bidi-Erweiterung und zeigt das Szenario, in dem die Direktive BidiUSBStatusInterface angegeben wurde und die Kommunikation daher über eine alternative USB-Schnittstelle geleitet wird.
Diese Methode wird während des Druckens wiederholt aufgerufen. Es wird erwartet, dass das Gerät nur dann Daten zurückgibt, wenn sie verfügbar sind und das Skript sie verstehen kann. Wenn das Gerät keine Unterstützung für den angeforderten Status bietet oder kein Bedarf besteht, diese Methode erneut aufzurufen, sollte das Skript einen Wert von 2 zurückgeben, der den Ausführungs-Thread getStatus in USBMon erfolgreich beendet.
Parameter (requestStatus-Methode)
scriptContext [in] Ein IPrinterScriptContext-Objekt, das den Zugriff auf relevante Property-Bags ermöglicht. printerStream
[in] Ein IPrinterScriptableSequentialStream-Objekt, das Lese- und Schreibzugriff auf den USB-Bus bietet. printerBidiSchemaResponses
[out] Objekt, das das Skript verwendet, um alle Antworten auf Abfragen zu speichern.
Rückgabewerte (Methode requestStatus)
| Rückgabewert | BESCHREIBUNG |
|---|---|
| 0 | Das Skript wurde erfolgreich abgeschlossen. |
| 2 | Das angeschlossene Gerät unterstützt den angeforderten Status nicht mehr und diese Funktion sollte nicht mehr aufgerufen werden. |