You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
1734 lines
54 KiB
1734 lines
54 KiB
/*
|
|
* user.h
|
|
*
|
|
* Copyright (c) 1993 - 1995 by DataBeam Corporation, Lexington, KY
|
|
*
|
|
* Abstract:
|
|
* This is the interface file for the User class. Instances of this class
|
|
* represent attachments between user applications and domains within MCS.
|
|
*
|
|
* This class inherits from CommandTarget. This means that all message
|
|
* traffic between this class and other CommandTarget classes is in MCS
|
|
* commands. Not all commands need to be handled (some are not relevant
|
|
* for user attachments). For example, a user attachment should never
|
|
* receive a SendDataRequest. It should only receive indications,
|
|
* confirms, and ultimatums.
|
|
*
|
|
* Messages coming from the application pass through one of these objects,
|
|
* where they are translated into MCS commands before being sent to the
|
|
* domain to which this user is attached. This usually involves adding
|
|
* the correct user ID, as well as a fair amount of error checking and
|
|
* parameter validation.
|
|
*
|
|
* It is worth noting that this class contains two types of public member
|
|
* functions. The first type represent messages flowing from the user
|
|
* application into MCS. All of these member functions are inherited from the
|
|
* IMCSSap interface. These are converted as memntioned above, and sent
|
|
* into the appropriate domain if everything checks out. The second type
|
|
* of public member function represents messages flowing from within MCS
|
|
* to the user application. All of these member function are overrides
|
|
* of virtual functions defined in class CommandTarget, and are not
|
|
* prefixed with anything.
|
|
*
|
|
* Messages coming from the domain are translated into T.122 indications
|
|
* and confirms, and sent to the proper application interface object via
|
|
* the owner callback mechanism.
|
|
*
|
|
* A third duty of this class is to post indications and confirms to user
|
|
* applications using a client window. The client must dispatch messages
|
|
* to receive these indications/confirms. It also
|
|
* prevents a user application from having to worry about receiving an
|
|
* indication or confirm before they have even returned from the request
|
|
* that caused it.
|
|
*
|
|
* Caveats:
|
|
* None.
|
|
*
|
|
* Author:
|
|
* James P. Galvin, Jr.
|
|
*/
|
|
|
|
#ifndef _USER_
|
|
#define _USER_
|
|
|
|
/*
|
|
* Interface files.
|
|
*/
|
|
#include "pktcoder.h"
|
|
#include "imcsapp.h"
|
|
#include "attmnt.h"
|
|
|
|
/*
|
|
* These types are used to keep track of what users have attached to MCS
|
|
* within a given process, as well as pertinent information about that
|
|
* attachment.
|
|
*
|
|
* BufferRetryInfo
|
|
* In cases where MCSSendDataRequest and MCSUniformSendDataRequest fail
|
|
* due to a lack of resources, this structure will be used to capture
|
|
* appropriate information such that follow-up resource level checks can
|
|
* be performed during timer events.
|
|
*/
|
|
|
|
typedef struct
|
|
{
|
|
ULong user_data_length;
|
|
UINT_PTR timer_id;
|
|
} BufferRetryInfo;
|
|
typedef BufferRetryInfo * PBufferRetryInfo;
|
|
|
|
/*
|
|
* These are the owner callback functions that a user object can send to an
|
|
* object whose public interface is unknown to it. The first one is sent to
|
|
* the controller when a user object detects the need to delete itself. The
|
|
* rest are sent to an application interface object as part of communicating
|
|
* with the user application (the proper application interface object is
|
|
* identified to this class as one of its constructor parameters).
|
|
*
|
|
* When an object instantiates a user object (or any other object that uses
|
|
* owner callbacks), it is accepting the responsibility of receiving and
|
|
* handling those callbacks. For that reason, any object that issues owner
|
|
* callbacks will have those callbacks defined as part of the interface file
|
|
* (since they really are part of a bi-directional interface).
|
|
*
|
|
* Each owner callback function, along with a description of how its parameters
|
|
* are packed, is described in the following section.
|
|
*/
|
|
|
|
/*
|
|
* This macro is used to pack callback parameters into a single long word
|
|
* for delivery to the user application.
|
|
*/
|
|
#define PACK_PARAMETER(l,h) ((ULong) (((UShort) (l)) | \
|
|
(((ULong) ((UShort) (h))) << 16)))
|
|
|
|
/*
|
|
* TIMER_PROCEDURE_TIMEOUT
|
|
* This macro specifies the granularity, in milliseconds, of any timer
|
|
* which may be created to recheck resource levels following a call to
|
|
* MCSSendDataRequest or MCSUniformSendDataRequest which returned
|
|
* MCS_TRANSMIT_BUFFER_FULL.
|
|
* CLASS_NAME_LENGTH
|
|
* The class name of the window class for all User-related windows. These
|
|
* are the client windows that receive messages related to MCS indications and
|
|
* confirms that have to be delivered to the client apps.
|
|
*/
|
|
#define TIMER_PROCEDURE_TIMEOUT 300
|
|
#define CLASS_NAME_LENGTH 35
|
|
|
|
/*
|
|
* This is the function signature of the timer procedure. Timer messages will
|
|
* be routed to this function as a result of timer events which have been set
|
|
* up to recheck resource levels. This would happen following a call to either
|
|
* SendData or GetBuffer call which resulted in a return
|
|
* value of MCS_TRANSMIT_BUFFER_FULL.
|
|
*/
|
|
Void CALLBACK TimerProc (HWND, UINT, UINT, DWORD);
|
|
|
|
/* Client window procedure declarations
|
|
*
|
|
* UserWindowProc
|
|
* Declaration of the window procedure used to deliver all MCS messages
|
|
* to MCS apps (clients). The MCS main thread sends msgs to a client
|
|
* window with this window procedure. The window procedure is then
|
|
* responsible to deliver the callback to the MCS client.
|
|
*/
|
|
LRESULT CALLBACK UserWindowProc (HWND, UINT, WPARAM, LPARAM);
|
|
|
|
// Data packet queue
|
|
class CDataPktQueue : public CQueue
|
|
{
|
|
DEFINE_CQUEUE(CDataPktQueue, PDataPacket)
|
|
};
|
|
|
|
// timer user object list
|
|
class CTimerUserList2 : public CList2
|
|
{
|
|
DEFINE_CLIST2(CTimerUserList2, PUser, UINT_PTR) // timerID
|
|
};
|
|
|
|
// memory and buffer list
|
|
class CMemoryBufferList2 : public CList2
|
|
{
|
|
DEFINE_CLIST2(CMemoryBufferList2, PMemory, LPVOID)
|
|
};
|
|
|
|
/*
|
|
* This is the actual class definition for the User class. It inherits from
|
|
* CommandTarget (which in turn inherits from Object). It has only one
|
|
* constructor, which tells the newly created object who it is, who the
|
|
* controller is, and who the proper application interface object is. It also
|
|
* has a destructor, to clean up after itself. Most importantly, it has
|
|
* one public member function for each MCS command that it must handle.
|
|
*/
|
|
class User: public CAttachment, public CRefCount, public IMCSSap
|
|
{
|
|
friend Void CALLBACK TimerProc (HWND, UINT, UINT, DWORD);
|
|
friend LRESULT CALLBACK UserWindowProc (HWND, UINT, WPARAM, LPARAM);
|
|
public:
|
|
User (PDomain, PMCSError);
|
|
virtual ~User ();
|
|
|
|
static BOOL InitializeClass (void);
|
|
static void CleanupClass (void);
|
|
|
|
/* ------- IMCSSap interface -------- */
|
|
MCSAPI ReleaseInterface(void);
|
|
|
|
MCSAPI GetBuffer (UINT, PVoid *);
|
|
MCSAPI_(void) FreeBuffer (PVoid);
|
|
MCSAPI ChannelJoin (ChannelID);
|
|
MCSAPI ChannelLeave (ChannelID);
|
|
MCSAPI ChannelConvene ();
|
|
MCSAPI ChannelDisband (ChannelID);
|
|
MCSAPI ChannelAdmit (ChannelID, PUserID, UINT);
|
|
MCSAPI SendData (DataRequestType, ChannelID, Priority, unsigned char *, ULong, SendDataFlags);
|
|
MCSAPI TokenGrab (TokenID);
|
|
MCSAPI TokenInhibit (TokenID);
|
|
MCSAPI TokenGive (TokenID, UserID);
|
|
MCSAPI TokenGiveResponse (TokenID, Result);
|
|
MCSAPI TokenPlease (TokenID);
|
|
MCSAPI TokenRelease (TokenID);
|
|
MCSAPI TokenTest (TokenID);
|
|
|
|
#ifdef USE_CHANNEL_EXPEL_REQUEST
|
|
MCSError MCSChannelExpelRequest (ChannelID, PMemory, UINT);
|
|
#endif // USE_CHANNEL_EXPEL_REQUEST
|
|
|
|
void SetDomainParameters (PDomainParameters);
|
|
virtual void PlumbDomainIndication(ULONG height_limit) { };
|
|
virtual void PurgeChannelsIndication (CUidList *, CChannelIDList *);
|
|
virtual void PurgeTokensIndication(PDomain, CTokenIDList *) { };
|
|
virtual void DisconnectProviderUltimatum (Reason);
|
|
virtual void AttachUserConfirm (Result, UserID);
|
|
virtual void DetachUserIndication (Reason, CUidList *);
|
|
virtual void ChannelJoinConfirm (Result, UserID, ChannelID, ChannelID);
|
|
void ChannelLeaveIndication (Reason, ChannelID);
|
|
virtual void ChannelConveneConfirm (Result, UserID, ChannelID);
|
|
virtual void ChannelDisbandIndication (ChannelID);
|
|
virtual void ChannelAdmitIndication (UserID, ChannelID, CUidList *);
|
|
virtual void ChannelExpelIndication (ChannelID, CUidList *);
|
|
virtual void SendDataIndication (UINT, PDataPacket);
|
|
virtual void TokenGrabConfirm (Result, UserID, TokenID, TokenStatus);
|
|
virtual void TokenInhibitConfirm (Result, UserID, TokenID, TokenStatus);
|
|
virtual void TokenGiveIndication (PTokenGiveRecord);
|
|
virtual void TokenGiveConfirm (Result, UserID, TokenID, TokenStatus);
|
|
virtual void TokenPleaseIndication (UserID, TokenID);
|
|
void TokenReleaseIndication (Reason, TokenID);
|
|
virtual void TokenReleaseConfirm (Result, UserID, TokenID, TokenStatus);
|
|
virtual void TokenTestConfirm (UserID, TokenID, TokenStatus);
|
|
virtual void MergeDomainIndication (MergeStatus);
|
|
void RegisterUserAttachment (MCSCallBack, PVoid, UINT);
|
|
void IssueDataIndication (UINT, PDataPacket);
|
|
|
|
|
|
private:
|
|
MCSError ValidateUserRequest ();
|
|
void CreateRetryTimer (ULong);
|
|
MCSError ChannelJLCD (int, ChannelID);
|
|
void ChannelConfInd (UINT, ChannelID, UINT);
|
|
MCSError TokenGIRPT (int, TokenID);
|
|
void TokenConfInd (UINT, TokenID, UINT);
|
|
void PurgeMessageQueue ();
|
|
|
|
// Static member variables
|
|
static CTimerUserList2 *s_pTimerUserList2;
|
|
static HINSTANCE s_hInstance;
|
|
|
|
PDomain m_pDomain;
|
|
UserID User_ID;
|
|
UserID m_originalUser_ID;
|
|
BOOL Merge_In_Progress;
|
|
BOOL Deletion_Pending;
|
|
ULong Maximum_User_Data_Length;
|
|
HWND m_hWnd;
|
|
|
|
MCSCallBack m_MCSCallback;
|
|
PVoid m_UserDefined;
|
|
BOOL m_fDisconnectInDataLoss;
|
|
BOOL m_fFreeDataIndBuffer;
|
|
CDataPktQueue m_DataPktQueue;
|
|
CDataPktQueue m_PostMsgPendingQueue;
|
|
CMemoryBufferList2 m_DataIndMemoryBuf2;
|
|
PBufferRetryInfo m_BufferRetryInfo;
|
|
};
|
|
|
|
/*
|
|
* User (PCommandTarget top_provider)
|
|
*
|
|
* Functional Description:
|
|
* This is the constructor for the user object. Its primary purpose is
|
|
* to "insert" itself into the layered structure built by the controller.
|
|
* To do this it must register itself with the objects above and below it.
|
|
*
|
|
* It first registers itself with the application interface object
|
|
* identified as one of the parameters. This assures that any traffic
|
|
* from the application will get to this object correctly.
|
|
*
|
|
* It then issues an attach user request to the domain object identified
|
|
* by another of the parameters. This informs the domain of the users
|
|
* presence and also kicks off the process of attaching to that domain.
|
|
* Note that the object is not really attached to the domain until it
|
|
* receives a successful attach user confirm.
|
|
*
|
|
* Formal Parameters:
|
|
* top_provider (i)
|
|
* This is a pointer to the domain object to which this user should
|
|
* attach.
|
|
*
|
|
* Return Value:
|
|
* None.
|
|
*
|
|
* Side Effects:
|
|
* None.
|
|
*
|
|
* Caveats:
|
|
* None.
|
|
*/
|
|
|
|
/*
|
|
* ~User ()
|
|
*
|
|
* Functional Description:
|
|
* This is the destructor for the user class. It detaches itself from the
|
|
* objects above and below it, and frees any outstanding resources that
|
|
* it may holding in conjunction with unsent user messages.
|
|
*
|
|
* Formal Parameters:
|
|
* None.
|
|
*
|
|
* Return Value:
|
|
* None.
|
|
*
|
|
* Side Effects:
|
|
* None.
|
|
*
|
|
* Caveats:
|
|
* None.
|
|
*/
|
|
|
|
/*
|
|
* MCSError DetachUser ()
|
|
*
|
|
* Functional Description:
|
|
* This request comes from the application interface object in response
|
|
* to the same request from a user application. This object can then
|
|
* re-package the request as an MCS command and send it to the domain
|
|
* object. It will also cause the user object to destroy itself.
|
|
*
|
|
* Formal Parameters:
|
|
* None.
|
|
*
|
|
* Return Value:
|
|
* MCS_NO_ERROR
|
|
* Everything worked fine.
|
|
* MCS_TRANSMIT_BUFFER_FULL
|
|
* The request could not be processed due to a resource shortage
|
|
* within MCS. The application is responsible for re-trying the
|
|
* request at a later time.
|
|
* MCS_DOMAIN_MERGING
|
|
* This operation could not be performed due to a local merge operation
|
|
* in progress. The user application must retry at a later time.
|
|
*
|
|
* Side Effects:
|
|
* None.
|
|
*
|
|
* Caveats:
|
|
* None.
|
|
*/
|
|
|
|
/*
|
|
* MCSError ChannelJoin (
|
|
* ChannelID channel_id)
|
|
*
|
|
* Functional Description:
|
|
* This request comes from the application interface object in response
|
|
* to the same request from a user application. This object can then
|
|
* re-package the request as an MCS command and send it to the domain
|
|
* object.
|
|
*
|
|
* Formal Parameters:
|
|
* channel_id (i)
|
|
* This is the channel that the user application wishes to join.
|
|
*
|
|
* Return Value:
|
|
* MCS_NO_ERROR
|
|
* Everything worked fine.
|
|
* MCS_TRANSMIT_BUFFER_FULL
|
|
* The request could not be processed due to a resource shortage
|
|
* within MCS. The application is responsible for re-trying the
|
|
* request at a later time.
|
|
* MCS_USER_NOT_ATTACHED
|
|
* The user is not attached to the domain. This could indicate that
|
|
* the user application issued a request without waiting for the
|
|
* attach user confirm.
|
|
* MCS_DOMAIN_MERGING
|
|
* This operation could not be performed due to a local merge operation
|
|
* in progress. The user application must retry at a later time.
|
|
*
|
|
* Side Effects:
|
|
* None.
|
|
*
|
|
* Caveats:
|
|
* None.
|
|
*/
|
|
|
|
/*
|
|
* MCSError ChannelLeave (
|
|
* ChannelID channel_id)
|
|
*
|
|
* Functional Description:
|
|
* This request comes from the application interface object in response
|
|
* to the same request from a user application. This object can then
|
|
* re-package the request as an MCS command and send it to the domain
|
|
* object.
|
|
*
|
|
* Formal Parameters:
|
|
* channel_id (i)
|
|
* This is the channel that the user application wishes to leave.
|
|
*
|
|
* Return Value:
|
|
* MCS_NO_ERROR
|
|
* Everything worked fine.
|
|
* MCS_TRANSMIT_BUFFER_FULL
|
|
* The request could not be processed due to a resource shortage
|
|
* within MCS. The application is responsible for re-trying the
|
|
* request at a later time.
|
|
* MCS_USER_NOT_ATTACHED
|
|
* The user is not attached to the domain. This could indicate that
|
|
* the user application issued a request without waiting for the
|
|
* attach user confirm.
|
|
* MCS_DOMAIN_MERGING
|
|
* This operation could not be performed due to a local merge operation
|
|
* in progress. The user application must retry at a later time.
|
|
*
|
|
* Side Effects:
|
|
* None.
|
|
*
|
|
* Caveats:
|
|
* None.
|
|
*/
|
|
|
|
/*
|
|
* MCSError ChannelConvene ()
|
|
*
|
|
* Functional Description:
|
|
* This request comes from the application interface object in response
|
|
* to the same request from a user application. This object can then
|
|
* re-package the request as an MCS command and send it to the domain
|
|
* object.
|
|
*
|
|
* Formal Parameters:
|
|
* None.
|
|
*
|
|
* Return Value:
|
|
* MCS_NO_ERROR
|
|
* Everything worked fine.
|
|
* MCS_TRANSMIT_BUFFER_FULL
|
|
* The request could not be processed due to a resource shortage
|
|
* within MCS. The application is responsible for re-trying the
|
|
* request at a later time.
|
|
* MCS_USER_NOT_ATTACHED
|
|
* The user is not attached to the domain. This could indicate that
|
|
* the user application issued a request without waiting for the
|
|
* attach user confirm.
|
|
* MCS_DOMAIN_MERGING
|
|
* This operation could not be performed due to a local merge operation
|
|
* in progress. The user application must retry at a later time.
|
|
*
|
|
* Side Effects:
|
|
* None.
|
|
*
|
|
* Caveats:
|
|
* None.
|
|
*/
|
|
|
|
/*
|
|
* MCSError ChannelDisband (
|
|
* ChannelID channel_id)
|
|
*
|
|
* Functional Description:
|
|
* This request comes from the application interface object in response
|
|
* to the same request from a user application. This object can then
|
|
* re-package the request as an MCS command and send it to the domain
|
|
* object.
|
|
*
|
|
* Formal Parameters:
|
|
* channel_id (i)
|
|
* This is the channel that the user wishes to disband.
|
|
*
|
|
* Return Value:
|
|
* MCS_NO_ERROR
|
|
* Everything worked fine.
|
|
* MCS_TRANSMIT_BUFFER_FULL
|
|
* The request could not be processed due to a resource shortage
|
|
* within MCS. The application is responsible for re-trying the
|
|
* request at a later time.
|
|
* MCS_USER_NOT_ATTACHED
|
|
* The user is not attached to the domain. This could indicate that
|
|
* the user application issued a request without waiting for the
|
|
* attach user confirm.
|
|
* MCS_DOMAIN_MERGING
|
|
* This operation could not be performed due to a local merge operation
|
|
* in progress. The user application must retry at a later time.
|
|
*
|
|
* Side Effects:
|
|
* None.
|
|
*
|
|
* Caveats:
|
|
* None.
|
|
*/
|
|
|
|
/*
|
|
* MCSError ChannelAdmit (
|
|
* ChannelID channel_id,
|
|
* PUserID user_id_list,
|
|
* UINT user_id_count)
|
|
*
|
|
* Functional Description:
|
|
* This request comes from the application interface object in response
|
|
* to the same request from a user application. This object can then
|
|
* re-package the request as an MCS command and send it to the domain
|
|
* object.
|
|
*
|
|
* Formal Parameters:
|
|
* channel_id (i)
|
|
* This is the private channel for which the user wishes to expand
|
|
* the authorized user list.
|
|
* user_id_list (i)
|
|
* This is an array containing the user IDs of the users to be added
|
|
* to the authorized user list.
|
|
* user_id_count (i)
|
|
* This is the number of user IDs in the above array.
|
|
*
|
|
* Return Value:
|
|
* MCS_NO_ERROR
|
|
* Everything worked fine.
|
|
* MCS_TRANSMIT_BUFFER_FULL
|
|
* The request could not be processed due to a resource shortage
|
|
* within MCS. The application is responsible for re-trying the
|
|
* request at a later time.
|
|
* MCS_USER_NOT_ATTACHED
|
|
* The user is not attached to the domain. This could indicate that
|
|
* the user application issued a request without waiting for the
|
|
* attach user confirm.
|
|
* MCS_DOMAIN_MERGING
|
|
* This operation could not be performed due to a local merge operation
|
|
* in progress. The user application must retry at a later time.
|
|
*
|
|
* Side Effects:
|
|
* None.
|
|
*
|
|
* Caveats:
|
|
* None.
|
|
*/
|
|
|
|
/*
|
|
* MCSError ChannelExpel (
|
|
* ChannelID channel_id,
|
|
* PUserID user_id_list,
|
|
* UINT user_id_count)
|
|
*
|
|
* Functional Description:
|
|
* This request comes from the application interface object in response
|
|
* to the same request from a user application. This object can then
|
|
* re-package the request as an MCS command and send it to the domain
|
|
* object.
|
|
*
|
|
* Formal Parameters:
|
|
* channel_id (i)
|
|
* This is the private channel for which the user wishes to shrink
|
|
* the authorized user list.
|
|
* user_id_list (i)
|
|
* This is an array containing the user IDs of the users to be removed
|
|
* from the authorized user list.
|
|
* user_id_count (i)
|
|
* This is the number of user IDs in the above array.
|
|
*
|
|
* Return Value:
|
|
* MCS_NO_ERROR
|
|
* Everything worked fine.
|
|
* MCS_TRANSMIT_BUFFER_FULL
|
|
* The request could not be processed due to a resource shortage
|
|
* within MCS. The application is responsible for re-trying the
|
|
* request at a later time.
|
|
* MCS_USER_NOT_ATTACHED
|
|
* The user is not attached to the domain. This could indicate that
|
|
* the user application issued a request without waiting for the
|
|
* attach user confirm.
|
|
* MCS_DOMAIN_MERGING
|
|
* This operation could not be performed due to a local merge operation
|
|
* in progress. The user application must retry at a later time.
|
|
*
|
|
* Side Effects:
|
|
* None.
|
|
*
|
|
* Caveats:
|
|
* None.
|
|
*/
|
|
|
|
/*
|
|
* MCSError SendData (
|
|
* ChannelID channel_id,
|
|
* Priority priority,
|
|
* PUChar user_data,
|
|
* ULong user_data_length)
|
|
*
|
|
* Functional Description:
|
|
* This request comes from the application interface object in response
|
|
* to the same request from a user application. This object can then
|
|
* re-package the request as an MCS command and send it to the domain
|
|
* object.
|
|
*
|
|
* Formal Parameters:
|
|
* channel_id (i)
|
|
* This is the channel that the user application wishes to transmit
|
|
* data on.
|
|
* priority (i)
|
|
* This is the priority at which the data is to be transmitted.
|
|
* user_data (i)
|
|
* This is the address of the data to be transmitted.
|
|
* user_data_length (i)
|
|
* This is the length of the data to be transmitted.
|
|
*
|
|
* Return Value:
|
|
* MCS_NO_ERROR
|
|
* Everything worked fine.
|
|
* MCS_TRANSMIT_BUFFER_FULL
|
|
* The request has failed because the required memory could not be
|
|
* allocated. It is the responsibility of the user application to
|
|
* repeat the request at a later time.
|
|
* MCS_USER_NOT_ATTACHED
|
|
* The user is not attached to the domain. This could indicate that
|
|
* the user application issued a request without waiting for the
|
|
* attach user confirm.
|
|
* MCS_DOMAIN_MERGING
|
|
* This operation could not be performed due to a local merge operation
|
|
* in progress. The user application must retry at a later time.
|
|
*
|
|
* Side Effects:
|
|
* None.
|
|
*
|
|
* Caveats:
|
|
* None.
|
|
*/
|
|
/*
|
|
* MCSError TokenGrab (
|
|
* TokenID token_id)
|
|
*
|
|
* Functional Description:
|
|
* This request comes from the application interface object in response
|
|
* to the same request from a user application. This object can then
|
|
* re-package the request as an MCS command and send it to the domain
|
|
* object.
|
|
*
|
|
* Formal Parameters:
|
|
* token_id (i)
|
|
* This is the token the user application wishes to grab.
|
|
*
|
|
* Return Value:
|
|
* MCS_NO_ERROR
|
|
* Everything worked fine.
|
|
* MCS_TRANSMIT_BUFFER_FULL
|
|
* The request could not be processed due to a resource shortage
|
|
* within MCS. The application is responsible for re-trying the
|
|
* request at a later time.
|
|
* MCS_INVALID_PARAMETER
|
|
* The user attempted to perform an operation on token 0, which is not
|
|
* a valid token.
|
|
* MCS_USER_NOT_ATTACHED
|
|
* The user is not attached to the domain. This could indicate that
|
|
* the user application issued a request without waiting for the
|
|
* attach user confirm.
|
|
* MCS_DOMAIN_MERGING
|
|
* This operation could not be performed due to a local merge operation
|
|
* in progress. The user application must retry at a later time.
|
|
*
|
|
* Side Effects:
|
|
* None.
|
|
*
|
|
* Caveats:
|
|
* None.
|
|
*/
|
|
|
|
/*
|
|
* MCSError TokenInhibit (
|
|
* TokenID token_id)
|
|
*
|
|
* Functional Description:
|
|
* This request comes from the application interface object in response
|
|
* to the same request from a user application. This object can then
|
|
* re-package the request as an MCS command and send it to the domain
|
|
* object.
|
|
*
|
|
* Formal Parameters:
|
|
* token_id (i)
|
|
* This is the token the user application wishes to inhibit.
|
|
*
|
|
* Return Value:
|
|
* MCS_NO_ERROR
|
|
* Everything worked fine.
|
|
* MCS_TRANSMIT_BUFFER_FULL
|
|
* The request could not be processed due to a resource shortage
|
|
* within MCS. The application is responsible for re-trying the
|
|
* request at a later time.
|
|
* MCS_INVALID_PARAMETER
|
|
* The user attempted to perform an operation on token 0, which is not
|
|
* a valid token.
|
|
* MCS_USER_NOT_ATTACHED
|
|
* The user is not attached to the domain. This could indicate that
|
|
* the user application issued a request without waiting for the
|
|
* attach user confirm.
|
|
* MCS_DOMAIN_MERGING
|
|
* This operation could not be performed due to a local merge operation
|
|
* in progress. The user application must retry at a later time.
|
|
*
|
|
* Side Effects:
|
|
* None.
|
|
*
|
|
* Caveats:
|
|
* None.
|
|
*/
|
|
|
|
/*
|
|
* MCSError TokenGive (
|
|
* TokenID token_id,
|
|
* UserID receiver_id)
|
|
*
|
|
* Functional Description:
|
|
* This request comes from the application interface object in response
|
|
* to the same request from a user application. This object can then
|
|
* re-package the request as an MCS command and send it to the domain
|
|
* object.
|
|
*
|
|
* Formal Parameters:
|
|
* token_id (i)
|
|
* This is the token the user application wishes to give away.
|
|
* receiver_id (i)
|
|
* This is the ID of the user to receive the token.
|
|
*
|
|
* Return Value:
|
|
* MCS_NO_ERROR
|
|
* Everything worked fine.
|
|
* MCS_TRANSMIT_BUFFER_FULL
|
|
* The request could not be processed due to a resource shortage
|
|
* within MCS. The application is responsible for re-trying the
|
|
* request at a later time.
|
|
* MCS_INVALID_PARAMETER
|
|
* The user attempted to perform an operation on token 0, which is not
|
|
* a valid token.
|
|
* MCS_USER_NOT_ATTACHED
|
|
* The user is not attached to the domain. This could indicate that
|
|
* the user application issued a request without waiting for the
|
|
* attach user confirm.
|
|
* MCS_DOMAIN_MERGING
|
|
* This operation could not be performed due to a local merge operation
|
|
* in progress. The user application must retry at a later time.
|
|
*
|
|
* Side Effects:
|
|
* None.
|
|
*
|
|
* Caveats:
|
|
* None.
|
|
*/
|
|
|
|
/*
|
|
* MCSError TokenGiveResponse (
|
|
* TokenID token_id,
|
|
* Result result)
|
|
*
|
|
* Functional Description:
|
|
* This request comes from the application interface object in response
|
|
* to the same request from a user application. This object can then
|
|
* re-package the request as an MCS command and send it to the domain
|
|
* object.
|
|
*
|
|
* Formal Parameters:
|
|
* token_id (i)
|
|
* This is the token that the user application is either accepting or
|
|
* rejecting in response to a previous give indication from another
|
|
* user.
|
|
* result (i)
|
|
* This parameter specifies whether or not the token was accepted.
|
|
* Success indicates acceptance while anything else indicates that the
|
|
* token was not accepted.
|
|
*
|
|
* Return Value:
|
|
* MCS_NO_ERROR
|
|
* Everything worked fine.
|
|
* MCS_TRANSMIT_BUFFER_FULL
|
|
* The request could not be processed due to a resource shortage
|
|
* within MCS. The application is responsible for re-trying the
|
|
* request at a later time.
|
|
* MCS_INVALID_PARAMETER
|
|
* The user attempted to perform an operation on token 0, which is not
|
|
* a valid token.
|
|
* MCS_USER_NOT_ATTACHED
|
|
* The user is not attached to the domain. This could indicate that
|
|
* the user application issued a request without waiting for the
|
|
* attach user confirm.
|
|
* MCS_DOMAIN_MERGING
|
|
* This operation could not be performed due to a local merge operation
|
|
* in progress. The user application must retry at a later time.
|
|
*
|
|
* Side Effects:
|
|
* None.
|
|
*
|
|
* Caveats:
|
|
* None.
|
|
*/
|
|
|
|
/*
|
|
* MCSError TokenPlease (
|
|
* TokenID token_id)
|
|
*
|
|
* Functional Description:
|
|
* This request comes from the application interface object in response
|
|
* to the same request from a user application. This object can then
|
|
* re-package the request as an MCS command and send it to the domain
|
|
* object.
|
|
*
|
|
* Formal Parameters:
|
|
* token_id (i)
|
|
* This is the token the user application wishes to ask for.
|
|
*
|
|
* Return Value:
|
|
* MCS_NO_ERROR
|
|
* Everything worked fine.
|
|
* MCS_TRANSMIT_BUFFER_FULL
|
|
* The request could not be processed due to a resource shortage
|
|
* within MCS. The application is responsible for re-trying the
|
|
* request at a later time.
|
|
* MCS_INVALID_PARAMETER
|
|
* The user attempted to perform an operation on token 0, which is not
|
|
* a valid token.
|
|
* MCS_USER_NOT_ATTACHED
|
|
* The user is not attached to the domain. This could indicate that
|
|
* the user application issued a request without waiting for the
|
|
* attach user confirm.
|
|
* MCS_DOMAIN_MERGING
|
|
* This operation could not be performed due to a local merge operation
|
|
* in progress. The user application must retry at a later time.
|
|
*
|
|
* Side Effects:
|
|
* None.
|
|
*
|
|
* Caveats:
|
|
* None.
|
|
*/
|
|
|
|
/*
|
|
* MCSError TokenRelease (
|
|
* TokenID token_id)
|
|
*
|
|
* Functional Description:
|
|
* This request comes from the application interface object in response
|
|
* to the same request from a user application. This object can then
|
|
* re-package the request as an MCS command and send it to the domain
|
|
* object.
|
|
*
|
|
* Formal Parameters:
|
|
* token_id (i)
|
|
* This is the token the user application wishes to release.
|
|
*
|
|
* Return Value:
|
|
* MCS_NO_ERROR
|
|
* Everything worked fine.
|
|
* MCS_TRANSMIT_BUFFER_FULL
|
|
* The request could not be processed due to a resource shortage
|
|
* within MCS. The application is responsible for re-trying the
|
|
* request at a later time.
|
|
* MCS_INVALID_PARAMETER
|
|
* The user attempted to perform an operation on token 0, which is not
|
|
* a valid token.
|
|
* MCS_USER_NOT_ATTACHED
|
|
* The user is not attached to the domain. This could indicate that
|
|
* the user application issued a request without waiting for the
|
|
* attach user confirm.
|
|
* MCS_DOMAIN_MERGING
|
|
* This operation could not be performed due to a local merge operation
|
|
* in progress. The user application must retry at a later time.
|
|
*
|
|
* Side Effects:
|
|
* None.
|
|
*
|
|
* Caveats:
|
|
* None.
|
|
*/
|
|
|
|
/*
|
|
* MCSError TokenTest(
|
|
* TokenID token_id)
|
|
*
|
|
* Functional Description:
|
|
* This request comes from the application interface object in response
|
|
* to the same request from a user application. This object can then
|
|
* re-package the request as an MCS command and send it to the domain
|
|
* object.
|
|
*
|
|
* Formal Parameters:
|
|
* token_id (i)
|
|
* This is the token the user application wishes to test the state of.
|
|
*
|
|
* Return Value:
|
|
* MCS_NO_ERROR
|
|
* Everything worked fine.
|
|
* MCS_TRANSMIT_BUFFER_FULL
|
|
* The request could not be processed due to a resource shortage
|
|
* within MCS. The application is responsible for re-trying the
|
|
* request at a later time.
|
|
* MCS_INVALID_PARAMETER
|
|
* The user attempted to perform an operation on token 0, which is not
|
|
* a valid token.
|
|
* MCS_USER_NOT_ATTACHED
|
|
* The user is not attached to the domain. This could indicate that
|
|
* the user application issued a request without waiting for the
|
|
* attach user confirm.
|
|
* MCS_DOMAIN_MERGING
|
|
* This operation could not be performed due to a local merge operation
|
|
* in progress. The user application must retry at a later time.
|
|
*
|
|
* Side Effects:
|
|
* None.
|
|
*
|
|
* Caveats:
|
|
* None.
|
|
*/
|
|
|
|
/*
|
|
* Void SetDomainParameters (
|
|
* PDomainParameters domain_parameters)
|
|
*
|
|
* Functional Description:
|
|
* This member function is called whenever the domain parameters change
|
|
* as the result of accepting a first connection. It informs the user
|
|
* object of a change in the maximum PDU size, which is used when creating
|
|
* outbound data PDUs.
|
|
*
|
|
* Formal Parameters:
|
|
* domain_parameters (i)
|
|
* Pointer to a structure that contains the current domain parameters
|
|
* (those that are in use).
|
|
*
|
|
* Return Value:
|
|
* None.
|
|
*
|
|
* Side Effects:
|
|
* None.
|
|
*
|
|
* Caveats:
|
|
* None.
|
|
*/
|
|
|
|
/*
|
|
* Void PlumbDomainIndication (
|
|
* PCommandTarget originator,
|
|
* ULong height_limit)
|
|
*
|
|
* Functional Description:
|
|
* This command is issued by the domain object during a plumb domain
|
|
* operation. This is not relevant to user objects, and should be ignored.
|
|
*
|
|
* Formal Parameters:
|
|
* originator (i)
|
|
* This identifies the CommandTarget from which the command came (which
|
|
* should be the domain object).
|
|
* height_limit (i)
|
|
* This is height value passed through during the plumb operation.
|
|
*
|
|
* Return Value:
|
|
* None.
|
|
*
|
|
* Side Effects:
|
|
* None.
|
|
*
|
|
* Caveats:
|
|
* None.
|
|
*/
|
|
|
|
/*
|
|
* Void PurgeChannelsIndication (
|
|
* PCommandTarget originator,
|
|
* CUidList *purge_user_list,
|
|
* CChannelIDList *purge_channel_list)
|
|
*
|
|
* Functional Description:
|
|
* This command is issued by the domain object when purging channels
|
|
* from the lower domain during a domain merge operation.
|
|
*
|
|
* The user object will issue one MCS_DETACH_USER_INDICATION object for
|
|
* each user in the user list. Furthermore, if the user objects finds
|
|
* its own user ID in the list, it will destroy itself.
|
|
*
|
|
* Formal Parameters:
|
|
* originator (i)
|
|
* This identifies the CommandTarget from which the command came (which
|
|
* should be the domain object).
|
|
* purge_user_list (i)
|
|
* This is a list of user IDs that are to be purged from the lower
|
|
* domain.
|
|
* purge_channel_list (i)
|
|
* This is a list of channel IDs that are to be purged from the lower
|
|
* domain.
|
|
*
|
|
* Return Value:
|
|
* None.
|
|
*
|
|
* Side Effects:
|
|
* None.
|
|
*
|
|
* Caveats:
|
|
* None.
|
|
*/
|
|
|
|
/*
|
|
* Void PurgeTokensIndication (
|
|
* PCommandTarget originator,
|
|
* CTokenIDList *token_id_list)
|
|
*
|
|
* Functional Description:
|
|
* This command is issued by the domain object when purging tokens from
|
|
* the lower domain during a domain merge operation. IT is not relevant
|
|
* to a user object, and is therefore ignored.
|
|
*
|
|
* Formal Parameters:
|
|
* originator (i)
|
|
* This identifies the CommandTarget from which the command came (which
|
|
* should be the domain object).
|
|
* token_id (i)
|
|
* This is the ID of the token that is being purged.
|
|
*
|
|
* Return Value:
|
|
* None.
|
|
*
|
|
* Side Effects:
|
|
* None.
|
|
*
|
|
* Caveats:
|
|
* None.
|
|
*/
|
|
|
|
/*
|
|
* Void DisconnectProviderUltimatum (
|
|
* PCommandTarget originator,
|
|
* Reason reason)
|
|
*
|
|
* Functional Description:
|
|
* This command is issued by the domain object when it is necessary to
|
|
* force a user from the domain. This usually happens in response to
|
|
* the purging of an entire domain (either this user was in the bottom
|
|
* of a disconnected domain or the domain was deleted locally by user
|
|
* request).
|
|
*
|
|
* If the user was already attached to the domain, this will result in a
|
|
* DETACH_USER_INDICATION with the local user ID. Otherwise this will
|
|
* result is an ATTACH_USER_CONFIRM with a result of UNSPECIFIED_FAILURE.
|
|
*
|
|
* Formal Parameters:
|
|
* originator (i)
|
|
* This identifies the CommandTarget from which the command came (which
|
|
* should be the domain object).
|
|
* reason (i)
|
|
* This is the reason parameter to be issued to the local user
|
|
* application. See "mcatmcs.h" for a complete list of possible reaons.
|
|
*
|
|
* Return Value:
|
|
* None.
|
|
*
|
|
* Side Effects:
|
|
* None.
|
|
*
|
|
* Caveats:
|
|
* None.
|
|
*/
|
|
|
|
/*
|
|
* Void AttachUserConfirm (
|
|
* PCommandTarget originator,
|
|
* Result result,
|
|
* UserID uidInitiator)
|
|
*
|
|
* Functional Description:
|
|
* This command is issued by the domain object in response to the
|
|
* attach user request issued by this object during construction. If the
|
|
* result is successful, then this user is now attached and may request
|
|
* MCS services through this attachment.
|
|
*
|
|
* An ATTACH_USER_CONFIRM will be issued to the user application. If the
|
|
* result is not successful, this object will delete itself.
|
|
*
|
|
* Formal Parameters:
|
|
* originator (i)
|
|
* This identifies the CommandTarget from which the command came (which
|
|
* should be the domain object).
|
|
* result (i)
|
|
* This is the result of the attach request.
|
|
* uidInitiator (i)
|
|
* If the result was successful, this is the new user ID associated
|
|
* with this attachment.
|
|
*
|
|
* Return Value:
|
|
* None.
|
|
*
|
|
* Side Effects:
|
|
* None.
|
|
*
|
|
* Caveats:
|
|
* None.
|
|
*/
|
|
|
|
/*
|
|
* Void DetachUserIndication (
|
|
* PCommandTarget originator,
|
|
* Reason reason,
|
|
* CUidList *user_id_list)
|
|
*
|
|
* Functional Description:
|
|
* This command is issued by the domain object when one or more users leave
|
|
* the domain.
|
|
*
|
|
* An MCS_DETACH_USER_INDICATION is issued to the user application for each
|
|
* user in the list. Furthermore, if the user finds its own ID in the
|
|
* list, then it will destroy itself.
|
|
*
|
|
* Formal Parameters:
|
|
* originator (i)
|
|
* This identifies the CommandTarget from which the command came (which
|
|
* should be the domain object).
|
|
* reason (i)
|
|
* This is the reason for the detachment. Possible values are listed
|
|
* in "mcatmcs.h".
|
|
* user_id_list (i)
|
|
* This is a list user IDs of the users that are leaving.
|
|
*
|
|
* 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 command is issued by the domain object in response to a previous
|
|
* channel join request.
|
|
*
|
|
* A CHANNEL_JOIN_CONFIRM is issued to the user application. Note that a
|
|
* user is not really considered to be joined to a channel until a
|
|
* successful confirm is received.
|
|
*
|
|
* Formal Parameters:
|
|
* originator (i)
|
|
* This identifies the CommandTarget from which the command came (which
|
|
* should be the domain object).
|
|
* result (i)
|
|
* This is the result from the join request. If successful, then the
|
|
* user is now joined to the channel.
|
|
* uidInitiator (i)
|
|
* This is the user ID of the requestor. It will be the same as the
|
|
* local user ID (or else this command would not have gotten here).
|
|
* requested_id (i)
|
|
* This is the ID of the channel that the user originally requested
|
|
* to join. This will differ from the ID of the channel actually
|
|
* joined only if this ID is 0 (which identifies a request to join an
|
|
* assigned channel).
|
|
* channel_id (i)
|
|
* This is the channel that is now joined. This is important for
|
|
* two reasons. First, it is possible for a user to have more than
|
|
* one outstanding join request, in which case this parameter
|
|
* identifies which channel this confirm is for. Second, if the
|
|
* request is for channel 0 (zero), then this parameter identifies
|
|
* which assigned channel the user has successfully joined.
|
|
*
|
|
* Return Value:
|
|
* None.
|
|
*
|
|
* Side Effects:
|
|
* None.
|
|
*
|
|
* Caveats:
|
|
* None.
|
|
*/
|
|
|
|
/*
|
|
* Void ChannelLeaveIndication (
|
|
* PCommandTarget originator,
|
|
* Reason reason,
|
|
* ChannelID channel_id)
|
|
*
|
|
* Functional Description:
|
|
* This command is issued by the domain object when a user loses its right
|
|
* to use a channel.
|
|
*
|
|
* A CHANNEL_LEAVE_INDICATION is issued to the user application.
|
|
*
|
|
* Formal Parameters:
|
|
* originator (i)
|
|
* This identifies the CommandTarget from which the command came (which
|
|
* should be the domain object).
|
|
* reason (i)
|
|
* This is the reason for the lost channel. Possible values are listed
|
|
* in "mcatmcs.h".
|
|
* channel (i)
|
|
* This is the channel that the user can no longer use.
|
|
*
|
|
* Return Value:
|
|
* None.
|
|
*
|
|
* Side Effects:
|
|
* None.
|
|
*
|
|
* Caveats:
|
|
* None.
|
|
*/
|
|
|
|
/*
|
|
* Void ChannelConveneConfirm (
|
|
* PCommandTarget originator,
|
|
* Result result,
|
|
* UserID uidInitiator,
|
|
* ChannelID channel_id)
|
|
*
|
|
* Functional Description:
|
|
* This command is issued by the domain object in response to a previous
|
|
* channel convene request.
|
|
*
|
|
* A CHANNEL_CONVENE_CONFIRM is issued to the user application.
|
|
*
|
|
* Formal Parameters:
|
|
* originator (i)
|
|
* This identifies the CommandTarget from which the command came (which
|
|
* should be the domain object).
|
|
* result (i)
|
|
* This is the result from the convene request. If successful, then
|
|
* a private channel has been created, with this user as the manager.
|
|
* uidInitiator (i)
|
|
* This is the user ID of the requestor. It will be the same as the
|
|
* local user ID (or else this command would not have gotten here).
|
|
* channel_id (i)
|
|
* This is the channel ID for the newly created private channel.
|
|
*
|
|
* Return Value:
|
|
* None.
|
|
*
|
|
* Side Effects:
|
|
* None.
|
|
*
|
|
* Caveats:
|
|
* None.
|
|
*/
|
|
|
|
/*
|
|
* Void ChannelDisbandIndication (
|
|
* PCommandTarget originator,
|
|
* ChannelID channel_id)
|
|
*
|
|
* Functional Description:
|
|
* This command is issued by the domain object to the manager of a private
|
|
* channel when MCS determines the need to disband the channel. This will
|
|
* usually be done only if the channel is purged during a domain merger.
|
|
*
|
|
* A CHANNEL_DISBAND_INDICATION is issued to the user application.
|
|
*
|
|
* Formal Parameters:
|
|
* originator (i)
|
|
* This identifies the CommandTarget from which the command came (which
|
|
* should be the domain object).
|
|
* channel_id (i)
|
|
* This is the channel ID of the private channel that is being
|
|
* disbanded.
|
|
*
|
|
* Return Value:
|
|
* None.
|
|
*
|
|
* Side Effects:
|
|
* None.
|
|
*
|
|
* Caveats:
|
|
* None.
|
|
*/
|
|
|
|
/*
|
|
* Void ChannelAdmitIndication (
|
|
* PCommandTarget originator,
|
|
* UserID uidInitiator,
|
|
* ChannelID channel_id,
|
|
* CUidList *user_id_list)
|
|
*
|
|
* Functional Description:
|
|
* This command is issued by the domain object when a user is admitted to
|
|
* a private channel by the manager of that channel. It informs the user
|
|
* that the channel can be used.
|
|
*
|
|
* A CHANNEL_ADMIT_INDICATION is issued to the user application.
|
|
*
|
|
* Formal Parameters:
|
|
* originator (i)
|
|
* This identifies the CommandTarget from which the command came (which
|
|
* should be the domain object).
|
|
* uidInitiator (i)
|
|
* This is the user ID of the private channel manager.
|
|
* channel_id (i)
|
|
* This is the channel ID of the private channel to which the user has
|
|
* been admitted.
|
|
* user_id_list (i)
|
|
* This is a container holding the IDs of the users that have been
|
|
* admitted. By the time this reaches a particular user, that user
|
|
* should be the only one in the list (since the list is broken apart
|
|
* and forwarded in the direction of the contained users, recursively).
|
|
*
|
|
* Return Value:
|
|
* None.
|
|
*
|
|
* Side Effects:
|
|
* None.
|
|
*
|
|
* Caveats:
|
|
* None.
|
|
*/
|
|
|
|
/*
|
|
* Void ChannelExpelIndication (
|
|
* PCommandTarget originator,
|
|
* ChannelID channel_id,
|
|
* CUidList *user_id_list)
|
|
*
|
|
* Functional Description:
|
|
* This command is issued by the domain object when a user is expelled from
|
|
* a private channel by the manager of that channel. It informs the user
|
|
* that the channel can no longer be used.
|
|
*
|
|
* A CHANNEL_EXPEL_INDICATION is issued to the user application.
|
|
*
|
|
* Formal Parameters:
|
|
* originator (i)
|
|
* This identifies the CommandTarget from which the command came (which
|
|
* should be the domain object).
|
|
* channel_id (i)
|
|
* This is the channel ID of the private channel from which the user
|
|
* has been expelled.
|
|
* user_id_list (i)
|
|
* This is a container holding the IDs of the users that have been
|
|
* expelled. By the time this reaches a particular user, that user
|
|
* should be the only one in the list (since the list is broken apart
|
|
* and forwarded in the direction of the contained users, recursively).
|
|
*
|
|
* Return Value:
|
|
* None.
|
|
*
|
|
* Side Effects:
|
|
* None.
|
|
*
|
|
* Caveats:
|
|
* None.
|
|
*/
|
|
|
|
/*
|
|
* Void SendDataIndication (
|
|
* PCommandTarget originator,
|
|
* UINT message_type,
|
|
* PDataPacket data_packet)
|
|
*
|
|
* Functional Description:
|
|
* This command is issued by the domain object when non-uniform data
|
|
* data is received on a channel to which this user is joined.
|
|
*
|
|
* A SEND_DATA_INDICATION is issued to the user application.
|
|
*
|
|
* Formal Parameters:
|
|
* originator (i)
|
|
* This identifies the CommandTarget from which the command came (which
|
|
* should be the domain object).
|
|
* message_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 TokenGrabConfirm (
|
|
* PCommandTarget originator,
|
|
* Result result,
|
|
* UserID uidInitiator,
|
|
* TokenID token_id,
|
|
* TokenStatus token_status)
|
|
*
|
|
* Functional Description:
|
|
* This command is issued by the domain object in response to a previous
|
|
* token grab request.
|
|
*
|
|
* A TOKEN_GRAB_CONFIRM is issued to the user application.
|
|
*
|
|
* Formal Parameters:
|
|
* originator (i)
|
|
* This identifies the CommandTarget from which the command came (which
|
|
* should be the domain object).
|
|
* result (i)
|
|
* This is the result of the grab request. If successful, the user
|
|
* now exclusively owns the token.
|
|
* uidInitiator (i)
|
|
* This is the user ID of the user that made the grab request. This
|
|
* will be the same as the local user ID (or else this command would
|
|
* not have gotten here).
|
|
* token_id (i)
|
|
* This is the ID of the token which the grab confirm is for. It
|
|
* is possible to have more than one outstanding grab request, so this
|
|
* parameter tells the user application which request has been
|
|
* satisfied by this confirm.
|
|
* token_status (i)
|
|
* This is the status of the token at the time the Top Provider
|
|
* serviced the grab request. This will be SELF_GRABBED if the grab
|
|
* request was successful. It will be something else if not (see
|
|
* "mcatmcs.h" for a list of possible token status values).
|
|
*
|
|
* 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 command is issued by the domain object in response to a previous
|
|
* token inhibit request.
|
|
*
|
|
* A TOKEN_INHIBIT_CONFIRM is issued to the user application.
|
|
*
|
|
* Formal Parameters:
|
|
* originator (i)
|
|
* This identifies the CommandTarget from which the command came (which
|
|
* should be the domain object).
|
|
* result (i)
|
|
* This is the result of the inhibit request. If successful, the user
|
|
* now non-exclusively owns the token.
|
|
* uidInitiator (i)
|
|
* This is the user ID of the user that made the inhibit request. This
|
|
* will be the same as the local user ID (or else this command would
|
|
* not have gotten here).
|
|
* token_id (i)
|
|
* This is the ID of the token which the inihibit confirm is for.
|
|
* It is possible to have more than one outstanding inihibit request,
|
|
* so this parameter tells the user application which request has been
|
|
* satisfied by this confirm.
|
|
* token_status (i)
|
|
* This is the status of the token at the time the Top Provider
|
|
* serviced the inhibit request. This will be SELF_INHIBITED if the
|
|
* inhibit request was successful. It will be something else if not
|
|
* (see "mcatmcs.h" for a list of possible token status values).
|
|
*
|
|
* Return Value:
|
|
* None.
|
|
*
|
|
* Side Effects:
|
|
* None.
|
|
*
|
|
* Caveats:
|
|
* None.
|
|
*/
|
|
|
|
/*
|
|
* Void TokenGiveIndication (
|
|
* PCommandTarget originator,
|
|
* PTokenGiveRecord pTokenGiveRec)
|
|
*
|
|
* Functional Description:
|
|
* This command is issued by the domain object in response to a remote
|
|
* token give request (with the local user listed as the desired receiver).
|
|
*
|
|
* A TOKEN_GIVE_INDICATION is issued to the user application.
|
|
*
|
|
* Formal Parameters:
|
|
* originator (i)
|
|
* This identifies the CommandTarget from which the command came (which
|
|
* should be the domain object).
|
|
* 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 TokenGiveConfirm (
|
|
* PCommandTarget originator,
|
|
* Result result,
|
|
* UserID uidInitiator,
|
|
* TokenID token_id,
|
|
* TokenStatus token_status)
|
|
*
|
|
* Functional Description:
|
|
* This command is issued by the domain object in response to a previous
|
|
* token give request.
|
|
*
|
|
* A TOKEN_GIVE_CONFIRM is issued to the user application.
|
|
*
|
|
* Formal Parameters:
|
|
* originator (i)
|
|
* This identifies the CommandTarget from which the command came (which
|
|
* should be the domain object).
|
|
* result (i)
|
|
* This is the result of the give request. If successful, the user
|
|
* no longer owns the token.
|
|
* uidInitiator (i)
|
|
* This is the user ID of the user that made the give request. This
|
|
* will be the same as the local user ID (or else this command would
|
|
* not have gotten here).
|
|
* token_id (i)
|
|
* This is the ID of the token which the give confirm is for.
|
|
* token_status (i)
|
|
* This is the status of the token at the time the Top Provider
|
|
* serviced the give request.
|
|
*
|
|
* Return Value:
|
|
* None.
|
|
*
|
|
* Side Effects:
|
|
* None.
|
|
*
|
|
* Caveats:
|
|
* None.
|
|
*/
|
|
|
|
/*
|
|
* Void TokenPleaseIndication (
|
|
* PCommandTarget originator,
|
|
* UserID uidInitiator,
|
|
* TokenID token_id)
|
|
*
|
|
* Functional Description:
|
|
* This command is issued by the domain object to all owners of a token
|
|
* when a user issues a token please request for that token.
|
|
*
|
|
* A TOKEN_PLEASE_INDICATION is issued to the user application.
|
|
*
|
|
* Formal Parameters:
|
|
* originator (i)
|
|
* This identifies the CommandTarget from which the command came (which
|
|
* should be the domain object).
|
|
* uidInitiator (i)
|
|
* This is the user ID of the user that made the please request.
|
|
* token_id (i)
|
|
* This is the ID of the token which the please request is for.
|
|
*
|
|
* Return Value:
|
|
* None.
|
|
*
|
|
* Side Effects:
|
|
* None.
|
|
*
|
|
* Caveats:
|
|
* None.
|
|
*/
|
|
|
|
/*
|
|
* Void TokenReleaseIndication (
|
|
* PCommandTarget originator,
|
|
* Reason reason,
|
|
* TokenID token_id)
|
|
*
|
|
* Functional Description:
|
|
* This command is issued by the domain object when a token is taken
|
|
* away from its current owner.
|
|
*
|
|
* A TOKEN_RELEASE_INDICATION is issued to the user application.
|
|
*
|
|
* Formal Parameters:
|
|
* originator (i)
|
|
* This identifies the CommandTarget from which the command came (which
|
|
* should be the domain object).
|
|
* reason (i)
|
|
* This is the reason the token is being taken away.
|
|
* token_id (i)
|
|
* This is the ID of the token that is being taken away.
|
|
*
|
|
* 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 command is issued by the domain object in response to a previous
|
|
* token release request.
|
|
*
|
|
* A TOKEN_RELEASE_CONFIRM is issued to the user application.
|
|
*
|
|
* Formal Parameters:
|
|
* originator (i)
|
|
* This identifies the CommandTarget from which the command came (which
|
|
* should be the domain object).
|
|
* result (i)
|
|
* This is the result of the release request. If successful, the user
|
|
* no longer owns the token (if it ever did)
|
|
* uidInitiator (i)
|
|
* This is the user ID of the user that made the release request. This
|
|
* will be the same as the local user ID (or else this command would
|
|
* not have gotten here).
|
|
* token_id (i)
|
|
* This is the ID of the token which the release confirm is for.
|
|
* It is possible to have more than one outstanding release request,
|
|
* so this parameter tells the user application which request has been
|
|
* satisfied by this confirm.
|
|
* token_status (i)
|
|
* This is the status of the token at the time the Top Provider
|
|
* serviced the release request. This will be NOT_IN_USE or
|
|
* OTHER_INHIBITED if the release request was successful. It will be
|
|
* something else if not (see "mcatmcs.h" for a list of possible token
|
|
* status values).
|
|
*
|
|
* Return Value:
|
|
* None.
|
|
*
|
|
* Side Effects:
|
|
* None.
|
|
*
|
|
* Caveats:
|
|
* None.
|
|
*/
|
|
|
|
/*
|
|
* Void TokenTestConfirm (
|
|
* PCommandTarget originator,
|
|
* UserID uidInitiator,
|
|
* TokenID token_id,
|
|
* TokenStatus token_status)
|
|
*
|
|
* Functional Description:
|
|
* This command is issued by the domain object in response to a previous
|
|
* token test request.
|
|
*
|
|
* A TOKEN_TEST_CONFIRM is issued to the user application.
|
|
*
|
|
* Formal Parameters:
|
|
* originator (i)
|
|
* This identifies the CommandTarget from which the command came (which
|
|
* should be the domain object).
|
|
* uidInitiator (i)
|
|
* This is the user ID of the user that made the test request. This
|
|
* will be the same as the local user ID (or else this command would
|
|
* not have gotten here).
|
|
* token_id (i)
|
|
* This is the ID of the token which the test confirm is for.
|
|
* It is possible to have more than one outstanding test request,
|
|
* so this parameter tells the user application which request has been
|
|
* satisfied by this confirm.
|
|
* token_status (i)
|
|
* This is the status of the token at the time the Top Provider
|
|
* serviced the test request (see "mcatmcs.h" for a list of possible
|
|
* token status values).
|
|
*
|
|
* Return Value:
|
|
* None.
|
|
*
|
|
* Side Effects:
|
|
* None.
|
|
*
|
|
* Caveats:
|
|
* None.
|
|
*/
|
|
|
|
/*
|
|
* Void MergeDomainIndication (
|
|
* PCommandTarget originator,
|
|
* MergeStatus merge_status)
|
|
*
|
|
* Functional Description:
|
|
* This command is issued by a domain when it begins a merge operation.
|
|
* It is issued again when the merge operation is complete.
|
|
*
|
|
* A MERGE_DOMAIN_INDICATION is issued to the user application.
|
|
*
|
|
* Formal Parameters:
|
|
* originator (i)
|
|
* This identifies the CommandTarget from which the command came (which
|
|
* should be the domain object).
|
|
* merge_status (i)
|
|
* This is the current merge status. It will indicate either that the
|
|
* merge operation is in progress, or that it is complete.
|
|
*
|
|
* Return Value:
|
|
* None.
|
|
*
|
|
* Side Effects:
|
|
* None.
|
|
*
|
|
* Caveats:
|
|
* None.
|
|
*/
|
|
|
|
/*
|
|
* Void FlushMessageQueue (
|
|
* Void)
|
|
*
|
|
* Functional Description:
|
|
* This function is periodically called by the controller to allocate a
|
|
* time slice to the user object. It is during this time slice that this
|
|
* object will issue its queued messages to the user application.
|
|
*
|
|
* Formal Parameters:
|
|
* None.
|
|
*
|
|
* Return Value:
|
|
* None.
|
|
*
|
|
* Side Effects:
|
|
* None.
|
|
*
|
|
* Caveats:
|
|
* None.
|
|
*/
|
|
|
|
#endif
|
|
|