modules/swftools/swftools.module

<?php
// $Id: swftools.module,v 1.36 2009/03/18 23:27:43 stuartgreenfield Exp $

// Include the generic player module for basic mp3 and flv support
include_once(drupal_get_path('module', 'swftools') .'/genericplayers.module');

// The following list defines all the actions that SWF Tools understands
// Component modules report to SWF Tools what actions they support via hook_swftools_methods()
define('SWFTOOLS_EMBED',               'swftools_embed');              // Provides an embedding method
define('SWFTOOLS_IMAGE_DISPLAY_LIST',  'swftools_image_display_list'); // Can display list of images
define('SWFTOOLS_FLV_DISPLAY',         'swftools_flv_display');        // Can display .flv format file
define('SWFTOOLS_FLV_DISPLAY_LIST',    'swftools_flv_display_list');   // Can display list of .flv format files
define('SWFTOOLS_MP3_DISPLAY',         'swftools_mp3_display');        // Can display .mp3 format file
define('SWFTOOLS_MP3_DISPLAY_LIST',    'swftools_mp3_display_list');   // Can display list of .mp3 format files
define('SWFTOOLS_MEDIA_DISPLAY',       'swftools_media_display');      // Can display an unspecified file format
define('SWFTOOLS_MEDIA_DISPLAY_LIST',  'swftools_media_display_list'); // Can display list of mixed files
define('SWFTOOLS_SWF_DISPLAY_DIRECT',  'swftools_swf_display_direct'); // Can display .swf format file, not inside any player
define('SWFTOOLS_SWF_DISPLAY',         'swftools_swf_display');        // Can display .swf format inside a player

// These are for user convenience, most common parameters for casual users using the api.
define('SWFDEFAULT', FALSE);
define('SWFTOOLS_SWF', 'swftools_swf');                     // This is a 'player' method implemented by swftools.module itself.
define('SWFTOOLS_CUSTOM', 'swftools_custom');               // An unknown media/file player.
define('SWFTOOLS_NOJAVASCRIPT', 'swftools_nojavascript');   // This is an 'embed' method implemented by swftools.module itself.
//define('SWFTOOLS_DEFAULT_BG', $GLOBALS['base_url'] .'/'. drupal_get_path('module', 'swftools') .'/shared/swftools-default.jpg');       // A generic image for use in certain contexts.
define('SWFTOOLS_DEFAULT_BG', url(drupal_get_path('module', 'swftools') . '/shared/swftools-default.jpg', array('absolute' => TRUE)));   // A generic image for use in certain contexts.

// Let other modules know SWF Tools is available
define('SWFTOOLS_INSTALLED', TRUE);

// Configure some other defaults
define('SWFTOOLS_DEFAULT_HTML_ALT', '<p>You are missing some Flash content that should appear here! Perhaps your browser cannot display it, or maybe it did not initialize correctly.</p>');
define('SWFTOOLS_PLAYLIST_PATH', 'playlists');
define('SWFTOOLS_PLAYER_PATH', '');
define('SWFTOOLS_GRANT_ACCESS_TO_PRIVATE_FILES', FALSE);
define('SWFTOOLS_GRANT_ACCESS_EXTENSIONS', 'swf flv xml mp3 jpg jpeg png');
define('SWFTOOLS_ALWAYS_ADD_JS', TRUE);

/**
 * Implementation of hook_init(), used to force embedding JavaScript on to all pages
 */
function swftools_init() {
  if (variable_get('swftools_always_add_js', SWFTOOLS_ALWAYS_ADD_JS)) {
    swftools_push_js();
  }
}

/**
 * Implementation of hook_menu().
 */
function swftools_menu() {

  // Initialise array
  $items = array();

  // Should this be administer swf tools?
  $swf_admin = array('administer flash');

  $items['admin/settings/swftools'] = array(
    'title' => 'SWF Tools',
    'description' => 'Settings to control how SWF Tools integrates with Adobe Flash related methods and tools like video players, MP3 players and image viewers.',
    'access arguments' => $swf_admin,
    'page callback' => 'system_admin_menu_block_page',
    'file' => 'system.admin.inc',
    'file path' => drupal_get_path('module', 'system'),
  );

  $items['admin/settings/swftools/handling'] = array(
    'title' => 'File handling',
    'description' => 'Configure how SWF Tools should handle different types of file.',
    'access arguments' => $swf_admin,
    'weight' => -1,
    'page callback' => 'drupal_get_form',
    'page arguments' => array('swftools_admin_handling_form'),
    'file' => 'swftools.admin.inc',
  );

  $items['admin/settings/swftools/embed'] = array(
    'title' => 'Embedding settings',
    'description' => 'Set the embedding method that SWF Tools should use, and configure embedding defaults.',
    'access arguments' => $swf_admin,
    'weight' => -2,
    'page callback' => 'drupal_get_form',
    'page arguments' => array('swftools_admin_embed_form'),
    'file' => 'swftools.admin.inc',
  );

  $items['admin/reports/swftools'] = array(
    'title' => 'SWF Tools status',
    'description' => 'Get an overview of the status of the SWF Tools module and its supporting files.',
    'page callback' => 'swftools_status',
    'access arguments' => $swf_admin,
    'file' => 'swftools.admin.status.inc',
    'weight' => 9,
  );

  $items = array_merge($items, genericplayers_menu());

  return $items;
}


/**
 * Implementation of hook_perm().
 */
function swftools_perm() {
  return array(
    'administer flash',
  );
}


/**
 * Take an array of play list data and options, and return a markup string.
 * 
 * @param $playlist_data
 *   A formatted array of data to be used to create the playlist. An appropriate
 *   array can be created from an array of filenames by calling swftools_prepare_playlist_data.
 * @param $options
 *   An array of options to pass to the call to swf().
 * @return
 *   A string of markup to produce the playlist in a flash media player.
 */
