/*
 *	token.h
 *
 *	Copyright (c) 1993 - 1995 by DataBeam Corporation, Lexington, KY
 *
 *	Abstract:
 *		This is the interface file for the Token class.  Objects of this class
 *		represent tokens in the MCS environment.  Whenever a token is allocated
 *		by a user, one of these objects is created.  Its job is to handle all
 *		requests that are specific to the token ID with which it is associated.
 *
 *		Tokens in the MCS environment are used for critical resource management.
 *		The exact use of tokens is up to the user applications attaching to
 *		MCS.  They are provided as a generic resource.
 *
 *		Tokens can be "owned" by one or more users.  There are two types of
 *		ownership.  There is exclusive ownership, where only one user can
 *		own the token at a time.  That user has "grabbed" the token.  And there
 *		is non-exclusive ownership, where several users can own the token at
 *		the same time.  Those users have "inhibited" the token.  It is not
 *		possible to mix exclusive and non-exclusive ownership.
 *
 *		If a user has grabbed a token, that same user can inhibit the token,
 *		thus converting to non-exclusive ownership.  Similarly, if a user is
 *		the sole inhibitor of a token, that user can grab the token, thus
 *		converting to exclusive ownership.
 *
 *		During a domain merge operation, it is necessary to merge tokens upward
 *		to the new Top Provider of the enlarged domain.  This class also defines
 *		a member function allowing it to be told to issue a merge request with
 *		all of its state contained therein.
 *
 *	Caveats:
 *		None.
 *
 *	Author:
 *		James P. Galvin, Jr.
 */
#ifndef	_TOKEN_
#define	_TOKEN_

/*
 *	This is the class definition for the Token class.
 */
class	Token
{
public:

	Token (
			TokenID				token_id,
			PDomain             local_provider,
			PConnection         top_provider,
			CChannelList2      *channel_list,
			CAttachmentList    *attachment_list);
	Token (
			TokenID				token_id,
			PDomain             local_provider,
			PConnection         top_provider,
			CChannelList2      *channel_list,
			CAttachmentList    *attachment_list,
			TokenState			token_state,
			UserID				grabber,
			CUidList           *inhibitor_list,
			UserID				recipient);
	~Token ();

    void    SetTopProvider(PConnection top_provider) { m_pConnToTopProvider = top_provider; }
    BOOL    IsTopProvider(void) { return (m_pConnToTopProvider == NULL); }

				TokenState	GetTokenState () { return (Token_State); };
				BOOL    	IsValid ();
				Void		IssueMergeRequest ();
		Void		TokenGrabRequest (
									CAttachment        *originator,
									UserID				uidInitiator,
									TokenID				token_id);
		Void		TokenGrabConfirm (
									Result				result,
									UserID				uidInitiator,
									TokenID				token_id,
									TokenStatus			token_status);
		Void		TokenInhibitRequest (
									CAttachment        *originator,
									UserID				uidInitiator,
									TokenID				token_id);
		Void		TokenInhibitConfirm (
									Result				result,
									UserID				uidInitiator,
									TokenID				token_id,
									TokenStatus			token_status);
		Void		TokenGiveRequest (
									CAttachment        *originator,
									PTokenGiveRecord	pTokenGiveRec);
		Void		TokenGiveIndication (
									PTokenGiveRecord	pTokenGiveRec);
		Void		TokenGiveResponse (
									Result				result,
									UserID				receiver_id,
									TokenID				token_id);
		Void		TokenGiveConfirm (
									Result				result,
									UserID				uidInitiator,
									TokenID				token_id,
									TokenStatus			token_status);
		Void		TokenPleaseRequest (
									UserID				uidInitiator,
									TokenID				token_id);
		Void		TokenPleaseIndication (
									UserID				uidInitiator,
									TokenID				token_id);
		Void		TokenReleaseRequest (
									CAttachment        *originator,
									UserID				uidInitiator,
									TokenID				token_id);
		Void		TokenReleaseConfirm (
									Result				result,
									UserID				uidInitiator,
									TokenID				token_id,
									TokenStatus			token_status);
		Void		TokenTestRequest (
									CAttachment        *originator,
									UserID				uidInitiator,
									TokenID				token_id);
		Void		TokenTestConfirm (
									UserID				uidInitiator,
									TokenID				token_id,
									TokenStatus			token_status);

