1/*
2 * Copyright (C) 2008-2009 SVOX AG, Baslerstr. 30, 8048 Zuerich, Switzerland
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *     http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16/**
17 * @file picoextapi.h
18 *
19 * API extensions for development use
20 *
21 * Copyright (C) 2008-2009 SVOX AG, Baslerstr. 30, 8048 Zuerich, Switzerland
22 * All rights reserved.
23 *
24 * History:
25 * - 2009-04-20 -- initial version
26 *
27 */
28
29#ifndef PICOEXTAPI_H_
30#define PICOEXTAPI_H_
31
32#include "picodefs.h"
33#include "picodbg.h"
34
35#ifdef __cplusplus
36extern "C" {
37#endif
38#if 0
39}
40#endif
41
42
43/* ****************************************************************************/
44/* Things that might be added to picoapi later but should not appear there    */
45/* for the time being                                                         */
46/* ****************************************************************************/
47
48/* String type for Unicode text input *****************************************/
49
50/* Unicode encodings supported by PICO. */
51
52#define PICO_STRENC_UTF8    0
53#define PICO_STRENC_UTF16   1
54
55/* An UTF-8 string must point to a byte array, terminated by a null character
56   ('\0'). An UTF-16 string must point to a contiguous array of 16-bit units
57   (in native byte ordering), terminated by a 0. */
58
59typedef char        *PICO_STRING_UTF8;
60typedef pico_Uint16 *PICO_STRING_UTF16;
61
62/* Generic pointer to a Unicode string, encoded either as UTF-8 or UTF-16.
63   The application must make sure that for each 'PICO_STRING_PTR' it provides
64   an argument of type 'PICO_STRING_UTF8' or 'PICO_STRING_UTF16' (or of a type
65   compatible to one of these types). */
66
67typedef void *PICO_STRING_PTR;
68
69
70/* ****************************************************************************/
71/* System-level API functions                                                 */
72/* ****************************************************************************/
73
74/* System initialization and termination functions ****************************/
75
76/* Same as pico_initialize, but allows to enable memory protection
77   functionality for testing purposes (enableMemProt != 0). */
78
79PICO_FUNC picoext_initialize(
80        void *memory,
81        const pico_Uint32 size,
82        pico_Int16 enableMemProt,
83        pico_System *outSystem
84        );
85
86
87/* System and lingware inspection functions ***********************************/
88
89/* Returns version information of the current Pico engine. */
90
91PICO_FUNC picoext_getVersionInfo(
92        pico_Retstring outInfo,
93        const pico_Int16 outInfoMaxLen
94    );
95
96/* Returns unique resource name */
97
98/*
99PICO_FUNC picoext_getResourceName(
100        pico_Resource resource,
101        pico_Retstring outInfo
102    );
103*/
104
105/* Debugging/testing support functions *****************************************/
106
107/* Sets tracing level. Increasing amounts of information is displayed
108   at each level. */
109
110PICO_FUNC picoext_setTraceLevel(
111        pico_System system,
112        pico_Int32 level
113        );
114
115/* Sets trace filtering. Limits tracing output to tracing information
116   resulting from the source file name being filtered. */
117
118PICO_FUNC picoext_setTraceFilterFN(
119        pico_System system,
120        const pico_Char *name
121        );
122
123/* Enables logging of debug output to log file 'name'. If 'name' is NULL
124   or an empty string, logging is disabled. */
125
126PICO_FUNC picoext_setLogFile(
127        pico_System system,
128        const pico_Char *name
129        );
130
131
132/* Memory usage ***************************************************************/
133
134PICO_FUNC picoext_getSystemMemUsage(
135        pico_System system,
136        pico_Int16 resetIncremental,
137        pico_Int32 *outUsedBytes,
138        pico_Int32 *outIncrUsedBytes,
139        pico_Int32 *outMaxUsedBytes
140        );
141
142PICO_FUNC picoext_getEngineMemUsage(
143        pico_Engine engine,
144        pico_Int16 resetIncremental,
145        pico_Int32 *outUsedBytes,
146        pico_Int32 *outIncrUsedBytes,
147        pico_Int32 *outMaxUsedBytes
148        );
149
150PICO_FUNC picoext_getLastScheduledPU(
151        pico_Engine engine
152        );
153
154PICO_FUNC picoext_getLastProducedItemType(
155        pico_Engine engine
156        );
157
158#ifdef __cplusplus
159}
160#endif
161
162
163#endif /* PICOEXTAPI_H_ */
164