1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/epoc32/include/playerinformationtargetobserver.h Tue Mar 16 16:12:26 2010 +0000
1.3 @@ -0,0 +1,300 @@
1.4 +// Copyright (c) 2007-2009 Nokia Corporation and/or its subsidiary(-ies).
1.5 +// All rights reserved.
1.6 +// This component and the accompanying materials are made available
1.7 +// 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.8 +// which accompanies this distribution, and is available
1.9 +// at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
1.10 +//
1.11 +// Initial Contributors:
1.12 +// Nokia Corporation - initial contribution.
1.13 +//
1.14 +// Contributors:
1.15 +//
1.16 +// Description:
1.17 +//
1.18 +
1.19 +
1.20 +
1.21 +/**
1.22 + @file
1.23 + @publishedAll
1.24 + @released
1.25 +*/
1.26 +
1.27 +#ifndef REMCONPLAYERINFORMATIONTARGETOBSERVER_H
1.28 +#define REMCONPLAYERINFORMATIONTARGETOBSERVER_H
1.29 +
1.30 +#include <e32base.h>
1.31 +#include <remcon/avrcpspec.h>
1.32 +#include <barsc2.h>
1.33 +
1.34 +
1.35 +/**
1.36 +This class is used to define the capabilities of the current application,
1.37 +and the implementation will generate AVRCP responses to the controller.
1.38 +For the event part of the API, it is recommended to add all events which make
1.39 +sense for the media player. In general, this will be everything except
1.40 +ESystemStatusChanged. The company ID part of the API is only needed if
1.41 +the media player needs to support vendor extensions other than bluetooth SIG.
1.42 +The bluetooth SIG company ID is always included in responses to a COMPANY_ID request.
1.43 +*/
1.44 +class MPlayerCapabilitiesObserver
1.45 + {
1.46 + public:
1.47 + /**
1.48 + Remove all notification events from the supported list
1.49 + */
1.50 + IMPORT_C void ClearEvents();
1.51 + /**
1.52 + Add a notification event to the supported list of events
1.53 + The AVRCP 1.3 specification mandates that PlaybackStatusChanged
1.54 + and TrackChanged events must be supported; KErrAlreadyExists will
1.55 + be returned if AddEvent() is called with either of these events.
1.56 + @param aEvent the event to add
1.57 + @return KErrAlreadyExists if the event is already present.
1.58 + KErrNotSupported if the event isn't supported by the implementation, e.g.. ESystemStatusChanged
1.59 + */
1.60 + IMPORT_C TInt AddEvent(TRegisterNotificationEvent aEvent);
1.61 + /**
1.62 + Remove a notification event from the supported list of events
1.63 + The AVRCP 1.3 specification mandates that PlaybackStatusChanged
1.64 + and TrackChanged events must be supported; KErrNotSupported will
1.65 + be returned if RemoveEvent() is called with either of these events.
1.66 + @param aEvent the event to remove
1.67 + @return KErrNone if this completes successfully, KErrNotFound if aID
1.68 + was not in the list, or any other system wide error code.
1.69 + */
1.70 + IMPORT_C TInt RemoveEvent(TRegisterNotificationEvent aEvent);
1.71 +
1.72 + const static TInt KMaxCompanyID = 0xFFFFFF;
1.73 + const static TInt KMaxNrOfCompanyIDs = 255;
1.74 +
1.75 + /**
1.76 + Remove all additional company IDs from the supported list
1.77 + */
1.78 + IMPORT_C void ClearCompanyIds();
1.79 + /**
1.80 + Add a company id to the supported list of company ids.
1.81 + The AVRCP 1.3 specification mandates that the Bluetooth SIG vendor id
1.82 + must be supported; KErrAlreadyExists will be returned if AddCompanyId()
1.83 + is called with this company id.
1.84 + @param aID the id to add
1.85 + @return KErrNone if this completes successfully,
1.86 + KErrAlreadyExists if aID is already present,
1.87 + KErrOverflow if the maximum number of company ids are already listed,
1.88 + or any other system wide error code.
1.89 + */
1.90 + IMPORT_C TInt AddCompanyId(TInt aID);
1.91 + /**
1.92 + Remove a company id from the list of supported vendor extensions.
1.93 + The Bluetooth SIG id can't be removed, as this must always be supported
1.94 + @param aID the id to remove
1.95 + @return KErrNone if this completes successfully, KErrNotFound if aID
1.96 + was not in the list, or any other system wide error code.
1.97 + */
1.98 + IMPORT_C TInt RemoveCompanyID(TInt aID);
1.99 +
1.100 + private:
1.101 + virtual void DoClearEvents() = 0;
1.102 + virtual TInt DoAddEvent(TRegisterNotificationEvent aEvent) = 0;
1.103 + virtual TInt DoRemoveEvent(TRegisterNotificationEvent aEvent) = 0;
1.104 + virtual void DoClearCompanyIds() = 0;
1.105 + virtual TInt DoAddCompanyId(TInt aID) = 0;
1.106 + virtual TInt DoRemoveCompanyID(TInt aID) = 0;
1.107 + };
1.108 +
1.109 +/**
1.110 +This class is for supporting the player application settings PDUs in AVRCP1.3
1.111 +specification section 5.2. The RegisterNotification PDU for
1.112 +EVENT_PLAYER_APPLICATION_SETTING_CHANGED is also supported through this API.
1.113 +
1.114 +The media player should first define all the attributes it supports, using
1.115 +DefineAttributeL. When an attribute's value is changed by the media player,
1.116 +it should call SetAttributeL to inform the controller. When the controller
1.117 +changes a setting, the media player application receives a callback via the
1.118 +MPlayerApplicationSettingsNotify interface
1.119 +*/
1.120 +class MPlayerApplicationSettingsObserver
1.121 + {
1.122 + public:
1.123 + /**
1.124 + Define an attribute supported by this player.
1.125 + It will be included in future responses to the following PDUs:
1.126 + ListPlayerApplicationSettingAttributes,
1.127 + ListPlayerApplicationSettingValues,
1.128 + GetCurrentPlayerApplicationSettingValue,
1.129 + GetPlayerApplicationSettingAttributeText,
1.130 + GetPlayerApplicationSettingValueText,
1.131 + @param aAttributeID The specification or player defined attribute
1.132 + @param aAttributeText The UTF8 text name of the attribute(allowed text length is 1-255) - the API will take a copy
1.133 + @param aValues The list of defined values
1.134 + @param aValueTexts The UTF8 text for each defined value(allowed text length is 1-255) - The API will make copies.
1.135 + @param aInitialValue The initial value for this attribute
1.136 + @leave KErrNoMemory if memory could not be allocated to store the copies of aAttributeID and relative settings
1.137 + @leave KErrNotSupported if attribute or value is out of specification defined range,
1.138 + or aValueTexts is not equal length to aValues
1.139 + */
1.140 + IMPORT_C void DefineAttributeL(TUint aAttributeID,
1.141 + TDesC8& aAttributeText,
1.142 + RArray<TUint> &aValues,
1.143 + RArray<TPtrC8> &aValueTexts,
1.144 + TUint aInitialValue);
1.145 +
1.146 + /**
1.147 + Set the current value of a previously defined attribute
1.148 + This updates the cache and will cause completion of a
1.149 + pending EVENT_PLAYER_APPLICATION_SETTING_CHANGED notification PDU
1.150 + @param aAttributeID The specification or player defined attribute
1.151 + @param aValue The current value
1.152 + @leave KErrNotFound if the attribute is not defined,
1.153 + KErrArgument if the value is not valid according to the definition
1.154 + */
1.155 + IMPORT_C void SetAttributeL(TUint aAttributeID, TUint aValue);
1.156 +
1.157 + private:
1.158 + virtual void DoDefineAttributeL(TUint aAttributeID,
1.159 + TDesC8& aAttributeText,
1.160 + RArray<TUint> &aValues,
1.161 + RArray<TPtrC8> &aValueTexts,
1.162 + TUint aInitialValue) = 0;
1.163 + virtual void DoSetAttributeL(TUint aAttributeID, TUint aValue) = 0;
1.164 +
1.165 + };
1.166 +
1.167 +/**
1.168 +This is a helper API allowing CPlayerApplicationSettings to be initialised
1.169 +via a resource file. Using a resource file may help to provide localised text
1.170 +for the attributes and values, according to current language setting of the phone.
1.171 +*/
1.172 +class PlayerApplicationSettingsResourceInit
1.173 + {
1.174 + public:
1.175 + /**
1.176 + Defines multiple attributes supported by this player, which are listed in a resource file.
1.177 + @param aSettings The CPlayerApplicationSettings object on which the attributes should be defined
1.178 + @param aResource A fully constructed CResourceFile
1.179 + @leave KErrNoMemory, or leave from CResourceFile functions
1.180 + */
1.181 + IMPORT_C static void DefineAttributesL(MPlayerApplicationSettingsObserver& aSettings, CResourceFile &aResource);
1.182 + };
1.183 +
1.184 +/**
1.185 +This class supports the notification PDUs in AVRCP1.3 specification section 5.4,
1.186 +with the following exceptions:
1.187 + EVENT_SYSTEM_STATUS_CHANGED is not supported, it is only for adaptors that plug into a media player
1.188 + EVENT_PLAYER_APPLICATION_SETTING_CHANGED is supported through the CPlayerApplicationSettings API
1.189 +
1.190 +Events are pushed by the media player calling functions in this API, where they are
1.191 +cached until the controller pulls them via a GetPlayStatus or RegisterNotification PDU
1.192 +@see CPlayerApplicationSettings
1.193 +*/
1.194 +class MPlayerEventsObserver
1.195 + {
1.196 + public:
1.197 + enum TTargetBatteryStatus
1.198 + {
1.199 + ENormal = 0,
1.200 + EWarning = 1,
1.201 + ECritical = 2,
1.202 + EExternal = 3,
1.203 + EFullCharge = 4,
1.204 + EUnknown = 5
1.205 + };
1.206 +
1.207 + enum TPlaybackStatus
1.208 + {
1.209 + EStopped = 0,
1.210 + EPlaying = 1,
1.211 + EPaused = 2,
1.212 + EFwdSeek = 3,
1.213 + ERevSeek = 4,
1.214 + EError = 0xFF
1.215 + };
1.216 +
1.217 + enum TPlayPosition
1.218 + {
1.219 + EStart = 0,
1.220 + EMiddle = 1,
1.221 + EEnd= 2,
1.222 + };
1.223 +
1.224 + static const TUint64 KNoTrackSelected = KMaxTUint64;
1.225 +
1.226 + static const TUint32 KPlaybackPositionUnknown = 0xFFFFFFFF;
1.227 +
1.228 + /**
1.229 + Call this function whenever the playback status changes.
1.230 + It will be used to complete pending EVENT_PLAYBACK_STATUS_CHANGED
1.231 + and EVENT_PLAYBACK_POS_CHANGED notifications.
1.232 + The value is used to generate the response to a GetPlayStatus PDU.
1.233 + @param aStatus The specification defined playback status
1.234 + */
1.235 + IMPORT_C void PlaybackStatusChanged(TPlaybackStatus aStatus);
1.236 + /**
1.237 + Call this function whenever the current media track is changed.
1.238 + use KNoTrackSelected to indicate that there is no media selected.
1.239 + This is the default value on construction. It will be used to
1.240 + complete pending EVENT_TRACK_CHANGED and EVENT_PLAYBACK_POS_CHANGED notifications.
1.241 + The values are used to generate the response to a GetPlayStatus PDU.
1.242 + @param aTrackId A handle to the current track.
1.243 + @param aLengthInMilliseconds The length of the current track.
1.244 + */
1.245 + IMPORT_C void TrackChanged(TUint64 aTrackId, TUint32 aLengthInMilliseconds);
1.246 + /**
1.247 + Call this function whenever the current track reaches the end position,
1.248 + e.g. due to playback or forward seek. It will be used to complete
1.249 + pending EVENT_TRACK_REACHED_END and EVENT_PLAYBACK_POS_CHANGED notifications.
1.250 + */
1.251 + IMPORT_C void TrackReachedEnd();
1.252 + /**
1.253 + Call this function whenever the current track reaches the start position,
1.254 + e.g. due to reverse seek (rewind). It will be used to complete pending
1.255 + EVENT_TRACK_REACHED_START and EVENT_PLAYBACK_POS_CHANGED notifications.
1.256 + */
1.257 + IMPORT_C void TrackReachedStart();
1.258 + /**
1.259 + Call this function during playback or seek operations, to indicate the
1.260 + current position within the track. It will be used to complete a pending
1.261 + EVENT_PLAYBACK_POS_CHANGED notification. The value is used to generate the
1.262 + response to a GetPlayStatus PDU.
1.263 + @param aMilliseconds The current playback position. It is recommended to call
1.264 + with a resolution <=1000ms to satisfy the 1s resolution of the notification
1.265 + playback interval.
1.266 + */
1.267 + IMPORT_C void SetPlaybackPosition(TUint32 aMilliseconds);
1.268 +
1.269 + /**
1.270 + Call this function to report the current battery status
1.271 + @param aBatteryStatus The current battery status.
1.272 + */
1.273 + IMPORT_C void SetBatteryStatus(TTargetBatteryStatus aBatteryStatus);
1.274 +
1.275 + private:
1.276 + virtual void DoPlaybackStatusChanged(TPlaybackStatus aStatus) = 0;
1.277 + virtual void DoTrackChanged(TUint64 aTrackId, TUint32 aLengthInMilliseconds) = 0;
1.278 + virtual void DoTrackReachedEnd() = 0;
1.279 + virtual void DoTrackReachedStart() = 0;
1.280 + virtual void DoSetPlaybackPosition(TUint32 aMilliseconds) = 0;
1.281 + virtual void DoSetBatteryStatus(TTargetBatteryStatus aBatteryStatus) = 0;
1.282 +
1.283 +
1.284 + };
1.285 +
1.286 +/**
1.287 +Clients must implement this interface if they require callbacks
1.288 +when the controller has changed the settings via a SetPASValue message
1.289 +*/
1.290 +class MPlayerApplicationSettingsNotify
1.291 + {
1.292 + public:
1.293 + /**
1.294 + This is called when the controller has changed a setting
1.295 + @param aAttributeID A list of attribute IDs whose value has changed.
1.296 + @param aAttributeValue A list of new values for the attributes listed in aAttributeID.
1.297 + */
1.298 + virtual void MpasnSetPlayerApplicationValueL(const RArray<TInt>& aAttributeID,
1.299 + const RArray<TInt>& aAttributeValue)=0;
1.300 + };
1.301 +
1.302 +
1.303 +#endif // REMCONPLAYERINFORMATIONTARGETOBSERVER_H