|
|
/*
* domain.h * * Copyright (c) 1993 - 1995 by DataBeam Corporation, Lexington, KY * * Abstract: * This is the interface file for the domain class. This class contains * all code necessary to maintain a domain information base within the * MCS system. When a domain object is first created, it is completely * empty. That is, it has no user attachments, no MCS connections, and * therefore no outstanding resources, such as channels and tokens. * * A word of caution about terminology. Throughout the MCS documentation * the word "attachment" is used in conjunction with a USER attachment. The * word "connection" is used in conjunction with a TRANSPORT connection. In * this class, the two types of "attachments" are NOT differentiated (most * of the time). They are both referred to as attachments. When deleting * an attachment, it is necessary to know the difference, however, and so * there is an enumerated type (AttachmentType) to distinguish. The type * of each attachment is stored in a dictionary for easy access (see * description of AttachmentType below). * * This class keeps a list of "attachments" that are hierarchically below * the local provider within the domain. It also keeps a pointer to the * one attachment that is hierarchically above the local provider (if any). * * Since this class inherits from CommandTarget, it processes MCS commands * as member function calls (see cmdtar.h for a description of how this * mechanism works). In essence, domain objects are just big command * routers who react to incoming commands according to the contents of the * information base. That information base, in turn, is modified by the * commands that are handled. * * Domain objects keep lists of both channel objects and token objects, * who maintain information about the current state of various channels * and tokens. Objects of this class are the heart of MCS. * * Caveats: * None. * * Author: * James P. Galvin, Jr. */
#ifndef _DOMAIN_
#define _DOMAIN_
/*
* Interface files. */#include "userchnl.h"
#include "privchnl.h"
#include "token.h"
#include "randchnl.h"
#include "attmnt.h"
/*
* This enumeration defines the errors that a domain object can return when * instructed to do something by its creator. */typedef enum{ DOMAIN_NO_ERROR, DOMAIN_NOT_HIERARCHICAL, DOMAIN_NO_SUCH_CONNECTION, DOMAIN_CONNECTION_ALREADY_EXISTS} DomainError;typedef DomainError * PDomainError;
/*
* This enumeration defines the different merge states that a domain can be in * at any given time. They can be described as follows: * * MERGE_INACTIVE * There is no merge operation underway. This is the normal operational * state. * MERGE_USER_IDS * The domain is currently merging user IDs into the upper domain. * MERGE_STATIC_CHANNELS * The domain is currently merging static channels into the upper domain. * MERGE_ASSIGNED_CHANNELS * The domain is currently merging assigned channels into the upper domain. * MERGE_PRIVATE_CHANNELS * The domain is currently merging private channels into the upper domain. * MERGE_TOKENS * The domain is currently merging tokens into the upper domain. * MERGE_COMPLETE * The merge operation is complete (this is a transitional state). */typedef enum{ MERGE_INACTIVE, MERGE_USER_IDS, MERGE_STATIC_CHANNELS, MERGE_ASSIGNED_CHANNELS, MERGE_PRIVATE_CHANNELS, MERGE_TOKENS, MERGE_COMPLETE} MergeState;typedef MergeState * PMergeState;
/*
* This collection type is used to hold the height of the domain across * various downward attachments. The Domain object needs to know this in order * to calculate the effect of attachment loss on the height of the domain. */class CDomainHeightList2 : public CList2{ DEFINE_CLIST2(CDomainHeightList2, UINT, PConnection)};
/*
* This is the class definition for the Domain class. */class Domain{public:
Domain (); ~Domain ();
BOOL IsTopProvider(void) { return (NULL == m_pConnToTopProvider); }
Void GetDomainParameters ( PDomainParameters domain_parameters, PDomainParameters min_domain_parameters, PDomainParameters max_domain_parameters); Void BindConnAttmnt ( PConnection originator, BOOL upward_connection, PDomainParameters domain_parameters); Void PlumbDomainIndication ( PConnection originator, ULong height_limit); Void ErectDomainRequest ( PConnection originator, ULong height_in_domain, ULong throughput_interval); Void MergeChannelsRequest ( PConnection originator, CChannelAttributesList *merge_channel_list, CChannelIDList *purge_channel_list); Void MergeChannelsConfirm ( PConnection originator, CChannelAttributesList *merge_channel_list, CChannelIDList *purge_channel_list); Void PurgeChannelsIndication ( PConnection originator, CUidList *purge_user_list, CChannelIDList *purge_channel_list); Void MergeTokensRequest ( PConnection originator, CTokenAttributesList *merge_token_list, CTokenIDList *purge_token_list); Void MergeTokensConfirm ( PConnection originator, CTokenAttributesList *merge_token_list, CTokenIDList *purge_token_list); Void PurgeTokensIndication ( PConnection originator, CTokenIDList *purge_token_list); Void DisconnectProviderUltimatum ( CAttachment *originator, Reason reason); Void RejectUltimatum ( PConnection originator, Diagnostic diagnostic, PUChar octet_string_address, ULong octet_string_length); Void AttachUserRequest ( CAttachment *originator); Void AttachUserConfirm ( PConnection originator, Result result, UserID uidInitiator); Void DetachUserRequest ( CAttachment *originator, Reason reason, CUidList *user_id_list); Void DetachUserIndication ( PConnection originator, Reason reason, CUidList *user_id_list); Void ChannelJoinRequest ( CAttachment *originator, UserID uidInitiator, ChannelID channel_id); Void ChannelJoinConfirm ( PConnection originator, Result result, UserID uidInitiator, ChannelID requested_id, ChannelID channel_id); Void ChannelLeaveRequest ( CAttachment *originator, CChannelIDList *channel_id_list); Void ChannelConveneRequest ( CAttachment *originator, UserID uidInitiator); Void ChannelConveneConfirm ( PConnection originator, Result result, UserID uidInitiator, ChannelID channel_id); Void ChannelDisbandRequest ( CAttachment *originator, UserID uidInitiator, ChannelID channel_id); Void ChannelDisbandIndication ( PConnection originator, ChannelID channel_id); Void ChannelAdmitRequest ( CAttachment *originator, UserID uidInitiator, ChannelID channel_id, CUidList *user_id_list); Void ChannelAdmitIndication ( PConnection originator, UserID uidInitiator, ChannelID channel_id, CUidList *user_id_list); Void ChannelExpelRequest ( CAttachment *originator, UserID uidInitiator, ChannelID channel_id, CUidList *user_id_list); Void ChannelExpelIndication ( PConnection originator, ChannelID channel_id, CUidList *user_id_list); Void SendDataRequest ( CAttachment *originator, UINT type, PDataPacket data_packet); Void SendDataIndication ( PConnection originator, UINT type, PDataPacket data_packet); Void TokenGrabRequest ( CAttachment *originator, UserID uidInitiator, TokenID token_id); Void TokenGrabConfirm ( PConnection originator, Result result, UserID uidInitiator, TokenID token_id, TokenStatus token_status); Void TokenInhibitRequest ( CAttachment *originator, UserID uidInitiator, TokenID token_id); Void TokenInhibitConfirm ( PConnection originator, Result result, UserID uidInitiator, TokenID token_id, TokenStatus token_status); Void TokenGiveRequest ( CAttachment *originator, PTokenGiveRecord pTokenGiveRec); Void TokenGiveIndication ( PConnection originator, PTokenGiveRecord pTokenGiveRec); Void TokenGiveResponse ( CAttachment *originator, Result result, UserID receiver_id, TokenID token_id); Void TokenGiveConfirm ( PConnection originator, Result result, UserID uidInitiator, TokenID token_id, TokenStatus token_status); Void TokenPleaseRequest ( CAttachment *originator, UserID uidInitiator, TokenID token_id); Void TokenPleaseIndication ( PConnection originator, UserID uidInitiator, TokenID token_id); Void TokenReleaseRequest ( CAttachment *originator, UserID uidInitiator, TokenID token_id); Void TokenReleaseConfirm ( PConnection originator, Result result, UserID uidInitiator, TokenID token_id, TokenStatus token_status); Void TokenTestRequest ( CAttachment *originator, UserID uidInitiator, TokenID token_id); Void TokenTestConfirm ( PConnection originator, UserID uidInitiator, TokenID token_id, TokenStatus token_status);
private: Void LockDomainParameters ( PDomainParameters domain_parameters, BOOL parameters_locked); ChannelID AllocateDynamicChannel (); BOOL ValidateUserID ( UserID user_id, CAttachment *pOrigAtt); Void PurgeDomain ( Reason reason); Void DeleteAttachment ( CAttachment *pAtt, Reason reason); Void DeleteUser ( UserID user_id); Void DeleteChannel ( ChannelID channel_id); Void DeleteToken ( TokenID token_id); Void ReclaimResources (); Void MergeInformationBase (); Void SetMergeState ( MergeState merge_state); Void AddChannel ( PConnection pConn, PChannelAttributes merge_channel, CChannelAttributesList *merge_channel_list, CChannelIDList *purge_channel_list); Void AddToken ( PTokenAttributes merge_token, CTokenAttributesList *merge_token_list, CTokenIDList *purge_token_list); Void CalculateDomainHeight ();
MergeState Merge_State; UShort Outstanding_Merge_Requests; UINT Number_Of_Users; UINT Number_Of_Channels; UINT Number_Of_Tokens; DomainParameters Domain_Parameters; BOOL Domain_Parameters_Locked;
PConnection m_pConnToTopProvider; CAttachmentList m_AttachmentList;
CAttachmentQueue m_AttachUserQueue; CConnectionQueue m_MergeQueue;
CChannelList2 m_ChannelList2; CTokenList2 m_TokenList2;
UINT m_nDomainHeight; CDomainHeightList2 m_DomainHeightList2;
RandomChannelGenerator Random_Channel_Generator;};
/*
* Domain () * * Functional Description: * This is the constructor for the domain class. It initializes the state * of the domain, which at creation is empty. It also initializes the * domain parameters structure that will be used by this domain for all * future parameters and negotiation. * * Formal Parameters: * None. * * Return Value: * None. * * Side Effects: * None. * * Caveats: * None. */
/*
* ~Domain () * * Functional Description: * This is the destructor for the domain class. It purges the entire * domain by first sending disconnect provider ultimatums to ALL * attachments (both user attachments and MCS connections). It then frees * up all resources in use by the domain (which is just objects in its * various containers). * * Note that doing this will result in all user attachments and MCS * connections being broken. Furthermore, all providers that are * hierarchically below this one, will respond by purging their domains * as well. * * Formal Parameters: * None. * * Return Value: * None. * * Side Effects: * The domain from this provider downward is completely eradicated. * * Caveats: * None. */
/*
* BOOL IsTopProvider () * * Functional Description: * This function is used to ask the domain if it is the top provider in * the domain that it represents. * * Formal Parameters: * None. * * Return Value: * TRUE if this is the top provider. FALSE otherwise. * * Side Effects: * None. * * Caveats: * None. */
/*
* Void GetDomainParameters ( * PDomainParameters domain_parameters, * PDomainParameters min_domain_parameters, * PDomainParameters max_domain_parameters) * * Functional Description: * This function is used to ask the domain what the minimum and maximum * acceptable values for domain parameters are. If the domain has no * connections (and therefore has not yet locked its domain parameters), * then it will return min and max values based on what it can handle. * If it has locked its domain parameters, then both the min and max values * will be set to the locked set (indicating that it will not accept * anything else). * * Formal Parameters: * domain_parameters (o) * Pointer to a structure to be filled with the current domain * parameters (those that are in use). Setting this to NULL will * prevent current domain parameters from being returned. * min_domain_parameters (o) * Pointer to a structure to be filled with the minimum domain * parameters. Setting this to NULL will prevent minimum domain * parameters from being returned. * max_domain_parameters (o) * Pointer to a structure to be filled with the maximum domain * parameters. Setting this to NULL will prevent maximum domain * parameters from being returned. * * Return Value: * None (except as specified in the parameter list above). * * Side Effects: * None. * * Caveats: * None. */
/*
* Void BindConnAttmnt ( * PConnection originator, * BOOL upward_connection, * PDomainParameters domain_parameters, * AttachmentType attachment_type) * * Functional Description: * This function is used when an attachment wishes to bind itself to the * domain. This will occur only after the connection has been been * completely and successfully negotiated. * * Formal Parameters: * originator (i) * This is the attachment that wishes to bind. * upward_connection (i) * A boolean flag indicating whether or not this is an upward * connection. * domain_parameters (i) * A pointer to a domain parameters structure that holds the parameters * that were negotiated for the connection. If the domain has not * already locked its parameters, it will accept and lock these. * attachment_type (i) * What type of attachment is this (local or remote). * * Return Value: * None. * * Side Effects: * None. * * Caveats: * None. */
/*
* Void PlumbDomainIndication ( * PCommandTarget originator, * ULong height_limit) * * Functional Description: * This member function represents the reception of a plumb domain * indication from the top provider. If the height limit is zero, then * the connection to the top provder will be severed. If its not, then * it will be decremented and broadcast to all downward attachments. * * Formal Parameters: * originator (i) * This is the attachment from which the command originated. * height_limit (i) * This is initially the height limit for the domain. It is * decremented at each layer in the domain. When it reaches zero, * the recipient is too far from the top provider, and must * disconnect. * * Return Value: * None. * * Side Effects: * None. * * Caveats: * None. */
/*
* Void ErectDomainRequest ( * PCommandTarget originator, * ULong height_in_domain, * ULong throughput_interval) * * Functional Description: * This member function represents the reception of an erect domain request * from one of its downward attachments. This contains information needed * by higher providers to know what's going on below (such as total * height of domain). * * Formal Parameters: * originator (i) * This is the attachment from which the command originated. * height_in_domain (i) * This is the height of the domain from the originator down. * throughput_interval (i) * This is not currently supported and will always be zero (0). * * Return Value: * None. * * Side Effects: * None. * * Caveats: * None. */
/*
* Void MergeChannelsRequest ( * PCommandTarget originator, * CChannelAttributesList *merge_channel_list, * CChannelIDList *purge_channel_list) * * Functional Description: * This member function represents the reception of a merge channel * request from one of this domain's attachments. If this is the top * provider, then the merge request will be processed locally (which * will result in the transmission of merge channel confirms back to * the originating attachment). If this is not the top provider, then * the command will be forwarded toward the top provider, and this * provider will remember how to route it back. * * Formal Parameters: * originator (i) * This is the attachment from which the command originated. * merge_channel_list (i) * This is a list of strutures that contains the attributes of channels * that are being merged into the upper domain. * purge_channel_list (i) * This is a list of channel IDs for those channels that are determined * to be invalid even before this request reaches the Top Provider. * * Return Value: * None. * * Side Effects: * None. * * Caveats: * None. */
/*
* Void MergeChannelsConfirm ( * PCommandTarget originator, * CChannelAttributesList *merge_channel_list, * CChannelIDList *purge_channel_list) * * Functional Description: * This member function represents the reception of a merge channel * confirm from the top provider. If this is the former top provider of * a lower domain, the confirm will contain information indicating * acceptance or rejection of the named channel. If a channel is rejected, * the former top provider will issue a purge channel indication * downwards. If this is not the former top provider, then it must be * an intermediate provider. The command will be forwarded downward towards * the former top provider. The intermediate providers will also add the * channel to their channel lists if it was accepted into the upper * domain. * * Formal Parameters: * originator (i) * This is the attachment from which the command originated. * merge_channel_list (i) * This is a list of strutures that contains the attributes of channels * that are being merged into the upper domain. * purge_channel_list (i) * This is a list of channel IDs for those channels that are to be * purged from the lower domain. * * Return Value: * None. * * Side Effects: * None. * * Caveats: * None. */
/*
* Void PurgeChannelsIndication ( * PCommandTarget originator, * CUidList *purge_user_list, * CChannelIDList *purge_channel_list) * * Functional Description: * This member function represents the reception of a purge channel * indication from the top provider. This will cause the local * provider to remove the channel from the local information base (if * it are there). It will also broadcast the message downward in the * domain. Note that this will be translated by user objects into either * a detach user indication or a channel leave indication, depending on * which type of channel is being left. * * Formal Parameters: * originator (i) * This is the attachment from which the command originated. * purge_user_list (i) * This is a list of users that are being purged from the lower * domain. * purge_channel_list (i) * This is a list of channels that are being purged from the lower * domain. * * Return Value: * None. * * Side Effects: * None. * * Caveats: * None. */
/*
* Void MergeTokensRequest ( * PCommandTarget originator, * CTokenAttributesList *merge_token_list, * CTokenIDList *purge_token_list) * * Functional Description: * This member function represents the reception of a merge token * request from one of this domain's attachments. If this is the top * provider, then the merge request will be processed locally (which * will result in the transmission of merge token confirms back to * the originating attachment). If this is not the top provider, then * the command will be forwarded toward the top provider, and this provider * will remember how to route it back. * * Formal Parameters: * originator (i) * This is the attachment from which the command originated. * merge_token_list (i) * This is a list of token attributes structures, each of which * describes one token to be merged. * purge_token_list (i) * This is a list of tokens that are to be purged from the lower * domain. * * Return Value: * None. * * Side Effects: * None. * * Caveats: * None. */
/*
* Void MergeTokensConfirm ( * PCommandTarget originator, * CTokenAttributesList *merge_token_list, * CTokenIDList *purge_token_list) * * Functional Description: * This member function represents the reception of a merge token * confirm from the top provider. If this is the former top provider of * a lower domain, the confirm will contain information indicating * acceptance or rejection of the named token. If a token is rejected, * the former top provider will issue a purge token indication * downwards. If this is not the former top provider, then it must be * an intermediate provider. The command will be forwarded downward towards * the former top provider. The intermediate providers will also add the * token to their token lists if it was accepted into the upper * domain. * * Formal Parameters: * originator (i) * This is the attachment from which the command originated. * merge_token_list (i) * This is a list of token attributes structures, each of which * describes one token to be merged. * purge_token_list (i) * This is a list of tokens that are to be purged from the lower * domain. * * Return Value: * None. * * Side Effects: * None. * * Caveats: * None. */
/*
* Void PurgeTokensIndication ( * PCommandTarget originator, * CTokenIDList *purge_token_list) * * Functional Description: * This member function represents the reception of a purge token * indication from the top provider. This will cause the local * provider to remove the token from the local information base (if * it are there). It will also broadcast the message downward in the * domain. Note that this will be translated by user objects into a * token release indication. * * Formal Parameters: * originator (i) * This is the attachment from which the command originated. * purge_token_list (i) * This is a list of tokens that are to be purged from the lower * domain. * * Return Value: * None. * * Side Effects: * None. * * Caveats: * None. */
/*
* Void DisconnectProviderUltimatum ( * PCommandTarget originator, * Reason reason) * * Functional Description: * This member function represents the reception of a disconnect provider * ultimatum. The attachment from which this command is received is * automatically terminated. Any resources that are held by users on * the other side of the attachment are automatically freed by the top * provider (if it was a downward attachment). If it was an upward * attachment then the domain is purged completely (which means that it * is returned to its initialized state). * * Formal Parameters: * originator (i) * This is the attachment from which the command originated. * reason (i) * This is the reason for the disconnect. This will be one of the * reasons defined in "mcatmcs.h". * * Return Value: * None. * * Side Effects: * An attachment will be severed, and potentially the entire domain can * be purged. * * Caveats: * None. */
/*
* Void RejectUltimatum ( * PCommandTarget originator, * Diagnostic diagnostic, * PUChar octet_string_address, * ULong octet_string_length) * * Functional Description: * This command represents the reception of a reject ultimatum. This * indicates that the remote side was unable to correctly process a PDU * that was sent to them. At this time we simply sever the connection * that carried the reject. * * Formal Parameters: * originator (i) * This is the attachment from which the command originated. * diagnostic (i) * This is a diagnostic code describing the nature of the problem. * octet_string_address (i) * This is address of an optional octet string that contains the * bad PDU. * octet_string_length (i) * This is the length of the above octet string. * * Return Value: * None. * * Side Effects: * None. * * Caveats: * None. */
/*
* Void AttachUserRequest ( * PCommandTarget originator) * * Functional Description: * This member function represents the reception of an attach user request. * If this is the top provider, the domain will attempt to add the * new user into the channel list (as a user channel). A confirm will * be issued in the direction of the requesting user, letting it know * the outcome of the attach operation (as well as the user ID if the * attach was successful). If his is not the top provider, then the * request will be forwarded in the direction of the top provider. * * Formal Parameters: * originator (i) * This is the attachment from which the command originated. * * Return Value: * None. * * Side Effects: * None. * * Caveats: * None. */
/*
* Void AttachUserConfirm ( * PCommandTarget originator, * Result result, * UserID uidInitiator) * * Functional Description: * This member function represents the reception of an attach user confirm. * If this provider has an outstanding attach user request, then it * will forward the confirm in the direction of the requester. It will * also add the new user channel to the local channel list. If there * are no outstanding requests (as a result of the requester being * disconnected), then this provider will issue a detach user request * upward to eliminate the user ID that is no longer needed (it will only * do this if the result of the attach was successful). * * Formal Parameters: * originator (i) * This is the attachment from which the command originated. * result (i) * This is the result of the attach operation. Anything but * RESULT_SUCCESSFUL indicates that the attach did not succeed. * uidInitiator (i) * If the attach succeeded, then this field will contain the user ID * of the newly attached user. * * Return Value: * None. * * Side Effects: * None. * * Caveats: * None. */
/*
* Void DetachUserRequest ( * PCommandTarget originator, * Reason reason, * CUidList *user_id_list) * * Functional Description: * This member function represents the reception of a detach user request. * This causes the user channels associated with all users in the list to * be deleted from the user information base. If this is not the top * provider, the request will then be forwarded upward. Additionally, * all resources owned by the detaching users will be reclaimed by all * providers along the way. * * Formal Parameters: * originator (i) * This is the attachment from which the command originated. * reason (i) * This is the reason for th detachment. * user_id_list (i) * This is a list of the users that are detaching. * * Return Value: * None. * * Side Effects: * None. * * Caveats: * None. */
/*
* Void DetachUserIndication ( * PCommandTarget originator, * Reason reason, * CUidList *user_id_list) * * Functional Description: * This member function represents the reception of a detach user * indication. This indication will be repeated to all downward * attachments (both user attachments and MCS connections). Then, if * the user IDs represent any users in the local sub-tree, those users will * be removed from the information base. * * Formal Parameters: * originator (i) * This is the attachment from which the command originated. * reason (i) * This is the reason for the detachment. * user_id_list (i) * This is a list of the users that are detaching. * * Return Value: * None. * * Side Effects: * None. * * Caveats: * None. */
/*
* Void ChannelJoinRequest ( * PCommandTarget originator, * UserID uidInitiator, * ChannelID channel_id) * * Functional Description: * This member function represents the reception of a channel join request. * If the channel exists in the local information base, then the * domain will attempt to join the requesting attachment to the channel. * A channel join confirm will be sent to the requesting attachment * informing the requester of the result. If the channel is not already * in the information base, then one of two things will happen. If this * is the top provider, then the domain will attempt to add the channel * (if it is a static channel). If this is not the top provider, then * the request will be forwarded upward. * * Formal Parameters: * originator (i) * This is the attachment from which the command originated. * uidInitiator (i) * This is the user ID of the user requesting the join. * channel_id (i) * This is the ID of the channel to be joined. * * Return Value: * None. * * Side Effects: * None. * * Caveats: * None. */
/*
* Void ChannelJoinConfirm ( * PCommandTarget originator, * Result result, * UserID uidInitiator, * ChannelID requested_id, * ChannelID channel_id) * * Functional Description: * This member function represents the reception of a channel join confirm. * If the channel has not already been added to the channel, it will * be put there now. The confirm will then be forwarded in the direction * of the requesting user. * * Formal Parameters: * originator (i) * This is the attachment from which the command originated. * result (i) * This is the result of the join. Anything but RESULT_SUCCESSFUL * means that the join failed. * uidInitiator (i) * This is the user ID of the user that requested the channel join. * This is used to properly route the confirm. * requested_id (i) * This is the ID of the channel the user originally requested, which * may be 0. * channel_id (i) * This is the ID of the channel that has been joined. If the original * request was for channel 0, then this field will indicate to the * user which assigned channel was selected by the top provider. * * Return Value: * None. * * Side Effects: * None. * * Caveats: * None. */
/*
* Void ChannelLeaveRequest ( * PCommandTarget originator, * CChannelIDList *channel_id_list) * * Functional Description: * This member function represents the reception of a channel leave * request. The domain removes the requesting attachment from all channels * in the channel list. If this results in any empty channels, then the * channel leave request will be forwarded to the next higher provider in * the domain (unless this is the top provider). Furthermore, if a static * or assigned channel is left empty, it is automatically removed from the * channel list. * * Formal Parameters: * originator (i) * This is the attachment from which the command originated. * channel_id_list (i) * This is a list of channels to be left. * * Return Value: * None. * * Side Effects: * None. * * Caveats: * None. */
/*
* Void ChannelConveneRequest ( * PCommandTarget originator, * UserID uidInitiator) * * Functional Description: * This member function represents the reception of a channel convene * request. If this is not the Top Provider, the request will be sent * upward. If this is the Top Provider, then a new private channel will * be created (if domain parameters allow). * * Formal Parameters: * originator (i) * This is the attachment from which the command originated. * uidInitiator (i) * This is the user ID of the user that requested the creation of a * new private channel. This is used to properly route the confirm. * * Return Value: * None. * * Side Effects: * None. * * Caveats: * None. */
/*
* Void ChannelConveneConfirm ( * PCommandTarget originator, * Result result, * UserID uidInitiator, * ChannelID channel_id) * * Functional Description: * This member function represents the reception of a channel convene * confirm. This causes the local provider to add the new private channel * to the local information base, and route the confirm on toward the * initiator of the request. * * Formal Parameters: * originator (i) * This is the attachment from which the command originated. * result (i) * This is the result of the convene. Anything but RESULT_SUCCESSFUL * means that the convene failed. * uidInitiator (i) * This is the user ID of the user that requested the channel convene. * This is used to properly route the confirm. * channel_id (i) * This is the ID of the new private channel that has been created. * * Return Value: * None. * * Side Effects: * None. * * Caveats: * None. */
/*
* Void ChannelDisbandRequest ( * PCommandTarget originator, * UserID uidInitiator, * ChannelID channel_id) * * Functional Description: * This member function represents the reception of a channel disband * request. If this is not the Top Provider, then the request will be * forwarded upward. If this is the Top Provider, then the specified * private channel will be destroyed (after appropriate identity * verification). This will cause channel disband and channel expel * indications to be sent downward to all admitted users. * * Formal Parameters: * originator (i) * This is the attachment from which the command originated. * uidInitiator (i) * This is the user ID of the user that requested the channel disband. * If this does not correspond to the channel manager, then the request * will be ignored. * channel_id (i) * This is the ID of the channel to be disbanded. * * Return Value: * None. * * Side Effects: * None. * * Caveats: * None. */
/*
* Void ChannelDisbandIndication ( * PCommandTarget originator, * ChannelID channel_id) * * Functional Description: * This member function represents the reception of a channel disband * indication. This causes the specified private channel to be removed * from the information base. The indication is then forwarded to all * attachments that are either admitted or the channel manager. * * Formal Parameters: * originator (i) * This is the attachment from which the command originated. * channel_id (i) * This is the ID of the channel being disbanded. * * Return Value: * None. * * Side Effects: * None. * * Caveats: * None. */
/*
* Void ChannelAdmitRequest ( * PCommandTarget originator, * UserID uidInitiator, * ChannelID channel_id, * CUidList *user_id_list) * * Functional Description: * This member function represents the reception of a channel admit * request. If this is not the Top Provider, then the request will be * forwarded upward. If this is the Top Provider, then the user IDs * will be added to the admitted list, and a channel admit indication will * be sent downward toward all attachments that contain an admitted user. * * Formal Parameters: * originator (i) * This is the attachment from which the command originated. * uidInitiator (i) * This is the user ID of the user that requested the channel admit. * This must be the channel manager for the admit to succeed. * channel_id (i) * This is the ID of the private channel whose admitted list is to * be expanded. * user_id_list (i) * This is a container holding the user IDs of those users to be * admitted to the private channel. * * Return Value: * None. * * Side Effects: * None. * * Caveats: * None. */
/*
* Void ChannelAdmitIndication ( * PCommandTarget originator, * UserID uidInitiator, * ChannelID channel_id, * CUidList *user_id_list) * * Functional Description: * This member function represents the reception of a channel admit * indication. If the specified private channel does not yet exist in the * information base, it will be created now. The users specified will be * added to the admitted list, and this indication will be forwarded to * all attachments that contain an admitted user. * * Formal Parameters: * originator (i) * This is the attachment from which the command originated. * uidInitiator (i) * This is the user ID of the manager of this private channel. * channel_id (i) * This is the ID of the private channel for which this indication * is intended. * user_id_list (i) * This is a container holding the list of user IDs to be added to * the admitted list. * * Return Value: * None. * * Side Effects: * None. * * Caveats: * None. */
/*
* Void ChannelExpelRequest ( * PCommandTarget originator, * UserID uidInitiator, * ChannelID channel_id, * CUidList *user_id_list) * * Functional Description: * This member function represents the reception of a channel expel * request. If this is not the Top Provider, then the request will be * forwarded upward. If this is the Top Provider, then the specifed users * will be removed from the private channel, and an expel indication will * be sent downward to all attachments that contain (or did contain) an * admitted user. * * Formal Parameters: * originator (i) * This is the attachment from which the command originated. * uidInitiator (i) * This is the user ID of the user that requested the channel expel. * This must be the channel manager for the expel to succeed. * channel_id (i) * This is the ID of the private channel whose admitted list is to * be reduced. * user_id_list (i) * This is a container holding the user IDs of those users to be * expelled from the private channel. * * Return Value: * None. * * Side Effects: * None. * * Caveats: * None. */
/*
* Void ChannelExpelIndication ( * PCommandTarget originator, * ChannelID channel_id, * CUidList *user_id_list) * * Functional Description: * This member function represents the reception of a channel expel * indication. The specified users will be removed from the admitted * list of the channel. If the channel is empty, and the channel manager * is not in the sub-tree of this provider, then the channel will be * removed from the local information base. The expel indication will * also be forwarded to all attachments that contain (or did contain( an * admitted user. * * Formal Parameters: * originator (i) * This is the attachment from which the command originated. * channel_id (i) * This is the ID of the private channel for which this indication * is intended. * user_id_list (i) * This is a container holding the list of user IDs to be removed * from the admitted list. * * Return Value: * None. * * Side Effects: * None. * * Caveats: * None. */
/*
* Void SendDataRequest ( * PCommandTarget originator, * UINT type, * PDataPacket data_packet) * * Functional Description: * This member function represents the reception of a send data request. * If this is not the top provider, the request will be repeated * upward toward the top provider. The data will also be sent downward * to all attachments that are joined to the channel (except for the * originator) in the form of a send data indication. * * Formal Parameters: * originator (i) * This is the attachment from which the command originated. * type (i) * Normal or uniform send data request. * data_packet (i) * This is a pointer to a DataPacket object containing the channel * ID, the User ID of the data sender, segmentation flags, priority of * the data packet and a pointer to the packet to be sent. * * Return Value: * None. * * Side Effects: * None. * * Caveats: * None. */
/*
* Void SendDataIndication ( * PCommandTarget originator, * UINT type, * PDataPacket data_packet) * * Functional Description: * This member function represents the reception of a send data indication. * This indication will be repeated downward to all attachments that * are joined to the channel. * * Formal Parameters: * originator (i) * This is the attachment from which the command originated. * type (i) * normal or uniform send data indication * data_packet (i) * This is a pointer to a DataPacket object containing the channel * ID, the User ID of the data sender, segmentation flags, priority of * the data packet and a pointer to the packet to be sent. * * Return Value: * None. * * Side Effects: * None. * * Caveats: * None. *//*
* Void TokenGrabRequest ( * PCommandTarget originator, * UserID uidInitiator, * TokenID token_id) * * Functional Description: * This member function represents the reception of a token grab request. * If this is not the top provider, the request will be forwarded * upward towards the top provider. If this is the top provider, the * domain will attempt to grab the token on behalf of the requesting user. * A token grab confirm will be issued to the requesting user informing * it of the outcome. * * Formal Parameters: * originator (i) * This is the attachment from which the command originated. * uidInitiator (i) * This is the ID of the user that is requesting the token grab. * token_id (i) * This is the ID of the token that the user is attempting to grab. * * 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 member function represents the reception of a token grab confirm. * This confirm will simply be forwarded in the direction of the * requesting user. * * Formal Parameters: * originator (i) * This is the attachment from which the command originated. * result (i) * This is the result of the grab request. If it is anything but * RESULT_SUCCESSFUL, the grab request failed. * uidInitiator (i) * This is the ID of the user that is requesting the token grab. * token_id (i) * This is the ID of the token that the user is attempting to grab. * token_status (i) * This is the state of the token after the grab request was * processed at the top provider. * * Return Value: * None. * * Side Effects: * None. * * Caveats: * None. */
/*
* Void TokenInhibitRequest ( * PCommandTarget originator, * UserID uidInitiator, * TokenID token_id) * * Functional Description: * This member function represents the reception of a token inhibit * request. If this is not the top provider, the request will be forwarded * upward towards the top provider. If this is the top provider, the * domain will attempt to inhibit the token on behalf of the requesting * user. A token inhibit confirm will be issued to the requesting user * informing it of the outcome. * * Formal Parameters: * originator (i) * This is the attachment from which the command originated. * uidInitiator (i) * This is the ID of the user that is requesting the token inhibit. * token_id (i) * This is the ID of the token that the user is attempting to inhibit. * * 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 member function represents the reception of a token inhibit * confirm. This confirm will simply be forwarded in the direction of the * requesting user. * * Formal Parameters: * originator (i) * This is the attachment from which the command originated. * result (i) * This is the result of the inhibit request. If it is anything but * RESULT_SUCCESSFUL, the inhibit request failed. * uidInitiator (i) * This is the ID of the user that is requesting the token inhibit. * token_id (i) * This is the ID of the token that the user is attempting to inhibit. * token_status (i) * This is the state of the token after the inhibit request was * processed at the top provider. * * Return Value: * None. * * Side Effects: * None. * * Caveats: * None. */
/*
* Void TokenGiveRequest ( * PCommandTarget originator, * PTokenGiveRecord pTokenGiveRec) * * Functional Description: * This member function represents the reception of a token give request. * If this is not the top provider, the request will be forwarded upward * towards the top provider. If this is the top provider, the domain will * issue a token give indication in the direction of the user identified * to receive the token. * * Formal Parameters: * originator (i) * This is the attachment from which the command originated. * 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 member function represents the reception of a token give * indication. This indication will be forwarded toward the user that * is to receive the token. * * Formal Parameters: * originator (i) * This is the attachment from which the command originated. * 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 member function represents the reception of a token give response. * If this is not the top provider, the response will be forwarded * upward towards the top provider. If this is the top provider, the * domain will make the appropriate changes to the state of the token in * the local information base, and then issue a token give confirm to the * user that initiated the give request. * * Formal Parameters: * originator (i) * This is the attachment from which the command originated. * result (i) * This specifies whether or not the token was accepted. Anything but * RESULT_SUCCESSFUL indicates that the token was rejected. * receiver_id (i) * This is the ID of the user that has either accepted or rejected the * token. * token_id (i) * This is the ID of the token that the user has been given. * * 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 member function represents the reception of a token give confirm. * This is forwarded toward the user that initiated the give request to * inform it of the outcome. * * Formal Parameters: * originator (i) * This is the attachment from which the command originated. * result (i) * This parameter specifies whether or not the token was accepted. * Anything but RESULT_SUCCESSFUL indicates that the token was not * accepted. * uidInitiator (i) * This is the ID of the user that originally requested the token * give request. * token_id (i) * This is the ID of the token that the user is attempting to give. * token_status (i) * This specifies the status of the token after the give operation * was complete. * * Return Value: * None. * * Side Effects: * None. * * Caveats: * None. */
/*
* Void TokenPleaseRequest ( * PCommandTarget originator, * UserID uidInitiator, * TokenID token_id) * * Functional Description: * This member function represents the reception of a token please * request. If this is not the top provider, the request will be forwarded * upward towards the top provider. If this is the top provider, the * domain will issue a token please indication in the direction of all * users that currently own the token. * * Formal Parameters: * originator (i) * This is the attachment from which the command originated. * uidInitiator (i) * This is the ID of the user that is asking for the token. * token_id (i) * This is the ID of the token that the user is asking for. * * Return Value: * None. * * Side Effects: * None. * * Caveats: * None. */
/*
* Void TokenPleaseIndication ( * PCommandTarget originator, * UserID uidInitiator, * TokenID token_id) * * Functional Description: * This member function represents the reception of a token please * indication. This indication is forwarded to all users who currently * own the specified token. * * Formal Parameters: * originator (i) * This is the attachment from which the command originated. * uidInitiator (i) * This is the ID of the user that is asking for the token. * token_id (i) * This is the ID of the token that the user is asking for. * * Return Value: * None. * * Side Effects: * None. * * Caveats: * None. */
/*
* Void TokenReleaseRequest ( * PCommandTarget originator, * UserID uidInitiator, * TokenID token_id) * * Functional Description: * This member function represents the reception of a token release * request. If this is not the top provider, the request will be forwarded * upward towards the top provider. If this is the top provider, the * domain will attempt to release the token on behalf of the requesting * user. A token release confirm will be issued to the requesting user * informing it of the outcome. * * Formal Parameters: * originator (i) * This is the attachment from which the command originated. * uidInitiator (i) * This is the ID of the user that is requesting the token release. * token_id (i) * This is the ID of the token that the user is attempting to release. * * 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 member function represents the reception of a token release * confirm. This confirm will simply be forwarded in the direction of the * requesting user. * * Formal Parameters: * originator (i) * This is the attachment from which the command originated. * result (i) * This is the result of the release request. If it is anything but * RESULT_SUCCESSFUL, the release request failed. * uidInitiator (i) * This is the ID of the user that is requesting the token release. * token_id (i) * This is the ID of the token that the user is attempting to release. * token_status (i) * This is the state of the token after the release request was * processed at the top provider. * * Return Value: * None. * * Side Effects: * None. * * Caveats: * None. */
/*
* Void TokenTestRequest ( * PCommandTarget originator, * UserID uidInitiator, * TokenID token_id) * * Functional Description: * This member function represents the reception of a token test request. * If this is not the top provider, the request will be forwarded * upward towards the top provider. If this is the top provider, the * domain will test the current state of the token. A token test confirm * will be issued to the requesting user informing it of the outcome. * * Formal Parameters: * originator (i) * This is the attachment from which the command originated. * uidInitiator (i) * This is the ID of the user that is requesting the token test. * token_id (i) * This is the ID of the token that the user is testing. * * Return Value: * None. * * Side Effects: * None. * * Caveats: * None. */
/*
* Void TokenTestConfirm ( * PCommandTarget originator, * UserID uidInitiator, * TokenID token_id, * TokenStatus token_status) * * Functional Description: * This member function represents the reception of a token test confirm. * This confirm will simply be forwarded in the direction of the * requesting user. * * Formal Parameters: * originator (i) * This is the attachment from which the command originated. * uidInitiator (i) * This is the ID of the user that is requesting the token test. * token_id (i) * This is the ID of the token that the user is testing. * token_status (i) * This is the state of the token at the time of the test. * * Return Value: * None. * * Side Effects: * None. * * Caveats: * None. */
#endif
|
