Filter and Backend APIs
Keywords: Programming

## Introduction

The CUPS filter and backend APIs define standard exit codes and provide access to the backchannel data stream. They are only used when writing backends, filters, and port monitors.

## General Usage

The <cups/backend.h> and <cups/cups.h> header files must be included to use the `CUPS_BACKEND_` constants and `cupsBackChannel` functions, respectively.

Programs using these functions must be linked to the CUPS library: libcups.a, libcups.so.2, libcups.2.dylib, libcups_s.a, or libcups2.lib depending on the platform. The following command compiles myprogram.c using GCC and the CUPS library:

    gcc -o myprogram myprogram.c -lcups

## Compatibility

All of these functions require CUPS 1.2 or higher.

## Contents

- Functions

## Functions

- `cupsBackChannelRead()` CUPS 1.2
- `cupsBackChannelWrite()` CUPS 1.2

### CUPS 1.2 cupsBackChannelRead()

#### Description

Read data from the backchannel. Reads up to "bytes" bytes from the backchannel. The "timeout" parameter controls how many seconds to wait for the data - use 0.0 to return immediately if there is no data, -1.0 to wait for data indefinitely.

#### Syntax

    ssize_t
    cupsBackChannelRead(
        char * buffer,
        size_t bytes,
        double timeout);

#### Arguments

Name | Description
--- | ---
`buffer` | Buffer to read
`bytes` | Bytes to read
`timeout` | Timeout in seconds

#### Returns

Bytes read or -1 on error

### CUPS 1.2 cupsBackChannelWrite()

#### Description

Write data to the backchannel. Writes "bytes" bytes to the backchannel. The "timeout" parameter controls how many seconds to wait for the data to be written - use 0.0 to return immediately if the data cannot be written, -1.0 to wait indefinitely.

#### Syntax

    ssize_t
    cupsBackChannelWrite(
        const char * buffer,
        size_t bytes,
        double timeout);

#### Arguments

Name | Description
--- | ---
`buffer` | Buffer to write
`bytes` | Bytes to write
`timeout` | Timeout in seconds

#### Returns

Bytes written or -1 on error