|
1 // Copyright (c) 2007-2009 Nokia Corporation and/or its subsidiary(-ies). |
|
2 // All rights reserved. |
|
3 // This component and the accompanying materials are made available |
|
4 // under the terms of "Eclipse Public License v1.0" |
|
5 // which accompanies this distribution, and is available |
|
6 // at the URL "http://www.eclipse.org/legal/epl-v10.html". |
|
7 // |
|
8 // Initial Contributors: |
|
9 // Nokia Corporation - initial contribution. |
|
10 // |
|
11 // Contributors: |
|
12 // |
|
13 // Description: |
|
14 // |
|
15 |
|
16 /** |
|
17 @file |
|
18 @publishedPartner |
|
19 @released |
|
20 */ |
|
21 |
|
22 #ifndef SYMBIAN_AVAILABILITY_H |
|
23 #define SYMBIAN_AVAILABILITY_H |
|
24 |
|
25 #ifdef _DEBUG |
|
26 // Panic category for "absolutely impossible!" vanilla ASSERT()-type panics from this module |
|
27 // (if it could happen through user error then you should give it an explicit, documented, category + code) |
|
28 _LIT(KSpecAssert_ESock_Availabili, "ESock_Availabili"); |
|
29 #endif |
|
30 |
|
31 namespace ESock |
|
32 { |
|
33 |
|
34 /** |
|
35 Container for availability status. Used by availability plugins to pass availability information into the mesh machine. |
|
36 */ |
|
37 class TAvailabilityStatus |
|
38 { |
|
39 public: |
|
40 enum |
|
41 { |
|
42 EUnknownAvailabilityScore = -1, |
|
43 EMinAvailabilityScore = 0, |
|
44 EMaxAvailabilityScore = 100 |
|
45 }; |
|
46 |
|
47 TAvailabilityStatus() |
|
48 : iScore(EUnknownAvailabilityScore) |
|
49 { |
|
50 } |
|
51 |
|
52 TAvailabilityStatus(TInt aScore) |
|
53 : iScore(aScore) |
|
54 { |
|
55 } |
|
56 |
|
57 /** |
|
58 @return ETrue if availability is known, EFalse otherwise. |
|
59 */ |
|
60 TBool IsKnown() const |
|
61 { |
|
62 return iScore >= EMinAvailabilityScore && iScore <= EMaxAvailabilityScore; |
|
63 } |
|
64 |
|
65 /** |
|
66 @param aScore the availability score. Must be >= EMinAvailabilityScore and <= EMinAvailabilityScore. |
|
67 */ |
|
68 void SetScore(TInt aScore) |
|
69 { |
|
70 __ASSERT_DEBUG(aScore >= EMinAvailabilityScore && aScore <= EMaxAvailabilityScore, User::Panic(KSpecAssert_ESock_Availabili, 1)); |
|
71 iScore = aScore; |
|
72 } |
|
73 |
|
74 /** |
|
75 Set the availability status to unknown |
|
76 */ |
|
77 void SetUnknown() |
|
78 { |
|
79 iScore = EUnknownAvailabilityScore; |
|
80 } |
|
81 |
|
82 /** |
|
83 @return the availability score |
|
84 */ |
|
85 TInt Score() const { return iScore; } |
|
86 |
|
87 private: |
|
88 TInt iScore; |
|
89 }; |
|
90 |
|
91 /** |
|
92 Collection of options used to register to availability notifications |
|
93 */ |
|
94 struct TAvailabilitySubscriptionOptions |
|
95 { |
|
96 public: |
|
97 /** |
|
98 Subscription option flags: |
|
99 ENotAnyChange - the client is specifying availability score thresholds he wishes to be notified on crossing; |
|
100 EAnyChange - the client is interestes in any change in the availability. Only change in calculated score will be reported. |
|
101 EAnyNestedChamge - the client is interested in any change in the availability even if it does not affect the calculated score |
|
102 e.g.: one of many available access points ceases to be available (and doesn't affect the score calculated against the remaning access points) |
|
103 */ |
|
104 enum TChangeScopeFlags |
|
105 { |
|
106 ENotAnyChange = 0, |
|
107 EAnyChange, |
|
108 EAnyNestedChange, |
|
109 }; |
|
110 |
|
111 /** |
|
112 @param aAnyChange If ETrue, notify on all changes in the calculated availability. If EFalse, use following parameters to decide what to notify on. |
|
113 @param aScoreExceeds Notify if availability score exceeds this |
|
114 @param aScoreDropsBelow Notify if availability score drops below this |
|
115 @param aScoreIncreasesByMoreThan Notify if availability score increased by more than this |
|
116 @param aScoreDescreasesByMoreThan Notify if availability score decreased by more than this |
|
117 */ |
|
118 TAvailabilitySubscriptionOptions(TBool aAnyChange = ETrue, |
|
119 TUint aScoreExceeds = 0, |
|
120 TUint aScoreDropsBelow = 0, |
|
121 TUint aScoreIncreasesByMoreThan = 0, |
|
122 TUint aScoreDecreasesByMoreThan = 0) |
|
123 : iFlags(aAnyChange? EAnyChange : ENotAnyChange), |
|
124 iScoreExceeds(aScoreExceeds), |
|
125 iScoreDropsBelow(aScoreDropsBelow), |
|
126 iScoreIncreasesByMoreThan(aScoreIncreasesByMoreThan), |
|
127 iScoreDecreasesByMoreThan(aScoreDecreasesByMoreThan) |
|
128 { |
|
129 __ASSERT_DEBUG(aScoreExceeds >= TAvailabilityStatus::EMinAvailabilityScore && aScoreExceeds <= TAvailabilityStatus::EMaxAvailabilityScore, User::Panic(KSpecAssert_ESock_Availabili, 2)); |
|
130 __ASSERT_DEBUG(aScoreDropsBelow >= TAvailabilityStatus::EMinAvailabilityScore && aScoreDropsBelow <= TAvailabilityStatus::EMaxAvailabilityScore, User::Panic(KSpecAssert_ESock_Availabili, 3)); |
|
131 __ASSERT_DEBUG(aScoreIncreasesByMoreThan >= TAvailabilityStatus::EMinAvailabilityScore && aScoreIncreasesByMoreThan <= TAvailabilityStatus::EMaxAvailabilityScore, User::Panic(KSpecAssert_ESock_Availabili, 4)); |
|
132 __ASSERT_DEBUG(aScoreDecreasesByMoreThan >= TAvailabilityStatus::EMinAvailabilityScore && aScoreDecreasesByMoreThan <= TAvailabilityStatus::EMaxAvailabilityScore, User::Panic(KSpecAssert_ESock_Availabili, 5)); |
|
133 } |
|
134 |
|
135 |
|
136 |
|
137 /** |
|
138 @param aFlags, TChangeScopeFlags describing the subscrption. |
|
139 @see TChangeScopeFlags. |
|
140 */ |
|
141 TAvailabilitySubscriptionOptions(TChangeScopeFlags aFlags) |
|
142 : iFlags(aFlags), |
|
143 iScoreExceeds(0), |
|
144 iScoreDropsBelow(0), |
|
145 iScoreIncreasesByMoreThan(0), |
|
146 iScoreDecreasesByMoreThan(0) |
|
147 { |
|
148 ASSERT(aFlags != ENotAnyChange); //illegal to ask for thersholds without specifying them. |
|
149 } |
|
150 |
|
151 /** |
|
152 @param aReported Currently reported availability |
|
153 @param aNew Newly reported availability |
|
154 @return ETrue if the change is one which should be reported |
|
155 */ |
|
156 TBool IsChangeSignificant(const TAvailabilityStatus& aReported, const TAvailabilityStatus& aNew) const |
|
157 { |
|
158 __ASSERT_DEBUG(aNew.IsKnown(), User::Panic(KSpecAssert_ESock_Availabili, 6)); //Use only with known availability! |
|
159 return ShouldNotifyAnyChange(aReported, aNew) |
|
160 || ShouldNotifyScoreExceeds(aReported, aNew) |
|
161 || ShouldNotifyScoreDropsBelow(aReported, aNew) |
|
162 || ShouldNotifyScoreIncreasesByMoreThan(aReported, aNew) |
|
163 || ShouldNotifyScoreDecreasesByMoreThan(aReported, aNew); |
|
164 } |
|
165 |
|
166 private: |
|
167 TBool ShouldNotifyAnyChange(const TAvailabilityStatus& aReported, const TAvailabilityStatus& aNew) const |
|
168 { |
|
169 return (iFlags == EAnyNestedChange) || |
|
170 (iFlags == EAnyChange && aNew.Score() != aReported.Score()); |
|
171 } |
|
172 |
|
173 TBool ShouldNotifyScoreExceeds(const TAvailabilityStatus& aReported, const TAvailabilityStatus& aNew) const |
|
174 { |
|
175 return iScoreExceeds != 0 && aNew.Score() > iScoreExceeds && aReported.Score() <= iScoreExceeds; |
|
176 } |
|
177 |
|
178 TBool ShouldNotifyScoreDropsBelow(const TAvailabilityStatus& aReported, const TAvailabilityStatus& aNew) const |
|
179 { |
|
180 return iScoreDropsBelow != 0 && aNew.Score() < iScoreDropsBelow && aReported.Score() >= iScoreDropsBelow; |
|
181 } |
|
182 |
|
183 TBool ShouldNotifyScoreIncreasesByMoreThan(const TAvailabilityStatus& aReported, const TAvailabilityStatus& aNew) const |
|
184 { |
|
185 return iScoreIncreasesByMoreThan != 0 && (aNew.Score() - aReported.Score()) > iScoreIncreasesByMoreThan; |
|
186 } |
|
187 |
|
188 TBool ShouldNotifyScoreDecreasesByMoreThan(const TAvailabilityStatus& aReported, const TAvailabilityStatus& aNew) const |
|
189 { |
|
190 return iScoreDecreasesByMoreThan != 0 && (aReported.Score() - aNew.Score()) > iScoreDecreasesByMoreThan; |
|
191 } |
|
192 |
|
193 private: |
|
194 TUint iScoreExceeds:7; |
|
195 TUint iScoreDropsBelow:7; |
|
196 TUint iScoreIncreasesByMoreThan:7; |
|
197 TUint iScoreDecreasesByMoreThan:7; |
|
198 TUint iFlags:4; |
|
199 }; |
|
200 |
|
201 |
|
202 } //namespace ESock |
|
203 |
|
204 |
|
205 |
|
206 #endif // SYMBIAN_AVAILABILITY_H |
|
207 |
|
208 |