function swf_list($playlist_data, $options = array()) {

  // Populate methods and othervars with playlist data
  if (is_array($playlist_data)) {

    // If action isn't set then set it
    if (empty($options['methods']['action']) && isset($playlist_data['action'])) {
      $options['methods']['action'] = $playlist_data['action'];
    }
    
    // If playlist_data isn't set then set it
    if (empty($options['othervars']['playlist_data'])) {
      $options['othervars']['playlist_data'] = $playlist_data;
    }
      
    // If playlist filename is set
    if (isset($playlist_data['filename'])) {
      $playlist = $playlist_data['filename'];
    }
    else {
      $playlist = '';
    }

    // Produce markup
    return swf($playlist, $options);
  }
}

/**
 * Return output, which might be embed markup, or pre-flash markup, that
 * includes the appropriate JavaScript added to the head of the page.
 *
 * @param $file
 *   The file to be played. If it is a SWF file it will usually be embedded directly.
 *   Use a full URL, a path relative to webroot, or a path relative to the configured files directory.
 *   If an array is passed then the array will be converted to a playlist automatically.
 *   If the file string is a complete url then SWF Tools will pass it along unaltered. If the string
 *   is a partial path then it will either be resolved to the local file system, or to a remote host,
 *   depending whether the swftools_media_url variable is set.
 * @param $options=>$params
 *   An associative array of <param> variables to set.eg. array('bgcolor'=>'FF00FF')
 *   To set height and width: array('width'=>'200', 'height'=>'120'). However,
 *   as a convenient alternative for the common requirement of just height and width
 *   you can also pass a text string like '200x100'.
 *   If you pass nothing, and the file to play is a .swf, swftools will try and
 *   establish a natural width and height from the actual .swf file that you've
 *   passed into $file.
 * @param $options=>$flashvars
 *   An associative array of flashvar variables to set. eg. array('playlist'=>'files/my_playlist.xml')
 * @param $options=>$othervars
 *   An associative array of variables that might be required by the $player or $embed technique.
 *   These values are not output as params or flashvars.
 * @param $options=>$methods
 *   Explicitly declare an action, player or embedding method by passing an array of
 *   the form: array('action'=>'dosomething', 'player'=>'withsomething', 'embed'=>'withthisjavascript').
 *   These usually default to the administration settings and also you will
 *   usually use a CONSTANT which will be documented further at a later stage.
 */
