xref: /external/srec/shared/include/ESR_SessionType.h

/*---------------------------------------------------------------------------*
 *  ESR_SessionType.h  *
 *                                                                           *
 *  Copyright 2007, 2008 Nuance Communciations, Inc.                               *
 *                                                                           *
 *  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.                                           *
 *                                                                           *
 *---------------------------------------------------------------------------*/

#ifndef __ESR_SESSIONTYPE_H
#define __ESR_SESSIONTYPE_H



#include "ESR_ReturnCode.h"
#include "ESR_SharedPrefix.h"
#include "ESR_VariableTypes.h"
#include "ESR_SessionTypeListener.h"
#include "pstdio.h"
#include "ptypes.h"

/**
 * @addtogroup ESR_SessionTypeModule ESR_SessionType API functions
 * ESR_Session interface functions.
 *
 * @{
 */

/**
 * Hashmap with helper functions for adding primitives and add-if-empty.
 */
typedef struct ESR_SessionType_t
{
  /**
   * Returns session property value.
   *
   * @param self ESR_SessionType handle
   * @param name Property name
   * @param value Property value
   * @param type Expected variable type (for strong-typing purposes)
   * @return ESR_INVALID_RESULT_TYPE if the property is not of the specified type
   */
  ESR_ReturnCode(*getProperty)(struct ESR_SessionType_t* self, const LCHAR* name, void** value, VariableTypes type);
  /**
   * Returns the type of a property value.
   *
   * @param self ESR_SessionType handle
   * @param name Property name
   * @param type [out] Value type
   * @return ESR_INVALID_ARGUMENT if self is null or property cannot be found
   */
  ESR_ReturnCode(*getPropertyType)(struct ESR_SessionType_t* self, const LCHAR* name, VariableTypes* type);
  /**
   * Returns copy of session property value.
   *
   * @param self ESR_SessionType handle
   * @param name Property name
   * @param value Property value
   * @return ESR_INVALID_RESULT_TYPE if the property is not a int
   */
  ESR_ReturnCode(*getInt)(struct ESR_SessionType_t* self, const LCHAR* name, int* value);
  /**
   * Returns copy of session property value.
   *
   * @param name Property name
   * @param value Property value
   * @return ESR_INVALID_RESULT_TYPE if the property is not a asr_uint16_t
   */
  ESR_ReturnCode(*getUint16_t)(struct ESR_SessionType_t* self, const LCHAR* name, asr_uint16_t* value);
  /**
   * Returns copy of session property value.
   *
   * @param self ESR_SessionType handle
   * @param name Property name
   * @param value Property value
   * @return ESR_INVALID_RESULT_TYPE if the property is not a size_t
   * @return ESR_INVALID_RESULT_TYPE if the property is not a size_t
   */
  ESR_ReturnCode(*getSize_t)(struct ESR_SessionType_t* self, const LCHAR* name, size_t* value);
  /**
   * Returns copy of session property value.
   *
   * @param self ESR_SessionType handle
   * @param name Property name
   * @param value Property value
   * @return ESR_INVALID_RESULT_TYPE if the property is not a float
   */
  ESR_ReturnCode(*getFloat)(struct ESR_SessionType_t* self, const LCHAR* name, float* value);
  /**
   * Returns copy of session property value.
   *
   * @param self ESR_SessionType handle
   * @param name Property name
   * @param value Property value
   * @return ESR_INVALID_RESULT_TYPE if the property is not a bool
   */
  ESR_ReturnCode(*getBool)(struct ESR_SessionType_t* self, const LCHAR* name, ESR_BOOL* value);
  /**
   * Returns copy of session property value.
   *
   * @param self ESR_SessionType handle
   * @param name Property name
   * @param value Property value
   * @param len Size of value argument. If the return code is ESR_BUFFER_OVERFLOW,
   *            the required length is returned in this variable.
   * @return ESR_INVALID_RESULT_TYPE if the property is not a LCHAR*
   */
  ESR_ReturnCode(*getLCHAR)(struct ESR_SessionType_t* self, const LCHAR* name, LCHAR* value, size_t* len);
  /**
   * Indicates if key exists in the session.
   *
   * @param self ESR_SessionType handle
   * @param name Property name
   * @param exists True if key exists, false otherwise
   * @return ESR_INVALID_ARGUMENT if self is null
   */
  ESR_ReturnCode(*contains)(struct ESR_SessionType_t* self, const LCHAR* name, ESR_BOOL* exists);
  /**
   * Sets session property value.
   *
   * @param self ESR_SessionType handle
   * @param name Property name
   * @param value Property value
   * @param type Type of value being set
   * @return ESR_INVALID_ARGUMENT if self is null; ESR_OUT_OF_MEMORY if system is out of memory
   */
  ESR_ReturnCode(*setProperty)(struct ESR_SessionType_t* self, const LCHAR* name, void* value, VariableTypes type);
  /**
   * Sets session property value, storing a copy of the value.
   *
   * @param self ESR_SessionType handle
   * @param name Property name
   * @param value Property value
   * @return ESR_INVALID_ARGUMENT if self is null; ESR_OUT_OF_MEMORY if system is out of memory
   */
  ESR_ReturnCode(*setInt)(struct ESR_SessionType_t* self, const LCHAR* name, int value);
  /**
   * Sets session property value, storing a copy of the value.
   *
   * @param name Property name
   * @param value Property value
   * @return ESR_INVALID_ARGUMENT if self is null; ESR_OUT_OF_MEMORY if system is out of memory
   */
  ESR_ReturnCode(*setUint16_t)(struct ESR_SessionType_t* self, const LCHAR* name, asr_uint16_t value);
  /**
   * Sets session property value, storing a copy of the value.
   *
   * @param self ESR_SessionType handle
   * @param name Property name
   * @param value Property value
   * @return ESR_INVALID_ARGUMENT if self is null; ESR_OUT_OF_MEMORY if system is out of memory
   */
  ESR_ReturnCode(*setSize_t)(struct ESR_SessionType_t* self, const LCHAR* name, size_t value);
  /**
   * Sets session property value, storing a copy of the value.
   *
   * @param self ESR_SessionType handle
   * @param name Property name
   * @param value Property value
   * @return ESR_INVALID_ARGUMENT if self is null; ESR_OUT_OF_MEMORY if system is out of memory
   */
  ESR_ReturnCode(*setFloat)(struct ESR_SessionType_t* self, const LCHAR* name, float value);
  /**
   * Sets session property value, storing a copy of the value.
   *
   * @param self ESR_SessionType handle
   * @param name Property name
   * @param value Property value
   * @return ESR_INVALID_ARGUMENT if self is null; ESR_OUT_OF_MEMORY if system is out of memory
   */
  ESR_ReturnCode(*setBool)(struct ESR_SessionType_t* self, const LCHAR* name, ESR_BOOL value);
  /**
   * Sets session property value, storing a copy of the value.
   *
   * @param self ESR_SessionType handle
   * @param name Property name
   * @param value Property value
   * @return ESR_INVALID_ARGUMENT if self is null; ESR_OUT_OF_MEMORY if system is out of memory
   */
  ESR_ReturnCode(*setLCHAR)(struct ESR_SessionType_t* self, const LCHAR* name, LCHAR* value);
  /**
   * If the key does not exist in the session, calls SessionSetInt().
   *
   * This helper function aids implementation of "default values", overwriting
   * session values only if they have not been set already.
   *
   * @param self ESR_SessionType handle
   * @param name Property name
   * @param value Property value
   * @return ESR_INVALID_ARGUMENT if self is null; ESR_OUT_OF_MEMORY if system is out of memory
   */
  ESR_ReturnCode(*setIntIfEmpty)(struct ESR_SessionType_t* self, const LCHAR* name, int value);
  /**
   * If the key does not exist in the session, calls SessionSetUint16_t().
   *
   * This helper function aids implementation of "default values", overwriting
   * session values only if they have not been set already.
   *
   * @param name Property name
   * @param value Property value
   * @return ESR_INVALID_ARGUMENT if self is null; ESR_OUT_OF_MEMORY if system is out of memory
   */
  ESR_ReturnCode(*setUint16_tIfEmpty)(struct ESR_SessionType_t* self, const LCHAR* name, asr_uint16_t value);
  /**
   * If the key does not exist in the session, calls SessionSetSize_t().
   *
   * This helper function aids implementation of "default values", overwriting
   * session values only if they have not been set already.
   *
   * @param self ESR_SessionType handle
   * @param name Property name
   * @param value Property value
   * @return ESR_INVALID_ARGUMENT if self is null; ESR_OUT_OF_MEMORY if system is out of memory
   */
  ESR_ReturnCode(*setSize_tIfEmpty)(struct ESR_SessionType_t* self, const LCHAR* name, size_t value);
  /**
   * If the key does not exist in the session, calls SessionSetFloat().
   *
   * This helper function aids implementation of "default values", overwriting
   * session values only if they have not been set already.
   *
   * @param self ESR_SessionType handle
   * @param name Property name
   * @param value Property value
   * @return ESR_INVALID_ARGUMENT if self is null; ESR_OUT_OF_MEMORY if system is out of memory
   */
  ESR_ReturnCode(*setFloatIfEmpty)(struct ESR_SessionType_t* self, const LCHAR* name, float value);
  /**
   * If the key does not exist in the session, calls SessionSetBool().
   *
   * This helper function aids implementation of "default values", overwriting
   * session values only if they have not been set already.
   *
   * @param self ESR_SessionType handle
   * @param name Property name
   * @param value Property value
   * @return ESR_INVALID_ARGUMENT if self is null; ESR_OUT_OF_MEMORY if system is out of memory
   */
  ESR_ReturnCode(*setBoolIfEmpty)(struct ESR_SessionType_t* self, const LCHAR* name, ESR_BOOL value);
  /**
   * If the key does not exist in the session, calls SessionSetLCHAR().
   *
   * This helper function aids implementation of "default values", overwriting
   * session values only if they have not been set already.
   *
   * @param self ESR_SessionType handle
   * @param name Property name
   * @param value Property value
   * @return ESR_INVALID_ARGUMENT if self is null; ESR_OUT_OF_MEMORY if system is out of memory
   */
  ESR_ReturnCode(*setLCHARIfEmpty)(struct ESR_SessionType_t* self, const LCHAR* name, LCHAR* value);
  /**
   * Removes property from session.
   *
   * @param self ESR_SessionType handle
   * @param name Property name
   * @return ESR_INVALID_ARGUMENT if self is null; ESR_NO_MATCH_ERROR if key cannot be found
   */
  ESR_ReturnCode(*removeProperty)(struct ESR_SessionType_t* self, const LCHAR* name);
  /**
   * Removes and deallocates property from session.
   *
   * @param self ESR_SessionType handle
   * @param name Property name
   * @return ESR_INVALID_ARGUMENT if self is null; ESR_NO_MATCH_ERROR if key cannot be found
   */
  ESR_ReturnCode(*removeAndFreeProperty)(struct ESR_SessionType_t* self, const LCHAR* name);
  /**
   * Imports commandline arguments into the system session.
   *
   * Keys are imported as "cmdline.[name]" where [name] is the name of the command-line argument
   * Values are set in char* format.
   *
   * For example, given the argument "-timer=5", the following key will be added to the session:
   * ["cmdline.timer", "5"]
   *
   * Validation is left up to the application.
   *
   * If the session contains a key that is clobbered by the parser, the old [key, value]
   * pair will be deallocated. For example, if the session contained
   * ["cmdline.timer", "value"] before the aforementioned example occured, then the old
   * [key, value] pair will be allocated by the parser.
   *
   * @param self ESR_SessionType handle
   * @param argc Number of arguments
   * @param argv Argument values
   * @return ESR_INVALID_ARGUMENT if self is null; ESR_OUT_OF_MEMORY if the system is out of memory;
   */
  ESR_ReturnCode(*importCommandLine)(struct ESR_SessionType_t* self, int argc, char* argv[]);
  /**
   * Returns the number of elements in the session.
   *
   * @param self ESR_SessionType handle
   * @param size [out] Session size
   * @return ESR_INVALID_ARGUMENT if self is null
   */
  ESR_ReturnCode(*getSize)(struct ESR_SessionType_t* self, size_t* size);
  /**
   * Returns the key associated with the specified index.
   *
   * @param self ESR_SessionType handle
   * @param index Element index
   * @param key [out] Key name
   * @return ESR_INVALID_ARGUMENT if self is null; ESR_ARGUMENT_OUT_OF_BOUNDS if index is out of bounds
   */
  ESR_ReturnCode(*getKeyAtIndex)(struct ESR_SessionType_t* self, size_t index, LCHAR** key);
  /**
   * Convert the specified argument to int.
   *
   * @param self ESR_SessionType handle
   * @param key Property name
   * @return ESR_INVALID_RESULT_TYPE if the property is not a LCHAR*; ESR_OUT_OF_MEMORY if system is out of memory;
   * ESR_INVALID_ARGUMENT if self is null or property cannot be converted to int
   */
  ESR_ReturnCode(*convertToInt)(struct ESR_SessionType_t* self, const LCHAR* key);

  /**
   * Convert the specified argument to asr_uint16_t.
   *
   * @param self ESR_SessionType handle
   * @param key Property name
  * @return ESR_INVALID_RESULT_TYPE if the property is not a LCHAR*; ESR_OUT_OF_MEMORY if system is out of memory;
  * ESR_INVALID_ARGUMENT if self is null or property cannot be converted to asr_uint16_t
   */
  ESR_ReturnCode(*convertToUint16_t)(struct ESR_SessionType_t* self, const LCHAR* key);

  /**
   * Convert the specified argument to size_t.
   *
   * @param self ESR_SessionType handle
   * @param key Property name
  * @return ESR_INVALID_RESULT_TYPE if the property is not a LCHAR*; ESR_OUT_OF_MEMORY if system is out of memory;
  * ESR_INVALID_ARGUMENT if self is null or property cannot be converted to size_t
   */
  ESR_ReturnCode(*convertToSize_t)(struct ESR_SessionType_t* self, const LCHAR* key);

  /**
   * Convert the specified argument to float.
   *
   * @param self ESR_SessionType handle
   * @param key Property name
  * @return ESR_INVALID_RESULT_TYPE if the property is not a LCHAR*; ESR_OUT_OF_MEMORY if system is out of memory;
  * ESR_INVALID_ARGUMENT if self is null or property cannot be converted to float
   */
  ESR_ReturnCode(*convertToFloat)(struct ESR_SessionType_t* self, const LCHAR* key);

  /**
   * Convert the specified argument to bool.
   *
   * @param self ESR_SessionType handle
   * @param key Property name
   * @return ESR_INVALID_RESULT_TYPE if the property is not a LCHAR*; ESR_OUT_OF_MEMORY if system is out of memory;
   * ESR_INVALID_ARGUMENT if self is null or property cannot be converted to bool
   */
  ESR_ReturnCode(*convertToBool)(struct ESR_SessionType_t* self, const LCHAR* key);
  /**
   * Destroys the Session.
   *
   * @param self ESR_SessionType handle
   * @return ESR_INVALID_ARGUMENT if self is null
   */
  ESR_ReturnCode(*destroy)(struct ESR_SessionType_t* self);
  /**
   * Import PAR file into session.
   *
   * @param self ESR_SessionType handle
   * @param file File to read session from
   * @return ESR_INVALID_STATE if self is null; ESR_OPEN_ERROR if file cannot be opened; ESR_READ_ERROR if file cannot be
  * read; ESR_OUT_OF_MEMORY if system is out of memory
   */
  ESR_ReturnCode(*importParFile)(struct ESR_SessionType_t* self, const LCHAR* filename);
  /**
   * Import ARG file into session.
   *
   * @param self ESR_SessionType handle
   * @param file File to read arguments from
   */
  ESR_ReturnCode(*importArgFile)(struct ESR_SessionType_t* self, const LCHAR* filename);

  /**
   * Adds an event-listener.
   *
   * @param self ESR_SessionType handle
   * @param listener The event-listener to add
    * @return ESR_INVALID_ARGUMENT if self is null; ESR_OUT_OF_MEMORY if system is out of memory
   */
  ESR_ReturnCode(*addListener)(struct ESR_SessionType_t* self, ESR_SessionTypeListenerPair* listener);

  /**
   * Removes an event-listener.
   *
   * @param self ESR_SessionType handle
   * @param listener The event-listener to remove
    * @return ESR_INVALID_ARGUMENT if self is null; ESR_OUT_OF_MEMORY if system is out of memory
   */
  ESR_ReturnCode(*removeListener)(struct ESR_SessionType_t* self, ESR_SessionTypeListenerPair* listener);

  /**
   * Pointer to session data.
   */
  void* data;
}
ESR_SessionType;

/**
 * Initializes the system session.
 *
 * @param self ESR_SessionType handle
 * @return ESR_OUT_OF_MEMORY if system is out of memory
 */
ESR_SHARED_API ESR_ReturnCode ESR_SessionTypeCreate(ESR_SessionType** self);
/**
 * @}
 */


#endif /* __ESR_SESSIONTYPE_H */