share/lua/sd/README.txt

   1 ## Instructions to code your own VLC Lua services discovery script.
   2 $Id$
   3
   4 See lua/README.txt for generic documentation about Lua usage in VLC.
   5
   6 Examples: See fmc.lua, frenchtv.lua
   7
   8 ## API
   9 VLC Lua SD modules should define two functions:
  10   * descriptor(): returns a table with information about the module.
  11     The table has the following members:
  12       .title: the name of the SD
  13       .capabilities: A list of your SD's capabilities. Only the
  14         following flags are supported yet:
  15         * 'search' : Does your SD handle search himself
  16
  17     Example:
  18     function descriptor()
  19       return { title = "My SD's title", capabilities={"search"}}
  20     end
  21
  22   * main(): will be called when the SD is started. It should use VLC's SD API
  23     described in lua/README.txt do add the items found.
  24
  25   * search(query_string): Will be called with a string to search for
  26     services/medias matching that string.
  27
  28
  29 User defined modules stored in the share/lua/modules/ directory are
  30 available. Read the 'Lazy initialization' section
  31
  32 Available VLC specific Lua modules: input, msg, net, object, sd,
  33 strings, variables, stream, gettext, xml. See lua/README.txt.
  34
  35 ## Lazy Initialization
  36
  37 SD Lua scripts are actually ran in two different contexts/interpreters. One of
  38 them is the one that will call your main() and search() functions. The other one
  39 is a lighter one that will only fetch your description(). Due to threading
  40 issues and to reduce implementation complexity (NDLR: i guess), the
  41 description() interpreter doesn't load/expose VLC's API nor add
  42 share/lua/modules to the lua load path (these modules are using vlc API anyway).
  43 This has some implications to the way you need to load modules.
  44
  45 This means you cannot make a global/top-level require for the module you use but
  46 instead use lazily load them from the main() and/or search() functions. Here's
  47 an example implementation:
  48
  49 -------------------------------------------------------------------------------
  50 lazily_loaded = false
  51 dkjson        = nil
  52
  53 function lazy_load()
  54   if lazily_loaded then return nil end
  55   dkjson = require("dkjson")
  56   lazily_loaded = true
  57 end
  58
  59 function descriptor()
  60   return { title = "..." }
  61 end
  62
  63 function main()
  64   lazy_load()
  65   -- Do stuff here
  66 end
  67
  68 function search(query)
  69   lazy_load()
  70   -- Do stuff here
  71 end
  72 -------------------------------------------------------------------------------