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