diff -r 000000000000 -r 4e1aa6a622a0 accessoryservices/remotecontrolfw/targetselectorplugin/public/remcontargetselectorplugininterface.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/accessoryservices/remotecontrolfw/targetselectorplugin/public/remcontargetselectorplugininterface.h Tue Feb 02 00:53:00 2010 +0200 @@ -0,0 +1,344 @@ +// Copyright (c) 2004-2009 Nokia Corporation and/or its subsidiary(-ies). +// All rights reserved. +// This component and the accompanying materials are made available +// under the terms of "Eclipse Public License v1.0" +// which accompanies this distribution, and is available +// at the URL "http://www.eclipse.org/legal/epl-v10.html". +// +// Initial Contributors: +// Nokia Corporation - initial contribution. +// +// Contributors: +// +// Description: +// + +/** + @file + @publishedPartner + @released +*/ + +#ifndef TARGETSELECTORPLUGININTERFACE_H +#define TARGETSELECTORPLUGININTERFACE_H + +#include + +class MRemConTargetSelectorPluginObserver; +class TRemConAddress; +class TClientInfo; +class TBearerSecurity; +class TClientInfoConstIter; + +/** +The UID of this version of the Target Selector Plugin interface. +*/ +const TInt KRemConTargetSelectorInterface1 = 0x10208BCD; + + +/** +Abstract base class for target selector plugins. +*/ +class MRemConTargetSelectorPluginInterface + { +public: + /** + Called by RemCon to get the TSP to address an outgoing command (from a + connectionless controller client) to zero or more remotes. The implementor + should add zero or more items to aConnections and then call + OutgoingCommandAddressed on the observer with an appropriate error. + Note that only one of AddressOutgoingCommand and PermitOutgoingCommand is + outstanding at once. + The implementor is responsible for the capability check. For this reason, + aSender contains the client's current send message, and aBearerSecurity + contains all the bearer security policies. To reiterate, RemCon does no + security check on the client's send request either before calling + AddressOutgoingCommand. + @param aInterfaceUid The UID of the client interface. + @param aOperationId The operation ID of the command. + @param aSender The TClientInfo of the sending session. + @param aConnections An empty collection of connections. NB On completion, + an actual (bearer-level) connection does not need to exist for each item + in the collection- RemCon passes responsibility to the bearer(s) for + creating the specified connections. On successful completion, RemCon takes + ownership of any items in the collection- new TRemConAddresses must be + made on the heap. + @param aBearerSecurity Contains all the bearer security policies. + */ + virtual void AddressOutgoingCommand( + TUid aInterfaceUid, + TUint aOperationId, + const TClientInfo& aSender, + TSglQue& aConnections, + TSglQue& aBearerSecurity) = 0; + + /** + Called by RemCon to find out from the TSP whether the given + connection-oriented controller client is permitted to send the given + command to the given remote at this time. The implementor should call + PermitOutgoingCommand with either ETrue, if the send is permitted, or + EFalse, if the send is not permitted. + Note that only one of AddressOutgoingCommand and PermitOutgoingCommand is + outstanding at once. + Note that a capability check will have been done by RemCon before + PermitOutgoingCommand is called- actually at GoConnectionOriented time. + @param aInterfaceUid The UID of the client interface. + @param aOperationId The operation ID of the command. + @param aSender The TClientInfo of the sending session. + @param aConnection The remote the command will be sent over if permission + is granted. + */ + virtual void PermitOutgoingCommand( + TUid aInterfaceUid, + TUint aOperationId, + const TClientInfo& aSender, + const TRemConAddress& aConnection) = 0; + + /** + Called by RemCon to cancel the current AddressOutgoingCommand or + PermitOutgoingCommand command. + On receipt, the TSP must stop dereferencing any data given in the + AddressOutgoingCommand or PermitOutgoingCommand request. The TSP should + not subsequently call OutgoingCommandAddressed or + OutgoingCommandPermitted, except in response to a subsequent new + AddressOutgoingCommand or PermitOutgoingCommand command. + If an AddressOutgoingCommand request is currently being processed, the TSP + is responsible for deleting any TRemConAddresses it has already created. + */ + virtual void CancelOutgoingCommand() = 0; + + /** + Called by RemCon to get the TSP to address an incoming command (from a + remote to zero or more target clients). The implementor should add or + remove zero or more items from aClients and then call + IncomingCommandAddressed on the observer with a suitable error. + @param aInterfaceUid The UID of the client interface. + @param aOperationId The operation ID of the command. + @param aClients A collection of existing target clients. The implementor + may wish to start further target client(s) and add their process ID(s) to + this collection. New TClientInfo items must be made on the stack. Note + that when adding a TClientInfo to aClients, only the process ID needs to + be correctly populated. + There is no 'cancel' method for AddressIncomingCommand. RemCon will only + want to 'cancel' this when the server is terminating, at which point it + will destroy the TSP anyway. + */ + virtual void AddressIncomingCommand( + TUid aInterfaceUid, + TUint aOperationId, + TSglQue& aClients) = 0; + + }; + +/** +The UID of this version of the Target Selector Plugin interface. +*/ +const TInt KRemConTargetSelectorInterface2 = 0x102858CF; + +/** +Additional functions for TSP Interface V2 +*/ +class MRemConTargetSelectorPluginInterfaceV2: public MRemConTargetSelectorPluginInterface + { +public: + /** + Called by RemCon to get the TSP to decide which client should be + allowed to respond to a command. + This function is called as soon as each client returns a response, so + the order in which clients are offered to the TSP is not predetermined. + Since AV/C expects only a single response, the first response allowed by + the TSP is the one which will be sent on-air. + The initial list of clients will be populated from the TSP's response + to AddressIncomingCommand(). + @param aInterfaceUid The UID of the client interface. + @param aOperationId The operation ID of the command. + @param aClient The client which is trying to send a response + @param aClients A list of clients which are still expected to respond, + including the one specified in aClient + */ + + virtual void PermitOutgoingResponse( + TUid aInterfaceUid, + TUint aOperationId, + const TClientInfo& aClient, + TClientInfoConstIter& aClients) = 0; + + /** + Called by RemCon to get the TSP to address an incoming notify (from a + remote to zero or more target clients). The implementor should call + IncomingNotifyAddressed on the observer with a pointer to the chosen + client (or NULL if no client is to be addressed) from the list, and a + suitable error. + @param aInterfaceUid The UID of the client interface. + @param aOperationId The operation ID of the command. + @param aClients A collection of existing target clients. The implementor + may wish to start a target client and call IncomingNotifyAddressed + with a new TClientInfo. The new TClientInfo item must be made on the stack. + Note when creating the new TClientInfo, only the process ID needs to + be correctly populated. + */ + virtual void AddressIncomingNotify( + TUid aInterfaceUid, + TUint aOperationId, + TSglQue& aClients) = 0; + + /** + Called by RemCon to cancel the current PermitOutgoingResponse request. + On receipt, the TSP must stop dereferencing any data given in the + PermitOutgoingResponse request. The TSP should not subsequently call + OutgoingResponsePermitted, except in response to a subsequent new + PermitOutgoingResponse request. + */ + virtual void CancelOutgoingResponse() = 0; + }; + +/** +The UID of this version of the Target Selector Plugin interface. +*/ +const TInt KRemConTargetSelectorInterface3 = 0x102858D3; + +/** +Additional functions for TSP Interface V3 + +This interface must be implemented if the TSP wishes to support outgoing +Notify commands (local role controller). +*/ +class MRemConTargetSelectorPluginInterfaceV3 + { +public: + /** + Called by RemCon to get the TSP to address an outgoing notify command (from a + connectionless controller client) to zero or one remote. The implementor + need to get the connection list from which to chose the only one target device and then call + OutgoingNotifyCommandAddressed on the observer with an appropriate error. + Note that only one of AddressOutgoingNotifyCommand and PermitOutgoingNotifyCommand is + outstanding at once. + The implementor is responsible for the capability check. For this reason, + aSender contains the client's current send message, and aBearerSecurity + contains all the bearer security policies. To reiterate, RemCon does no + security check on the client's send request either before calling + AddressOutgoingNotify. + @param aInterfaceUid The UID of the client interface. + @param aOperationId The operation ID of the command. + @param aSender The TClientInfo of the sending session. + @param aBearerSecurity Contains all the bearer security policies. + */ + virtual void AddressOutgoingNotify( + TUid aInterfaceUid, + TUint aOperationId, + const TClientInfo& aSender, + TSglQue& aBearerSecurity) = 0; + + /** + Called by RemCon to cancel the current AddressOutgoingNotify or + PermitOutgoingNotifyCommand command. + On receipt, the TSP must stop dereferencing any data given in the + AddressOutgoingNotify or PermitOutgoingNotifyCommand request. The TSP should + not subsequently call OutgoingNotifyCommandAddressed or + OutgoingNotifyCommandPermitted, except in response to a subsequent new + AddressOutgoingNotify or PermitOutgoingNotifyCommand command. + If an AddressOutgoingNotify request is currently being processed, the TSP + is responsible for deleting any TRemConAddresses it has already created. + */ + virtual void CancelOutgoingNotifyCommand() = 0; + + /** + Called by RemCon to find out from the TSP whether the given + connection-oriented controller client is permitted to send the given notify + command to the given remote at this time. The implementor should call + PermitOutgoingNotifyCommand with either ETrue, if the send is permitted, or + EFalse, if the send is not permitted. + Note that only one of AddressOutgoingNotify and PermitOutgoingNotifyCommand is + outstanding at once. + Note that a capability check will have been done by RemCon before + PermitOutgoingNotifyCommand is called- actually at GoConnectionOriented time. + @param aInterfaceUid The UID of the client interface. + @param aOperationId The operation ID of the command. + @param aSender The TClientInfo of the sending session. + @param aConnection The remote the command will be sent over if permission + is granted. + */ + virtual void PermitOutgoingNotifyCommand( + TUid aInterfaceUid, + TUint aOperationId, + const TClientInfo& aSender, + const TRemConAddress& aConnection) = 0; + }; + +/** +The UID of this version of the Target Selector Plugin interface. +*/ +const TInt KRemConTargetSelectorInterface4 = 0x10286A7; + +/** +Additional functions for TSP Interface V4 + +This interface must be implemented if the TSP wishes to support addressing +by the bearer. Bearer addressing will always be used if supported by the +bearer. When bearer addressing is used the TSP will not be given any +option over which client receives a command, however if it implements this +interface it has visibility of where each command goes and can reject the +command if it is not acceptable. + +If this interface is not implemented default implementations of these functions +will be used which will allow the command to be addressed to the bearer's +selected client. This means that if the TSP does not implement this interface +it will not see any commands which have been addressed by the bearer. + +Regardless of whether this interface is implemented commands which are not +addressed by the bearer will continue to be addressed by the TSP via earlier +versions of MRemConTargetSelectorPluginInterface. +*/ +class MRemConTargetSelectorPluginInterfaceV4 + { +public: + /** + Called by RemCon to get the TSP to permit an incoming command. This is called + if the bearer has provided a target client for the command. + + The implementor should decide if they wish to allow this command and then call + IncomingCommandPermitted on the observer with a suitable error. + + @param aInterfaceUid The UID of the client interface. + @param aOperationId The operation ID of the command. + @param aClient a TClientInfo referring to the selected client + */ + virtual void PermitIncomingCommand( + TUid aInterfaceUid, + TUint aOperationId, + const TClientInfo& aClient) = 0; + + /** + Called by RemCon to get the TSP to permit an incoming Notify. This is called + if the bearer has provided a target client for the Notify. + + The implementor should decide if they wish to allow this Notify and then call + IncomingNotifyPermitted on the observer with a suitable error. + + @param aInterfaceUid The UID of the client interface. + @param aOperationId The operation ID of the Notify. + @param aClient a TClientInfo referring to the selected client + */ + virtual void PermitIncomingNotify( + TUid aInterfaceUid, + TUint aOperationId, + const TClientInfo& aClient) = 0; + + /** + Called by RemCon when a bearer that can address commands wishes to + inform the system that there has been a remote user action to + select a different addressed client. + + The bearer will then route addressed commands to this client until + such time as SetRemoteAddressedClient is called again or the TSP + calls SetLocalAddressedClient. + + @param aBearerUid The bearer that has changed its addressed client + @param aClient The RemCon client that is now selected by the bearer + */ + virtual void SetRemoteAddressedClient(const TUid& aBearerUid, + const TClientInfo& aClient) = 0; + }; + + +#endif // TARGETSELECTORPLUGININTERFACE_H