michael@0: /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
michael@0: /* vim: set ts=8 sts=2 et sw=2 tw=80: */
michael@0: /* This Source Code Form is subject to the terms of the Mozilla Public
michael@0:  * License, v. 2.0. If a copy of the MPL was not distributed with this
michael@0:  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
michael@0: 
michael@0: #include "nsISupports.idl"
michael@0: 
michael@0: %{C++
michael@0: #include "nsDependentString.h"
michael@0: %}
michael@0: 
michael@0: interface nsIFile;
michael@0: 
michael@0: /**
michael@0:  * A simple interface for writing to a .gz file.
michael@0:  *
michael@0:  * Note that the file that this interface produces has a different format than
michael@0:  * what you'd get if you compressed your data as a gzip stream and dumped the
michael@0:  * result to a file.
michael@0:  *
michael@0:  * The standard gunzip tool cannot decompress a raw gzip stream, but can handle
michael@0:  * the files produced by this interface.
michael@0:  */
michael@0: [scriptable, uuid(a256f26a-c603-459e-b5a4-53b4877f2cd8)]
michael@0: interface nsIGZFileWriter : nsISupports
michael@0: {
michael@0:   /**
michael@0:    * Initialize this object.  We'll write our gzip'ed data to the given file,
michael@0:    * overwriting its contents if the file exists.
michael@0:    *
michael@0:    * init() will return an error if called twice.  It's an error to call any
michael@0:    * other method on this interface without first calling init().
michael@0:    */
michael@0:   void init(in nsIFile file);
michael@0: 
michael@0:   /**
michael@0:    * Write the given string to the file.
michael@0:    */
michael@0:   void write(in AUTF8String str);
michael@0: 
michael@0:   /*
michael@0:    * The following two overloads of Write() are C++ because we can't overload
michael@0:    * methods in XPIDL.  Anyway, they don't add much functionality for JS
michael@0:    * callers.
michael@0:    */
michael@0:   %{C++
michael@0:   /**
michael@0:    * Write the given char* to the file (not including the null-terminator).
michael@0:    */
michael@0:   nsresult Write(const char* str)
michael@0:   {
michael@0:     return Write(str, strlen(str));
michael@0:   }
michael@0: 
michael@0:   /**
michael@0:    * Write |length| bytes of |str| to the file.
michael@0:    */
michael@0:   nsresult Write(const char* str, uint32_t len)
michael@0:   {
michael@0:     return Write(nsDependentCString(str, len));
michael@0:   }
michael@0:   %}
michael@0: 
michael@0:   /**
michael@0:    * Close this nsIGZFileWriter.  Classes implementing nsIGZFileWriter will run
michael@0:    * this method when the underlying object is destroyed, so it's not strictly
michael@0:    * necessary to explicitly call it from your code.
michael@0:    *
michael@0:    * It's an error to call this method twice, and it's an error to call write()
michael@0:    * after finish() has been called.
michael@0:    */
michael@0:   void finish();
michael@0: };