如何使用 Internet 打印协议(CUPS)
以上来自维基百科
为什么会有这篇文章?
起因是我需要做一个自助打印，要用到CUPS,但是国内没有对应的CUPS的API文档，在翻阅后找到一个英文网站www.pwg.org有CUPS的相关API,但是出于众所周知的原因已经被屏蔽了,所以翻译(机翻)一份放在这里,以便后来人查阅
如何使用 Internet 打印协议(CUPS)
版本 v2019.0117
作者：迈克尔·R·斯威特、彼得·泽勒
版权所有 © 2017-2019 打印机工作组。版权所有。
此处包含的材料不是对本材料的任何作者或开发者或打印机工作组拥有或控制的任何知识产权的明示或暗示许可。此处包含的材料按原样提供，并在适用法律允许的最大范围内提供，本材料按原样提供，包含所有错误，以及本材料的作者和开发者以及打印机工作组及其成员特此否认所有明示、暗示或法定的保证和条件，包括但不限于任何（如果有）暗示使用此处信息不会侵犯任何权利或任何适销性或适用性的暗示保证特殊用途。
本书 献给__Peter Zehler ，他__是__本书 的__合著__者，也是__打印机__工作__组__和__Internet__打印__协议__的__长期__贡献者。___ ___ ___ 你__很__想念。
目录
前言
什么是IPP？
Internet 打印协议 (IPP) 是用于网络打印的安全应用程序级协议。IPP 定义了高级打印机、作业和文档对象，允许客户向打印机询问功能和默认值（支持的介质尺寸、双面打印等）、打印机的状态（缺纸/卡纸、墨水不足/toner 等）以及任何打印作业及其文档。客户还可以提交文件文件进行打印，然后取消它们。所有现代网络打印机都支持 IPP，并取代所有传统网络协议，包括端口 9100 打印和 LPD/lpr。
IPP 也在软件中广泛实施，包括以下开源项目：
- 基于 C 的：CUPS和PWG IPP 示例代码
- Java：用于 IPP 的 Java 实现的Java IPP 客户端实现和核心解析器
- Javascript IPP 客户端实现
- Python IPP 客户端实现
虽然 IPP 涵盖 40 多个规范和近 2000 页，但支持大多数打印需求所需的核心协议足够小，可以在任何硬件上运行。
本文档中使用的术语
_客户端_是启动连接并向打印机发送请求的客户端设备（计算机、电话、平板电脑等）。
_打印机_是 IPP 打印机对象的一个实例，代表一个真实的或可视的打印机或打印队列。打印机侦听来自客户端的连接并维护作业列表以供处理。
_作业_是 IPP 作业对象的一个实例，代表打印机要做的工作。作业与单个打印机相关联并包含要处理的文档。
_文档_是表示文件或 URI 的 IPP 文档对象的实例。文档与单个作业相关联。
本指南的组织
本指南分为三个章节和一个附录：
- 第 1 章，IPP 概述，提供 Internet 打印协议的概述；
- 第 2 章，打印机，描述 IPP 打印机对象、它的操作和它的属性；
- 第 3 章，作业和文档，描述 IPP 作业和文档对象及其操作和属性；和
- 附录 A，快速参考，提供 IPP 操作、属性和值的摘要以及相应规范的链接。
第 1 章：IPP 概述
IPP 定义了一个用于打印的抽象模型，包括用于处理模型对象的具有通用语义（业务逻辑）的操作。因为所有打印机都遵循相同的 IPP 语义，所以客户端（软件）不需要知道打印机（硬件）的内部细节。
IPP 使用 HTTP 作为其传输协议。每个 IPP 请求都是一个 HTTP POST，在请求消息正文中带有二进制 IPP 消息和打印文件（如果有）。在 POST 响应中返回相应的 IPP 响应。HTTP 连接可以不加密，使用 HTTP OPTIONS 请求升级到 TLS 加密，或立即加密 (HTTPS)。HTTP POST 请求也可以使用任何常用的 HTTP 机制进行身份验证。
注意：传统网络协议不支持身份验证、授权或隐私（加密）。
使用ipp或ipps方案的通用资源标识符（URI）来标识打印机。打印作业使用打印机的 URI 和该打印机唯一的作业编号来标识。以下是示例打印机 URI：
ipp://printer.example.com/ipp/print
这些映射到http和https URL，IPP 的默认端口号为 631。例如，以前的 IPP URI 将映射到：
http://printer.example.com:631/ipp/print
注意：资源路径
/ipp/print通常由 IPP 打印机使用，但没有硬性要求遵循该约定，并且较旧的 IPP 打印机使用各种不同的位置。请查阅您的打印机文档或打印机的 Bonjour (DNS-SD) 注册信息，以确定用于您的打印机的正确主机名、端口号和路径。
IPP 运营
常用的 IPP 操作如下：
- Create-Job：创建一个新的（空的）打印作业。
- 发送文档：将文档添加到打印作业。
- 打印作业：使用单个文档创建新的打印作业。
- Get-Printer-Attributes：获取打印机状态和功能。
- Get-Jobs：获取排队作业的列表。
- Get-Job-Attributes：获取作业状态和选项。
- Cancel-Job：取消排队的作业。
IANA IPP Registry列出了所有已注册的 IPP 运营。
注意：IPP 提供了两种打印单个文件的方法 - 使用 Print-Job 操作或使用 Create-Job 和 Send-Document 操作的组合。IPP 实施者指南 v2.0描述了要使用的操作。
IPP 消息编码
IPP 消息对请求（从客户端到打印机）和响应（从打印机到客户端）使用通用格式。每条 IPP 消息都以版本号（最常见的是 2.0）、操作（请求）或状态（响应）代码、请求号和属性列表开头。属性被命名并具有强类型值，例如：
collection：组合在一起的键/值对列表。enum：整数枚举值，通常从 3 开始，其中每个值都有特定的含义。整数：从 -2147483648 到 2147483647 的 32 位有符号整数。keyword：小写字符串标识符，如one-sided或iso_a4_210x297mm。mimeMediaType：一种 MIME 媒体类型，如text/plain或application/pdf。name：一个人类可读的名称，例如Bob Smith。text：人类可读的字符串，例如Printer is out of paper。uri：通用资源标识符，例如https://www.example.com或ipps://printer.example.com/ipp/print。
属性也根据它们的用途被放置在组中——操作组用于操作请求或响应的属性，作业组用于打印作业属性，等等。
IPP 消息中的前两个属性始终是：
- "attributes-charset" 定义用于所有名称和文本字符串的字符集，以及
attributes-natural-language定义了这些字符串的默认语言，例如，en表示英语，fr表示法语，ja表示日语等。
下一个属性必须是打印机的 URI（printer-uri），如果请求以打印作业为目标，则必须是作业的 ID 号（job-id）。
大多数请求还包括提供用户名称的requesting-user-name属性。
包含附加打印文件的请求包括文件的 MIME 媒体类型（文档格式）。媒体类型为文本文件的text/plain，JPEG文件的image/jpeg，PDF文件的application/pdf等。
以下示例使用ipptool测试文件格式对 Print-Job 请求进行编码：
{
使用 CUPS API 的相同请求如下所示：
#include <cups/cups.h>
这就是您使用 nodejs API 发送 Print-Job 请求的方式：
var ipp = require("ipp");
响应消息使用与请求相同的版本号、请求号、字符集和自然语言值。状态代码替换初始消息头中的操作代码 - 对于 Print-Job 操作，如果打印请求成功，打印机将返回successful-ok状态代码，如果打印机返回server-error-printer-busy正忙，希望您稍后再试。
响应中的字符集和自然语言值后跟特定于操作的属性。例如，Print-Job 操作返回打印作业标识符（job-id）和状态（job-state和job-state-reasons）属性。
您可以通过阅读Internet 打印协议/1.1：编码和传输文档来了解有关 IPP 消息编码的更多信息。
第 2 章：打印机
什么是打印机？
IPP 中的打印机是代表真实或虚拟（用于保存、发送电子邮件等）输出设备的对象。打印机对象提供描述打印机_状态_（正在打印、缺纸等）、打印机_功能_（支持何种纸张尺寸、打印机能否再现颜色、打印机能否装订输出等）的属性。 ) 以及有关打印机的_一般_信息（打印机所在的位置、打印机管理网页的 URL 等）。打印机还管理打印作业队列。
打印机状态属性
打印机有两个主要的状态属性：printer-state和printer-state-reasons。printer-state属性是一个描述打印机一般状态的数字：
3：打印机空闲。4：打印机正在处理打印作业。5：打印机停止并需要注意。printer-stateidle:打印机空闲。processing:打印进行中stopped:打印机停止并需要注意
printer-state-reasons属性是提供有关打印机状态详细信息的关键字字符串列表：
none：一切都很好，没有什么可报告的。media-needed：打印机需要装入纸张。toner-low：打印机的碳粉不足。toner-empty：打印机的碳粉用完了。marker-supply-low：打印机墨水不足。marker-supply-empty：打印机墨水用完了。
该字符串还可能具有严重性后缀（-error、-warning或-report），以告知客户端原因是否影响打印作业。
注意：IANA IPP 注册表列出了
printer-state-reasons属性的所有已注册关键字字符串。所有字符串均为英文，但可以使用每台打印机提供的消息目录进行本地化。
许多打印机还提供警报（printer-alert）、耗材（printer-supply、printer-supply-description和printer-supply-info-uri）、进纸盘（printer-进纸盘）、出纸盘（打印机出纸盘）等等。
打印机功能属性
打印机具有许多功能属性，包括：
ipp-features-supported：支持的 IPP 功能列表，例如ipp-everywhere和icc-color-matching。ipp-versions-supported：支持的 IPP 版本列表，例如1.1和2.0。操作支持：受支持的 IPP 操作列表，例如 Print-Job、Create-Job、Send-Document、Cancel-Job、Get-Jobs、Get-Job-Attributes 和 Get-Printer-Attributes。charset-supported：支持的字符集列表（需要utf-8。）job-creation-attributes-supported：提交打印作业时支持的 IPP 属性列表，例如media、media-col和print-quality。document-format-supported：可以打印的文件格式列表，例如application/pdf和image/pwg-raster。media-supported和media-col-database：支持的纸张尺寸和类型的列表，例如na_letter_8.5x11in和iso_a4_210x297mm。media-ready和media-col-ready：加载的纸张尺寸和类型的列表，例如na_letter_8.5x11in和iso_a4_210x297mm。copies-supported：可以生产的最大副本数，例如99。sides-supported：支持的单面和双面打印模式列表，例如单面、双面长边和双面短边。print-quality-supported：支持的打印质量列表，例如3（草稿）、4（正常）和5（高）。print-color-mode-supported：支持的彩色打印模式列表，例如bi-level、monochrome和color。print-scaling-supported：支持的缩放模式列表，例如auto、fill和fit。printer-resolution-supported：支持的打印分辨率列表，例如300dpi和600dpi。page-ranges-supported：指定是否支持页面范围（布尔值）。finishings-supported和finishings-col-database：支持的整理过程（装订、打孔、折叠等）的列表。finishings-ready和finishings-col-ready：无需停止打印机即可请求的整理过程列表。job-password-supported、job-password-encryption-supported、job-password-repertoire-configured和job-password-repertoire-supported：支持的作业密码/可指定的 PIN 值创建作业时。
打印机信息属性
打印机有七个主要的信息属性：printer-uri-supported、uri-authentication-supported、uri-security-supported、printer-info、printer-more-info、printer-location和打印机地理位置。
printer-uri-supported属性列出了支持的打印机 URI 值。uri-authentication-supported属性列出了每个受支持的打印机 URI 值的授权和访问控制要求。同样，uri-security-supported属性列出了每个受支持的打印机 URI 值的加密要求。
printer-info属性提供打印机的文本描述，通常默认为打印机的品牌和型号。printer-more-info属性提供了打印机管理网页的 URL。
打印机位置属性提供打印机的文本位置，例如休息室附近的二楼。printer-geo-location属性提供打印机的地理位置，如果已知的话，作为geo: URI。
查询打印机属性
Get-Printer-Attributes 操作用于查询前面提到的任何打印机属性。以下示例ipptool测试文件将在打印 PWG 光栅文件时报告当前的打印机属性值：
VERSION 2.0
OPERATION Get-Printer-Attributes
注意：
requested-attributes属性列出了客户感兴趣的属性（或属性组）。printer-description组要求提供所有状态和信息属性，而job-template组要求提供所有功能属性。出于兼容性原因，需要明确请求media-col-database属性。
使用 CUPS API 的相同请求如下所示：
#include <cups/cups.h>
这就是您使用 nodejs API 查询打印机的方式：
var ipp = require("ipp");
第 3 章：作业和文档
什么是打印作业？
IPP 中的打印作业是表示打印机要完成的工作的对象，通常是打印或传真文档。打印作业提供描述作业_状态_的属性（待定、因某种原因暂停、打印、已完成等）、有关作业的_一般_ 信息（作业的所有者、名称、提交时间等）、作业 单（打印选项）和_作业_ 收据（使用了哪些打印选项、打印了多少页、打印作业的时间等）
作业状态属性
Job 对象有两个主要的状态属性：job-state和job-state-reasons。job-state属性是一个描述作业一般状态的数字：
3：作业已排队等待。4：作业已暂停，例如PIN 打印。5：正在处理作业（打印、传真等）6：作业停止（缺纸等）7：作业被用户取消。8：作业被打印机中止。9：作业成功完成。
job-state-reasons属性是一个关键字字符串列表，提供有关作业状态的详细信息：
none：一切都很好，没有什么可报告的。document-format-error：由于文件格式错误，无法打印文档。document-unprintable-error：由于其他原因（太复杂、内存不足等）无法打印文档job-incoming：正在从客户端接收作业。job-password-wait：打印机正在等待用户输入作业的 PIN。
注意：IANA IPP 注册表列出了
job-state-reasons属性的所有已注册关键字字符串。所有字符串均为英文，但可以使用每台打印机提供的消息目录进行本地化。
页数记录在以下属性中：
job-impressions-completed：已打印或发送的面数/图像数。job-media-sheets-completed：已打印的张数。job-pages-completed：已处理的文档页数。
职位信息属性
作业对象有许多信息属性，包括作业的名称（job-name）、编号（job-id）、所有者（job-originating-user-name）、打印机（job-printer-uri )，以及在作业创建请求（Create-Job 或 Print-Job）中提供或生成的页数（job-impressions、job-media-sheets和job-pages）。
作业单属性
作业单属性告诉打印机您希望如何打印文档。客户端可以查询打印机功能属性以获取支持的值。以下是常用属性的列表：
介质：使用自描述名称（关键字）值的打印作业所需的纸张尺寸。例如，美国信纸是na_letter_8.5x11in，ISO A4 纸是iso_a4_210x297mm。media-col：打印作业所需的纸张尺寸和其他属性，使用尺寸、类型、来源（纸盘）和边距的键/值对集合。份数：要生产的份数。此属性通常仅支持高级格式，如 PDF 和 JPEG，因此在查询打印机功能时指定文档格式值很重要。sides：指定是否进行双面打印的关键字。值包括单面、双面长边（纵向文档的典型双面打印）和双面短边（横向文档的双面打印）。打印质量：指定所需打印质量的枚举。3是草稿，4是正常的，5是最好的质量。print-color-mode：指定要使用的彩色打印模式的关键字。值color指定全彩色打印，monochrome指定灰度打印，bi-level指定黑白（无灰度）打印。print-scaling：指定如何缩放文档以进行打印的关键字。这通常仅在打印图像时使用，但可用于任何格式。值包括auto（缩放以适应或根据需要填充）、auto-fit（缩放以适应需要）、fill（缩放以填充页面）、fit（缩放以适应文档/图像在页面上）和无（无缩放）。printer-resolution：打印时使用的输出分辨率。默认值通常受打印质量值的影响，但此属性可用于将输出分辨率强制为打印机支持的特定值。page-ranges：要打印的文档页面列表，例如1-8打印第 1 到 8 页。此属性通常仅支持更高级别的格式，如 PDF，因此指定查询打印机功能时的文档格式值。finishings：指定输出应如何完成的枚举列表，例如3表示未完成，4表示装订，5表示打孔，4,5表示装订和打孔。finishings-col：描述应该如何完成输出的键/值对集合列表。基本上是整理属性的高级替代品。job-password和job-password-encryption：用于释放作业以在打印机上打印的密码，例如指定 PIN 打印。
工作收据属性
一些打印机还在每个作业模板属性的名为xxx-actual的属性中记录只读作业回执，例如copies-actual、media-actual等。
文件
打印机在document-format-supported打印机功能属性中报告他们支持的文档格式。大多数 IPP 打印机支持标准格式，如 PDF (application/pdf)、PWG Raster (image/pwg-raster) 和 JPEG (image/jpeg)。AirPrint 打印机还支持称为 Apple Raster (image/urf) 的简单光栅格式。
许多 IPP 打印机还支持传统格式，例如 Adobe PostScript（application/postscript）和 HP 页面控制语言（PCL，application/vnd.hp-pcl），以及各种供应商特定的语言。
application/octet-stream 文档格式用于告诉打印机它应该自动检测格式。检测精度因打印机而异，因此您应尽可能指定实际格式。
提交打印作业
提交打印作业有两种方式：
- 使用 Print-Job 操作，以及
- 使用 Create-Job 和 Send-Document 操作。
打印作业操作
Print-Job 操作允许您创建打印作业并在一个请求中发送文档数据。虽然所有 IPP 打印机都支持此操作，但使用它意味着您无法在提交作业时可靠地取消作业，并且对于许多文档格式，这意味着将在您获得对请求的响应之前打印整个作业。
以下ipptool测试将使用 Print-Job 操作提交 US Letter 打印作业：
{
使用 CUPS API 的相同请求如下所示：
#include <cups/cups.h>
这就是您使用 nodejs API 打印作业的方式：
var ipp = require("ipp");
创建作业和发送文档操作
Create-Job 和 Send-Document 操作将 Job 提交分为两个步骤。您首先使用您的 Job 模板属性发送一个 Create-Job 请求，打印机将返回一个job-id值来识别您刚刚创建的新 Job。然后您发送带有您的文档数据的发送文档请求以完成作业提交。如果您想在发送文档数据时停止作业，您可以打开与打印机的单独连接，并使用从 Create-Job 请求中获得的job-id值发送 Cancel-Job 请求。
以下ipptool测试将使用 Create-Job 和 Send-Document 操作提交 US Letter 打印作业：
{
使用 CUPS API 的相同请求如下所示：
#include <cups/cups.h>
这就是您使用 nodejs API 打印作业的方式：
var ipp = require("ipp");
附录 A：快速参考
工具和库
网络调试工具：
库和示例代码：
- 基于 C 的：CUPS和PWG IPP 示例代码
- Java：用于 IPP 的 Java 实现的Java IPP 客户端实现和核心解析器
- Javascript IPP 客户端实现
- Python IPP 客户端实现
常见操作
下表列出了常见的 IPP 操作（均在RFC 8011中定义）和常用属性。每个请求总是以以下三个属性开始：
属性字符集（charset）：通常是utf-8。attributes-natural-language (naturalLanguage)：通常只是en，格式为ll或ll-cc，其中ll是两个字母的语言代码，cc是国家/地区代码。printer-uri(uri)：通常是ipp://_地址_/ipp/print或ipps://_地址_/ipp/print。
注意：语法使用标准 IPP 数据类型。除作业属性外，所有属性都在操作组中。
文档格式属性对于 Get-Printer-Attributes 操作是可选的，但强烈建议使用。
手术
必需属性（语法）
可选属性（语法）
取消工作
job-id（整数），requesting-user-name（名称）
创建工作
请求用户名（名称），作业名称（名称）
获取作业属性
job-id（整数），requesting-user-name（名称）
请求属性（1setOf 关键字）
找工作
请求用户名（名称）
my-jobs (boolean), requested-attributes (1setOf 关键字), which-jobs (keyword)
获取打印机属性
文档格式（mimeMediaType），请求属性（1setOf 关键字）
打印作业
请求用户名（名称），作业名称（名称）
发送文件
job-id（整数），requesting-user-name（名称）
文档格式（mimeMediaType），文档名称（名称）
常用文档格式
document-format属性指定打印文件的格式。以下是用于打印的常用格式列表：
application/pdf：可移植文档格式 (PDF) 文件。应用程序/postscript：Adobe PostScript 文件（旧版）。application/vnd.hp-pcl：HP 页面控制语言 (PCL) 文件（旧版）。图像/JPEG：JPEG 图像。image/pwg-raster：PWG 光栅格式文件。image/urf：Apple 光栅文件 (AirPrint)。text/plain：带有 CR LF 行结尾的纯 (ASCII) 文本（旧版）。
常用作业属性
下表列出了大多数 IPP 打印机在 Create-Job 和 Print-Job 操作中支持的常见 Job 属性。您可以使用 Get-Printer-Attributes 操作查询相应的打印机属性，只需记住发送文档格式（mimeMediaType）属性即可获取您正在使用的文件格式的值。
注意：语法使用标准 IPP 数据类型。
1setOf something是一个或多个值的数组。如果可用，应使用finishings-ready和media-ready打印机属性，否则使用finishings-supported和media-supported属性。同样，如果可用，应使用finishings-col-ready和media-col-ready打印机属性，否则使用finishings-col-database和media-col-database属性。
作业属性（语法）
打印机属性（语法）
标准
副本（整数）
副本支持（整数）
整理（1setOf 枚举）
完成准备（1setOf 枚举）
整理-col（1setOf 集合）
整理-col-ready（1setOf 系列）
媒体（关键字）
媒体就绪（1setOf 关键字）
media-col (集合)
media-col-ready (1setOf 集合)
输出箱（关键字）
支持输出箱（1setOf 关键字）
页面范围（rangeOfInteger）
支持页面范围（布尔值）
打印颜色模式（关键字）
支持打印颜色模式（1setOf 关键字）
打印质量（枚举）
支持打印质量（1setOf 枚举）
打印缩放（关键字）
支持打印缩放（1setOf 关键字）
打印机分辨率（分辨率）
支持打印机分辨率（1setOf 分辨率）
边（关键字）
侧面支持（1setOf 关键字）
常用打印机属性
下表列出了大多数 IPP 打印机支持的常见打印机属性。您可以使用 Get-Printer-Attributes 操作查询它们。
注意：语法使用标准 IPP 数据类型。
1setOf something是一个或多个值的数组。
打印机属性（语法）
标准
支持文档格式 (1setOf mimeMediaType)
支持 ipp 功能（1setOf 关键字）
支持 ipp 版本（1setOf 关键字）
支持工作创建属性（1setOf 关键字）
操作支持（1setOf 枚举）
打印机警报（1setOf octetString）
打印机警报描述（1setOf 文本）
打印机地理位置 (uri)
打印机信息（文本）
打印机输入托盘 (1setOf octetString)
打印机正在接受作业（布尔值）
打印机位置（文本）
打印机品牌和型号（文本）
打印机更多信息 (uri)
打印机名称（名称）
打印机输出托盘（1setOf octetString）
打印机状态（枚举）
打印机状态原因（1setOf 关键字）
支持打印机字符串语言 (1setOf naturalLanguage)
打印机字符串 uri (uri)
打印机供应 (1setOf octetString)
打印机供应描述（1setOf 文本）
打印机供应信息 uri (uri)
打印机 uri 支持 (1setOf uri)
pwg-raster-document-resolution-supported (1setOf 分辨率)
pwg-raster-document-sheet-back（关键字）
支持 pwg-raster-document-type （1setOf 关键字）
支持 uri 身份验证（1setOf 关键字）
支持 uri-security（1setOf 关键字）
标准
IANA IPP 注册提供了所有 IPP 属性、值、操作和状态代码的列表，其中包含指向相应标准的链接。
这些是核心的 Internet 打印协议标准：
- IPP 无处不在 (PWG 5100.14)
- IPP 2.0、2.1 和 2.2 (PWG 5100.12)
- IPP 1.1 -编码和传输 (RFC 8010) -模型和语义 (RFC 8011)
- IPP 实施者指南 (PWG 5100.19)
这些是媒体命名和常见文件格式的标准：
这些是定义如何支持特定打印机功能的 Internet 打印协议标准：