1/*---------------------------------------------------------------------------*
2 *  SR_SemanticGraph.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_SEMANTICGRAPH_H
21#define __SR_SEMANTICGRAPH_H
22
23
24
25#include "SR_SemprocPrefix.h"
26#include "pstdio.h"
27#include "ptypes.h"
28#include "srec_context.h" /* for wordmap */
29#include "ESR_ReturnCode.h"
30
31
32/**
33 * A Semantic Graph is a data structure representing acceptable phrases and their associated
34 * meaning. A graph is made up of nodes and arcs. Arcs are associated with input symbols and
35 * output symbols. Input symbols are words that may be spoken, and output symbols are symbols
36 * which allow for semantic interpretation. For example, certain output symbols are actually
37 * labels which map to script expressions (eScript expressions, similar to JavaScript).
38 * These expressions are interpreted by a Semantic Processor in order to determine meaning, such as
39 * spoken input symbol: "one", expression: "DIGIT.V='1'", semantic interpretation: "1".
40 *
41 * Refer to the SR_SemanticProcessor.h documentation to find out more about parsing, and about
42 * semantic interpretation (eScript).
43 */
44typedef struct SR_SemanticGraph_t
45{
46  /**
47   * Destroys a semantic graph.
48   *
49   * @param self SR_SemanticGraph handle
50   */
51  ESR_ReturnCode(*destroy)(struct SR_SemanticGraph_t* self);
52  /**
53   * Loads a semantic graph from disk.
54   *
55   * @param self SR_SemanticGraph handle
56   * @param ilabels Input word labels to be used when building the graph (The should be the same as
57   * the output word labels from the recognition graph/context.)
58   * @param basename File to read graph from (.g2g image or basename for text files)
59   * @param num_words_to_add Number of words to add dynamically (only applies when loading from text files)
60   * @todo complete documentation
61   */
62  ESR_ReturnCode(*load)(struct SR_SemanticGraph_t* self, wordmap* ilabels, const LCHAR* basename, int num_words_to_add);
63  /**
64   * Unloads a semantic graph.
65   *
66   * @param self SR_SemanticGraph handle
67  * @return ESR_SUCCESS
68   */
69  ESR_ReturnCode(*unload)(struct SR_SemanticGraph_t* self);
70
71  /**
72   * Saves the semantic graph as a binary image.
73   *
74   * @param self SR_SemanticGraph handle
75   * @param filename Name of the binary image file.
76   * @param version_number Target file format version.
77   */
78  ESR_ReturnCode(*save)(struct SR_SemanticGraph_t* self, const LCHAR* filename, int version_number);
79
80  /**
81   * Adds a word to the semantic graph at the specified slot. Tag may be defined or NULL.
82   *
83   * @param self SR_SemanticGraph handle
84   * @param slot Where to insert in graph (only ROOT supported right now)
85   * @param word Word to add.
86   * @param word Semantic Tag for the word.
87   * @param maybeMultiMeaning Indicates that we MAY be adding alternate multiple meanings a previously added word
88   */
89  ESR_ReturnCode(*addWordToSlot)(struct SR_SemanticGraph_t* self, const LCHAR* slot, const LCHAR* word, const LCHAR* tag, const ESR_BOOL maybeMultiMeaning);
90	/**
91	 * Removes all words from the semantic graph.
92	 *
93	 * @param self SR_SemanticGraph handle
94	 */
95  ESR_ReturnCode(*reset)(struct SR_SemanticGraph_t* self);
96}
97SR_SemanticGraph;
98
99
100/**
101 * Create a new Semantic Graph
102 *
103 * @param self SR_SemanticGraph handle
104 */
105SREC_SEMPROC_API ESR_ReturnCode SR_SemanticGraphCreate(SR_SemanticGraph** self);
106
107#endif /* __SR_SEMANTICGRAPH_H */
108