wx.Archive.ZipResource Class Reference

List of all members.

Public Member Functions

FSFile FindResourceFile (string resourceName)
 This is the main service of instances: Return a stream on the resource described by a local path name representation.
override string ToString ()

Static Public Member Functions

static void AddCatalogLookupPrefix (string prefix)
static Stream FindResource (string archiveName, string resourceName, string canonicalName)
static Stream FindResource (string archiveName, string resourceName)
static Stream FindResource (Assembly callingAssembly, string archiveName, string resourceName)
static FSFile FindResourceFile (string archiveName, string resourceName, string canonicalName)
static FSFile FindResourceFile (string archiveName, string resourceName)
static string[] GetDerivatedArchiveNames (string archiveName, string canonicalName)
static string[] GetDerivatedArchiveNames (string archiveName)
static string[] GetDerivatedResourceNames (string resourceName, string canonicalName)
static string[] GetDerivatedResourceNames (string archiveName)
static FSFile ResourceFileAppropriateType (string archiveName, string resourceName)
static FSFile ResourceFileCanSeek (string archiveName, string resourceName)

Properties

bool IsArchive [get]
 If this is an archive.
bool IsDir [get]
 If this is a directory.
bool IsEmpty [get]
 Archive has not been found.
static ZipResource LastFoundArchive [get]
static string LastFoundArchiveName [get]
static string LastFoundResourceName [get]
static string LastSearchedArchiveName [get]

Classes

class  KeyArchiveName


Detailed Description

An ArchiveInput used as a resource provider.

Refer also to ZipRC as help file compiler.

C# has a nice native resource system that only has two drawbacks: Support for internationalization is less productive than the classical gettext procedure and the visual development environment supports things like images as resources only within Forms.

This class is meant as a very simple alternative. It cannot be used to retrieve resources that have been linked into the application itself but it can serve as a replacement for satellite assemblies.

Call FindResource() or FindResourceFile() to get a stream or a FSFile descriptor for accessing the content of a resource. These resource may either be simply files within a certain directory, zipped directories, or resources embedded into the manufest.

Resources may be stored in different types of streams, either ZIP files, System.IO file streams, or memory streams. Unfortunately, these types of streams differ with respect to some characteristics that are used within wxWidgets. Namely, especially the image handler presuppose streams as data source that can seek. ZipResource is prepared to deal with this if you use the methods ResourceFileCanSeek() and ResourceFileAppropriateType(). Refer to the remarks on these methods for details. ResourceFileAppropriateType() forms the basis of the zrs:// file system protocol according to IOStreamFSHandler.

This class maintains a collection of archive files resp. instances of ArchiveEntry that will be used for loading resources. Users of the class provide a resource name an archive name. If not already analysed, the archive will be loaded and a stream on the resource contents will be returned. Refer to FindResource() for details. The main service of this class is to amend names of resources and archives with the canonical name of the current locale. So, this class enables locale specific provision of resources.

Resource archives will be found in the codebase path of the calling assembly, subdirectory "zrs" or a subdirectory named with the canonical name of the current locale.

You may also use directories instead of archives.

Whenever a resource cannot be found in files, the manifest will be searched.

What is loaded: A resource will be loaded on FindResource(archiveName, resourceName) or FindResource(archiveName, resourceName, canonicalLocaleName), where

Resources will be preferably loaded from the resource system (a zipped resource file added to the assembly by csc.exe option /resource) and then from the local file system.

A missing locale name will be loaded from wx.Locale.

The method does not directly search for provided filenames for archive and resource but produce derivated filenames for both using the canonical name of the locale as a parameter. Possible locations of the archive also reflect prefixes as added by method AddCatalogLookupPrefix(). The code base directory of the calling assembly will also be considered as a prefix path.

For each prefix, a file directory/archive.zrs for locale "de_DE" will be loaded as one of the following files (referring to the order as given below):

Motivation: All path names including the name of a locale will be searched first. So, systems can overload a neutrally localized resources by localized resources. The two final paths the neutral paths (with respect to localization). When asking for the neutral resource (example: FindResource(archiveName, resourceName, "")) only these two path names will be searched.

The locale can ne specified within the path as well as within the filename. The latter form may be used to avoid the effect that the usage of a particular file (as a localized resource) depends only on its position in the directory tree.

