1. HTML5/Flash Uploader 8.5.81
  2. HTML5/Flash Uploader
  3. Using HTML5/Flash Uploader

Configuring Restriction Rules for Files

Supported technologies: Adobe FlashHTML 5

This article contains information on the application of various restrictions, such as:

to the files that are selecting for the upload to your server. These restriction rules can be specified using the RestrictionsRestrictions (ASP.NET)Restrictions (PHP)restrictions (JavaScript) class.

Note

All the limitations specified with Restrictions are checked client-side, so you should not interpret them as a reliable protection. A potentially malicious user can bypass all these limitations (by emulating Flash Uploader). This is why it is highly recommended to implement server-side verification of uploaded files in addition to Restrictions properties.

In other words, all the limitation features discussed in this topic should be used solely user's convenience. They should not be interpreted as a serious protection measure from malicious users.

Filtering Files by Extensions

Usually it makes sense to allow to upload only certain kinds of files. For example, if you use Flash Uploader to:

  • gather photo print orders, you would prefer to show only JPEG files
  • upload web graphics, you would show GIF and PNG files as well
  • send documents to a storage, you would disable all the images and allow uploading only PDF files

To specify file type limitations, use the Restrictions.FileMaskFileMask (ASP.NET)FileMask (PHP)fileMask (JavaScript) property. This property accepts an array of filters each consists of the description string and file mask. The description is displayed in the Files of type drop-down list and the file mask is applied onto the files in the currently selected folder.

The Restrictions.FileMask property support the following wildcards:

  • asterisk (*) for arbitrary substring
  • question mark (?) for single arbitrary character

Here are few examples of file masks:

  • *.jpg for files which have the .jpg extension (most JPEG files)
  • *. for all files without an extension
  • * for all files no matter if they have an extension or not
  • *.* for all the files which have any extension
  • *.doc;*.xls for files which have either .doc or .xls extension (Microsoft Office files)
  • *.mp? for most MPEG audio files (.mp3, .mp2, .mpa, .mp+ and etc)

When the user clicks the Add Files button a standard Open File dialog is shown. Files allowed for upload from client-side can be filtered using Files of type drop-down list. Description of each filter specified via the FileMask will appear in the Files of type in this drop-down list. The order of these filters corresponds to the order in which they were specified by the FileMask property. By default, no filter applied and Flash Uploader displays all files in the currently selected folder.

Sometimes instead of specifying a list of files you want to accept, you may want to specify a list of extensions you would like to avoid. In this case, you should use the Restrictions.DeniedFileMaskDeniedFileMask (ASP.NET)DeniedFileMask (PHP)deniedFileMask (JavaScript) property. It does not affect the Open File dialog, however it does not let matching files to appear in the upload list.

Important

The Restrictions.FileMask property allows infiltrating files only by their extensions. Though it cannot guarantee that files, say, with the .jpg extension are JPEG files indeed. A malicious user can rename executable files to .jpg and upload them as if they are images. That is why if an application Flash Uploader is integrated with has increased security requirements, it is highly recommended to verify uploaded files on the server side.

The code sample below demonstrates how to set three filtering options, namely, Images, Documents, and All files.

ASP.NET
<aur:ImageUploaderFlash ID="Uploader1" runat="server">
    <Restrictions FileMask=
        "[['Images (*.jpg; *.jpeg; *.png; *.gif; *.bmp)', '*.jpg;*.jpeg;*.png;*.gif;*.bmp'], 
          ['Documents (*.txt;*.rtf;*.pdf;*.doc;*.docx;*.xls;*.xlsx)', '*.txt;*.rtf;*.pdf;*.doc;*.docx;*.xls;*.xlsx'], 
          ['All files (*.*)', '*.*']]"
    />
</aur:ImageUploaderFlash>
PHP
$uploader = new ImageUploaderFlash("Uploader1");

$uploader->getRestrictions()->setFileMask(
    "[['Images (*.jpg; *.jpeg; *.png; *.gif; *.bmp)', '*.jpg;*.jpeg;*.png;*.gif;*.bmp'], 
      ['Documents (*.txt;*.rtf;*.pdf;*.doc;*.docx;*.xls;*.xlsx)', '*.txt;*.rtf;*.pdf;*.doc;*.docx;*.xls;*.xlsx'], 
      ['All files (*.*)', '*.*']]"
);
JavaScript
var fu = $au.imageUploaderFlash({
    id: 'Uploader1',
    restrictions{
        fileMask: [
            ['Images (*.jpg; *.jpeg; *.png; *.gif; *.bmp)', '*.jpg;*.jpeg;*.png;*.gif;*.bmp'], 
            ['Documents (*.txt;*.rtf;*.pdf;*.doc;*.docx;*.xls;*.xlsx)', '*.txt;*.rtf;*.pdf;*.doc;*.docx;*.xls;*.xlsx'], 
            ['All files (*.*)', '*.*']]}
});

