/*

    File:       Hose.h

    Contains:   interface to the hose routines

    Written by: Richard Blanchard and Ingrid Kelly  

    Copyright:  Copyright © 1999 by Apple Computer, Inc., All Rights Reserved.

                You may incorporate this Apple sample source code into your program(s) without

                restriction. This Apple sample source code has been provided "AS IS" and the

                responsibility for its operation is yours. You are not permitted to redistribute

                this Apple sample source code as "Apple sample source code" after having made

                changes. If you're going to re-distribute the source, we require that you make

                it clear in the source that the code was descended from Apple sample source

                code, but that you've made changes.

    Change History (most recent first):

                7/26/1999   Karl Groethe    Updated for Metrowerks Codewarror Pro 2.1

*/

#ifndef __HOSE__

#define __HOSE__

/*** Constants ***/

/*  The size and number of buffers to use when writing PostScript to a file.

*/

#define kPrinterHoseBufSize         (8 * 512)       // For a quantem 8 printer.

#define kPrinterHoseMinBufs         2               // We need at least this many buffers.

#define kPrinterHoseMaxBufs         16              // Don't allocate more that this many buffers. rb891

/*  The PAP code sets ioResult to 1 while an operation is pending.

*/

#define kPAPBusy            1

/*  Our queues use the following constant as the queue type.

    The type really doesn't matter, but it can ease debugging.

*/

#define kMemQueueType               84

/*** Variable Types ***/

/*  The format of our queue elements. We allocate the queue elements

    seperately from the actual buffers. This means we make twice as many

    allocations (bad), but the code is more flexible (good) in that we can switch

    to handles for the buffers or we can allocate multiple buffers in a single NewPtr

    call.

*/

typedef struct MemQElem{

    QElemPtr qLink;                 // Used by Enqueue and Dequeue.

    short qType;                    // Our constant (kMemQueueType) to identify our queues.

    struct BufIO *bufIO;            // So we can recover buffer information.

    Byte *buf;                      // Pointer to the allocated buffer.

    SInt32 maxBytes;                // The size of the block pointed to by 'buf'

    SInt32 nBytes;                  // Number of valid bytes in 'buf'.

    Boolean eoj;                    // true if the data is followed by an end of job.

    Boolean inQOnly;                // This buffer should be used only for the input routines.

}MemQElem, *MemQElemPtr;

/*  We track the state of the connection using these state constants.

*/

typedef enum{

    kConnClosed = 0,        // We start in this state.

    kConnOpening,           // This is the state while we wait for the printer to accept the connection.

    kConnOpen,              // This is the state while we do reads and writes to the printer.

    kConnClosing            // This is the state while we wait for the connection to close

}ConnState;

/*  When the hose's async routines complete, they should call PrStream's routines

    via the following procedures. The hose passes the memory element of the

    buffer that just completed reading or writing. The hose also passes an

    error parameter to indicate problems with the channel.

*/

typedef void (*FinishedWriteProc)(MemQElemPtr memElem, OSStatus err);

typedef void (*FinishedReadProc)(MemQElemPtr memElem, OSStatus err);

typedef struct{

    FinishedWriteProc finishedWrite;

    FinishedReadProc finishedRead;

}BufCallbacks;

typedef OSStatus (*HoseOutProc)(void *refcon, MemQElemPtr memElem);

typedef OSStatus (*HoseInProc)(void *refcon, MemQElemPtr memElem);

typedef OSStatus (*HoseIdleProc)(void *refcon);

typedef OSStatus (*HoseCloseProc)(void *refcon);

typedef ConnState (*HoseConnProc)(void *refcon);

typedef OSStatus (*HoseStatusProc)(void *refcon, StringPtr statusStr);

typedef OSStatus (*HoseDisposeProc)(void *refcon);                      

typedef OSStatus (*HoseCancelProc)(void *refcon);

/*  Support for the HoseCancelProc is new in PrintingLib 8.6.5.

    When a job is being terminated abnormally, if the hose exports

    a function with the name "hoseCancel" then that routine

    is invoked prior to the HoseCloseProc and HoseDisposeProc. 

*/

/*  The HoseInfo structure is filled out by a hose open procedure. The

    structure describes the buffer requirements of the hose as well as

    the function pointers for reading, writing, and closing the hose.

*/

typedef struct{

    HoseOutProc out;            // The procedure to call with a filled buffer.

    HoseInProc in;              // The procedure to call to send a buffer.

    HoseIdleProc idle;          // The procedure to call when we get a chance.

    HoseCloseProc close;        // The procedure to call when we are done printing.

    HoseConnProc connState;     // This procedure returns the state of the current connection.

    HoseStatusProc status;      // Use this procedure to get the hose's current status string.

    HoseDisposeProc dispose;    // The hose should free up all of its memory.               //rb2198

    Size bufSize;               // The size of each allocated data buffer.

    long minBufs;               // We need at least this many buffers or we return an out of mem error.

    long maxBufs;               // We'll never allocate more buffers than this.

    void *refcon;               // A pointer that will be passed to the data handling routines.

}HoseInfo;

typedef OSStatus (*HoseOpenProc)(HoseInfo *hoseInfo, BufCallbacks *callbacks, Collection hints, Handle papaH);      // DMG500

/* The entry point for a hose library. 

*/

#if PRAGMA_IMPORT_SUPPORTED

#pragma import on

#endif

OSStatus hoseOpen(HoseInfo *hoseInfo, BufCallbacks *callbacks, Collection hints, Handle papaH);

#if PRAGMA_IMPORT_SUPPORTED 

#pragma import off

#endif

#endif      // __HOSE__