Directory name zrs is used as a standard amendment to the prefix. Reason: Usually, the code base of the calling assembly will be the only prefix. This is typically a Bin directory already crowded with lots of files required on running the program. A system designer may use a sub-directory zrs without any changes to the code to prevent the files on resources to additionally appear directly in this directory.

Note, that each resource archive may also contain the same resource in several localizations, because also a resourceName like "rdirectory/resource" is used to produce derivations.

The used derivation scheme may change from locale to locale. Lets assume for instance, that locale "en" has been found in archive directory/archive.zrs in file entry rdirectory/en/resource. The Germen localization may be shipped as another file resource_de.zrs containing entry rdirectory/resource. Both resources will be found although the English version of the resource has been added to the neutral archive whereas the German version is in a perticularly localized archive.

A ZipResource file may be compiled and analyzed by program ZipRC.exe (refer to directory Utils). Call ZipRC.exe -h on a CMD.exe console to get information on using this program.

    C:\\wx.NET\\Bin> ZipRC.exe -h
    ZipRC 0.7.3 (c) 2006 wx.NET Team
    Generate ZIP archived resources .zrs.
    Synopsis: ZipRC.exe (compile | c | extract | e | verify | v) ARCHIVE_FILE {--help | -h | --CANONICAL_NAME | FILE | RCNAME=FILE}*
    compile/c: Compile archive file ARCHIVE_FILE
    extract/e: Extract files from ARCHIVE_FILE
    info/i: Information ARCHIVE_FILE and the specified files (search paths, comparison)
    --help/-h: PrintData this information.
    --CANONCAL_NAME e.g. --en|--de_DE: switch to the specified locale.
    FILE: compile or extract this file.
    RCFILE=FILE: compile FILE as RCFILE or extract RCFILE to FILE.
    

Example: The current working directory contains the files logo2.png, editDocGroups.html, and editDocGroups_de.html where the last file is a German translation of the second one whereas the icon logo2.png is neutral (with repsect to localization).

     ZipRC c test.zip wxnetlogo.png=logo2.png editDocGroups.html --de editDocGroups_de.html
     
generates a ZIP archive test.zip. This archive contains wxnetlogo.png (a copy of the original file logo2.png) and editDocGroups.html in its root and editDocGroups_de.html in sub-directory de. This is to indicate that the latter HTML file is a German translation whereas the other files are considered neutral with respect to localization.

The more interesting thing about ZipResource is of course reading the resource. The application knows command extract to decompress the content. However, the application also knows command verify to investigate the structure of a compiled archive and compare the content with uncompressed files (for instance the original sources). Back to the example:

     ZipRC v test.zip wxnetlogo.png=logo2.png editDocGroups.html --de editDocGroups_de.html
     
produces the following output:
ZipRC 0.7.3 (c) 2006 wx.NET Team
1/4: Candidate test.zip existing as file containing:
   1: "wxnetlogo.png"<=>"wxnetlogo.png"
        28.10.2006 19:18:54 size 5215
   2: "editDocGroups.html"<=>"editDocGroups.html"
        28.10.2006 19:18:54 size 548
   3: "de/editDocGroups_de.html"<=>"deditDocGroups_de.html"
        28.10.2006 19:18:54 size 727
2/4: Candidate zrs\test.zip is unknown.
3/4: Candidate file:\C:\sf\wx.NET\Bin\test.zip is unknown.
4/4: Candidate file:\C:\sf\wx.NET\Bin\zrs\test.zip is unknown.
    
The specified filename test.zip matches with archive file test.zip containing the listed files (with their local and internal names). The program has not been able to find archives corresponding to the rest of the derivated file names.
Looking for resource wxnetlogo.png <=> file logo2.png, locale neutral in test.zip.
Derivations of the resource name:
1. wxnetlogo.png
Found in test.zip as wxnetlogo.png
Both files share the same content.
    
File logo2.png has been found on the file system and has been successfully compared to wxnetlogo.png from the archive.
Looking for resource editDocGroups.html <=> file editDocGroups.html, locale neutral in test.zip.
Derivations of the resource name:
1. editDocGroups.html
Found in test.zip as editDocGroups.html
Both files share the same content.
    
