include/freerdp/dvc.h

   1 /**
   2  * FreeRDP: A Remote Desktop Protocol client.
   3  * Dynamic Virtual Channel Interface
   4  *
   5  * Copyright 2010-2011 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  * DVC Plugin API: See the original MS DVC Client API:
  22  * http://msdn.microsoft.com/en-us/library/bb540880%28v=VS.85%29.aspx
  23  *
  24  * The FreeRDP DVC Plugin API is a simulation of the MS DVC Client API in C.
  25  * The main difference is that every interface method must take an instance
  26  * pointer as the first parameter.
  27  */
  28
  29 /**
  30  * Implemented by DRDYNVC:
  31  * o IWTSVirtualChannelManager
  32  * o IWTSListener
  33  * o IWTSVirtualChannel
  34  *
  35  * Implemented by DVC plugin:
  36  * o IWTSPlugin
  37  * o IWTSListenerCallback
  38  * o IWTSVirtualChannelCallback
  39  *
  40  * A basic DVC plugin implementation:
  41  * 1. DVCPluginEntry:
  42  *    The plugin entry point, which creates and initializes a new IWTSPlugin
  43  *    instance
  44  * 2. IWTSPlugin.Initialize:
  45  *    Call IWTSVirtualChannelManager.CreateListener with a newly created
  46  *    IWTSListenerCallback instance
  47  * 3. IWTSListenerCallback.OnNewChannelConnection:
  48  *    Create IWTSVirtualChannelCallback instance if the new channel is accepted
  49  */
  50
  51 #ifndef __FREERDP_DVC_H
  52 #define __FREERDP_DVC_H
  53
  54 #include <freerdp/types.h>
  55
  56 typedef struct _IWTSVirtualChannelManager IWTSVirtualChannelManager;
  57 typedef struct _IWTSListener IWTSListener;
  58 typedef struct _IWTSVirtualChannel IWTSVirtualChannel;
  59
  60 typedef struct _IWTSPlugin IWTSPlugin;
  61 typedef struct _IWTSListenerCallback IWTSListenerCallback;
  62 typedef struct _IWTSVirtualChannelCallback IWTSVirtualChannelCallback;
  63
  64 struct _IWTSListener
  65 {
  66         /* Retrieves the listener-specific configuration. */
  67         int (*GetConfiguration) (IWTSListener* pListener,
  68                 void** ppPropertyBag);
  69 };
  70
  71 struct _IWTSVirtualChannel
  72 {
  73         /* Starts a write request on the channel. */
  74         int (*Write) (IWTSVirtualChannel* pChannel,
  75                 uint32 cbSize,
  76                 uint8* pBuffer,
  77                 void* pReserved);
  78         /* Closes the channel. */
  79         int (*Close) (IWTSVirtualChannel* pChannel);
  80 };
  81
  82 struct _IWTSVirtualChannelManager
  83 {
  84         /* Returns an instance of a listener object that listens on a specific
  85            endpoint, or creates a static channel. */
  86         int (*CreateListener) (IWTSVirtualChannelManager* pChannelMgr,
  87                 const char* pszChannelName,
  88                 uint32 ulFlags,
  89                 IWTSListenerCallback* pListenerCallback,
  90                 IWTSListener** ppListener);
  91         /* Push a virtual channel event.
  92            This is a FreeRDP extension to standard MS API. */
  93         int (*PushEvent) (IWTSVirtualChannelManager* pChannelMgr,
  94                 RDP_EVENT* pEvent);
  95 };
  96
  97 struct _IWTSPlugin
  98 {
  99         /* Used for the first call that is made from the client to the plug-in. */
 100         int (*Initialize) (IWTSPlugin* pPlugin,
 101                 IWTSVirtualChannelManager* pChannelMgr);
 102         /* Notifies the plug-in that the Remote Desktop Connection (RDC) client
 103            has successfully connected to the Remote Desktop Session Host (RD
 104            Session Host) server. */
 105         int (*Connected) (IWTSPlugin* pPlugin);
 106         /* Notifies the plug-in that the Remote Desktop Connection (RDC) client
 107            has disconnected from the RD Session Host server. */
 108         int (*Disconnected) (IWTSPlugin* pPlugin,
 109                 uint32 dwDisconnectCode);
 110         /* Notifies the plug-in that the Remote Desktop Connection (RDC) client
 111            has terminated. */
 112         int (*Terminated) (IWTSPlugin* pPlugin);
 113 };
 114
 115 struct _IWTSListenerCallback
 116 {
 117         /* Accepts or denies a connection request for an incoming connection to
 118            the associated listener. */
 119         int (*OnNewChannelConnection) (IWTSListenerCallback* pListenerCallback,
 120                 IWTSVirtualChannel* pChannel,
 121                 uint8* Data,
 122                 int* pbAccept,
 123                 IWTSVirtualChannelCallback** ppCallback);
 124 };
 125
 126 struct _IWTSVirtualChannelCallback
 127 {
 128         /* Notifies the user about data that is being received. */
 129         int (*OnDataReceived) (IWTSVirtualChannelCallback* pChannelCallback,
 130                 uint32 cbSize,
 131                 uint8* pBuffer);
 132         /* Notifies the user that the channel has been closed. */
 133         int (*OnClose) (IWTSVirtualChannelCallback* pChannelCallback);
 134 };
 135
 136 /* The DVC Plugin entry points */
 137 typedef struct _IDRDYNVC_ENTRY_POINTS IDRDYNVC_ENTRY_POINTS;
 138 struct _IDRDYNVC_ENTRY_POINTS
 139 {
 140         int (*RegisterPlugin) (IDRDYNVC_ENTRY_POINTS* pEntryPoints,
 141                 const char* name, IWTSPlugin* pPlugin);
 142         IWTSPlugin* (*GetPlugin) (IDRDYNVC_ENTRY_POINTS* pEntryPoints,
 143                 const char* name);
 144         RDP_PLUGIN_DATA* (*GetPluginData) (IDRDYNVC_ENTRY_POINTS* pEntryPoints);
 145 };
 146
 147 typedef int (*PDVC_PLUGIN_ENTRY) (IDRDYNVC_ENTRY_POINTS*);
 148
 149 #endif