settings (GET)

{server}/api/v1/printer/settings/{deviceName}/{units}

Description

Returns device settings for a print device that HTML/PDF/RAW content will be printed to (paper size, source etc.).

Where a value of 0 corresponds to 'Default' (eg. for collate or duplex), the setting will be taken from the Internet Explorer settings on the machine providing ScriptX.Services.

Applies to:

ScriptX.Services for Windows PC v2.19 and later.

Request parameters


    deviceName (string, required)
    units (integer, optional): 0 = Default, 1 = Inches, 2 = Mm

deviceName (string, optional): Name of the printer/device available to the ScriptX.Services device (Windows PC/Windows Server), or 'default' for the service default printer.
units (integer, optional): Option that specifies the measurement units to be used for margin settings, header and footer heights etc. Value can be 0 (Default), 1 (inches) or 2 (mm).

Response model


    DeviceSettings {
        printerName (string, optional),
        paperSizeName (string, optional),
        paperSourceName (string, optional),
        collate (integer, optional): 0 = Default, 1 = True, 2 = False,
        copies (integer, optional),
        duplex (integer, optional): 0 = Default, 1 = Simplex, 2 = Vertical, 3 = Horizontal,
        paperPageSize (Size, optional),
        unprintableMargins (Margins, optional),
        status (integer, optional),
        port (string, optional),
        attributes (integer, optional),
        serverName (string, optional),
        shareName (string, optional),
        location (string, optional),
        isLocal (boolean, optional),
        isNetwork (boolean, optional),
        isShared (boolean, optional),
        isDefault (boolean, optional),
        bins (Array[string], optional),
        forms (Array[string], optional)
    }

    Size {
        width (number, optional),
        height (number, optional)
    }
    Margins {
        left (string, optional),
        top (string, optional),
        bottom (string, optional),
        right (string, optional)
    }

DeviceSettings:

printerName (string, optional): Name of the printer/device on the server. If 'default' was used for the deviceName parameter this will be the default server printer.
paperSizeName (string, optional): Current paper size setting for the device.
paperSourceName (string, optional): Current paper source setting (or bin) for the device (eg. 'Upper tray').
collate (integer, optional): Current collation setting for the device. Value can be 0 (Default), 1 (True) or 2 (False).
copies (integer, optional): Current device setting for number of copies to be printed.
duplex (integer, optional): Current duplex setting for the device. Value can be 0 (Default), 1 (Simplex ie. not Duplex), 2 (Vertical duplex) or 3 (Horizontal duplex).
paperPageSize (Size, optional): Current paper page size for the device as described by the Size class.
unprintableMargins (Margins, optional): Current device setting for unprintable margins as described by the Margins class.
status (integer, optional): Current status of the device. Value can be any reasonable combination of these values.
port (string, optional): A string that identifies the port(s) used to transmit data to the printer. If a printer is connected to more than one port, the names of each port will be separated by commas (for example, "LPT1:,LPT2:,LPT3:").
attributes (integer, optional): The current attributes of the printer. Value can be any reasonable combination of these values.
serverName (string, optional): A string giving the name of the server computer controlling the printer. If the string is empty then the printer is controlled locally.
shareName (string, optional): A string identifying the share point of the printer. This value is only present if PRINTER_ATTRIBUTE_SHARED is set in attributes.
location (string, optional): A string describing the physical location of the printer.
isLocal (boolean, optional): Whether the printer is a local printer (true) or not (false). isLocal tests whether PRINTER_ATTRIBUTE_LOCAL is set in attributes.
isNetwork (boolean, optional): Whether the printer is a network printer (true) or not (false). isNetwork tests whether PRINTER_ATTRIBUTE_NETWORK is set in attributes.
isShared (string, optional): Whether the printer is a shared printer (true) or not (false). isShared tests whether PRINTER_ATTRIBUTE_SHARED is set in attributes.
isDefault (boolean, optional): Whether the printer is the default printer of the server computer (true) or not (false).
bins (Array[string], optional): Lists the available paper sources for a printer. The names returned are suitable for use with the paperSource property.
forms (Array[string], optional): Lists the available paper sizes (forms) for a printer. The names returned are suitable for use with the paperSize property.

Size:

width (number, optional): The width of the paper specified by paperSizeName. Units are as specified in the units request parameter.
height (number, optional): The height of the paper specified by paperSizeName. Units are as specified in the units request parameter.

Margins:

left (string, optional): Left page margin.
top (string, optional): Top page margin.
bottom (string, optional): Bottom page margin.
right (string, optional): Right page margin.

Example usage

for Cloud
for On-Premise Devices
for Windows PC

Server URL:

Request


<h5>Response <span id="response-status"></span></h5>
<textarea id="response" readonly="readonly" rows="3" class="codefont"></textarea>
<h5>Response headers</h5>
<textarea id="headers" readonly="readonly" rows="3" class="codefont"></textarea>


document.addEventListener("DOMContentLoaded", function() {
    document.getElementById('btn_runcode').addEventListener('click', function() { callServer(); });
});

