/**
  @file src/component_loader.h
  
  OpenMAX Component loader APIs. This header file specifies the entry point
  that a component loader must provide.
    
  Copyright (C) 2007-2008 STMicroelectronics
  Copyright (C) 2007-2008 Nokia Corporation and/or its subsidiary(-ies).

  This library is free software; you can redistribute it and/or modify it under
  the terms of the GNU Lesser General Public License as published by the Free
  Software Foundation; either version 2.1 of the License, or (at your option)
  any later version.

  This library is distributed in the hope that it will be useful, but WITHOUT
  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
  FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License for more
  details.

  You should have received a copy of the GNU Lesser General Public License
  along with this library; if not, write to the Free Software Foundation, Inc.,
  51 Franklin St, Fifth Floor, Boston, MA
  02110-1301  USA
  
  $Date: 2008-06-27 12:00:23 +0200 (Fri, 27 Jun 2008) $
  Revision $Rev: 554 $
  Author $Author: pankaj_sen $
*/

#ifndef __COMPONENT_LOADER_H__
#define __COMPONENT_LOADER_H__

#include "omxcore.h"

/** @brief Component loader entry points  
 * 
 * The component loader generic structure contains the entry points for 
 * each component loader. The list of component loaders is filled using 
 * a special function, called AddComponentLoader.
 */