function swf($file, $options = array()) {
  
  // Initialise any $options array elements that weren't passed by the caller
  $options += array(
    'params' => array(),
    'flashvars' => array(),
    'othervars' => array(),
    'methods' => array(),
  );

  // If swf() was called with an array of files, make a playlist and call swf_list() for processing
  if (is_array($file)) {
   
    // Determine if this is streamed content
    $stream = FALSE;
    if (isset($options['othervars']['stream'])) {
      $stream = TRUE;
    }
    
    // Is a specific action being set?
    $get_action = (isset($options['methods']['action'])) ? FALSE : TRUE;
    
    // Turn the array in to a playlist
    $playlist_data = swftools_prepare_playlist_data($file, '', $get_action, array(), $stream);

    // Call swf_list to process the playlist and create the markup
    return swf_list($playlist_data, $options);
  }

  // Get all the actions, players and embedding options available to us
  $methods = swftools_methods_available();

  
  // ACTION
  // Work out what SWF Tools should do with this file

  // Was an explicit action set in $options['methods']['action']
  $action = (isset($options['methods']['action'])) ? $options['methods']['action'] : FALSE;

  // If an explicit action wasn't set then try to determine an appropriate one using the filename
  if (!$action) {
    $action = swftools_get_action($file);
  }
  
  // HTML ALTERNATIVE
  // If an explicit value wasn't set in $options['othervars']['html_alt'] use a default
  $html_alt = (isset($options['othervars']['html_alt'])) ? $options['othervars']['html_alt'] : variable_get('swftools_html_alt', SWFTOOLS_DEFAULT_HTML_ALT);

  
  // RESOLVE PLAYER AND EMBEDDING
  // 'resolved' refers to the fact that these are the methods we now intend to use, not /all/ methods available.
  $resolved_methods = new stdClass();

  
  // PLAYER
  // Work out what player SWF Tools will need to use for this action
  
  // Was an explicit player set in $options['methods']['player']
  $player = (isset($options['methods']['player'])) ? $options['methods']['player'] : FALSE;
  
  // If an explicit player wasn't set then find out what player is configured for the current action
  if (!$player) {

    // Find out what player is assigned to handle the current action
    $player = swftools_get_player($action);
    
    // If still no player assignment then we don't know what to do with this action
    if (!$player) {
      
      // Build an array of descriptions for each possible action
      $descriptions = array(
        SWFTOOLS_IMAGE_DISPLAY_LIST=> 'a series of images',
        SWFTOOLS_FLV_DISPLAY=> 'a single flv file',
        SWFTOOLS_FLV_DISPLAY_LIST=> 'a series of flv files',
        SWFTOOLS_MP3_DISPLAY=> 'a single mp3 file',
        SWFTOOLS_MP3_DISPLAY_LIST=> 'a series of mp3 files',
        SWFTOOLS_MEDIA_DISPLAY_LIST=> 'a series mixed media files',
      );
      
      // If we have a matching description for the specified action, create a meaningful message
      if (isset($descriptions[$action])) {
        drupal_set_message(t('No player is configured to play ' . $descriptions[$action] . '. Check the SWF Tools file handling settings on the configuration page.'), 'error');
      }
      
      // Otherwise we have an action that SWF Tools doesn't understand, so create a fallback message
      else {
        drupal_set_message(t('No player is configured for the action %action. Check the SWF Tools file handling settings on the configuration page.', array('%action' => $action)), 'error');
      }

      // We couldn't find a player for this content, so fallback to the alternate markup and return
      return $html_alt;
    }
  }
  
  // Check that the action / player combination is valid by checking for the [action][player] keys
  if (isset($methods[$action][$player])) {
    
    // If the combination was found, place player information in to $resolved_methods
    $resolved_methods->player = $methods[$action][$player];
  
  }
  
  // If the action / player combination doesn't appear then we need to do something else
  else {
    
    // If the action is display an swf directly then assume we have a custom player
    if ($action == SWFTOOLS_SWF_DISPLAY_DIRECT) {

      // Assign SWFTOOLS_CUSTOM data in to $resolved_methods
      $resolved_methods->player = $methods[$action][SWFTOOLS_CUSTOM];
      $resolved_methods->player['shared_file'] = $player;
    }

    // This player and action combination is not valid
    else {
      drupal_set_message(t('%player cannot perform the action %action.', array('%player' => $player, '%action' => $action)), 'error', FALSE);
      return $html_alt;
    }
  }

  
  // EMBED
  // Work out what embedding method SWF Tools should use for this content
  
  // Was an explicit embedding method set in $options['methods']['embed']
  $embed = (isset($options['methods']['embed'])) ? $options['methods']['embed'] : FALSE;
  
  // If an explicit embedding method wasn't set then find get the current default
  if (!$embed) {
    $embed = variable_get('swftools_embed_method', SWFTOOLS_NOJAVASCRIPT);
  }

  // Place the embedding method information in to $resolved_methods
  $resolved_methods->embed = $methods[SWFTOOLS_EMBED][$embed];


  // VARIABLES AND PARAMETERS
  // Put all the variables on a simple object to make internal function calls simpler
  $vars = new stdClass();

  
  // OTHERVARS
  // If $options['othervars'] were supplied, add to $vars->othervars
  $vars->othervars = (is_array($options['othervars'])) ? $options['othervars'] : array();

  
  // PARAMS
  // $options['params'] could be an associative array, or in 'WIDTHxHEIGHT' format.

  // If $options were passed to the swf() function then process them
  if ($options['params']) {
    
    // If $options['params'] is an array then just add it to $vars
    if (is_array($options['params'])) {
      $vars->params = $options['params'];
    }
    
    // Otherwise see if we can explode the string in to a height and width
    else {
      $dimensions = explode('x', $options['params']);
      if (count($dimensions) == 2) {
        $vars->params = array(
          'width' => $dimensions[0],
          'height' => $dimensions[1],
        );
      }
    }
  }

  
  // FLASHVARS
  // Flashvars could be passed as an associative array, or as a string in 'a=1&b=2' format
  
  // If the flashvars have been passed as an array simply add to $varsa
  if (is_array($options['flashvars'])) {
    $vars->flashvars = $options['flashvars'];
  }
  
  // Otherwise parse the flashvars string in to an array
  else {

    // Parse the string as if in 'a=1&b=2' format.
    parse_str($options['flashvars'], $vars->flashvars);
  }


  // BASE
  // Determine a reasonable 'base' directory, if a remote url is set, use that
  // If file is local, set to the file directory
  
  // Was an explicit base path set in $options['params']['base']
  $base = (!empty($vars->params['base'])) ? $vars->params['base'] : '';
  
  // If the base path isn't set, or the path is not valid try to find a reasonable alternative
  if (!$base || !valid_url($base)) {

    // Use swftools_get_media_url() to obtain either the local path, or the remote media path
    $base = swftools_get_media_url('', FALSE);
  }

  // Strip $base_root if this is a local base path
  $base = swftools_strip_base_root($base);
  
  // Assign the resulting base path in to  $vars->params['base']
  $vars->params['base'] = $base;

  
  // PLAYLIST
  // Determine if we trying to generate a playlist
  
  // If $options['othervars']['playlist_data'] is set then we are processing a playlist
  if (isset($options['othervars']['playlist_data'])) {
    
    // Flag that a playlist is being generated
    $playlist = TRUE;

    // Generate a playlist in the files directory
    $file = swftools_generate_playlist($options['othervars']['playlist_data'], '', $resolved_methods, $vars);

    // If a file wasn't generated by swftools_generate_playlist then set an error and return alternate markup
    if (!$file) {
      drupal_set_message(t('Unable to create playlist.'), 'error');
      return $html_alt;
    }
  }

  
  // CACHING
  // To try and prevent the xml files from being cached append the time to the filename to try and force it to reload
  if (variable_get('swftools_playlist_caching', 'here') == 'always') {
    $nocache = '?nc='. time();
  }
  else {
    $nocache = '';
  }

  
  // FILE
  // Make sure that the file path is $file is valid - we skip this section if $file is already a full url
  // Otherwise we try to expand it to a full url to the local file system or the remote media directory
      
  // If the file isn't a stream and isn't already a url, then turn it in to a url
  if (!isset($vars->othervars['stream']) && !valid_url($file, TRUE)) {
    
    // If file is local, make sure it points to the file directory
    if (swftools_get_media_path()) {
      $file = file_create_path($file);
    }
    
    // Process $file to resolve ensure it resolves to a full url
    $file_url = swftools_create_url($file);

    // If $file_url was not generated then file doesn't exist so return $html_alt
    if (!$file_url) {
      return $html_alt;
    }

  }
  
  // If this is a media stream simply set $file_url to $file
  else {
    $file_url = $file;
  }
  
  // Attach file_url to othervars so player modules have access if required
  $vars->othervars['file_url'] = $file_url;
  
  // SRC
  // Determine the "src" attribute of the embed (also applies to the 'movie' attribute).
  // Usually this is the Flash Player, but it can also be a swf file, or a custom file
  // passed on othervars['shared_file'].
  switch ($player) {
    case SWFTOOLS_SWF:
      $vars->params['src_path'] = $file;
      $vars->params['src'] = $file_url;
      break;
    case SWFTOOLS_CUSTOM:
      $vars->params['src_path'] = $resolved_methods->player['shared_file'];
      $vars->params['src'] = swftools_create_url($vars->params['src_path']);
      break;
    default:
      $vars->params['src_path'] = swftools_get_player_path() . '/' . $resolved_methods->player['shared_file'];
      $vars->params['src'] = $GLOBALS['base_url'] . '/' . $vars->params['src_path'];
  }
  
  // Try to strip $base_root if this is a local path
  $vars->params['src'] = swftools_strip_base_root($vars->params['src']);
   
  // Merge default and user defined "params".
  $vars->params = array_merge(_swftools_params(), $vars->params);

  // Ask the module implementing the player what flashvars are required, pass
  // all existing values by reference to allow optional override at the player.module level.
  if (module_hook($resolved_methods->player['module'], 'swftools_flashvars')) {

    // Get player flashvars
    $player_flashvars = module_invoke($resolved_methods->player['module'], 'swftools_flashvars', $action, $resolved_methods, $vars);

    // Merge player flashvars with existing flashvars
    if (is_array($player_flashvars)) {
      $vars->flashvars = array_merge($vars->flashvars, $player_flashvars);
    }
  }

  // If the player made a flashvar assignment for the playlist, add it to the flashvars
  if (!empty($resolved_methods->player['file'])) {
    $vars->flashvars[$resolved_methods->player['file']] = $vars->othervars['file_url'];
  }

  // If the player requires a specific minimum flash version then assign it to the params
  if (isset($resolved_methods->player['version'])) {
    $vars->params['version'] = $resolved_methods->player['version'];
  }

  // Call function to set the size of the content
  swftools_set_size($vars, $resolved_methods->player);
    
  // Build a string out of the flashvars array.
  $vars->params['flashvars'] = _swftools_get_flashvars_string($vars->flashvars);

  // Call the embedding code to get the HTML and set the JavaScript if necessary.
  $embed_markup = module_invoke($resolved_methods->embed['module'], 'swftools_embed', $action, $resolved_methods, $vars, $html_alt);

  // Call theme function to return completed markup, e.g. add containing div
  return theme('swftools_embed', $embed_markup, $action, $resolved_methods, $vars, $html_alt);
}