Restricting Image Dimensions

When you use Flash Uploader to upload images (rather than common files) to your Web site, you may desire to limit dimensions of these images. For example, if you provide photo blog hosting, usually it makes no sense to accept the files that are too large (which are larger than, say, 800x600). To restrict image dimensions the Restrictions class exposes the following properties:

Note

You may want to resize the images which are too large instead of prohibiting them. See the Configuring Files to be Uploaded in HTML5/Flash Uploader topic for more information.

Important

Enabling image dimension restrictions can significantly downsize number of images which can be selected for upload. It means that if, for example, a user selects 200 images and only 50 of them meet image dimension restrictions, but the user cannot select more images because Adobe Flash Player memory limit is reached. This behaviour is caused by Adobe Flash Player architecture which requires to load whole image files in memory to extract information about image size. Adobe Flash does not support unloading files from memory that leads to "out of memory" issues. In other words, if your web application requires checking image dimensions on client side, consider applying limitation on maximum number of files avialable for upload per one upload session.

If one of these restrictions is exceeded, Flash Uploader will not allow to add "wrong" images to the upload list. Error message specified with the DimensionsTooLargeDimensionsTooLarge (ASP.NET)DimensionsTooLarge (PHP)dimensionsTooLarge (JavaScript) or DimensionsTooSmallDimensionsTooSmall (ASP.NET)DimensionsTooSmall (PHP)dimensionsTooSmall (JavaScript) property will be displayed.

JavaScript
var fu = $au.imageUploaderFlash({
    id: 'Uploader1',
    restrictions{
        minImageWidth: 800, minImageHeight: 600,
        maxImageWidth: 1600, maxImageHeight: 1200}
    messages{
        dimensionsTooLarge: 'Image dimesions should be smaller than 1600x1200 pixels.',
        dimensionsTooSmall: 'Image dimesions should be larger than 800x600 pixels.'}
});
ASP.NET
<aur:ImageUploaderFlash ID="Uploader1" runat="server">
    <Restrictions MinImageWidth="800" MinImageHeight="600"
                  MaxImageWidth="1600" MaxImageHeight="1200" />
    <Messages DimensionsTooLarge="Image dimesions should be smaller than 1600x1200 pixels."
              DimensionsTooSmall="Image dimesions should be larger than 800x600 pixels." />
</aur:ImageUploaderFlash>
PHP
$uploader = new ImageUploaderFlash("Uploader1");
        
$uploader->getRestrictions()->setMinImageWidth(800);
$uploader->getRestrictions()->setMinImageHeight(600);
$uploader->getRestrictions()->setMaxImageWidth(1600);
$uploader->getRestrictions()->setMaxImageHeight(1200);
$uploader->getMessages()->setDimensionsTooLarge("Image dimesions should be smaller than 1600x1200 pixels.");
$uploader->getMessages()->setDimensionsTooSmall("Image dimesions should be larger than 800x600 pixels.");

Restricting Size and Number of Files

Flash Uploader allows not only filtering files by type or restricting images, but also limiting size and count of files. It is extremely useful when you:

  • want to allocate limited space on your server for users
  • provide file hosting service, which does not allow uploading large files

Restricting Number of Files

Note

Flash Uploader Express restricts the maximum number of user-selected files to 100. See the Upload Suite Editions topic for details.

To limit the maximum and minimum number of files allowed for the upload in a single upload session, use the Restrictions.MinFileCountMinFileCount (ASP.NET)MinFileCount (PHP)minFileCount (JavaScript) and Restrictions.MaxFileCountMaxFileCount (ASP.NET)MaxFileCount (PHP)maxFileCount (JavaScript) properties respectively. If a user adds more files than specified by the MaxFileCount property, an error message (which can be customized using the Messages.MaxFileCountExceededMaxFileCountExceeded (ASP.NET)MaxFileCountExceeded (PHP)maxFileCountExceeded (JavaScript) property) appears. If a user adds fewer files than the MinFileCount property value and clicks Send, an error message specified with the Messages.TooFewFilesTooFewFiles (ASP.NET)TooFewFiles (PHP)tooFewFiles (JavaScript) property will be shown.

To remove these limitations, set the MaxFileCount property to 0 and MinFileCount to 1.

JavaScript
var fu = $au.imageUploaderFlash({
    id: 'Uploader1',
    restrictions: {minFileCount: 3, maxFileCount: 10},    
    messages: { tooFewFiles: 'You can add not less than 3 files.',
    maxFileCountExceeded: 'You can add not more than 10 files.'}
});
ASP.NET
<aur:ImageUploaderFlash ID="Uploader1" runat="server">
    <Restrictions MinFileCount="3" MaxFileCount="10" />
    <Messages TooFewFiles = "You can add not less than 3 files."
              MaxFileCountExceeded = "You can add not more than 10 files." />
