SetFileZone Method

Creates or changes the security zone information for a local file.

Syntax

object.SetFileZone( LocalFile, ZoneId, [, HostUrl ])

Parameters

LocalFile

A string that specifies the name of a local file. This parameter must specify a regular file which exists on the local system and the current process must have permission to access and read from the file. If the file path includes environment variables surrounded in percent (%) symbols, the variables will be expanded. This parameter cannot be an empty string.

ZoneId

An integer which specifies the zone ID which should be assigned to the file. It may be one of the following values:

Value Description

fileZoneNone The file does not have a zone identifier associated with it.

fileZoneLocal The file is considered to be part of the local computer zone.

fileZoneIntranet The file originates from the local intranet zone, such as an internal corporate network.

fileZoneTrusted The file originates from a site in the Trusted Sites zone.

fileZoneInternet The file was downloaded from the Internet and is treated with caution by Windows.

fileZoneRestricted The file originates from a site in the Restricted Sites zone, which is used for untrusted content.

HostUrl

An optional string variable which specifies the URL used to originally download the file. If this parameter is missing or is an empty string, a URL will not be included in the security zone information.

Return Value

A value of zero is returned if the operation was successful, otherwise a non-zero error code is returned which indicates the cause of the failure.

Remarks

The SetFileZone method enables applications to set or remove the security zone identifier metadata associated with a local file. This information is stored in an alternate data stream named Zone.Identifier and is used by Windows to determine the origin and trust level of a file, potentially prompting the user with a warning before the file is opened. For more detailed information about the security zones, refer to the ZoneId property.

The file name specified by the LocalFile parameter must not reference a network location. This includes UNC paths (such as \\server\share\file.txt) and drive letters that are mapped to network shares. Security zone metadata cannot be applied to files on network volumes because the SMB protocol does not support alternate data streams. If a file with zone metadata is copied from a local NTFS drive to a network share, any associated streams like Zone.Identifier will be lost.

Specifying fileZoneNone (-1) will remove any existing zone identifier stream from the file. This has the same effect as selecting the Unblock option in the file's properties dialog in Windows Explorer. Once the stream is removed, the file will be treated as though it originated from the local computer. Note that when the Zone.Identifier stream is deleted from a file to remove its security zone information, Windows Explorer may not immediately reflect this change. This is because Explorer caches certain file metadata, including zone information used to display the "This file came from another computer" warning in the file's Properties dialog.

When assigning a zone ID, it is important to ensure that the value accurately reflects the source of the file. For files that have been downloaded from the Internet, it is strongly recommended to use fileZoneInternet. This allows Windows and other software to enforce appropriate security measures, such as requiring user confirmation before executing or opening the file.

In most scenarios, zone identifiers should only be set for files that were downloaded from untrusted or external sources. Setting an overly permissive zone (such as fileZoneLocal) for files obtained from the Internet or other potentially unsafe locations can expose users to security risks and circumvent built-in protections.

If a URL is provided via the HostUrl parameter, it will be included in the zone metadata and can be retrieved later using the GetFileZone method. This provides additional context about the origin of the file and may aid in auditing or diagnostic tasks. The URL must be a syntactically valid FTP or HTTP address and should reflect the actual location from which the file was downloaded.

Not all file systems support alternate data streams. The method will fail if used on a volume (such as FAT32) that does not support this feature. Additionally, modifying zone information may fail if the file is in use, read-only, or if the current process does not have the required permissions. It is possible to disable the creation of security zone metadata through local policy settings. In this case, the method will fail and the return value will be stErrorPolicyNoZoneInfo.

Assigning fileZoneLocal as the default security zone identifier for downloaded files is strongly discouraged. This zone disables key Windows security features and can expose users to significant risk. This security zone should only be used with files that are generated locally by the application and are guaranteed to be safe. Never assign this zone to content obtained from the Internet or other untrusted sources.

Example

The following example demonstrates how to retrieve the security zone for a local file:

Dim strHostUrl As String
Dim nError As Long

strHostUrl = "ftp://www.example.com/download/file.zip"
nError = FileTransfer1.SetFileZone(strLocalFile, fileZoneInternet, strHostUrl)
If nError > 0
    MsgBox "Unable to update the security zone information for this file"
End If

Syntax

Parameters

Return Value

Remarks

Example

See Also