Home | History | Annotate | Download | only in include
      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  */
     44 typedef 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 }
     97 SR_SemanticGraph;
     98 
     99 
    100 /**
    101  * Create a new Semantic Graph
    102  *
    103  * @param self SR_SemanticGraph handle
    104  */
    105 SREC_SEMPROC_API ESR_ReturnCode SR_SemanticGraphCreate(SR_SemanticGraph** self);
    106 
    107 #endif /* __SR_SEMANTICGRAPH_H */
    108