fifo_event.h

界面程序

/*************************************************************************

NAME
	fifo_event.h  -  Rabbit IPC "glue" interface fifo event header file


DESCRIPTION
	This header file contains data structures and #defines needed by 
	applications which use FIFOs (named pipes) as event mechanisms.

	At the lowest level, a process can use a FIFO as an event mechanism
	by performing all necessary system calls and setting up the FIFO_EVENT 
	data structure with the information which describes the FIFO to other 
	processes. Once published, this FIFO information can be learned by
	other processes which can then use the learned information to post
	events to the FIFO. 

	To make this whole process a bit easier, the FIFO event interface
	provides a higher level calling interface which makes certain 
	assumptions about how the FIFO is to be used.

	A process can set up a FIFO as an event mechanism by calling 
	fevCreate() before publishing. fevCreate() loads a predetermined
	temporary file template from the Rabbit IPC map file, creates a
	file name from that template, and then creates and opens a FIFO
	using the built path name. It is assumed that the creator of the
	FIFO is the process which will be reading the FIFO. The FIFO is
	opened in read/write mode so there are no problems reading from
	the FIFO before a writer exists. This is necessary because the
	FIFO may need to be created and published before a learner process
	is available to post events to it. There is one argument to 
	fevCreate() - a pointer to a FIFO event structure. The value of
	the fev_id field of this data structure will be published as the 
	message ID to be sent to the publisher on the FIFO to indicate 
	is read. This allows the publisher to specify a special ID (such
	as a process ID) to be used for messages from different processes
	talking to the publisher. All other fields of the FIFO_EVENT data
	structure will be filled in by fevCreate(). fevCreate() returns
	SUCCEED or FAIL. 

	After creating a FIFO, a publisher can call fevRead() to read a
	message from the event FIFO. This call will pend, and can be 
	called by the alternate name fevWait(). A pointer to a FIFO_EVENT
	data structure is expected as an argument, along with a pointer
	to an integer area to store the read message ID into. fevRead()
	returns SUCCEED or FAIL.

	fevDestroy() is used to destroy a previously created event FIFO.
	It takes a FIFO_EVENT structure pointer as an argument and returns
	SUCCEED or FAIL.

	A process which learns about a FIFO event being used by a publsiher
	should call fevLearn() with the learned FIFO_EVENT structure pointer
	after learning about the publisher via ipcLearn(). fevLearn() will
	open the FIFO for writing so the learner can post events to the FIFO. 
	The event which is posted is an integer value set up by the publisher
	in the fev_id field of the FIFO_EVENT data structure. fevLearn()
	returns SUCCEED or FAIL.

	fevPostEvent() and fevDSInit() are functions called internally by
	other IPC glue functions.

	The global error status holder "fev_errno" can be queried on
	function failures to determine the cause of the error.

Copyright 1993 by Rabbit Software Corporation
*************************************************************************/

#ifndef _FIFO_EVENT_H_
#define _FIFO_EVENT_H_

#ifdef HEADERVERSIONS
static char *_fifo_event_h_ = "@(#)fifo_event.h	1.3 !R2";
#endif /* HEADERVERSIONS */

#define NO_FIFO_DESC	FAIL		/* FIFO descriptor initializer	*/

typedef byte FEV_ID;			/* FIFO ID type			*/

typedef struct
{
    PathName   fev_path;		/* path name of FIFO		*/
    FEV_ID     fev_id;			/* ID (message) put on FIFO	*/
    int	       fev_rdesc;		/* read descriptor of FIFO	*/
    int	       fev_wdesc;		/* write descriptor of FIFO	*/
} FIFO_EVENT;

/* Macro to check if a given FIFO event is being used.			*/
#define FIFO_USED(fifo_event) 	(fifo_event.fev_path[0] != EOS)

#define FID_DEFAULT	(byte) 'x';	/* default FIFO event ID	*/

/* Definitions of event FIFO error codes.		*/
#define FEV_NOERROR	0		/* no error (initializer)	*/
#define FEV_MAPNAME	1		/* mapname error		*/
#define FEV_MKTEMP	2		/* failed to make temp. file	*/
#define FEV_MKFIFO	3		/* failed to make FIFO		*/
#define FEV_OPEN	4		/* failed to open FIFO		*/
#define FEV_CLOSE	5		/* failed to close FIFO		*/
#define FEV_UNLINK	6		/* failed to unlink FIFO	*/
#define FEV_WRITE	7		/* failed to write to FIFO	*/
#define FEV_READ	8		/* failed to read from FIFO	*/
#define FEV_NOTOPEN	9		/* FIFO has not been opened	*/	

extern void fevDSInit	(
				/*
				FIFO_EVENT *p_fifo_event
				*/
			);

extern int fevCreate	(	
				/* 
				FIFO_EVENT *p_fifo_event
				*/
			);

extern int fevDestroy	(	
				/* 
				FIFO_EVENT *p_fifo_event
				*/
			);

extern int fevRead	(	/* 
				FIFO_EVENT *p_fifo_event, 
				int	   *p_msgid
				*/
			);

#define fevWait(p_fifo_event, p_msgid)	fevRead(p_fifo_event, p_msgid)

extern int fevLearn	(	
				/* 
				FIFO_EVENT *p_fifo_event
				*/
			);

extern int fevPostEvent	(	
				/* 
				FIFO_EVENT *p_fifo_event 
				*/
			);

extern int fev_errno;

#endif /* _FIFO_EVENT_H_ */