/**
 * Produce finished markup ready for inserting on the page
 *
 * @param $embed_markup
 *   The markup needed to add the swf content to the page
 * @param $action
 *   The action that is being used, in case the themer wants it
 * @param $methods
 *   The player and embedding methods being used, in case the themer wants it
 * @param $vars
 *   The array of othervars, params and flashvars in case the themer wants it
 * @param $html_alt
 *   The alternate HTML content, in case the themer wants it
 * @return
 *   An HTML string that generates the output
 */
function theme_swftools_embed($embed_markup, $action, $methods, $vars, $html_alt) {

  // Generate a css id if an id was supplied in $vars->othervars
  $id = (!empty($vars->othervars['id'])) ? ' id="swf-'. $vars->othervars['id'] .'"' : '';

  // Prepare an array of classes to include in the wrapper div
  $classes[] = 'swftools-wrapper';
  $classes[] = str_replace('_', '-', $methods->player['name']);

  // If the user provided class data already then don't over-rule it
  if (!empty($vars->othervars['class'])) {
    $classes[] = $vars->othervars['class'];
  }
  
  // Return completed markup
  return '<div' . $id . ' class="' . implode(' ', $classes) . '">' . $embed_markup . '</div>';
}


/**
 * Collect information from all modules about the methods (players and embedding)
 * that are available.
 * 
 * @param $action
 *   Optional parameter to retrieve data only about a specific action.
 * @param $reset
 *   Optional parameter which if TRUE will reset the methods cache and rebuild it.
 * @return
 *   An array of data describing the available methods.
 */
function swftools_methods_available($action = NULL, $reset = FALSE) {

  // Cache methods array as it may be called several times
  static $methods = array();

  // If user has requested the cache to be reset then reset it
  if ($reset) {
    $methods = array();
  }

  // If the cache isn't populated then build it by calling hook_swftools_methods
  if (!count($methods)) {
    $methods = module_invoke_all('swftools_methods');
  }
  
  // In case no module is presenting support for the required action then the
  // following line avoids a notice error
  if ($action) {
    $methods += array(
      $action => NULL,
    );
  }

  // Return methods - either for the specific action, or all actions
  return ($action) ? $methods[$action] : $methods;

}


/**
 * Convert an array of parameters in to JSON and assign to an object
 * 
 * @param $params
 *   An array of parameters to process.
 * @param $attr
 *   Optional name of object to assign the JSON string to, default is swftools.
 * @return
 *   A string defining the object in JSON.
 */
function swftools_json_params($params, $object = 'swftools') {
  return $object . "='" . drupal_to_js($params) . "'";
}


/**
 * Returns 'true' or 'false' for JavaScript based the supplied value $bool.
 * 
 * @param $bool
 *   The value that should be cast to true or false.
 * @return
 *   The string 'true' or 'false' depending on the supplied value.
 */
function _swftools_tf($bool) {

  // String 'false' is treated as TRUE in PHP logic, so force to FALSE
  if (strtolower($bool) == 'false') {
    $bool = FALSE;
  }

  // Return 'true' or 'false' now we are sure of result
  return $bool ? 'true' : 'false';

}


/**
 * Identify the most likely SWF Tools action for a file, based on its extension.
 * 
 * @param $file
 *   The name of the file for which the action is required.
 * @return
 *   A string describing an SWF Tools action.
 */
function swftools_get_action($file) {

  // Get the path information for this file
  $path_parts = pathinfo($file);
  
  // Select an action based on the file extension
  switch (strtolower($path_parts['extension'])) {
    case 'swf':
      return SWFTOOLS_SWF_DISPLAY_DIRECT;
    case 'flv':
      return SWFTOOLS_FLV_DISPLAY;
    case 'mp3':
      return SWFTOOLS_MP3_DISPLAY;
    case 'jpg': case 'gif': case 'png': case 'jpeg': case 'img':
      return SWFTOOLS_IMAGE_DISPLAY_LIST;
    default:
      // Assume that this is mixed media and let the media player try to handle it
      return SWFTOOLS_MEDIA_DISPLAY_LIST;
  }
}


