1/* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
2/* vim: set ts=8 sts=2 et sw=2 tw=80: */
3/* This Source Code Form is subject to the terms of the Mozilla Public
4 * License, v. 2.0. If a copy of the MPL was not distributed with this
5 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
6
7#include "nsISupports.idl"
8
9%{C++
10#include "nsDependentString.h"
11#include <stdio.h>
12%}
13
14interface nsIFile;
15[ptr] native FILE(FILE);
16
17/**
18 * A simple interface for writing to a .gz file.
19 *
20 * Note that the file that this interface produces has a different format than
21 * what you'd get if you compressed your data as a gzip stream and dumped the
22 * result to a file.
23 *
24 * The standard gunzip tool cannot decompress a raw gzip stream, but can handle
25 * the files produced by this interface.
26 */
27[scriptable, uuid(6bd5642c-1b90-4499-ba4b-199f27efaba5)]
28interface nsIGZFileWriter : nsISupports
29{
30  /**
31   * Initialize this object.  We'll write our gzip'ed data to the given file,
32   * overwriting its contents if the file exists.
33   *
34   * init() will return an error if called twice.  It's an error to call any
35   * other method on this interface without first calling init().
36   */
37  [must_use] void init(in nsIFile file);
38
39  /**
40   * Alternate version of init() for use when the file is already opened;
41   * e.g., with a FileDescriptor passed over IPC.
42   */
43  [noscript, must_use] void initANSIFileDesc(in FILE file);
44
45  /**
46   * Write the given string to the file.
47   */
48  [must_use] void write(in AUTF8String str);
49
50  /*
51   * The following two overloads of Write() are C++ because we can't overload
52   * methods in XPIDL.  Anyway, they don't add much functionality for JS
53   * callers.
54   */
55  %{C++
56  /**
57   * Write the given char* to the file (not including the null-terminator).
58   */
59  [[nodiscard]] nsresult Write(const char* str)
60  {
61    return Write(str, strlen(str));
62  }
63
64  /**
65   * Write |length| bytes of |str| to the file.
66   */
67  [[nodiscard]] nsresult Write(const char* str, uint32_t len)
68  {
69    return Write(nsDependentCSubstring(str, len));
70  }
71  %}
72
73  /**
74   * Close this nsIGZFileWriter.  Classes implementing nsIGZFileWriter will run
75   * this method when the underlying object is destroyed, so it's not strictly
76   * necessary to explicitly call it from your code.
77   *
78   * It's an error to call this method twice, and it's an error to call write()
79   * after finish() has been called.
80   */
81  void finish();
82};
83