--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/datacommsserver/esockserver/inc/ss_nodemessages_selector.h~ Thu Jan 07 13:34:53 2010 +0200
@@ -0,0 +1,693 @@
+// Copyright (c) 2005-2009 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"
+// which accompanies this distribution, and is available
+// at the URL "http://www.symbianfoundation.org/legal/sfl-v10.html".
+//
+// Initial Contributors:
+// Nokia Corporation - initial contribution.
+//
+// Contributors:
+//
+// Description:
+//
+
+/**
+ @file
+ @publishedPartner
+ @released
+*/
+
+#ifndef SYMBIAN_NODEMESSAGES_SELECTOR_H
+#define SYMBIAN_NODEMESSAGES_SELECTOR_H
+
+#include <connpref.h>
+#include <comms-infras/metadata.h>
+#include <elements/nm_signatures.h>
+
+#include <comms-infras/ss_nodemessages.h>
+#include <comms-infras/cfmacro.h>
+#include <comms-infras/api_ext_msg.h>
+
+#include <es_enum.h>
+#include <comms-infras/ss_commsprov.h>
+#include <comms-infras/es_availability.h>
+
+namespace ConnStates
+{
+ class TSelectMetaPlane;
+}
+
+class TConnProviderInfo;
+
+namespace ESock
+{
+
+/**
+TConnProviderInfo based preferences. Can be passed into RConnection::Start
+to specify what connection should be started. The handling of this preference
+is implementation specific.
+
+@publishedPartner
+@released
+*/
+
+class TConnProviderInfoPref : public TConnPref
+ {
+public:
+ IMPORT_C explicit TConnProviderInfoPref(const TConnProviderInfo& aProviderInfo);
+
+ IMPORT_C const TConnProviderInfo& Info() const;
+ };
+
+/**
+Selection preferences object used internally by the 3 plane comms implementation.
+
+@publishedPartner
+@released
+*/
+class TSelectionPrefs : public Meta::SMetaData
+ {
+public:
+ /**
+ Uid and TypeId for SMetaData
+ */
+ enum {EUid = 0x10272C79, ETypeId = 1};
+
+ /**
+ Scopes for which the selection can take place.
+
+ Each of the flags may be set, alone, all or in any combinations
+ */
+ enum TSelectionScope
+ {
+ /**
+ For initialisation only
+ */
+ ENone = 0x00,
+ /**
+ Select only from preexisting providers. Do not create new ones.
+ */
+ ESelectFromExisting = 0x01,
+ /**
+ Select only the top provider.
+ */
+ EExplicitConnection = 0x02,
+ /**
+ Do not request a comms binder.
+ */
+ ERequestCommsBinder = 0x04
+ };
+
+ /**
+ Flags to indicate what type of selection is taking place.
+ */
+ enum TSelectionFlags
+ {
+ /**
+ Selecting for a monitor access point. This access point does not affect the idleness
+ of a node.
+ */
+ EMonitor = 0x01,
+ /**
+ Selecting for an access point wishing to attach to a specified access point which
+ already exists
+ */
+ EAttach = 0x02
+ };
+
+public:
+ IMPORT_C TSelectionPrefs();
+ /**
+ @param aSelectionScope Scope for which the selection will take place
+ */
+ IMPORT_C TSelectionPrefs(TSelectionScope aSelectionScope);
+ /**
+ @param aPref Preferences used to decide which access point to select
+ */
+ IMPORT_C TSelectionPrefs(const TConnPref& aPref);
+
+ /**
+ @param aPref Preferences used to decide which access point to select
+ */
+ inline void SetPrefs(const TConnPref& aPref);
+
+ /**
+ @return Mutable connection preferences of this selection preference.
+ */
+ inline TConnPref& Prefs();
+
+ /**
+ @return Immutable connection preferences of this selection preference.
+ */
+ inline const TConnPref& Prefs() const;
+
+ /**
+ @return ETrue if no preferences has been set in the selection preferences object
+ */
+ inline TBool IsEmpty() const;
+
+ /**
+ @return the scope of the selection preferences
+ */
+ inline TUint Scope() const;
+
+ /**
+ @param aScope a new scope for the selection preferences
+ */
+ inline void SetScope(TUint aScope);
+
+ /**
+ @return The flags which have been set for the selection preferences
+ */
+ inline TUint Flags() const;
+
+ /**
+ @param aFlags New flags for set for the selection preferences. Overwrites the old flags
+ */
+ inline void SetFlags(TUint aFlags);
+
+ /**
+ @return The subsession unique id of the subsession which initiated this selection
+ */
+ inline TSubSessionUniqueId SubSessionUniqueId() const;
+
+ /**
+ @param aSubSessionUniqueId The subsession unique id of the subsession initiated this selection
+ */
+ inline void SetSubSessionUniqueId(TSubSessionUniqueId aSubSessionUniqueId);
+
+ EXPORT_DATA_VTABLE_AND_FN
+
+private:
+ TConnPref iPrefs;
+ union
+ {
+ TUint iSelectionParams; //used by meta data offset
+ struct //used by node
+ {
+ TUint iScope : 16;
+ TUint iFlags : 16;
+ } iS;
+ } iU;
+ TSubSessionUniqueId iSubSessionUniqueId;
+ };
+
+void TSelectionPrefs::SetPrefs(const TConnPref& aPref)
+ {
+ iPrefs = aPref;
+ }
+
+TConnPref& TSelectionPrefs::Prefs()
+ {
+ return iPrefs;
+ }
+
+const TConnPref& TSelectionPrefs::Prefs() const
+ {
+ return iPrefs;
+ }
+
+TBool TSelectionPrefs::IsEmpty() const
+ {
+ return iPrefs.ExtensionId() == TConnPref::EConnPrefUnknown;
+ }
+
+TUint TSelectionPrefs::Scope() const
+ {
+ return iU.iS.iScope;
+ }
+
+void TSelectionPrefs::SetScope(TUint aScope)
+ {
+ iU.iS.iScope = aScope;
+ }
+
+TUint TSelectionPrefs::Flags() const
+ {
+ return iU.iS.iFlags;
+ }
+
+void TSelectionPrefs::SetFlags(TUint aFlags)
+ {
+ iU.iS.iFlags = aFlags;
+ }
+
+TSubSessionUniqueId TSelectionPrefs::SubSessionUniqueId() const
+ {
+ return iSubSessionUniqueId;
+ }
+
+void TSelectionPrefs::SetSubSessionUniqueId(TSubSessionUniqueId aSubSessionUniqueId)
+ {
+ iSubSessionUniqueId = aSubSessionUniqueId;
+ }
+
+/**
+Selection preferences override. By default a mcpr will select using the selection prefs
+which were used to create it. The selection preferences override can be used to make them use
+something else.
+
+@publishedPartner
+@released
+*/
+class TOverridenSelectionPrefsExt : public Meta::SMetaData
+ {
+public:
+ enum {EUid = 0x10272C79, ETypeId = 2};
+
+public:
+ /**
+ @param aTierId The tier on which the preferences will be used
+ @param aPrefs The preferences which will override the default preferences
+ */
+ IMPORT_C explicit TOverridenSelectionPrefsExt(TUid aTierId, const TSelectionPrefs& aPrefs);
+
+ EXPORT_DATA_VTABLE_AND_FN
+
+ TSelectionPrefs iPrefs;
+ TUid iTierId;
+ };
+
+/**
+Panic catagory for RConnPrefList panics
+*/
+_LIT (RConnPrefListPanic,"RConnPrefListPanic");
+
+/**
+Null element panic code. An attempt was made to access an element in the
+preferences list that didn't exist
+*/
+const TInt ENullElement = 1;
+
+/**
+This class will be used as a handle to TConnPrefList. During construction of
+the stack this class will be sent in messages as TConnPrefList cannot be sent
+in every message. The overhead of this would be too great (as it would have to
+be serialized and deserialized every time the message was sent). A reference
+cannot be sent as this would not work across processes.
+
+
+@publishedPartner
+@released
+*/
+class RConnPrefList
+ {
+ friend class ConnStates::TSelectMetaPlane;
+public:
+ /**
+ Base class for RConnPrefList iterators
+ */
+ class TIterBase
+ {
+ protected:
+ /**
+ @param aConnPrefList Connection preference list to iterate over
+ */
+ TIterBase(RConnPrefList &aConnPrefList)
+ : iConnPrefList(aConnPrefList), iMasterIndex(0)
+ {
+
+ }
+
+ /**
+ @param aType Only return preferences of this type
+ @param aIndex Index of preference requested
+ @return The requested connection preference, or NULL if no preference of the specified type was found at aIndex
+ */
+ IMPORT_C Meta::SMetaData* AtIndex(const Meta::STypeId& aType, TInt aIndex);
+
+ protected:
+ RConnPrefList& iConnPrefList;
+ TInt iMasterIndex;
+ };
+
+ template<class TYPE>
+ /**
+ This iterator will return objects of the templated class. It will only
+ return objects from the list that are of the type passed in as the template parameter
+ */
+ class TIter : public TIterBase
+ {
+ public:
+ /**
+ @param aConnPrefList Connection preferences to iterate over
+ */
+ TIter(RConnPrefList &aConnPrefList)
+ : TIterBase(aConnPrefList)
+ {
+ iIndex = 0;
+ }
+
+ /**
+ This will return the instance of the given type in the list at the
+ point specified by aIndex
+
+ @param aIndex index of item to return
+ @return The item found at the index, or NULL if not found
+ */
+ TYPE* operator[](TInt aIndex)
+ {
+ return static_cast<TYPE*>(AtIndex(Meta::STypeId::CreateSTypeId(TYPE::EUid,TYPE::ETypeId) , aIndex));
+ }
+
+ /**
+ @return the next instance of the given tpye in the list or NULL if no more instances remain
+ */
+ TYPE* operator++(TInt)
+ {
+ return static_cast<TYPE*>((*this)[iIndex++]);
+ }
+
+ /**
+ @return a reference to the current object pointed to by the iterator
+ */
+ TYPE& operator*()
+ {
+ TYPE* ptr = static_cast<TYPE*>(iConnPrefList[iMasterIndex]);
+ __ASSERT_ALWAYS(ptr != NULL,User::Panic(RConnPrefListPanic, ENullElement));
+ return *ptr;
+ }
+
+ /**
+ @return a pointer to the current object pointed to by the iterator
+ */
+ TYPE* operator->()
+ {
+ TYPE* ptr = static_cast<TYPE*>(iConnPrefList[iMasterIndex]);
+ return ptr;
+ }
+
+ /**
+ @return ETrue if there are no more elements to iterate over. EFalse, otherwise
+ */
+ TBool IsEnd()
+ {
+ if((*this)[iIndex] == NULL)
+ {
+ return ETrue;
+ }
+ else
+ {
+ return EFalse;
+ }
+ }
+
+ /**
+ Remove the current object from the iterators associated RConnPrefList
+ @return a pointer to the removed object
+ */
+ TYPE* Remove()
+ {
+ TYPE* ptr = static_cast<TYPE*>(iConnPrefList[iMasterIndex]);
+ iConnPrefList.Remove(iMasterIndex);
+ (*this)[iIndex];
+ return ptr;
+ }
+
+ private:
+ TInt iIndex;
+ };
+
+public:
+ IMPORT_C RConnPrefList();
+
+ /**
+ Open and initialise with data from passed in RConnPrefList
+ @param aPrefList RConnPrefList to copy data from. The copy is shallow.
+ */
+ IMPORT_C void Open(RConnPrefList& aPrefList);
+
+ /**
+ Close the RConnPrefList object
+ */
+ IMPORT_C void Close();
+
+ /**
+ Create an iterator for template parameter TYPE. The iterator will be able to
+ iterate over all the members of the RConnPrefList which match the type specified.
+ @return A new iterator object for this connection preferences list
+ */
+ template<class TYPE>
+ RConnPrefList::TIter<TYPE> getIter()
+ {
+ return RConnPrefList::TIter<TYPE>(*this);
+ }
+
+ /**
+ Append a preference to connection preferences list
+ @param aFamily Preference to append
+ @leave System wide error code.
+ */
+ IMPORT_C void AppendL(SMetaDataECom* aFamily);
+
+ /**
+ @param aIndex index of requested object
+ @return The object at aIndex
+ */
+ IMPORT_C SMetaData* operator[](TInt aIndex);
+
+ /**
+ Remove an object from the RConnPrefList
+ @param aIndex the index of the object to remove
+ */
+ IMPORT_C void Remove(TInt aIndex);
+
+ /**
+ @return the number of preferences in the list
+ */
+ IMPORT_C TInt Count();
+
+private:
+ TInt Open(TConnPrefList* aObject);
+ TConnPrefList* iObject;
+ };
+
+
+/**
+Signature for a message which can carry selection preferences
+*/
+struct TSigSelectionPrefs : public Messages::TSignatureBase
+ {
+protected:
+ inline TSigSelectionPrefs() {}
+
+ /**
+ @param aMessageId Id of the message this signature is being created for.
+ */
+ TSigSelectionPrefs(const Messages::TNodeSignal::TMessageId& aMessageId)
+ : Messages::TSignatureBase(aMessageId)
+ {}
+
+ /**
+ @param aMessageId Id of the message this signature is being created for.
+ @param aSelectionPrefs Selection preferences object to be passed in the message
+ */
+ TSigSelectionPrefs(const Messages::TNodeSignal::TMessageId& aMessageId, const Meta::SMetaData& aSelectionPrefs)
+ : Messages::TSignatureBase(aMessageId)
+ {
+ //TODO: the copy can be optimised out when SMetaDataNetCtr handlers supported.
+ iSelectionPrefs.Copy(aSelectionPrefs);
+ }
+public:
+ DECLARE_MVIP_CTR(TSigSelectionPrefs)
+ EXPORT_DATA_VTABLE_AND_FN
+
+ /**
+ Selection preferences object passed in the message
+ */
+ TSelectionPrefs iSelectionPrefs;
+ };
+
+/**
+Signature for a message which can carry a list of connection preferences
+*/
+struct TSigConnPrefList : public Messages::TSignatureBase
+ {
+protected:
+ inline TSigConnPrefList() {}
+
+ /**
+ @param aMessageId Id of the message this signature is being created for.
+ */
+ TSigConnPrefList(const Messages::TNodeSignal::TMessageId& aMessageId)
+ : Messages::TSignatureBase(aMessageId)
+ {}
+
+ /**
+ @param aMessageId Id of the message this signature is being created for.
+ @param aConnPrefList List of connection preferences to be passed in this message
+ */
+ TSigConnPrefList(const Messages::TNodeSignal::TMessageId& aMessageId, RConnPrefList& aConnPrefList)
+ : Messages::TSignatureBase(aMessageId)
+ {
+ iConnPrefList = aConnPrefList;
+ }
+public:
+ DECLARE_MVIP_CTR(TSigConnPrefList)
+ EXPORT_DATA_VTABLE_AND_FN
+
+ /**
+ List of connection preferences passed in this message
+ */
+ RConnPrefList iConnPrefList;
+ };
+
+
+/**
+Message signature template for a message which can carry selection preferences
+
+@see TSigSelectionPrefs
+*/
+template<TInt id, TInt32 realm>
+struct TMessageSigSelectionPrefs : public TSigSelectionPrefs, public Messages::TSignatureBase::TTypeToMessageId<id, realm>
+ {
+ explicit TMessageSigSelectionPrefs() :
+ TSigSelectionPrefs(Messages::TNodeSignal::TMessageId(id, realm))
+ { }
+
+ explicit TMessageSigSelectionPrefs(const Meta::SMetaData& aSelectionPrefs)
+ : TSigSelectionPrefs(Messages::TNodeSignal::TMessageId(id, realm), aSelectionPrefs)
+ {
+ }
+ };
+
+/**
+Message signature template for a message which can carry a list of connection preferences
+
+@see TSigConnPrefList
+*/
+template<TInt id, TInt32 realm>
+ struct TMessageSigConnPrefList : public TSigConnPrefList, public Messages::TSignatureBase::TTypeToMessageId<id, realm>
+ {
+ explicit TMessageSigConnPrefList()
+ : TSigConnPrefList(Messages::TNodeSignal::TMessageId(id, realm))
+ {}
+
+ explicit TMessageSigConnPrefList(RConnPrefList& aCustomPrefs)
+ : TSigConnPrefList(Messages::TNodeSignal::TMessageId(id, realm), aCustomPrefs)
+ {}
+ };
+
+/**
+Signature for a select complete message.
+*/
+struct TSigSelectComplete : public Messages::TSignatureBase
+ {
+protected:
+ inline TSigSelectComplete() {}
+
+ /**
+ @param aMessageId Id of the message this signature is being created for.
+ @param aNodeId Node id of node which has been created
+ @param aProviderInfo Provider info of access point which has been created.
+ */
+ TSigSelectComplete(const Messages::TNodeSignal::TMessageId& aMessageId, const Messages::TNodeId& aNodeId, const TProviderInfo& aProviderInfo)
+ : Messages::TSignatureBase(aMessageId),
+ iNodeId(aNodeId),
+ iProviderInfo(aProviderInfo)
+ {
+ }
+public:
+ DECLARE_MVIP_CTR(TSigSelectComplete)
+ EXPORT_DATA_VTABLE_AND_FN
+ /**
+ Node id of node which has been created
+ */
+ Messages::TNodeId iNodeId;
+ /**
+ Provider info of the access point which has been created
+ */
+ TProviderInfo iProviderInfo;
+ };
+
+/**
+Message signature template for a select complete message
+
+@see TSigSelectComplete
+ */
+template<TInt id, TInt32 realm>
+struct TMessageSigSelectComplete : public TSigSelectComplete, public Messages::TSignatureBase::TTypeToMessageId<id, realm>
+ {
+ explicit TMessageSigSelectComplete(const Messages::TNodeId& aNodeId, const TProviderInfo aProviderInfo)
+ : TSigSelectComplete(Messages::TNodeSignal::TMessageId(id, realm), aNodeId, aProviderInfo)
+ {
+ }
+ };
+
+/**
+Message signature template for availability subscription message
+ */
+DECLARE_MESSAGE_SIG_1(SigAvailabilitySubscriptionOptions, TAvailabilitySubscriptionOptions, AvailabilitySubscriptionOptions)
+/**
+Message signature for availability status message
+*/
+DECLARE_MESSAGE_SIG_1(SigAvailabilityStatus, TAvailabilityStatus, AvailabilityStatus)
+
+/**
+Message interface for selector nodes
+Nodes wishing to implement this interface must implement all message protocols in the interface.
+
+@publishedPartner
+@released
+*/
+class TCFSelector
+ {
+ private:
+ enum
+ {
+ ECFSimpleSelect = 1,
+ ECFSelect = 2,
+ ECFSelectComplete = 3
+ };
+
+public:
+ enum { ERealmId = 0x10285F4E }; //UID allocated on 4/6/08 from KUidNodeMessageRealms
+
+ /**
+ Selection request sent to TierManagers (usually by MCPRs). Can only carry one type of selection preferences at a time, and for this
+ reason, using TSelect is preferred. It should be noted however, that multiple nodes may be returned in exchange for this single
+ preference, for example in the case of SNAP preferences.
+
+ This request is completed only after TSelectComplete with a NULL address has been received by the requestor.
+
+ @li Type: Request
+ @li Fallible: Yes
+
+ @param iSelectionPrefs preferences used by the selection process to choose nodes
+ */
+ typedef TMessageSigSelectionPrefs<ECFSimpleSelect, TCFSelector::ERealmId> TSimpleSelect;
+
+
+ /**
+ Selection request sent to Tier Managers (usually by MCPRs or CSR). Carries an RConnPrefList instance, the objects in the list are used
+ during the construction of the stack. Multiple nodes may be returned by the selection activity. This request is completed only after
+ TSelectComplete with a NULL address has been received by the requestor.
+
+ @li Type: Request
+ @li Fallible: Yes
+
+ @param aConnPrefList an instance of RConnPrefList
+ */
+ typedef TMessageSigConnPrefList<ECFSelect, TCFSelector::ERealmId> TSelect;
+
+ /**
+ Response to TSelect or TSelectNextLayer. Carries address to selected providers (MCPRs). A selection request is completed only after
+ TSelectComplete with a NULL address has been received by the requestor. This response also carries some additional information about
+ the selected provider.
+
+ @li Type: Response to TSimpleSelect or TSelect
+ @li Fallible: No
+
+ @param iNodeId node id of the node which has been selected
+ @param iProviderInfo additional information about the created node
+ */
+ typedef TMessageSigSelectComplete<ECFSelectComplete, TCFSelector::ERealmId> TSelectComplete;
+ };
+
+} //namespace esock
+
+#endif
+//SYMBIAN_NODEMESSAGES_SELECTOR_H
+