/*
 * Copyright 2010 Trident Microsystems (Far East) Ltd. All rights reserved.
 * All prior copyright rights in this work and the accompanying software
 * products transferred to Trident Microsystems (Far East) Ltd. by written
 * agreement.
 */
/*****************************************************************************/
/* Copyright (c) 2010 NXP B.V.  All rights are reserved.                     */
/*                                                                           */
/* Redistribution and use in source and binary forms, with or without        */
/* modification, are permitted provided that the following conditions        */
/* are met:                                                                  */
/*                                                                           */
/* Redistributions of source code must retain the above copyright            */
/* notice, this list of conditions and the following disclaimer.             */
/*                                                                           */
/* Redistributions in binary form must reproduce the above copyright         */
/* notice, this list of conditions and the following disclaimer in the       */
/* documentation and/or other materials provided with the distribution.      */
/*                                                                           */
/* Neither the name of NXP nor the names of its                              */
/* contributors may be used to endorse or promote products derived from      */
/* this software without specific prior written permission.                  */
/*                                                                           */
/* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS       */
/* "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT         */
/* LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR     */
/* A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT      */
/* OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,     */
/* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT          */
/* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,     */
/* DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY     */
/* THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT       */
/* (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE         */
/* USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH          */
/* DAMAGE.                                                                   */
/*                                                                           */
/*****************************************************************************/
/**
    @file   phStbStreamingSystem_Server.h
    @brief  Interface for control of Streaming System.

@b  Component:  phStbStreamingSystem_Server.

    This header file is a partial implementation of the StreamingSystemServer
    interface from the Streaming System detailed design. It contains functions
    for use by the platform software to control stream graphs and connections.
    Classes that implement this interface are singletons (they have only one
    instance)
*//*

Rev Date        Author      Comments
--------------------------------------------------------------------------------
  1 20050527    J Grant     Skeleton
  2 20050627    burningh    Correcting prototype of _AddResource
  3 20050629    burningh    Using phStbCommon to allow build on Linux & TM
  4 20060124    batelaan    Add extern "C" for use with C++
  5 20060602    G.Lawrance  Port to STB225
  6 20071217    burningh    Improve documentation of top-level APIs
  7 20080626    burningh    Update license text
  8 20090120    batelaan    Update file copyright/license text
--------------------------------------------------------------------------------
    For consistency and standardisation retain the Section Separators.
*/

#ifndef PHSTBSTREAMINGSYSTEM_SERVER_H
#define PHSTBSTREAMINGSYSTEM_SERVER_H

/*******************
* INCLUDE FILES    *
********************/

#include <tmNxTypes.h>

#include "phStbStreamingSystem_IDTypes.h"


