1/*---------------------------------------------------------------------------*
2 *  SR_SemanticResult.h  *
3 *                                                                           *
4 *  Copyright 2007, 2008 Nuance Communciations, Inc.                               *
5 *                                                                           *
6 *  Licensed under the Apache License, Version 2.0 (the 'License');          *
7 *  you may not use this file except in compliance with the License.         *
8 *                                                                           *
9 *  You may obtain a copy of the License at                                  *
10 *      http://www.apache.org/licenses/LICENSE-2.0                           *
11 *                                                                           *
12 *  Unless required by applicable law or agreed to in writing, software      *
13 *  distributed under the License is distributed on an 'AS IS' BASIS,        *
14 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. *
15 *  See the License for the specific language governing permissions and      *
16 *  limitations under the License.                                           *
17 *                                                                           *
18 *---------------------------------------------------------------------------*/
19
20#ifndef __SR_SEMANTICRESULT_H
21#define __SR_SEMANTICRESULT_H
22
23
24
25#include "ESR_ReturnCode.h"
26#include "SR_SemprocPrefix.h"
27
28/**
29 * Semantic result.
30 */
31typedef struct SR_SemanticResult_t
32{
33  /**
34   * Returns number of [key, value] pairs in the current results.
35   *
36   * @param self SemanticResult handler
37   * @param count The number keys
38   */
39  ESR_ReturnCode(*getKeyCount)(struct SR_SemanticResult_t* self, size_t* count);
40  /**
41   * Given an array of pointers to <code>LCHAR*</code>, populates that array with pointers
42    * to the keys used internally by the recognition result. These keys should not be modified!
43   *
44   * @param self SemanticResult handler
45   * @param list [out] List of keys associated with n-best list entry.
46    * @param size [in/out] Size of list. If the return code is ESR_BUFFER_OVERFLOW, the required size
47    *             is returned in this variable.
48   */
49  ESR_ReturnCode(*getKeyList)(struct SR_SemanticResult_t* self, LCHAR** list, size_t* size);
50  /**
51   * Returns copy of semantic value.
52   *
53   * @param self SemanticResult handler
54    * @param key The key to look up
55   * @param value [out] The buffer used to hold the resulting value
56   * @param len [in/out] Length of value argument. If the return code is ESR_BUFFER_OVERFLOW,
57   *            the required length is returned in this variable.
58   */
59  ESR_ReturnCode(*getValue)(struct SR_SemanticResult_t* self, const LCHAR* key, LCHAR* value, size_t* len);
60  /**
61   * Destroys a semantic result.
62   *
63   * @param self SemanticResult handler
64   */
65  ESR_ReturnCode(*destroy)(struct SR_SemanticResult_t* self);
66}
67SR_SemanticResult;
68
69
70/**
71 * Create a new semantic result.
72 *
73 * @param self SemanticResult handle
74 */
75SREC_SEMPROC_API ESR_ReturnCode SR_SemanticResultCreate(SR_SemanticResult** self);
76/**
77 * Returns number of [key, value] pairs in the current results.
78 *
79 * @param self SemanticResult handler
80 * @param count The number keys
81 */
82SREC_SEMPROC_API ESR_ReturnCode SR_SemanticResultGetKeyCount(SR_SemanticResult* self, size_t* count);
83/**
84 * Given an array of pointers to <code>LCHAR*</code>, populates that array with pointers
85 * to the keys used internally by the recognition result. These keys should not be modified!
86 *
87 * @param self SemanticResult handler
88 * @param list [out] List of keys associated with n-best list entry.
89 * @param size [in/out] Size of list. If the return code is ESR_BUFFER_OVERFLOW, the required size
90 *             is returned in this variable.
91 */
92SREC_SEMPROC_API ESR_ReturnCode SR_SemanticResultGetKeyList(SR_SemanticResult* self, LCHAR** list,
93    size_t* size);
94/**
95 * Returns value component of [key, value] pair.
96 *
97 * @param self SemanticResult handler
98 * @param key The key to look up
99 * @param value [out] The buffer used to hold the resulting value
100 * @param len [in/out] Length of value argument. If the return code is ESR_BUFFER_OVERFLOW,
101 *            the required length is returned in this variable.
102 */
103SREC_SEMPROC_API ESR_ReturnCode SR_SemanticResultGetValue(SR_SemanticResult* self, const LCHAR* key, LCHAR* value, size_t* len);
104/**
105 * Destroys a semantic result.
106 *
107 * @param self SemanticResult handler
108 */
109SREC_SEMPROC_API ESR_ReturnCode SR_SemanticResultDestroy(SR_SemanticResult* self);
110
111
112#endif /* __SR_SEMANTICRESULT_H */
113