windows-nt/Source/XPSP1/NT/public/internal/termsrv/inc/cchannel.h

442 lines
26 KiB
C
Raw Permalink Normal View History

2020-09-26 03:20:57 -05:00
/****************************************************************************/
/* Header: cchannel.h */
/* */
/* Purpose: Virtual Channel Client API */
/* */
/* Copyright(C) Microsoft Corporation 1999 */
/* */
/****************************************************************************/
#ifndef H_CCHANNEL
#define H_CCHANNEL
/****************************************************************************/
/* Include Virtual Channel Protocol header */
/****************************************************************************/
#include <pchannel.h>
#ifdef _WIN32
#define VCAPITYPE _stdcall
#define VCEXPORT
#else // _WIN32
#define VCAPITYPE CALLBACK
#define VCEXPORT __export
#endif // _WIN32
/****************************************************************************/
/* Name: CHANNEL_INIT_EVENT_FN */
/* */
/* Purpose: */
/* */
/* This function is passed to MSTSC on VirtualChannelInit. It is called by */
/* MSTSC to tell the application about interesting events. */
/* */
/* Returns: */
/* */
/* none */
/* */
/* Params: */
/* */
/* - pInitHandle - a handle uniquely identifying this connection */
/* - event - the event that has occurred - see CHANNEL_EVENT_XXX below */
/* - pData - data associated with the event - see CHANNEL_EVENT_XXX below */
/* - dataLength - length of the data. */
/* */
/****************************************************************************/
typedef VOID VCAPITYPE CHANNEL_INIT_EVENT_FN(LPVOID pInitHandle,
UINT event,
LPVOID pData,
UINT dataLength);
typedef CHANNEL_INIT_EVENT_FN FAR * PCHANNEL_INIT_EVENT_FN;
typedef VOID VCAPITYPE CHANNEL_INIT_EVENT_EX_FN(LPVOID lpUserParam,
LPVOID pInitHandle,
UINT event,
LPVOID pData,
UINT dataLength);
typedef CHANNEL_INIT_EVENT_EX_FN FAR * PCHANNEL_INIT_EVENT_EX_FN;
/****************************************************************************/
/* Events passed to VirtualChannelInitEvent */
/****************************************************************************/
/* Client initialized (no data) */
#define CHANNEL_EVENT_INITIALIZED 0
/* Connection established (data = name of Server) */
#define CHANNEL_EVENT_CONNECTED 1
/* Connection established with old Server, so no channel support */
#define CHANNEL_EVENT_V1_CONNECTED 2
/* Connection ended (no data) */
#define CHANNEL_EVENT_DISCONNECTED 3
/* Client terminated (no data) */
#define CHANNEL_EVENT_TERMINATED 4
/* Remote control is starting on this client */
#define CHANNEL_EVENT_REMOTE_CONTROL_START 5
/* Remote control is ending on this client */
#define CHANNEL_EVENT_REMOTE_CONTROL_STOP 6
/****************************************************************************/
/* Name: CHANNEL_OPEN_EVENT_FN */
/* */
/* Purpose: */
/* */
/* This function is passed to MSTSC on VirtualChannelOpen. It is called by */
/* MSTSC when data is available on the channel. */
/* */
/* Returns: */
/* */
/* none */
/* */
/* Params: */
/* */
/* - openHandle - a handle uniquely identifying this channel */
/* - event - event that has occurred - see CHANNEL_EVENT_XXX below */
/* - pData - data received */
/* - dataLength - length of the data */
/* - totalLength - total length of data written by the Server */
/* - dataFlags - flags, zero, one or more of: */
/* - 0x01 - beginning of data from a single write operation at the Server */
/* - 0x02 - end of data from a single write operation at the Server. */
/* */
/****************************************************************************/
typedef VOID VCAPITYPE CHANNEL_OPEN_EVENT_FN(DWORD openHandle,
UINT event,
LPVOID pData,
UINT32 dataLength,
UINT32 totalLength,
UINT32 dataFlags);
typedef CHANNEL_OPEN_EVENT_FN FAR * PCHANNEL_OPEN_EVENT_FN;
typedef VOID VCAPITYPE CHANNEL_OPEN_EVENT_EX_FN(LPVOID lpUserParam,
DWORD openHandle,
UINT event,
LPVOID pData,
UINT32 dataLength,
UINT32 totalLength,
UINT32 dataFlags);
typedef CHANNEL_OPEN_EVENT_EX_FN FAR * PCHANNEL_OPEN_EVENT_EX_FN;
/****************************************************************************/
/* Events passed to VirtualChannelOpenEvent */
/****************************************************************************/
/* Data received from Server (data = incoming data) */
#define CHANNEL_EVENT_DATA_RECEIVED 10
/* VirtualChannelWrite completed (pData - pUserData passed on
VirtualChannelWrite) */
#define CHANNEL_EVENT_WRITE_COMPLETE 11
/* VirtualChannelWrite cancelled (pData - pUserData passed on
VirtualChannelWrite) */
#define CHANNEL_EVENT_WRITE_CANCELLED 12
/****************************************************************************/
/* Return codes from VirtualChannelXxx functions */
/****************************************************************************/
#define CHANNEL_RC_OK 0
#define CHANNEL_RC_ALREADY_INITIALIZED 1
#define CHANNEL_RC_NOT_INITIALIZED 2
#define CHANNEL_RC_ALREADY_CONNECTED 3
#define CHANNEL_RC_NOT_CONNECTED 4
#define CHANNEL_RC_TOO_MANY_CHANNELS 5
#define CHANNEL_RC_BAD_CHANNEL 6
#define CHANNEL_RC_BAD_CHANNEL_HANDLE 7
#define CHANNEL_RC_NO_BUFFER 8
#define CHANNEL_RC_BAD_INIT_HANDLE 9
#define CHANNEL_RC_NOT_OPEN 10
#define CHANNEL_RC_BAD_PROC 11
#define CHANNEL_RC_NO_MEMORY 12
#define CHANNEL_RC_UNKNOWN_CHANNEL_NAME 13
#define CHANNEL_RC_ALREADY_OPEN 14
#define CHANNEL_RC_NOT_IN_VIRTUALCHANNELENTRY 15
#define CHANNEL_RC_NULL_DATA 16
#define CHANNEL_RC_ZERO_LENGTH 17
#define CHANNEL_RC_INVALID_INSTANCE 18
#define CHANNEL_RC_UNSUPPORTED_VERSION 19
/****************************************************************************/
/* Levels of Virtual Channel Support */
/****************************************************************************/
#define VIRTUAL_CHANNEL_VERSION_WIN2000 1
#ifdef __cplusplus
extern "C" {
#endif /* __cplusplus */
/****************************************************************************/
/* Name: VirtualChannelInit */
/* */
/* Purpose: */
/* */
/* This function is called by the application to register the virtual */
/* channels it wants to have access to. Note that this does not open the */
/* channels, merely reserves the names for use by this application. This */
/* function must be called before the Client connects to the Server, hence */
/* it is recommended that it is called from the DLL's initialization */
/* procedure. */
/* */
/* */
/* On_return, the channels requested have been registered. However, other */
/* MSTSC initialization may not yet have completed. The application */
/* receives a VirtualChannelInitEvent callback with the "Client */
/* initialized" event when all MSTSC initialization is complete. */
/* */
/* Returns: */
/* */
/* CHANNEL_RC_OK */
/* CHANNEL_RC_ALREADY_INITIALIZED */
/* CHANNEL_RC_ALREADY_CONNECTED */
/* CHANNEL_RC_TOO_MANY_CHANNELS */
/* CHANNEL_RC_NOT_IN_VIRTUALCHANNELENTRY */
/* */
/* Parameters */
/* */
/* - ppInitHandle (returned) - handle to pass to subsequent */
/* VirtualChannelXxx calls */
/* - pChannel - list of names registered by this application */
/* - channelCount - number of channels registered. */
/* - versionRequested - level of virtual channel support requested (one of */
/* the VIRTUAL_CHANNEL_LEVEL_XXX parameters) */
/* - pChannelInitEventProc - address of VirtualChannelInitEvent procedure */
/* */
/****************************************************************************/
typedef UINT VCAPITYPE VIRTUALCHANNELINIT(
LPVOID FAR * ppInitHandle,
PCHANNEL_DEF pChannel,
INT channelCount,
ULONG versionRequested,
PCHANNEL_INIT_EVENT_FN pChannelInitEventProc);
typedef VIRTUALCHANNELINIT FAR * PVIRTUALCHANNELINIT;
/****************************************************************************/
/* Parameters for EX version */
/* */
/* pUserParam - user definded value that will be passed back */
/* to addin in callbacks */
/* */
/* - pInitHandle - handle passed in in entry function */
/* - pChannel - list of names registered by this application */
/* - channelCount - number of channels registered. */
/* - versionRequested - level of virtual channel support requested (one of */
/* the VIRTUAL_CHANNEL_LEVEL_XXX parameters) */
/* - pChannelInitEventProc - address of VirtualChannelInitEvent procedure */
/* */
/****************************************************************************/
typedef UINT VCAPITYPE VIRTUALCHANNELINITEX(
LPVOID lpUserParam,
LPVOID pInitHandle,
PCHANNEL_DEF pChannel,
INT channelCount,
ULONG versionRequested,
PCHANNEL_INIT_EVENT_EX_FN pChannelInitEventProcEx);
typedef VIRTUALCHANNELINITEX FAR * PVIRTUALCHANNELINITEX;
/****************************************************************************/
/* Name: VirtualChannelOpen */
/* */
/* Purpose: */
/* */
/* This function is called by the application to open a channel. It cannot */
/* be called until a connection is established with a Server. */
/* */
/* Returns: */
/* */
/* CHANNEL_RC_OK */
/* CHANNEL_RC_NOT_INITIALIZED */
/* CHANNEL_RC_NOT_CONNECTED */
/* CHANNEL_RC_BAD_CHANNEL_NAME */
/* CHANNEL_RC_BAD_INIT_HANDLE */
/* */
/* Params: */
/* */
/* - pInitHandle - handle from VirtualChannelInit */
/* */
/* - pOpenHandle (returned) - handle to pass to subsequent */
/* VirtualChannelXxx calls */
/* - pChannelName - name of channel to open */
/* - pChannelOpenEventProc - address of VirtualChannelOpenEvent procedure */
/* */
/****************************************************************************/
typedef UINT VCAPITYPE VIRTUALCHANNELOPEN(
LPVOID pInitHandle,
LPDWORD pOpenHandle,
PCHAR pChannelName,
PCHANNEL_OPEN_EVENT_FN pChannelOpenEventProc);
typedef VIRTUALCHANNELOPEN FAR * PVIRTUALCHANNELOPEN;
typedef UINT VCAPITYPE VIRTUALCHANNELOPENEX(
LPVOID pInitHandle,
LPDWORD pOpenHandle,
PCHAR pChannelName,
PCHANNEL_OPEN_EVENT_EX_FN pChannelOpenEventProcEx);
typedef VIRTUALCHANNELOPENEX FAR * PVIRTUALCHANNELOPENEX;
/****************************************************************************/
/* Name: VirtualChannelClose */
/* */
/* Purpose: */
/* */
/* This function is called to close a previously opened channel. */
/* */
/* Returns: */
/* */
/* CHANNEL_RC_OK */
/* CHANNEL_RC_BAD_CHANNEL_HANDLE */
/* */
/* Params: */
/* */
/* - (EX version) pInitHandle - handle identifying the client instance */
/* - openHandle - handle returned on VirtualChannelOpen */
/* */
/****************************************************************************/
typedef UINT VCAPITYPE VIRTUALCHANNELCLOSE(DWORD openHandle);
typedef VIRTUALCHANNELCLOSE FAR * PVIRTUALCHANNELCLOSE;
typedef UINT VCAPITYPE VIRTUALCHANNELCLOSEEX(LPVOID pInitHandle,
DWORD openHandle);
typedef VIRTUALCHANNELCLOSEEX FAR * PVIRTUALCHANNELCLOSEEX;
/****************************************************************************/
/* Name: VirtualChannelWrite */
/* */
/* Purpose: */
/* */
/* This function is used to send data to the partner app on the Server. */
/* */
/* VirtualChannelWrite copies the data to one or more network buffers as */
/* necessary. VirtualChannelWrite ensures that data is sent to the Server */
/* on the right context. It sends all data on MS TC's Sender thread. */
/* */
/* VirtualChannelWrite is asynchronous - the VirtualChannelOpenEvent */
/* procedure is called when the write completes. Until that callback is */
/* made, the caller must not free or reuse the buffer passed on */
/* VirtualChannelWrite. The caller passes a piece of data (pUserData) to */
/* VirtualChannelWrite, which is returned on the VirtualChannelOpenEvent */
/* callback. The caller can use this data to identify the write which has */
/* completed. */
/* */
/* */
/* Returns: */
/* */
/* CHANNEL_RC_OK */
/* CHANNEL_RC_NOT_INITIALIZED */
/* CHANNEL_RC_NOT_CONNECTED */
/* CHANNEL_RC_BAD_CHANNEL_HANDLE */
/* */
/* Params: */
/* - (EX version) pInitHandle - handle identifying the client instance */
/* - openHandle - handle from VirtualChannelOpen */
/* - pData - data to write */
/* - datalength - length of data to write */
/* - pUserData - user supplied data, returned on VirtualChannelOpenEvent */
/* when the write completes */
/* */
/****************************************************************************/
typedef UINT VCAPITYPE VIRTUALCHANNELWRITE(DWORD openHandle,
LPVOID pData,
ULONG dataLength,
LPVOID pUserData);
typedef VIRTUALCHANNELWRITE FAR * PVIRTUALCHANNELWRITE;
typedef UINT VCAPITYPE VIRTUALCHANNELWRITEEX(LPVOID pInitHandle,
DWORD openHandle,
LPVOID pData,
ULONG dataLength,
LPVOID pUserData);
typedef VIRTUALCHANNELWRITEEX FAR * PVIRTUALCHANNELWRITEEX;
/****************************************************************************/
/* Structure: CHANNEL_ENTRY_POINTS */
/* */
/* Description: Virtual Channel entry points passed to VirtualChannelEntry */
/****************************************************************************/
typedef struct tagCHANNEL_ENTRY_POINTS
{
DWORD cbSize;
DWORD protocolVersion;
PVIRTUALCHANNELINIT pVirtualChannelInit;
PVIRTUALCHANNELOPEN pVirtualChannelOpen;
PVIRTUALCHANNELCLOSE pVirtualChannelClose;
PVIRTUALCHANNELWRITE pVirtualChannelWrite;
} CHANNEL_ENTRY_POINTS, FAR * PCHANNEL_ENTRY_POINTS;
typedef struct tagCHANNEL_ENTRY_POINTS_EX
{
DWORD cbSize;
DWORD protocolVersion;
PVIRTUALCHANNELINITEX pVirtualChannelInitEx;
PVIRTUALCHANNELOPENEX pVirtualChannelOpenEx;
PVIRTUALCHANNELCLOSEEX pVirtualChannelCloseEx;
PVIRTUALCHANNELWRITEEX pVirtualChannelWriteEx;
} CHANNEL_ENTRY_POINTS_EX, FAR * PCHANNEL_ENTRY_POINTS_EX;
/****************************************************************************/
/* Name: VirtualChannelEntry */
/* */
/* Purpose: */
/* */
/* This function is provided by addin DLLS. It is called by MSTSC at */
/* initialization to tell the addin DLL the addresses of the */
/* VirtualChannelXxx functions. */
/* */
/* Returns: */
/* */
/* TRUE - everything OK */
/* FALSE - error, unload the DLL */
/* */
/* Parameters: */
/* */
/* - pVirtualChannelInit - pointers to VirtualChannelXxx functions */
/* - pVirtualChannelOpen */
/* - pVirtualChannelClose */
/* - pVirtualChannelWrite */
/* */
/* - (EX version) pInitHandle - value that identifies client instance */
/* this must be passed back when calling into */
/* the client. */
/****************************************************************************/
typedef BOOL VCAPITYPE VIRTUALCHANNELENTRY(
PCHANNEL_ENTRY_POINTS pEntryPoints);
typedef VIRTUALCHANNELENTRY FAR * PVIRTUALCHANNELENTRY;
typedef BOOL VCAPITYPE VIRTUALCHANNELENTRYEX(
PCHANNEL_ENTRY_POINTS_EX pEntryPointsEx,
PVOID pInitHandle);
typedef VIRTUALCHANNELENTRYEX FAR * PVIRTUALCHANNELENTRYEX;
#ifdef __cplusplus
}
#endif /* __cplusplus */
#endif /* H_CCHANNEL */