windows-nt/Source/XPSP1/NT/termsrv/inc/mcscommn.h
2020-09-26 16:20:57 +08:00

405 lines
12 KiB
C

/* (C) 1997-1998 Microsoft Corp.
*
* file : MCSCommn.h
* author : Erik Mavrinac
*
* description: Common definitions for MCS.
*/
#ifndef __MCSCOMMN_H
#define __MCSCOMMN_H
/*
* MCSError return codes from MCS entry points. These are distinct from
* T.125 Result, Diagnostic, and Reason codes which are defined below.
*
* MCS_NO_ERROR
* Success. This does not imply that the requested function is complete if
* the requested service is asynchronous -- the result code in a callback
* gives this information. This value should also be returned when handling
* an MCS callback and the callback has been processed.
*
* MCS_COMMAND_NOT_SUPPORTED
* The called entry point is not yet implemented.
*
* MCS_NOT_INITIALIZED
* The application has attempted to use MCS services before MCS has been
* initialized. It is necessary for the node controller (or whatever
* application is serving as the node controller), to initialize MCS
* before it is called upon to perform any services.
*
* MCS_ALREADY_INITIALIZED
* The application has attempted to initialize MCS when it is already
* initialized.
*
* MCS_DOMAIN_ALREADY_EXISTS
* The application has attempted to create a domain that already exists.
*
* MCS_USER_NOT_ATTACHED
* This indicates that the application has issued an MCSAttachUserRequest,
* and then tried to use the returned handle before receiving an
* MCS_ATTACH_USER_CONFIRM (which essentially validates the handle).
*
* MCS_NO_SUCH_USER
* An unknown user handle was used during an MCS call.
*
* MCS_TRANSMIT_BUFFER_FULL
* This indicates that the call failed due to an MCS resource shortage.
* This will typically occur when there is a LOT of traffic through the
* MCS layer. It simply means that MCS could not process the request at
* this time. It is the responsibility of the application to retry at a
* later time.
*
* MCS_NO_SUCH_CONNECTION
* An unknown connection handle was used during an MCS call.
*
* MCS_NO_SUCH_DOMAIN
* The DomainHandle used was not valid.
*
* MCS_DOMAIN_NOT_HIERARCHICAL
* An attempt has been made to create an upward connection from a local
* domain that already has an upward connection.
*
* MCS_ALLOCATION_FAILURE
* The request could not be successfully invoked due to a resource
* allocation failure.
*
* MCS_INVALID_PARAMETER
* One of the parameters to an MCS call is invalid.
*/
typedef enum
{
MCS_NO_ERROR,
MCS_COMMAND_NOT_SUPPORTED,
MCS_NOT_INITIALIZED,
MCS_ALREADY_INITIALIZED,
MCS_DOMAIN_ALREADY_EXISTS,
MCS_NO_SUCH_DOMAIN,
MCS_USER_NOT_ATTACHED,
MCS_NO_SUCH_USER,
MCS_NO_SUCH_CONNECTION,
MCS_NO_SUCH_CHANNEL,
MCS_DOMAIN_NOT_HIERARCHICAL,
MCS_ALLOCATION_FAILURE,
MCS_INVALID_PARAMETER,
MCS_CALLBACK_NOT_PROCESSED,
MCS_TOO_MANY_USERS,
MCS_TOO_MANY_CHANNELS,
MCS_CANT_JOIN_OTHER_USER_CHANNEL,
MCS_USER_NOT_JOINED,
MCS_SEND_SIZE_TOO_LARGE,
MCS_SEND_SIZE_TOO_SMALL,
MCS_NETWORK_ERROR,
MCS_DUPLICATE_CHANNEL
} MCSError;
typedef MCSError *PMCSError;
/*
* MCS types
*
* DomainHandle: Identifies a unique domain.
*
* ConnectionHandle: Identifies a distinct connection between two nodes in
* an MCS domain.
*
* UserHandle: Identifies a unique local user attachment.
*
* ChannelHandle: Identifies a unique channel that has been joined locally.
* Different from a ChannelID -- a ChannelID corresponds to a T.125
* ChannelID whereas a ChannelHandle is a local handle only.
*
* ChannelID: Identifies an MCS channel. There are four different
* types of channels that are part of this type: user ID, static, private,
* and assigned.
*
* UserID: This is a special channel that identifies a particular user in an
* MCS domain. Only that user can join the channel, so this is referred
* to as a single-cast channel. All other channels are multi-cast,
* meaning that any number of users can join them at once.
*
* TokenID: A token is an MCS object that is used to resolve resource conflicts.
* If an application has a particular resource or service that can only
* be used by one user at a time, that user can request exclusive
* ownership of a token.
*
* DomainParameters: The set of negotiated characteristics of an MCS domain.
* These are negotiated by the first two nodes in a domain, after which
* they are set for all members.
*
* MCSPriority: Identifiers for the four data send priorities allowed in MCS.
*
* Segmentation: Flag field for use during data sends, specifies how the data
* are broken up between sends. SEGMENTATION_BEGIN implies that this is the
* first block in a sequence; SEGMETNATION_END means this is the last block.
* A singleton block would specify both flags.
*
* TokenStatus: States of a token. Corresponds to the TokenStatus enumeration
* values defined in T.125.
*
* MCSReason, MCSResult: Correspond to the values defined for the Reason and
* Result enumerations defined in the T.125 spec.
*/
typedef HANDLE DomainHandle;
typedef DomainHandle *PDomainHandle;
typedef HANDLE ConnectionHandle;
typedef ConnectionHandle *PConnectionHandle;
typedef HANDLE UserHandle;
typedef UserHandle *PUserHandle;
typedef HANDLE ChannelHandle;
typedef ChannelHandle *PChannelHandle;
typedef unsigned char *DomainSelector;
typedef unsigned ChannelID;
typedef ChannelID *PChannelID;
typedef ChannelID UserID;
typedef UserID *PUserID;
typedef ChannelID TokenID;
typedef TokenID *PTokenID;
typedef struct
{
unsigned MaxChannels;
unsigned MaxUsers;
unsigned MaxTokens;
unsigned NumPriorities;
unsigned MinThroughput;
unsigned MaxDomainHeight;
unsigned MaxPDUSize;
unsigned ProtocolVersion;
} DomainParameters, *PDomainParameters;
typedef enum
{
MCS_TOP_PRIORITY = 0,
MCS_HIGH_PRIORITY = 1,
MCS_MEDIUM_PRIORITY = 2,
MCS_LOW_PRIORITY = 3
} MCSPriority;
typedef MCSPriority *PMCSPriority;
// Segmentation type and flags. The flag values correspond to bit locations
// in PER-encoded PDUs for faster PDU creation.
typedef unsigned Segmentation;
typedef Segmentation *PSegmentation;
#define SEGMENTATION_BEGIN 0x20
#define SEGMENTATION_END 0x10
// Not used in this implementation, this comes from the NetMeeting user-mode
// MCS implementation.
#if 0
// SegmentationFlag: Alternate specification of segmentation type that defines
// how the buffers that are given to SendDataRequest() are divided in packets.
typedef enum {
SEGMENTATION_ONE_PACKET, // All the buffers make up one packet
SEGMENTATION_MANY_PACKETS, // Each buffer makes up one packet
SEGMENTATION_PACKET_START, // The first buffers of one packet
SEGMENTATION_PACKET_CONTINUE, // Middle buffers of a packet that was started earlier
SEGMENTATION_PACKET_END // The ending buffers of a packet which started earlier
} SegmentationFlag, *PSegmentationFlag;
#endif
typedef enum
{
TOKEN_NOT_IN_USE = 0,
TOKEN_SELF_GRABBED = 1,
TOKEN_OTHER_GRABBED = 2,
TOKEN_SELF_INHIBITED = 3,
TOKEN_OTHER_INHIBITED = 4,
TOKEN_SELF_RECIPIENT = 5,
TOKEN_SELF_GIVING = 6,
TOKEN_OTHER_GIVING = 7
} TokenStatus;
typedef TokenStatus *PTokenStatus;
typedef enum
{
REASON_DOMAIN_DISCONNECTED = 0,
REASON_PROVIDER_INITIATED = 1,
REASON_TOKEN_PURGED = 2,
REASON_USER_REQUESTED = 3,
REASON_CHANNEL_PURGED = 4
} MCSReason, *PMCSReason;
typedef enum
{
RESULT_SUCCESSFUL = 0,
RESULT_DOMAIN_MERGING = 1,
RESULT_DOMAIN_NOT_HIERARCHICAL = 2,
RESULT_NO_SUCH_CHANNEL = 3,
RESULT_NO_SUCH_DOMAIN = 4,
RESULT_NO_SUCH_USER = 5,
RESULT_NOT_ADMITTED = 6,
RESULT_OTHER_USER_ID = 7,
RESULT_PARAMETERS_UNACCEPTABLE = 8,
RESULT_TOKEN_NOT_AVAILABLE = 9,
RESULT_TOKEN_NOT_POSSESSED = 10,
RESULT_TOO_MANY_CHANNELS = 11,
RESULT_TOO_MANY_TOKENS = 12,
RESULT_TOO_MANY_USERS = 13,
RESULT_UNSPECIFIED_FAILURE = 14,
RESULT_USER_REJECTED = 15
} MCSResult, *PMCSResult;
// The following defines the DataRequestType type that defines whether a
// SendDataRequest is a normal send or a uniform send.
typedef enum {
NORMAL_SEND_DATA,
UNIFORM_SEND_DATA,
} DataRequestType, *PDataRequestType;
/*
* MCS callback definitions. The Params value is dependent on Message value
* being received, and should be cast to the right type before use.
*/
// MCS node controller callback.
typedef void (__stdcall *MCSNodeControllerCallback) (DomainHandle hDomain,
unsigned Message, void *Params, void *UserDefined);
// MCS user callback.
typedef void (__stdcall *MCSUserCallback) (UserHandle hUser, unsigned Message,
void *Params, void *UserDefined);
// MCS send-data indication callback.
typedef BOOLEAN (__fastcall *MCSSendDataCallback) (BYTE *pData, unsigned DataLength,
void *UserDefined, UserHandle hUser, BOOLEAN bUniform,
ChannelHandle hChannel, MCSPriority Priority, UserID SenderID,
Segmentation Segmentation);
// Callback parameter types. Pointers to these structs are passed to the
// callback in the Params value of the callback.
typedef struct
{
ConnectionHandle hConnection;
BOOLEAN bUpwardConnection;
DomainParameters DomainParams;
BYTE *pUserData;
unsigned UserDataLength;
} ConnectProviderIndication, *PConnectProviderIndication;
typedef struct
{
DomainHandle hDomain;
ConnectionHandle hConnection;
DomainParameters DomainParams;
MCSResult Result;
BYTE *pUserData;
unsigned UserDataLength;
} ConnectProviderConfirm, *PConnectProviderConfirm;
typedef struct
{
DomainHandle hDomain;
ConnectionHandle hConnection;
MCSReason Reason;
} DisconnectProviderIndication, *PDisconnectProviderIndication;
typedef struct
{
UserID UserID;
BOOLEAN bSelf;
MCSReason Reason;
} DetachUserIndication, *PDetachUserIndication;
typedef struct
{
ChannelHandle hChannel;
MCSError ErrResult;
} ChannelJoinConfirm, *PChannelJoinConfirm;
/*
* Callback values.
*/
#define MCS_CONNECT_PROVIDER_INDICATION 0
#define MCS_CONNECT_PROVIDER_CONFIRM 1
#define MCS_DISCONNECT_PROVIDER_INDICATION 2
#define MCS_ATTACH_USER_CONFIRM 3
#define MCS_DETACH_USER_INDICATION 4
#define MCS_CHANNEL_JOIN_CONFIRM 5
#define MCS_CHANNEL_CONVENE_CONFIRM 6
#define MCS_CHANNEL_DISBAND_INDICATION 7
#define MCS_CHANNEL_ADMIT_INDICATION 8
#define MCS_CHANNEL_EXPEL_INDICATION 9
#define MCS_SEND_DATA_INDICATION 10
#define MCS_UNIFORM_SEND_DATA_INDICATION 11
#define MCS_TOKEN_GRAB_CONFIRM 12
#define MCS_TOKEN_INHIBIT_CONFIRM 13
#define MCS_TOKEN_GIVE_INDICATION 14
#define MCS_TOKEN_GIVE_CONFIRM 15
#define MCS_TOKEN_PLEASE_INDICATION 16
#define MCS_TOKEN_RELEASE_CONFIRM 17
#define MCS_TOKEN_TEST_CONFIRM 18
#define MCS_TOKEN_RELEASE_INDICATION 19
/*
* API function prototypes common to user and kernel mode implementations.
*/
#ifdef __cplusplus
extern "C" {
#endif
#ifndef APIENTRY
#define APIENTRY __stdcall
#endif
MCSError APIENTRY MCSAttachUserRequest(
DomainHandle hDomain,
MCSUserCallback UserCallback,
MCSSendDataCallback SDCallback,
void *UserDefined,
UserHandle *phUser,
unsigned *pMaxSendSize,
BOOLEAN *pbCompleted);
UserID APIENTRY MCSGetUserIDFromHandle(UserHandle hUser);
MCSError APIENTRY MCSDetachUserRequest(
UserHandle hUser);
MCSError APIENTRY MCSChannelJoinRequest(
UserHandle hUser,
ChannelID ChannelID,
ChannelHandle *phChannel,
BOOLEAN *pbCompleted);
ChannelID APIENTRY MCSGetChannelIDFromHandle(ChannelHandle hChannel);
MCSError APIENTRY MCSChannelLeaveRequest(
UserHandle hUser,
ChannelHandle hChannel);
#ifdef __cplusplus
}
#endif
#endif // !defined(__MCSCOMMN_H)