windows-nt/Source/XPSP1/NT/termsrv/remdsk/rds/t120/h/token.h
2020-09-26 16:20:57 +08:00

828 lines
22 KiB
C++

/*
* 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