/**
 * Identify the currently configured player for the specified action.
 *
 * @param $action
 *   The SWF Tools action to be performed.
 * @return
 *   The name of the currently configured player for this action.
 */
function swftools_get_player($action) {

  switch ($action) {
    case SWFTOOLS_SWF_DISPLAY_DIRECT:
      return variable_get(SWFTOOLS_SWF_DISPLAY_DIRECT, SWFTOOLS_SWF);
    case SWFTOOLS_FLV_DISPLAY:
      return variable_get(SWFTOOLS_FLV_DISPLAY, GENERIC_FLV);
    case SWFTOOLS_MP3_DISPLAY:
      return variable_get(SWFTOOLS_MP3_DISPLAY, GENERIC_MP3);

    // For all other actions try to get the setting from the database, otherwise
    // return FALSE to indicate no player is available to handle this action.
    default:
      return variable_get($action, FALSE);
  }
}

/**
 * Returns the playlist path relative to webroot.
 * This path needs to be writeable, so it is fitting to limit valid
 * locations to the files directory.
 *
 */
/**
 * Returns the playlist path, relative to the webroot
 * 
 * @param $dir
 *   If FALSE the function returns the current playlist directory.
 *   Otherwise the function tries to create the named directory in the file system.
 * @return
 *   The path to the playlist directory, either the one stored in the database or
 *   the one that was created, otherwise returns FALSE to indicate failure.
 */
function swftools_get_playlist_path($dir = FALSE) {

  // If no directory specified, get the default
  if (!$dir) {
    $dir = variable_get('swftools_playlist_path', SWFTOOLS_PLAYLIST_PATH);
  }

  // Ensure we have a path in the file system
  $dir = file_create_path($dir);

  // Create playlist directory if necessary
  if (!file_check_directory($dir, FILE_CREATE_DIRECTORY)) {
    drupal_set_message(t('%dir does not exist, or is not writeable.', array('%dir' => $dir)), 'error', FALSE);
  }

  // Return path to the playlist directory
  return $dir;

}


/**
 * Returns a flash player path relative to webroot.
 * The default path is in the modules/swftools/shared directory.
 * It may suit some sites to store flash players in an alternative location, but
 * the assumption is the location will be on the same server.
 * If the path starts with '/', then we can assume is relative to the webroot.
 * Otherwise we assume it's in the files directory.
 * 
 * @param $dir
 *   Optional parameter that gives the location of flash media players.
 * @return
 *   String with the path to the media players.
 */
function swftools_get_player_path($dir = FALSE) {

  // If a directory parameter wasn't set then return the configured value
  if (!$dir) {
    $dir = variable_get('swftools_player_path', SWFTOOLS_PLAYER_PATH);
    
    // If the swftools_player_path variable isn't set return the default path
    if (!$dir) {
      $dir = drupal_get_path('module', 'swftools') .'/shared';
    }
  }
  
  // If $dir starts with / then assume we provided a full path from the web root
  elseif (substr($dir, 0, 1) == '/') {
    $dir = ltrim($dir, '/');
  }
  
  // Otherwise assume the path is in the files directory and build that path
  else {
    $dir = file_create_path($dir);
  }
  
  // Return the resulting directory
  return $dir;
}


/**
 * Returns the media path relative to webroot.
 * There is a setting called 'swftools_media_url'. If this is set, we assume the
 * media is on a different server.
 * 
 * @return
 *   A string containing the path to the local files, or empty if the files are remote.
 */
function swftools_get_media_path() {

  // Retrieve the media url setting
  $media_url = trim(variable_get('swftools_media_url', ''));
  
  // If no media url is set then return the path to local files
  if (!$media_url || $media_url == '') {
    return file_create_path('') . '/';
  }

  // If a media url is set then assume this is a remote path and so we don't know anything
  // about the path between the base url and the file. Return an empty string.
  return '';
}


/**
 * Resolve a path to a full url, either on the local file system, or at a remote address
 * if the swftools_media_url variable has been set. If the path describes a file, is local
 * and the swftools_check_media variable is set then check if the file exists.
 * The path must be relative to the webroot.
 * 
 * @param $path
 *   The file path to check.
 * @param $is_file
 *   Optional flag to indicate that the path points to a file in which case local files can be tested to see if
 *   they exist (defaults to TRUE). If set to FALSE then it indicates the path doesn't refer to a file and it won't be tested.
 * @return
 *   A string with the complete url to the file, either locally or using the remote path, or FALSE if the local file doesn't exist
 */
function swftools_get_media_url($path, $is_file = TRUE) {

  // Retrieve the media url setting - this is set if the files are remote
  static $media_url;
  if (!isset($media_url)) {
    $media_url = trim(variable_get('swftools_media_url', ''));
  }
  
  // If a remote path is set simply build the appropriate path and return
  if ($media_url) {
    return $media_url . '/' . $path;
  }
  
  // If media checking is active, and the path is a file, check to see if it actually exists
  if (variable_get('swftools_check_media', TRUE) && $is_file) {
    
    // If the file doesn't exist, set an error message and return FALSE to indicate failure
    if (!file_exists($path)) {
      drupal_set_message(t('SWF Tools error - %path does not appear to exist.', array('%path' => $path)), 'error');
      return FALSE;
    }
  }

  // Return the path
  return file_create_url($path);

}


/**
 * "flashvars" is a parameter like height and width, which are
 * passed into the flash player as a=1&b=2&...
 *
 */
function _swftools_get_flashvars_string(&$flashvars) {

  foreach ($flashvars AS $var => $value) {
    $flashvars[$var] = str_replace(array('&', '=', '?'), array('%26', '%3D', '%3F'), $value);
  }
  $encoded = drupal_query_string_encode($flashvars);

  // '#' seems to encode as %2523, reverse this, using a more robust hex prefix..
  $encoded = str_replace('%2523', '0x', $encoded);

  // Fix encoding per #181998#comment-882293
  $encoded = str_replace('%3A', ':', $encoded);
  $encoded = str_replace('%252F', '/', $encoded);

  return $encoded;
}


