/*
 * Copyright (C) 2008-2009 SVOX AG, Baslerstr. 30, 8048 Zuerich, Switzerland
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
/**
 * @file picoapi.h
 *
 * SVOX Pico application programming interface
 * (SVOX Pico version 1.0 and later)
 *
 * Copyright (C) 2008-2009 SVOX AG, Baslerstr. 30, 8048 Zuerich, Switzerland
 * All rights reserved.
 *
 * History:
 * - 2009-04-20 -- initial version
 */


/**
 * @addtogroup picoapi
 *
@b Basic_Concepts

@e SVOX_Pico_System

The SVOX Pico 'system' is the entity that manages data common to all
SVOX Pico engines, e.g. linguistic data needed to do text-to-speech
(TTS) synthesis, license key, etc.  All API functions on the Pico
system level take a 'pico_System' handle as the first parameter.

@e SVOX_Pico_Engine

A SVOX Pico 'engine' provides the functions needed to perform actual
synthesis. Currently there can be only one engine instance at a time
(concurrent engines will be possible in the future). All API functions
at the engine level take a 'pico_Engine' handle as the first
parameter.

@e SVOX_Pico_Resource

A SVOX Pico 'resource' denotes all the language- and speaker-dependent
data needed to do TTS synthesis. In the following, the term 'resource'
may be used interchangeably with the term 'lingware'. A resource file
contains a set of knowledge bases for an entire TTS voice or parts of
it.


@b Basic_Usage

In its most basic form, an application must call the following
functions in order to perform TTS synthesis:

   - pico_initialize
   - pico_loadResource
   - pico_createVoiceDefinition
   - pico_addResourceToVoiceDefinition
   - pico_newEngine
   - pico_putTextUtf8
   - pico_getData (several times)
   - pico_disposeEngine
   - pico_releaseVoiceDefinition
   - pico_unloadResource
   - pico_terminate

It is possible to repeatedly run the above sequence, i.e., the SVOX
Pico system may be initialized and terminated multiple times. This may
be useful in applications that need TTS functionality only from time
to time.


@b Conventions

@e Function_arguments

All arguments that only return values are marked by a leading 'out...'
in their name. All arguments that are used as input and output values
are marked by a leading 'inout...'. All other arguments are read-only
(input) arguments.

@e Error_handling

All API functions return a status code which is one of the status
constants defined in picodefs.h. In case of an error, a more detailed
description of the status can be retrieved by calling function
'pico_getSystemStatusMessage' (or 'pico_getEngineStatusMessage'
if the error happened on the SVOX Pico engine level).

Unlike errors, warnings do not prevent an API function from performing
its function, but output might not be as intended. Functions
'pico_getNrSystemWarnings' and 'pico_getNrEngineWarnings' respectively
can be used to determine whether an API function caused any
warnings. Details about warnings can be retrieved by calling
'pico_getSystemWarning' and 'pico_getEngineWarning' respectively.

*/


#ifndef PICOAPI_H_
#define PICOAPI_H_


#include "picodefs.h"

#ifdef __cplusplus
extern "C" {
#endif
#if 0
}
#endif


#ifdef _WIN32
#  define PICO_EXPORT  __declspec( dllexport )
#else
#  define PICO_EXPORT extern
#endif

#define PICO_FUNC PICO_EXPORT pico_Status


/* ********************************************************************/
/* PICO data types                                                    */
/* ********************************************************************/

/* Handle types (opaque) for Pico system, resource, engine ************/

typedef struct pico_system   *pico_System;
typedef struct pico_resource *pico_Resource;
typedef struct pico_engine   *pico_Engine;


/* Signed/unsigned integer data types *********************************/

#define PICO_INT16_MAX   32767
#define PICO_UINT16_MAX  0xffff
#define PICO_INT32_MAX   2147483647
#define PICO_UINT32_MAX  0xffffffff

#include <limits.h>

#if (SHRT_MAX == PICO_INT16_MAX)
typedef short pico_Int16;
#else
#error "platform not supported"
#endif

#if (USHRT_MAX == PICO_UINT16_MAX)
typedef unsigned short pico_Uint16;
#else
#error "platform not supported"
#endif

#if (INT_MAX == PICO_INT32_MAX)
typedef int pico_Int32;
#else
#error "platform not supported"
#endif

#if (UINT_MAX == PICO_UINT32_MAX)
typedef unsigned int pico_Uint32;
#else
#error "platform not supported"
#endif


/* Char data type *****************************************************/

typedef unsigned char pico_Char;


/* String type to be used when ASCII string values are returned *******/

#define PICO_RETSTRINGSIZE 200  /* maximum length of returned strings */

typedef char pico_Retstring[PICO_RETSTRINGSIZE];


/* ********************************************************************/
/* System-level API functions                                         */
/* ********************************************************************/

/* System initialization and termination functions ********************/

/**
   Initializes the Pico system and returns its handle in 'outSystem'.
   'memory' and 'size' define the location and maximum size of memory
   in number of bytes that the Pico system will use. The minimum size
   required depends on the number of engines and configurations of
   lingware to be used. No additional memory will be allocated by the
   Pico system. This function must be called before any other API
   function is called. It may only be called once (e.g. at application
   startup), unless a call to 'pico_terminate'.
*/
PICO_FUNC pico_initialize(
        void *memory,
        const pico_Uint32 size,
        pico_System *outSystem
        );

/**
   Terminates the Pico system. Lingware resources still being loaded
   are unloaded automatically. The memory area provided to Pico in
   'pico_initialize' is released. The system handle becomes
   invalid. It is not allowed to call this function as long as Pico
   engine instances are existing. No API function may be called after
   this function, except for 'pico_initialize', which reinitializes
   the system.
*/
PICO_FUNC pico_terminate(
        pico_System *system
        );


/* System status and error/warning message retrieval ******************/

/**
   Returns in 'outMessage' a description of the system status or of an
   error that occurred with the most recently called system-level API
   function.
*/
PICO_FUNC pico_getSystemStatusMessage(
        pico_System system,
        pico_Status errCode,
        pico_Retstring outMessage
        );

/**
   Returns in 'outNrOfWarnings' the number of warnings that occurred
   with the most recently called system-level API function.
*/
PICO_FUNC pico_getNrSystemWarnings(
        pico_System system,
        pico_Int32 *outNrOfWarnings
        );

/**
   Returns in 'outMessage' a description of a warning that occurred
   with the most recently called system-level API function.
   'warningIndex' must be in the range 0..N-1 where N is the number of
   warnings returned by 'pico_getNrSystemWarnings'. 'outCode' returns
   the warning as an integer code (cf. PICO_WARN_*).
*/
PICO_FUNC pico_getSystemWarning(
        pico_System system,
        const pico_Int32 warningIndex,
        pico_Status *outCode,
        pico_Retstring outMessage
        );


/* Resource loading and unloading functions ***************************/

/**
   Loads a resource file into the Pico system. The number of resource
   files loaded in parallel is limited by PICO_MAX_NUM_RESOURCES.
   Loading of a resource file may be done at any time (even in
   parallel to a running engine doing TTS synthesis), but with the
   general restriction that functions taking a system handle as their
   first argument must be called in a mutually exclusive fashion. The
   loaded resource will be available only to engines started after the
   resource is fully loaded, i.e., not to engines currently
   running.
*/
PICO_FUNC pico_loadResource(
        pico_System system,
        const pico_Char *resourceFileName,
        pico_Resource *outResource
        );

/**
   Unloads a resource file from the Pico system. If no engine uses the
   resource file, the resource is removed immediately and its
   associated internal memory is released, otherwise
   PICO_EXC_RESOURCE_BUSY is returned.
*/
PICO_FUNC pico_unloadResource(
        pico_System system,
        pico_Resource *inoutResource
        );

/* *** Resource inspection functions *******************************/

/**
 Gets the unique resource name of a loaded resource
*/
PICO_FUNC pico_getResourceName(
        pico_System system,
        pico_Resource resource,
        pico_Retstring outName);


/* Voice definition ***************************************************/

/**
   Creates a voice definition. Resources must be added to the created
   voice with 'pico_addResourceToVoiceDefinition' before using the
   voice in 'pico_newEngine'. It is an error to create a voice
   definition with a previously defined voice name. In that case use
   'pico_releaseVoiceName' first.
*/
PICO_FUNC pico_createVoiceDefinition(
        pico_System system,
        const pico_Char *voiceName
        );

/**
   Adds a mapping pair ('voiceName', 'resourceName') to the voice
   definition. Multiple mapping pairs can added to a voice defintion.
   When calling 'pico_newEngine' with 'voiceName', the corresponding
   resources from the mappings will be used with that engine. */

PICO_FUNC pico_addResourceToVoiceDefinition(
        pico_System system,
        const pico_Char *voiceName,
        const pico_Char *resourceName
        );


