/**
 * 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
 *
 * XKMSMessageAbstractType := Interface for base schema of XKMS messages
 *
 * $Id$
 *
 */

#ifndef XKMSMESSAGEABSTRACTTYPE_INCLUDE
#define XKMSMESSAGEABSTRACTTYPE_INCLUDE

// XSEC Includes

#include <xsec/framework/XSECDefs.hpp>
#include <xsec/dsig/DSIGConstants.hpp>

#ifdef XSEC_XKMS_ENABLED

class DSIGSignature;

XSEC_DECLARE_XERCES_CLASS(DOMElement);

/**
 * @ingroup xkms
 */

/**
 * @brief Interface definition for the MessageAbstractType
 *
 * The \<MessageAbstractType\> is an abstract type on which all
 * other XKMS messages are built.  All request/response messages
 * have :
 * <ul>
 *  <li><b>Id</b> The unique ID of this message</li>
 *  <li><b>Service</b> The URI of the service for which this message is
 * destined or comes from.</li>
 *  <li><b>Nonce</b> (Optional) Random data used to defend against replay attacks.
 * </ul>
 *
 * In addition, such messages may have :
 *
 * <ul>
 *  <li><b>Signature</b> Validating authenticity of this message</li>
 *  <li><b>MessageExtension</b> Used for extensibility</li>
 *  <li><b>OpaqueClientData</b> Used for application specific info</li>
 * </ul>
 *
 * The schema definition for MessageAbstractType is as follows :
 *
 * \verbatim
   <!-- MessageAbstractType -->
   <complexType name="MessageAbstractType" abstract="true">
      <sequence>
         <element ref="ds:Signature" minOccurs="0"/>
         <element ref="xkms:MessageExtension" minOccurs="0" 
               maxOccurs="unbounded"/>
         <element ref="xkms:OpaqueClientData" minOccurs="0"/>
      </sequence>
      <attribute name="Id" type="ID" use="required"/>
      <attribute name="Service" type="anyURI" use="required"/>
      <attribute name="Nonce" type="base64Binary" use="optional"/>
   </complexType>
   <!-- /MessageAbstractType -->

  \endverbatim
 */


class XSEC_EXPORT XKMSMessageAbstractType {

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

protected:

	XKMSMessageAbstractType() {};

public:

	enum messageType {

		None,					/** A default value that indicates something hasn't been set */

		/* X-KISS messages */

		CompoundRequest,		/** A CompoundRequest message - holding multiple requests */
		CompoundResult,			/** A CompoundResult message - holding multiple results */
		LocateRequest,			/** A LocateRequest message */
		LocateResult,			/** A LocateResult message */
		ValidateRequest,		/** A ValidateRequest message */
		ValidateResult,			/** A ValidateResult message */
		PendingRequest,			/** A PendingRequest message (Asynchronous protocol) */
		StatusRequest,          /** A StatusRequest message (Asynchronous protocol) */
		StatusResult,           /** A StatusResult message (Asynchronous protocol) */
		Result,					/** A non-specific result message */

		/* X-KRSS messages */

		RegisterRequest,		/** A RegisterReqeust message */
		RegisterResult,			/** A RegisterResult message */
		RevokeRequest,			/** A RevokeRequest message */
		RevokeResult,			/** A RevokeResult message */
		RecoverRequest,			/** A RecoverRequest message */
		RecoverResult,			/** A RecoverResult message */
		ReissueRequest,			/** A ReissueRequest message */
		ReissueResult			/** A ReissueResult message */

	};

	virtual ~XKMSMessageAbstractType() {};

	/** @name Message Manipulation Methods */
	//@{

	virtual messageType getMessageType(void) = 0;

	/** @name Getter Interface Methods */
	//@{

	/**
	 * \brief Find out whether this is a signed Message
	 *
	 * @returns true if the message is signed
	 */

	virtual bool isSigned(void) const = 0;

	/**
	 * \brief Retrieve the Signature information (if any is attached)
	 *
	 * All XKMS messages MAY have a \<Signature\> node that is used
	 * to attest to the validity of the message.
	 *
	 * @returns The DSIGSignature object associated with this Message,
	 * or NULL if none is defined
	 */

