[[PageOutline(3-4, Sections)]]

== !SearchToMail == 

=== Intro ===

  schedule a periodical search for subtitles matching given video files, send results to user's e-mail address.


----
=== Description ===

  '''struct !SearchToMail(string $token, array(string $sublanguageid, string $sublanguageid, ...) $sublangs, array(struct('moviehash' => string $moviehash, 'moviesize' => double $moviesize), ...) $videos)'''

  This function will perodically search for subtitles in languages ''sublangs'' and matching video files ''videos'' and send the results to user's e-mail address.

  Available only to registered users.
  
  Scenario: user has a directory with movies he cannot find subtitles to. With this function he can subscribe to possible results, when someone else uploads matching subtitles.
  
  Once a day/week (based on user's profile) the system will send subtitle link by e-mail to user's e-mail address.

{{{
#!html
  <div style='color:red'>This page contains unverified information, if you try to implement this feature and find any mistakes, please, fix them.</div>
}}}
  

----
=== Parameters ===

  Used parameter structure:
  {{{
  struct(
    (string) [token],
    array( <--- list of subtitle languages
      (string) [lang3],
      (string) [lang3], 
      ... more subtitle language IDs go here (if any) ...
    ),
    array( <--- list of video files
      struct( <--- video file information
        (string) [moviehash],
        (double) [moviesize]
      ),
      ... more video file information structures go here (if any) ...
    )
  )
  }}}

  This function takes 3 parameters, first is the session token, second is an array of subtitle languages and third is the array/list of video file hashes.

  ''token (required)''::
    token string identifying user's session, taken from [XmlRpcLogIn LogIn] output structure.
    token mustn't be a session of an anonymous user
  ''sublangs''::
    array of subtitle file language IDs (ISO639-3 codes),
    if no languages are specified (array is empty), system will try to find subtitles in all languages.
  ''videos''::
    array of video file information using structure displayed below.
    
  Structure of video file information:
  {{{
  struct(
    (string) [moviehash],
    (double) [moviesize]
  )
  }}}


----
=== Return Values ===

  The returned structure contains these elements:
    ''status''::
      function result code, see [XmlRpcStatusCode list of status codes]
    ''seconds''::
      time taken to execute this command on server


----
=== Implementations ===

  There are currently no available sample implementations.


----
=== Changelog ===

  Version 1: created this function


----
=== Examples ===


==== Input ====
  
{{{
#!html
  <div style='color:red'>TO-DO</div>
}}}

  
==== Output ====

{{{
#!xml
<methodResponse>
<params>
 <param>
  <value>
   <struct>
    <member>
     <name>status</name>
     <value><string>200 OK</string></value>
    </member>
    <member>
     <name>seconds</name>
     <value><double>0.197</double></value>
    </member>
   </struct>
  </value>
 </param>
</params>
</methodResponse>
}}}


----
=== Notes ===

  * if possible, send moviehashes and moviesizes only for the first CD in set (e.g. for movies on 2+ CDs) because users will receive duplicate e-mails (one for CD1, one for CD2, ...)


----
=== See also ===

  * [wiki:XmlRpcSearchSubtitles SearchSubtitles]


----
=== Comments ===

	add your comments, hints and suggestions here if you like ...


--------
[Prev] [wiki:XmlRpcIntro Home] [Next]