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@4: * under the terms of "Eclipse Public License v1.0"
williamr@2: * which accompanies this distribution, and is available
williamr@4: * at the URL "http://www.eclipse.org/legal/epl-v10.html".
williamr@2: *
williamr@2: * Initial Contributors:
williamr@2: * Nokia Corporation - initial contribution.
williamr@2: *
williamr@2: * Contributors:
williamr@2: *
williamr@2: * Description:  Data listener
williamr@2: *
williamr@2: */
williamr@2: 
williamr@2: 
williamr@2: #ifndef SENSRVDATALISTENER_H
williamr@2: #define SENSRVDATALISTENER_H
williamr@2: 
williamr@2: 
williamr@2: #include <e32base.h>
williamr@2: #include <sensrvchannel.h>
williamr@2: #include <sensrvtypes.h>
williamr@2: 
williamr@2: /**
williamr@2: * Data listener callback interface to indicate when data is available for clients to read.
williamr@2: * 
williamr@2: * This class is for use with the CSensrvChannel::StartDataListeningL() method. Clients wishing to
williamr@2: * use data listening must inherit from this class and provide a reference to an instance of it in
williamr@2: * CSensrvChannel::StartDataListeningL().
williamr@2: * 
williamr@2: * @see CSensrvChannel::StartDataListeningL()
williamr@2: * @see CSensrvChannel::GetData()
williamr@2: * @see CSensrvChannel::StopDataListening()
williamr@2: * @lib sensrvclient.lib
williamr@2: * @since S60 5.0 
williamr@2: */
williamr@2: class MSensrvDataListener
williamr@2:     {
williamr@2:     public:
williamr@2:     /**
williamr@2:     * Callback implemented by a client so that they can be notified that data is available to read.
williamr@2:     * A client can read the data using CSensrvChannel::GetData(). Data is valid until this
williamr@2:     * DataReceived() notification occurs again.
williamr@2:     
williamr@2:     * Data loss can occur if the client does not retrieve data, using SensrvChannel::GetData(), from
williamr@2:     * server fast enough after the client has been told it is availble. This can happen when system
williamr@2:     * is under heavy load and the client process has lower priority than sensor server process.
williamr@2:     * If data loss is a problem consider using a higher object count in data listening, which will
williamr@2:     * reduce the number of IPC context switches.
williamr@2:     * 
williamr@2:     * Clients providing an implementation for this callback must ensure that the operation does not
williamr@2:     * leave. If a leave does occur then the behaviour is undefined.
williamr@2:     * 
williamr@2:     * @since S60 5.0
williamr@2:     * @param  aChannel Channel associated with the listener
williamr@2:     * @param  aCount Data object count contained in data to be read
williamr@2:     * @param  aDataLost Number of lost data items.
williamr@2:     * @see CSensrvChannel::GetData()
williamr@2:     */  
williamr@2:     virtual void DataReceived( CSensrvChannel& aChannel, 
williamr@2:                                TInt aCount, 
williamr@2:                                TInt aDataLost ) = 0;
williamr@2:     
williamr@2:     /**
williamr@2:     * Callback implemented by a client so that they can be notified when data listening has failed.
williamr@2:     * If the error is fatal the channel will be closed, the sensor server session has been terminated
williamr@2:     * and the channel object is no longer useable. If the error is minor, some data has potentially
williamr@2:     * been lost, however listening is still active.
williamr@2:     * 
williamr@2:     * Clients providing an implementation for this callback must ensure that the operation does not
williamr@2:     * leave. If a leave does occur then the behaviour is undefined.
williamr@2:     * 
williamr@2:     * @since S60 5.0
williamr@2:     * @param  aChannel Channel associated with the listener
williamr@2:     * @param  aError The error severity
williamr@2:     */
williamr@2:     virtual void DataError( CSensrvChannel& aChannel, 
williamr@2:                             TSensrvErrorSeverity aError ) = 0;
williamr@2:     
williamr@2:     /** 
williamr@2:     * Callback to future proof this API so that additional callbacks can be added in the future 
williamr@2:     * without breaking binary compatibility.
williamr@2:     * 
williamr@2:     * @since S60 5.0
williamr@2:     * @param  aInterfaceUid Identifier for the interface to be retrieved
williamr@2:     * @param  aInterface A reference to a pointer for the specified interface. Implementation sets
williamr@2:     * aInterface to a valid pointer if the M-class identified by aInterfaceUid is supported, otherwise
williamr@2:     * it is set to NULL on exit.
williamr@2:     * @leave  One of the system-wide error codes
williamr@2:     */
williamr@2: 	virtual void GetDataListenerInterfaceL( TUid aInterfaceUid, TAny*& aInterface ) = 0;
williamr@2: 
williamr@2:     };
williamr@2:  
williamr@2: #endif //SENSRVDATALISTENER_H
williamr@2: 
williamr@2: // End of File