home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 164.lha / IPC / DemoSources / IPC.h < prev    next >
C/C++ Source or Header  |  1988-04-28  |  9KB  |  251 lines
  1. /*******************************************************************
  2.  *                                                                 *
  3.  *                           IPC.h                                 *
  4.  *                                                                 *
  5.  *           Inter-Process-Communication Message Format            *
  6.  *                                                                 *
  7.  *              Revision 1.2.1 -- 1988 July 31                     *
  8.  *                                                                 *
  9.  *         Copyright 1988 Peter da Silva & Peter Goodeve           *
  10.  *                      All Rights reserved                        *
  11.  *                                                                 *
  12.  *  This source is freely distributable, but should not be         *
  13.  *  modified without prior consultation with the authors.          *
  14.  *                                                                 *
  15.  *******************************************************************/
  16.  
  17. #ifdef AZTEC_C
  18. /* can't use prototyping */
  19. #define NARGS 1
  20. /* (if NARGS is undefined, prototyping is enabled) */
  21. #endif
  22.  
  23. #ifndef EXEC_TYPES_H
  24. #include "exec/types.h"
  25. #endif
  26.  
  27. #ifndef EXEC_PORTS_H
  28. #include "exec/ports.h"
  29. #endif
  30.  
  31. /*** Item Reference block -- an arbitrary number of these may be
  32.    put in an IPCMessage ***/
  33.  
  34. struct IPCItem {
  35.     ULONG   ii_Id;      /* four character ID (normally);
  36.                            determines exact meaning of IPCItem IDs */
  37.     ULONG   ii_Flags;   /* upper 16 bits have standard meaning;
  38.                            lower 16 bits are message dependent */
  39.     ULONG   ii_Size;    /* size of data structure (zero if ii_Ptr is not
  40.                            actually a pointer to data) */
  41.     void   *ii_Ptr;     /* points to defined data structure (could be within
  42.                            message block if IE_Flags says so) -- also may be
  43.                            recast to other 32-bit value (e.g. Lock) */
  44.     };
  45.  
  46.  
  47.  
  48. /*** The basic IPCMessage block ***/
  49.  
  50. struct IPCMessage {
  51.     struct Message  ipc_Msg;
  52.         /* ..ln_Name field should be NULL
  53.             mn_Length will include IPC_Items array and any in-line data
  54.         */
  55.     ULONG   ipc_Id,                /* four character (or other) ID */
  56.             ipc_Flags;
  57.     UWORD   ipc_ItemCount;         /* number of items in array */
  58.     struct  IPCItem ipc_Items[1];  /* .. actual size as needed */
  59.     };
  60.  
  61.  
  62. /*************************************************************/
  63.  
  64. /* Flags set by client (tentative...): */
  65. /* -- may appear in either IPCItem or IPCMessage Flags field */
  66.  
  67. #define IPC_TRANSFER   0x08000000
  68.     /* Data block ownership is to be transferred to receiver. */
  69. #define IPC_NETWORK    0x04000000
  70.     /* The data in this block/message may be transmitted to
  71.        another machine */
  72. #define IPC_INMESSAGE  0x02000000
  73.     /* The data in this block/message is included in the message length */
  74.  
  75. /* Flags returned by server (ditto): */
  76.  
  77. #define IPC_NOTKNOWN   0x80000000
  78.     /* The server could not handle this block/message
  79.        (either because it did not understand the ID or
  80.        was unable to process it -- see the secondary flags */
  81. #define IPC_MODIFIED   0x40000000
  82.     /* The server modified the data, either within the
  83.        supplied data block(s) or -- if permitted -- by
  84.        replacing/removing the block pointer; again maybe
  85.        other flag bits should indicate the nature of
  86.        the modification */
  87.  
  88. /* valid for Item only: */
  89. #define IPC_SERVER_OWNED 0x10000000
  90.     /* The server owns this data Item -- either because it has
  91.        created it or because it took it over from the client
  92.        (in which case it clears IPC_TRANSFER, which must have
  93.        been set) */
  94.  
  95.  
  96. /* secondary flag bits (more to come...): */
  97.  
  98. #define IPC_CHECKITEM 0x00800000
  99.     /* associated with IPC_NOTKNOWN -- indicates that one or more
  100.        particular items caused the flag to be set */
  101. #define IPC_FAILED 0x00400000
  102.     /* IPC_NOTKNOWN flag was set because the server failed to
  103.        handle an ID that it is designed to (rather than just
  104.        not recognizing the block) */
  105.  
  106. /*************************************************************/
  107.  
  108.  
  109. /*** IPC Ports and Procedures ***/
  110.  
  111.  
  112. /* -- see IPCPorts.h for actual structure definitions */
  113. #ifndef IPC_PORTS_H
  114. /* Normal user doesn't need access to port components,
  115.    so just use a convenient define.  Note that an IPC port
  116.    is NEVER in private data space -- or in the public port
  117.    list -- it is created and managed by the package routines
  118.    only. */
  119. #define IPCPort MsgPort
  120. #endif
  121.  
  122.  
  123. /* IPC Port Handling function prototypes: */
  124.  
  125. #ifndef NARGS /* define this to SUPPRESS function argument prototyping */
  126.  
  127. struct IPCPort * FindIPCPort(char *);
  128.     /* returns pointer to port if it exists -- null otherwise;
  129.        registers a new connection to the port */
  130.  
  131. struct IPCPort * GetIPCPort(char *);
  132.     /* returns pointer to port -- it is created if it doesn't exist;
  133.        registers a new connection to the port */
  134.  
  135.  
  136. void UseIPCPort(struct IPCPort *);
  137.     /* adds a connection to a port (passed by pointer from another
  138.        process) */
  139.  
  140.  
  141. void DropIPCPort(struct IPCPort *);
  142.     /* disconnect from port -- port will be destroyed if there are
  143.        no other connections left */
  144.  
  145.  
  146. struct IPCPort * ServeIPCPort(char *);
  147.     /* become a server for the named port (created if it doesn't exist);
  148.        null is returned if the port already has a server, otherwise a
  149.        pointer to it is returned */
  150.  
  151. void ShutIPCPort(struct IPCPort *);
  152.     /* (server only) prevent more messages being sent to this port, but
  153.        do not end server connection; remaining messages can be dealt
  154.        with before Leaving */
  155.  
  156. void LeaveIPCPort(struct IPCPort *);
  157.     /* cease to be a server for this port; another process can then
  158.        become a server if it desires */
  159.  
  160. CheckIPCPort(struct IPCPort *, UWORD);
  161.     /* returns number of current connections to this port (including
  162.        server); a call by the server (only) will also set the (user
  163.        settable) port flags to the value in the second argument --
  164.        currently the only valid flag is IPP_NOTIFY */
  165.  
  166.  
  167. PutIPCMsg(struct IPCPort *, struct IPCMessage *);
  168.     /* sends an IPCMessage to an IPCPort; if the port has no server or
  169.        is shut, the message is not sent and the function returns FALSE;
  170.        otherwise it returns TRUE. (Other port flags to be added later
  171.        may affect these actions.) */
  172.  
  173. struct IPCMessage * CreateIPCMsg(int, int, struct MsgPort *);
  174.     /* creates a standard IPCMessage block (in MEMF_PUBLIC) with the
  175.        number of IPCItems supplied as first argument;  the second
  176.        argument is the number of bytes -- if any -- to reserve beyond
  177.        that required for the items; the third is a pointer to the
  178.        ReplyPort (may be NULL -- note that it's a standard MsgPort,
  179.        not an IPCPort). (You always have to manage any data
  180.        blocks yourself). */
  181.  
  182.  
  183. void DeleteIPCMsg(struct IPCMessage *);
  184.     /* deletes a standard IPCMessage block;  you must first have disposed
  185.        of any attached data as appropriate */
  186.  
  187. /*************************************************************/
  188. #else NARGS defined
  189.  
  190. struct IPCPort * FindIPCPort ();
  191. struct IPCPort * GetIPCPort ();
  192. void             UseIPCPort ();
  193. void             DropIPCPort ();
  194. struct IPCPort * ServeIPCPort ();
  195. void             ShutIPCPort ();
  196. void             LeaveIPCPort ();
  197. int              CheckIPCPort ();
  198. int              PutIPCMsg ();
  199. struct IPCMessage * CreateIPCMsg ();
  200. void             DeleteIPCMsg ();
  201.  
  202. /*************************************************************/
  203. #endif NARGS
  204.  
  205.  
  206. /* System IPCPort flags: */
  207.  
  208. #define IPP_SERVED 0x8000
  209.     /* port currently has a server */
  210. #define IPP_SHUT 0x4000
  211.     /* port is no longer open for new messages (server still attached) */
  212. #define IPP_REOPEN 0x2000
  213.     /* set (by "Port Broker") to request that server reopen service
  214.        to this port after it has completed Shut/Leave sequence
  215.        in progress */
  216. #define IPP_LOADING 0x1000
  217.     /* set (by "Port Broker") to indicate that a server is being loaded
  218.        for this port (cleared by ServeIPCPort()) */
  219.  
  220.  
  221. /* Server settable Port flags: */
  222.  
  223. #define IPP_NOTIFY 0x0001
  224.     /* server wants to be signalled if connection is added or
  225.        dropped (the port sigbit is used to signal the task,
  226.        but no message is sent) */
  227.  
  228. /*************************************************************/
  229.  
  230. /*
  231.  *  Some useful Macros:
  232.  */
  233.  
  234. #define GetIPCMessage(port) ((struct IPCMessage *)GetMsg((struct MsgPort *)port))
  235.  
  236. #define ReplyIPCMessage(msg)  ReplyMsg((struct Message *)msg)
  237.  
  238. #define SigBitIPCPort(port) (1<<((struct MsgPort *)port)->mp_SigBit)
  239.     /* note: this will work whether or not IPCPorts.h has been included */
  240.  
  241.  
  242. /*
  243.    For convenience in creating IDs:
  244.     (Alternatively, your compiler may have multi-character constants,
  245.      which you may find more convenient (but less portable...))
  246. */
  247.  
  248. #define MAKE_ID(a,b,c,d) ((a)<<24L | (b)<<16L | (c)<<8 | (d))
  249.  
  250.  
  251.