/*

* Copyright (c) 2001-2009 Nokia Corporation and/or its subsidiary(-ies).

* All rights reserved.

* This component and the accompanying materials are made available

* under the terms of the License "Eclipse Public License v1.0"

* which accompanies this distribution, and is available

* at the URL "http://www.eclipse.org/legal/epl-v10.html".

*

* Initial Contributors:

* Nokia Corporation - initial contribution.

*

* Contributors:

*

* Description: 

*

*/

/**

 @file

 @publishedAll

 @released

*/

#ifndef __MCERTINFO_H__

#define __MCERTINFO_H__

#include <ct/rmpointerarray.h>

// Forward declarations

class CCTCertInfo;

class CCertAttributeFilter;

class TCTTokenObjectHandle;

/**

 * 

 * Defines the interface for a read-only certificate store.

 *

 * This documentation describes the security policy that must be enforced by

 * implementations of the interface.

 */

class MCertStore

	{

public:

	/**

	 * Listing Certificates

	 */

	/**

	 * Get a list of all certificates that satisfy the supplied filter.

	 * 	

	 * This is an async function; all errors are reported by completing aStatus

	 * with the error value, and it can be cancelled with CancelList().

	 * 

	 * @param aCerts An array into which the returned certificates are placed.

	 * @param aFilter A filter to select which certificates should be included.

	 * @param aStatus A request status that will be completed when the operation completes.

	 */	

	virtual void List(RMPointerArray<CCTCertInfo>& aCerts, const CCertAttributeFilter& aFilter,

					  TRequestStatus& aStatus) = 0;

	/** Cancels an ongoing List() operation. */

	virtual void CancelList() = 0;

	/**

	 * Getting a certificate given a handle.

	 */

	/**

	 * Get a certificate given its handle.

	 * 

	 * @param aCertInfo The returned certificate.

	 * @param aHandle The handle of the certificate to return.

	 * @param aStatus The request status object; contains the result of the

	 *     GetCert() request when complete. Set to KErrCancel if any outstanding

	 *     request is cancelled.

	 */

	virtual void GetCert(CCTCertInfo*& aCertInfo, const TCTTokenObjectHandle& aHandle, 

						 TRequestStatus& aStatus) = 0;

	/** Cancel an ongoing GetCert() operation. */

	virtual void CancelGetCert() = 0;

	/**

	 * Querying the applications of a certificate.

	 */

	/**

	 * Get the list of the applications associcated with certificate.

	 * 

	 * Applications are represented by UIDs. Examples would be Software Install,

	 * TLS, WTLS, WMLScript, SignText, etc..

	 * 

	 * @param aCertInfo The certificate to return applications for.

	 * @param aAplications An array to save the applications in.

	 * @param aStatus The request status object; contains the result of the

	 *     Applications() request when complete. Set to KErrCancel if any

	 *     outstanding request is cancelled.

	 */

	virtual void Applications(const CCTCertInfo& aCertInfo, RArray<TUid>& aAplications,

							  TRequestStatus& aStatus) = 0;

	/** Cancels an ongoing Applications() operation. */

	virtual void CancelApplications() = 0;

	/**

	 * Tests if a certificate is applicable to a particular application.	

	 * 

	 * @param aCertInfo The certificate in question.

	 * @param aApplication The application.

	 * @param aIsApplicable Set to ETrue or EFalse by the function to return the result.

	 * @param aStatus The request status object; contains the result of the

	 *     IsApplicable() request when complete. Set to KErrCancel if any

	 *     outstanding request is cancelled.

	 */

	virtual void IsApplicable(const CCTCertInfo& aCertInfo, TUid aApplication, 

							  TBool& aIsApplicable, TRequestStatus& aStatus) = 0;

	/** Cancels an ongoing IsApplicable() operation. */

	virtual void CancelIsApplicable() = 0;

	/**

	 * Trust querying

	 */

	/**

	 * Tests whether a certificate is trusted.

	 * 

	 * Trust is only meaningful for CA certificates where it means that the

	 * certificate can be used as a trust root for the purposes of certificate

	 * validation.

	 * 

	 * @param aCertInfo The certificate we are interested in.

	 * @param aTrusted Used to return the trust status.

	 * @param aStatus The request status object; contains the result of the

	 *     Trusted() request when complete. Set to KErrCancel if any outstanding

	 *     request is cancelled.

	 */

	virtual void Trusted(const CCTCertInfo& aCertInfo, TBool& aTrusted, 

						 TRequestStatus& aStatus) = 0;

	/** Cancels an ongoing Trusted() operation. */

	virtual void CancelTrusted() = 0;

	/**

	 * Retrieving the actual certificate

	 */

	/**

	 * Retrieves the actual data of the certificate.	

	 *

	 * @param aCertInfo The certificate to retrieve.

	 * @param aEncodedCert A buffer to put the certificate in. It must be big

	 *     enough; the size is stored in aCertInfo.

	 * @param aStatus The request status object; contains the result of the

	 *     Retrieve()request when complete. Set to KErrCancel if any outstanding

	 *     request is cancelled.

	 *

	 * @capability ReadUserData This requires the ReadUserData capability when

	 *     applied to user certificates, as these may contain sensitive user data.

	 * @leave KErrPermissionDenied If called for a user certificate when the

	 *     caller doesn't have the ReadUserData capability.

	 */

	virtual void Retrieve(const CCTCertInfo& aCertInfo, TDes8& aEncodedCert, 

						  TRequestStatus& aStatus) = 0;

	/** Cancels an ongoing Retrieve() operation. */

	virtual void CancelRetrieve() = 0;

	};

#endif