/*

* Copyright (c) 2008 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:  Sensor Channel API

*

*/

#ifndef SENSRVCHANNELFINDER_H

#define SENSRVCHANNELFINDER_H

//  INCLUDES

#include <e32base.h>

#include <sensrvtypes.h>

#include <sensrvchannelinfo.h>

// CLASS DECLARATION

class MSensrvChannelListener;

/**

* The CSensrvChannelFinder class provides an API that allows clients to discover the sensor

* channels supported by Sensor Services and receive notifications when channels are installed

* and uninstalled.

* 

* The channel specific header files e.g. for orientation, acceleration, proximity, will document

* whether a secure id, vendor id or a set of capabilities, if any, is required by the client to

* be able to view a channel or receive notifications for it. See the channel specific header

* files for these requirements.

* 

* On instantiation of this class a session connection to the Sensor Server is made. The Sensor

* server is a transient server and is started, if not already running, when a session connection

* is made. The sensor server is shutdown when a device-configured timeout period expires after

* the last session connection has been dropped. The Sensor Server will not shutdown if there is

* a session connection to it.

* 

* Each item in RSensrvChannelInfoList returned by FindChannelsL() contains a channel Id which is

* only valid for the lifetime of the sensor server. If a client requires that this id remains

* unchanged then the client must ensure that an instance of either CSensrvChannelFinder or

* CSensrvChannel remains instantiated. This keeps a session connection with the server open which

* prevents the sensor server from shutting down.

*

* @see CSensrvChannel

* @lib sensrvclient.lib

* @since S60 5.0

*/

NONSHARABLE_CLASS( CSensrvChannelFinder ): public CBase

    {

    public:

    /**

    * Two-phased constructor.

    *

    * @since S60 5.0

    * @return Pointer to created CSensrvChannelFinder object

    * @leave  KErrNoMemory

    * @leave  One of the system-wide error codes

    */  

    IMPORT_C static CSensrvChannelFinder* NewL();

    /**

    * Two-phased constructor.

    *

    * @since S60 5.0

    * @return Pointer to created CSensrvChannelFinder object that is placed on the cleanup stack.

    * @leave  KErrNoMemory

    * @leave  One of the system-wide error codes

    */  

    IMPORT_C static CSensrvChannelFinder* NewLC();

    public:

    /**

    * Retrieves a list of channels that meet the supplied search parameters. Only

    * channels for which the client has the required secure id, vendor id and

    * capabilities will be returned. See class description for further information.

    *     

    * @since S60 5.0

    * @param  aChannelList List of all channels matching the supplied search 

    *         parameters. Each TSensrvChannelInfo instance in the list can be used

    *         to open a channel. Empty list is returned if no matching channels are

    *         found.

    * @param  aSearchParameters Parameters for which matching channels are to be

    *         found. To omit a field from the search use zero (if integer) or

    *         empty string (if descriptor). If all fields are zero or empty string

    *         all channels provided by the system will be returned. ChannelId,

    *         DataItemSize and Reserved data will be ignored if set.

    * @leave  One of the system-wide error codes

    */

    virtual void FindChannelsL( RSensrvChannelInfoList& aChannelList, 

                                const TSensrvChannelInfo& aSearchParameters ) = 0;

    /**

    * Listens for channels that meet the supplied search parameters. Only channels

    * for which the client has the required secure id, vendor id and capabilities

    * will be returned. See class description. Listening can be stopped by providing

    * a NULL parameter for the aChannelListener argument.

    * 

    * @since S60 5.0

    * @param  aChannelListener Pointer to channel listener callback instance. The

    *         channel listener must be valid until the CSensrvChannelFinder object

    *         is destroyed or listening has been stopped. Listening can be stopped

    *         using a NULL parameter.

    * @param  aSearchParameters Parameters for which matching channel notifications

    *         are to be provided. To omit a field from the search use zero (if integer)

    *         or empty string (if descriptor). If all fields are zero or empty string

    *         all channels provided by the system will be returned. ChannelId,

    *         DataItemSize and Reserved data will be ignored if set.

    * @leave  KErrAlreadyExists if channel listener has already been set

    * @leave  One of the system-wide error codes

    */

    virtual void SetChannelListenerL( MSensrvChannelListener* aChannelListener,

                                const TSensrvChannelInfo& aSearchParameters  ) = 0;

    public:

    /**

    * Default constructor. 

    */

    CSensrvChannelFinder();

    };

#endif //SENSRVCHANNELFINDER_H

// End of File