git.sesse.net Git - vlc/blob - projects/activex/README.TXT

   1 == ACTIVEX Control for VLC ==
   2
   3 The VLC ActiveX Control has been primary designed to work with Internet Explorer.
   4 however it may also work with Visual Basic and/or .NET
   5 Please note, that this code does not rely upon Microsoft MFC/ATL code,
   6 hence good compatibility is not guaranteed.
   7
   8 I. Compiling
   9
  10 The ActiveX Control should compile without any glitches as long as you have the latest
  11 version of mingw gcc and headers. However, In order to script the ActiveX Control
  12 on Internet Explorer, a type library is required.
  13
  14 This type library is usually generated from an IDL file using Microsoft MIDL compiler.
  15 Therefore, for convenience I have checked in the output of the MIDL compiler in the
  16 repository so that you will only need the MIDL compiler if you change axvlc.idl.
  17 the generated files are as follow:
  18
  19 axvlc_idl.c
  20 axvlc_idl.h
  21 axvlc.tlb
  22
  23 To use the MIDL compiler on cygwin, you will need to set some environment variables
  24 before configuring vlc. If you have a copy of 'Microsoft Visual C++ 6.0' installed,
  25 the following settings are correct:
  26
  27 export PATH=$PATH:"/cygdrive/c/Program Files/Microsoft Visual Studio/COMMON/MSDev98/Bin":"/cygdrive/c/Program Files/Microsoft Visual Studio/VC98/Bin"
  28 export INCLUDE='C:\Program Files\Microsoft Visual Studio\VC98\Include'
  29 export MIDL="midl"
  30
  31 If you are cross-compiling on Linux, you can use 'widl' which is part of
  32 the WINE project (http://www.winehq.com). At leat wine-dev-0.9.57 works,
  33 the comand line to compile IDL should looks like the following :
  34
  35 widl -I/usr/include/wine/windows/ \
  36      -h -H axvlc_idl.h -t -T axvlc.tlb -u -U axvlc_idl.c \
  37      axvlc.idl
  38 NOTE: widl breaks compatibility with Visual Basic. If that is important to you then use midl.
  39
  40 II. Debugging
  41
  42 the ActiveX control is compiled with verbose output by default. However you will
  43 need to launch Internet Explorer from a Cygwin shell to see the output.
  44 Alternatively, the plugin will also use the VLC preferences, hence if you enable
  45 the file logging interface through the player and save the preferences, the
  46 control will automatically log its verbose output into the designated file.
  47
  48 Debugging the ActiveX control DLL with GNU GDB can be difficult. Fortunately,
  49 the ActiveX control can also be compiled as an executable rather than a DLL.
  50 In ActiveX terms, this is called a local server.
  51 The advantage of a local server is that it will never crash its client,
  52 i.e Internet Explorer, if itself is crashing.
  53 The build system does not currently allow to create an executable version of
  54 the ActiveX control, you will need to manually define the BUILD_LOCALSERVER
  55 pre-processor variable and modify the Makefile to exclude the '-shared' option
  56 at the linking stage. Once this is done, you just need to launch axvlc.exe to
  57 have a working Activex control. Please note, that executable version of the
  58 ActiveX control will override any settings required for the DLL version, which
  59 will no longer work until you (re)register it as shown in the following section
  60
  61 III. Local Install
  62
  63 The VLC NSIS installer will install the ActiveX Control without requiring any
  64 further manual intervention, but for people who like to live on the edge, here
  65 are the steps you need to perform once you have built the ActiveX Control.
  66
  67 The ActiveX control DLL file may be copied anywhere on the target machine,
  68 but before you can use the control, you will need to register it with Windows
  69 by using the REGSVR32 command, as per following example:
  70
  71 REGSVR32 C:\WINDOWS\AXVLC.DLL
  72
  73 If the control needs to use external VLC plugins (i.e other than built-in ones),
  74 make sure that the plugin path is set in the registry as per following example:
  75
  76 [HKEY_LOCAL_MACHINE\Software\VideoLAN\VLC]
  77 InstallDir="C:\Program Files\VideoLAN\VLC"
  78
  79 The InstallDir must be the parent directory of the 'plugins' directory.
  80
  81 WARNING: Both control and plugins must come from the same build source tree.
  82 Otherwise, at best, the control will not play any content, at worse
  83 it may crash Internet Explorer while attempting to load incompatible plugins.
  84
  85 IV. Internet Install
  86
  87 The activex control may be installed from a remote through Internet Installer if
  88 it is packaged up in a CAB file. The following link explains how to achieve this
  89
  90 http://msdn.microsoft.com/workshop/components/activex/packaging.asp
  91
  92 For convenience, I have provided a sample axvlc.INF file, which assumes that the VLC
  93 NSIS Installer has been packaged up a CAB file called AXVLC.CAB.
  94
  95 The ActiveX Control DLL file can also be distributed by itself if it has been
  96 compiled with built-in VLC plugins; check developer information for more
  97 information on built-in plugins.
  98
  99 V. Controlling the plugin
 100
 101 1) Properties
 102
 103 the following public properties can be used to control the plugin from HTML,
 104 the property panel of Visual Basic and most ActiveX aware applications.
 105
 106 +==========+=========+===================================+===============+
 107 | Name:    | Type:   |   Description:                    | Alias:        |
 108 +==========+=========+===================================+===============+
 109 | autoplay | boolean | play when control is activated    | autostart     |
 110 +----------+---------+-----------------------------------+---------------+
 111 | autoloop | boolean | loop the playlist                 | loop          |
 112 +----------+---------+-----------------------------------+---------------+
 113 | mrl      | string  | initial MRL in playlist           | src, filename |
 114 +----------+---------+-----------------------------------+---------------+
 115 | mute     | boolean | mute audio volume                 |               |
 116 +----------+---------+-----------------------------------+---------------+
 117 | visible  | boolean | show/hide control viewport        | showdisplay   |
 118 +----------+---------+-----------------------------------+---------------+
 119 | volume   | integer | set/get audio volume              |               |
 120 +----------+---------+-----------------------------------+---------------+
 121 | toolbar  | boolean | set/get visibility of the toolbar |               |
 122 +----------+---------+-----------------------------------+---------------+
 123
 124 the alias column allows to specify an alternative <PARAM name> for the
 125 property in internet explorer, which is useful to maintain compatibility
 126 with HTML pages already leveraging Windows Media Player
 127
 128 2) Programming APIs
 129
 130 the MRL, Autoplay and Autoloop properties are only used to configure the initial
 131 state of the ActiveX control,i.e before its activation; they are ignored afterward.
 132 Therefore, if some runtime control is required, the following APIs should be used
 133 within your programming environment:
 134
 135 Variables:
 136
 137 +==========+=========+=========+=======================================+
 138 | Name:    | Type:   | Access: | Description:                          |
 139 +==========+=========+=========+=======================================+
 140 | Playing  | boolean |   RO    | Returns whether some MRL is playing   |
 141 +----------+---------+---------+---------------------------------------+
 142 | Time     | integer |   RW    | Time elapsed in seconds playing       |
 143 |          |         |         | current MRL                           |
 144 |          |         |         | NOTE: live feeds returns 0            |
 145 +----------+---------+---------+---------------------------------------+
 146 | Position | real    |   RW    | Playback position within current MRL  |
 147 |          |         |         | in a scale from 0.0 to 1.0            |
 148 |          |         |         | NOTE: live feeds returns 0.0          |
 149 +----------+---------+---------+---------------------------------------+
 150 | Length   | integer |   RO    | Total length in seconds of current MRL|
 151 |          |         |         | NOTE: live feeds returns 0            |
 152 +----------+---------+---------+---------------------------------------+
 153 | Volume   | integer |   RW    | Current volume from 0 to 100          |
 154 +----------+---------+---------+---------------------------------------+
 155 | Visible  | boolean |   RW    | Indicates whether control is visible  |
 156 +----------+---------+---------+---------------------------------------+
 157
 158 Methods:
 159
 160   *** current interface (0.8.6+) ***
 161 UUID : 9BE31822-FDAD-461B-AD51-BE1D1C159921
 162 defined in axvlc.idl as "coclass VLCPlugin2", "interface IVLCControl2"
 163
 164 This interface organize API with several object (like .audio.mute)
 165 It is currently documented on videolan wiki (may change) at
 166 http://wiki.videolan.org/Documentation:Play_HowTo/Advanced_Use_of_VLC
 167
 168
 169   ***  old interface (deprecated)  ***
 170 UUID : E23FE9C6-778E-49D4-B537-38FCDE4887D8
 171 defined in axvlc.idl as "coclass VLCPlugin", "interface IVLCControl"
 172
 173 play()
 174     Play current item the playlist
 175
 176 pause()
 177     Pause current item in the playlist
 178
 179 stop()
 180     Stop playing current item in playlist
 181
 182 shuttle(Seconds as integer)
 183     Advance/backtrack playback by specified amount (which is negative for
 184     backtracking). This is also called relative seeking.
 185     This method does not work for live streams.
 186
 187 fullscreen()
 188     Switch between normal and full screen video
 189
 190 playFaster()
 191     Increase play back speed by 2X, 4X, 8X
 192
 193 playSlower()
 194     Decrease play back speed by 2X, 4X, 8X
 195
 196 toggleMute()
 197     mute/unmute sound output
 198
 199 addTarget(MRL As String, Options as array of strings, Mode as enumeration, Position as integer)
 200     Add MRL into the default playlist, you can also specify a list of playlist Options to attach
 201     to this MRL or Null for no options. mode indicates the action taken by the playlist on MRL
 202     which is one the following:
 203         VLCPlayListInsert       =  1 (Insert MRL into playlist at Position)
 204         VLCPlayListInsertAndGo  =  9 (Insert MRL into playlist at Position and play it immediately)
 205         VLCPlayListReplace      =  2 (Replace MRL in playlist at Position)
 206         VLCPlayListReplaceAndGo = 10 (Replace MRL in playlist at Position and play it immediately)
 207         VLCPlayListAppend       =  4 (Append MRL in playlist after Position)
 208         VLCPlayListAppendAndGo  = 12 (Append MRL in playlist after Position and play it immediately)
 209         VLCPlayListCheckInsert  = 16 (Verify if MRL is in playlist)
 210     Position can take the value of -666 as wildcard for the last element in playlist
 211
 212
 213 setVariable(Name as string, Value as object);
 214     Set a value into a VLC variables
 215
 216 getVariable( Name as string) as object
 217     Retrieve the value of a VLC variable.
 218
 219 Regards,
 220     Damien Fouilleul <Damien dot Fouilleul at laposte dot net>
 221