Media API
=========

HOOKS
=====

/**
 * MAPI core hook
 */
mapi_extensions()
-----------------
* 'list'
  Returns a list of the extensions handled by the module.

* 'mime'
  Returns the appropriate mime value for the extension.

* 'dimensions'
  Returns the physical dimensions of the filename. (This is only height/width/duration)

* 'metadata'
  Returns metadata for the filename.

/**
 * MAPI core hook
 */
mapi_types()
------------
* 'list'
  Returns a list of types the module handles.

* 'extensions'
  Returns a list of the extension a type handles.

* 'info'
  Returns basic information for a type.
  Can be used for defining node types.

/**
 * MAPI core hook
 */
mapi_presenters()
-----------------
* 'list'
  Lists the presenters available for use.

* 'extensions'
  Lists the extension that a presenter can handle.

* 'display'
  Returns HTML for a presentation of a filename for a given presenter.

* 'playlist'
  Returns HTML for a playlist presentation of a series of filenames for a given presenter.
  Incompatible filenames are ignored. Also returned are contents for possible required
  files for a playlist (i.e. an addition RSS feed). These are temporarily stored in cache,
  so that the appropriate result can be shown.

* 'defaults'
  Returns a default configuration for the presenter in question

* 'configure'
  Returns form elements to be able to configure the presenter

* 'validate'
  Validates the form elements that are passed to it.

* 'submit'
  Submits the form, this could be useful for updating something, but can't think of a reason
  for it currently.

/**
 * MAPI core hook
 */
mapi_workspaces()
-----------------
* 'list'
  Provides a list of paths that form the basis for usage by the module itself.

* 'path'
  Returns a path for a given selected name, returns file_temporary_path() on failure.

/**
 * MAPI core hook
 */
mapi_profiles()
--------------
* 'create'
  Called when a profile is created

* 'delete'
  Called when a profile is deleted

* 'update'
  Called when a profile is updated

* 'load'
  Called when a profile is loaded

* 'configure'
  Called when configuration details are need for a single object within a profile.

* 'validate'
  Validates the above configuration details

* 'submit'
  Submits the form, with configuration details.

* 'remove'
  Removes a configurable object within a profile.

/**
 * MAPI core hook
 */
mapi_programs()
---------------
* 'list'
  Lists all the programs that this module handles.

* 'path'
  Attempts to locate the path for a given program.

* 'configure'
  Provides a way to generally configure a program for use

* 'validate'
  Validates the previous configure form

* 'submit'
  Notifies of submission of the configure form.

* 'extensions'
  Returns a list of the extensions a program can handle.

/**
 * MAPI core hook
 */
mapi_transforms()
-----------------
* 'list'
  Returns a list of all transforms that this applies to.

* 'extensions'
  Returns a list of all extensions a given transform applies to.

* 'process'
  Proceeds to apply a transform on a file. It is up to the module itself to handle
  changing the file name, or processing it in a different location.

* 'test'
  Returns the result of executing a test on a file name. This includes not only the
  filename, but the given dimensions (height/width/duration) of the newly created filename.

* 'info'
  Returns information for an extension, for instance, a description of what the extension
  does.

* 'defaults'
  Returns defaults for the configuration of a transformation.

* 'configure'
  Returns form elements to process details about the transformation, creating the settings
  which will then be used to perform the transformation.

* 'validate'
  Validates the form data from 'configure'

* 'submit'
  Allows settings to be updated, if there is something that is required, most transformations
  don't require this.

* 'flush'
  Signifies that a transformed files requires updating or deletion, whichever is appropriate.

/**
 * defined in mapi_filter
 */
mapi_filters()
--------------
* 'list'
  Lists the various keywords which will be used by the filtering mechanism, these are then
  directed to this location.

* 'process'
  Processes the resulting information (which is stored in an array), and provides the resulting
  text. This could be HTML or plain text, javascript or whatever else.

* 'configure'
  Allows configuration options for the various filters, which can be used for popups. Generates
  the form array structure.

