gecko-dev/netwerk/base/nsIURIMutator.idl

/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

#include "nsISupports.idl"
interface nsIURI;
interface nsIObjectInputStream;

%{C++
#include "nsStringGlue.h"

#undef SetPort  // XXX Windows!

namespace mozilla {
class Encoding;
}


namespace mozilla {
namespace ipc {
class URIParams;
} // namespace ipc
} // namespace mozilla

template <class T>
class BaseURIMutator
{
// This is the base class that can be extended by implementors of nsIURIMutator
// in order to avoid code duplication
// Class type T should be the type of the class that implements nsIURI
protected:
    nsresult InitFromURI(T* aURI)
    {
        nsCOMPtr<nsIURI> clone;
        nsresult rv = aURI->Clone(getter_AddRefs(clone));
        if (NS_FAILED(rv)) {
            return rv;
        }
        mURI = static_cast<T*>(clone.get());
        return NS_OK;
    }

    nsresult InitFromInputStream(nsIObjectInputStream* aStream)
    {
        RefPtr<T> uri = new T();
        nsresult rv = uri->Read(aStream);
        if (NS_FAILED(rv)) {
            return rv;
        }
        mURI = uri;
        return NS_OK;
    }

    nsresult InitFromIPCParams(const mozilla::ipc::URIParams& aParams)
    {
        RefPtr<T> uri = new T();
        bool ret = uri->Deserialize(aParams);
        if (!ret) {
          return NS_ERROR_FAILURE;
        }
        mURI = uri;
        return NS_OK;
    }

    nsresult InitFromSpec(const nsACString& aSpec)
    {
        RefPtr<T> uri = new T();
        nsresult rv = uri->SetSpec(aSpec);
        if (NS_FAILED(rv)) {
          return rv;
        }
        mURI = uri;
        return NS_OK;
    }

    RefPtr<T> mURI;
};

// Since most implementations of nsIURIMutator would extend BaseURIMutator,
// some methods would have the same implementation. We provide a useful macro
// to avoid code duplication.
#define NS_DEFINE_NSIMUTATOR_COMMON                                           \
  NS_IMETHOD Deserialize(const mozilla::ipc::URIParams& aParams) override     \
    { return InitFromIPCParams(aParams); }                                    \
  NS_IMETHOD Read(nsIObjectInputStream* aStream) override                     \
    { return InitFromInputStream(aStream); }                                  \
  NS_IMETHOD Finalize(nsIURI** aURI) override                                 \
    { mURI.forget(aURI); return NS_OK; }                                      \
  NS_IMETHOD SetSpec(const nsACString & aSpec) override                       \
    { return InitFromSpec(aSpec); }

%}

[ptr] native Encoding(const mozilla::Encoding);
[ref] native const_URIParams_ref(const mozilla::ipc::URIParams);

[scriptable, builtinclass, uuid(1fc53257-898b-4c5e-b69c-05bc84b4cd8f)]
interface nsIURISetSpec : nsISupports
{
  /**
   * This setter is different from all other setters because it may be used to
   * initialize the object. We define it separately allowing mutator implementors
   * to define it separately, while the rest of the setters may be simply
   * forwarded to the mutable URI.
   */
  void setSpec(in AUTF8String aSpec);
};

[scriptable, builtinclass, uuid(5403a6ec-99d7-405e-8b45-9f805bbdfcef)]
interface nsIURISetters : nsIURISetSpec
{
  void setScheme(in AUTF8String aScheme);
  void setUserPass(in AUTF8String aUserPass);
  void setUsername(in AUTF8String aUsername);
  void setPassword(in AUTF8String aPassword);
  void setHostPort(in AUTF8String aHostPort);
  void setHostAndPort(in AUTF8String aHostAndPort);
  void setHost(in AUTF8String aHost);
  void setPort(in long aPort);
  void setPathQueryRef(in AUTF8String aPathQueryRef);
  void setRef(in AUTF8String aRef);
  void setFilePath(in AUTF8String aFilePath);
  void setQuery(in AUTF8String aQuery);
  [noscript] void setQueryWithEncoding(in AUTF8String query, in Encoding encoding);
};

[scriptable, builtinclass, uuid(4d1f3103-1c44-4dcd-b717-5d22a697a7d9)]
interface nsIURIMutator : nsIURISetters
{
  /**
   * Initializes the URI by reading from the input stream.
   * The input stream must contain the serialization of the same object type.
   * See nsISerializable.
   */
  void read(in nsIObjectInputStream aInputStream);

  /**
   * Initalizes the URI by reading IPC URIParams.
   * See nsIIPCSerializableURI.
   */
  [noscript, notxpcom]
  nsresult deserialize(in const_URIParams_ref aParams);

  /**
   * Finishes changing or constructing the URI and returns an immutable URI.
   */
  nsIURI finalize();
};