/**
 * Return an array of default values to use as the swf parameters.
 * Parameters are described in the Adobe knowledge base TechNote 12701
 * http://kb.adobe.com/selfservice/viewContent.do?externalId=tn_12701
 * 
 * @return
 *   An array of key/value pairs
 */
function _swftools_params() {

  $defaults = array(
    'swliveconnect'     => variable_get('swftools_params_swliveconnect', 'default'),
    'play'              => variable_get('swftools_params_play', TRUE),
    'loop'              => variable_get('swftools_params_loop', TRUE),
    'menu'              => variable_get('swftools_params_menu', FALSE),
    'quality'           => variable_get('swftools_params_quality', 'autohigh'),
    'scale'             => variable_get('swftools_params_scale', 'showall'),
    'align'             => variable_get('swftools_params_align', 'l'),
    'salign'            => variable_get('swftools_params_salign', 'tl'),
    'wmode'             => variable_get('swftools_params_wmode', 'opaque'),
    'bgcolor'           => variable_get('swftools_params_bgcolor', '#FFFFFF'),
    'version'           => variable_get('swftools_params_version', '7'),
    'allowfullscreen'   => variable_get('swftools_params_allowfullscreen', TRUE),
    'allowscriptaccess' => variable_get('swftools_params_allowscriptaccess', 'sameDomain'), 
  );

  // Ensure that boolean parameters are set to strings 'true' or 'false'
  $defaults['menu'] = _swftools_tf($defaults['menu']);
  $defaults['play'] = _swftools_tf($defaults['play']);
  $defaults['loop'] = _swftools_tf($defaults['loop']);
  $defaults['allowfullscreen'] = _swftools_tf($defaults['allowfullscreen']);

  // Return the defaults
  return $defaults;
}


/**
 * Attempt to return information for the specified file
 * Supply the path to the file to be processed, and it return FALSE if no data
 * was obtained. The return variable, if successful, is an array that may
 * include width, height, extension, file_size, mime_type.
 *
 */
function swftools_get_info($file) {

  // Only check the file if it is local, or it is a media player
  //if (trim(variable_get('swftools_media_url', '')) == '') {
  if ((trim(variable_get('swftools_media_url', '')) == '') or (strpos($file, swftools_get_player_path()) === 0)) {
    $info = image_get_info($file);
    return $info;
  }
  return FALSE;
}


/**
 * Saves a playlist (xml file) to the playlist directory ready for the swf player to use.
 * 
 * @param &$playlist_data
 *   A formatted array of playlist data that will be converted to an xml file. NEED TO DOCUMENT THE STRUCTURE.
 * @param $playlist_name
 *   An optional name for the playlist. If not specified a filename will be created.
 * @param $method
 *   An array describing the selected player method.
 * @param &$vars
 *   Array of variables. Not used by this function, but will be passed to the playlist generator functions.
 * @return
 *   A string containing the path to the playlist, or FALSE if the playlist generation failed.
 *   Note that $playlist_data and $vars can be manipulated by this function.
 */
function swftools_generate_playlist(&$playlist_data, $playlist_name, &$method, &$vars) {

  // If no filename is supplied
  if (!$playlist_name) {
    
    // Initialise a string
    $prename = '';
    
    // Iterate through each element of $playlist_data['playlist']
    foreach ($playlist_data['playlist'] AS $data) {
      
      // Build a string using all the filenames
      $prename .= $data['filename'];
    }
    
    // Hash the resulting string of names and use as the filename
    $playlist_name = md5($method->player['name'] . $prename) . '.xml';
  }

  // Turn the playlist name in to a full path
  $playlist_name = swftools_get_playlist_path() . '/' . $playlist_name;

  // If caching of xml playlist files has been disabled then delete the current playlist by this name
  if (variable_get('swftools_playlist_caching', 'here') == 'always') {
    file_delete($playlist_name);
  }

  // If the playlist already exists then return the path to it
  elseif (is_file($playlist_name)) {
    
    // Return path to the file
    return file_create_url($playlist_name);
  }

  // Determine the name of the relevant hook to output the playlist in the appropriate format
  $hook = $method->player['name'] . '_swftools_playlist';
  
  // Check that the module implements this hook before trying to call it
  if (module_hook($method->player['module'], $hook)) {
    $playlist = module_invoke($method->player['module'], $hook, $playlist_data, $method, $vars);
  }
  
  // If the hook doesn't exist then the player doesn't support playlists
  else {
    drupal_set_message(t('@title module does not support xml playlists.', array('@title' => $method->player['title'])), 'error');
  }

  // Try to open the playlist file ready to store the xml playlist
  if (!$handle = fopen($playlist_name, 'a')) {
    drupal_set_message(t('An error occurred trying to create file %playlist_name.', array('%playlist_name' => $playlist_name)), 'error');
    return FALSE;
  }

  // If the file was opened then try to write the playlist data to it
  if (fwrite($handle, $playlist) === FALSE) {
    drupal_set_message(t('An error occurred trying to create file %playlist_name.', array('%playlist_name' => $playlist_name)), 'error');
    return FALSE;
  }
  
  // Close the file
  fclose($handle);

  // Return a url to the playlist
  return file_create_url($playlist_name);
}


/**
 * Add to the page any supporting files required by a given embedding method.
 * 
 * @param $embed
 *   Optional parameter - if not supplied the files for the current method will be added.
 *   If supplied then the files for the named method will be added.
 * @return
 *   Nothing
 */
function swftools_push_js($embed = SWFDEFAULT) {

  // Get the list of all the the currently available methods
  $methods = swftools_methods_available();
  
  // If no specific embedding method was named then get the current default
  if (!$embed) {
    $embed = variable_get('swftools_embed_method', SWFTOOLS_NOJAVASCRIPT);
  }

  // Call the module responsible to output the js. Don't pass any additional
  // parameters - as we don't want the module to try and return the in-body
  // html placeholder for the flash content.
  $output = module_invoke($methods[SWFTOOLS_EMBED][$embed]['module'], 'swftools_embed');
}


