1/* *********************************************************************

2 * This Original Work is copyright of 51 Degrees Mobile Experts Limited.

4 * Forbury Square, Reading, Berkshire, United Kingdom RG1 3EU.

5 *

6 * This Original Work is licensed under the European Union Public Licence

7 * (EUPL) v.1.2 and is subject to its terms as set out below.

8 *

9 * If a copy of the EUPL was not distributed with this file, You can obtain

10 * one at https://opensource.org/licenses/EUPL-1.2.

11 *

12 * The 'Compatible Licences' set out in the Appendix to the EUPL (as may be

13 * amended by the European Commission) shall be deemed incompatible for

14 * the purposes of the Work and the provisions of the compatibility

15 * clause in Article 5 of the EUPL shall not apply.

16 *

17 * If using the Work as, or as part of, a network application, by

18 * including the attribution notice(s) required under Article 5 of the EUPL

19 * in the end user terms of the application under an appropriate heading,

20 * such notice(s) shall fulfill the requirements of that article.

21 * ********************************************************************* */

22

23#ifndef FIFTYONE_DEGREES_RESULTS_INCLUDED

24#define FIFTYONE_DEGREES_RESULTS_INCLUDED

25

26#ifdef FIFTYONE_DEGREES_IPI_SYMBOLS

27#include "ipiSymbols.h"

28#endif

29

85

86#include <string.h>

87#include "data.h"

88#include "status.h"

89#include "dataset.h"

90#include "common.h"

91

95typedef enum e_fiftyone_degrees_results_no_value_reason {

96 FIFTYONE_DEGREES_RESULTS_NO_VALUE_REASON_DIFFERENCE,

100 FIFTYONE_DEGREES_RESULTS_NO_VALUE_REASON_NO_MATCHED_NODES,

104 FIFTYONE_DEGREES_RESULTS_NO_VALUE_REASON_INVALID_PROPERTY,

109 FIFTYONE_DEGREES_RESULTS_NO_VALUE_REASON_NO_RESULT_FOR_PROPERTY,

116 FIFTYONE_DEGREES_RESULTS_NO_VALUE_REASON_NO_RESULTS,

119 FIFTYONE_DEGREES_RESULTS_NO_VALUE_REASON_TOO_MANY_VALUES,

123 FIFTYONE_DEGREES_RESULTS_NO_VALUE_REASON_NULL_PROFILE,

127 FIFTYONE_DEGREES_RESULTS_NO_VALUE_REASON_HIGH_RISK,

131 FIFTYONE_DEGREES_RESULTS_NO_VALUE_REASON_UNKNOWN

132} fiftyoneDegreesResultsNoValueReason;

133

134struct fiftyone_degrees_results_base_t;

135

144typedef void (*fiftyoneDegreesResultsEvaluateMethod)(

145 struct fiftyone_degrees_results_base_t *results,

146 byte componentIndex,

147 fiftyoneDegreesException *exception);

148

152#define FIFTYONE_DEGREES_RESULTS_PENDING_WORDS 8

153

158typedef struct fiftyone_degrees_results_base_t {

159 void *dataSet;

160 fiftyoneDegreesResultsEvaluateMethod evaluate;

164 uint32_t pending[FIFTYONE_DEGREES_RESULTS_PENDING_WORDS];

169 fiftyoneDegreesOverrideValueArray *overrides;

174} fiftyoneDegreesResultsBase;

175

183EXTERNAL fiftyoneDegreesResultsBase* fiftyoneDegreesResultsInit(

184 fiftyoneDegreesResultsBase *results,

185 void *dataSet);

186

191#if defined(_MSC_VER)

192#define FIFTYONE_DEGREES_RESULTS_INLINE static __inline

193#elif defined(__GNUC__) || defined(__clang__)

194#define FIFTYONE_DEGREES_RESULTS_INLINE static __inline__

195#else

196#define FIFTYONE_DEGREES_RESULTS_INLINE static inline

197#endif

198

203FIFTYONE_DEGREES_RESULTS_INLINE void fiftyoneDegreesResultsPendingClear(

204 fiftyoneDegreesResultsBase *results) {

205 memset(results->pending, 0, sizeof(results->pending));

206}

207

214FIFTYONE_DEGREES_RESULTS_INLINE void fiftyoneDegreesResultsPendingSet(

215 fiftyoneDegreesResultsBase *results,

216 byte componentIndex) {

217 results->pending[componentIndex >> 5] |=

218 (uint32_t)1 << (componentIndex & 31);

219}

220

230FIFTYONE_DEGREES_RESULTS_INLINE bool fiftyoneDegreesResultsWalkWhenPopulated(

231 const fiftyoneDegreesDataSetBase *dataSet) {

232 return dataSet->available != NULL && dataSet->available->named != NULL;

233}

234

