nsIZipWriter
出典: MDC
この記事は Firefox 3 の新機能について述べています
nsIZipWriter インタフェースは、スクリプトを使ってデータを Zip ファイル形式にアーカイブできる簡単な方法を提供します。アーカイブに対する操作はひとつずつ実行することも、キューに入れておいて後で実行することもできます。
実行したい操作をすべてキューに追加したら、processQueue() を呼び出せば、キューに追加した順番通りに操作が実行されます。キューの途中で実行された操作は、オブザーバの対象外で発生したエラーもすべて例外として投げます。
バックグラウンドでキューを実行中に、インタフェースに対して同時に操作を行おうとした場合、NS_ERROR_IN_PROGRESS という例外が投げられます。
ファイル名やディレクトリ名の区切り記号には必ずスラッシュ ("/") を使い、また 1 文字目がスラッシュで始まっていてはいけません。
目次 |
nsIZipWriter は modules/libjar/zipwriter/public/nsIZipWriter.idl で定義されています。これは scriptable で
非凍結です。 (Mozilla 1.9から更新されていません)
継承元: nsISupports
実装: @mozilla.org/zipwriter;1. インスタンスを作成するには、以下のように記述します。
var zipWriter = Components.classes["@mozilla.org/zipwriter;1"]
.createInstance(Components.interfaces.nsIZipWriter);
[編集] メソッドの概要
void addDirectoryEntry(in AUTF8String aZipEntry, in PRTime aModTime, in boolean aQueue);
|
void addEntryChannel(in AUTF8SZtring aZipEntry, in PRTime aModTime, in PRInt32 aCompression, in nsIChannel aChannel, in boolean aQueue)
|
void addEntryFile(in AUTF8SZtring aZipEntry, in PRInt32 aCompression, in nsIFile aFile, in boolean aQueue)
|
void addEntryStream(in AUTF8SZtring aZipEntry, in PRTime aModTime, in PRInt32 aCompression, in nsIInputStream aStream, in boolean aQueue)
|
void close()
|
nsIZipEntry getEntry(in AUTF8String aZipEntry);
|
boolean hasEntry(in AUTF8String aZipEntry);
|
void open(in nsIFile aFile, in PRInt32 aIoFlags);
|
void processQueue(in nsIRequestObserver aObserver, in nsISupports aContext)
|
void removeEntry(in AUTF8String aZipEntry, in boolean aQueue)
|
[編集] 属性
| 属性 | 型 | 説明 |
comment
| ACString
| 開かれている Zip ファイルに関連付けられているコメントを取得あるいは設定します。開かれている Zip ファイルがない場合は、例外 NS_ERROR_NOT_INITIALIZED が投げられます。
|
inQueue
| boolean
| バックグラウンドのキューで操作が実行中の場合は true、バックグラウンド操作が実行中でない場合は false。読み取り専用。
|
file
| nsIFile
| 書き込みを行う Zip ファイル。読み取り専用。 |
[編集] 定数
| 定数 | 値 | 説明 |
COMPRESSION_NONE
| 0 | ファイルを圧縮しない。 |
COMPRESSION_FASTEST
| 1 | ファイルをアーカイブに追加する際、最速の圧縮方法を使用します。 |
COMPRESSION_DEFAULT
| 6 | ファイルをアーカイブに追加する際、標準の圧縮方法を使用します。 |
COMPRESSION_BEST
| 9 | ファイルをアーカイブに追加する際、最も圧縮率の高い圧縮方法を使用します。 |
[編集] メソッド
[編集] addDirectoryEntry()
Zip ファイルに新しいディレクトリエントリを追加します。
void addEntryDirectory( in AUTF8String aZipEntry, in PRTime aModTime, in boolean aQueue );
[編集] 引数
- aZipEntry
- Zip ファイルに追加するディレクトリエントリのパス。
- aModTime
- エントリの変更日時。ミリ秒単位。
- aQueue
- 操作をキューに追加して後で実行する場合は
true、操作を即座に実行する場合はfalse。
[編集] 投げられる例外
- NS_ERROR_NOT_INITIALIZED
- 開かれている Zip ファイルがありません。
- NS_ERROR_FILE_ALREADY_EXISTS
- 指定されたパスは既に Zip ファイルの中に存在します。
- NS_ERROR_IN_PROGRESS
- Zip Writer は他の操作を実行中です。
[編集] addEntryChannel()
チャンネルから Zip ファイルにデータを追加します。
void addEntryChannel( in AUTF8String aZipEntry, in PRTime aModTime, in PRInt32 aCompression, in nsIChannel aChannel, in boolean aQueue );
[編集] 引数
- aZipEntry
- Zip ファイルに追加するファイルエントリのパス。これは Zip ファイル内に配置されるパスになります。
- aModTime
- エントリの変更日時。ミリ秒単位。
- aCompression
- 使用する圧縮方法を表す 圧縮定数 のいずれか。
- aChannel
- データを取得するチャンネル。
- aQueue
- 操作をキューに追加して後で実行する場合は
true、操作を即座に実行する場合はfalse。
[編集] 投げられる例外
- NS_ERROR_NOT_INITIALIZED
- 開かれている Zip ファイルがありません。
- NS_ERROR_FILE_ALREADY_EXISTS
- 指定されたパスは既に Zip ファイルの中に存在します。
- NS_ERROR_IN_PROGRESS
- Zip Writer は他の操作を実行中です。
[編集] addEntryFile()
新しいファイルもしくはディレクトリを Zip ファイルに追加します。指定されたファイルがディレクトリの場合、この呼び出しは以下と同じことになります。
addDirectoryEntry(aZipEntry, aFile.lastModifiedTime, aQueue);
void addEntryFile( in AUTF8String aZipEntry, in PRInt32 aCompression, in nsIFile aFile, in boolean aQueue );
[編集] 引数
- aZipEntry
- Zip ファイルに追加するファイルエントリのパス。これは Zip ファイル内に配置されるパスになります。
- aCompression
- 使用する圧縮方法を表す 圧縮定数 のいずれか。
- aFile
- データと変更日時を取得するファイル。
- aQueue
- 操作をキューに追加して後で実行する場合は
true、操作を即座に実行する場合はfalse。
[編集] 投げられる例外
- NS_ERROR_NOT_INITIALIZED
- 開かれている Zip ファイルがありません。
- NS_ERROR_FILE_ALREADY_EXISTS
- 指定されたパスは既に Zip ファイルの中に存在します。
- NS_ERROR_IN_PROGRESS
- Zip Writer は他の操作を実行中です。
[編集] addEntryStream()
入力ストリームから Zip ファイルにデータを追加します。
void addEntryStream( in AUTF8String aZipEntry, in PRTime aModTime, in PRInt32 aCompression, in nsIInputStream aStream, in boolean aQueue );
[編集] 引数
- aZipEntry
- Zip ファイルに追加するファイルエントリのパス。これは Zip ファイル内に配置されるパスになります。
- aModTime
- エントリの変更日時。ミリ秒単位。
- aCompression
- 使用する圧縮方法を表す 圧縮定数 のいずれか。
- aStream
- データを取得する入力ストリーム。
- aQueue
- 操作をキューに追加して後で実行する場合は
true、操作を即座に実行する場合はfalse。
[編集] 投げられる例外
- NS_ERROR_NOT_INITIALIZED
- 開かれている Zip ファイルがありません。
- NS_ERROR_FILE_ALREADY_EXISTS
- 指定されたパスは既に Zip ファイルの中に存在します。
- NS_ERROR_IN_PROGRESS
- Zip Writer は他の操作を実行中です。
[編集] close()
Zip ファイルを閉じます。
void close();
[編集] 引数
なし。
[編集] 投げられる例外
- NS_ERROR_NOT_INITIALIZED
- 開かれている Zip ファイルがありません。
- NS_ERROR_IN_PROGRESS
- Zip Writer は他の操作を実行中です。
Zip ファイルの仕上げが失敗した場合、他の例外が投げられる場合もあります。
[編集] getEntry()
開かれている Zip ファイルから特定のエントリを取得します。
nsIZipEntry getEntry( in AUTF8String aZipEntry, );
[編集] 引数
- aZipEntry
- 取得するファイルエントリのパス。
[編集] 戻り値
指定したエントリについて説明した nsIZipEntry オブジェクト。あるいは、該当するエントリが存在しなかった場合 null。
[編集] hasEntry()
特定のエントリが Zip ファイル内に存在するかどうかを判別します。
boolean hasEntry( in AUTF8String aZipEntry, );
[編集] 引数
- aZipEntry
- 確認を行うファイルエントリのパス。
[編集] 戻り値
指定されたパスのエントリが Zip ファイル内に存在する場合は true、存在しない場合は false を返します。
[編集] open()
指定された Zip ファイルを開きます。
void open( in nsIFile aFile, in PRInt32 aIoFlags );
[編集] 引数
- aFile
- 開く Zip ファイル。
- aIoFlags
- prio.h で指定された、Zip ファイルのオープンフラグ。
[編集] 投げられる例外
- NS_ERROR_ALREADY_INITIALIZED
- Zip ファイルは既に開かれています。
- NS_ERROR_INVALID_ARG
- aFile 引数が null です。
- NS_ERROR_FILE_NOT_FOUND
- 指定されたファイルが見つからず、フラグでそのファイルの作成が許可されていません。または、指定されたファイルを含むディレクトリが存在しません。
- NS_ERROR_FILE_CORRUPTED
- 指定されたファイルは識別可能な Zip ファイルではありません。
ファイルが破損していた場合やサポートされていない形式だった場合など、ファイルを開くのに失敗すると、他の例外が投げられる場合もあります。
[編集] processQueue()
キュー全体の処理が完了するかエラーが発生するまで、キューに追加されたすべての項目を処理します。最初の操作が開始されたときと、最後の操作が完了したときに、オブザーバに通知が行われます。
エラーが発生した場合はすべてオブザーバに通知されます。
キューが完了するか、エラーが起きて途中までのキューの処理が中止されるまで、Zip Writer はビジー状態になります。途中までの処理に失敗した場合、残りの項目はキューに留まります。再度 processQueue() を呼び出すと、操作が中断されたところから再開されます。
void processQueue( in nsIRequestObserver aObserver, in nsISupports aContext );
[編集] 引数
- aObserver
- キューから通知を受け取るオブザーバ。
- aContext
- オブザーバに渡すコンテキスト。
[編集] 投げられる例外
- NS_ERROR_NOT_INITIALIZED
- 開かれている Zip ファイルがありません。
- NS_ERROR_IN_PROGRESS
- キューの処理は既に実行中です。
[編集] removeEntry()
Zip ファイルからエントリを削除します。
void removeEntry( in AUTF8String aZipEntry, in boolean aQueue );
[編集] 引数
- aZipEntry
- Zip ファイルから削除するエントリのパス。
- aQueue
- 削除の操作をキューに追加する場合は
true。即座に実行する場合はfalse。
[編集] 投げられる例外
- NS_ERROR_NOT_INITIALIZED
- 開かれている Zip ファイルがありません。
- NS_ERROR_IN_PROGRESS
- キューの処理は既に実行中です。
- NS_ERROR_FILE_NOT_FOUND
- 指定されたパスにエントリが存在しません。
Zip ファイルの更新に失敗した場合、他の例外が投げられる場合もあります。
[編集] 例
[編集] コメントを Zip ファイルに追加する
var zipWriter = Components.Constructor("@mozilla.org/zipwriter;1", "nsIZipWriter");
var zipW = new zipWriter();
zipW.open(myZipFilePath, PR_RDWR | PR_CREATE_FILE | PR_TRUNCATE);
zipW.comment = "This is a comment.";
zipW.close();
PR_RDWR とそれに続くオプションは、どのインタフェースにも含まれていない定数です (Bug 433295 参照)。このため、上記のコードを実際に動作させるには、以下のようなコードを追加する必要があります。
const PR_RDONLY = 0x01; const PR_WRONLY = 0x02; const PR_RDWR = 0x04; const PR_CREATE_FILE = 0x08; const PR_APPEND = 0x10; const PR_TRUNCATE = 0x20; const PR_SYNC = 0x40; const PR_EXCL = 0x80;
I/O Snippets も参照してください。
[編集] ファイルを Zip アーカイブに追加する
このコードは、nsIFile theFile で指定されたファイルを、Zip アーカイブへ同期的に追加するものです。
var zipWriter = Components.Constructor("@mozilla.org/zipwriter;1", "nsIZipWriter");
var zipW = new zipWriter();
zipW.open(myZipFilePath, PR_RDWR | PR_CREATE_FILE | PR_TRUNCATE);
zipW.addEntryFile("Path/For/This/File/In/Zip Archive", Components.interfaces.nsIZipWriter.COMPRESSION_DEFAULT, theFile, false);
zipW.close();
引数のうち nyZipFilePath は、実際にはパスではなく、新しい Zip ファイルの場所を指定する nsIFile インスタンスのことを指しています。ファイルそのものは存在していなくても構いませんが、そのファイルを含むディレクトリ (つまり nsIFile.parent) は必ず存在している必要があります。
[編集] その他の例
他の例については、ソースツリー内のユニットテストを参照してください。