/**
  Releases the voice definition 'voiceName'.

*/
PICO_FUNC pico_releaseVoiceDefinition(
        pico_System system,
        const pico_Char *voiceName
        );


/* Engine creation and deletion functions *****************************/

/**
   Creates and initializes a new Pico engine instance and returns its
   handle in 'outEngine'. Only one instance per system is currently
   possible.
*/
PICO_FUNC pico_newEngine(
        pico_System system,
        const pico_Char *voiceName,
        pico_Engine *outEngine
        );


/**
 Disposes a Pico engine and releases all memory it occupied. The
 engine handle becomes invalid.
*/
PICO_FUNC pico_disposeEngine(
        pico_System system,
        pico_Engine *inoutEngine
        );


/* ********************************************************************/
/* Engine-level API functions                                         */
/* ********************************************************************/

/**
   Puts text 'text' encoded in UTF8 into the Pico text input buffer.
   'textSize' is the maximum size in number of bytes accessible in
   'text'. The input text may also contain text-input commands to
   change, for example, speed or pitch of the resulting speech
   output. The number of bytes actually copied to the Pico text input
   buffer is returned in 'outBytesPut'. Sentence ends are
   automatically detected. '\0' characters may be embedded in 'text'
   to finish text input or separate independently to be synthesized
   text parts from each other. Repeatedly calling 'pico_getData' will
   result in the content of the text input buffer to be synthesized
   (up to the last sentence end or '\0' character detected). To empty
   the internal buffers without finishing synthesis, use the function
   'pico_resetEngine'.
*/
PICO_FUNC pico_putTextUtf8(
        pico_Engine engine,
        const pico_Char *text,
        const pico_Int16 textSize,
        pico_Int16 *outBytesPut
        );

/**
   Gets speech data from the engine. Every time this function is
   called, the engine performs, within a short time slot, a small
   amount of processing its input text, and then gives control back to
   the calling application. Ie. after calling 'pico_putTextUtf8'
   (incl. a final embedded '\0'), this function needs to be called
   repeatedly till 'outBytesReceived' bytes are returned in
   'outBuffer'. The type of data returned in 'outBuffer' (e.g. 8 or 16
   bit PCM samples) is returned in 'outDataType' and depends on the
   lingware resources. Possible 'outDataType' values are listed in
   picodefs.h (PICO_DATA_*).
   This function returns PICO_STEP_BUSY while processing input and
   producing speech output. Once all data is returned and there is no
   more input text available in the Pico text input buffer,
   PICO_STEP_IDLE is returned.  All other function return values
   indicate a system error.
*/
PICO_FUNC pico_getData(
        pico_Engine engine,
        void *outBuffer,
        const pico_Int16 bufferSize,
        pico_Int16 *outBytesReceived,
        pico_Int16 *outDataType
        );

/**
   Resets the engine and clears all engine-internal buffers, in
   particular text input and signal data output buffers.
   'resetMode' is one of 'PICO_RESET_SOFT', to be used to flush the engine,
   or 'PICO_RESET_FULL', to reset the engine after an engine error.
*/
PICO_FUNC pico_resetEngine(
        pico_Engine engine,
        pico_Int32 resetMode
);


/* Engine status and error/warning message retrieval ******************/

/**
   Returns in 'outMessage' a description of the engine status or of an
   error that occurred with the most recently called engine-level API
   function.
*/
PICO_FUNC pico_getEngineStatusMessage(
        pico_Engine engine,
        pico_Status errCode,
        pico_Retstring outMessage
        );

/**
   Returns in 'outNrOfWarnings' the number of warnings that occurred
   with the most recently called engine-level API function.
*/
PICO_FUNC pico_getNrEngineWarnings(
        pico_Engine engine,
        pico_Int32 *outNrOfWarnings
        );

/**
   Returns in 'outMessage' a description of a warning that occurred
   with the most recently called engine-level API function.
   'warningIndex' must be in the range 0..N-1 where N is the number of
   warnings returned by 'pico_getNrEngineWarnings'. 'outCode' returns
   the warning as an integer code (cf. PICO_WARN_*).
*/
PICO_FUNC pico_getEngineWarning(
        pico_Engine engine,
        const pico_Int32 warningIndex,
        pico_Status *outCode,
        pico_Retstring outMessage
        );

#ifdef __cplusplus
}
#endif

#endif /*PICOAPI_H_*/