UnknownCharacterFallbackConversion Property (ZipArchive)

Gets or sets the fallback character to use when converting filenames to ASCII.

Syntax

Visual Basic
C#

'Declaration
 
Public Property UnknownCharacterFallbackConversion As Byte

'Usage
 
Dim instance As ZipArchive
Dim value As Byte
 
instance.UnknownCharacterFallbackConversion = value
 
value = instance.UnknownCharacterFallbackConversion

public byte UnknownCharacterFallbackConversion {get; set;}

Property Value

A System.Byte value that represents the fallback character to use when converting filenames to ASCII. The default value is 0x3f ('?').

Remarks

This is an advanced property. It is only useful when dealing with interoperability issues with 3rd party Zip tools and Unicode characters. Unless there is a specific need, the property should be left to its default value.

The Zip format uses the IBM PC character encoding set, commonly referred to as IBM Code Page 437 to write filenames in its headers.

When writing items to archives, the component converts characters from .NET's native Unicode to the code page 437 character set.

Obviously, not all Unicode characters have a representation in the code page. Code page 437 characters are 8-bit and is made up of the ASCII character set, plus various characters and symbols common to the English and French language.

A full table of characters in the code page can be seen here.

If a Unicode characters has no representation in the code page character set, it is represented by the fallback character specified by this property.

For example, a file named "FileNameWithNonASCIIStartÀÉяテEnd.dat" will be converted to "FileNameWithNonASCIIStart?É??End.dat". If you change the property value to 0x5f (the ASCII character '_'), then the conversion would be "FileNameWithNonASCIIStart_É__End.dat".

With the advent of Unicode support in Zip archives, relying on the code page for non-ASCII has become deprecated as it was never an optimal solution in the first place. However, when creating zip archive that will be used by 3rd party tools that do not support Unicode, this property can be useful.

On Windows, the '?' character is illegal in filenames. If an item's name contains this character, some zip tools will not display or extract the item from the archive. Interoperability can be increased by setting the value of the property to a more suitable character, like '_' (0x5f).

Example

C#
VB.NET

public static void MaximumInteroperability()
{
  /* The path and filename of the zip file itself is not covered by the zip specification's
   * Unicode support. The name of the zip file is determined by your application and is
   * governed by the rules of your operating system. */
  AbstractFile zipFile = new DiskFile( "MaximumInteroperability.zip" );

  // Delete any existing zip file
  if( zipFile.Exists )
    zipFile.Delete();

  // Create a logical zip archive around the zip file
  ZipArchive zip = new ZipArchive( zipFile );

  // Disable the use of any OEM code page mandated by the local machine policy
  zip.UseLocalMachineOEMCodePageForFilenames = false;

  // Specify the '_' character for characters that can't be converted
  zip.UnknownCharacterFallbackConversion = 0x5f; // '_'

  string destinationPath;

  AbstractFile sourceFile = new DiskFile( @"D:\Components\NET40\FileSystem\Dev\Trunk\Tests\UnitTesting\Xceed.Zip.Tests\Data\TinyFile1.txt" );
  using( AutoBatchUpdate batch = new AutoBatchUpdate( zip ) )
  {
    /* We use "universal character names" like \u00C0 instead of using character
     * literals so that the code source file remains an ASCII file and can be read
     * without issue by any editor. */

    destinationPath = "FileNameWithNonASCIIStart\u00C0\u00C9\u044F\u30C6End.dat";

    ZippedFile destinationFile = ( ZippedFile ) zip.GetFile( destinationPath );
    // The string "My comment" in Japanese
    destinationFile.Comment = "\u79C1\u306E\u30B3\u30E1\u30F3\u30C8";
    sourceFile.CopyTo( destinationFile, true );

    destinationPath = "FileNameWithOEMCharsStartéàùïEnd.dat";
    destinationFile = ( ZippedFile ) zip.GetFile( destinationPath );
    sourceFile.CopyTo( destinationFile, true );
  }
}

    Public Shared Sub MaximumInteroperability()
'       The path and filename of the zip file itself is not covered by the zip specification's
'       * Unicode support. The name of the zip file is determined by your application and is
'       * governed by the rules of your operating system. 
      Dim zipFile As AbstractFile = New DiskFile("MaximumInteroperability.zip")

      ' Delete any existing zip file
      If zipFile.Exists Then
        zipFile.Delete()
      End If

      ' Create a logical zip archive around the zip file
      Dim zip As New ZipArchive(zipFile)

      ' Disable the use of any OEM code page mandated by the local machine policy
      zip.UseLocalMachineOEMCodePageForFilenames = False

      ' Specify the '_' character for characters that can't be converted
      zip.UnknownCharacterFallbackConversion = &H5f ' '_'

      Dim destinationPath As String

      Dim sourceFile As AbstractFile = New DiskFile("D:\Components\NET40\FileSystem\Dev\Trunk\Tests\UnitTesting\Xceed.Zip.Tests\Data\TinyFile1.txt")
      Using batch As New AutoBatchUpdate(zip)
'         We use "universal character names" like \u00C0 instead of using character
'         * literals so that the code source file remains an ASCII file and can be read
'         * without issue by any editor. 

        destinationPath = "FileNameWithNonASCIIStart" & ChrW(&H00C0).ToString() & ChrW(&H00C9).ToString() & ChrW(&H044F).ToString() & ChrW(&H30C6).ToString() & "End.dat"

        Dim destinationFile As ZippedFile = CType(zip.GetFile(destinationPath), ZippedFile)
        ' The string "My comment" in Japanese
        destinationFile.Comment = ChrW(&H79C1).ToString() & ChrW(&H306E).ToString() & ChrW(&H30B3).ToString() & ChrW(&H30E1).ToString() & ChrW(&H30F3).ToString() & ChrW(&H30C8).ToString()
        sourceFile.CopyTo(destinationFile, True)

        destinationPath = "FileNameWithOEMCharsStart����End.dat"
        destinationFile = CType(zip.GetFile(destinationPath), ZippedFile)
        sourceFile.CopyTo(destinationFile, True)
      End Using
    End Sub

Requirements

Target Platforms: Windows 7, Windows Vista SP1 or later, Windows XP SP3, Windows Server 2008 (Server Core not supported), Windows Server 2008 R2 (Server Core supported with SP1 or later), Windows Server 2003 SP2

Reference

ZipArchive Class
ZipArchive Members
Code Page 437 [wikipedia.org]
UseLocalMachineOEMCodePageForFilenames Property
Handling Unicode characters