	virtual DSIGSignature * getSignature(void) const = 0;

	/*
	 * \brief Obtain the base Element for this structure
	 *
	 * @returns the Element node at the head of the DOM structure
	 */

	virtual XERCES_CPP_NAMESPACE_QUALIFIER DOMElement * getElement(void) const = 0;

	/**
	 * \brief Get the Id for the Message
	 *
	 * All messages are required to have an Id attribute that uniquely
	 * identifies the message.  This method is used to retrieve a pointer
	 * to the Id string.
	 *
	 * @returns a pointer to the Id string (owned by the library)
	 */

	virtual const XMLCh * getId(void) const = 0;

	/**
	 * \brief Get the Service identifier for this message
	 *
	 * All Messages are associated with a particular XKMS service.  This
	 * method can be used to retrieve the Service URI for a particular
	 * message.
	 *
	 * @returns a pointer to the Service URI string (owned by the library)
	 *
	 */

	virtual const XMLCh * getService(void) const = 0;

	/**
	 * \brief Get the Nonce of the message
	 *
	 * All messages MAY have a nonce, used to provide cryptographically
	 * random data that will help defend against a replay attack.
	 *
	 * @returns A string (owned by the library) providing the nonce data in
	 * base64 encoded form.  If no Nonce is set, NULL is returned.
	 */

	virtual const XMLCh * getNonce(void) const = 0;

	//@}

	/** @name Setter interface methods */
	//@{

	/**
	 * \brief Set the Id URI for the Message
	 *
	 * Allows a calling application to set a new Id for the
	 * message
	 * 
	 * Note: Great care should be taken on resetting Id attributes, as
	 * they are used to track a particular transaction through its
	 * liefcycle.
	 *
	 * @param id The Id to set
	 */

	virtual void setId(const XMLCh * id) = 0;

	/**
	 * \brief Set the Service for the Message
	 *
	 * Used to set a new service URI for a particular message.  In general,
	 * the service attribute would not be expected to change.
	 *
	 *
	 * @param service String to set in the Service attribute.
	 */

	virtual void setService(const XMLCh * service) = 0;

	/**
	 * \brief Set the Nonce value
	 *
	 * Allows the application to set a new Nonce value (overwriting any
	 * that is currently set).
	 *
	 * @param uri String (base64 encoded data) to set in the Nonce attribute.
	 * @note no checking of this string is done by the library - it
	 * is assumed that it is a valid base64 encoding.
	 */

	virtual void setNonce(const XMLCh * uri) = 0;

	/**
	 * \brief Add a signature to the message
	 *
	 * Allows an application to sign the message
	 *
	 * @returns the new Signature structure
	 */

	virtual DSIGSignature * addSignature(
		const XMLCh* c14nAlgorithm,
		const XMLCh* signatureAlgorithm,
		const XMLCh* hashAlgorithm) = 0;

	//@}

	/** @name Opaque client data handling */
	//@{

	/**
	 * \brief Find the number of \<OpaqueData\> elements
	 *
	 * The \<OpaqueClientData\> element can have multiple
	 * \<OpaqueData\> children.  This method allows an application
	 * to determine how many such children exist
	 *
	 * @return Number of \<OpaqueData\> elements
	 */

	virtual int getOpaqueClientDataSize(void) = 0;

	/*
	 * \brief Get the nth item in the OpaqueClientData list
	 *
	 * @param item The item to return
	 * @returns the string of the nth item in the OpaqueClientData list.
	 *
	 */

	virtual const XMLCh * getOpaqueClientDataItemStr(int item) = 0;

	/*
	 * \brief Append an item to the OpaqueClientData list
	 *
	 * @param item Base64 string to append to the list.  Will be
	 * wrapped in a OpaqueData element.
	 */

	virtual void appendOpaqueClientDataItem(const XMLCh * item) = 0;

	//@}

private:

	// Unimplemented
	XKMSMessageAbstractType(const XKMSMessageAbstractType &);
	XKMSMessageAbstractType & operator = (const XKMSMessageAbstractType &);

};

#endif /* XSEC_XKMS_ENABLED */

#endif /* XKMSMESSAGEABSTRACTTYPE_INCLUDE */