/**
 * Take an array of filenames and prepare them to be used as a playlist
 * 
 * @param $files
 *   An array of files that will be added to the playlist.
 * @param $title
 *   Optional playlist title
 * @param $get_action
 *   Optional parameter indicating if the function should determine an appropriate action. Default is TRUE.
 * @param $type_filter
 *   Optional parameter - an array of file extensions that are permitted
 * @param $stream
 *   Option parameter to indicate if this is going to be a streamed playlist, in which case checks for the
 *   existence of files should be skipped
 * @return unknown_type
 */
function swftools_prepare_playlist_data($files, $title = '', $get_action = TRUE, $type_filter = array(), $stream = FALSE) {
  
  // Initialise an array to return the results in
  $playlist_data = array();
  
  // Set a title for the playlist
  $playlist_data['header']['title'] = $title;
 
  // Initialize an array for the results
  $processed_files = array();
  
  // Iterate through the array of files that have been passed
  foreach ($files AS $key => $data) {

    // If $data is an object then recast it to an array
    if (is_object($data)) {
      $temp = array($data);      
    }
    
    // If $data is already an array simply put a copy in $temp
    elseif (is_array($data)) {
      $temp = $data;      
    }
    
    // Otherwise turn a single piece of data in to an array
    else {

      // Initialise array
      $temp = array();
      
      // Use the data string as the filepath
      $temp['filepath'] = $data;
      
      // If the $key isn't numeric then take it to be a filename
      if (!is_numeric($key)) {
        $temp['filename'] = $key;
      }
      
      // Otherwise use the data string as the filename
      else {
        $temp['filename'] = $data;
      }
    }

    // Suppress errors in case the array is missing keys
    $temp += array(
      'filename' => '',
      'filepath' => '',
    );
    
    // We should now have an item called $temp, with some known keys, and
    // also any other keys that were passed (if originally an array or object)
    // filepath holds either a file path, or the name of the item sent as a string
    // filename contains either the name of the key from original array, of if this
    // was not set, it will be the same as filepath
    
    // We know $temp array contains keys filename and filepath
    $file['filename'] = $temp['filename'];
    $file['filepath'] = $temp['filepath'];
   
    // Do we need the playlist generator to do this stuff with the urls?
    // I suppose it avoids repetition in later modules.
    
    // If the fileurl isn't set in the original array, then try to work it out
    if (!isset($temp['fileurl'])) {

      // If the filepath is a valid url, use that
      if (valid_url($file['filepath'], TRUE)) {
        $file['fileurl'] = $file['filepath'];
        $file['filepath'] = FALSE; // Flag that we don't know the server path.
      }

      // If fid is set then these are files from the upload module, so make a file path
      elseif (isset($temp['fid'])) {
        $file['fileurl'] = swftools_strip_base_root(swftools_get_media_url($temp['filepath'], FALSE));
      }

      else {
        // Build a fileurl, or just assign the filepath if this is to be streamed
        if (!$stream) {

          // Then check if files are being sourced locally, and if they are build a file path
          if (swftools_get_media_path()) {
            $filepath = file_create_path($file['filepath']);
          }
          else {
            $filepath = $file['filepath'];
          }
          
          $file['filepath'] = $filepath;
          $file['fileurl'] = swftools_strip_base_root(swftools_get_media_url($filepath));
        }
        else {
          $file['fileurl'] = $temp['filepath'];
        }
      }
    }

    // If the filename isn't set then try to extract it from the url
    if (!isset($file['filename'])) {
      $path_parts = pathinfo($file['fileurl']);
      $file['filename'] = $path_parts['basename'];
    }

    // If a title for the file isn't set then create one form the filename
    if (!isset($temp['title'])) {
      $file['title'] = $file['filename'];
    }
    
    // Otherwise use the supplied one
    else {
      $file['title'] = $temp['title'];
    }
    
    // Store the prepared file data in the $processed_files array
    // We now have a consistent array with keys filename, filepath, fileurl and title
    $processed_files[] = $file;
  }

  // Add the finished array of processed files to the playlist data
  $playlist_data['playlist'] = $processed_files;
  
  // Note, we want to exit quickly if the caller did not want us to
  // dynamically determine the display action by passing $get_action = FALSE.
  if (!$get_action) {
    // The caller knows what swftools action to set, so exit here.
    return $playlist_data;
  }

  // Try to work out the action from the files passed.
  $first_valid_file_type = FALSE;
  $mixed_media = FALSE;

  // Process the files attached to the node to determine the correct action.
  foreach ($playlist_data['playlist'] AS $key => $data) {
    
    // fileurl is always set, irrespective of what we are passing, so use this to determine extension
    $path_parts = pathinfo($data['fileurl']);
    
    // Get the extension for the file
    $extension = strtolower($path_parts['extension']);
    
    // Only try to determine actions if there's an extension to work with
    if ($extension) {
    
      // Determine if this is an image type
      if (strpos('|jpg|jpeg|gif|png|', $extension)) {
        // Treat all types of images as the same file type
        $extension = 'img';
      }
  
      // Only process the file if $type_filter is empty (ie. no filter)
      // or if the extension is declared in the $type_filter array.
      if (!count($type_filter) || in_array($extension, $type_filter)) {
        // $first_valid_file_type stores the file type of the first valid file.
        // This will be compared to subsequent files and if two files
        // have different types, the action will be defined as SWFTOOLS_MEDIA_DISPLAY_LIST
        // in order to utilize a flexible media player.
        if (!$first_valid_file_type) {
          $first_valid_file_type = $extension;
        }
        else {
          if ($first_valid_file_type != $extension) {
            $mixed_media = TRUE;
          }
        }
      }
      else {
        // This file is not desired so remove it
        unset($playlist_data['playlist'][$key]);
      }
    }
  }
    
  // Make a decision based on analysing the file array.
  if ($first_valid_file_type == '') {
    // No files passed our test.
    return FALSE;
  }

  // Determine the required action.
  if ($mixed_media) {
    // We have files of multiple types.
    $action = SWFTOOLS_MEDIA_DISPLAY_LIST;
  }
  else {
    // We only had one file type, so discover the action for that type by
    // calling swftools_get_action() with a dummy filename
    $action = swftools_get_action('dummy.' . $first_valid_file_type);
  }

  // Pluralize the action for multiple files if not already pluralized
  if (count($playlist_data['playlist']) > 1 && substr($action, -5, 5) != '_list') {
    $action = $action . '_list';
  }

  // Assign the action to the playlist data ready for return
  $playlist_data['action'] = $action;

  // Return the resulting playlist data
  return $playlist_data;
}


