include/freerdp/channels/wtsvc.h

   1 /**
   2  * FreeRDP: A Remote Desktop Protocol client.
   3  * Server Virtual Channel Interface
   4  *
   5  * Copyright 2011-2012 Vic Lee
   6  *
   7  * Licensed under the Apache License, Version 2.0 (the "License");
   8  * you may not use this file except in compliance with the License.
   9  * You may obtain a copy of the License at
  10  *
  11  *     http://www.apache.org/licenses/LICENSE-2.0
  12  *
  13  * Unless required by applicable law or agreed to in writing, software
  14  * distributed under the License is distributed on an "AS IS" BASIS,
  15  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  16  * See the License for the specific language governing permissions and
  17  * limitations under the License.
  18  */
  19
  20 /**
  21  * The server-side virtual channel API follows the Microsoft Remote Desktop
  22  * Services API functions WTSVirtualChannel* defined in:
  23  * http://msdn.microsoft.com/en-us/library/windows/desktop/aa383464.aspx
  24  *
  25  * Difference between the MS API are documented in this header. All functions
  26  * are implemented in and integrated with libfreerdp-channels.
  27  *
  28  * Unlike MS API, all functions except WTSVirtualChannelOpenEx in this
  29  * implementation are thread-safe.
  30  */
  31
  32 #ifndef __FREERDP_WTSVC_H
  33 #define __FREERDP_WTSVC_H
  34
  35 #include <freerdp/types.h>
  36 #include <freerdp/peer.h>
  37
  38 typedef struct WTSVirtualChannelManager WTSVirtualChannelManager;
  39
  40 #define WTS_CHANNEL_OPTION_DYNAMIC 0x00000001
  41
  42 typedef enum _WTS_VIRTUAL_CLASS
  43 {
  44         WTSVirtualClientData,
  45         WTSVirtualFileHandle
  46 } WTS_VIRTUAL_CLASS;
  47
  48 /**
  49  * WTSVirtualChannelManager functions are FreeRDP extensions to the API.
  50  */
  51 FREERDP_API WTSVirtualChannelManager* WTSCreateVirtualChannelManager(freerdp_peer* client);
  52 FREERDP_API void WTSDestroyVirtualChannelManager(WTSVirtualChannelManager* vcm);
  53 FREERDP_API void WTSVirtualChannelManagerGetFileDescriptor(WTSVirtualChannelManager* vcm,
  54         void** fds, int* fds_count);
  55 FREERDP_API boolean WTSVirtualChannelManagerCheckFileDescriptor(WTSVirtualChannelManager* vcm);
  56
  57 /**
  58  * Opens a static or dynamic virtual channel and return the handle. If the
  59  * operation fails, a NULL handle is returned.
  60  *
  61  * The original MS API has 'DWORD SessionId' as the first argument, while we
  62  * use our WTSVirtualChannelManager object instead.
  63  *
  64  * This functions should be called only from the main thread.
  65  */
  66 FREERDP_API void* WTSVirtualChannelOpenEx(
  67         /* __in */ WTSVirtualChannelManager* vcm,
  68         /* __in */ const char* pVirtualName,
  69         /* __in */ uint32 flags);
  70
  71 /**
  72  * Returns information about a specified virtual channel.
  73  *
  74  * Servers use this function to gain access to a virtual channel file handle
  75  * that can be used for asynchronous I/O.
  76  */
  77 FREERDP_API boolean WTSVirtualChannelQuery(
  78         /* __in */  void* hChannelHandle,
  79         /* __in */  WTS_VIRTUAL_CLASS WtsVirtualClass,
  80         /* __out */ void** ppBuffer,
  81         /* __out */ uint32* pBytesReturned);
  82
  83 /**
  84  * Frees memory allocated by WTSVirtualChannelQuery
  85  */
  86 FREERDP_API void WTSFreeMemory(
  87         /* __in */ void* pMemory);
  88
  89 /**
  90  * Reads data from the server end of a virtual channel.
  91  *
  92  * FreeRDP behavior:
  93  *
  94  * This function will always return a complete channel data packet, i.e. chunks
  95  * are already assembled. If BufferSize argument is smaller than the packet
  96  * size, it will set the desired size in pBytesRead and return false. The
  97  * caller should allocate a large enough buffer and call this function again.
  98  * Returning false with pBytesRead set to zero indicates an error has occurred.
  99  * If no pending packet to be read, it will set pBytesRead to zero and return
 100  * true.
 101  *
 102  * TimeOut is not supported, and this function will always return immediately.
 103  * The caller should use the file handle returned by WTSVirtualChannelQuery to
 104  * determine whether a packet has arrived.
 105  */
 106 FREERDP_API boolean WTSVirtualChannelRead(
 107         /* __in */  void* hChannelHandle,
 108         /* __in */  uint32 TimeOut,
 109         /* __out */ uint8* Buffer,
 110         /* __in */  uint32 BufferSize,
 111         /* __out */ uint32* pBytesRead);
 112
 113 /**
 114  * Writes data to the server end of a virtual channel.
 115  */
 116 FREERDP_API boolean WTSVirtualChannelWrite(
 117         /* __in */  void* hChannelHandle,
 118         /* __in */  uint8* Buffer,
 119         /* __in */  uint32 Length,
 120         /* __out */ uint32* pBytesWritten);
 121
 122 /**
 123  * Closes an open virtual channel handle.
 124  */
 125 FREERDP_API boolean WTSVirtualChannelClose(
 126         /* __in */ void* hChannelHandle);
 127
 128 #endif /* __FREERDP_WTSVC_H */