	private:
				BOOL    	ValidateUserID (
									UserID				user_id);
			CAttachment    *GetUserAttachment (
									UserID				user_id);
				Void		IssueTokenReleaseIndication (
									UserID				user_id);
				Void		BuildAttachmentList (
									CUidList            *user_id_list,
									CAttachmentList     *attachment_list);

		TokenID				Token_ID;
		PDomain             m_pDomain;
		PConnection         m_pConnToTopProvider;
		CChannelList2      *m_pChannelList2;
		CAttachmentList    *m_pAttachmentList;
		TokenState			Token_State;
		UserID				m_uidGrabber;
		CUidList			m_InhibitorList;
		UserID				m_uidRecipient;
};

/*
 *	Token (
 *			TokenID				token_id,
 *			PDomain     		local_provider,
 *			PConnection 		top_provider,
 *			PChannelList		channel_list,
 *			PAttachmentList		attachment_list)
 *
 *	Functional Description:
 *		This is the constructor for the Token class.  It simply initializes
 *		local instance variables with the passed in values.  It also marks
 *		the state of the token as available.
 *
 *	Formal Parameters:
 *		token_id (i)
 *			This is the token ID that this token object is associated with.
 *		local_provider (i)
 *			This is a pointer to the local provider.  A Token object will
 *			never actually send a command to the local provider, but it needs
 *			this value to use a parameter when it sends commands to various
 *			attachments (since it is doing so on behalf of the local provider).
 *		top_provider (i)
 *			This is a pointer to the top provider.  This is used by the
 *			Token object when it needs to issue a request to the Top
 *			Provider.
 *		channel_list (i)
 *			This is a pointer to the domain's channel list, which identifies
 *			all valid channels in the domain.  This is used by token objects
 *			to validate user IDs.
 *		attachment_list (i)
 *			This is a pointer to the domain's attachment list, which identifies
 *			all valid attachments in the domain.  This is used by token
 *			objects to validate joined attachments.
 *
 *	Return Value:
 *		None.
 *
 *	Side Effects:
 *		None.
 *
 *	Caveats:
 *		None.
 */

/*
 *	Token (
 *			TokenID				token_id,
 *			PDomain     		local_provider,
 *			PConnection 		top_provider,
 *			PChannelList		channel_list,
 *			PAttachmentList		attachment_list,
 *			TokenState			token_state,
 *			UserID				grabber,
 *			CUidList           *inhibitor_list,
 *			UserID				recipient)
 *
 *	Functional Description:
 *		This is the constructor for the Token class.  It simply initializes
 *		local instance variables with the passed in values.  It also marks
 *		the state of the token as available.
 *
 *	Formal Parameters:
 *		token_id (i)
 *			This is the token ID that this token object is associated with.
 *		local_provider (i)
 *			This is a pointer to the local provider.  A Token object will
 *			never actually send a command to the local provider, but it needs
 *			this value to use a parameter when it sends commands to various
 *			attachments (since it is doing so on behalf of the local provider).
 *		top_provider (i)
 *			This is a pointer to the top provider.  This is used by the
 *			Token object when it needs to issue a request to the Top
 *			Provider.
 *		channel_list (i)
 *			This is a pointer to the domain's channel list, which identifies
 *			all valid channels in the domain.  This is used by token objects
 *			to validate user IDs.
 *		attachment_list (i)
 *			This is a pointer to the domain's attachment list, which identifies
 *			all valid attachments in the domain.  This is used by token
 *			objects to validate joined attachments.
 *		token_state (i)
 *			This is the state of the token being merged.
 *		grabber (i)
 *			This is the user ID of the user who has the token grabbed (this is
 *			only valid if the token state is grabbed or giving).
 *		inhibitor_list (i)
 *			This is a list of the users who have the token inhibited (this is
 *			only valid if the token state is inhibited).
 *		recipient (i)
 *			This is the user ID of the user who is being offered the token
 *			as part of a give operation (this is only valid if the token state
 *			is giving or given).
 *
 *	Return Value:
 *		None.
 *
 *	Side Effects:
 *		None.
 *
 *	Caveats:
 *		None.
 */

