/**
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements. See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership. The ASF licenses this file
 * to you under the Apache License, Version 2.0 (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.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied. See the License for the
 * specific language governing permissions and limitations
 * under the License.
 */

/*
 * XSEC
 *
 * XSECProvider.hpp := Main interface class that applications use to
 *                       get access to Signature and Encryption functions.
 *
 * $Id$
 *
 */
#ifndef XSECPROVIDER_INCLUDE
#define XSECPROVIDER_INCLUDE

#include <xsec/utils/XSECPlatformUtils.hpp>
#include <xsec/dsig/DSIGSignature.hpp>
#include <xsec/xenc/XENCCipher.hpp>
#include <xsec/xkms/XKMSMessageFactory.hpp>

#include <vector>

/**
 * @addtogroup pubsig
 * @{
 */

/**
 * @brief The main provider class for XML Digital Signatures and Encryption objects.
 *
 * <p>The XSECProvider class is used to create and destroy signature objects and
 * encryption objects.  It provides a number of methods to create signature 
 * and encryption objects for a variety of situations - in particular creating an 
 * empty signature or cipher with which to create the DOM structure or creating a 
 * security object based on an already existing DOM structure.</p>
 *
 */


class XSEC_EXPORT XSECProvider {
public:

    /** @name Constructors and Destructors */
    //@{

    /**
     * \brief Default constructor.
     *
     * <p>The provider class requires no parameters for construction</p>
     *
     */


    XSECProvider();
    virtual ~XSECProvider();

    //@}

    /** @name Signature Creation Classes */
    //@{

    /**
     * \brief DSIGSignature creator for use with existing XML signatures or templates.
     *
     * <p>Create a DSIGSignature object based on an already existing
     * DSIG Signature XML node.  It is assumed that the underlying
     * DOM structure is in place and works correctly.</p>
     *
     * <p>In this case, the caller can pass in the signature DOM Node for cases
     * where there may be more than one signature in a document.  The caller
     * needs to specify which signature tree is to be used.</p>
     *
     * @param doc The DOM document node in which the signature is embedded.
     * @param sigNode The DOM node (within doc) that is to be used as the
     *    base of the signature.
     * @see DSIGSignature#load
     */

    DSIGSignature* newSignatureFromDOM(
        XERCES_CPP_NAMESPACE_QUALIFIER DOMDocument* doc,
        XERCES_CPP_NAMESPACE_QUALIFIER DOMNode* sigNode
    );

    /**
     * \brief DSIGSignature creator for use with existing XML signatures or templates.
     *
     * <p>Create a DSIGSignature object based on an already existing
     * DSIG Signature XML node.  It is assumed that the underlying
     * DOM structure is in place and works correctly.</p>
     *
     * <p>In this case, the XML-Security libraries will find the signature
     * node.</p>
     *
     * @note The library will <em>only</em> find and use the first signature node
     * in the document.  If there are more, they will not be validated
     * @param doc The DOM document node in which the signature is embedded.
     * @see DSIGSignature#load
     */

    DSIGSignature* newSignatureFromDOM(XERCES_CPP_NAMESPACE_QUALIFIER DOMDocument* doc);

    /**
     * \brief DSIGSignature creator for creating new XML signatures.
     *
     * <p>Create an empty DSIGSignature object that can be used to create new
     * signature values.  The returned signature object needs to be initialised
     * with a document so a blank signature DOM structure can be created</p>
     *
     * @see DSIGSignature#createBlankSignature
     */

    DSIGSignature* newSignature();

    /**
     * \brief Method for destroying DSIGSignature objects created via this provider.
     *
     * <p>The provider keeps track of all signature objects created during the lifetime
     * of the provider.  This method can be called to delete a signature whilst the
     * provider is still in scope.  Otherwise the objects will be automatically
     * deleted when the provider object goes out of scope.</p>
     *
     * <p>In cases where the DSIGSignature has been used to create a new DOM structure,
     * it can be safely deleted once the signature operations have been completed without
     * impacting the underlying DOM structure.</p>
     *
     * @param toRelease The DSIGSignature object to be deleted.
     * @todo The DSIGSignature objects are fairly bulky in terms of creation and deletion.
     * There should be a capability to store "released" objects in a re-use stack.  At the
     * moment the Provider class simply deletes the objects.
     * @see DSIGSignature#createBlankSignature
     */

    void releaseSignature(DSIGSignature* toRelease);

    //@}

    /** @name Encryption Creation Functions */
    //@{

    /**
     * \brief Create an XENCCipher object based on a particular DOM Document
     *
     * XENCCipher is an engine class that is used to wrap encryption/decryption
     * functions.  Unlike the Signature functions, only a XENCCipher object attached
     * to a particular document is required.  Arbitrary objects within this document
     * can then be encrypted/decrypted using this class.
     *
     * @param doc Document to attach the XENCCipher to.
     * @returns An implementation object for XENCCipher
     */

    XENCCipher* newCipher(XERCES_CPP_NAMESPACE_QUALIFIER DOMDocument* doc);

    /**
     * \brief Method to delete XENCCipher objects created via this provider
     *
     * <p>The provider keeps track of all objects by it.  This method can be used
     * to delete any previously created XENCCipher objects prior to the provider
     * being deleted.  Any XENCCipher objects not released using this function will
     * automatically be deleted when the provider goes out of scope (or is itself
     * deleted).
     *
     * @param toRelease The XENCCipher object to be deleted
     */

    void releaseCipher(XENCCipher* toRelease);

    //@}

#ifdef XSEC_XKMS_ENABLED
    /** @name XKMS Functions */
    //@{

    /**
     * \brief Obtain a pointer to the XKMSMessageFactory.
     *
     * The XKMSMessageFactory is used to create and manipulate XKMS messages.
     *
     * @note Unlike other objects created by the provider, only one
     * XKMSMessageFactory is ever instantiated for a particular provider.
     * Applications should <b>never</b> delete the Factory, as it is taken
     * care of by the provider.
     */

    XKMSMessageFactory* getXKMSMessageFactory(void);
#endif

    /** @name Environmental Options */
    //@{

    /**
     * \brief Set the default URIResolver.
     *
     * DSIGSignature objects require a URIResolver to allow them to de-reference
     * URIs in reference elements.
     *
     * This function sets the resolver that will be used for all
     * signatures created after this is set.  The resolver is
     * cloned, so the object passed in can be safely deleted once the
     * function has been completed.
     */

    void setDefaultURIResolver(XSECURIResolver* resolver);

    //@}

private:

    // Copy constructor is disabled
    XSECProvider(const XSECProvider&);
    XSECProvider* operator=(const XSECProvider&);

    // Internal functions

    void setup(DSIGSignature* sig);
    void setup(XENCCipher* cipher);

#ifdef XSEC_XKMS_ENABLED
    XKMSMessageFactory* mp_xkmsMessageFactory;
#endif

    XSECURIResolver* mp_URIResolver;
};

/** @} */

#endif /* XSECPROVIDER_INCLUDE */