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