/*
 *	~Token ()
 *
 *	Functional Description:
 *		This is a virtual destructor defined for the Token class.  It does
 *		nothing at this time.
 *
 *	Formal Parameters:
 *		None.
 *
 *	Return Value:
 *		None.
 *
 *	Side Effects:
 *		None.
 *
 *	Caveats:
 *		None.
 */

/*
 *	Void		SetTopProvider (
 *						PConnection		top_provider)
 *
 *	Functional Description:
 *		This member function is used to change the identity of the Top Provider
 *		in an existing token.  The only time this will really occur is when
 *		a provider that used to be the Top Provider merges into another
 *		domain, and therefore ceases to be the Top Provider.  When the merge
 *		operation has been successfully completed, this function allows the
 *		domain to inform all of its Token objects about the identity of
 *		the new Top Provider.
 *
 *	Formal Parameters:
 *		top_provider (i)
 *			This is a pointer to the new Top Provider.
 *
 *	Return Value:
 *		None.
 *
 *	Side Effects:
 *		None.
 *
 *	Caveats:
 *		None.
 */

/*
 *	TokenState		GetTokenState ()
 *
 *	Functional Description:
 *		This function returns the current state of the token.  This is used
 *		by the caller primarily during a merge operation, when decisions have
 *		to made about what tokens can and cannot be merged.
 *
 *	Formal Parameters:
 *		None.
 *
 *	Return Value:
 *		TOKEN_AVAILABLE if the token is not in use.
 *		TOKEN_GRABBED if the token is currently grabbed.
 *		TOKEN_INHIBITED if the token is currently inhiited.
 *		TOKEN_GIVING if the token is currently in the giving state.
 *		TOKEN_GIVEN if the token is currently in the given state.
 *
 *	Side Effects:
 *		None.
 *
 *	Caveats:
 *		None.
 */

/*
 *	BOOL    	IsValid ()
 *
 *	Functional Description:
 *		This function returns TRUE if the token is still valid, or FALSE if the
 *		token needs to be deleted.  A token is valid if it has ANY owners
 *		(grabbers, inhibitors, or recipient).
 *
 *	Formal Parameters:
 *		None.
 *
 *	Return Value:
 *		TRUE if the token is valid.
 *		FALSE if the token needs to be deleted.
 *
 *	Side Effects:
 *		None.
 *
 *	Caveats:
 *		None.
 */

/*
 *	Void			IssueMergeRequest ()
 *
 *	Functional Description:
 *		This function is called during a domain merge operation.  It causes
 *		the token object to pack it state and send it out in a merge token
 *		request to the top provider.
 *
 *	Formal Parameters:
 *		None.
 *
 *	Return Value:
 *		None.
 *
 *	Side Effects:
 *		None.
 *
 *	Caveats:
 *		None.
 */

/*
 *	Void			TokenGrabRequest (
 *							PCommandTarget		originator,
 *							UserID				uidInitiator,
 *							TokenID				token_id)
 *
 *	Functional Description:
 *		This function is called when a user wishes to grab a token.  Depending
 *		on the current state of the token, the request will either succeed or
 *		fail.  Either way, an appropriate token grab confirm will be issued
 *		to the requesting user.
 *
 *	Formal Parameters:
 *		originator (i)
 *			This is a pointer to the attachment that leads to the originator
 *			of the request.
 *		uidInitiator (i)
 *			This is the user ID of the user that originated the request.
 *		token_id (i)
 *			This is the token being acted upon.
 *
 *	Return Value:
 *		None.
 *
 *	Side Effects:
 *		None.
 *
 *	Caveats:
 *		None.
 */