typedef struct BOSA_COMPONENTLOADER
{
  /** @brief The constructor of the component loader 
   * 
   * The component loader creator is called by the OMX_Init function. It is 
   * implemented by the specific component loader. It must allocate any 
   * resource needed by the component loader.
   * 
   * @param loader A private data structure, if needed by the component loader. 
   * This data structure is passed every time a function of this loader is called.
   * @return OMX_ErrorInsufficientResources if the component loader can not be constructed
   */
  OMX_ERRORTYPE (*BOSA_InitComponentLoader)(struct BOSA_COMPONENTLOADER *loader);
  
  /** @brief The destructor of the component loader  
   * 
   * The component loader destructor is called by the OMX_Deinit function. It is 
   * implemented by the specific component loader. It must free every specific 
   * resource used by the component loader.
   * 
   * @param loader the specific component loader. This parameter is also specific
   * to the component loader, and its structure is defined by each loader.
   * @return OMX_ErrorNone
   */
  OMX_ERRORTYPE (*BOSA_DeInitComponentLoader)(struct BOSA_COMPONENTLOADER *loader);
  
  /** @brief The component costructor of the current component loader
   *  
   * This function implements the OMX_GetHandle function for the 
   * specific component loader. Its interface is the same as the 
   * standard GetHandle function, except that the first parameter
   * that contains the private data of the specific component loader.
   * 
   * @param loader Private data of the component loader
   * @param pHandle the openmax handle returned by the function, or NULL 
   * in case of failure.
   * @param cComponentName A string that contains the standard 
   * component's name
   * @param pAppData private data of the component (if needed)
   * @param pCallBacks IL client callback function pointers passed
   * to the component
   * 
   * @return OMX_ErrorNone if the component is correctly constructed and returned
   * @return OMX_ErrorComponentNotFound if the component is not found
   * @return OMX_ErrorInsufficientResources if the component exists but can not be allocated.
   */ 
  OMX_ERRORTYPE (*BOSA_CreateComponent)(
    struct BOSA_COMPONENTLOADER *loader,
    OMX_HANDLETYPE* pHandle,
    OMX_STRING cComponentName,
    OMX_PTR pAppData,
    OMX_CALLBACKTYPE* pCallBacks);

  /** @brief The component destructor of the current component loader
   *  
   * This function implements the OMX_FreeHandle function for the 
   * specific component loader. Its interface is the same as the 
   * standard FreeHandle function, except that the first parameter
   * that contains the private data of the specific component loader.
   * 
   * @param loader Private data of the component loader
   * @param pHandle the openmax handle returned by the function, or NULL 
   * in case of failure.
   * @param cComponentName A string that contains the standard 
   * component's name
   * @param pAppData private data of the component (if needed)
   * @param pCallBacks IL client callback function pointers passed
   * to the component
   * 
   * @return OMX_ErrorNone if the component is correctly constructed and returned
   * @return OMX_ErrorComponentNotFound if the component is not found
   * @return OMX_ErrorInsufficientResources if the component exists but can not be allocated.
   */ 
  OMX_ERRORTYPE (*BOSA_DestroyComponent)(
      struct BOSA_COMPONENTLOADER *loader, 
      OMX_HANDLETYPE hComponent);
  
  /** @brief An enumerator of the components handled by the current component loader.
   * 
   * This function implements the OMX_ComponentNameEnum function 
   * for the specific component loader
   * 
   * @param loader Private data of the component loader
   * @param cComponentName A pointer to a null terminated string 
   * with the component name.  The names of the components are 
   * strings less than 127 bytes in length plus the trailing null 
   * for a maximum size of 128 bytes (OMX_MAX_STRINGNAME_SIZE).
   * @param nNameLength The number of characters in the 
   * cComponentName string.  With all component name strings 
   * restricted to less than 128 characters (including the trailing null) 
   * it is recomended that the caller provide a input string for the 
   * cComponentName of 128 characters.
   * @param nIndex A number containing the enumeration index 
   * for the component. Multiple calls to OMX_ComponentNameEnum 
   * with increasing values of nIndex will enumerate through the 
   * component names in the system until OMX_ErrorNoMore is returned.  
   * The value of nIndex is 0 to (N-1), where N is the number of 
   * valid installed components in the system.
   * 
   * @return OMX_ErrorNone If the command successfully executes 
   * @return OMX_ErrorNoMore If the value of nIndex exceeds the 
   * number of components handled by the component loader minus 1 
   */ 
  OMX_ERRORTYPE (*BOSA_ComponentNameEnum)(
    struct BOSA_COMPONENTLOADER *loader,
    OMX_STRING cComponentName,
    OMX_U32 nNameLength,
    OMX_U32 nIndex);

  /** @brief This function implements the OMX_GetRolesOfComponent standard function for the current component loader
   * 
   * This function will return the number of roles supported by 
   * the given component and (if the roles field is non-NULL) 
   * the names of those roles. The call will fail if an insufficiently 
   * sized array of names is supplied.
   * To ensure the array is sufficiently sized the client should:
   * - first call this function with the roles field NULL to 
   *   determine the number of role names
   * - second call this function with the roles field pointing to 
   *   an array of names allocated according to the number 
   *   returned by the first call.
   * 
   * @param loader Private data of the component loader
   * @param compName The name of the component being queried about.
   * @param pNumRoles This parameter is used both as input and output.
   * If roles is NULL, the input is ignored and the output specifies
   * how many roles the component supports. If compNames is not NULL,
   * on input it bounds the size of the input structure and on output,
   * it specifies the number of roles string names listed within 
   * the roles parameter.
   * @param roles If NULL this field is ignored. If non-NULL this points 
   * to an array of 128-byte strings which accepts a list of the names of
   * all standard components roles implemented on the specified 
   * component name. numComps indicates the number of names.
   */
  OMX_ERRORTYPE (*BOSA_GetRolesOfComponent)( 
    struct BOSA_COMPONENTLOADER *loader,
    OMX_STRING compName,
    OMX_U32 *pNumRoles,
    OMX_U8 **roles);

  /** @brief This function implements the OMX_GetComponentsOfRole
   * standard function for the current component loader
   * 
   * This function will return the number of components that support
   * the given role and (if the compNames field is non-NULL) the names
   * of those components. The call will fail if an insufficiently
   * sized array of names is supplied. To ensure the array is
   * sufficiently sized the client should:
   * - first call this function with the compNames field NULL to
   *   determine the number of component names
   * - second call this function with the compNames field pointing
   *   to an array of names allocated according to the number
   *   returned by the first call.
   *
   * @param loader Private data of the component loader
   * @param role This is generic standard component name consisting 
   * only of component class name and the type within that class 
   * (e.g. 'audio_decoder.aac').
   * @param pNumComps This is used both as input and output. If compNames 
   * is NULL, the input is ignored and the output specifies how many 
   * components support the given role. If compNames is not NULL,
   * on input it bounds the size of the input structure and on output,
   * it specifies the number of components string names listed within 
   * the compNames parameter.
   * @param compNames If NULL this field is ignored. If non-NULL this points
   * to an array of 128-byte strings which accepts a list of the names of
   * all physical components that implement the specified standard component 
   * name. Each name is NULL terminated. numComps indicates the number of names.
   */
  OMX_ERRORTYPE (*BOSA_GetComponentsOfRole) ( 
    struct BOSA_COMPONENTLOADER *loader,
    OMX_STRING role,
    OMX_U32 *pNumComps,
    OMX_U8  **compNames);
  
  /** @brief The reference to the current component loader private data
   * 
   * The current loader specified by this structure is described with this
   * generic pointer that contains the private data of the loader.
   */
  void *loaderPrivate;
  
} BOSA_COMPONENTLOADER;

#endif
