/*

* Copyright (c) 2002-2007 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 "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members

* which accompanies this distribution, and is available

* at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".

*

* Initial Contributors:

* Nokia Corporation - initial contribution.

*

* Contributors:

*

* Description:        Callback interface through which (web service consumer/management)

*                applications can provide userinfo / account (username & password)

*                to WS-stack. This information can be used in actual authentication

*                with (remote) web service (Liberty Authentication Service or 

*                WS-* STS), or locally (in device) to allow secure access to private

*                information (like credentials to the service, etc).

*

*/

#ifndef M_SEN_AUTHENTICATION_PROVIDER_H

#define M_SEN_AUTHENTICATION_PROVIDER_H

// INCLUDES

#include <e32std.h>

// FORWARD DECLARATIONS

class CSenIdentityProvider;

/**

* Interface description:

*

* The applications can register this callback interface, through which they will receive

* userinfo callbacks (when data like username and password is needed).

*

* Both Service Connection and Service Manager APIs utilize this interface.

*

* In practice, service consumer applications often integrate these callbacks to their UI 

* events, allowing them a control point end-user (login) prompts. 

*

* Furthermore, (remote) service management applications can provide identity (user account)

* spesific "secret", in order to manipulate associated credentials stored in Web Services

* -stack database(s).

*/

class MSenAuthenticationProvider

    {

    public: 

        /**

        * If (consumer) application needs to access protected information or service

        * (behind some identity / account / sing-in process), it may choose to override

        * this method. Returned object represents XML containing all required information

        * that is required to securely authenticate the identity in question.

        * In case that only username & password  -pair is needed, application may 

        * alternatively implement UsernameL() and PasswordL() callbacks.

        * @returs the identity provider description that contains "credentials", like

        * like username and password of some identity (user's account), or other (binary)

        * secret, like fingerprint. 

        */

        virtual const CSenIdentityProvider* IdentityProviderL() { return NULL; }

        /**

        * Callback type getter for username.

        * through this method an application may choose to provide the username of

        * an account it wishes to use. 

        * In cases where the username (login ID) is in simple text format (descriptor),

        * this may be the most convenient method to be overridden. Alternatively,

        * in complex cases, applications may choose to provide identity provider (IDP)

        * description, a piece of XML through IdentityProviderL() callback; that

        * XML could contain extended amount of (binary) information, like fingerprint.

        * Consumer application is supposed to decide, whether or not to show a GUI

        * dialog when this callback is issued: in many cases, that is a common

        * approach to prompt userinfo directly from end-user (unless data is cached

        * elsewhere).

        * @return Password as string (UTF-8 descriptor)

        */

        virtual const TPtrC8 UsernameL() { return TPtrC8(KNullDesC8); }

        /**

        * Callback type getter for password.

        * Application may choose to provide the passport of an account through this

        * method. In cases where the "secret" is in simple text format (descriptor),

        * this may be the most convenient method to be overridden. Alternatively,

        * in complex cases, applications may choose to provide identity provider (IDP)

        * description, a piece of XML through IdentityProviderL() callback; that

        * XML could contain extended amount of (binary) information, like fingerprint.

        * Consumer application is supposed to decide, whether or not to show a GUI

        * dialog when this callback is issued: in many cases, that is a common

        * approach to prompt userinfo directly from end-user (unless data is cached

        * elsewhere).

        * @return Password as string (UTF-8 descriptor)

        */

        virtual const TPtrC8 PasswordL() { return TPtrC8(KNullDesC8); }

        /**

        * This method obtains the callback interface matching the specified uid.

        * @param				aUid the uid identifying the required interface.

        * @return				NULL if no interface matching the uid is found.

        * 					    Otherwise, attempt to dynamically cast this pointer

        *                       to that interface will be made.

        */

    	inline virtual TAny* ExtendedInterface(const TInt32 /* aUid */) { return NULL; }

    };

#endif // M_SEN_PROPERTIES_H

// End of File