1/*---------------------------------------------------------------------------*
2 *  SR_NametagDefs.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_NAMETAGDEFS_H
21#define __SR_NAMETAGDEFS_H
22
23
24
25#include "SR_NametagPrefix.h"
26#include "ESR_Locale.h"
27#include "ptypes.h"
28#include "ESR_ReturnCode.h"
29
30
31/**
32 * @addtogroup SR_NametagModule SR_Nametag API functions
33 * Nametags are user-added words. These words are created using the audio that has been collected
34 * during a recognition phase. The Recognizer stores the audio in the RecognizerResult object.
35 * The result is passed to NametagCreate() to create the nametag. The Nametags object is a
36 * collection of nametags. The nametag will consist of the speech parts of the audio. The
37 * silence from the ends of the utterance, and any long pause between speech chunks, is removed.
38 *
39 * @{
40 */
41
42/**
43 * Represents a nametag.
44 */
45typedef struct SR_Nametag_t
46{
47	/**
48	 * Returns the Nametag ID.
49	 *
50	 * @param self Nametag handle
51	 * @param id Nametag ID
52	 * @return ESR_INVALID_ARGUMENT if self is null
53	 */
54  ESR_ReturnCode (*getID)(const struct SR_Nametag_t* self, LCHAR** id);
55
56  	/**
57	 * Returns the Nametag ID.
58	 *
59	 * @param self Nametag handle
60	 * @param pvalue pointer to the transcription, SR_Nametag retains ownership
61	 * @param plen pointer to the length of the transcription
62	 * @return ESR_NO_MATCH_ERROR if self is null or bad voice tag
63	 */
64  ESR_ReturnCode (*getValue)(const struct SR_Nametag_t* self, const char** pvalue, size_t* plen);
65
66	/**
67	 * Sets the Nametag ID.
68	 *
69	 * @param self Nametag handle
70	 * @param id Nametag ID
71	 * @return ESR_INVALID_ARGUMENT if self is null; ESR_OUT_OF_MEMORY if system is out of memory
72	 */
73	ESR_ReturnCode (*setID)(struct SR_Nametag_t* self, const LCHAR* id);
74
75  /**
76   * Clones a nametag.
77   *
78   * @param self Nametag handle
79   * @param result the resulting Nametag
80   * @return ESR_INVALID_ARGUMENT if self is null; ESR_OUT_OF_MEMORY if system is out of memory
81   */
82  ESR_ReturnCode (*clone)(const struct SR_Nametag_t* self, struct SR_Nametag_t** result);
83
84  /**
85	 * Destroys a nametag.
86	 *
87	 * @param self Nametag handle
88	 * @return ESR_SUCCESS
89	 */
90	ESR_ReturnCode (*destroy)(struct SR_Nametag_t* self);
91} SR_Nametag;
92
93/**
94 * @}
95 */
96
97#endif /* __SR_NAMETAGDEFS_H */
98