442 lines
26 KiB
C
442 lines
26 KiB
C
/****************************************************************************/
|
|
/* 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 */
|