#ifdef __cplusplus
extern "C"
{
#endif

/**************************************************************************
* EXPORTED MACROS    PH[<LNX|TM|NONE>]_STBSTREAMINGSYSTEM_SERVER_<_WORD>+ *
***************************************************************************/

/******************************************************************************
* EXPORTED TYPEDEFS  [p]ph[<lnx|tm|NONE>]StbStreamingSystem_Server_<Word>+_t  *
*******************************************************************************/

/**************************************************************************
* EXPORTED DATA   g[k|p|kp|pk|kpk]ph[<lnx|tm|NONE>]StbStreamingSystem_Server_<Word>+ *
***************************************************************************/

/****************************************************************************
* EXPORTED FUNCTION PROTOTYPES     ph[<lnx|tm|NONE>]StbStreamingSystem_Server[_<Word>+]   *
*****************************************************************************/

/* Class Operations */

/******************************************************************************/
/** Create the single instance, preparing the class for use (enter Active state)
    Constraints:
        Must be in Idle state

    @retval TM_OK           Success
    @retval AnotherValue    Error occured.

    @todo   Error codes
*/
tmErrorCode_t phStbStreamingSystem_Server_Initialise(void);


/******************************************************************************/
/** Destroy the single instance (enter Idle state).
    Constraints:
        Must be in Active state

    @retval TM_OK           Success
    @retval AnotherValue    Error occured.

    @todo   Error codes
*/
tmErrorCode_t phStbStreamingSystem_Server_Deinitialise(void);



/* Instance Operations */
/******************************************************************************/
/** Allocate the specified resource for use in the specified stream graph
    Constraints:
        Graph with the specified ID must exist
        Resource must not be already allocated to a different stream graph

    @param graphID      IN  Identifier of stream graph to which resource must be
                            added
    @param pName        IN  Unique textual name of resource to be added
    @param pResourceID  OUT Identifier of the added resource, unique within the
                            specified stream graph


    @retval TM_OK           Success
    @retval AnotherValue    Error occured.
*/
tmErrorCode_t phStbStreamingSystem_Server_AddResource
   (phStbStreamingSystem_GraphID_t     graphID,
    const char*                        pName,
    phStbStreamingSystem_ResourceID_t* pResourceID);


/******************************************************************************/
/** Deallocate the specified resource from the specified stream graph
    Constraints:
        Must be in Active state
        Objects with the specified IDs must exist
        Resource must be disconnected from all other resources with no pending
        connect or disconnect operations

    @param graphID      IN  Identifier of stream graph from which resource must
                            be removed
    @param resourceID   IN  Identifier of the resource to remove, unique within
                            the specified stream graph

    @retval TM_OK           Success
    @retval AnotherValue    Error occured.
*/
tmErrorCode_t phStbStreamingSystem_Server_RemoveResource
   (phStbStreamingSystem_GraphID_t    graphID,
    phStbStreamingSystem_ResourceID_t resourceID);


/******************************************************************************/
/** Record that a connection should be made between the specified source and
    sink pins in the next commit() operation
    Constraints:
        Must be in Active state
        Objects with the specified IDs must exist
        Pins must be compatible

    @param graphID          IN  Identifier of stream graph which owns the
                                specified resources
    @param sourceResourceID IN  Identifier of the resource owning the source
                                pin, unique within the specified stream graph
    @param sourcePinID      IN  Identifier of the source pin, unique within the
                                source resource
    @param sinkResourceID   IN  Identifier of the resource owning the sink pin,
                                unique within the specified stream graph
    @param sinkPinID        IN  Identifier of the sink pin, unique within the
                                sink resource
    @param pConnectionID    OUT Identifier of the new (pending) connection,
                                unique within the specified stream graph


    @retval TM_OK           Success
    @retval AnotherValue    Error occured.
*/
tmErrorCode_t phStbStreamingSystem_Server_Connect
   (phStbStreamingSystem_GraphID_t          graphID,
    phStbStreamingSystem_ResourceID_t       sourceResourceID,
    phStbStreamingSystem_SourcePinID_t      sourcePinID,
    phStbStreamingSystem_ResourceID_t       sinkResourceID,
    phStbStreamingSystem_SinkPinID_t        sinkPinID,
    phStbStreamingSystem_ConnectionID_t*    pConnectionID);


/******************************************************************************/
/** Record that the specified connection should be broken in the next commit()
    operation
    Constraints:
        Must be in Active state
        Objects with the specified IDs must exist

    @param graphID      IN  Identifier of stream graph which owns the specified
                            connection
    @param connectionID IN  Identifier of the connection to break, unique within
                            the specified stream graph

    @retval TM_OK           Success
    @retval AnotherValue    Error occured.
*/
tmErrorCode_t phStbStreamingSystem_Server_Disconnect
   (phStbStreamingSystem_GraphID_t      graphID,
    phStbStreamingSystem_ConnectionID_t connectionID);


/******************************************************************************/
/** Break all connections specified in previous disconnect() operations
    Make all connections specified in previous connect() operations
    Constraints:
        Must be in Active state
        Graph with the specified ID must exist

    @param graphID  IN  Identifier of stream graph

    @retval TM_OK           Success
    @retval AnotherValue    Error occured.
*/
tmErrorCode_t phStbStreamingSystem_Server_Commit
   (phStbStreamingSystem_GraphID_t graphID);


/******************************************************************************/
/** Start streaming of data through the entire stream graph
    Constraints:
        Must be in Active state
        Graph with the specified ID must exist

    @param graphID  IN  Identifier of stream graph

    @retval TM_OK           Success
    @retval AnotherValue    Error occured.
*/
tmErrorCode_t phStbStreamingSystem_Server_Start
   (phStbStreamingSystem_GraphID_t graphID);


/******************************************************************************/
/** Stop streaming of data through the entire stream graph
    Constraints:
        Must be in Active state
        Graph with the specified ID must exist

    @param graphID  IN  Identifier of stream graph

    @retval TM_OK           Success
    @retval AnotherValue    Error occured.
*/
tmErrorCode_t phStbStreamingSystem_Server_Stop
   (phStbStreamingSystem_GraphID_t graphID);


/******************************************************************************/
/** Create a new stream graph
    Constraints:
        Must be in Active state

    @param pGraphID OUT Identifier of newly created stream graph

    @retval TM_OK           Success
    @retval AnotherValue    Error occured.
*/
tmErrorCode_t phStbStreamingSystem_Server_CreateStreamGraph
   (phStbStreamingSystem_GraphID_t* pGraphID);


/******************************************************************************/
/** Destroy the specified stream graph
    Constraints:
        Must be in Active state
        Graph with the specified ID must exist

    @param graphID  IN  Identifier of stream graph to destroy

    @retval TM_OK           Success
    @retval AnotherValue    Error occured.
*/
tmErrorCode_t phStbStreamingSystem_Server_DestroyStreamGraph
   (phStbStreamingSystem_GraphID_t graphID);


/******************************************************************************/
/** Dump debugging information for the specified stream graph and its
    contained resources
    Constraints:
        Graph with the specified ID must exist

    @param graphID  IN  Identifier of stream graph to dump

    @retval TM_OK           Success
    @retval AnotherValue    Error occured.
*/
tmErrorCode_t phStbStreamingSystem_Server_DumpStreamGraph
   (phStbStreamingSystem_GraphID_t graphID);


/******************************************************************************/
/** Dump debugging information for the specified resource
    Constraints:
        Resource with the specified name must exist

    @param pResourceName IN  Name of resource to dump

    @retval TM_OK           Success
    @retval AnotherValue    Error occured.
*/
tmErrorCode_t phStbStreamingSystem_Server_DumpResource
   (const char* pResourceName);


/******************************************************************************/
/******************************************************************************/
/******************************************************************************/
/******************************************************************************/

#ifdef __cplusplus
}
#endif

#endif /* PHSTBSTREAMINGSYSTEM_SERVER_H  Do not add any thing below this line */
