printing

package
v0.1.4 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 20, 2026 License: MIT Imports: 13 Imported by: 0

README

Printing SDK

Printers(ctx) and DefaultPrinter(ctx) only inspect installed destinations. SubmitPDF(ctx, path, Options{PrinterName: "…", Copies: 1}) explicitly submits a readable PDF. Keep the file until the synchronous call returns. No package initialization, test, or enumeration operation submits a print job.

  • macOS/Linux: installed CUPS destinations (lpstat -p/-d); lp returns the spooler job ID. Requires CUPS client tools and a configured printer.
  • Windows: Unicode Winspool EnumPrintersW level 4 / GetDefaultPrinterW; PDF submission requires SumatraPDF.exe on PATH. It is not downloaded or bundled. Unknown file associations and RAW PDF-to-device writes are not used. Job.Dispatched means the renderer exited successfully without exposing a queue ID, not verified paper output. Windows job titles are renderer-owned.
  • Copies: 1–99 (zero means one). Fit to printable area; printer-default paper, tray and duplex settings. No custom-paper, page-range or printer-preferences UI is claimed. Invalid/encrypted/restricted PDFs may be refused by the renderer.
  • Cancellation before submission is ErrCanceled. A timeout/cancellation during submission is ErrSubmissionUnknown: inspect the print queue before retrying, because killing the client cannot recall an accepted job.

The GUI confirmation dialog stages its own private PDF before returning and submits asynchronously, so its caller may delete the original temporary PDF after gui.ShowPrintDialog returns. The private copy is removed after backend completion. Applications can inject a Backend using NewClient for testing without paper consumption.

Primary references: CUPS lp, lpstat, Winspool enumeration, SumatraPDF command line.

Documentation

Overview

Package printing enumerates installed printers and submits PDF documents. Submission is an explicit operation: enumeration never creates print jobs. A successful submission does not mean that paper has left the printer.

Index

Constants

This section is empty.

Variables

View Source
var (
	ErrNoPrinters         = errors.New("printing: no printers installed")
	ErrNoDefaultPrinter   = errors.New("printing: no default printer configured")
	ErrPrinterNotFound    = errors.New("printing: selected printer not found")
	ErrBackendUnavailable = errors.New("printing: required print backend is unavailable")
	ErrInvalidDocument    = errors.New("printing: a readable PDF document is required")
	ErrInvalidOptions     = errors.New("printing: invalid print options")
	ErrCanceled           = errors.New("printing: canceled before submission")
	ErrSubmissionUnknown  = errors.New("printing: submission status unknown; check the printer queue before retrying")
)

Functions

func ValidatePDF

func ValidatePDF(path string) (string, error)

ValidatePDF rejects directories, non-PDF files and unreadable documents. It checks the signature, not full PDF validity; the system renderer performs the actual PDF validation. Absolute paths also prevent option-like filenames from being interpreted as command switches.

Types

type Backend

type Backend interface {
	Printers(context.Context) ([]Printer, error)
	SubmitPDF(context.Context, string, Options) (Job, error)
}

Backend allows applications/tests to provide an explicitly chosen spooler. SubmitPDF is called only after PDF/options/printer validation succeeds.

type Client

type Client struct {
	// contains filtered or unexported fields
}

func NewClient

func NewClient(backend Backend) *Client

func (*Client) DefaultPrinter

func (c *Client) DefaultPrinter(ctx context.Context) (Printer, error)

func (*Client) Printers

func (c *Client) Printers(ctx context.Context) ([]Printer, error)

func (*Client) SubmitPDF

func (c *Client) SubmitPDF(ctx context.Context, path string, options Options) (Job, error)

type Job

type Job struct {
	ID          string
	PrinterName string
	// Dispatched means the PDF renderer accepted the document but exposes no
	// spooler job ID. It must not be presented as verified physical printing.
	Dispatched bool
}

func SubmitPDF

func SubmitPDF(ctx context.Context, path string, options Options) (Job, error)

SubmitPDF waits until the spool command/renderer exits; the caller must keep path readable until return. Canceling an in-flight command cannot recall a queued job: its result is ErrSubmissionUnknown, not a promise of cancellation.

type Options

type Options struct {
	PrinterName string
	Copies      int
	Title       string
}

Options deliberately omits paper/tray/duplex settings: printer defaults are used and PDF content is fitted to the printable area. Copies is 1..99; zero selects one copy. Windows PDF renderers choose their own spooler job title.

type Printer

type Printer struct {
	Name    string
	Default bool
}

func DefaultPrinter

func DefaultPrinter(ctx context.Context) (Printer, error)

func Printers

func Printers(ctx context.Context) ([]Printer, error)

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL