/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* ***** BEGIN LICENSE BLOCK *****
 * Version: NPL 1.1/GPL 2.0/LGPL 2.1
 *
 * 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 the Initial Developer are Copyright (C) 2001
 * the Initial Developer. All Rights Reserved.
 *
 * Contributor(s):
 *
 *
 * 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 NPL, 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 NPL, the GPL or the LGPL.
 *
 * ***** END LICENSE BLOCK ***** */

#include "nsISupports.idl"

interface nsISchemaType;
interface nsIDOMElement;
interface nsISOAPEncoder;
interface nsISOAPDecoder;
interface nsISOAPMessage;
interface nsIVariant;
interface nsISOAPAttachments;
interface nsISchemaCollection;
interface nsISOAPEncoding;

/** 
 * This interface provides access to a collection of SOAP encodings
 *   and schemas. The registry is owned by an encoding.
 */
[scriptable, uuid(9fe91a61-3048-40e3-99ef-e39ab946ae0b)]
interface nsISOAPEncodingRegistry : nsISupports {
  /**
   * Get an associated encoding for a different encoding style.  If
   *   there is no default associated encoding available for the
   *   specified encoding style, then if aCreateIf is specified, one
   *   is created, otherwise a null is returned.  Associated encodings
   *   are the set of encodings that may be used and modified together
   *   as a set.
   *
   * @param aStyleURI The style URI of the associated encoding.
   *
   * @param aCreateIf If true, then create the associated encoding if it
   *   does not already exist, otherwise return the existing encoding.
   *
   * @return The associated encoding which corresponds to the
   *   specified styleURI, or null if the spefied alternative encoding
   *   does not exist and it was not requested that it be created.
   */
  nsISOAPEncoding getAssociatedEncoding(in AString aStyleURI,
                                        in boolean aCreateIf);

  /**
    * The schema collection used by the owning encoding and all 
    *   associated encodings.
    */
  attribute nsISchemaCollection schemaCollection;
};


/**
 * This interface keeps track of the current encoding style and
 *   how objects should be encoded or decoded, as well as all
 *   associated encodings.
 *   <p>While two different nsSOAPCalls may have an encoding
 *   for the same styleURI, by default the encoding object and all
 *   associated encoding objects are local do not affect other
 *   calls because the encodings are local and not associated, 
 *   unless the same or associated encodings are explicitly set
 *   on multiple calls.  When a call is invoked, the same encoding 
 *   object is automatically set on the response message so that
 *   decoders registered on the call encoding are automatically
 *   applied to the response.
 */

[scriptable, uuid(9ae49600-1dd1-11b2-877f-e62f620c5e92)]
interface nsISOAPEncoding : nsISupports {

  /**
   * The name of the encoding as it is known to SOAP.
   */
  readonly attribute AString styleURI;

  /**
   * Get an associated encoding for a different encoding style.  If
   *   there is no default associated encoding available for the
   *   specified encoding style, then if aCreateIf is specified, one
   *   is created, otherwise a null is returned.  Associated encodings
   *   are the set of encodings that may be used and modified together
   *   as a set.
   *
   * @param aStyleURI The style URI of the associated encoding.
   *
   * @param aCreateIf If true, then create the associated encoding if it
   *   does not already exist, otherwise return the existing encoding.
   *
   * @return The associated encoding which corresponds to the
   *   specified styleURI, or null if the spefied alternative encoding
   *   does not exist and it was not requested that it be created.
   */
  nsISOAPEncoding getAssociatedEncoding(in AString aStyleURI,
                                        in boolean aCreateIf);

  /**
    * Set an encoder in the encoding.
    *
    * @param aKey The key to be associated with the encoder.
    *
    * @param aEncoder The encoder to be specified or null to eliminate
    *   the encoder.
    */
  void setEncoder(in AString aKey, in nsISOAPEncoder aEncoder);

  /**
    * Get an encoder from the encoding.
    *
    * @param aKey The key to be used to look up the encoder.
    *
    * @return The encoder.
    */
  nsISOAPEncoder getEncoder(in AString aKey);

  /**
    * Set a decoder in the encoding.
    *
    * @param aKey The key to be associated with the decoder.
    *
    * @param aDecoder The decoder to be specified or null to eliminate
    *   the decoder.
    */
  void setDecoder(in AString aKey, in nsISOAPDecoder aDecoder);

  /**
    * Get a decoder from the encoding.
    *
    * @param aKey The key to be used to look up the decoder.
    *
    * @return The decoder.
    */
  nsISOAPDecoder getDecoder(in AString aKey);

  /**
   * The default encoder invoked by all encoding calls. Appropriate calls
   * to more-specific encoders, if any, must be dispatched by this default 
   * encoder.  The default encoder typically looks up encoders by known 
   * information such as explicit or implicit types.
   */
  attribute nsISOAPEncoder defaultEncoder;

  /**
   * The default decoder invoked by all encoding calls. Appropriate calls
   * to more-specific decoders, if any, must be dispatched by this default 
   * decoder.  The default decoder typically looks up encoders by known 
   * information such as explicit or implicit types.
   */
  attribute nsISOAPDecoder defaultDecoder;

  /**
    * The schema collection used by this and all associated encodings.
    */
  attribute nsISchemaCollection schemaCollection;

  /**
   * Encode the source variant
   *
   * @param aEncodings The encodings to be used.
   *
   * @param aEncodingStyleURI The encoding style
   *
   * @param aSource The variant to be encoded, soon to become a variant
   *
   * @param aNamespaceURI The namespace of the thing being coded
   *
   * @param aName The name of the thing being coded
   *
   * @param aSchemaType The schema type of the thing being encoded
   *
   * @param aDestination The node scope where the result will live.
   *
   * @param aAttachments Accumulates any attachments.
   *
   * @return The element which was inserted and encoded.
   */
  nsIDOMElement encode(in nsIVariant aSource,
                       in AString aNamespaceURI,
                       in AString aName,
                       in nsISchemaType aSchemaType,
                       in nsISOAPAttachments aAttachments,
                       in nsIDOMElement aDestination);

  /**
   * Decode the source DOM node
   *
   * @param aEncodings The encodings used to decode
   *
   * @param aEncodingStyleURI The encoding style
   *
   * @param aSource The DOM node to be decoded.
   *
   * @param aSchemaType The schema type of the source DOM node
   *
   * @param aAttachments Dispenses any attachments.
   *
   * @return The decoded variant, soon to become a variant, which is null if 
   *   the operation failed or did not return a result.
   */
  nsIVariant decode(in nsIDOMElement aSource,
                    in nsISchemaType aSchemaType,
                    in nsISOAPAttachments aAttachments);
  /**
   * Map an external schema URI to an internal one.  In an
   * ideal world, we don't need this, but schemas change URIs,
   * and we wind up with inconsistencies between WSDL and
   * exchanged documents.  The external URI must not be
   * currently mapped and if output mapping is true, then
   * the internal URI must be unique for output mapping.
   *
   * @param aExternalURI the external URI to be mapped.
   *
   * @param aInternalURI the internal URI to be mapped.
   *
   * @param aOutput If true, then re-map to the output
   *   URI when outputting.
   *
   * @return boolean true if succeeded, false if the
   *   mapping was not unique as required.
   */
  boolean mapSchemaURI(in AString aExternalURI,
                    in AString aInternalURI,
                    in boolean aOutput);

  /**
   * Unmap an external schema URI as mapped by
   * mapSchemaURI.
   *
   * @param aExternalURI the external URI to be mapped.
   *
   * @return boolean true if succeeded, false if the
   *   mapping did not exist.
   */
  boolean unmapSchemaURI(in AString aExternalURI);

  /**
   * Get an internal schema URI from an external one.
   *
   * @param aExternalURI the external URI which may
   *   have been mapped.
   *
   * @return The corresponding internal URI (the
   *   original is returned if it has not been mapped).
   */
  AString getInternalSchemaURI(in AString aExternalURI);

  /**
   * Get an external schema URI from an internal one.
   *
   * @param aExternalURI the external URI which may
   *   have been mapped.
   *
   * @return The corresponding internal URI (the
   *   original is returned if it has not been mapped).
   */
  AString getExternalSchemaURI(in AString aInternalURI);

};

%{C++
#define NS_SOAPENCODING_CID                            \
{ /* db612ec6-1dd1-11b2-a8bc-e6777bf70a30 */        \
  0xdb612ec6, 0x1dd1, 0x11b2,                       \
 {0xa8, 0xbc, 0xe6, 0x77, 0x7b, 0xf7, 0x0a, 0x30} }
#define NS_SOAPENCODING_CONTRACTID \
"@mozilla.org/xmlextras/soap/encoding;1"
#define NS_SOAPENCODING_CONTRACTID_PREFIX \
NS_SOAPENCODING_CONTRACTID "?uri="
#define NS_DEFAULTSOAPENCODING_1_1_CID                            \
{ /* 06fb035c-1dd2-11b2-bc30-f6d8e314d6b9 */        \
  0x06fb035c, 0x1dd2, 0x11b2,                       \
 {0xbc, 0x30, 0xf6, 0xd8, 0xe3, 0x14, 0xd6, 0xb9} }
#define NS_DEFAULTSOAPENCODING_1_1_CONTRACTID \
NS_SOAPENCODING_CONTRACTID_PREFIX "http://schemas.xmlsoap.org/soap/encoding/"
#define NS_DEFAULTSOAPENCODING_1_2_CID                            \
{ /* e0ee4044-1dd1-11b2-9d7e-8899d4d89648 */        \
  0xe0ee4044, 0x1dd1, 0x11b2,                       \
 {0x9d, 0x7e, 0x88, 0x99, 0xd4, 0xd8, 0x96, 0x48} }
#define NS_DEFAULTSOAPENCODING_1_2_CONTRACTID \
NS_SOAPENCODING_CONTRACTID_PREFIX "http://www.w3.org/2001/09/soap-encoding"
%}