pete@violet.berkeley.edu (Pete Goodeve) (04/28/88)
Alright -- I finally got some time to write some code again.
Here is the first "REAL" -- i.e. working -- version of the
InterPeterMessage header file. (That's OK -- I'm quite happy
to be called Peter, too.)
The code that goes along with the prototype functions does exist too -- and
appears to work cleanly. I'd better not post anything until I do some
commenting, though. A proper write up on the whole system is another vital
necessity. I hope you can understand IPC.h at this point from its internal
comments and all the previous postings.
Apologies for putting a copyright notice on it. This isn't in any sense
for commercial purposes. This code will always be free for both personal
and commercial use. The idea of the notice is just to keep a little
control over things if possible.
Feedback is expected (or do I mean inevitable...)
-- Pete --
________________________________________________________________________
/*******************************************************************
* *
* IPC.h *
* *
* Inter-Process-Communication Message Format *
* *
* Revision 0.0 -- 1988 April 27 *
* *
* Copyright 1988 Peter da Silva & Peter Goodeve *
* All Rights reserved *
* *
* This source is freely distributable, but should not be *
* modified without prior consultation with the authors. *
* *
*******************************************************************/
#ifndef EXEC_TYPES_H
#include "exec/types.h"
#endif
#ifndef EXEC_PORTS_H
#include "exec/ports.h"
#endif
/*** Item Reference block -- an arbitrary number of these may be
put in an IPCMessage ***/
struct IPCItem {
ULONG ii_Id; /* four character ID (normally);
determines exact meaning of IPCItem IDs */
ULONG ii_Flags; /* upper 16 bits have standard meaning;
lower 16 bits are message dependent */
ULONG ii_Size; /* size of data structure (zero if ii_Ptr is not
actually a pointer to data) */
void *ii_Ptr; /* points to defined data structure (could be within
message block if IE_Flags says so) -- also may be
recast to other 32-bit value (e.g. Lock) */
};
/*** The basic IPCMessage block ***/
struct IPCMessage {
struct Message ipc_Msg;
/* ..ln_Name field should be NULL
mn_Length will include IPC_Items array and any in-line data
*/
ULONG ipc_Id, /* four character (or other) ID */
ipc_Flags;
UWORD ipc_ItemCount; /* number of items in array */
struct IPCItem ipc_Items[1]; /* .. actual size as needed */
};
/*************************************************************/
/* Flags set by client (tentative...): */
/* -- may appear in either IPCItem or IPCMessage Flags field */
#define IPC_TRANSFER 0x08000000
/* Data block ownership may be transferred to server */
#define IPC_NETWORK 0x04000000
/* The data in this block/message may be transmitted to
another machine */
#define IPC_INMESSAGE 0x02000000
/* The data in this block/message is included in the message length */
/* Flags returned by server (ditto): */
#define IPC_NOTKNOWN 0x80000000
/* The server could not handle this block/message
(either because it did not understand the ID or
was unable to process it -- maybe this should be
two flag bits?): */
#define IPC_MODIFIED 0x40000000
/* The server modified the data, either within the
supplied data block(s) or -- if permitted -- by
replacing/removing the block pointer; again maybe
other flag bits should indicate the nature of
the modification: */
/* valid for Item only: */
#define IPC_SERVER_OWNED 0x10000000
/* The server owns this data Item -- either because it has
created it or because it took it over from the client
(in which case it clears IPC_TRANSFER, which must have
been set) */
/*************************************************************/
/*** IPC Ports and Procedures ***/
/* -- see IPCPorts.h for actual structure definitions */
#ifndef IPC_PORTS_H
/* Normal user doesn't need access to port components,
so just use a convenient define. Note that an IPC port
is NEVER in private data space -- or in the public port
list -- it is created and managed by the package routines
only. */
#define IPCPort MsgPort
#endif
/* IPC Port Handling function prototypes: */
struct IPCPort * FindIPCPort(char *);
/* returns pointer to port if it exists -- null otherwise;
registers a new connection to the port */
struct IPCPort * GetIPCPort(char *);
/* returns pointer to port -- it is created if it doesn't exist;
registers a new connection to the port */
void DropIPCPort(struct IPCPort *);
/* disconnect from port -- port will be destroyed if there are
no other connections left */
struct IPCPort * ServeIPCPort(char *);
/* become a server for the named port (created if it doesn't exist);
null is returned if the port already has a server, otherwise a
pointer to it is returned */
void ShutIPCPort(struct IPCPort *);
/* (server only) prevent more messages being sent to this port, but
do not end server connection; remaining messages can be dealt
with before Leaving */
void LeaveIPCPort(struct IPCPort *);
/* cease to be a server for this port; another process can then
become a server if it desires */
CheckIPCPort(struct IPCPort *, USHORT);
/* returns number of current connections to this port (including
server); a call by the server (only) will also set the (user
settable) port flags to the value in the second argument --
currently the only valid flag is IPP_NOTIFY */
PutIPCMsg(struct IPCPort *, struct IPCMessage *);
/* sends an IPCMessage to an IPCPort; if the port has no server or
is shut, the message is not sent and the function returns FALSE;
otherwise it returns TRUE. (Other port flags to be added later
may affect these actions.) */
struct IPCMessage * CreateIPCMsg(int);
/* creates a standard IPCMessage block (in MEMF_PUBLIC) with the
number of IPCItems supplied as argument ( special cases -- like
in line data -- you will have to handle yourself, and you always
have to manage the data blocks yourself). */
void DeleteIPCMsg(struct IPCMessage *);
/* deletes a standard IPCMessage block; you must first have disposed
of any attached data as appropriate */
/* Server settable Port flags: */
#define IPP_NOTIFY 0x0001
/* server wants to be signalled if connection is added or dropped
(the port sigbit is used to signal the task,
but no message is sent) */
/*************************************************************/