Type Definitions

Protocol and Session Objects

The Protl and Sessn structures are the fundamental objects in the system. Most fields in the Protl and Sessn structures are not directly read or written by the programmer; those that are available to the programmer are so indicated in the comments.

 
		typedef struct protl {

				char         		*name;      				/* the protocol name, e.g., ``ethdrv'' */

				char         		*instName;  				/* the instance name, e.g., ``SE0'' */

				char         		*fullName;  				/* the name given in graph.comp, e.g., ``ethdrv/SE0'' */

				char         		*state;     				/* readable/writable */

				Binding      		binding;    				/* readable/writable */

				int          		id;

				int          		*traceVar;  				/* readable */

				/* pointers to protocols configured below this one */

				int          		numdown;    				/* readable - total number in down list */

				int          		downlistsz; 				/* size of downlist */

				struct protl 		*down[8];   				/* first 8 in down list */

				struct protl 		**downlist; 				/* overflow from down array */

				/* interface functions */

				XOpenFunc           				open;

				XOpenEnableFunc     				openenable;

				XOpenDisableFunc    				opendisable;

				XOpenDisableAllFunc 				opendisableall;

				XOpenDoneFunc       				opendone;

				XCloseDoneFunc      				closedone;

				XDemuxFunc          				demux;

				XCallDemuxFunc      				calldemux;

				XControlProtlFunc   				controlprotl;

		} *Protl;

 
		typedef struct sessn {

				char          		*state;     				/* readable/writable */

				Binding       		binding;    				/* readable/writable */

				int           		rcnt;

				unsigned char 		idle;

				/* pointers to open sessions below this one */

				int           		numdown;    				/* readable - total number in down list */

				int           		downlistsz; 				/* size of downlist */

				struct sessn  		*down[8];   				/* first 8 in down list */

				struct sessn  		**downlist; 				/* overflow from down array */

				/* interface functions */

				XCloseFunc           				close;

				XPopFunc             				pop;

				XCallPopFunc         				callpop;

				XPushFunc            				push;

				XCallFunc            				call;

				XControlSessnFunc    				controlsessn;

				XGetParticipantsFunc 				getparticipants;

				XDuplicateFunc       				duplicate;

				/* pointers to protocols associated with this session */

				struct protl  		*myprotl;   				/* session is an instance of this protocol */

				struct protl  		*up;        				/* session was created by this protocol */

				struct protl  		*hlpType;   				/* session was created on behalf of this protocol */

		} *Sessn;

If you think of the x-kernel as implementing protocol and session graphs, then each Protl represents a node in the protocol graph and each Sessn represents a node in the session graph. A protocol's down vector represents protocol graph edges; it contains pointers to the Protls that are below the protocol in the graph. The same is true for a session's down vector. The fields myprotl and up in the Sessn structure link a session to the protocols that own and created it, respectively.

For historical reasons, there are some fields in the actual Protl and Sessn structures that aren't shown in this document. These fields should not be used, as they will eventually be removed.

Enable Objects

Protocol writers use Enable objects to remember xOpenEnable calls. Typically, a protocol saves a pointer to an Enable object in its passive map, using mapBind. An Enable object has a field for reference counting. Calls to xOpenEnable with identical participants (the calls are redundant with respect to session creation) must be reference counted in order to properly handle xOpenDisable calls.

 
		typedef struct xenable {

				Protl   		hlp;     		/* upper protocol */

				Protl   		hlpType; 		/* upper protocol */

				Binding 		binding; 		/* from mapBind */

				int     		rcnt;    		/* use count */

		}Enable;

Return Values

Most routines have a return value type of XkReturn, which is either XK_SUCCESS or XK_FAILURE. Routines that return type Protl or Sessn have a failure value of ERR_PROTL or ERR_SESSN, respectively. Some message handling routines use type XkHandle (see Section 2.2.13). Severe error conditions will result in console error messages and the termination of the x-kernel .

Function Types

The following function typedefs are used in the Protl and Sessn structures.

 
		typedef struct sessn 		*(*XOpenFunc)(Protl, Protl, Protl, Part *);

		typedef XkReturn     		(*XOpenEnableFunc)(Protl, Protl, Protl, Part *);

		typedef XkReturn     		(*XOpenDisableFunc)(Protl, Protl, Protl, Part *);

		typedef XkReturn     		(*XOpenDisableAllFunc)(Protl, Protl);

		typedef XkReturn     		(*XOpenDoneFunc)(Protl, Protl, Sessn, Protl);

		typedef XkReturn     		(*XCloseDoneFunc)(Sessn);

		typedef XkReturn     		(*XDemuxFunc)(Protl, Sessn, Msg *);

		typedef XkReturn     		(*XCallDemuxFunc)(Protl, Sessn, Msg *, Msg *);

		typedef int          		(*XControlProtlFunc)(Protl, int, char *, int);

		typedef XkReturn     		(*XCloseFunc)(Sessn);

		typedef XkReturn     		(*XPopFunc)(Sessn, Sessn, Msg *, void *);

		typedef XkReturn     		(*XCallPopFunc)(Sessn, Sessn, Msg *, void *, Msg *);

		typedef XkHandle     		(*XPushFunc)(Sessn, Msg *);

		typedef XkReturn     		(*XCallFunc)(Sessn, Msg *, Msg *);

		typedef int          		(*XControlSessnFunc)(Sessn, int, char *, int);

		typedef Part         		*(*XGetParticipantsFunc)(Sessn);

		typedef XkReturn     		(*XDuplicateFunc)(Sessn);