PDF printing

print_pdf sends a PDF byte buffer or data stream to the active host's print UI or service. Call it from a user action after the app has generated the document. Its result describes what the host accepted or presented; it never claims that paper was physically printed.

Public API

Item
Value
Effect helper
ctx.effects.print_pdf(request)
Capability
PRINT_PDF (fission.print.pdf)
Request
PrintPdfRequest
PDF source
FileWriteSource::Bytes / FileWriteSource::Stream
Page range
PrintPageRange { first_page, last_page }
Result
PrintPdfResult { outcome, job_id }
Error
PrintError { code, message }
CLI value
none required
The request defaults to one copy and all pages. Page numbers are one-based and inclusive. copies must be between 1 and 999. Empty or malformed PDF data returns invalid_pdf.
let request = PrintPdfRequest {
    pdf: FileWriteSource::Stream(generated_pdf),
    job_name: Some("Quarterly report".into()),
    copies: 1,
    page_ranges: Vec::new(),
};
ctx.effects.print_pdf(request)
Bind both result paths so the app can explain whether the host opened a print dialog, submitted a job, or returned an error:
let printed = ctx.effects.bind(PrintFinished, reduce_with!(on_print_finished));
let failed = ctx.effects.bind(PrintFailed, reduce_with!(on_print_failed));

ctx.effects.print_pdf(request).on_ok(printed).on_err(failed);

#[fission_reducer(PrintFinished)]
fn on_print_finished(state: &mut AppState, ctx: &mut ReducerContext<AppState>) {
    if let Some(result) = ctx.input.capability_ok(PRINT_PDF) {
        state.print_outcome = Some(result.outcome);
        state.print_error = None;
    }
}

#[fission_reducer(PrintFailed)]
fn on_print_failed(state: &mut AppState, ctx: &mut ReducerContext<AppState>) {
    state.print_error = ctx.input.capability_error(PRINT_PDF);
}
The callbacks name the outcome paths; the host's actual result arrives through ctx.input, not through a fabricated Submitted action payload. Here the app owns print_outcome: Option<PrintOutcome> and print_error: Option<PrintError>. Persist the original PDF and any product-level output record in app storage before calling this capability; the host print operation does not own that document data.

Outcomes

Outcome or error
Meaning
PrintOutcome::Submitted
The native print service accepted the job or the Windows print action launched. This is not a physical completion receipt.
PrintOutcome::Presented
A browser or Android print surface opened. Those APIs do not report the user's final choice to Fission.
PrintOutcome::Cancelled
iOS reported that the user dismissed its print sheet before submission, or the browser print window closed before loading.
PrintError with code = "unsupported"
The active host has no configured print provider or cannot apply the requested settings.
popup_blocked, print_failed, print_submission_failed
The browser blocked its print window, or a host failed to present/submit the document.
Do not show “Printed” from Submitted or Presented. Use wording such as “Print dialog opened” or “Sent to the print queue,” and keep a separate download or save action when the user needs a retained copy.

Target behavior

Target
Behavior
Linux, macOS
Sends PDF bytes to CUPS using lp or lpr. Copy count and page ranges are passed to the print service.
Windows
Writes a temporary PDF for the registered PDF handler's print verb. The host reports when that print action launches. Requested page/copy overrides return unsupported.
Web
Opens a blank print window before it awaits a stream, preserving the click's popup activation; then loads the PDF and invokes the browser print UI. Allow popups for the site. Browser print settings are chosen in that dialog.
Android
Uses PrintManager and the system print sheet. The current adapter accepts all pages; Fission reports a write error instead of silently ignoring a selected page range.
iOS
Uses UIPrintInteractionController; the completion callback distinguishes submission, cancellation, and errors. The print sheet provides page and copy controls.
Static site, SSR browser client
Uses the Web behavior when running in a browser.
Terminal, SSR server process
Returns a typed unsupported error.

Streaming and errors

Providers open FileWriteSource::Stream through CapabilityCtx; the stream is one-shot. Current providers buffer its contents before handing the PDF to the platform print API, so large PDFs still use memory proportional to their size. Keep the source in app state only if the app owns the stream lifecycle. Stream-open and stream-read failures return stream_open_failed and stream_read_failed respectively.
Page ranges with a first page of zero or an ending page before the first page return invalid_page_range. Browser and Windows print handlers cannot apply explicit page/copy overrides, so those requests return unsupported rather than silently dropping the settings.
Previous
Scatter
Next
Charts