/*
 *	Void			TokenGrabConfirm (
 *							PCommandTarget		originator,
 *							Result				result,
 *							UserID				uidInitiator,
 *							TokenID				token_id,
 *							TokenStatus			token_status)
 *
 *	Functional Description:
 *		This function is called as a result of the top provider answering a
 *		previous grab request.  It tells the user whether or not the request
 *		succeeded.
 *
 *	Formal Parameters:
 *		originator (i)
 *			This is a pointer to the attachment that leads to the originator
 *			of the request.
 *		result (i)
 *			This is the result of the request.  RESULT_SUCCESSFUL indicates
 *			that the token was successfully grabbed.
 *		uidInitiator (i)
 *			This is the user ID of the user that originated the request.
 *		token_id (i)
 *			This is the token being acted upon.
 *		token_status (i)
 *			This is the status of the token after this request is processed.
 *
 *	Return Value:
 *		None.
 *
 *	Side Effects:
 *		None.
 *
 *	Caveats:
 *		None.
 */

/*
 *	Void			TokenInhibitRequest (
 *							PCommandTarget		originator,
 *							UserID				uidInitiator,
 *							TokenID				token_id)
 *
 *	Functional Description:
 *		This function is called when a user wishes to inhibit a token.
 *		Depending on the current state of the token, the request will either
 *		succeed or fail.  Either way, an appropriate token inhibit confirm will
 *		be issued to the requesting user.
 *
 *	Formal Parameters:
 *		originator (i)
 *			This is a pointer to the attachment that leads to the originator
 *			of the request.
 *		uidInitiator (i)
 *			This is the user ID of the user that originated the request.
 *		token_id (i)
 *			This is the token being acted upon.
 *
 *	Return Value:
 *		None.
 *
 *	Side Effects:
 *		None.
 *
 *	Caveats:
 *		None.
 */

/*
 *	Void			TokenInhibitConfirm (
 *							PCommandTarget		originator,
 *							Result				result,
 *							UserID				uidInitiator,
 *							TokenID				token_id,
 *							TokenStatus			token_status)
 *
 *	Functional Description:
 *		This function is called as a result of the top provider answering a
 *		previous inhibit request.  It tells the user whether or not the request
 *		succeeded.
 *
 *	Formal Parameters:
 *		originator (i)
 *			This is a pointer to the attachment that leads to the originator
 *			of the request.
 *		result (i)
 *			This is the result of the request.  RESULT_SUCCESSFUL indicates
 *			that the token was successfully inhibited.
 *		uidInitiator (i)
 *			This is the user ID of the user that originated the request.
 *		token_id (i)
 *			This is the token being acted upon.
 *		token_status (i)
 *			This is the status of the token after this request is processed.
 *
 *	Return Value:
 *		None.
 *
 *	Side Effects:
 *		None.
 *
 *	Caveats:
 *		None.
 */

/*
 *	Void	TokenGiveRequest (
 *					PCommandTarget		originator,
 *					PTokenGiveRecord	pTokenGiveRec)
 *
 *	Functional Description:
 *		This function is called when a user wishes to give a token to another
 *		user.  Depending on the current state of the token, the request will
 *		either succeed or fail.  Either way, an appropriate token grab confirm
 *		will be issued to the requesting user.
 *
 *	Formal Parameters:
 *		originator (i)
 *			This is a pointer to the attachment that leads to the originator
 *			of the request.
 *		pTokenGiveRec (i)
 *			This is the address of a structure containing the following information:
 *			The ID of the user attempting to give away the token.
 *			The ID of the token being given.
 *			The ID of the user that the token is being given to.
 *
 *	Return Value:
 *		None.
 *
 *	Side Effects:
 *		None.
 *
 *	Caveats:
 *		None.
 */

