williamr@2: /* williamr@2: * Copyright (c) 2008 Nokia Corporation and/or its subsidiary(-ies). williamr@2: * All rights reserved. williamr@2: * This component and the accompanying materials are made available williamr@2: * 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 williamr@2: * which accompanies this distribution, and is available williamr@2: * at the URL "http://www.symbianfoundation.org/legal/licencesv10.html". williamr@2: * williamr@2: * Initial Contributors: williamr@2: * Nokia Corporation - initial contribution. williamr@2: * williamr@2: * Contributors: williamr@2: * williamr@2: * Description: Sensor Channel API williamr@2: * williamr@2: */ williamr@2: williamr@2: williamr@2: williamr@2: #ifndef SENSRVCHANNELFINDER_H williamr@2: #define SENSRVCHANNELFINDER_H williamr@2: williamr@2: // INCLUDES williamr@2: #include williamr@2: #include williamr@2: #include williamr@2: williamr@2: // CLASS DECLARATION williamr@2: class MSensrvChannelListener; williamr@2: williamr@2: /** williamr@2: * The CSensrvChannelFinder class provides an API that allows clients to discover the sensor williamr@2: * channels supported by Sensor Services and receive notifications when channels are installed williamr@2: * and uninstalled. williamr@2: * williamr@2: * The channel specific header files e.g. for orientation, acceleration, proximity, will document williamr@2: * whether a secure id, vendor id or a set of capabilities, if any, is required by the client to williamr@2: * be able to view a channel or receive notifications for it. See the channel specific header williamr@2: * files for these requirements. williamr@2: * williamr@2: * On instantiation of this class a session connection to the Sensor Server is made. The Sensor williamr@2: * server is a transient server and is started, if not already running, when a session connection williamr@2: * is made. The sensor server is shutdown when a device-configured timeout period expires after williamr@2: * the last session connection has been dropped. The Sensor Server will not shutdown if there is williamr@2: * a session connection to it. williamr@2: * williamr@2: * Each item in RSensrvChannelInfoList returned by FindChannelsL() contains a channel Id which is williamr@2: * only valid for the lifetime of the sensor server. If a client requires that this id remains williamr@2: * unchanged then the client must ensure that an instance of either CSensrvChannelFinder or williamr@2: * CSensrvChannel remains instantiated. This keeps a session connection with the server open which williamr@2: * prevents the sensor server from shutting down. williamr@2: * williamr@2: * @see CSensrvChannel williamr@2: * @lib sensrvclient.lib williamr@2: * @since S60 5.0 williamr@2: */ williamr@2: NONSHARABLE_CLASS( CSensrvChannelFinder ): public CBase williamr@2: { williamr@2: public: williamr@2: /** williamr@2: * Two-phased constructor. williamr@2: * williamr@2: * @since S60 5.0 williamr@2: * @return Pointer to created CSensrvChannelFinder object williamr@2: * @leave KErrNoMemory williamr@2: * @leave One of the system-wide error codes williamr@2: */ williamr@2: IMPORT_C static CSensrvChannelFinder* NewL(); williamr@2: williamr@2: /** williamr@2: * Two-phased constructor. williamr@2: * williamr@2: * @since S60 5.0 williamr@2: * @return Pointer to created CSensrvChannelFinder object that is placed on the cleanup stack. williamr@2: * @leave KErrNoMemory williamr@2: * @leave One of the system-wide error codes williamr@2: */ williamr@2: IMPORT_C static CSensrvChannelFinder* NewLC(); williamr@2: williamr@2: public: williamr@2: /** williamr@2: * Retrieves a list of channels that meet the supplied search parameters. Only williamr@2: * channels for which the client has the required secure id, vendor id and williamr@2: * capabilities will be returned. See class description for further information. williamr@2: * williamr@2: * @since S60 5.0 williamr@2: * @param aChannelList List of all channels matching the supplied search williamr@2: * parameters. Each TSensrvChannelInfo instance in the list can be used williamr@2: * to open a channel. Empty list is returned if no matching channels are williamr@2: * found. williamr@2: * @param aSearchParameters Parameters for which matching channels are to be williamr@2: * found. To omit a field from the search use zero (if integer) or williamr@2: * empty string (if descriptor). If all fields are zero or empty string williamr@2: * all channels provided by the system will be returned. ChannelId, williamr@2: * DataItemSize and Reserved data will be ignored if set. williamr@2: * @leave One of the system-wide error codes williamr@2: */ williamr@2: virtual void FindChannelsL( RSensrvChannelInfoList& aChannelList, williamr@2: const TSensrvChannelInfo& aSearchParameters ) = 0; williamr@2: williamr@2: /** williamr@2: * Listens for channels that meet the supplied search parameters. Only channels williamr@2: * for which the client has the required secure id, vendor id and capabilities williamr@2: * will be returned. See class description. Listening can be stopped by providing williamr@2: * a NULL parameter for the aChannelListener argument. williamr@2: * williamr@2: * @since S60 5.0 williamr@2: * @param aChannelListener Pointer to channel listener callback instance. The williamr@2: * channel listener must be valid until the CSensrvChannelFinder object williamr@2: * is destroyed or listening has been stopped. Listening can be stopped williamr@2: * using a NULL parameter. williamr@2: * @param aSearchParameters Parameters for which matching channel notifications williamr@2: * are to be provided. To omit a field from the search use zero (if integer) williamr@2: * or empty string (if descriptor). If all fields are zero or empty string williamr@2: * all channels provided by the system will be returned. ChannelId, williamr@2: * DataItemSize and Reserved data will be ignored if set. williamr@2: * @leave KErrAlreadyExists if channel listener has already been set williamr@2: * @leave One of the system-wide error codes williamr@2: */ williamr@2: virtual void SetChannelListenerL( MSensrvChannelListener* aChannelListener, williamr@2: const TSensrvChannelInfo& aSearchParameters ) = 0; williamr@2: williamr@2: public: williamr@2: /** williamr@2: * Default constructor. williamr@2: */ williamr@2: CSensrvChannelFinder(); williamr@2: }; williamr@2: williamr@2: williamr@2: #endif //SENSRVCHANNELFINDER_H williamr@2: williamr@2: // End of File