1.1 --- a/epoc32/include/sensrvchannelfinder.h Tue Nov 24 13:55:44 2009 +0000
1.2 +++ b/epoc32/include/sensrvchannelfinder.h Tue Mar 16 16:12:26 2010 +0000
1.3 @@ -1,1 +1,133 @@
1.4 -sensrvchannelfinder.h
1.5 +/*
1.6 +* Copyright (c) 2008 Nokia Corporation and/or its subsidiary(-ies).
1.7 +* All rights reserved.
1.8 +* This component and the accompanying materials are made available
1.9 +* 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
1.10 +* which accompanies this distribution, and is available
1.11 +* at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
1.12 +*
1.13 +* Initial Contributors:
1.14 +* Nokia Corporation - initial contribution.
1.15 +*
1.16 +* Contributors:
1.17 +*
1.18 +* Description: Sensor Channel API
1.19 +*
1.20 +*/
1.21 +
1.22 +
1.23 +
1.24 +#ifndef SENSRVCHANNELFINDER_H
1.25 +#define SENSRVCHANNELFINDER_H
1.26 +
1.27 +// INCLUDES
1.28 +#include <e32base.h>
1.29 +#include <sensrvtypes.h>
1.30 +#include <sensrvchannelinfo.h>
1.31 +
1.32 +// CLASS DECLARATION
1.33 +class MSensrvChannelListener;
1.34 +
1.35 +/**
1.36 +* The CSensrvChannelFinder class provides an API that allows clients to discover the sensor
1.37 +* channels supported by Sensor Services and receive notifications when channels are installed
1.38 +* and uninstalled.
1.39 +*
1.40 +* The channel specific header files e.g. for orientation, acceleration, proximity, will document
1.41 +* whether a secure id, vendor id or a set of capabilities, if any, is required by the client to
1.42 +* be able to view a channel or receive notifications for it. See the channel specific header
1.43 +* files for these requirements.
1.44 +*
1.45 +* On instantiation of this class a session connection to the Sensor Server is made. The Sensor
1.46 +* server is a transient server and is started, if not already running, when a session connection
1.47 +* is made. The sensor server is shutdown when a device-configured timeout period expires after
1.48 +* the last session connection has been dropped. The Sensor Server will not shutdown if there is
1.49 +* a session connection to it.
1.50 +*
1.51 +* Each item in RSensrvChannelInfoList returned by FindChannelsL() contains a channel Id which is
1.52 +* only valid for the lifetime of the sensor server. If a client requires that this id remains
1.53 +* unchanged then the client must ensure that an instance of either CSensrvChannelFinder or
1.54 +* CSensrvChannel remains instantiated. This keeps a session connection with the server open which
1.55 +* prevents the sensor server from shutting down.
1.56 +*
1.57 +* @see CSensrvChannel
1.58 +* @lib sensrvclient.lib
1.59 +* @since S60 5.0
1.60 +*/
1.61 +NONSHARABLE_CLASS( CSensrvChannelFinder ): public CBase
1.62 + {
1.63 + public:
1.64 + /**
1.65 + * Two-phased constructor.
1.66 + *
1.67 + * @since S60 5.0
1.68 + * @return Pointer to created CSensrvChannelFinder object
1.69 + * @leave KErrNoMemory
1.70 + * @leave One of the system-wide error codes
1.71 + */
1.72 + IMPORT_C static CSensrvChannelFinder* NewL();
1.73 +
1.74 + /**
1.75 + * Two-phased constructor.
1.76 + *
1.77 + * @since S60 5.0
1.78 + * @return Pointer to created CSensrvChannelFinder object that is placed on the cleanup stack.
1.79 + * @leave KErrNoMemory
1.80 + * @leave One of the system-wide error codes
1.81 + */
1.82 + IMPORT_C static CSensrvChannelFinder* NewLC();
1.83 +
1.84 + public:
1.85 + /**
1.86 + * Retrieves a list of channels that meet the supplied search parameters. Only
1.87 + * channels for which the client has the required secure id, vendor id and
1.88 + * capabilities will be returned. See class description for further information.
1.89 + *
1.90 + * @since S60 5.0
1.91 + * @param aChannelList List of all channels matching the supplied search
1.92 + * parameters. Each TSensrvChannelInfo instance in the list can be used
1.93 + * to open a channel. Empty list is returned if no matching channels are
1.94 + * found.
1.95 + * @param aSearchParameters Parameters for which matching channels are to be
1.96 + * found. To omit a field from the search use zero (if integer) or
1.97 + * empty string (if descriptor). If all fields are zero or empty string
1.98 + * all channels provided by the system will be returned. ChannelId,
1.99 + * DataItemSize and Reserved data will be ignored if set.
1.100 + * @leave One of the system-wide error codes
1.101 + */
1.102 + virtual void FindChannelsL( RSensrvChannelInfoList& aChannelList,
1.103 + const TSensrvChannelInfo& aSearchParameters ) = 0;
1.104 +
1.105 + /**
1.106 + * Listens for channels that meet the supplied search parameters. Only channels
1.107 + * for which the client has the required secure id, vendor id and capabilities
1.108 + * will be returned. See class description. Listening can be stopped by providing
1.109 + * a NULL parameter for the aChannelListener argument.
1.110 + *
1.111 + * @since S60 5.0
1.112 + * @param aChannelListener Pointer to channel listener callback instance. The
1.113 + * channel listener must be valid until the CSensrvChannelFinder object
1.114 + * is destroyed or listening has been stopped. Listening can be stopped
1.115 + * using a NULL parameter.
1.116 + * @param aSearchParameters Parameters for which matching channel notifications
1.117 + * are to be provided. To omit a field from the search use zero (if integer)
1.118 + * or empty string (if descriptor). If all fields are zero or empty string
1.119 + * all channels provided by the system will be returned. ChannelId,
1.120 + * DataItemSize and Reserved data will be ignored if set.
1.121 + * @leave KErrAlreadyExists if channel listener has already been set
1.122 + * @leave One of the system-wide error codes
1.123 + */
1.124 + virtual void SetChannelListenerL( MSensrvChannelListener* aChannelListener,
1.125 + const TSensrvChannelInfo& aSearchParameters ) = 0;
1.126 +
1.127 + public:
1.128 + /**
1.129 + * Default constructor.
1.130 + */
1.131 + CSensrvChannelFinder();
1.132 + };
1.133 +
1.134 +
1.135 +#endif //SENSRVCHANNELFINDER_H
1.136 +
1.137 +// End of File