/**
 * Next three filter related code ported from flash_filter.
 *
 */

/*
 * Implementation of hook_filter_tips
 *
 */
function swftools_filter_tips($delta, $format, $long = false) {
  if ($long) {
    return t('
    <h3 id="swftools_filter">SWF Tools Filter</h3>
    <p>The basic syntax for embedding a flash file (.swf), flash movie (.flv) or audio file (.mp3) is:</p>
    <blockquote><code>&lt;swf file="filename.swf"&gt;</code></blockquote>

    <p>If you would like to override SWF Tools and flash player default settings,
       you can specify additional parameters. For example:</p>
    <blockquote><code>&lt;swf file="song.mp3" flashvars="backcolor=#AABBCC&&forecolor=#11AA11"&gt;</code></blockquote>
    <p>If you would like to output a list of files then the format is:</p>
    <blockquote><code>&lt;swf files="image1.jpg&&image2.jpg&&..."&gt;</code></blockquote>
    SWF Tools Filter will accept following:
    <ul>
      <li><b>params</b> : You can specify values for parameters to be passed to Flash
                           to control the appearance of the output. Typical values are
                           bgcolor and wmode. Example: <code>params="wmode=true&&bgcolor="#00FF00"</code>
                           Alternatively you can supply each parameter individually without using
                           <code>params</code>. Example <code>wmode="true" bgcolor="#00FF00"</code></li>
      <li><b>flashvars</b> : You can specify values for output as flashvars, which
                           become available to the Flash movie that is playing. This is often done
                           to control a media player. Refer to the documentation of the flash player
                           you are using to know what flashvar options are available.
                           Example: <code>flashvars="autostart=true&&volume=80"</code></li>
      <li><b>methods</b> : Optional information about how to display the file. The most
                           common usage is to specify a particular media player and
                           thus override the default specified on the settings page.
                           Example: <code>methods="player=onepixelout_mp3"</code></li>
       </ul>
      <p><strong>WARNING</strong>: with params, flashvars and othervars, pass multiple values
                      separated by <strong>&amp;&amp;</strong>.</p>');
  }
  else {
    return t('You may use !swftools_filter_help to display Flash files inline', array("!swftools_filter_help" => l('<swf file="song.mp3">', "filter/tips/$format", array('query' => 'swftools_filter'))));
  }
}

/*
 * Implementation of hook_filter
 *
 */
function swftools_filter($op, $delta = 0, $format = -1, $text = '') {
  switch ($op) {
    case 'list':
      return array(0 => t('SWF Tools filter'));
    case 'no cache':
      return FALSE;
    case 'description':
      return t('Substitutes <swf file="filename.flv"> or <swf files="file1.jpg&&file2.jpg"> with embedding code.');
    case 'prepare':
        // replace <swf > with [swf ] to prevent other filters stripping
        return (preg_replace('/\<(swflist|swf)\s*(.*)>/sU', '[\1 \2]', $text));
    case 'process':
      return _swftools_filter_process_text($text);
  }
}

/*
 * This function processes the filter text that the user has added to the text area.
 * If the filter is wrapped in <p></p> then these are stripped as part of the processing
 * This eliminates a validation error in the resulting mark up if SWF Tools filter is
 * being used in conjunction with other HTML filters that correct line breaks.
 * It won't work in EVERY case, but it will work in MOST cases.
 * Filters that are embedded in-line with text will continue to fail validation.
 */
function _swftools_filter_process_text($text) {
  $endl = chr(13) ;
  if (preg_match_all('@(?:<p>)?\[(swflist|swf)\s*(.*?)\](?:</p>)?@s', $text, $match)) {
    // $match[0][#] .... fully matched string <swf|swflist parm_0="value_0" parm_1="value_1" parm_2="value_2">
    // $match[1][#] .... matched tag type ( swf | swflist )
    // $match[2][#] .... full params string until the closing '>'

    $swftools_parameters = array('file', 'params', 'flashvars', 'othervars', 'methods', 'files');
    $match_vars = array();
    foreach ($match[2] as $key => $passed_parameters) {
      preg_match_all('/(\w*)=\"(.*?)\"/', $passed_parameters, $match_vars[$key]);
      // $match_vars[0][#] .... fully matched string
      // $match_vars[1][#] .... matched parameter, eg flashvars, params
      // $match_vars[2][#] .... value after the '='

      // Process the parameters onto the $prepared array.
      // Search for standard parameters, parse the values out onto the array.
      foreach ($match_vars[$key][1] as $vars_key => $vars_name) {

        // Switch to swf or swflist, based on file or files
        // Need to tidy up this line, probably use switch/case
        if ($vars_name == 'file') {
          $match[1][$key] = 'swf';
        }
        else {
          if ($vars_name == 'files') {
            $match[1][$key] = 'swflist';
          }
        }

        if ($vars_name == 'file') {
          $prepared[$key][$vars_name] = $match_vars[$key][2][$vars_key];
          unset ($match_vars[$key][1][$vars_key]);
        }
        elseif (in_array($vars_name, $swftools_parameters)) {
          $prepared[$key][$vars_name] = swftools_url_parse(str_replace(array('&amp;&amp;', '&&'), '&', $match_vars[$key][2][$vars_key]));
          unset ($match_vars[$key][1][$vars_key]);
        }
        else 