home *** CD-ROM | disk | FTP | other *** search
/ PC Format (South-Africa) 2001 June / PCFJune.iso / Xenon / C++ / FreeCommandLineTools.exe / Include / cchannel.h < prev    next >
Encoding:
C/C++ Source or Header  |  2000-01-31  |  21.3 KB  |  348 lines
  1. /****************************************************************************/
  2. /* Header:    cchannel.h                                                    */
  3. /*                                                                          */
  4. /* Purpose:   Virtual Channel Client API                                    */
  5. /*                                                                          */
  6. /* Copyright(C) Microsoft Corporation 1999                                  */
  7. /*                                                                          */
  8. /****************************************************************************/
  9.  
  10. #ifndef H_CCHANNEL
  11. #pragma option push -b -a8 -pc -A- /*P_O_Push*/
  12. #define H_CCHANNEL
  13.  
  14. /****************************************************************************/
  15. /* Include Virtual Channel Protocol header                                  */
  16. /****************************************************************************/
  17. #include <pchannel.h>
  18.  
  19. #ifdef _WIN32 
  20. #define VCAPITYPE _stdcall
  21. #define VCEXPORT
  22. #else // _WIN32
  23. #define VCAPITYPE CALLBACK
  24. #define VCEXPORT  __export
  25. #endif // _WIN32
  26.  
  27. /****************************************************************************/
  28. /* Name: CHANNEL_INIT_EVENT_FN                                              */
  29. /*                                                                          */
  30. /* Purpose:                                                                 */
  31. /*                                                                          */
  32. /* This function is passed to MSTSC on VirtualChannelInit.  It is called by */
  33. /* MSTSC to tell the application about interesting events.                  */
  34. /*                                                                          */
  35. /* Returns:                                                                 */
  36. /*                                                                          */
  37. /* none                                                                     */
  38. /*                                                                          */
  39. /* Params:                                                                  */
  40. /*                                                                          */
  41. /* - pInitHandle - a handle uniquely identifying this connection            */
  42. /* - event - the event that has occurred - see CHANNEL_EVENT_XXX below      */
  43. /* - pData - data associated with the event - see CHANNEL_EVENT_XXX below   */
  44. /* - dataLength - length of the data.                                       */
  45. /*                                                                          */
  46. /****************************************************************************/
  47. typedef VOID VCAPITYPE CHANNEL_INIT_EVENT_FN(LPVOID pInitHandle,
  48.                                              UINT   event,
  49.                                              LPVOID pData,
  50.                                              UINT   dataLength);
  51.  
  52. typedef CHANNEL_INIT_EVENT_FN FAR * PCHANNEL_INIT_EVENT_FN;
  53.  
  54. /****************************************************************************/
  55. /* Events passed to VirtualChannelInitEvent                                 */
  56. /****************************************************************************/
  57. /* Client initialized (no data)                                             */
  58. #define CHANNEL_EVENT_INITIALIZED       0
  59.  
  60. /* Connection established (data = name of Server)                           */
  61. #define CHANNEL_EVENT_CONNECTED         1
  62.  
  63. /* Connection established with old Server, so no channel support            */
  64. #define CHANNEL_EVENT_V1_CONNECTED      2
  65.  
  66. /* Connection ended (no data)                                               */
  67. #define CHANNEL_EVENT_DISCONNECTED      3
  68.  
  69. /* Client terminated (no data)                                              */
  70. #define CHANNEL_EVENT_TERMINATED        4
  71.  
  72. /****************************************************************************/
  73. /* Name: CHANNEL_OPEN_EVENT_FN                                              */
  74. /*                                                                          */
  75. /* Purpose:                                                                 */
  76. /*                                                                          */
  77. /* This function is passed to MSTSC on VirtualChannelOpen.  It is called by */
  78. /* MSTSC when data is available on the channel.                             */
  79. /*                                                                          */
  80. /* Returns:                                                                 */
  81. /*                                                                          */
  82. /* none                                                                     */
  83. /*                                                                          */
  84. /* Params:                                                                  */
  85. /*                                                                          */
  86. /* - openHandle - a handle uniquely identifying this channel                */
  87. /* - event - event that has occurred - see CHANNEL_EVENT_XXX below          */
  88. /* - pData - data received                                                  */
  89. /* - dataLength - length of the data                                        */
  90. /* - totalLength - total length of data written by the Server               */
  91. /* - dataFlags - flags, zero, one or more of:                               */
  92. /*   - 0x01 - beginning of data from a single write operation at the Server */
  93. /*   - 0x02 - end of data from a single write operation at the Server.      */
  94. /*                                                                          */
  95. /****************************************************************************/
  96. typedef VOID VCAPITYPE CHANNEL_OPEN_EVENT_FN(DWORD  openHandle,
  97.                                              UINT   event,
  98.                                              LPVOID pData,
  99.                                              UINT32 dataLength,
  100.                                              UINT32 totalLength,
  101.                                              UINT32 dataFlags);
  102.  
  103. typedef CHANNEL_OPEN_EVENT_FN FAR * PCHANNEL_OPEN_EVENT_FN;
  104.  
  105.  
  106. /****************************************************************************/
  107. /* Events passed to VirtualChannelOpenEvent                                 */
  108. /****************************************************************************/
  109. /* Data received from Server (data = incoming data)                         */
  110. #define CHANNEL_EVENT_DATA_RECEIVED     10
  111.  
  112. /* VirtualChannelWrite completed (pData - pUserData passed on
  113.    VirtualChannelWrite)                                                     */
  114. #define CHANNEL_EVENT_WRITE_COMPLETE    11
  115.  
  116. /* VirtualChannelWrite cancelled (pData - pUserData passed on
  117.    VirtualChannelWrite)                                                     */
  118. #define CHANNEL_EVENT_WRITE_CANCELLED   12
  119.  
  120.  
  121. /****************************************************************************/
  122. /* Return codes from VirtualChannelXxx functions                            */
  123. /****************************************************************************/
  124. #define CHANNEL_RC_OK                             0
  125. #define CHANNEL_RC_ALREADY_INITIALIZED            1
  126. #define CHANNEL_RC_NOT_INITIALIZED                2
  127. #define CHANNEL_RC_ALREADY_CONNECTED              3
  128. #define CHANNEL_RC_NOT_CONNECTED                  4
  129. #define CHANNEL_RC_TOO_MANY_CHANNELS              5
  130. #define CHANNEL_RC_BAD_CHANNEL                    6
  131. #define CHANNEL_RC_BAD_CHANNEL_HANDLE             7
  132. #define CHANNEL_RC_NO_BUFFER                      8
  133. #define CHANNEL_RC_BAD_INIT_HANDLE                9
  134. #define CHANNEL_RC_NOT_OPEN                      10
  135. #define CHANNEL_RC_BAD_PROC                      11
  136. #define CHANNEL_RC_NO_MEMORY                     12
  137. #define CHANNEL_RC_UNKNOWN_CHANNEL_NAME          13
  138. #define CHANNEL_RC_ALREADY_OPEN                  14
  139. #define CHANNEL_RC_NOT_IN_VIRTUALCHANNELENTRY    15
  140. #define CHANNEL_RC_NULL_DATA                     16
  141. #define CHANNEL_RC_ZERO_LENGTH                   17
  142.  
  143. /****************************************************************************/
  144. /* Levels of Virtual Channel Support                                        */
  145. /****************************************************************************/
  146. #define VIRTUAL_CHANNEL_VERSION_WIN2000         1
  147.  
  148. #ifdef __cplusplus
  149. extern "C" {
  150. #endif /* __cplusplus */
  151. /****************************************************************************/
  152. /* Name: VirtualChannelInit                                                 */
  153. /*                                                                          */
  154. /* Purpose:                                                                 */
  155. /*                                                                          */
  156. /* This function is called by the application to register the virtual       */
  157. /* channels it wants to have access to.  Note that this does not open the   */
  158. /* channels, merely reserves the names for use by this application.  This   */
  159. /* function must be called before the Client connects to the Server, hence  */
  160. /* it is recommended that it is called from the DLL's initialization        */
  161. /* procedure.                                                               */
  162. /*                                                                          */
  163. /*                                                                          */
  164. /* On_return, the channels requested have been registered.  However, other  */
  165. /* MSTSC initialization may not yet have completed.  The application        */
  166. /* receives a VirtualChannelInitEvent callback with the "Client             */
  167. /* initialized" event when all MSTSC initialization is complete.            */
  168. /*                                                                          */
  169. /* Returns:                                                                 */
  170. /*                                                                          */
  171. /* CHANNEL_RC_OK                                                            */
  172. /* CHANNEL_RC_ALREADY_INITIALIZED                                           */
  173. /* CHANNEL_RC_ALREADY_CONNECTED                                             */
  174. /* CHANNEL_RC_TOO_MANY_CHANNELS                                             */
  175. /* CHANNEL_RC_NOT_IN_VIRTUALCHANNELENTRY                                    */
  176. /*                                                                          */
  177. /* Parameters                                                               */
  178. /*                                                                          */
  179. /* - ppInitHandle (returned) - handle to pass to subsequent                 */
  180. /*                             VirtualChannelXxx calls                      */
  181. /* - pChannel - list of names registered by this application                */
  182. /* - channelCount - number of channels registered.                          */
  183. /* - versionRequested - level of virtual channel support requested (one of  */
  184. /*                      the VIRTUAL_CHANNEL_LEVEL_XXX parameters)           */
  185. /* - pChannelInitEventProc - address of VirtualChannelInitEvent procedure   */
  186. /*                                                                          */
  187. /****************************************************************************/
  188. typedef UINT VCAPITYPE VIRTUALCHANNELINIT(
  189.                 LPVOID FAR *           ppInitHandle,
  190.                 PCHANNEL_DEF           pChannel,
  191.                 INT                    channelCount,
  192.                 ULONG                  versionRequested,
  193.                 PCHANNEL_INIT_EVENT_FN pChannelInitEventProc);
  194.  
  195. typedef VIRTUALCHANNELINIT FAR * PVIRTUALCHANNELINIT;
  196.  
  197.  
  198. /****************************************************************************/
  199. /* Name: VirtualChannelOpen                                                 */
  200. /*                                                                          */
  201. /* Purpose:                                                                 */
  202. /*                                                                          */
  203. /* This function is called by the application to open a channel.  It cannot */
  204. /* be called until a connection is established with a Server.               */
  205. /*                                                                          */
  206. /* Returns:                                                                 */
  207. /*                                                                          */
  208. /* CHANNEL_RC_OK                                                            */
  209. /* CHANNEL_RC_NOT_INITIALIZED                                               */
  210. /* CHANNEL_RC_NOT_CONNECTED                                                 */
  211. /* CHANNEL_RC_BAD_CHANNEL_NAME                                              */
  212. /* CHANNEL_RC_BAD_INIT_HANDLE                                               */
  213. /*                                                                          */
  214. /* Params:                                                                  */
  215. /*                                                                          */
  216. /* - pInitHandle - handle from VirtualChannelInit                           */
  217. /*                                                                          */
  218. /* - pOpenHandle (returned) - handle to pass to subsequent                  */
  219. /*                            VirtualChannelXxx calls                       */
  220. /* - pChannelName - name of channel to open                                 */
  221. /* - pChannelOpenEventProc - address of VirtualChannelOpenEvent procedure   */
  222. /*                                                                          */
  223. /****************************************************************************/
  224. typedef UINT VCAPITYPE VIRTUALCHANNELOPEN(
  225.                                 LPVOID                 pInitHandle,
  226.                                 LPDWORD                pOpenHandle,
  227.                                 PCHAR                  pChannelName,
  228.                                 PCHANNEL_OPEN_EVENT_FN pChannelOpenEventProc);
  229.  
  230. typedef VIRTUALCHANNELOPEN FAR * PVIRTUALCHANNELOPEN;
  231.  
  232.  
  233. /****************************************************************************/
  234. /* Name: VirtualChannelClose                                                */
  235. /*                                                                          */
  236. /* Purpose:                                                                 */
  237. /*                                                                          */
  238. /* This function is called to close a previously opened channel.            */
  239. /*                                                                          */
  240. /* Returns:                                                                 */
  241. /*                                                                          */
  242. /* CHANNEL_RC_OK                                                            */
  243. /* CHANNEL_RC_BAD_CHANNEL_HANDLE                                            */
  244. /*                                                                          */
  245. /* Params:                                                                  */
  246. /*                                                                          */
  247. /* - openHandle - handle returned on VirtualChannelOpen                     */
  248. /*                                                                          */
  249. /****************************************************************************/
  250. typedef UINT VCAPITYPE VIRTUALCHANNELCLOSE(DWORD openHandle);
  251.  
  252. typedef VIRTUALCHANNELCLOSE FAR * PVIRTUALCHANNELCLOSE;
  253.  
  254.  
  255. /****************************************************************************/
  256. /* Name: VirtualChannelWrite                                                */
  257. /*                                                                          */
  258. /* Purpose:                                                                 */
  259. /*                                                                          */
  260. /* This function is used to send data to the partner app on the Server.     */
  261. /*                                                                          */
  262. /* VirtualChannelWrite copies the data to one or more network buffers as    */
  263. /* necessary.  VirtualChannelWrite ensures that data is sent to the Server  */
  264. /* on the right context.  It sends all data on MS TC's Sender thread.       */
  265. /*                                                                          */
  266. /* VirtualChannelWrite is asynchronous - the VirtualChannelOpenEvent        */
  267. /* procedure is called when the write completes.  Until that callback is    */
  268. /* made, the caller must not free or reuse the buffer passed on             */
  269. /* VirtualChannelWrite.  The caller passes a piece of data (pUserData) to   */
  270. /* VirtualChannelWrite, which is returned on the VirtualChannelOpenEvent    */
  271. /* callback.  The caller can use this data to identify the write which has  */
  272. /* completed.                                                               */
  273. /*                                                                          */
  274. /*                                                                          */
  275. /* Returns:                                                                 */
  276. /*                                                                          */
  277. /* CHANNEL_RC_OK                                                            */
  278. /* CHANNEL_RC_NOT_INITIALIZED                                               */
  279. /* CHANNEL_RC_NOT_CONNECTED                                                 */
  280. /* CHANNEL_RC_BAD_CHANNEL_HANDLE                                            */
  281. /*                                                                          */
  282. /* Params:                                                                  */
  283. /* - openHandle - handle from VirtualChannelOpen                            */
  284. /* - pData - data to write                                                  */
  285. /* - datalength - length of data to write                                   */
  286. /* - pUserData - user supplied data, returned on VirtualChannelOpenEvent    */
  287. /*               when the write completes                                   */
  288. /*                                                                          */
  289. /****************************************************************************/
  290. typedef UINT VCAPITYPE VIRTUALCHANNELWRITE(DWORD  openHandle,
  291.                                            LPVOID pData,
  292.                                            ULONG  dataLength,
  293.                                            LPVOID pUserData);
  294.  
  295. typedef VIRTUALCHANNELWRITE FAR * PVIRTUALCHANNELWRITE;
  296.  
  297.  
  298. /****************************************************************************/
  299. /* Structure: CHANNEL_ENTRY_POINTS                                          */
  300. /*                                                                          */
  301. /* Description: Virtual Channel entry points passed to VirtualChannelEntry  */
  302. /****************************************************************************/
  303. typedef struct tagCHANNEL_ENTRY_POINTS
  304. {
  305.     DWORD cbSize;
  306.     DWORD protocolVersion;
  307.     PVIRTUALCHANNELINIT  pVirtualChannelInit;
  308.     PVIRTUALCHANNELOPEN  pVirtualChannelOpen;
  309.     PVIRTUALCHANNELCLOSE pVirtualChannelClose;
  310.     PVIRTUALCHANNELWRITE pVirtualChannelWrite;
  311. } CHANNEL_ENTRY_POINTS, FAR * PCHANNEL_ENTRY_POINTS;
  312.  
  313.  
  314. /****************************************************************************/
  315. /* Name: VirtualChannelEntry                                                */
  316. /*                                                                          */
  317. /* Purpose:                                                                 */
  318. /*                                                                          */
  319. /* This function is provided by addin DLLS.  It is called by MSTSC at       */
  320. /* initialization to tell the addin DLL the addresses of the                */
  321. /* VirtualChannelXxx functions.                                             */
  322. /*                                                                          */
  323. /* Returns:                                                                 */
  324. /*                                                                          */
  325. /* TRUE - everything OK                                                     */
  326. /* FALSE - error, unload the DLL                                            */
  327. /*                                                                          */
  328. /* Parameters:                                                              */
  329. /*                                                                          */
  330. /* - pVirtualChannelInit - pointers to VirtualChannelXxx functions          */
  331. /* - pVirtualChannelOpen                                                    */
  332. /* - pVirtualChannelClose                                                   */
  333. /* - pVirtualChannelWrite                                                   */
  334. /*                                                                          */
  335. /****************************************************************************/
  336. typedef BOOL VCAPITYPE VIRTUALCHANNELENTRY(
  337.                                           PCHANNEL_ENTRY_POINTS pEntryPoints);
  338.  
  339. typedef VIRTUALCHANNELENTRY FAR * PVIRTUALCHANNELENTRY;
  340.  
  341.  
  342. #ifdef __cplusplus
  343. }
  344. #endif  /* __cplusplus */
  345.  
  346. #pragma option pop /*P_O_Pop*/
  347. #endif /* H_CCHANNEL */
  348.