/* ***** BEGIN LICENSE BLOCK *****
 * Version: MPL 1.1/GPL 2.0/LGPL 2.1
 *
 * The contents of this file are subject to the Mozilla 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/MPL/
 *
 * 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 XML-RPC Client component.
 *
 * The Initial Developer of the Original Code is
 * Digital Creations 2, Inc.
 * Portions created by the Initial Developer are Copyright (C) 2000
 * the Initial Developer. All Rights Reserved.
 *
 * Contributor(s):
 *   Martijn Pieters <mj@digicool.com> (original author)
 *   Samuel Sieb <samuel@sieb.net>
 *
 * Alternatively, the contents of this file may be used under the terms of
 * either the GNU General Public License Version 2 or later (the "GPL"), or
 * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
 * in which case the provisions of the GPL or the LGPL are applicable instead
 * of those above. If you wish to allow use of your version of this file only
 * under the terms of either the GPL or the LGPL, and not to allow others to
 * use your version of this file under the terms of the MPL, indicate your
 * decision by deleting the provisions above and replace them with the notice
 * and other provisions required by the GPL or the LGPL. If you do not delete
 * the provisions above, a recipient may use your version of this file under
 * the terms of any one of the MPL, the GPL or the LGPL.
 *
 * ***** END LICENSE BLOCK ***** */

/*
 *  XPCOM XML-RPC Client, interface definition.
 *  Version: $Revision: 1.6.28.1 $
 *
 *  $Id: nsIXmlRpcClient.idl,v 1.6.28.1 2006/08/06 22:30:02 samuel%sieb.net Exp $
 */

#include "nsISupports.idl"
#include "nsIURL.idl"
#include "nsIXmlRpcClientListener.idl"

// forward decl.
interface nsIXmlRpcFault;

/**
 * Simple XML-RPC client interface.
 */
[scriptable, uuid(4d7d15c0-3747-4f7f-b6b3-792a5ea1a9aa)]
interface nsIXmlRpcClient: nsISupports {
    /**
     * Set server URL. Call this before using this object.
     *
     * @param serverURL URL of server side object on which methods should
     *                  be called.
     */
    void init(in string serverURL);

    /**
     * Set authentication info if needed.  Both parameters must be
     * specified for authentication to be enabled.
     *
     * @param username  username to be used if asked to authenticate
     * @param password  password to be used if asked to authenticate
     */
    void setAuthentication(in string username, in string password);

    /**
     * Clear authentication info.
     */
    void clearAuthentication(in string username, in string password);

    /**
     * Set character encoding.  The default charset if this function is
     * not called is "UTF-8".
     *
     * @param encoding  encoding charset to be used
     */
    void setEncoding(in string encoding);

    /**
     * The URL of the XML-RPC server
     */
    readonly attribute nsIURL serverURL;

    /**
     * Call remote method methodName asynchronously with given arguments.
     * 
     * Supported arguments are:
     * nsISupportsPRUint8, nsISupportsPRUint16,
     * nsISupportsPRInt16, nsISupportsPRInt32: <i4>
     * nsISupportsPRBool: <boolean>
     * nsISupportsChar, nsISupportsCString: <string>
     * nsISupportsFloat, nsISupportsDouble: <double>
     * nsISupportsPRTime: <dateTime.iso8601>
     * nsIInputStream: <base64>
     * nsISupportsArray: <array>
     * nsIDictionary: <struct>
     *
     * Note that both nsISupportsArray and nsIDictionary can only hold any of
     * the supported input types.
     *
     * Return value will be converted as follows:
     * <i4> or <int>: nsISupportsPRInt32
     * <boolean>: nsISupportsPRBool
     * <string>: nsISupportsCString
     * <double>: nsISupportsDouble
     * <dateTime.iso8601>: nsISupportsPRTime
     * <base64>: nsISupportsCString
     * <array>: nsISupportsArray
     * <struct>: nsIDictionary
     *
     * <fault>s (server side errors) are indicated by returning
     * NS_ERROR_FAILURE. Via nsIXPConnect::GetPendingException()->data a
     * nsIXmlRpcFault object can be retreieved with more information on the
     * fault.
     *
     * @param listener          A nsIXmlRpcClientListener that will get notified
     *                          of XML-RPC events.
     * @param context           A context to be passed on to the listener.
     * @param methodName        Remote method to call.
     * @param arguments         Array of arguments to pass to remote method.
     * @return                  Return value of remote method.
     */
    void asyncCall(in nsIXmlRpcClientListener listener, in nsISupports ctxt,
        in string methodName,
        [array, size_is(count)] in nsISupports arguments, in PRUint32 count);

    /**
     * Whether or not a call is in progress
     */
    readonly attribute boolean inProgress;
    
    /**
     * The most recent XML-RPC fault from returned from this server.
     * null if the last call didn't return an XML-RPC fault.
     */
    readonly attribute nsIXmlRpcFault fault;

    /**
     * The most recent XML-RPC call result returned from this server.
     * null if the last call didn't return a valid result
     */
    readonly attribute nsISupports result;

    /**
     * The most recent HTTP status code returned from this server
     * null if the server was unreachable or not yet contacted.
     */
    readonly attribute unsigned long responseStatus;
    readonly attribute unsigned long responseString;

    /**
     * Convenience: return the correct nsISupportsPrimitive for a given XML-RPC
     * type, or nsISupportsArray or nsIDictionary.  'base64' isn't supported.
     * No QueryInterface call is needed, the object has been QueryInterfaced to
     * the correct interface.
     *
     * @param type              One of the listed constants.
     * @param uuid              The uuid of the returned object. No QI call 
     *                          needed.
     * @param nsQIResult        The apropriate XPCOM object.
     */
    void createType(in unsigned long type, out nsIIDRef uuid, 
        [iid_is(uuid),retval] out nsQIResult result);
    const unsigned long INT      = 1; // nsISupportsPRInt32
    const unsigned long BOOLEAN  = 2; // nsISupportsPRBool
    const unsigned long STRING   = 3; // nsISupportsCString
    const unsigned long DOUBLE   = 4; // nsISupportsDouble
    const unsigned long DATETIME = 5; // nsISupportsPRTime
    const unsigned long ARRAY    = 6; // nsISupportsArray
    const unsigned long STRUCT   = 7; // nsIDictionary
};

/**
 * An XML-RPC exception.
 * XML-RPC server fault codes are returned wrapped in this Access via
 * nsIXPConnect::GetPendingException()->data
 */
[scriptable, uuid(691cb864-0a7e-448c-98ee-4a7f359cf145)]
interface nsIXmlRpcFault: nsISupports {
    readonly attribute PRInt32 faultCode;
    readonly attribute string faultString;
    
    void init(in PRInt32 faultCode, in string faultString);

    string toString();
};

// vim:sw=4:sr:sta:et:sts: