diff -r 000000000000 -r af10295192d8 networkcontrol/qoslib/include/qoslib.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/networkcontrol/qoslib/include/qoslib.h Tue Jan 26 15:23:49 2010 +0200 @@ -0,0 +1,786 @@ + +// 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 "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: +// qoslib.h - This file defines the generic QoS API interface. +// + +#ifndef __QOSLIB_H__ +#define __QOSLIB_H__ + +/** + * @file qoslib.h + * + * QoS API - This file defines the generic QoS API interface. + */ + +#include +#include + +#include +#ifndef SYMBIAN_ENABLE_SPLIT_HEADERS +#include +#endif + +class CQoSParameters; +class CPolicy; + +/** + * Selector for QoS policies. The variables defined in TQoSSelector are used to find QoS policies + * for traffic flows. Not all variables have to be set, the application can specify the variables that it wants to. + * Note: TQoSSelector stores IPv4 addresses in "IPv4-mapped IPv6 address" format. + * + * @publishedPartner + * @released + */ +class TQoSSelector +{ +public: + /** + * Constructor. Initialises all variables to unspecified values. + */ + IMPORT_C TQoSSelector(); + + /** + * Compares if the selectors are equal. + * + * @param aSelector TQoSSelector object that is compared with this object. + * @return ETrue if selectors are equal to this object, otherwise EFalse. + */ + IMPORT_C TInt operator==(const TQoSSelector& aSelector) const; + + /** + * Compares if the selector matches aSocket. + * + * @param aSocket RSocket that is compared with this object. + * @return ETrue if selector created from aSocket is equal to this object, otherwise EFalse. + */ + IMPORT_C TBool Match(RSocket& aSocket) const; + + /** + * Sets the addresses for selector. + * + * @param aSrcAddr Source address. Port must have value <= 65535 (0 is used as uspecified value for a port). + * @param aSrcAddrMask Source address mask. Port must have value <= 65535 (0 is used as uspecified value for a port). + * @param aDstAddr Destination address. Port must have value <= 65535 (0 is used as uspecified value for a port). + * @param aDstAddrMask Destination address mask. Port must have value <= 65535 (0 is used as uspecified value for a port). + * @param aProtocol Protocol id. + * @param aSrcPortMax Maximum source port. Must have value <= 65535 (0 is used as uspecified value for a port). + * @param aDstPortMax Maximum destination port. Must have value <= 65535 (0 is used as uspecified value for a port). + * @return KErrNone if parameters have valid values, otherwise KErrArgument. + */ + IMPORT_C TInt SetAddr(const TInetAddr& aSrcAddr, const TInetAddr& aSrcAddrMask, const TInetAddr& aDstAddr, const TInetAddr& aDstAddrMask, TUint aProtocol, TUint aSrcPortMax, TUint aDstPortMax); + + /** + * Sets the addresses for selector. RSocket is used to fetch addresses and ports for a selector. The resulting + * selector will match only for one socket. NOTE: RSocket::Connect() must be called before calling this method. + * + * @param aSocket RSocket object that is used to set the selector variables. Note: RSocket must be connected + * @return KErrNone if parameters have valid values, otherwise KErrArgument. + */ + IMPORT_C TInt SetAddr(RSocket& aSocket); + + /** + * Sets the source address for selector. + * + * @param aAddr Source address. Port must have value <= 65535 (0 is used as uspecified value for a port). + * @return KErrNone if parameters have valid values, otherwise KErrArgument. + */ + IMPORT_C TInt SetSrc(const TInetAddr& aAddr); + + /** + * Sets the destination address for selector. + * + * @param aAddr Source address. Port must have value <= 65535 (0 is used as uspecified value for a port). + * @return KErrNone if parameters have valid values, otherwise KErrArgument. + */ + IMPORT_C TInt SetDst(const TInetAddr& aAddr); + + /** + * Returns the current source address. + * + * @return Source address. + */ + IMPORT_C TInetAddr GetSrc() const; + + /** + * Returns the current destination address. + * + * @return Destination address. + */ + IMPORT_C TInetAddr GetDst() const; + + /** + * Sets the source address mask. + * + * @param aMask Source address mask. Port must have value <= 65535 (0 is used as uspecified value for a port). + * @return KErrNone if parameters have valid values, otherwise KErrArgument. + */ + IMPORT_C TInt SetSrcMask(const TInetAddr& aMask); + + /** + * Returns the current source address mask. + * + * @return Source address mask. + */ + IMPORT_C TInetAddr GetSrcMask() const; + + /** + * Sets the destination address mask. + * + * @param aMask Destination address mask. Port must have value <= 65535 (0 is used as uspecified value for a port). + * @return KErrNone if parameters have valid values, otherwise KErrArgument. + */ + IMPORT_C TInt SetDstMask(const TInetAddr& aMask); + + /** + * Returns the current destination address mask. + * + * @return Destination address mask. + */ + IMPORT_C TInetAddr GetDstMask() const; + + /** + * Sets the Internet access point identifier. 0 is used as unspecified value. + * + * @param aIapId Value to which to set the IapId. + */ + IMPORT_C void SetIapId(TInt aIapId); + + /** + * Returns the current Internet access point identifier. + * + * @return Internet access point identifier. + */ + IMPORT_C TInt IapId() const; + + /** + * Sets the protocol identifier. 0 is used as unspecified value. + * + * @param aProtocol Value to which to set the protocol id. + */ + IMPORT_C void SetProtocol(TUint aProtocol); + + /** + * Returns the current protocol identifier. + * + * @return Protocol identifier. + */ + IMPORT_C TUint Protocol() const; + + /** + * Sets the maximum source port. Port must have value <= 65535 (0 is used as unspecified value). + * + * @param aMaxPort Value to which to set maximum source port. + * @return KErrNone if aMaxPort has valid values, otherwise KErrArgument. + */ + IMPORT_C TInt SetMaxPortSrc(TUint aMaxPort); + + /** + * Sets the maximum destination port. Port must have value <= 65535 (0 is used as unspecified value). + * + * @param aMaxPort Value to which to set maximum destination port. + * @return KErrNone if aMaxPort has valid values, otherwise KErrArgument. + */ + IMPORT_C TInt SetMaxPortDst(TUint aMaxPort); + + /** + * Returns the maximum source port. + * + * @return Maximum source port. + */ + IMPORT_C TUint MaxPortSrc() const; + + /** + * Returns the maximum destination port. + * + * @return Maximum destination port. + */ + IMPORT_C TUint MaxPortDst() const; + +private: + /** The source address. */ + TInetAddr iSrc; + /** The destination address. */ + TInetAddr iDst; + /** The source address mask. */ + TInetAddr iSrcMask; + /** The destination address mask. */ + TInetAddr iDstMask; + /** The protocol ID. */ + TUint iProtocol; + /** The maximum source port. */ + TUint iSrcPortMax; + /** The maximum destination port. */ + TUint iDstPortMax; + /** The Internet access point identifier. */ + TUint iIapId; +}; + +/** +* @name QoS capabilities. +* +* These are used to notify the application as to the type of QoS support provided. +* @publishedPartner +* @released +*/ +//@{ +/** End-to-end signalling is used, e.g. RSVP. */ +const TUint KQoSSignaled = 0x0001; +/** Signalling is used along some part of end-to-end path. */ +const TUint KQoSPartiallySignaled = 0x0002; +/** No signalling is used, e.g. DiffServ. */ +const TUint KQoSProvisioned = 0x0004; +//@} + +/** + * QoS event types + * @publishedPartner + * @released + */ +enum TQoSEvent + { + /** QoS request failed. */ + EQoSEventFailure=1, + /** QoS request was successful. */ + EQoSEventConfirm, + /** QoS parameters have changed. */ + EQoSEventAdapt, + /** QoS channel is opened. */ + EQoSEventChannel, + /** A socket is attached to a QoS channel. */ + EQoSEventJoin, + /** A socket is detached from a QoS channel. */ + EQoSEventLeave, + /** QoS policy was added to QoS policy database. */ + EQoSEventAddPolicy, + /** QoS policy was searched from the QoS policy database. */ + EQoSEventGetPolicy, + /** QoS policy was deleted. */ + EQoSEventDeletePolicy, + /** QoS policy file was loaded. */ + EQoSEventLoadPolicyFile, + /** QoS policy file was unloaded. */ + EQoSEventUnloadPolicyFile + }; + +/** + * Default mask for QoS events: all events are notified to the application. + * @publishedPartner + * @released + */ +const TUint KQoSEventAll = EQoSEventFailure | EQoSEventConfirm | EQoSEventAdapt | EQoSEventChannel | EQoSEventJoin | EQoSEventLeave | EQoSEventAddPolicy | EQoSEventGetPolicy | EQoSEventDeletePolicy | EQoSEventLoadPolicyFile | EQoSEventUnloadPolicyFile; + +/** + * Base class for QoS events. + * + * @publishedPartner + * @released + */ +class CQoSEventBase : public CBase +{ +public: + /** + * Constructor. Sets the QoS event type. + * + * @param aEventType QoS event type (values defined in enum TQoSEvent). + */ + IMPORT_C CQoSEventBase(TInt aEventType); + + /** + * Returns the QoS event type. + * + * @return QoS event type (values defined in enum TQoSEvent). + */ + IMPORT_C TInt EventType() const; + +private: + /** The QoS event type. */ + TInt iEventType; +}; + +/** + * Class for EQoSEventConfirm event whereby a QoS request was successful + * + * @publishedPartner + * @released + */ +class CQoSConfirmEvent : public CQoSEventBase +{ +public: + /** + * Constructor. Sets the QoS parameters. + * + * @param aParameters QoS parameters. + */ + IMPORT_C CQoSConfirmEvent(CQoSParameters& aParameters); + + /** + * Returns the QoS parameters. + * + * @return QoS parameters. + */ + IMPORT_C CQoSParameters* Parameters() const; + +private: + /** The address of the CQoSParameters parameter supplied during construction. */ + CQoSParameters* iParameters; +}; + +/** + * Class for EQoSEventFailure event whereby a QoS request failed + * + * @publishedPartner + * @released + */ +class CQoSFailureEvent : public CQoSEventBase +{ +public: + /** + * Constructor. Sets the QoS parameters and reason code. + * + * @param aParameters QoS parameters. + * @param aReason Reason code specifies the success or failure of the request. + */ + IMPORT_C CQoSFailureEvent(CQoSParameters& aParameters, TInt aReason); + + /** + * Returns the QoS parameters. + * + * @return QoS parameters. + */ + IMPORT_C CQoSParameters* Parameters() const; + + /** + * Returns the reason code. Reason code specifies the success or failure of the request. + * + * @return Reason code. + */ + IMPORT_C TInt Reason() const; + +private: + /** The address of the CQoSParameters parameter supplied during construction. */ + CQoSParameters* iParameters; + /** The reason code that specifies the success or failure of the request. */ + TInt iReason; +}; + +/** + * Class for EQoSEventAdapt event whereby the QoS parameters have changed + * + * @publishedPartner + * @released + */ +class CQoSAdaptEvent : public CQoSEventBase +{ +public: + /** + * Constructor. Sets the QoS parameters and reason code. + * + * @param aParameters QoS parameters. + * @param aReason Reason code specifies the success or failure of the request. + */ + IMPORT_C CQoSAdaptEvent(CQoSParameters& aParameters, TInt aReason); + + /** + * Returns the QoS parameters. + * + * @return QoS parameters. + */ + IMPORT_C CQoSParameters* Parameters() const; + + /** + * Returns the reason code. Reason code specifies the success or failure of the request. + * + * @return Reason code. + */ + IMPORT_C TInt Reason() const; + +private: + /** The address of the CQoSParameters parameter supplied during construction. */ + CQoSParameters* iParameters; + /** The reason code that specifies the success or failure of the request. */ + TInt iReason; +}; + +/** + * Class for EQoSEventChannel event whereby a QoS channel is opened + * + * @publishedPartner + * @released + */ +class CQoSChannelEvent : public CQoSEventBase +{ +public: + /** + * Constructor. Sets the QoS parameters and reason code. + * + * @param aParameters QoS parameters. + * @param aReason Reason code specifies the success or failure of the request. + */ + IMPORT_C CQoSChannelEvent(CQoSParameters* aParameters, TInt aReason); + + /** + * Returns the QoS parameters. + * + * @return QoS parameters. + */ + IMPORT_C CQoSParameters* Parameters() const; + + /** + * Returns the reason code. Reason code specifies the success or failure of the request. + * + * @return Reason code. KErrNone if an existing channel was found, otherwise an error code. + */ + IMPORT_C TInt Reason() const; + +private: + /** The address of the CQoSParameters parameter supplied during construction. */ + CQoSParameters* iParameters; + /** The reason code that specifies the success or failure of the request. */ + TInt iReason; +}; + +/** + * Class for EQoSEventJoin event whereby a socket is attached to a QoS channel + * + * @publishedPartner + * @released + */ +class CQoSJoinEvent : public CQoSEventBase +{ +public: + /** + * Constructor. Sets the selector and reason code. Selector specifies the socket + * that was attached to the QoS channel. + * + * @param aSelector Selector specifies the socket that was attached to the QoS channel. + * @param aReason Reason code specifies the success or failure of the request. + */ + IMPORT_C CQoSJoinEvent(const TQoSSelector& aSelector, TInt aReason); + + /** + * Returns the selector that was attached to the QoS channel. + * + * @return Selector that was attached to the QoS channel. + */ + IMPORT_C const TQoSSelector& Selector() const; + + /** + * Returns the reason code. Reason code specifies the success or failure of the request. + * + * @return Reason code. + */ + IMPORT_C TInt Reason() const; + +private: + /** The selector that specifies the socket that was attached to the QoS channel. */ + TQoSSelector iSelector; + /** The reason code that specifies the success or failure of the request. */ + TInt iReason; +}; + +/** + * Class for EQoSEventLeave event whereby a socket is detached from a QoS channel + * + * @publishedPartner + * @released + */ +class CQoSLeaveEvent : public CQoSEventBase +{ +public: + /** + * Constructor. Sets the selector and reason code. Selector specifies the socket + * that was detached from the QoS channel. + * + * @param aSelector Selector specifies the socket that was detached from the QoS channel. + * @param aReason Reason code specifies the success or failure of the request. + */ + IMPORT_C CQoSLeaveEvent(const TQoSSelector& aSelector, TInt aReason); + + /** + * Returns the selector that was detached from the QoS channel. + * + * @return Selector that was detached from the QoS channel. + */ + IMPORT_C const TQoSSelector& Selector() const; + + /** + * Returns the reason code. Reason code specifies the success or failure of the request. + * + * @return Reason code. + */ + IMPORT_C TInt Reason() const; + +private: + /** The QoS channel selector. */ + TQoSSelector iSelector; + /** The reason code that specifies the success or failure of the request. */ + TInt iReason; +}; + +/** + * Class for EQoSEventAddPolicy event whereby a QoS policy was added to QoS policy database + * + * @publishedPartner + * @released + */ +class CQoSAddEvent : public CQoSEventBase +{ +public: + /** + * Constructor. Sets the QoS parameters and reason code. + * + * @param aParameters QoS parameters. + * @param aReason Reason code specifies the success or failure of the request. + */ + IMPORT_C CQoSAddEvent(CQoSParameters* aParameters, TInt aReason); + + /** + * Returns the QoS parameters. + * + * @return QoS parameters. + */ + IMPORT_C CQoSParameters* Parameters() const; + + /** + * Returns the reason code. Reason code specifies the success or failure of the request. + * + * @return Reason code. + */ + IMPORT_C TInt Reason() const; + +private: + /** The address of the CQoSParameters parameter supplied during construction. */ + CQoSParameters* iParameters; + /** The reason code that specifies the success or failure of the request. */ + TInt iReason; +}; + +/** + * Class for EQoSEventGetPolicy event whereby a QoS policy was searched from the + * QoS policy database + * + * @publishedPartner + * @released + */ +class CQoSGetEvent : public CQoSEventBase +{ +public: + /** + * Constructor. Sets the QoS parameters and reason code. + * + * @param aParameters QoS parameters. + * @param aReason Reason code specifies the success or failure of the request. + */ + IMPORT_C CQoSGetEvent(CQoSParameters* aParameters, TInt aReason); + + /** + * Returns the QoS parameters. + * + * @return QoS parameters. + */ + IMPORT_C CQoSParameters* Parameters() const; + + /** + * Returns the reason code. Reason code specifies the success or failure of the request. + * + * @return Reason code. + */ + IMPORT_C TInt Reason() const; + +private: + /** The address of the CQoSParameters parameter supplied during construction. */ + CQoSParameters* iParameters; + /** The reason code that specifies the success or failure of the request. */ + TInt iReason; +}; + +/** + * Class for EQoSEventDeletePolicy event whereby a QoS policy was deleted + * + * @publishedPartner + * @released + */ +class CQoSDeleteEvent : public CQoSEventBase +{ +public: + /** + * Constructor. Sets the reason code indicating the success or failure of the request. + * + * @param aReason Reason code. + */ + IMPORT_C CQoSDeleteEvent(TInt aReason); + + /** + * Returns the reason code. Reason code specifies the success or failure of the request. + * + * @return Reason code. + */ + IMPORT_C TInt Reason() const; + +private: + /** The reason code specifies the success or failure of the request. */ + TInt iReason; +}; + +/** + * Class for EQoSEventLoadPolicyFile and EQoSEventUnloadPolicyFile events whereby + * policy files are loaded or unloaded + * + * @publishedPartner + * @released + */ +class CQoSLoadEvent : public CQoSEventBase +{ +public: + /** + * Constructor. + * + * @param aEvent Sets the event type (EQoSEventLoadPolicyFile or EQoSEventUnloadPolicyFile). + * @param aReason Reason code. + * @param aFileName The name of the policy file. + */ + IMPORT_C CQoSLoadEvent(const TQoSEvent& aEvent, TInt aReason, const TDesC& aFileName); + + /** + * Returns the name of the policy file. + * + * @return The name of the policy file. + */ + IMPORT_C const TFileName& FileName() const; + + /** + * Returns the reason code. Reason code specifies the success or failure of the request. + * + * @return Reason code. + */ + IMPORT_C TInt Reason() const; + +private: + /** The reason code that specifies the success or failure of the request. */ + TInt iReason; + /** The name of the QoS policy file. */ + TFileName iFileName; +}; + +/** + * An interface to catch QoS events. + * + * @publishedPartner + * @released + */ +class MQoSObserver +{ +public: + /** + This method is called by the QoS API when a QoS event occurs. + + @publishedPartner + @released + @capability NetworkServices Restrict QoS operations in similar way as + normal socket operations. + @param aQoSEvent QoS event class. + */ + virtual void Event(const CQoSEventBase& aQoSEvent)=0; +}; + +/** + * An interface to manage QoS policies and QoS policy files. RQoSPolicy::Open must always be called before + * any other methods in the RQoSPolicy can be called. Note that only one request can be pending at once + * (QoS event should be received before issuing next request). + * + * @publishedPartner + * @released + */ +class RQoSPolicy +{ +public: + IMPORT_C RQoSPolicy(); + IMPORT_C ~RQoSPolicy(); + + /** + * RQoSPolicy::Open must always be called before any other method can be used. + * Specifies the selector for a QoS policy. + * + * @param aSelector Selector for the QoS policy. + * @return KErrNone if everything is ok, != KErrNone is the QoS channel cannot be opened. + */ + IMPORT_C TInt Open(const TQoSSelector& aSelector); + + /** + * Sets the QoS parameters for the QoS policy. CQoSAddEvent event is received + * asynchronously to indicate the success of failure of the request. + * + * @param aPolicy QoS parameters. + * @return KErrNone if request was issued, != KErrNone if there was an error. + */ + IMPORT_C TInt SetQoS(CQoSParameters& aPolicy); + + /** + * Gets the QoS policy from QoS policy database. CQoSGetEvent event is received + * asynchronously to indicate the success of failure of the request. + * + * @return KErrNone if request was issued, != KErrNone if there was an error. + */ + IMPORT_C TInt GetQoS(); + + /** + * Deletes the QoS policy. + * @return KErrNone if request was issued, != KErrNone if there was an error (for example, + * RQoSPolicy::Open was not called). + */ + IMPORT_C TInt Close(); + + /** + * Registers an event observer to catch QoS events. + * + * @param aObserver Event observer. + * @param aMask An event mask. An application can specify a set of QoS events that it wants to receive. + * By default all events are notified to the application. + * @return KErrNone if request was issued, != KErrNone if there was an error. + */ + IMPORT_C TInt NotifyEvent(MQoSObserver& aObserver, TUint aMask=KQoSEventAll); + + /** + * Deregisters an event observer to catch QoS events. + * + * @param aObserver Event observer. + * @return KErrNone if request was issued, != KErrNone if there was an error. + */ + IMPORT_C TInt CancelNotifyEvent(MQoSObserver& aObserver); + + /** + * Loads a QoS policy file into the QoS policy database. EQoSEventLoadPolicyFile event is received + * asynchronously to indicate the success of failure of the request. + * + * @param aName Name of the QoS policy file to be loaded. + * @return KErrNone if request was issued, != KErrNone if there was an error. + */ + IMPORT_C TInt LoadPolicyFile(const TDesC& aName); + + /** + * Unloads a QoS policy file from the QoS policy database. EQoSEventUnloadPolicyFile event is received + * asynchronously to indicate the success of failure of the request. + * + * @param aName Name of the QoS policy file to be unloaded. + * @return KErrNone if request was issued, != KErrNone if there was an error. + */ + IMPORT_C TInt UnloadPolicyFile(const TDesC& aName); + +private: + /** A dynamically allocated QoS policy. */ + CPolicy* iPolicy;// //< Used internally by qoslib +}; + +#endif