home *** CD-ROM | disk | FTP | other *** search
/ NeXTSTEP 3.0 / NeXTSTEP3.0.iso / NextDeveloper / Headers / dpsclient / dpsclient.h next >
Text File  |  1992-01-30  |  11KB  |  301 lines
  1.  
  2. /*
  3.   dpsclient.h
  4.     Application interface to the Display PostScript Library.
  5.  
  6.   This header file is intended to be identical across all
  7.   implementations of the Display PostScript System. It defines types
  8.   and procedures needed by DPS applications to access DPS. It does not
  9.   include operations for creating new DPSContexts.
  10.  
  11.   Copyright (c) 1988 Adobe Systems Incorporated.
  12.   All rights reserved.
  13.   
  14. */
  15.  
  16. #ifndef DPSCLIENT_H
  17. #define DPSCLIENT_H
  18.  
  19. #ifndef DPSFRIENDS_H
  20. #include "dpsfriends.h"
  21. #endif DPSFRIENDS_H
  22.  
  23. /*=== TY&D===*/
  24.  
  25. /* Standard error codes (type DPSErrorCode)
  26.  * These are intended to be used with dpsexcept.h
  27.  * System-specific extensions can be made. Codes 1000 through 1099 are
  28.  * reserved for use by Adobe.
  29.  *
  30.  * Codes 1100-1999 are reserved by NeXT.
  31.  */
  32.  
  33. #define DPS_ERROR_BASE        1000
  34. #define DPS_NEXT_ERROR_BASE    1100
  35.  
  36. #define DPS_ERRORBASE        1000    /* historical synonym */
  37. #define DPS_NEXTERRORBASE    1100    /* historical synonym */
  38.  
  39. typedef enum _DPSErrorCode {
  40.     dps_err_ps = DPS_ERROR_BASE,
  41.     dps_err_nameTooLong,
  42.     dps_err_resultTagCheck,
  43.     dps_err_resultTypeCheck,
  44.     dps_err_invalidContext,
  45.     dps_err_select = DPS_NEXT_ERROR_BASE,
  46.     dps_err_connectionClosed,
  47.     dps_err_read,
  48.     dps_err_write,
  49.     dps_err_invalidFD,
  50.     dps_err_invalidTE,
  51.     dps_err_invalidPort,
  52.     dps_err_outOfMemory,
  53.     dps_err_cantConnect
  54. } DPSErrorCode;
  55.  
  56.   /* The above definitions specify the error codes passed to a DPSErrorProc:
  57.  
  58.        dps_err_ps identifies standard PostScript language interpreter
  59.        errors. The arg1 argument to the errorProc is the address of the
  60.        binary object sequence sent by the handleerror (or resynchandleerror)
  61.        operator to report the error. The sequence has 1 object, which is an
  62.        array of 4 objects. See the language extensions document for details
  63.        on the contents of this sequence. arg2 is the number of bytes in the
  64.        entire binary object sequence.
  65.  
  66.        dps_err_nameTooLong flags user names that are too long. 128 chars
  67.        is the maximum length for PostScript language names. The name and its
  68.        length are passed as arg1 and arg2 to the error proc.
  69.  
  70.        dps_err_resultTagCheck flags erroneous result tags, most likely
  71.        due to erroneous explicit use of the printobject operator. The
  72.        pointer to the binary object sequence and its length are passed
  73.        as arg1 and arg2 to the error proc. There is one object in the
  74.        sequence.
  75.  
  76.        dps_err_resultTypeCheck flags incompatible result types. A pointer
  77.        to the offending binary object is passed as arg1; arg2 is unused.
  78.  
  79.        dps_err_invalidContext flags an invalid DPSContext argument. An
  80.        attempt to send PostScript language code to a context that has
  81.        terminated is the most likely cause of this error. arg1 to the
  82.        DPSErrorProc is the context id (see the fork operator); arg2 is
  83.        unused.
  84.  
  85.        dps_err_select, dps&D_read and dps_err_write signal communication
  86.        errors in the connection.  The OS return code is passed in arg1;
  87.        arg2 is unused.
  88.  
  89.        dps_err_connectionClosed indicates the connection to a windowserver
  90.        went away.  arg1 and arg2 are unused.
  91.  
  92.        dps_err_invalidFD, dps_err_invalidTE and dps_err_invalidPort 
  93.        indicate a illegal item of the given type was passed to a DPS
  94.        routine.  The illegal item is passed in arg1; arg2 is unused.
  95.  
  96.        dps_err_outOfMemory indicates a storage allocation failure.  The size
  97.        of the block requested is passed in arg1; arg2 is unused.
  98.  
  99.        dps_err_cantConnect signals an error during the creation of a
  100.        connection to a window server.  The host that was being connected
  101.        to is passed in arg1; arg2 is unused. 
  102.   */
  103.  
  104. typedef void (*DPSTextProc)(
  105.   DPSContext ctxt,
  106.   const char *buf,
  107.   long unsigned int count );
  108.  
  109.   /* Call-back procedure to handle text from the PostScript interpreter.
  110.      'buf' contains 'count' bytes of ASCII text. */
  111.  
  112. typedef void (*DPSErrorProc)(
  113.   DPSContext ctxt,
  114.   DPSErrorCode errorCode,
  115.   long unsigned int arg1, 
  116.   long unsigned int arg2 );
  117.   
  118.   /* Call-back procedure to report errors from the PostScript interpreter.
  119.      The meaning of arg1 and arg2 depend on 'errorCode', as described above.
  120.      See DPSDefaultErrorProc, below.
  121.    */
  122.  
  123.  
  124. /*=== PROCEDURES ===*/
  125.  
  126. extern void DPSDefaultErrorProc(
  127.   DPSContext ctxt,
  128.   DPSErrorCode errorCode,
  129.   long unsigned int arg1,
  130.   long unsigned int arg2 );
  131.   
  132.   /* This is the default error proc that is used for both contexts'
  133.      individual errors and the global error backstop.  It raises an
  134.      exception using NX_RAISE.  For all DPS errors, the context is the
  135.      first piece of data put in the NXHandler record.  The second
  136.      data field is value passed to this routine in arg1.
  137.      */
  138.  
  139. extern void DPSSetTextBackstop( DPSTextProc textProc );
  140.  
  141.   /* Call this to establish textProc as the handler for text output from
  142.      DPSDefaultErrorProc or from contexts created by the 'fork' operator but
  143.      not made known to the dps client library. NULL will be passed as the ctxt
  144.      argument to textProc in the latter case. */
  145.  
  146. extern DPSTextProc DPSGetCurrentTextBackstop(void);
  147.  
  148.   /* Returns the textProc passed most recently to DPSSetTextBackstop, or NULL
  149.      if none */
  150.  
  151. extern&Dd DPSSetErrorBackstop( DPSErrorProc errorProc );
  152.  
  153.   /* Call this to establish errorProc as the handler for PostScript interpreter
  154.      errors from contexts created by the 'fork' operator but not made
  155.      known to the dps client library. NULL will be passed as the ctxt
  156.      argument to errorProc. */
  157.  
  158. extern DPSErrorProc DPSGetCurrentErrorBackstop(void);
  159.  
  160.   /* Returns the errorProc passed most recently to DPSSetErrorBackstop, or NULL
  161.      if none */
  162.  
  163. #define DPSWritePostScript(ctxt, buf, count)\
  164.   (*(ctxt)->procs->WritePostScript)((ctxt), (buf), (count))
  165.  
  166.   /* Send as input to 'ctxt' 'count' bytes of PostScript language contained
  167.      in 'buf'. The code may be in either of the 3 encodings for PostScript
  168.      language programs: plain text, encoded tokens, or binary object sequence.
  169.      If the form is encoded tokens or binary object sequence, an entire
  170.      one of these must be sent (perhaps in a series of calls on
  171.      DPSWritePostScript) before PostScript language in a different encoding
  172.      can be sent.
  173.      
  174.      DPSWritePostScript may transform the PostScript language to a different
  175.      encoding, depending on the characteristics established for 'ctxt' when
  176.      it was created. For example, a context created to store its PostScript
  177.      in an ASCII file would convert binary object sequences to ASCII.
  178.  
  179.      If 'ctxt' represents an invalid context, for example because
  180.      the context has terminated in the server, the dps_err_invalidContext
  181.      error will be reported via ctxt's error proc.
  182.      
  183.      If 'ctxt' is incapable of accepting more PostScript language, for example
  184.      because it is backlogged with code that was sent earlier to be executed,
  185.      this will block until transmission of 'count' bytes can be completed. */
  186.  
  187. extern void DPSPrintf( DPSContext ctxt, const char *fmt, ... );
  188.  
  189.   /* Write string 'fmt' to ctxt with the optional arguments converted,
  190.      formatted and logically inserted into the string in a manner
  191.      identical to the C library routine printf.
  192.  
  193.      If 'ctxt' represents an invalid context, for example because
  194.      the context has terminated in the server, the dps_err_invalidContext
  195.      error will be reported via ctxt's error proc.
  196.      
  197.      If 'ctxt' is incapable of accepting more PostScript language, for example
  198.      because it is backlogged with code that was sent earlier&Dbe executed,
  199.      this will block until transmission of the string can be completed. */
  200.  
  201. #define DPSWriteData(ctxt, buf, count)\
  202.   (*(ctxt)->procs->WriteData)((ctxt), (buf), (count))
  203.   
  204.   /* Write 'count' bytes of data from 'buf' to 'ctxt'. This will not
  205.      change the data.
  206.  
  207.      If 'ctxt' represents an invalid context, for example because
  208.      the context has terminated in the server, the dps_err_invalidContext
  209.      error will be reported via ctxt's error proc.
  210.      
  211.      If 'ctxt' is incapable of accepting more PostScript language, for example
  212.      because it is backlogged with code that was sent earlier to be executed,
  213.      this will block until transmission of 'count' bytes can be completed. */
  214.   
  215. #define DPSFlushContext(ctxt) (*(ctxt)->procs->FlushContext)((ctxt))
  216.   
  217.   /* Force any buffered data to be sent to ctxt.
  218.  
  219.      If 'ctxt' represents an invalid context, for example because
  220.      the context has terminated in the server, the dps_err_invalidContext
  221.      error will be reported via ctxt's error proc.
  222.      
  223.      If 'ctxt' is incapable of accepting more PostScript language, for example
  224.      because it is backlogged with code that was sent earlier to be executed,
  225.      this will block until transmission of all buffered bytes can be completed.
  226.      */
  227.   
  228. extern int DPSChainContext( DPSContext parent, DPSContext child );
  229.  
  230.   /* This links child and all of child's children onto parent's 'chainChild'
  231.      list. The 'chainChild' list threads those contexts that automatically
  232.      receive copies of any PostScript code sent to parent. A context may
  233.      appear on only one such list.
  234.      
  235.      Normally, DPSChainContext returns 0. It returns -1 if child already
  236.      appears on some other context's 'chainChild' list. */
  237.  
  238. extern void DPSUnchainContext( DPSContext ctxt );
  239.  
  240.   /* This unlinks ctxt from the chain that it is on, if any. It leaves
  241.     ctxt->chainParent == ctxt->chainChild == NULL
  242.    */
  243.  
  244. #define DPSResetContext(ctxt) (*(ctxt)->procs->ResetContext)((ctxt))
  245.   
  246.   /* This routine is unimplemented in the NeXT implementation of
  247.      Display PostScript.  See the documentation. */
  248.   
  249. #define DPSWaitContext(ctxt) (*(ctxt)->procs->WaitContext)(ctxt)
  250.  
  251.   /* Waits until the PostScript interpreter is ready for more input to
  252.      this context.  This is useful for synchronizing an application
  253.      with the DPS server.
  254.  
  255.  &DIf 'ctxt' represents an invalid context, for example because
  256.      the context has terminated in the server, the dps_err_invalidContext
  257.      error will be reported via ctxt's error proc. */
  258.  
  259. #define DPSSetTextProc(ctxt, tp) ((ctxt)->textProc = (tp))
  260.  
  261.   /* Change ctxt's textProc. */
  262.   
  263. #define DPSSetErrorProc(ctxt, ep) ((ctxt)->errorProc = (ep))
  264.  
  265.   /* Change ctxt's errorProc. */
  266.   
  267. #define DPSInterruptContext(ctxt) (*(ctxt)->procs->Interrupt)((ctxt))
  268.  
  269.   /* This routine is unimplemented in the NeXT implementation of
  270.      Display PostScript. */
  271.  
  272. #define DPSDestroyContext(ctxt) (*(ctxt)->procs->DestroyContext)((ctxt))
  273.  
  274.   /* This calls DPSUnchainContext, then (for an interpreter context) sends a
  275.      request to the interpreter to terminate ctxt, then frees the storage
  276.      referenced by ctxt. The termination request is ignored by the
  277.      server if the context is invalid, for example if it has already
  278.      terminated. */
  279.   
  280. #define DPSSpaceFromContext(ctxt) ((ctxt)->space)
  281.  
  282.   /* Extract space handle from context. */
  283.  
  284. #define DPSDestroySpace(spc) (*(spc)->procs->DestroySpace)((spc))
  285.  
  286.   /* Calls DPSDestroyContext for each of the contexts in the space, then
  287.      sends a request to the server to terminate the space, then frees the
  288.      storage referenced by spc. */
  289.  
  290. extern int DPSSynchronizeContext(DPSContext ctxt, int flag);
  291.  
  292.   /* Causes a DPSWaitContext to be done after each wrap.  Used during
  293.      debugging to isolate the cause of PS errors. */
  294.  
  295. #ifndef DPSNEXT_H
  296. #include "dpsNeXT.h"
  297. #endif DPSNEXT_H
  298.  
  299. #endif DPSCLIENT_H
  300.  
  301.