</aur:ImageUploaderFlash>
PHP
$uploader = new ImageUploaderFlash("Uploader1");

$uploader->getRestrictions()->setMinFileCount(3);
$uploader->getRestrictions()->setMaxFileCount(10);
$uploader->getMessages()->setTooFewFiles("You can add not less than 3 files.");
$uploader->getMessages()->setMaxFileCountExceeded("You can add not more than 10 files.");

Restricting Upload Size

To set a limit on a total size of files added to the upload list, Flash Uploader exposes the Restrictions.MaxTotalFileSizeMaxTotalFileSize (ASP.NET)MaxTotalFileSize (PHP)maxTotalFileSize (JavaScript) property. When the sum of file sizes exceeds this value, an error specified with the Messages.MaxTotalFileSizeExceededMaxTotalFileSizeExceeded (ASP.NET)MaxTotalFileSizeExceeded (PHP)maxTotalFileSizeExceeded (JavaScript) property is displayed.

If you do not need to restrict the total file size, set MaxTotalFileSize to 0.

This limitation is applied to sizes of original files only. It does not take into account sizes of files created by Flash Uploader from original ones (downsized copies of images, associated icons, compressed ZIP files) because there is no way to know their sizes before upload process starts. Therefore, the amount of the actually uploaded bytes may noticeably differ from this value. So, the Restrictions.MaxTotalFileSize property is useful when you upload original files without applying any client-side file transformations. Otherwise, if it is important to limit the POST request size, the only way is to configure maximum acceptable POST request length in the server settings.

ASP.NET
<aur:ImageUploaderFlash ID="Uploader1" runat="server">
    <Restrictions MaxTotalFileSize="104857600" />
    <Messages MaxTotalFileSizeExceeded="You are not allowed for uploading more than 100 MB." />
</aur:ImageUploaderFlash>
PHP
$uploader = new ImageUploaderFlash("Uploader1");
        
$uploader->getRestrictions()->setMaxTotalFileSize(104857600);
$uploader->getMessages()->setMaxTotalFileSizeExceeded("You are not allowed for uploading more than 100 MB.");
JavaScript
var fu = $au.imageUploaderFlash({
    id: 'Uploader1',
    restrictions: {maxTotalFileSize: 104857600},    
    messages: {maxTotalFileSizeExceeded: 'You are not allowed for uploading more than 100 MB.'}
});

Restricting Single File Size

You can set a limitation not only for total size of files added to the upload list, but also for a single file size. Both minimum and maximum limits can be specified with the Restrictions.MinFileSizeMinFileSize (ASP.NET)MinFileSize (PHP)minFileSize (JavaScript) and Restrictions.MaxFileSizeMaxFileSize (ASP.NET)MaxFileSize (PHP)maxFileSize (JavaScript) properties respectively. Files which are too large or too small cannot be added to the upload list. If a user tries to add such file an error message specified with the Messages.FileSizeTooSmallFileSizeTooSmall (ASP.NET)FileSizeTooSmall (PHP)fileSizeTooSmall (JavaScript) or Messages.MaxFileSizeExceededMaxFileSizeExceeded (ASP.NET)MaxFileSizeExceeded (PHP)maxFileSizeExceeded (JavaScript) property will be displayed.

Both these properties should be set to 0 when no file size limitations are required.

In the following example files smaller than 200 Kb or larger than 2 Mb are denied:

JavaScript
var fu = $au.imageUploaderFlash({
    id: 'Uploader1',
    restrictions: {minFileSize: 204800, maxFileSize: 2097152},    
    messages: {fileSizeTooSmall: 'You can add files not smaller than 200 KB.',
    maxFileSizeExceeded: 'You can add files not larger than 2 MB.'}
});
ASP.NET
<aur:ImageUploaderFlash ID="Uploader1" runat="server">
    <Restrictions MinFileSize="204800" MaxFileSize="2097152" />
    <Messages FileSizeTooSmall="You can add files not smaller than 200 KB."
              MaxFileSizeExceeded="You can add files not larger than 2 MB." />
</aur:ImageUploaderFlash>
PHP
$uploader = new ImageUploaderFlash("Uploader1");
        
$uploader->getRestrictions()->setMinFileSize(204800);
$uploader->getRestrictions()->setMaxFileSize(2097152);
$uploader->getMessages()->setFileSizeTooSmall("You can add files not smaller than 200 KB.");
$uploader->getMessages()->setMaxFileSizeExceeded("You can add files not larger than 2 MB.");

See Also

Reference