244FIFTYONE_DEGREES_RESULTS_INLINE void fiftyoneDegreesResultsEvaluate(

245 fiftyoneDegreesResultsBase *results,

246 byte componentIndex,

247 fiftyoneDegreesException *exception) {

248 uint32_t *word = &results->pending[componentIndex >> 5];

249 const uint32_t bit = (uint32_t)1 << (componentIndex & 31);

250 if ((*word & bit) != 0) {

251 *word &= ~bit;

252 if (results->evaluate != NULL) {

253 results->evaluate(results, componentIndex, exception);

254 }

255 }

256}

257

267FIFTYONE_DEGREES_RESULTS_INLINE void fiftyoneDegreesResultsEvaluateAll(

268 fiftyoneDegreesResultsBase *results,

269 fiftyoneDegreesException *exception) {

270 uint32_t word, bit;

271 for (word = 0; word < FIFTYONE_DEGREES_RESULTS_PENDING_WORDS; word++) {

272 while (results->pending[word] != 0) {

273 bit = 0;

274 while ((results->pending[word] & ((uint32_t)1 << bit)) == 0) {

275 bit++;

276 }

277 fiftyoneDegreesResultsEvaluate(

278 results,

279 (byte)(word * 32 + bit),

280 exception);

281 if (FIFTYONE_DEGREES_EXCEPTION_FAILED) {

282 return;

283 }

284 }

285 }

286}

287

295FIFTYONE_DEGREES_RESULTS_INLINE bool fiftyoneDegreesResultsHasOverrideValue(

296 fiftyoneDegreesResultsBase *results,

297 uint32_t availableIndex) {

298 return results->overrides != NULL &&

299 fiftyoneDegreesOverrideHasValueForRequiredPropertyIndex(

300 results->overrides,

301 availableIndex);

302}

303

314FIFTYONE_DEGREES_RESULTS_INLINE uint32_t fiftyoneDegreesResultsGetOverrideValues(

315 fiftyoneDegreesResultsBase *results,

316 uint32_t availableIndex,

317 fiftyoneDegreesList *values) {

318 return results->overrides == NULL ? 0 :

319 fiftyoneDegreesOverrideValuesAdd(

320 results->overrides,

321 availableIndex,

322 values);

323}

324

328

329#endif

FIFTYONE_DEGREES_EXCEPTION_FAILED

#define FIFTYONE_DEGREES_EXCEPTION_FAILED

Macro to test if the exception has been set and is failed.

Definition exceptions.h:208

fiftyoneDegreesResultsEvaluate

FIFTYONE_DEGREES_RESULTS_INLINE void fiftyoneDegreesResultsEvaluate(fiftyoneDegreesResultsBase *results, byte componentIndex, fiftyoneDegreesException *exception)

Walks the component's graph if it is pending, and marks it walked whether or not the walk succeeds,...

Definition results.h:244

fiftyoneDegreesResultsEvaluateAll

FIFTYONE_DEGREES_RESULTS_INLINE void fiftyoneDegreesResultsEvaluateAll(fiftyoneDegreesResultsBase *results, fiftyoneDegreesException *exception)

Walks every pending component in component order, stopping at the first walk that fails.

Definition results.h:267

FIFTYONE_DEGREES_RESULTS_PENDING_WORDS

#define FIFTYONE_DEGREES_RESULTS_PENDING_WORDS

Number of 32 bit words holding one bit for each possible component index.

Definition results.h:152

fiftyoneDegreesResultsPendingClear

FIFTYONE_DEGREES_RESULTS_INLINE void fiftyoneDegreesResultsPendingClear(fiftyoneDegreesResultsBase *results)

Marks every component as walked, before the results are populated again.

Definition results.h:203

fiftyoneDegreesResultsHasOverrideValue

FIFTYONE_DEGREES_RESULTS_INLINE bool fiftyoneDegreesResultsHasOverrideValue(fiftyoneDegreesResultsBase *results, uint32_t availableIndex)

Returns true if the results hold an override value for the property, so that a read can answer withou...

Definition results.h:295

fiftyoneDegreesResultsInit

fiftyoneDegreesResultsBase * fiftyoneDegreesResultsInit(fiftyoneDegreesResultsBase *results, void *dataSet)

Initialise a set of results by setting the data set they are associated with.

fiftyoneDegreesResultsEvaluateMethod

void(* fiftyoneDegreesResultsEvaluateMethod)(struct fiftyone_degrees_results_base_t *results, byte componentIndex, fiftyoneDegreesException *exception)

Walks the graph of one component for the results, setting what a read of the component's properties n...

Definition results.h:144

FIFTYONE_DEGREES_RESULTS_INLINE

#define FIFTYONE_DEGREES_RESULTS_INLINE

Marks a function defined in this header, so that it adds no name to the libraries.

Definition results.h:196

fiftyoneDegreesResultsWalkWhenPopulated

FIFTYONE_DEGREES_RESULTS_INLINE bool fiftyoneDegreesResultsWalkWhenPopulated(const fiftyoneDegreesDataSetBase *dataSet)

Returns true if populating the results walks the graph of each component they answer for,...

Definition results.h:230

fiftyoneDegreesResultsNoValueReason