/*
 *	Void	TokenGiveIndication (
 *					PCommandTarget		originator,
 *					PTokenGiveRecord	pTokenGiveRec)
 *
 *	Functional Description:
 *		This function is called when the top provider wants to indicate to a
 *		user that another user is offering them a token.
 *
 *	Formal Parameters:
 *		originator (i)
 *			This is a pointer to the attachment that leads to the originator
 *			of the request.
 *		pTokenGiveRec (i)
 *			This is the address of a structure containing the following information:
 *			The ID of the user attempting to give away the token.
 *			The ID of the token being given.
 *			The ID of the user that the token is being given to.
 *
 *	Return Value:
 *		None.
 *
 *	Side Effects:
 *		None.
 *
 *	Caveats:
 *		None.
 */

/*
 *	Void	TokenGiveResponse (
 *					PCommandTarget		originator,
 *					Result				result,
 *					UserID				receiver_id,
 *					TokenID				token_id)
 *
 *	Functional Description:
 *		This function is called in response to a previous give indication.  It
 *		contains the user's answer as to whether or not the token was
 *		accepted.
 *
 *	Formal Parameters:
 *		originator (i)
 *			This is a pointer to the attachment that leads to the originator
 *			of the request.
 *		result (i)
 *			This is the result of the request.  RESULT_SUCCESSFUL indicates that
 *			the recipient has accepted the token.
 *		token_id (i)
 *			This is the token being acted upon.
 *		receiver_id (i)
 *			This is the ID of the user that is to receive the token.
 *
 *	Return Value:
 *		None.
 *
 *	Side Effects:
 *		None.
 *
 *	Caveats:
 *		None.
 */

/*
 *	Void	TokenGiveConfirm (
 *					PCommandTarget		originator,
 *					Result				result,
 *					UserID				uidInitiator,
 *					TokenID				token_id,
 *					TokenStatus			token_status)
 *
 *	Functional Description:
 *		This function is called to send a confirmation back to a user who
 *		is trying to give away a token.  It lets the user know whether or
 *		not the operation was successful.
 *
 *	Formal Parameters:
 *		originator (i)
 *			This is a pointer to the attachment that leads to the originator
 *			of the request.
 *		result (i)
 *			This is the result of the request.  RESULT_SUCCESSFUL indicates that
 *			the recipient has accepted the token.
 *		uidInitiator (i)
 *			This is the user ID of the user that originated the request.
 *		token_id (i)
 *			This is the token being acted upon.
 *		token_status (i)
 *			This is the status of the token after the operation.
 *
 *	Return Value:
 *		None.
 *
 *	Side Effects:
 *		None.
 *
 *	Caveats:
 *		None.
 */

/*
 *	Void	TokenPleaseRequest (
 *					PCommandTarget		originator,
 *					UserID				uidInitiator,
 *					TokenID				token_id)
 *
 *	Functional Description:
 *		This function is called when a user wishes to ask the current owners
 *		of a token to relinquish it.
 *
 *	Formal Parameters:
 *		originator (i)
 *			This is a pointer to the attachment that leads to the originator
 *			of the request.
 *		uidInitiator (i)
 *			This is the user ID of the user that originated the request.
 *		token_id (i)
 *			This is the token being acted upon.
 *
 *	Return Value:
 *		None.
 *
 *	Side Effects:
 *		None.
 *
 *	Caveats:
 *		None.
 */

