home *** CD-ROM | disk | FTP | other *** search
/ NeXTSTEP 3.0 / NeXTSTEP3.0.iso / NextDeveloper / Headers / dpsclient / dpsfriends.h < prev    next >
Text File  |  1992-02-22  |  14KB  |  383 lines
  1.  
  2. /*
  3.   dpsfriends.h -- Low-level interface to the Display PostScript Library.
  4.       Imported by the output of pswrap.
  5.  
  6.   This interface is intended to be identical across different implementations
  7.   of the Display PostScript System, except for items explicitly identified
  8.   below as system-dependent, and lists explicitly identified below as
  9.   extensible. System-dependent items may be redefined, and items may be added
  10.   to extensible lists, but existing items in these lists may not be changed or
  11.   deleted.
  12.   
  13.   We expect there to be little if any need to make extensions. If you do feel
  14.   the need, it is&Dely that you are doing something wrong. Such extensions
  15.   hinder the portability of Display PostScript applications.
  16.  
  17.   Copyright (c) 1988 Adobe Systems Incorporated.
  18.   All rights reserved.
  19.   
  20. */
  21.  
  22. #ifndef    DPSFRIENDS_H
  23. #define    DPSFRIENDS_H
  24.  
  25. #import <stdarg.h>
  26.  
  27. /*=== CONSTANTS ===*/
  28.  
  29. /* TokenType values, used to specify the format of numeric values
  30.    for the system on which the client library is built. See DPS language
  31.    reference manual */
  32.  
  33. #define DPS_HI_IEEE    128
  34. #define DPS_LO_IEEE    129
  35. #define DPS_HI_NATIVE    130
  36. #define DPS_LO_NATIVE    131
  37.   
  38. #ifndef DPS_DEF_TOKENTYPE
  39. #ifdef __BIG_ENDIAN__
  40. #define DPS_DEF_TOKENTYPE    DPS_HI_IEEE
  41. #else
  42. #define DPS_DEF_TOKENTYPE    DPS_LO_IEEE
  43. #endif
  44. #endif  DPS_DEF_TOKENTYPE
  45.  
  46.   /* DPS_DEF_TOKENTYPE is the specification code for the form of binary
  47.      object sequences generated by PSWrap. The C code generated by pswrap
  48.      references this name. DPS_DEF_TOKENTYPE is system-dependent. */
  49.  
  50.  
  51. /* --- binary object sequence support --- */
  52.  
  53. /* Object attributes & types: Values for attributedTypes */
  54.  
  55. #define DPS_LITERAL    0
  56. #define DPS_EXEC    0x080
  57.  
  58.   /* Attribute masks */
  59.  
  60.  
  61. #define DPS_NULL    0
  62. #define DPS_INT        1
  63. #define DPS_REAL    2
  64. #define DPS_NAME    3
  65. #define DPS_BOOL    4
  66. #define DPS_STRING    5
  67. #define DPS_IMMEDIATE    6
  68. #define DPS_ARRAY    9
  69. #define    DPS_MARK    10
  70.  
  71.   /* Type values */
  72.  
  73.  
  74. /* Object sequence constants */
  75.  
  76. #define DPS_HEADER_SIZE        4
  77. #define DPS_EXT_HEADER_SIZE    8
  78.  
  79.  
  80. /*=== TYPES ===*/ 
  81.      
  82. typedef enum {
  83.   dps_ascii, dps_binObjSeq, dps_encodedTokens
  84.   } DPSProgramEncoding;
  85.   /* Defines the 3 possible encodings of PostScript language programs. */
  86.      
  87. typedef enum {
  88.   dps_indexed, dps_strings
  89.   } DPSNameEncoding;
  90.   /* Defines the 2 possible encodings for user names in the
  91.      dps_binObjSeq and dps_encodedTokens forms of PostScript language
  92.      programs. */     
  93.   
  94. typedef enum {
  95.   dps_tBoolean,
  96.   dps_tChar,    dps_tUChar,
  97.   dps_tFloat,    dps_tDouble,
  98.   dps_tShort,    dps_tUShort,
  99.   dps_tInt,    dps_tUInt,
  100.   dps_tLong,    dps_tULong } DPSDefinedType;
  101.   
  102.   /* Enumerates the C data types that can be used to describe wrap
  103.      parameters. */
  104.   
  105. typedef enum {        /* NeXT addition */
  106.   dps_machServer,    /* a mach binary connection to a window server */
  107.   dps_fdServer,        /* a socket binary connection to a window server */
  108.   dps_stream        /* an ascii NXStream */
  109.   } DPSContextType;
  110.   /* Enumerates the context types th&De support. */
  111.  
  112. typedef struct {
  113.   DPSDefinedType type;
  114.   int count;
  115.   char *value;
  116.   } DPSResultsRec, *DPSResults;
  117.   
  118.   /* A DPSResultsRec defines one of the formal result args of a wrapped
  119.      procedure.  The 'type' field specifies the formal type of the
  120.      return value. The 'count' field specifies the number of values
  121.      expected (this supports array formals). The 'value' field points
  122.      to the location of the first value; the storage beginning there
  123.      must have room for count values of type.   If 'count' == -1, then
  124.      'value' points to a scalar (single) result arg. */
  125.  
  126. typedef struct {
  127.   int lastNameIndex;
  128.   struct _t_DPSSpaceProcsRec const * procs;
  129.   } DPSSpaceRec, *DPSSpace;
  130.  
  131.   /* A DPSSpaceRec provides a representation of a space.
  132.      
  133.      The DPSSpaceRec may be extended to include system-specific items.
  134.  
  135.      BEWARE an implementation of the DPS client library is also likely to
  136.      extend the DPSSpaceRec to include implementation-dependent information
  137.      in additional fields. */
  138.  
  139. typedef struct _t_DPSSpaceProcsRec {
  140.   void (*DestroySpace)( DPSSpace space );
  141.        /* See DPSDestroySpace() in dpsclient.h */
  142.   } DPSSpaceProcsRec, *DPSSpaceProcs;
  143.   
  144.   /* The DPSSpaceProcsRec may be extended to include system-specific items */
  145.   
  146. typedef struct _t_DPSContextRec {
  147.   char *priv;
  148.   DPSSpace space;
  149.   DPSProgramEncoding programEncoding;
  150.   DPSNameEncoding nameEncoding;
  151.   struct _t_DPSProcsRec const * procs;
  152.   void (*textProc)();
  153.   void (*errorProc)();
  154.   DPSResults resultTable;
  155.   unsigned int resultTableLength;
  156.   struct _t_DPSContextRec *chainParent, *chainChild;
  157.   DPSContextType type;        /* NeXT addition - denotes type of context */
  158.   } DPSContextRec, *DPSContext;
  159.   
  160.   /* A DPSContextRec provides a representation of a context.
  161.   
  162.      The 'priv' field is provided for use by application code. It is
  163.      initialized to NULL and is not touched thereafter by the client
  164.      library implementation.
  165.      
  166.      The 'space' field is the space to which the context belongs.  The
  167.      'programEncoding' and 'nameEncoding' fields describe the encodings
  168.      preferred by the context (server). The values in these fields are
  169.      established when the DPSContext is created and cannot be changed
  170.      therafter. The 'procs' field points to a vector of procedures
  171.      (in a DPSProcsRec) that implement the context oper&Dns.
  172.  
  173.      The 'textProc' and 'errorProc' are called by the client library
  174.      implementation to dispose of ascii text and errors, respectively, that
  175.      the PostScript interpreter produces.
  176.      
  177.      The 'resultTableLength' and 'resultTable' fields define the number, type
  178.      and location of values expected back from the PostScript interpreter.
  179.      They should be set up before writing any PostScript language that
  180.      may return values.
  181.      
  182.      The chainParent field is non-NIL if this context automatically receives
  183.      a copy of any PostScript language sent to the referenced (parent) context.
  184.      
  185.      The chainChild field is non-NIL if this context automatically sends
  186.      a copy of any PostScript language it receives to the referenced (child)
  187.      context.
  188.      
  189.      The type field is used by the client library to tag different types
  190.      of contexts.
  191.      
  192.      NOTE the client library implementation extends the DPSContextRec to
  193.      include implementation-dependent information in additional fields.
  194.      
  195.      You may read the fields of a DPSContextRec directly, but you should
  196.      never modify them directly. Use the macros provided for that purpose. */
  197.  
  198. typedef struct _t_DPSProcsRec {
  199.   void (*BinObjSeqWrite)( DPSContext ctxt, const void *buf, unsigned int count );
  200.        /* Begin a new binary object sequence. 'buf' contains 'count'
  201.       bytes of a binary object sequence. 'buf' must point to the
  202.       beginning of a sequence, which includes at least the header
  203.       and the entire top-level sequence of objects.  It may also
  204.       include subsidiary array elements and/or string chars.
  205.       Writes PostScript language as specified by the
  206.       encoding variables of ctxt, doing appropriate conversions as
  207.       needed. 'buf' and its contents must remain valid until the
  208.       entire binary object sequence has been sent. */
  209.   void (*WriteTypedObjectArray)(
  210.             DPSContext ctxt,
  211.             DPSDefinedType type,
  212.             const void *array,
  213.             unsigned int length );
  214.        /* 'array' points at an array of 'length' elements of 'type'.
  215.       'array' contains the element values for the body of a subsidiary
  216.       array in a binary object sequence. Writes PostScript language
  217.       as specified by the 4 format and encoding variables of ctxt, doing
  218.       appropriate conversions as needed. 'array' and its contents must
  219.       rema&D alid until the entire binary object sequence has been sent. */
  220.   void (*WriteStringChars)( DPSContext ctxt, const char *buf, unsigned int count );
  221.        /* Used both to implement DPSWritePostScript and to send the bodies of
  222.           strings in binary object sequences. 'buf' contains 'count' bytes.
  223.       For the latter, 'buf' and its contents must remain valid until the
  224.       entire binary object sequence has been sent.*/
  225.   void (*WriteData)( DPSContext ctxt, const void *buf, unsigned int count );
  226.        /* See DPSWriteData() in dpsclient.h */
  227.   void (*WritePostScript)( DPSContext ctxt, const void *buf, unsigned int count );
  228.        /* See DPSWritePostScript() in dpsclient.h */
  229.   void (*FlushContext)( DPSContext ctxt );
  230.        /* See DPSFlushContext() in dpsclient.h */
  231.   void (*ResetContext)( DPSContext ctxt );
  232.        /* See DPSResetContext() in dpsclient.h */
  233.   void (*UpdateNameMap)( DPSContext ctxt );
  234.        /* This routine is called if the context's space's name map is
  235.           out-of-sync with that of the client library's name map. It may
  236.           send a series of "defineusername" commands to the service. */
  237.   void (*AwaitReturnValues)( DPSContext ctxt );
  238.        /* Called to receive return values.
  239.           ctxt->resultTableLength and ctxt->resultTable must have been
  240.           set previously. Returns when all expected results are received.
  241.      
  242.           This is normally called from wraps. It is unusual for an application
  243.           program to call this directly.
  244.      
  245.           See the definitions of DPSResultsRec and DPSContextRec for more info.
  246.       */
  247.   void (*Interrupt)( DPSContext ctxt );
  248.        /* See DPSInterrupt() in dpsclient.h */
  249.   void (*DestroyContext)( DPSContext ctxt );
  250.        /* See DPSDestroyContext() in dpsclient.h */
  251.   void (*WaitContext)( DPSContext ctxt );
  252.        /* See DPSWaitContext() in dpsclient.h */
  253.   void (*Printf)( DPSContext ctxt, const char *fmt, va_list argList );
  254.        /* See DPSPrintf() in dpsclient.h */
  255.   void (*WriteNumString)( 
  256.             DPSContext ctxt,
  257.             DPSDefinedType type,
  258.             const void *array,
  259.             unsigned int count,
  260.             int scale );
  261.        /* Translates the arguments into an homogenous number array encoded
  262.       as a string and writes the string to the context.
  263.       */
  264.   } DPSProcsRec, *DPSProcs;
  265.  
  266.   /* The DPSProcsRec may be extended t&D!clude system-specific items */
  267.  
  268. /* -- binary object sequence support -- */
  269.  
  270. #define DPSSYSNAME    0x0FFFF        /* unsigned rep. of -1 */
  271.  
  272. typedef struct {
  273.     unsigned char attributedType;
  274.     unsigned char tag;
  275.     unsigned short length;
  276.     long int val;
  277. } DPSBinObjGeneric;    /* boolean, int, string, name and array */
  278.  
  279.  
  280. typedef struct {
  281.     unsigned char attributedType;
  282.     unsigned char tag;
  283.     unsigned short length;
  284.     float realVal;
  285. } DPSBinObjReal;    /* float */
  286.  
  287.  
  288. typedef struct {
  289.     unsigned char attributedType;
  290.     unsigned char tag;
  291.     unsigned short length;
  292.     union {
  293.         long int integerVal;
  294.         float realVal;
  295.         long int nameVal;    /* offset or index */
  296.         long int booleanVal;
  297.         long int stringVal;  /* offset */
  298.         long int arrayVal;  /* offset */
  299.     } val;
  300. } DPSBinObjRec, *DPSBinObj;
  301.  
  302. typedef struct {
  303.     unsigned char tokenType;
  304.     unsigned char nTopElements;
  305.     unsigned short length;
  306.     DPSBinObjRec objects[1];
  307. } DPSBinObjSeqRec, *DPSBinObjSeq;
  308.  
  309. typedef struct {
  310.     unsigned char tokenType;
  311.     unsigned char escape;  /* zero if this is an extended sequence */
  312.     unsigned short nTopElements;
  313.     unsigned long length;
  314.     DPSBinObjRec objects[1];
  315. } DPSExtendedBinObjSeqRec, *DPSExtendedBinObjSeq;
  316.     
  317.  
  318. /*=== PROCEDURES ===*/
  319.  
  320. #define DPSAwaitReturnValues(ctxt)\
  321.   (*(ctxt)->procs->AwaitReturnValues)((ctxt))
  322.   
  323. #define DPSUpdateNameMap(ctxt)\
  324.   (*(ctxt)->procs->UpdateNameMap)((ctxt))
  325.   
  326. #define DPSBinObjSeqWrite(ctxt, buf, count)\
  327.   (*(ctxt)->procs->BinObjSeqWrite)((ctxt), (buf), (count))
  328.   
  329. #define DPSPrivCurrentContext() (DPSGetCurrentContext())
  330.     
  331. extern void DPSSetContext( DPSContext ctxt );
  332.  
  333.   /* Set the default context. Used in conjunction with psops.h and with
  334.      wraps that are defined without an explicit DPSContext argument. */
  335.  
  336. extern DPSContext DPSGetCurrentContext(void);
  337.  
  338.   /* Get the default context. Used in conjunction with psops.h and with
  339.      wraps that are defined without an explicit DPSContext argument. 
  340.      Initially NULL. */
  341.  
  342. #define DPSWriteStringChars(ctxt, buf, count)\
  343.   (*(ctxt)->procs->WriteStringChars)((ctxt), (buf), (count))
  344.   
  345. #define DPSWriteTypedObjectArray(ctxt, type, array, length)\
  346.   (*(ctxt)->procs->WriteTypedObjectArray)((ctxt), (type), (array), (length))
  347.  
  348. #define DPSSetResultTable(ctxt, tbl, len)\
  349.   (ctxt)->resultTable = (tbl);\&D"ctxt)->resultTableLength = (len)
  350.   
  351.  
  352. /* Support for user names */
  353.  
  354. extern void DPSMapNames(
  355.   DPSContext ctxt,
  356.   unsigned int nNames,
  357.   const char * const *names,
  358.   long int * const *indices );
  359.   
  360.   /* This routine assigns indices to the given user names. It is
  361.      called once for each wrapped procedure. The parameters 'nNames' and
  362.      'names' define an array of strings which are the user names. The
  363.      parameter 'indices' is an array of (int *) which are the locations
  364.      in which to store the indices. The caller must ensure that the string
  365.      pointers remain valid after the return. 
  366.      
  367.      As a storage optimization, DPSMapNames will interpret a NIL
  368.      value in the names array as the previous valid string in
  369.      the name array. Effectively, if names[n] == NIL, DPSMapNames
  370.      will decrement n until names[] is non-NIL and use that string.
  371.      names[0] must be non-NIL. */
  372.      
  373. extern const char *DPSNameFromIndex( int index );
  374.  
  375.   /* This routine returns the text for the user name with the given index. 
  376.      The string returned is owned by the library (treat it as readonly). */
  377.  
  378. #define DPSWriteNumString(ctxt, type, array, count, scale)\
  379.   (*(ctxt)->procs->WriteNumString)((ctxt), (type), (array), (count), (scale))
  380.  
  381. #endif    DPSFRIENDS_H
  382.  
  383.