editDocGroups.html has also been found and compared.
Archive test.zip will be searched with locale <de> as:
1/16: 1. file:\C:\sf\wx.NET\Bin\de\test.zip has not been found.
2/16: 2. file:\C:\sf\wx.NET\Bin\zrs\test_de.zip has not been found.
3/16: 3. file:\C:\sf\wx.NET\Bin\zrs\de\test.zip has not been found.
4/16: 4. file:\C:\sf\wx.NET\Bin\zrs\de\test_de.zip has not been found.
5/16: 5. zrs\test_de.zip has not been found.
6/16: 6. test_de.zip has not been found.
7/16: 7. de\test_de.zip has not been found.
8/16: 8. zrs\de\test_de.zip has not been found.
9/16: 9. file:\C:\sf\wx.NET\Bin\test_de.zip has not been found.
10/16: 10. zrs\de\test.zip has not been found.
11/16: 11. de\test.zip has not been found.
12/16: 12. file:\C:\sf\wx.NET\Bin\de\test_de.zip has not been found.
13/16: 13. test.zip is an existing file containing:
   1: "wxnetlogo.png"<=>"wxnetlogo.png"
        28.10.2006 19:18:54 size 5215
   2: "editDocGroups.html"<=>"editDocGroups.html"
        28.10.2006 19:18:54 size 548
   3: "de/editDocGroups_de.html"<=>"deditDocGroups_de.html"
        28.10.2006 19:18:54 size 727
14/16: 14. zrs\test.zip has not been found.
15/16: 15. file:\C:\sf\wx.NET\Bin\test.zip has not been found.
16/16: 16. file:\C:\sf\wx.NET\Bin\zrs\test.zip has not been found.
    
Switch to locale de. The program lists all derivated file names of test.zip and the contents of the archives found on the file system.
Looking for resource editDocGroups_de.html <=> file editDocGroups_de.html, local
e de in test.zip.
Derivations of the resource name:
1. editDocGroups_de.html
2. \deditDocGroups_de.html
Found in test.zip as \deditDocGroups_de.html
Both files share the same content.
    
Finally, the derivated resource names of editDocGroups_de.html are listed. One of these derivations
 .html 
can be found in test.zip. Both files have the same content.

Note, that also directories can be treated as resources. Compiled resources are important for deployment, not development. So, class ZipResource treats directories the same way as archive files. Reconsider the verifier of program ZipRC. This time we will call this directly with the working directory as archived source.

    ZipRC v . wxnetlogo.png=logo2.png editDocGroups.html --de editDocGroups_de.html
This produces the following output:
ZipRC 0.7.3 (c) 2006 wx.NET Team
1/8: Candidate . exists as directory.
2/8: Candidate zrs\.zrs is unknown.
3/8: Candidate .zrs is unknown.
4/8: Candidate file:\C:\sf\wx.NET\Bin\ is unknown.
5/8: Candidate zrs\ is unknown.
6/8: Candidate file:\C:\sf\wx.NET\Bin\.zrs is unknown.
7/8: Candidate file:\C:\sf\wx.NET\Bin\zrs\.zrs is unknown.
8/8: Candidate file:\C:\sf\wx.NET\Bin\zrs\ is unknown.

Looking for resource wxnetlogo.png <=> file <logo2.png>, locale neutral in <.>.
Derivations of the resource name:
1. wxnetlogo.png
Cannot open resource <wxnetlogo.png> in <.>.
    
The program searches derivated archive names and recognizes "." to denote a directory. The command line specified that source logo2.png has been renamed to wxnetlogo.png in the resource file. However, since "." is exactly the directory of the sources, logo2.png appears here with its original name so wxnetlogo.png cannot be found.
Looking for resource editDocGroups.html <=> file <editDocGroups.html>, locale neutral in <.>.
Derivations of the resource name:
1. editDocGroups.html
Found in <.> as <editDocGroups.html>
Directory as resource and reference refer to the same file C:\sf\wx.NET\Utils\Zi
pRCditDocGroups.html.
    
