--- a/epoc32/include/sensrvchannelfinder.h Tue Nov 24 13:55:44 2009 +0000
+++ b/epoc32/include/sensrvchannelfinder.h Tue Mar 16 16:12:26 2010 +0000
@@ -1,1 +1,133 @@
-sensrvchannelfinder.h
+/*
+* 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