Home | History | Annotate | Download | only in lib
      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 picoapi.c
     18  *
     19  * Copyright (C) 2008-2009 SVOX AG, Baslerstr. 30, 8048 Zuerich, Switzerland
     20  * All rights reserved.
     21  *
     22  * History:
     23  * - 2009-04-20 -- initial version
     24  */
     25 #include "picodefs.h"
     26 #include "picoos.h"
     27 #include "picodbg.h"
     28 #include "picorsrc.h"
     29 #include "picoctrl.h"
     30 #include "picoapi.h"
     31 #include "picoapid.h"
     32 
     33 #ifdef __cplusplus
     34 extern "C" {
     35 #endif
     36 
     37 /* ****************************************************************************/
     38 /* System-level API functions                                                 */
     39 /* ****************************************************************************/
     40 
     41 #define MAGIC_MASK 0x5069636F  /* Pico */
     42 
     43 #define SET_MAGIC_NUMBER(sys) \
     44     (sys)->magic = ((picoos_uint32) (sys)) ^ MAGIC_MASK
     45 
     46 #define CHECK_MAGIC_NUMBER(sys) \
     47     ((sys)->magic == (((picoos_uint32) (sys)) ^ MAGIC_MASK))
     48 
     49 
     50 
     51 /* *** Auxiliary routines (may also be called from picoextapi.c) **************/
     52 
     53 
     54 int is_valid_system_handle(pico_System system)
     55 {
     56     return (system != NULL) && CHECK_MAGIC_NUMBER(system);
     57 }
     58 
     59 
     60 picoos_Common pico_sysGetCommon(pico_System this)
     61 {
     62     if (this != NULL) {
     63         return this->common;
     64     } else {
     65         return NULL;
     66     }
     67 }
     68 
     69 
     70 
     71 /* *** System initialization and termination functions ************************/
     72 pico_Status pico_initialize_priv(
     73         void *memory,
     74         const pico_Uint32 size,
     75         pico_Int16 enableMemProt,
     76         pico_System *system
     77         )
     78 {
     79     pico_Status status = PICO_OK;
     80 
     81     PICODBG_INITIALIZE(PICODBG_LOG_LEVEL_INFO);
     82     PICODBG_ENABLE_COLORS(0);
     83     /*PICODBG_SET_OUTPUT_FORMAT((PICODBG_SHOW_LEVEL | PICODBG_SHOW_SRCNAME));*/
     84 
     85     if (memory == NULL) {
     86         status = PICO_ERR_NULLPTR_ACCESS;
     87     } else if (size == 0) {
     88         status = PICO_ERR_INVALID_ARGUMENT;
     89     } else if (system == NULL) {
     90         status = PICO_ERR_NULLPTR_ACCESS;
     91     } else {
     92         byte_ptr_t rest_mem;
     93         picoos_uint32 rest_mem_size;
     94         pico_System sys;
     95         picoos_MemoryManager sysMM;
     96         picoos_ExceptionManager sysEM;
     97 
     98         sys = (pico_System) picoos_raw_malloc(memory, size, sizeof(pico_system_t),
     99                 &rest_mem, &rest_mem_size);
    100         if (sys != NULL) {
    101             sysMM = picoos_newMemoryManager(rest_mem, rest_mem_size, enableMemProt ? TRUE : FALSE);
    102             if (sysMM != NULL) {
    103                 sysEM = picoos_newExceptionManager(sysMM);
    104                 sys->common = picoos_newCommon(sysMM);
    105                 sys->rm = picorsrc_newResourceManager(sysMM, sys->common);
    106                 if ((sysEM != NULL) && (sys->common != NULL) && (sys->rm != NULL)) {
    107                     sys->common->em = sysEM;
    108                     sys->common->mm = sysMM;
    109                     sys->engine = NULL;
    110 
    111                     picorsrc_createDefaultResource(sys->rm /*,&defaultResource */);
    112 
    113                     SET_MAGIC_NUMBER(sys);
    114                     status = PICO_OK;
    115                 } else {
    116                     status = PICO_EXC_OUT_OF_MEM;
    117                 }
    118             } else {
    119                 status = PICO_EXC_OUT_OF_MEM;
    120             }
    121         } else {
    122             status = PICO_EXC_OUT_OF_MEM;
    123         }
    124         *system = sys;
    125     }
    126 
    127     if (status != PICO_OK) {
    128         if (system != NULL) {
    129             *system = NULL;
    130         }
    131         PICODBG_TERMINATE();
    132     }
    133 
    134     return status;
    135 }
    136 /**
    137  * pico_initialize : initializes the pico system private memory
    138  * @param    memory : pointer to a free and already allocated memory area
    139  * @param    size : size of the memory area
    140  * @param    system : pointer to a pico_System struct
    141  * @return  PICO_OK : successful init, !PICO_OK : error on allocating private memory
    142  * @callgraph
    143  * @callergraph
    144 */
    145 PICO_FUNC pico_initialize(
    146         void *memory,
    147         const pico_Uint32 size,
    148         pico_System *system
    149         )
    150 {
    151     return pico_initialize_priv(memory, size, /*enableMemProt*/ FALSE, system);
    152 }
    153 
    154 /**
    155  * pico_terminate : deallocates the pico system private memory
    156  * @param    system : pointer to a pico_System struct
    157  * @return  PICO_OK : successful de-init, !PICO_OK : error on de-allocating private memory
    158  * @callgraph
    159  * @callergraph
    160 */
    161 PICO_FUNC pico_terminate(
    162         pico_System *system
    163         )
    164 {
    165     pico_Status status = PICO_OK;
    166 
    167     if ((system == NULL) || !is_valid_system_handle(*system)) {
    168         status = PICO_ERR_INVALID_HANDLE;
    169     } else {
    170         pico_System sys = *system;
    171 
    172         /* close engine(s) */
    173         picoctrl_disposeEngine(sys->common->mm, sys->rm, &sys->engine);
    174 
    175         /* close all resources */
    176         picorsrc_disposeResourceManager(sys->common->mm, &sys->rm);
    177 
    178         sys->magic ^= 0xFFFEFDFC;
    179         *system = NULL;
    180     }
    181 
    182     PICODBG_TERMINATE();
    183 
    184     return status;
    185 }
    186 
    187 
    188 
    189 /* *** System status and error/warning message retrieval function *************/
    190 
    191 /**
    192  * pico_getSystemStatusMessage : Returns a description of the system status or errors
    193  * @param    system : pointer to a pico_System struct
    194  * @param    errCode : pico_System error code
    195  * @param    outMessage : memory area where to return a string
    196  * @return  PICO_OK : successful
    197  * @return     PICO_ERR_INVALID_HANDLE, PICO_ERR_NULLPTR_ACCESS : errors
    198  * @callgraph
    199  * @callergraph
    200 */
    201 PICO_FUNC pico_getSystemStatusMessage(
    202         pico_System system,
    203         pico_Status errCode,
    204         pico_Retstring outMessage
    205         )
    206 {
    207     pico_Status status = PICO_OK;
    208 
    209     if (!is_valid_system_handle(system)) {
    210         status = PICO_ERR_INVALID_HANDLE;
    211         if (outMessage != NULL) {
    212             picoos_strlcpy((picoos_char *) outMessage, (picoos_char *) "'system' not initialized", PICO_RETSTRINGSIZE);
    213         }
    214     } else if (outMessage == NULL) {
    215         status = PICO_ERR_NULLPTR_ACCESS;
    216     } else {
    217         if (picoos_emGetExceptionCode(system->common->em) == PICO_OK) {
    218             if (errCode == PICO_OK) {
    219                 picoos_strlcpy((picoos_char *) outMessage, (picoos_char *) "system ok", PICO_RETSTRINGSIZE);
    220             } else {
    221                 /* exceptionManager was not informed yet; produce default message */
    222                 picoos_setErrorMsg((picoos_char *) outMessage, PICO_RETSTRINGSIZE, errCode, NULL, NULL, NULL);
    223             }
    224         } else {
    225             picoos_emGetExceptionMessage(system->common->em, (picoos_char *) outMessage, PICO_RETSTRINGSIZE);
    226         }
    227     }
    228 
    229     return status;
    230 }
    231 
    232 /**
    233  * pico_getSystemStatusMessage : Returns the number of warnings
    234  * @param    system : pointer to a pico_System struct
    235  * @param    *outNrOfWarnings : pointer to location to receive number of warnings
    236  * @return  PICO_OK : successful
    237  * @return     PICO_ERR_INVALID_HANDLE, PICO_ERR_NULLPTR_ACCESS : errors
    238  * @callgraph
    239  * @callergraph
    240 */
    241 PICO_FUNC pico_getNrSystemWarnings(
    242         pico_System system,
    243         pico_Int32 *outNrOfWarnings
    244         )
    245 {
    246     pico_Status status = PICO_OK;
    247 
    248     if (!is_valid_system_handle(system)) {
    249         status = PICO_ERR_INVALID_HANDLE;
    250         if (outNrOfWarnings != NULL) {
    251             *outNrOfWarnings = 0;
    252         }
    253     } else if (outNrOfWarnings == NULL) {
    254         status = PICO_ERR_NULLPTR_ACCESS;
    255     } else {
    256         *outNrOfWarnings = picoos_emGetNumOfWarnings(system->common->em);
    257     }
    258 
    259     return status;
    260 }
    261 
    262 /**
    263  * pico_getSystemWarning : Returns a description of a warning
    264  * @param    system : pointer to a pico_System struct
    265  * @param    warningIndex : warning index
    266  * @param    *outCode : pointer to receive the warning code
    267  * @param    outMessage : pointer to receive the output message
    268  * @return  PICO_OK : successful
    269  * @return     PICO_ERR_INVALID_HANDLE, PICO_ERR_NULLPTR_ACCESS : errors
    270  * @callgraph
    271  * @callergraph
    272 */
    273 PICO_FUNC pico_getSystemWarning(
    274         pico_System system,
    275         const pico_Int32 warningIndex,
    276         pico_Status *outCode,
    277         pico_Retstring outMessage
    278         )
    279 {
    280     pico_Status status = PICO_OK;
    281 
    282     if (!is_valid_system_handle(system)) {
    283         status = PICO_ERR_INVALID_HANDLE;
    284         if (outMessage != NULL) {
    285             picoos_strlcpy((picoos_char *) outMessage, (picoos_char *) "'system' not initialized", PICO_RETSTRINGSIZE);
    286         }
    287     } else if (warningIndex < 0) {
    288         status = PICO_ERR_INDEX_OUT_OF_RANGE;
    289     } else if ((outCode == NULL) || (outMessage == NULL)) {
    290         status = PICO_ERR_NULLPTR_ACCESS;
    291     } else {
    292         *outCode = picoos_emGetWarningCode(system->common->em, warningIndex);
    293         picoos_emGetWarningMessage(system->common->em, warningIndex, (picoos_char *) outMessage, (picoos_uint16) PICO_RETSTRINGSIZE);
    294     }
    295 
    296     return status;
    297 }
    298 
    299 
    300 
    301 /* *** Resource loading and unloading functions *******************************/
    302 
    303 /**
    304  * pico_loadResource : Loads a resource file into the Pico system
    305  * @param    system : pointer to a pico_System struct
    306  * @param    *lingwareFileName : lingware resource file name
    307  * @param    *outLingware : pointer to receive the loaded lingware resource memory area address
    308  * @return  PICO_OK : successful
    309  * @return     PICO_ERR_INVALID_HANDLE, PICO_ERR_NULLPTR_ACCESS : errors
    310  * @callgraph
    311  * @callergraph
    312 */
    313 PICO_FUNC pico_loadResource(
    314         pico_System system,
    315         const pico_Char *lingwareFileName,
    316         pico_Resource *outLingware
    317         )
    318 {
    319     pico_Status status = PICO_OK;
    320 
    321     if (!is_valid_system_handle(system)) {
    322         status = PICO_ERR_INVALID_HANDLE;
    323     } else if ((lingwareFileName == NULL) || (outLingware == NULL)) {
    324         status = PICO_ERR_NULLPTR_ACCESS;
    325     } else {
    326         PICODBG_DEBUG(("memory usage before resource loading"));
    327         picoos_showMemUsage(system->common->mm, FALSE, TRUE);
    328         picoos_emReset(system->common->em);
    329         status = picorsrc_loadResource(system->rm, (picoos_char *) lingwareFileName, (picorsrc_Resource *) outLingware);
    330         PICODBG_DEBUG(("memory used to load resource %s", lingwareFileName));
    331         picoos_showMemUsage(system->common->mm, TRUE, FALSE);
    332     }
    333 
    334     return status;
    335 }
    336 
    337 /**
    338  * pico_unloadResource : unLoads a resource file from the Pico system
    339  * @param    system : pointer to a pico_System struct
    340  * @param    *inoutLingware : pointer to the loaded lingware resource memory area address
    341  * @return  PICO_OK : successful
    342  * @return     PICO_ERR_INVALID_HANDLE, PICO_ERR_NULLPTR_ACCESS : errors
    343  * @callgraph
    344  * @callergraph
    345 */
    346 PICO_FUNC pico_unloadResource(
    347         pico_System system,
    348         pico_Resource *inoutLingware
    349         )
    350 {
    351     pico_Status status = PICO_OK;
    352 
    353     if (!is_valid_system_handle(system)) {
    354         status = PICO_ERR_INVALID_HANDLE;
    355     } else if (inoutLingware == NULL) {
    356         status = PICO_ERR_NULLPTR_ACCESS;
    357     } else if (!picoctrl_isValidResourceHandle(*((picorsrc_Resource *) inoutLingware))) {
    358         status = PICO_ERR_INVALID_HANDLE;
    359     } else {
    360         PICODBG_DEBUG(("memory usage before resource unloading"));
    361         picoos_showMemUsage(system->common->mm, FALSE, TRUE);
    362         picoos_emReset(system->common->em);
    363         status = picorsrc_unloadResource(system->rm, (picorsrc_Resource *) inoutLingware);
    364         PICODBG_DEBUG(("memory released by resource unloading"));
    365         picoos_showMemUsage(system->common->mm, TRUE, FALSE);
    366     }
    367 
    368     return status;
    369 }
    370 
    371 /* *** Resource inspection functions *******************************/
    372 /**
    373  * pico_getResourceName : Gets a resource name
    374  * @param    system : pointer to a pico_System struct
    375  * @param    resource : pointer to the loaded resource memory area address
    376  * @param    outName : pointer to the area to receuive the resource name
    377  * @return  PICO_OK : successful
    378  * @return     PICO_ERR_INVALID_HANDLE, PICO_ERR_NULLPTR_ACCESS : errors
    379  * @callgraph
    380  * @callergraph
    381 */
    382 PICO_FUNC pico_getResourceName(
    383         pico_System system,
    384         pico_Resource resource,
    385         pico_Retstring outName) {
    386 
    387     if (!is_valid_system_handle(system)) {
    388         return PICO_ERR_INVALID_HANDLE;
    389     } else if (NULL == outName) {
    390         return PICO_ERR_NULLPTR_ACCESS;
    391     }
    392     return picorsrc_rsrcGetName((picorsrc_Resource)resource, (picoos_char *) outName, PICO_RETSTRINGSIZE);
    393 }
    394 
    395 
    396 /* *** Voice definition functions *********************************************/
    397 
    398 /**
    399  * pico_createVoiceDefinition : Creates a voice definition
    400  * @param    system : pointer to a pico_System struct
    401  * @param    *voiceName : pointer to the area to receive the voice definition
    402  * @return  PICO_OK : successful
    403  * @return     PICO_ERR_INVALID_HANDLE, PICO_ERR_NULLPTR_ACCESS : errors
    404  * @callgraph
    405  * @callergraph
    406 */
    407 PICO_FUNC pico_createVoiceDefinition(
    408         pico_System system,
    409         const pico_Char *voiceName
    410         )
    411 {
    412     pico_Status status = PICO_OK;
    413 
    414     if (!is_valid_system_handle(system)) {
    415         status = PICO_ERR_INVALID_HANDLE;
    416     } else if (voiceName == NULL) {
    417         status = PICO_ERR_NULLPTR_ACCESS;
    418     } else if (picoos_strlen((picoos_char *) voiceName) == 0) {
    419         status = PICO_ERR_INVALID_ARGUMENT;
    420     } else {
    421         picoos_emReset(system->common->em);
    422         status = picorsrc_createVoiceDefinition(system->rm, (picoos_char *) voiceName);
    423     }
    424 
    425     return status;
    426 }
    427 
    428 /**
    429  * pico_addResourceToVoiceDefinition : Adds a mapping pair to a voice definition
    430  * @param    system : pointer to a pico_System struct
    431  * @param    *voiceName : pointer to the area containing the voice definition
    432  * @param    *resourceName : pointer to the area containing the resource name
    433  * @return  PICO_OK : successful
    434  * @return     PICO_ERR_INVALID_HANDLE, PICO_ERR_NULLPTR_ACCESS : errors
    435  * @callgraph
    436  * @callergraph
    437 */
    438 PICO_FUNC pico_addResourceToVoiceDefinition(
    439         pico_System system,
    440         const pico_Char *voiceName,
    441         const pico_Char *resourceName
    442         )
    443 {
    444     pico_Status status = PICO_OK;
    445 
    446     if (!is_valid_system_handle(system)) {
    447         status = PICO_ERR_INVALID_HANDLE;
    448     } else if (voiceName == NULL) {
    449         status = PICO_ERR_NULLPTR_ACCESS;
    450     } else if (picoos_strlen((picoos_char *) voiceName) == 0) {
    451         status = PICO_ERR_INVALID_ARGUMENT;
    452     } else if (resourceName == NULL) {
    453         status = PICO_ERR_NULLPTR_ACCESS;
    454     } else if (picoos_strlen((picoos_char *) resourceName) == 0) {
    455         status = PICO_ERR_INVALID_ARGUMENT;
    456     } else {
    457         picoos_emReset(system->common->em);
    458         status = picorsrc_addResourceToVoiceDefinition(system->rm, (picoos_char *) voiceName, (picoos_char *) resourceName);
    459     }
    460 
    461     return status;
    462 }
    463 
    464 /**
    465  * pico_releaseVoiceDefinition : Releases a voice definition
    466  * @param    system : pointer to a pico_System struct
    467  * @param    *voiceName : pointer to the area containing the voice definition
    468  * @return  PICO_OK : successful
    469  * @return     PICO_ERR_INVALID_HANDLE, PICO_ERR_NULLPTR_ACCESS : errors
    470  * @callgraph
    471  * @callergraph
    472 */
    473 PICO_FUNC pico_releaseVoiceDefinition(
    474         pico_System system,
    475         const pico_Char *voiceName
    476         )
    477 {
    478     pico_Status status = PICO_OK;
    479 
    480     if (!is_valid_system_handle(system)) {
    481         status = PICO_ERR_INVALID_HANDLE;
    482     } else if (voiceName == NULL) {
    483         status = PICO_ERR_NULLPTR_ACCESS;
    484     } else if (picoos_strlen((picoos_char *) voiceName) == 0) {
    485         status = PICO_ERR_INVALID_ARGUMENT;
    486     } else {
    487         picoos_emReset(system->common->em);
    488         status = picorsrc_releaseVoiceDefinition(system->rm, (picoos_char *) voiceName);
    489     }
    490 
    491     return status;
    492 }
    493 
    494 
    495 
    496 /* *** Engine creation and deletion functions *********************************/
    497 
    498 /**
    499  * pico_newEngine : Creates and initializes a new Pico engine
    500  * @param    system : pointer to a pico_System struct
    501  * @param    *voiceName : pointer to the area containing the voice definition
    502  * @param    *outEngine : pointer to the Pico engine handle
    503  * @return  PICO_OK : successful
    504  * @return     PICO_ERR_INVALID_HANDLE, PICO_ERR_NULLPTR_ACCESS : errors
    505  * @callgraph
    506  * @callergraph
    507 */
    508 PICO_FUNC pico_newEngine(
    509         pico_System system,
    510         const pico_Char *voiceName,
    511         pico_Engine *outEngine
    512         )
    513 {
    514     pico_Status status = PICO_OK;
    515 
    516     PICODBG_DEBUG(("creating engine for voice '%s'", (picoos_char *) voiceName));
    517 
    518     if (!is_valid_system_handle(system)) {
    519         status = PICO_ERR_INVALID_HANDLE;
    520     } else if (voiceName == NULL) {
    521         status = PICO_ERR_NULLPTR_ACCESS;
    522     } else if (picoos_strlen((picoos_char *) voiceName) == 0) {
    523         status = PICO_ERR_INVALID_ARGUMENT;
    524     } else if (outEngine == NULL) {
    525         status = PICO_ERR_NULLPTR_ACCESS;
    526     } else {
    527         picoos_emReset(system->common->em);
    528         if (system->engine == NULL) {
    529             *outEngine = (pico_Engine) picoctrl_newEngine(system->common->mm, system->rm, voiceName);
    530             if (*outEngine != NULL) {
    531                 system->engine = (picoctrl_Engine) *outEngine;
    532             } else {
    533                 status = picoos_emRaiseException(system->common->em, PICO_EXC_OUT_OF_MEM,
    534                             (picoos_char *) "out of memory creating new engine", NULL);
    535             }
    536         } else {
    537             status = picoos_emRaiseException(system->common->em, PICO_EXC_MAX_NUM_EXCEED,
    538                         NULL, (picoos_char *) "no more than %i engines", 1);
    539         }
    540     }
    541 
    542     return status;
    543 }
    544 
    545 /**
    546  * pico_disposeEngine : Disposes a Pico engine
    547  * @param    system : pointer to a pico_System struct
    548  * @param    *inoutEngine : pointer to the Pico engine handle
    549  * @return  PICO_OK : successful
    550  * @return     PICO_ERR_INVALID_HANDLE, PICO_ERR_NULLPTR_ACCESS : errors
    551  * @callgraph
    552  * @callergraph
    553 */
    554 PICO_FUNC pico_disposeEngine(
    555         pico_System system,
    556         pico_Engine *inoutEngine
    557         )
    558 {
    559     pico_Status status = PICO_OK;
    560 
    561     if (!is_valid_system_handle(system)) {
    562         status = PICO_ERR_INVALID_HANDLE;
    563     } else if (inoutEngine == NULL) {
    564         status = PICO_ERR_NULLPTR_ACCESS;
    565     } else if (!picoctrl_isValidEngineHandle(*((picoctrl_Engine *) inoutEngine))) {
    566         status = PICO_ERR_INVALID_HANDLE;
    567     } else {
    568         picoos_emReset(system->common->em);
    569         picoctrl_disposeEngine(system->common->mm, system->rm, (picoctrl_Engine *) inoutEngine);
    570         system->engine = NULL;
    571         status = picoos_emGetExceptionCode(system->common->em);
    572     }
    573 
    574     return status;
    575 }
    576 
    577 
    578 
    579 /* ****************************************************************************/
    580 /* Engine-level API functions                                                 */
    581 /* ****************************************************************************/
    582 
    583 /**
    584  * pico_putTextUtf8 : Puts UTF8 text into Pico text input buffer
    585  * @param    engine : pointer to a Pico engine handle
    586  * @param    *text : pointer to the text buffer
    587  * @param    textSize : text buffer size
    588  * @param    *bytesPut : pointer to variable to receive the number of bytes put
    589  * @return  PICO_OK : successful
    590  * @return     PICO_ERR_INVALID_HANDLE, PICO_ERR_NULLPTR_ACCESS : errors
    591  * @callgraph
    592  * @callergraph
    593  */
    594 PICO_FUNC pico_putTextUtf8(
    595         pico_Engine engine,
    596         const pico_Char *text,
    597         const pico_Int16 textSize,
    598         pico_Int16 *bytesPut)
    599 {
    600     pico_Status status = PICO_OK;
    601 
    602     if (!picoctrl_isValidEngineHandle((picoctrl_Engine) engine)) {
    603         status = PICO_ERR_INVALID_HANDLE;
    604     } else if (text == NULL) {
    605         status = PICO_ERR_NULLPTR_ACCESS;
    606     } else if (textSize < 0) {
    607         status = PICO_ERR_INVALID_ARGUMENT;
    608     } else if (bytesPut == NULL) {
    609         status = PICO_ERR_NULLPTR_ACCESS;
    610     } else {
    611         picoctrl_engResetExceptionManager((picoctrl_Engine) engine);
    612         status = picoctrl_engFeedText((picoctrl_Engine) engine, (picoos_char *)text, textSize, bytesPut);
    613     }
    614 
    615     return status;
    616 }
    617 
    618 /**
    619  * pico_getData : Gets speech data from the engine.
    620  * @param    engine : pointer to a Pico engine handle
    621  * @param    *buffer : pointer to output buffer
    622  * @param    bufferSize : out buffer size
    623  * @param    *bytesReceived : pointer to a variable to receive the number of bytes received
    624  * @param    *outDataType : pointer to a variable to receive the type of buffer received
    625  * @return  PICO_OK : successful
    626  * @return     PICO_ERR_INVALID_HANDLE, PICO_ERR_NULLPTR_ACCESS : errors
    627  * @callgraph
    628  * @callergraph
    629 */
    630 PICO_FUNC pico_getData(
    631         pico_Engine engine,
    632         void *buffer,
    633         const pico_Int16 bufferSize,
    634         pico_Int16 *bytesReceived,
    635         pico_Int16 *outDataType
    636         )
    637 {
    638     pico_Status status = PICO_OK;
    639 
    640     if (!picoctrl_isValidEngineHandle((picoctrl_Engine) engine)) {
    641         status = PICO_STEP_ERROR;
    642     } else if (buffer == NULL) {
    643         status = PICO_STEP_ERROR;
    644     } else if (bufferSize < 0) {
    645         status = PICO_STEP_ERROR;
    646     } else if (bytesReceived == NULL) {
    647         status = PICO_STEP_ERROR;
    648     } else {
    649         picoctrl_engResetExceptionManager((picoctrl_Engine) engine);
    650         status = picoctrl_engFetchOutputItemBytes((picoctrl_Engine) engine, (picoos_char *)buffer, bufferSize, bytesReceived);
    651         if ((status != PICO_STEP_IDLE) && (status != PICO_STEP_BUSY)) {
    652             status = PICO_STEP_ERROR;
    653         }
    654     }
    655 
    656     *outDataType = PICO_DATA_PCM_16BIT;
    657     return status;
    658 }
    659 
    660 /**
    661  * pico_resetEngine : Resets the engine
    662  * @param    engine : pointer to a Pico engine handle
    663  * @param resetMode : reset mode; one of PICO_RESET_FULL or PICO_RESET_SOFT
    664  * @return  PICO_OK : successful
    665  * @return     PICO_ERR_INVALID_HANDLE, PICO_ERR_NULLPTR_ACCESS : errors
    666  * @callgraph
    667  * @callergraph
    668 */
    669 PICO_FUNC pico_resetEngine(
    670         pico_Engine engine,
    671         pico_Int32 resetMode)
    672 {
    673     pico_Status status = PICO_OK;
    674 
    675     if (!picoctrl_isValidEngineHandle((picoctrl_Engine) engine)) {
    676         status = PICO_ERR_INVALID_HANDLE;
    677     } else {
    678         picoctrl_engResetExceptionManager((picoctrl_Engine) engine);
    679 
    680         resetMode = (PICO_RESET_SOFT == resetMode) ? PICO_RESET_SOFT : PICO_RESET_FULL;
    681 
    682         status = picoctrl_engReset((picoctrl_Engine) engine, (picoos_int32)resetMode);
    683     }
    684 
    685     return status;
    686 }
    687 
    688 /**
    689  * pico_getEngineStatusMessage : Returns the engine status or error description
    690  * @param    engine : pointer to a Pico engine handle
    691  * @param    errCode : error code
    692  * @param    outMessage : pointer to a memory area to receive the output message
    693  * @return  PICO_OK : successful
    694  * @return     PICO_ERR_INVALID_HANDLE, PICO_ERR_NULLPTR_ACCESS : errors
    695  * @callgraph
    696  * @callergraph
    697 */
    698 PICO_FUNC pico_getEngineStatusMessage(
    699         pico_Engine engine,
    700         pico_Status errCode,
    701         pico_Retstring outMessage
    702         )
    703 {
    704     pico_Status status = PICO_OK;
    705 
    706     PICODBG_DEBUG(("got error code %i", errCode));
    707 
    708     if (!picoctrl_isValidEngineHandle((picoctrl_Engine) engine)) {
    709         status = PICO_ERR_INVALID_HANDLE;
    710         if (outMessage != NULL) {
    711             picoos_strlcpy((picoos_char *) outMessage, (picoos_char *) "'engine' not initialized", PICO_RETSTRINGSIZE);
    712         }
    713     } else if (outMessage == NULL) {
    714         status = PICO_ERR_NULLPTR_ACCESS;
    715     } else {
    716         picoos_Common common = picoctrl_engGetCommon((picoctrl_Engine) engine);
    717         if (picoos_emGetExceptionCode(common->em) == PICO_OK) {
    718             if (errCode == PICO_OK) {
    719                 picoos_strlcpy((picoos_char *) outMessage, (picoos_char *) "engine ok", PICO_RETSTRINGSIZE);
    720             } else {
    721                 /* exceptionManager was not informed yet; produce default message */
    722                 picoos_setErrorMsg((picoos_char *) outMessage, PICO_RETSTRINGSIZE, errCode, NULL, NULL, NULL);
    723             }
    724         } else {
    725             picoos_emGetExceptionMessage(common->em, (picoos_char *) outMessage, PICO_RETSTRINGSIZE);
    726         }
    727     }
    728 
    729     return status;
    730 }
    731 
    732 /**
    733  * pico_getNrEngineWarnings : Returns the number of warnings
    734  * @param    engine : pointer to a Pico engine handle
    735  * @param    *outNrOfWarnings: pointer to a variable to receive the number of warnings
    736  * @return  PICO_OK : successful
    737  * @return     PICO_ERR_INVALID_HANDLE, PICO_ERR_NULLPTR_ACCESS : errors
    738  * @callgraph
    739  * @callergraph
    740 */
    741 PICO_FUNC pico_getNrEngineWarnings(
    742         pico_Engine engine,
    743         pico_Int32 *outNrOfWarnings
    744         )
    745 {
    746     pico_Status status = PICO_OK;
    747 
    748     if (!picoctrl_isValidEngineHandle((picoctrl_Engine) engine)) {
    749         status = PICO_ERR_INVALID_HANDLE;
    750         if (outNrOfWarnings != NULL) {
    751             *outNrOfWarnings = 0;
    752         }
    753     } else if (outNrOfWarnings == NULL) {
    754         status = PICO_ERR_NULLPTR_ACCESS;
    755     } else {
    756         picoos_Common common = picoctrl_engGetCommon((picoctrl_Engine) engine);
    757         *outNrOfWarnings = picoos_emGetNumOfWarnings(common->em);
    758     }
    759 
    760     return status;
    761 }
    762 
    763 /**
    764      * pico_getEngineWarning : Returns a description of a warning
    765      * @param    engine : pointer to a Pico engine handle
    766      * @param    warningIndex : warning index
    767      * @param    *outCode: pointer to a variable to receive the warning code
    768      * @param    outMessage: pointer to a memory area to receive the warning description
    769      * @return  PICO_OK : successful
    770      * @return     PICO_ERR_INVALID_HANDLE, PICO_ERR_NULLPTR_ACCESS : errors
    771      * @callgraph
    772      * @callergraph
    773 */
    774 PICO_FUNC pico_getEngineWarning(
    775         pico_Engine engine,
    776         const pico_Int32 warningIndex,
    777         pico_Status *outCode,
    778         pico_Retstring outMessage
    779         )
    780 {
    781     pico_Status status = PICO_OK;
    782 
    783     if (!picoctrl_isValidEngineHandle((picoctrl_Engine) engine)) {
    784         status = PICO_ERR_INVALID_HANDLE;
    785         if (outMessage != NULL) {
    786             picoos_strlcpy((picoos_char *) outMessage, (picoos_char *) "'engine' not initialized", PICO_RETSTRINGSIZE);
    787         }
    788     } else if (warningIndex < 0) {
    789         status = PICO_ERR_INDEX_OUT_OF_RANGE;
    790     } else if ((outCode == NULL) || (outMessage == NULL)) {
    791         status = PICO_ERR_NULLPTR_ACCESS;
    792     } else {
    793         picoos_Common common = picoctrl_engGetCommon((picoctrl_Engine) engine);
    794         *outCode = picoos_emGetWarningCode(common->em, warningIndex);
    795         picoos_emGetWarningMessage(common->em, warningIndex, (picoos_char *) outMessage, (picoos_uint16) PICO_RETSTRINGSIZE);
    796     }
    797 
    798     return status;
    799 }
    800 
    801 #ifdef __cplusplus
    802 }
    803 #endif
    804 
    805 
    806 /* end */
    807