In contrast, the program has been able to find editdocGroups.html since the command line didn't specify a renaming scheme here.
Archive . will be searched with locale <de> as:
1/32: 1. file:\C:\sf\wx.NET\Bin\de\.zrs has not been found.
2/32: 2. zrs\de\_de.zrs has not been found.
3/32: 3. file:\C:\sf\wx.NET\Bin\zrs\de\.zrs has not been found.
4/32: 4. file:\C:\sf\wx.NET\Bin\de\_de has not been found.
5/32: 5. file:\C:\sf\wx.NET\Bin\zrs\_de.zrs has not been found.
6/32: 6. zrs\_de.zrs has not been found.
7/32: 7. file:\C:\sf\wx.NET\Bin\zrs\_de has not been found.
8/32: 8. de\_de has not been found.
9/32: 9. zrs\de\.zrs has not been found.
10/32: 10. zrs\_de has not been found.
11/32: 11. zrs\de\_de has not been found.
12/32: 12. file:\C:\sf\wx.NET\Bin\de\_de.zrs has not been found.
13/32: 13. file:\C:\sf\wx.NET\Bin\_de.zrs has not been found.
14/32: 14. file:\C:\sf\wx.NET\Bin\zrs\de\ has not been found.
15/32: 15. file:\C:\sf\wx.NET\Bin\de\ has not been found.
16/32: 16. de\.zrs has not been found.
17/32: 17. zrs\de\ has not been found.
18/32: 18. file:\C:\sf\wx.NET\Bin\zrs\de\_de has not been found.
19/32: 19. _de has not been found.
20/32: 20. de\_de.zrs has not been found.
21/32: 21. _de.zrs has not been found.
22/32: 22. file:\C:\sf\wx.NET\Bin\_de has not been found.
23/32: 23. de\ has not been found.
24/32: 24. file:\C:\sf\wx.NET\Bin\zrs\de\_de.zrs has not been found.
25/32: 25. . is an existing directory.
26/32: 26. zrs\.zrs has not been found.
27/32: 27. .zrs has not been found.
28/32: 28. file:\C:\sf\wx.NET\Bin\ has not been found.
29/32: 29. zrs\ has not been found.
30/32: 30. file:\C:\sf\wx.NET\Bin\.zrs has not been found.
31/32: 31. file:\C:\sf\wx.NET\Bin\zrs\.zrs has not been found.
32/32: 32. file:\C:\sf\wx.NET\Bin\zrs\ has not been found.

Looking for resource editDocGroups_de.html <=> file <editDocGroups_de.html>, loc
ale de in <.>.
Derivations of the resource name:
1. editDocGroups_de.html
2. editDocGroups_de.html
Found in <.> as <editDocGroups_de.html>
Directory as resource and reference refer to the same file C:\sf\wx.NET\Utils\Zi
pRCditDocGroups_de.html.
     
Finally, also the localized HTML-text has been found. Please note, that the compressed archive booked this file in a subdirectory directory for locale de whereas "." is of a flat structure.

Motivation: Assume you develop an application "app.exe" involving several resource. During development you want direct access to these resources in order to modify them. So, you will probably check in a subdirectory app (or another name) containing all resources. However, you will use ZipRC to compile file "app.zrs" containing all resources. This file will be shiped with the executable code. The interesting thing is, that both configurations of resources can be accessd by the same program code using ZipResource.


Member Function Documentation

static void wx.Archive.ZipResource.AddCatalogLookupPrefix ( string  prefix  )  [static]

Add a prefix to be lookup path for loading archives with resources. Similar to wx.Locale.AddCatalogLookupPrefix(). The message catalog files will be looked up under prefix/LANG/zrs, prefix/LANG, and prefix (in this order) where LANG is the canonical name of a locale.

prefix will be expanded using the code base path of the calling assembly if necessary. So, the meaning of prefix never relies on the CWD but always on the position of the assemblies.

This only applies to subsequent instance creations.

static Stream wx.Archive.ZipResource.FindResource ( string  archiveName,
string  resourceName,
string  canonicalName 
) [static]

Finds a stream containing a resource of the provided name suitable for the specified locale from the provided archive.

Parameters:
archiveName is a filename describing the archive where the resource has been compiled in. This may also be the name of a resource. This method will generate derivates from this name as described below.
resourceName is a native filename (according to the conventions of class Path) describing the resource. This method will generate derivates from this name as described below.
canonicalName is the canonical name of the locale that the required resource has to comply with. If a locale specific resource cannot be found, the method will load a neutral version. If this is null or empty, this method will immediately search for a neutral resource.
If the resources cannot be found, the manifest of the calling assembly will be searched.

