1/*---------------------------------------------------------------------------*
2 *  SR_Nametag.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_NAMETAG_H
21#define __SR_NAMETAG_H
22
23
24
25#include "SR_NametagDefs.h"
26#include "SR_Recognizer.h"
27#include "SR_RecognizerResult.h"
28
29/**
30 * Create a new Nametag from the last recognition result.
31 *
32 * @param result RecognizerResult handle
33 * @param id Nametag id
34 * @param self Nametag handle
35 * @return ESR_OUT_OF_MEMORY if the system is out of memory; ESR_INVALID_ARGUMENT if result, self or the
36 * value pointed to by value are null; ESR_INVALID_STATE if the nametag value is invalid
37 */
38SREC_NAMETAG_API ESR_ReturnCode SR_NametagCreate(const SR_RecognizerResult* result,
39    const LCHAR* id,
40    SR_Nametag** self);
41
42/**
43 * Create a new Nametag from the persistent storage
44 *
45 * @param id Nametag id
46 * @param value Transcription content (opaque)
47 * @param len length of the value (number of opaque bytes)
48 * @param self Nametag handle
49 * @return ESR_OUT_OF_MEMORY if the system is out of memory; ESR_INVALID_ARGUMENT if result, self or the
50 * value pointed to by value are null; ESR_INVALID_STATE if the nametag value is invalid
51 */
52SREC_NAMETAG_API ESR_ReturnCode SR_NametagCreateFromValue(const LCHAR* id, const char* value, size_t len, SR_Nametag** self);
53
54/**
55 * Gets the nametag ID.
56 *
57 * @param self Nametag handle
58 * @param id Nametag id
59 * @return ESR_INVALID_ARGUMENT if self is null
60 */
61SREC_NAMETAG_API ESR_ReturnCode SR_NametagGetID(const SR_Nametag* self, LCHAR** id);
62
63/**
64 * Gets the nametag transcription.
65 *
66 * @param self Nametag handle
67 * @param id Nametag id
68 * @return ESR_INVALID_ARGUMENT if self is null
69 */
70SREC_NAMETAG_API ESR_ReturnCode SR_NametagGetValue(const SR_Nametag* self, const char** pvalue, size_t *plen);
71
72/**
73 * Sets the nametag ID.
74 *
75 * @param self Nametag handle
76 * @param id Nametag id
77 * @return ESR_INVALID_ARGUMENT if self is null; ESR_OUT_OF_MEMORY if system is out of memory
78 */
79SREC_NAMETAG_API ESR_ReturnCode SR_NametagSetID(SR_Nametag* self, const LCHAR* id);
80
81/**
82 * Clones a nametag.
83 *
84 * @param self Nametag handle
85 * @param result the resulting Nametag
86 * @return ESR_INVALID_ARGUMENT if self is null; ESR_OUT_OF_MEMORY if system is out of memory
87 */
88SREC_NAMETAG_API ESR_ReturnCode SR_NametagClone(const SR_Nametag* self, SR_Nametag** result);
89
90/**
91 * Destroys a Nametag.
92 *
93 * @param self Nametag handle
94 * @return ESR_SUCCESS
95 */
96SREC_NAMETAG_API ESR_ReturnCode SR_NametagDestroy(SR_Nametag* self);
97
98/**
99 * @}
100 */
101
102
103#endif /* __SR_NAMETAG_H */
104