405 lines
12 KiB
C
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)
|
|
|