/*
 *	Void	TokenPleaseIndication (
 *					PCommandTarget		originator,
 *					UserID				uidInitiator,
 *					TokenID				token_id)
 *
 *	Functional Description:
 *		This function is initially called by the top provider in response to
 *		a received token please request.  It is forwarded to all users who
 *		currently own the specified token, asking them to relinquish it.
 *
 *	Formal Parameters:
 *		originator (i)
 *			This is a pointer to the attachment that leads to the originator
 *			of the request.
 *		uidInitiator (i)
 *			This is the user ID of the user that originated the request.
 *		token_id (i)
 *			This is the token being acted upon.
 *
 *	Return Value:
 *		None.
 *
 *	Side Effects:
 *		None.
 *
 *	Caveats:
 *		None.
 */

/*
 *	BOOL    		TokenReleaseRequest (
 *							PCommandTarget		originator,
 *							UserID				uidInitiator,
 *							TokenID				token_id)
 *
 *	Functional Description:
 *		This function is called when a user wishes to release a token.
 *		Depending on the current state of the token, the request will either
 *		succeed or fail.  Either way, an appropriate token release confirm will
 *		be issued to the requesting user.
 *
 *	Formal Parameters:
 *		originator (i)
 *			This is a pointer to the attachment that leads to the originator
 *			of the request.
 *		uidInitiator (i)
 *			This is the user ID of the user that originated the request.
 *		token_id (i)
 *			This is the token being acted upon.
 *
 *	Return Value:
 *		None.
 *
 *	Side Effects:
 *		None.
 *
 *	Caveats:
 *		None.
 */

/*
 *	Void			TokenReleaseConfirm (
 *							PCommandTarget		originator,
 *							Result				result,
 *							UserID				uidInitiator,
 *							TokenID				token_id,
 *							TokenStatus			token_status)
 *
 *	Functional Description:
 *		This function is called as a result of the top provider answering a
 *		previous release request.  It tells the user whether or not the request
 *		succeeded.
 *
 *	Formal Parameters:
 *		originator (i)
 *			This is a pointer to the attachment that leads to the originator
 *			of the request.
 *		result (i)
 *			This is the result of the request.  RESULT_SUCCESSFUL indicates
 *			that the token was successfully released.
 *		uidInitiator (i)
 *			This is the user ID of the user that originated the request.
 *		token_id (i)
 *			This is the token being acted upon.
 *		token_status (i)
 *			This is the status of the token after this request is processed.
 *
 *	Return Value:
 *		None.
 *
 *	Side Effects:
 *		None.
 *
 *	Caveats:
 *		None.
 */

/*
 *	Void			TokenTestRequest (
 *							PCommandTarget		originator,
 *							UserID				uidInitiator,
 *							TokenID				token_id)
 *
 *	Functional Description:
 *		This function is called when a user wishes to test the current state
 *		of a token.  The token will issue a token test confirm to the
 *		originating user containing the requested information.
 *
 *	Formal Parameters:
 *		originator (i)
 *			This is a pointer to the attachment that leads to the originator
 *			of the request.
 *		uidInitiator (i)
 *			This is the user ID of the user that originated the request.
 *		token_id (i)
 *			This is the token being acted upon.
 *
 *	Return Value:
 *		None.
 *
 *	Side Effects:
 *		None.
 *
 *	Caveats:
 *		None.
 */

/*
 *	Void			TokenTestConfirm (
 *							PCommandTarget		originator,
 *							UserID				uidInitiator,
 *							TokenID				token_id,
 *							TokenStatus			token_status)
 *
 *	Functional Description:
 *		This function is called as a result of the top provider answering a
 *		previous test request.  It tells the user the current state of the
 *		token.
 *
 *	Formal Parameters:
 *		originator (i)
 *			This is a pointer to the attachment that leads to the originator
 *			of the request.
 *		uidInitiator (i)
 *			This is the user ID of the user that originated the request.
 *		token_id (i)
 *			This is the token being tested.
 *		token_status (i)
 *			This is the current status of the token.
 *
 *	Return Value:
 *		None.
 *
 *	Side Effects:
 *		None.
 *
 *	Caveats:
 *		None.
 */

#endif