Print API: AirPrint

The AirPrint API allows visitors to print content from your kiosk to your AirPrint-enabled printer. This API also allows for the use of different callbacks, returning information about whether the print had been successful or returned any error codes.

Functions

Callbacks

Related Settings

Requirements

  • Access JavaScript API
    • By Import - recommended, works both online & offline, requires inclusion of kiosk_functions.js prior to any of the following calls.
    • By Injection - only works offline, may not be available 'onload' event.
  • Printing
    • AirPrint = On
  • Connection to AirPrint Printer
    • iOS device must be on the same WiFi network as an available AirPrint-enabled printer. For more information about Airprint-enabled printers currently available and how to set up AirPrint, you can visit this page.

Sample Code

This sample code relies on the JavaScript APIs built into Kiosk Pro and will not run successfully in other browsers or within our in-app help interface.  

To run sample code, set the app's homepage to http://www.kioskproapp.com/airprint

Download Sample Code


kp_AirPrinter_requestStateOfSupporting

This function determines whether printing to AirPrint printers is enabled in Kiosk Pro's settings.

Format
kp_AirPrinter_requestStateOfSupporting();
		

Status

Following this call, Kiosk Pro will immediately trigger kp_AirPrinter_stateOfSupportingDidChange with the current state.


kp_AirPrinter_checkStatusOfSelectedPrinter

Added in 7.9
This function determines the connection status of the AirPrint printer Kiosk Pro is connected to. Print Mode must be set to Automatic Kiosk Print Mode for this call to execute correctly.

Format
kp_AirPrinter_checkStatusOfSelectedPrinter(callback);
		
Parameters callback = callback name as string.
Callback Format
callback(statusCode)
		
Callback Return Values
  • statusCode = integer variable indicating the status of the printer. Possible values are:
    • 0 = AirPrint is disabled in Kiosk Pro settings.
    • 1 = Print Mode is set to 'Standard Dialog'.
    • 2 = Printer is not selected.
    • 3 = Selected printer is not available.
    • 4 = Selected printer is available.
    • default = Status is unknown.

kp_AirPrinter_print

This function initiates printing of the current webpage or document.

Format
kp_AirPrinter_print();
		

Status

If the visitor cancels printing or an error is returned by the printer, the app will call kp_AirPrinter_printDidFailWithError with the appropriate error code.

If no error is returned by the printer, the job is assumed to be a success and the app will call kp_AirPrinter_printDidFinish.


kp_AirPrinter_printPdf

This function initiates printing of the referenced PDF file.

Format
kp_AirPrinter_printPdf();
		
Parameters filename = Kiosk Pro can print local or remote .pdf files using the following formats:
  • short filename (e.g. 'p1.pdf'). If no path is specified, Kiosk Pro will search for the file directly inside the main 'Documents' directory.
  • relative path from 'Documents' directory (e.g. 'MyPDFs/p2.pdf')
  • full URL path to the remote PDF-file (e.g. 'http://www.example.com/p2.pdf')

Status

If the file can't be found or is not available, then the app will call kp_AirPrinter_openPdfDidFailWithError with the appropriate error code.

If the visitor cancels printing or an error occurs during printing, the app will call kp_AirPrinter_printDidFailWithError with the appropriate error code.

If no error is returned by the printer, the job is assumed to be a success and Kiosk Pro will call kp_AirPrinter_printDidFinish.


kp_AirPrinter_printDidFinish

This callback is triggered when a print job is sent to a connected AirPrinter and no error is returned.

Format
kp_AirPrinter_printDidFinish();
		

Status

This callback may be triggered without actually printing if a job is accepted and stored in the printer's print queue without returning an error to the app. For example, the Brother Airprint printer we use for internal testing will accept print jobs even if it is out of paper and save them until new paper is added, at which point it will move ahead with printing automatically. As this may vary depending on the printer manufacturer, testing may be required with your specific printer set-up to determine how these types of errors are handled.


kp_AirPrinter_printDidFailWithError

This callback is triggered when visitor cancels printing or an error has occurred.

Format
kp_AirPrinter_printDidFailWithError(errorCode);
		
Format errorCode = the code of the error as an integer. The following are possible:
  • -1001 = AirPrint is disabled in Kiosk Pro's settings.
  • -1000 = AirPrint dialog is already showing.
  • -999 = UIWebView failed to create the necessary printer controller.
  • -998 = Printing was not completed: visitor cancelled printing or another error communicated by the printer.
  • 1 = The device does not support printing.
  • 2 = No print formatter, page renderer, printing item or printing items was assigned for printing.
  • 3 = An image is in a format not recognized by UIKit for printing.
  • 4 = An internal error occurred with the print job.

Status

Note that if the printer cannot print, but still accepts the print job successfully, no error is returned. For example, the Brother Airprint printer we use for internal testing will accept print jobs even if it is out of paper and save them until new paper is added, at which point it will move ahead with printing automatically; in this case, no error is returned by the printer and so we are unable to trigger this callback. As this may vary depending on the printer manufacturer, testing may be required with your specific printer set-up to determine when an error callback can be returned.


kp_AirPrinter_openPdfDidFailWithError

This callback is triggered when the PDF file named in kp_AirPrinter_printPdf cannot be successfully opened.

Format
kp_AirPrinter_openPdfDidFailWithError(errDescription, errDomain, errCode);
		
Return values
  • errDescription = a string containing the localized description of the error.
  • errDomain = a string containing the receiver’s error domain.
  • errCode = an integer containing the error code.

Error codes are returned directly from Apple's Foundations library. In testing, the most frequent error we have seen is: [Description: 'The operation couldn't be completed (Cocoa error 260)', ErrorDomain=NSCocoaErrorDomain, ErrorCode=260], which indicates a standard 'file not found' error. Please see Apple's documentation to get more information about errors (Ctrl-F or Command-F > search 'NSError Codes').


kp_AirPrinter_stateOfSupportingDidChange

This callback is triggered when your code calls kp_AirPrinter_requestStateOfSupporting and each time the app is launched or an administrative user changes Kiosk Pro's settings.

Format
kp_AirPrinter_stateOfSupportingDidChange(supported);
		
Return values supported = supported state as boolean:
  • 1 = AirPrint is enabled in Kiosk Pro's settings.
  • 0 = AirPrint is disabled in Kiosk Pro's settings.

Still stuck? How can we help? How can we help?