Required Features
Plupload is multi-runtime file uploader. Keyword here is - multi-runtime. Which means that if one runtime fails to initialize, it will try another. The problem is that runtimes are not equally backed up with the same features. Flash for example has severe problems with chunking and accessing raw file data in general. Also it cannot trigger file dialog programmatically (just like Silverlight). Additionally, Flash and Silverlight have to operate in two modes and the actual set of capabilities depends on the mode that they've been initialized into. HTML4 is the most crippled of all - it can't chunk, it can't resize the images, it can't upload binary streams, it even can't report a progress.
In most cases you do not even need to know about those complexities, but if you are planning something fancy, like extracting ID3v2 tags from MP3 files on client-side or such, you will need a way to tell the Plupload about those capabilities that you'll require, otherwise it might choose a wrong runtime.
Plupload has a number of options that are supported in one runtime, but aren't - in another (see the feature table below). But when you request them in the config, by default, they do not affect the decision-making process in any way (there are exclusions to the rule however). Instead they are considered as recommendations, so that if a runtime that is selected in the end can fulfill them, it will fulfill them. Otherwise they will simply be ignored. This is done to achieve the ultimate purpose - to upload the file, whatever it takes.
Currently there are two operational modes: browser and client. HTML runtimes (HTML5 and HTML4) operate in browser mode only, so additional mode is only for third party shims - Flash and Silverlight.
The whole necessity of introducing additional operational mode arose from the fact that features may be or may not be supported, depending on the way you initialize the runtime. In the table
<tr>
<th>Capability</th>
<th>Description</th>
<td><sup>browser</sup></td>
<td><sup>browser</sup></td>
<td><sup>client</sup></td>
<td><sup>browser</sup></td>
<td><sup>client</sup></td>
<td><sup>browser</sup></td>
</tr>
<tr>
<td>
<strong>
access_binary
</strong>
</td>
<td>
<em>
provide access to raw binary data of the file
</em>
</td>
<td>
✔</td>
<td>
✔ <sup><a href="#wiki-fn_1">[1]</a></sup></td>
<td>✘</td>
<td>✔</td>
<td>✔</td>
<td>✔ <sup><a href="#wiki-fn_8">[8]</a></sup></td>
</tr>
<tr>
<td>
<strong>
access_image_binary
</strong>
</td>
<td>
<em>
provide access to raw binary data of the image
</em>
</td>
<td>
✔</td>
<td>
✔ <sup><a href="#wiki-fn_1">[1]</a></sup></td>
<td>✘</td>
<td>✔</td>
<td>✔</td>
<td>✔ <sup><a href="#wiki-fn_8">[8]</a></sup></td>
</tr>
<tr>
<td>
<strong>
display_media
</strong>
</td>
<td>
<em>
display binary data as thumbs for example
</em>
</td>
<td>
✔</td>
<td>✔
</td>
<td>✔</td>
<td>✔</td>
<td>✔</td>
<td>
✔ <sup><a href="#wiki-fn_8">[8]</a></sup></td>
</tr>
<tr>
<td>
<strong>
do_cors
</strong>
</td>
<td>
<em>
make cross-domain requests
</em>
</td>
<td>
✔</td>
<td>
✔
</td>
<td>✔</td>
<td>
✔</td>
<td>✔</td>
<td>
✘</td>
</tr>
<tr>
<td>
<strong>
drag_and_drop
</strong>
</td>
<td>
<em>
accept files dragged and dropped from the desktop
</em>
</td>
<td>
✔</td>
<td>
✘
</td>
<td>✘</td>
<td>
✘</td>
<td>✘</td>
<td>
✘</td>
</tr>
<tr>
<td>
<strong>
filter_by_extension
</strong>
</td>
<td>
<em>
filter files in selection dialog by their extensions
</em>
</td>
<td>
✔</td>
<td>
✔
</td>
<td>✔</td>
<td>
✔</td>
<td>✔</td>
<td>
✔ <sup><a href="#wiki-fn_7">[7]</a></sup></td>
</tr>
<tr>
<td>
<strong>
resize_image
</strong>
</td>
<td>
<em>
resize image
</em>
</td>
<td>
✔</td>
<td>
✔ <sup><a href="#wiki-fn_1">[1]</a></sup></td>
<td>✘</td>
<td>
✔</td>
<td>✔</td>
<td>
✘</td>
</tr>
<tr>
<td>
<strong>
report_upload_progress
</strong>
</td>
<td>
<em>
periodically report how many bytes were uploaded
</em>
</td>
<td>
✔</td>
<td>
✔ <sup><a href="#wiki-fn_2">[2]</a></sup></td>
<td>✔</td>
<td>
✔</td>
<td>✔</td>
<td>
✘</td>
</tr>
<tr>
<td>
<strong>
return_response_headers
</strong>
</td>
<td>
<em>
provide access to the headers of http response
</em>
</td>
<td>
✔</td>
<td>✘</td>
<td>✘</td>
<td>✘</td>
<td>✔</td>
<td>
✘</td>
</tr>
<tr>
<td>
<strong>
return_response_type
</strong>
</td>
<td>
<em>
support http response of specific type
</em>
</td>
<td>
✔</td>
<td>
✔</td>
<td>✔ <sup><a href="#wiki-fn_9">[9]</a></sup></td>
<td>
✔</td>
<td>✔</td>
<td>
✔</td>
</tr>
<tr>
<td>
<strong>
return_status_code
</strong>
</td>
<td>
<em>
return http status code of the response
</em>
</td>
<td>
✔</td>
<td>
✔</td>
<td>✔ <sup><a href="#wiki-fn_10">[10]</a></sup></td>
<td>
✔ <sup><a href="#wiki-fn_10">[10]</a></sup></td>
<td>✔</td>
<td>
✔</td>
</tr>
<tr>
<td>
<strong>
send_custom_headers
</strong>
</td>
<td>
<em>
send custom http header with the request
</em>
</td>
<td>
✔</td>
<td>
✔
</td>
<td>✘</td>
<td>✘</td>
<td>✔</td>
<td>
✔</td>
</tr>
<tr>
<td>
<strong>
select_file
</strong>
</td>
<td>
<em>
pick up a files from a dialog
</em>
</td>
<td>
✔ <sup><a href="#wiki-fn_3">[3]</a></sup></td>
<td>
✔
</td>
<td>✔</td>
<td>
✔
</td>
<td>✔</td>
<td>
✔</td>
</tr>
<tr>
<td>
<strong>
select_folder
</strong>
</td>
<td>
<em>
select a folder from a dialog
</em>
</td>
<td>
✔ <sup><a href="#wiki-fn_3">[4]</a></sup></td>
<td>
✘
</td>
<td>✘</td>
<td>
✘
</td>
<td>✘</td>
<td>
✘</td>
</tr>
<tr>
<td>
<strong>
select_multiple
</strong>
</td>
<td>
<em>
select multiple files at once from a file dialog
</em>
</td>
<td>
✔ <sup><a href="#wiki-fn_4">[5]</a></sup></td>
<td>
✔
</td>
<td>✔</td>
<td>
✔
</td>
<td>✔</td>
<td>
✘</td>
</tr>
<tr>
<td>
<strong>
send_binary_string
</strong>
</td>
<td>
<em>
send raw binary data (typically a binary string)
</em>
</td>
<td>
✔</td>
<td>
✔ <sup><a href="#wiki-fn_1">[1]</a></sup></td>
<td>✘</td>
<td>
✔
</td>
<td>✔</td>
<td>
✘</td>
</tr>
<tr>
<td>
<strong>
send_browser_cookies
</strong>
</td>
<td>
<em>
send browser cookies with http request
</em>
</td>
<td>
✔</td>
<td>
✔
</td>
<td>✘</td>
<td>
✔
</td>
<td>✘</td>
<td>
✔</td>
</tr>
<tr>
<td>
<strong>
send_multipart
</strong>
</td>
<td>
<em>
send multipart/form-data
</em>
</td>
<td>
✔</td>
<td>
✔
</td>
<td>✔</td>
<td>
✔
</td>
<td>✔</td>
<td>
✔</td>
</tr>
<tr>
<td>
<strong>
slice_blob
</strong>
</td>
<td>
<em>
slice the file or blob
</em>
</td>
<td>
✔ <sup><a href="#wiki-fn_7">[7]</a></sup></td>
<td>
✔ <sup><a href="#wiki-fn_1">[1]</a></sup></td>
<td>✘</td>
<td>
✔
</td>
<td>✔</td>
<td>
✘</td>
</tr>
<tr>
<td>
<strong>
stream_upload
</strong>
</td>
<td>
<em>
upload file without preloading it to memory
</em>
</td>
<td>
✔</td>
<td>✘</td>
<td>✔</td>
<td>
✔
</td>
<td>✔</td>
<td>
✔</td>
</tr>
<tr>
<td>
<strong>
summon_file_dialog
</strong>
</td>
<td>
<em>
programmatically trigger file dialog
</em>
</td>
<td>
✔</td>
<td>
✘
</td>
<td>✘</td>
<td>
✘
</td>
<td>✘</td>
<td>
✔ <sup><a href="#wiki-fn_6">[6]</a></sup></td>
</tr>
<tr>
<td>
<strong>
upload_filesize
</strong>
</td>
<td>
<em>
upload file of specific size
</em>
</td>
<td>
✔</td>
<td>
✔ <sup><a href="#wiki-fn_1">[1]</a></sup></td>
<td>✔</td>
<td>
✔
</td>
<td>✔</td>
<td>
✔</td>
</tr>
 |
 |
 |
 |