Enum containing reasons which cause a value to not be present or valid.

Definition results.h:95

fiftyoneDegreesResultsPendingSet

FIFTYONE_DEGREES_RESULTS_INLINE void fiftyoneDegreesResultsPendingSet(fiftyoneDegreesResultsBase *results, byte componentIndex)

Marks the component as waiting for the first read of one of its properties.

Definition results.h:214

fiftyoneDegreesResultsGetOverrideValues

FIFTYONE_DEGREES_RESULTS_INLINE uint32_t fiftyoneDegreesResultsGetOverrideValues(fiftyoneDegreesResultsBase *results, uint32_t availableIndex, fiftyoneDegreesList *values)

Adds the override values the results hold for the property to the list.

Definition results.h:314

FIFTYONE_DEGREES_RESULTS_NO_VALUE_REASON_DIFFERENCE

@ FIFTYONE_DEGREES_RESULTS_NO_VALUE_REASON_DIFFERENCE

The difference value is higher than the threshold, see the Pattern API.

Definition results.h:96

FIFTYONE_DEGREES_RESULTS_NO_VALUE_REASON_NO_MATCHED_NODES

@ FIFTYONE_DEGREES_RESULTS_NO_VALUE_REASON_NO_MATCHED_NODES

No hash nodes were matched, see the Hash API.

Definition results.h:100

FIFTYONE_DEGREES_RESULTS_NO_VALUE_REASON_INVALID_PROPERTY

@ FIFTYONE_DEGREES_RESULTS_NO_VALUE_REASON_INVALID_PROPERTY

The requested property does not exist, or is not a required property.

Definition results.h:104

FIFTYONE_DEGREES_RESULTS_NO_VALUE_REASON_NO_RESULT_FOR_PROPERTY

@ FIFTYONE_DEGREES_RESULTS_NO_VALUE_REASON_NO_RESULT_FOR_PROPERTY

There is no result which contains a value for the requested property.

Definition results.h:109

FIFTYONE_DEGREES_RESULTS_NO_VALUE_REASON_UNKNOWN

@ FIFTYONE_DEGREES_RESULTS_NO_VALUE_REASON_UNKNOWN

None of the above.

Definition results.h:131

FIFTYONE_DEGREES_RESULTS_NO_VALUE_REASON_NO_RESULTS

@ FIFTYONE_DEGREES_RESULTS_NO_VALUE_REASON_NO_RESULTS

There are no results to get a value from.

Definition results.h:116

FIFTYONE_DEGREES_RESULTS_NO_VALUE_REASON_HIGH_RISK

@ FIFTYONE_DEGREES_RESULTS_NO_VALUE_REASON_HIGH_RISK

The match is deemed high risk of containing incorrect or misleading results.

Definition results.h:127

FIFTYONE_DEGREES_RESULTS_NO_VALUE_REASON_NULL_PROFILE

@ FIFTYONE_DEGREES_RESULTS_NO_VALUE_REASON_NULL_PROFILE

The results contain a null profile for the required component.

Definition results.h:123

FIFTYONE_DEGREES_RESULTS_NO_VALUE_REASON_TOO_MANY_VALUES

@ FIFTYONE_DEGREES_RESULTS_NO_VALUE_REASON_TOO_MANY_VALUES

There are too many values to be expressed as the requested type.

Definition results.h:119

fiftyoneDegreesDataSetBase

Base data set structure which contains the 'must have's for all data sets.

Definition dataset.h:107

fiftyoneDegreesDataSetBase::available

fiftyoneDegreesPropertiesAvailable * available

Available properties.

Definition dataset.h:129

fiftyoneDegreesException

Structure used to represent a 51Degrees exception and passed into methods that might generate excepti...

Definition exceptions.h:115

fiftyoneDegreesList

List structure which contains a list of collection items.

Definition list.h:116

fiftyoneDegreesOverrideValueArray

An array of properties and values to use when getting override values.

Definition overrides.h:119

fiftyoneDegreesPropertyAvailableArray::named

fiftyoneDegreesPropertyNamed * named

The names the caller gave, in the caller's order, or NULL when the caller named no property.

Definition properties.h:215

fiftyoneDegreesResultsBase

Base results structure which any processing results should extend.

Definition results.h:158

fiftyoneDegreesResultsBase::pending

uint32_t pending[FIFTYONE_DEGREES_RESULTS_PENDING_WORDS]

One bit for each component whose graph is still to be walked.

Definition results.h:164

fiftyoneDegreesResultsBase::evaluate

fiftyoneDegreesResultsEvaluateMethod evaluate

Walks one component's graph, or NULL if the results walk none on a read.

Definition results.h:160

fiftyoneDegreesResultsBase::overrides

fiftyoneDegreesOverrideValueArray * overrides

Values from the evidence that override the values of properties, or NULL if the results hold none.

Definition results.h:169

fiftyoneDegreesResultsBase::dataSet

void * dataSet

Pointer to the data set associated with the results.

Definition results.h:159