This method will return a null if the desired resource cannot be find.

static Stream wx.Archive.ZipResource.FindResource ( string  archiveName,
string  resourceName 
) [static]

Finds a stream containing a resource of the provided name from the provided archive. Refer to FindResource(string, string, string) for details.

Non-rooted paths will be rooted with reference to the code base of the calling assembly.

static Stream wx.Archive.ZipResource.FindResource ( Assembly  callingAssembly,
string  archiveName,
string  resourceName 
) [static]

Finds a stream containing a resource of the provided name from the provided archive. Refer to FindResource(string, string, string) for details.

Non-rooted paths will be rooted with reference to the code base of callingAssembly.

static FSFile wx.Archive.ZipResource.FindResourceFile ( string  archiveName,
string  resourceName,
string  canonicalName 
) [static]

Finds a FSFile instance containing a resource of the provided name from the provided archive of a provided locale (culture). Refer to FindResource(string, string, string) for details.

static FSFile wx.Archive.ZipResource.FindResourceFile ( string  archiveName,
string  resourceName 
) [static]

Finds a FSFile instance containing a resource of the provided name from the provided archive. Refer to FindResource(string, string, string) for details.

FSFile wx.Archive.ZipResource.FindResourceFile ( string  resourceName  ) 

This is the main service of instances: Return a stream on the resource described by a local path name representation.

Result is null if nothing has been found.

static string [] wx.Archive.ZipResource.GetDerivatedArchiveNames ( string  archiveName,
string  canonicalName 
) [static]

Returns the file names derivated from archiveName assuming the locale canonicalName. Use the empty string to denote the neutral locale.

static string [] wx.Archive.ZipResource.GetDerivatedArchiveNames ( string  archiveName  )  [static]

Returns the file names derivated from archiveName of the current wx.Locale.

static string [] wx.Archive.ZipResource.GetDerivatedResourceNames ( string  resourceName,
string  canonicalName 
) [static]

Returns the resource names derivated from resourceName assuming locale canonicalName. Use the empty string to denote the neutral locale.

static string [] wx.Archive.ZipResource.GetDerivatedResourceNames ( string  archiveName  )  [static]

Returns the resource names derivated from resourceName of the current wx.Locale.

static FSFile wx.Archive.ZipResource.ResourceFileAppropriateType ( string  archiveName,
string  resourceName 
) [static]

This method will produce a stream that can seek (cf. ResourceFileCanSeek) if this seems to be appropriate referring to the mime type. At least images need streams as data source that can seek. This method will call ResourceFile() and analyze the mime type of the result. If considered to be appropriate, the content of the resource stream will be copied into a System.IO.MemoryStream in order to get a stream that can seek positions. Refer also to ResourceFileCanSeek().

static FSFile wx.Archive.ZipResource.ResourceFileCanSeek ( string  archiveName,
string  resourceName 
) [static]

Some kinds of data, especially images, require data sources that can seek positions in the stream. This will call ResourceFile() and then, if the result cannot seek, load the source directly into a memory stream.

override string wx.Archive.ZipResource.ToString (  ) 


Property Documentation

bool wx.Archive.ZipResource.IsArchive [get]

If this is an archive.

bool wx.Archive.ZipResource.IsDir [get]

If this is a directory.

bool wx.Archive.ZipResource.IsEmpty [get]

Archive has not been found.

ZipResource wx.Archive.ZipResource.LastFoundArchive [static, get]

The last ZipResource found by FindResource().

string wx.Archive.ZipResource.LastFoundArchiveName [static, get]

The last name of a resource that has been found by FindResource(). This may be null.

string wx.Archive.ZipResource.LastFoundResourceName [static, get]

The last name of a resource that has been found by FindResource(). This may be null.

string wx.Archive.ZipResource.LastSearchedArchiveName [static, get]

The last name of a resource that has been tried to be loaded by FindResource(). This may be null.


Manual of the wx.NET   (c) 2003-2011 the wx.NET project at   Get wx.NET at SourceForge.net. Fast, secure and Free Open Source software downloads