gecko-dev/netwerk/base/public/nsIIOService.idl

/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 4 -*-
 *
 * The contents of this file are subject to the Netscape Public
 * License Version 1.1 (the "License"); you may not use this file
 * except in compliance with the License. You may obtain a copy of
 * the License at http://www.mozilla.org/NPL/
 *
 * Software distributed under the License is distributed on an "AS
 * IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
 * implied. See the License for the specific language governing
 * rights and limitations under the License.
 *
 * The Original Code is mozilla.org code.
 *
 * The Initial Developer of the Original Code is Netscape
 * Communications Corporation.  Portions created by Netscape are
 * Copyright (C) 1998 Netscape Communications Corporation. All
 * Rights Reserved.
 *
 * Contributor(s): 
 */

#include "nsISupports.idl"

interface nsIProtocolHandler;
interface nsIURI;
interface nsIEventSinkGetter;
interface nsIChannel;
interface nsIStreamObserver;
interface nsIStreamListener;
interface nsIEventQueue;
interface nsIBufferInputStream;
interface nsIInputStream;
interface nsIBufferOutputStream;
interface nsIFileChannel;
interface nsILoadGroup;
interface nsILoadGroupObserver;

[scriptable, uuid(1daf19f0-8ea7-11d3-93ad-00104ba0fd40)]
interface nsIIOService : nsISupports
{
    /**
     * Returns a protocol handler for a given URI scheme.
     */
    nsIProtocolHandler getProtocolHandler(in string scheme);

    /**
     * This method constructs a new URI by first determining the scheme
     * of the URI spec, and then delegating the construction of the URI
     * to the protocol handler for that scheme. QueryInterface can be used
     * on the resulting URI object to obtain a more specific type of URI.
     */
    nsIURI newURI(in string aSpec, in nsIURI aBaseURI);

    /**
     * Creates a channel for a given URI. The eventSinkGetter is used to
     * obtain the appropriate callbacks for the URI's protocol from the
     * application.
     *
     * @param originalURI - Specifies the original URI which caused the creation
     * of this channel. This can occur when the construction of one channel
     * (e.g. for resource:) causes another channel to be created on its behalf
     * (e.g. a file: channel), or if a redirect occurs, causing the current
     * URL to become different from the original URL. If NULL, the aURI parameter
     * will be used as the originalURI instead.
     */
    nsIChannel newChannelFromURI(in string verb,
                                 in nsIURI aURI,
                                 in nsILoadGroup aLoadGroup,
                                 in nsIEventSinkGetter eventSinkGetter,
                                 in nsIURI originalURI);

    /**
     * Convenience routine that first creates a URI by calling NewURI, and
     * then passes the URI to NewChannelFromURI. 
     */
    nsIChannel newChannel(in string verb,
                          in string aSpec,
                          in nsIURI aBaseURI,
                          in nsILoadGroup aLoadGroup,
                          in nsIEventSinkGetter eventSinkGetter,
                          in nsIURI originalURI);

    /**
     * Get the application name string that will be used as part
     * of a HTTP request.
     */
    readonly attribute wstring appCodeName;
  
    /**
     * Get the application version string that will be used as part
     * of a HTTP request.
     */
    readonly attribute wstring appVersion;

    /**
     * Get the application name.
     */
    readonly attribute wstring appName;

    /**
     * Get the translation of the application. The value for language
     * is usually a 2-letter code such as "en" and occasionally a 
     * five-character code to indicate a language subtype, such as "zh_CN". 
     */
    attribute wstring language;

    /**
     * Get the current platform (machine type).
     */
    readonly attribute wstring platform;

    /**
     * Get the HTTP advertised user agent string.
     */
    readonly attribute wstring userAgent;

    /**
     * Returns a new stream observer that marshals data from another
     * stream observer over to the thread specified by an event queue.
     * If the event queue is null, the current thread's event queue is
     * used.
     */
    nsIStreamObserver newAsyncStreamObserver(in nsIStreamObserver receiver,
                                             in nsIEventQueue eventQueue);

    /**
     * An asynchronous stream listener is used to ship data over to another thread specified
     * by the thread's event queue. The receiver stream listener is then used to receive
     * the data on the other thread.
     */
    nsIStreamListener newAsyncStreamListener(in nsIStreamListener receiver,
                                             in nsIEventQueue eventQueue);

    /**
     * A synchronous stream listener pushes data through a pipe that ends up
     * in an input stream to be read by another thread.
     */
    nsIStreamListener newSyncStreamListener(out nsIInputStream inStream,
                                            out nsIBufferOutputStream outStream);

    /**
     * This convenience routine first looks up the file protocol handler, and
     * then uses it to construct a file channel from a native path string.
     */
    nsIFileChannel newChannelFromNativePath(in string nativePath);

    /**
     * Returns a simple channel implementation that uses the given input
     * stream and content type. A URI may also be supplied which will be returned
     * by the channel's GetURI method. This routine is a convenience facililty
     * for protocol writers.
     */
    nsIChannel newInputStreamChannel(in nsIURI uri,
                                     in string contentType, 
                                     in long contentLength,
                                     in nsIInputStream inStr,
                                     in nsILoadGroup group,
                                     in nsIURI originalURI);
};

%{C++

#define NS_IOSERVICE_CID                             \
{ /* 9ac9e770-18bc-11d3-9337-00104ba0fd40 */         \
    0x9ac9e770,                                      \
    0x18bc,                                          \
    0x11d3,                                          \
    {0x93, 0x37, 0x00, 0x10, 0x4b, 0xa0, 0xfd, 0x40} \
}

%}