/**
 * <copyright> Copyright 2006 by Know-Center, Graz, Austria </copyright>
 * PDF-AS has been contracted by the E-Government Innovation Center EGIZ, a
 * joint initiative of the Federal Chancellery Austria and Graz University of
 * Technology.
 *
 * Licensed under the EUPL, Version 1.1 or - as soon they will be approved by
 * the European Commission - subsequent versions of the EUPL (the "Licence");
 * You may not use this work except in compliance with the Licence.
 * You may obtain a copy of the Licence at:
 * http://www.osor.eu/eupl/
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the Licence is distributed on an "AS IS" basis,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the Licence for the specific language governing permissions and
 * limitations under the Licence.
 *
 * This product combines work with different licenses. See the "NOTICE" text
 * file for details on the various modules and licenses.
 * The "NOTICE" text file is part of the distribution. Any derivative works
 * that you distribute must include a readable copy of the "NOTICE" text file.
 */
package at.gv.egiz.pdfas.api.internal;

import java.util.Map;

import at.gv.egiz.pdfas.api.PdfAs;
import at.gv.egiz.pdfas.api.analyze.AnalyzeResult;
import at.gv.egiz.pdfas.api.commons.SignatureInformation;
import at.gv.egiz.pdfas.api.exceptions.PdfAsException;
import at.gv.egiz.pdfas.api.sign.SignParameters;
import at.gv.egiz.pdfas.api.sign.SignResult;
import at.gv.egiz.pdfas.api.sign.SignatureDetailInformation;
import at.gv.egiz.pdfas.api.verify.VerifyResult;
import at.knowcenter.wag.egov.egiz.exceptions.ConnectorException;
import at.knowcenter.wag.egov.egiz.exceptions.ConnectorFactoryException;
import at.knowcenter.wag.egov.egiz.exceptions.NormalizeException;
import at.knowcenter.wag.egov.egiz.exceptions.SettingsException;
import at.knowcenter.wag.egov.egiz.exceptions.SignatureException;
import at.knowcenter.wag.egov.egiz.exceptions.SignatureTypesException;

/**
 * The methods of this interface are used by the pdf-as-web project and are not for external use.<br/>
 * Using this API is inadvisable as its functionality might change without notice from release to release.
 * 
 * @author exthex
 *
 */
public interface PdfAsInternal {
   
   /**
    * Check if a BKU with the given parameters is supported. 
    * 
    * @param bkuParams
    * @throws ConnectorException if the BKU is not supported
    * @throws SettingsException if the BKU is not supported
    */
   public void verifyBKUSupport(LocalBKUParams bkuParams) throws ConnectorException, SettingsException;
   
   /**
    * Finish the sign process.
    * 
    * @param pdfAs
    * @param signParameters
    * @param sdi This info will most likely come from a {@link PdfAs#prepareSign(SignParameters)} call
    * @param bkuParams
    * @param xmlResponse the SecurityLayer response from the BKU
    * @return the signed document + additional info
    * @throws PdfAsException
    */
   public SignResult finishLocalSign(PdfAs pdfAs, SignParameters signParameters, SignatureDetailInformation sdi, LocalBKUParams bkuParams, boolean multipart, String xmlResponse) throws PdfAsException;

   /**
    * Get the security layer address for the given connector. (zB: http://127.0.0.1:3495/http-security-layer-request)
    * 
    * @param profile
    * @param device
    * @return
    * @throws SettingsException
    */
   public String getLocalServiceAddress(String profile, String device) throws SettingsException;

   /**
    * Get the CreateXMLSignatureRequest for the given parameters.
    * The request will use the given callback address to retrieve the data to sign.
    * 
    * @param signParameters the sign parameters. {@link SignParameters#getSignatureDevice()} determines the connector to use.
    * @param multipart true to select a {@link at.knowcenter.wag.egov.egiz.sig.connectors.LocalConnector} that uses multipart requests
    * @param loc_ref_url the URL where to retrieve the PDF to sign
    * @param sdi {@link SignatureDetailInformation#getSignatureData()} provides the data to be signed.
    * @return
    * @throws ConnectorException
    */
   public String prepareLocalSignRequest(SignParameters signParameters, boolean multipart, String loc_ref_url, SignatureDetailInformation sdi) throws ConnectorException;
   
   /**
    * Create an AnalyzeResult from raw text, instead of a PDF.
    * 
    * @param rawText
    * @param sigValues the signature values
    * @return
    * @throws SignatureException
    * @throws SettingsException
    * @throws SignatureTypesException
    * @throws NormalizeException
    */
   public AnalyzeResult analyzeFromRawText(String rawText, Map sigValues) throws SignatureException, SettingsException, SignatureTypesException, NormalizeException;
   
   /**
    * Create the SecurityLayer VerifyXMLSignatureRequest for the given parameters.
    * 
    * @param sigInfo
    * @param connector
    * @param profile
    * @param loc_ref_url
    * @return
    * @throws SignatureException
    * @throws ConnectorException
    */
   public String prepareLocalVerifyRequest(SignatureInformation sigInfo, String connector, String profile, String loc_ref_url) throws SignatureException, ConnectorException;
   
   /**
    * Parse the given xml_response - must be a VerifyXMLSignatureResponse - from the BKU or Mocca and generates a VerifyResult from it. 
    *  
    * @param sigInfo
    * @param connector
    * @param profile
    * @param loc_ref_url
    * @param xmlResponse
    * @return
    * @throws SignatureException
    * @throws ConnectorException
    */
   public VerifyResult finishLocalVerify(SignatureInformation sigInfo, String connector, String profile, String loc_ref_url, String xmlResponse) throws SignatureException, ConnectorException;
   
   /**
    * Get the {@link SignatureEntry} corresponding to a given {@link SignatureInformation}
    * 
    * @param key
    * @param sigInfo
    * @return
    */
   public SignatureEntry getSignatureEntryFromSignatureInformation(String key, SignatureInformation sigInfo);
   
   /**
    * Get the signed text for a given sigInfo.<br/>
    * If this signature is not text based this method will return null.  
    * 
    * @param sigInfo
    * @return
    */
   public String getSignedText(SignatureInformation sigInfo);

   /**
    * Get a map of all connectors available for web.
    * The key is the connector id, the value is the description.
    * 
    * @return
    * @throws ConnectorFactoryException
    */
   public Map getConnectorsAvailableForWeb() throws ConnectorFactoryException;
}