* 'validate'
  Validates the configuration options.

/**
 * defined in mapi_layout
 */
mapi_layouts()
--------------
* 'list'
  Returns a list of the various layouts available.

* 'process'
  Processes the layouts according to whatever information is required.


FUNCTIONS
=========

// workspace related
function mapi_workspace_list($workspace = null);
function mapi_workspace_path($workspace, $path);

// type related
function mapi_type_list();
function mapi_type_extensions($type);
function mapi_type_info($type);

// extension related
function mapi_extension_list();
function mapi_extension_type($ext);
function mapi_extension_mime($ext);
function mapi_extension_by_mime($mime);
function mapi_extension_list_by_transform($transform);
function mapi_extension_list_by_presenter($presenter);

// presenter related
function mapi_presenter_list();
function mapi_presenter_display($presenter, $filename, $settings);
function mapi_presenter_playlist($presenter, $playlist, $settings);
function mapi_presenter_defaults($presenter);
function mapi_presenter_configure($presenter, $edit = array());
function mapi_presenter_validate($presenter, $values);
function mapi_presenter_submit($presenter, $values);
function mapi_presenter_default($extension);

// profile related
function mapi_profile_list();
function mapi_profile_load($pid);
function mapi_profile_create($name, $settings);
function mapi_profile_delete($pid);
function mapi_profile_update($profile);
function _mapi_profile_validate_settings($settings);

// program related
function mapi_program_list();
function mapi_program_path($program);
function mapi_program_configure($program, $edit);
function mapi_program_validate($program, $values);
function mapi_program_submit($program, $values);

// transform related
function mapi_transform_list();
function mapi_transform_process($transform, $filename, $settings);
function mapi_transform_test($transform, $filename, $settings);
function mapi_transform_info($transform);
function mapi_transform_defaults($transform);
function mapi_transform_configure($transform, $edit);
function mapi_transform_validate($transform, $values);
function mapi_transform_submit($transform, $values);
function mapi_transform_flush($transform);
function mapi_transform_list_by_extension($ext);
function mapi_transform($filename, $transform, $settings);

// file related
function mapi_file_is_local($uri);
function mapi_file_uri($uri);
function mapi_file_exists($uri, $refresh);
function mapi_file_basename($filename);
function mapi_file_name($filename);
function mapi_file_ext($filename);
function mapi_directory_check_location($directory, $options = array());
function mapi_directory_check($directory, $options = array());
function mapi_directory_move($source, $dest, $options = array());
function mapi_directory_delete($directory, $options = array());
function mapi_directory_create($directory, $options = array());
function mapi_file_check_location($filename, $options = array());
function mapi_file_copy($source, $dest, $options = array());
function mapi_file_move($source, $dest, $options = array());
function mapi_file_delete($filename, $options = array());
function mapi_file_transfer($source, $headers);
function mapi_file_mime($filename);
function mapi_file_freename($filename);
function _mapi_file_external($uri);
function _mapi_file_workspace($options);

// display related
function mapi_display($filename, $options);
function mapi_playlist($filenames, $options);
function _mapi_playlist_cached($identifier);

VARIABLES
=========

mapi_allowed_external - What external sites are allowed to be used on this site?
mapi_profile_default - What is the default profile to use with this website?
mapi_presenter_defaults - This provides a default presenter in the case that profile doesn't exist.


THEME
=====

theme_generic($filename, $options) - Themes every extension to however it is necessary to present it.



Derivatives API
===============

FUNCTIONS
=========



Filter API
==========


FUNCTIONS
=========

// text processing, related to filter
function mapi_filter_process_text($text, $settings = array());
function mapi_filter_prepare_text($text);

// finds all occurrence of valid tags within a text
function mapi_filter_find($text);

// generates appropriate tags given the given inputs
function mapi_filter_tag($tag, $settings = array(), $profile = null);

// allows forms to be generated for a specific tag/settings/profile.
function mapi_filter_form_configure($tag, $settings, $profile);
function mapi_filter_form_validate($form_values);