function callServer() {

    document.getElementById('response-status').textContent = "(waiting)";
    const apiUrl = "/api/v1/printer/settings/default/2";

    const headers = new Headers({
        "Authorization": "Basic " + btoa("xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" + ":"),
        "Content-Type": "application/json"
    });
    
    fetch(apiUrl, { method: "GET", headers: headers })
    .then(response => {
        if (!response.ok) {
            throw new Error('Network response was not ok: ' + response.statusText);
        }
        document.getElementById('response-status').textContent = 
            '(status: ' + response.status + ' ' + response.statusText + ')';
        return response.json().then(data => {
            // show JSON response in textarea element
            document.getElementById('response').value = JSON.stringify(data, null, "  ");

              // do something with the device info
              var leftUnprintableMargin = data.unprintableMargins.left + (data.page.units === 1 ? ' inches' : ' mm';
              var isDefaultPrinter = data.isDefault;
              var currentPaperSize = data.paperSizeName + '(w:' + data.paperPageSize.width + 'mm h:' + data.paperPageSize.height + 'mm)';
              // the units request parameter was 2 so dimensions returned will be in mm
            return response.headers;
        });
    })
    .then(headers => {
        // show response headers in textarea element
        let headersText = "";
        for (let pair of headers.entries()) {
            headersText += `${pair[0]}: ${pair[1]}\n`;
        }
        document.getElementById('headers').value = headersText;
    })
    .catch(error => {
        document.getElementById('response-status').textContent = '(error: ' + error.message + ')';
        document.getElementById('response').value = "Failed to fetch data.";
    });

}

Response

Response headers

Printer/device status codes

The status code returned by a device can be any reasonable combination of the following values:

Name	Value	Meaning
PRINTER_STATUS_BUSY	0x00000200	The printer is busy.
PRINTER_STATUS_DOOR_OPEN	0x00400000	The printer door is open.
PRINTER_STATUS_ERROR	0x00000002	The printer is in an error state.
PRINTER_STATUS_INITIALIZING	0x00008000	The printer is initializing.
PRINTER_STATUS_IO_ACTIVE	0x00000100	The printer is in an active input/output state.
PRINTER_STATUS_MANUAL_FEED	0x00000020	The printer is in a manual feed state.
PRINTER_STATUS_NO_TONER	0x00040000	The printer is out of toner.
PRINTER_STATUS_NOT_AVAILABLE	0x00001000	The printer is not available for printing.
PRINTER_STATUS_OFFLINE	0x00000080	The printer is offline.
PRINTER_STATUS_OUT_OF_MEMORY	0x00200000	The printer has run out of memory.
PRINTER_STATUS_OUTPUT_BIN_FULL	0x00000800	The printer's output bin is full.
PRINTER_STATUS_PAGE_PUNT	0x00080000	The printer cannot print the current page. Windows 95/98/Me: Indicates the page is being "punted" (that is, not printed) because it is too complex for the printer to print.
PRINTER_STATUS_PAPER_JAM	0x00000008	Paper is jammed in the printer.
PRINTER_STATUS_PAPER_OUT	0x00000010	The printer is out of paper.
PRINTER_STATUS_PAPER_PROBLEM	0x00000040	The printer has a paper problem.
PRINTER_STATUS_PAUSED	0x00000001	The printer is paused.
PRINTER_STATUS_PENDING_DELETION	0x00000004	The printer is being deleted.
PRINTER_STATUS_POWER_SAVE	0x01000000	The printer is in power save mode.
PRINTER_STATUS_PRINTING	0x00000400	The printer is printing.
PRINTER_STATUS_PROCESSING	0x00004000	The printer is processing a print job.
PRINTER_STATUS_SERVER_UNKNOWN	0x00800000	The printer status is unknown.
PRINTER_STATUS_TONER_LOW	0x00020000	The printer is low on toner.
PRINTER_STATUS_USER_INTERVENTION	0x00100000	The printer has an error that requires the user to do something.
PRINTER_STATUS_WAITING	0x00002000	The printer is waiting.
PRINTER_STATUS_WARMING_UP	0x00010000	The printer is warming up.

Printer/device attributes

The attributes returned for a device can be any reasonable combination of the following values:

Name	Value	Meaning
PRINTER_ATTRIBUTE_DEFAULT	0x00000004	Windows 95/98/Me: Indicates the printer is the default printer in the system.
PRINTER_ATTRIBUTE_DIRECT	0x00000002	Job is sent directly to the printer (it is not spooled).
PRINTER_ATTRIBUTE_DO_COMPLETE_FIRST	0x00000200	If set and printer is set for print-while-spooling, any jobs that have completed spooling are scheduled to print before jobs that have not completed spooling.
PRINTER_ATTRIBUTE_ENABLE_BIDI	0x00000800	Windows 95/98/Me: Indicates whether bi-directional communications are enabled for the printer.
PRINTER_ATTRIBUTE_FAX	0x00004000	Windows XP: If set, printer is a fax printer.
PRINTER_ATTRIBUTE_KEEPPRINTEDJOBS	0x00000100	If set, jobs are kept after they are printed. If unset, jobs are deleted.
PRINTER_ATTRIBUTE_QUEUED	0x00000001	If set, the printer spools and starts printing after the last page is spooled. If not set and PRINTER_ATTRIBUTE_DIRECT is not set, the printer spools and prints while spooling.
PRINTER_ATTRIBUTE_SHARED	0x00000008	Printer is shared.
PRINTER_ATTRIBUTE_WORK_OFFLINE	0x00000400	Windows 95/98/Me: Indicates whether the printer is currently connected. If the printer is not currently connected, print jobs will continue to spool.
PRINTER_ATTRIBUTE_PUBLISHED	0x00002000	Windows 2000/XP: Indicates whether the printer is published in the directory service.
PRINTER_ATTRIBUTE_NETWORK	0x00000010	Printer is a network printer connection.
PRINTER_ATTRIBUTE_LOCAL	0x00000040	Printer is a local printer.
PRINTER_ATTRIBUTE_RAW_ONLY	0x00001000	Indicates that only raw data type print jobs can be spooled.