||||
|---|---|---|---|---|---|---|---|
1. Only in client mode.
2. Only if browser environment has FileReader and support for Canvas node or dataUrl as a source for Image node.
3. Useful addition to W3C Spec, although currently implemented only in Chrome.
4. All status codes available in client mode, browser mode reports only 200 and 404.
5. Only 200 and 404.
6. Smooth report available only in browser mode, in client mode it is faked.
7. In browser mode - text, json, document. In client mode - additionally blob.
8. Direct upload, without preloading in memory is only possible in client mode.
| Capability | Browser Mode | Client Mode |
|---|---|---|
| access_binary | ✔ | ✘ |
| access_image_binary | ✔ | ✘ |
| resize_image | ✔ | ✘ |
| report_upload_progress | ✔ [1] | ✔ |
| return_response_headers | ✔ | ✘ |
| return_status_code | ✔ | ✔ [2] |
| send_custom_headers | ✔ | ✘ |
| send_binary_string | ✔ | ✘ |
| send_browser_cookies | ✔ | ✘ |
| send_multipart | ✔ | ✔ |
| slice_blob | ✔ | ✘ |
| stream_upload | ✘ | ✔ |
| upload_filesize | ✔ [3] | ✔ |
1. We interpolate the progress feedback from the time it took the previous file to upload.
2. Only 200 and 404.
3. This is probably the only real drawback (but - huge!) of browser mode in Flash. Since the whole file must be loaded in memory first, it is not really applicable for files bigger than 200mb.